gh-optivem

README

gh-optivem

A GitHub CLI extension for scaffolding pipeline projects.

Prerequisites

• GitHub CLI (gh auth login)

Installation

gh extension install optivem/gh-optivem

Uninstalling

gh extension remove optivem

Version

gh optivem --version

Upgrading

gh extension upgrade optivem

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

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

Dry run

gh optivem init ... --dry-run

Verification level

Control how deep pipeline verification goes after scaffolding:

gh optivem init ... --verify-level local          # local compilation + local tests only (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 ... --exclude-legacy             # skip legacy in local tests and acceptance
gh optivem init ... --skip-local-tests           # skip Run-SystemTests.ps1 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.

Deployment target

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

Troubleshooting

Partial scaffold on failure

When scaffolding fails mid-run, the partial working tree is pushed to a debug/<timestamp> branch in the already-created remote repo so the state can be inspected and diffed. The default main branch is left untouched. The debug branch URL is printed in the summary.

To skip this push (e.g. for private repos or when you don't want any partial state on the remote):

gh optivem init ... --no-commit-on-failure

Auto-filed bug report (opt-in)

If you want the failure auto-filed to optivem/gh-optivem as an issue — including scaffold config and the debug-branch URL — 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.

Contributing

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

Documentation

Overview

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`, `stop system`, and `run system tests` subcommands into the main package. The runner package is fully agnostic — these handlers just translate CLI 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.