gh-optivem

README

gh-optivem

A GitHub CLI extension for scaffolding pipeline projects.

Prerequisites

• GitHub CLI (gh auth login)
• actionlint v1.7.7 — used by the Verify scaffolded workflows step. Install: go install github.com/rhysd/actionlint/cmd/actionlint@v1.7.7 or bash <(curl -fsSL https://raw.githubusercontent.com/rhysd/actionlint/v1.7.7/scripts/download-actionlint.bash) 1.7.7

Installation

gh extension install optivem/gh-optivem

Uninstalling

gh extension remove optivem

Version

gh optivem --version

Upgrading

gh optivem upgrade

Equivalent to gh extension upgrade optivem — either form works.

Usage

Scaffold a monolith project

gh optivem init --owner acme --system-name "Page Turner" --repo page-turner \
    --arch monolith --repo-strategy monorepo --monolith-lang java

The repo name can also be passed positionally — gh optivem init page-turner --owner acme ... — in which case --repo is optional.

Scaffold a multitier project

gh optivem init --owner acme --system-name "Page Turner" --repo page-turner \
    --arch multitier --repo-strategy multirepo \
    --backend-lang java --frontend-lang react

Other init flags

gh optivem init ... --license apache-2.0          # mit (default), apache-2.0, gpl-3.0, bsd-2-clause, bsd-3-clause, unlicense
gh optivem init ... --test-lang typescript         # override; defaults to --monolith-lang or --backend-lang
gh optivem init ... --workdir ./scratch            # custom clone dir; defaults to a temp dir
gh optivem init ... --shop-ref meta-v1.2.3         # pin optivem/shop to a tag, SHA, or branch
gh optivem init ... --no-atdd                      # skip installing ATDD agents/commands/prompts from shop

Dry run

gh optivem init ... --dry-run

Verification level

Control how deep pipeline verification goes after scaffolding:

gh optivem init ... --verify-level none          # skip all verification
gh optivem init ... --verify-level local         # local compilation + local tests + local SonarCloud scan (no CI)
gh optivem init ... --verify-level commit        # + commit stage CI
gh optivem init ... --verify-level acceptance    # + acceptance stage CI (latest + legacy in parallel)
gh optivem init ... --verify-level qa            # + QA stage + QA signoff
gh optivem init ... --verify-level release       # + production stage (default)
gh optivem init ... --no-legacy                  # skip legacy in local tests and acceptance
gh optivem init ... --no-local-tests             # skip the local system-tests step
gh optivem init ... --no-local-sonar             # skip the local SonarCloud scan step

Local cleanup

On a successful run the local scaffold dir is deleted — the end result is just the created GitHub repo(s) + SonarCloud project(s), which you can clone later. Pass --keep-local to keep the dir (e.g. for inspection). On failure the dir is always kept so the broken scaffold can be debugged.

Unattended runs (CI)

Pass --yes (or -y) to skip all interactive confirmations — the existing-repo prompt and the --report-bug confirmation. This is the expected pattern for CI/automation:

gh optivem init ... --yes

Logging flags

Available on init:

gh optivem init ... --verbose          # -v; debug output (retry/wait chatter, diagnostics)
gh optivem init ... --quiet            # -q; suppress info-level output (warnings + errors still shown)
gh optivem init ... --log-file run.log # also write a plain-text log (no ANSI colors, all levels)

Deployment target

Only --deploy docker is currently supported (the default). --deploy cloud-run is in development and may be available in a future release.

Running tests against a scaffolded project

gh optivem also provides runner subcommands for working with the system tests in a scaffolded project. Inspired by dotnet test and ./gradlew test, test system builds and starts the system implicitly — you don't need to run build or run first.

gh optivem test system                       # build (incremental) + start (if needed) + run tests
gh optivem test system --no-build            # skip the explicit build step
gh optivem test system --rebuild             # force full rebuild in the implicit build step (ignored with --no-build)
gh optivem test system --no-start            # skip the start step (system must already be up)
gh optivem test system --restart             # force tear-down + restart before tests
gh optivem test system --suite smoke         # run only the suite with this id
gh optivem test system --test "MyTest"       # narrow execution to one test name (substituted into the suite's testFilter)
gh optivem test system --sample              # use each suite's sampleTest field as the test name

gh optivem build system                      # docker compose build for every entry in system.json
gh optivem build system --rebuild            # force full rebuild (no layer cache reuse)

gh optivem run system                        # docker compose up + wait for health
gh optivem run system --restart              # force tear-down + restart
gh optivem run system --log-lines 200        # lines of compose logs to dump on health-probe failure (default 50)

gh optivem stop system                       # docker compose down + container cleanup
gh optivem clean system                      # docker compose down -v --rmi local (delete volumes + locally-built images)

All runner subcommands also accept --system <path> (default ./system.json) and the test subcommand accepts --tests <path> (default ./tests.json) for projects where the config files live elsewhere.

clean system is the analog of dotnet clean / ./gradlew clean — it deletes build outputs (containers, named volumes, locally-built images) without touching the dependency cache (registry-pulled images are kept). Chain it explicitly for a fresh start: gh optivem clean system && gh optivem test system.

Troubleshooting

Auto-filed bug report (opt-in)

If you want the failure auto-filed to optivem/gh-optivem as an issue — including scaffold config — opt in with --report-bug:

gh optivem init ... --report-bug

Off by default. Filing a quick issue yourself is usually clearer and keeps the scaffold config private unless you decide to share it.

How it works

See docs/how-it-works.md for a detailed walkthrough of the main.go logic, setup steps, and verification levels.

For the ATDD pipeline orchestration view, see the rendered process-flow diagram. It is regenerated automatically whenever the canonical YAML at internal/atdd/runtime/statemachine/process-flow.yaml changes; do not edit the diagram by hand.

Contributing

See CONTRIBUTING.md for development setup, testing, and release instructions.

Documentation

Overview

atdd_commands.go wires the `gh optivem atdd …` subcommands into the root Cobra command. Two public commands mirror today's slash commands:

gh optivem atdd implement-ticket --issue N
gh optivem atdd manage-project

A hidden `debug` parent groups the diagnostic helpers — pick-top-ready, classify, next-phase, gate, release — so each underlying runtime package can be exercised standalone without rerunning the whole pipeline. The hidden flag (Cobra's `Hidden: true`) keeps these out of the default help text; `gh optivem atdd debug --help` still works for anyone who knows they exist.

The handlers are deliberately thin: they translate Cobra flags into internal/atdd/runtime/* calls and surface their errors via exitOnError (defined in runner_commands.go) for consistency with the rest of the `optivem` binary.

atdd_init.go provides the thin wrapper that lets `runInit`'s buildSteps call `atdd.Install` as a phase step. There is no standalone `gh optivem atdd install` subcommand — ATDD assets are installed only as part of `gh optivem init`. To refresh ATDD assets in an existing repo, re-run `gh optivem init` (or copy the assets from a fresh shop checkout by hand).

gh-optivem: A gh CLI extension for pipeline project management.

Usage:

Monolith:
  gh optivem init --owner acme --system-name "Page Turner" --repo page-turner \
      --arch monolith --monolith-lang java

Multitier:
  gh optivem init --owner acme --system-name "Page Turner" --repo page-turner \
      --arch multitier --backend-lang java --frontend-lang react

Dry run:
  gh optivem init ... --dry-run

runner_commands.go wires the `build system`, `run system`, `test system`, `stop system`, and `clean system` subcommands into the root Cobra command. The runner package is fully agnostic — these handlers just translate Cobra flags into runner.* calls.

Working-dir contract: each command operates against the user's current working directory. JSON config paths default to ./system.json and ./tests.json; both can be overridden with --system / --tests.