Skip to content

Group gx help commands + quickstart and bump to 7.0.28#408

Merged
NagyVikt merged 1 commit intomainfrom
agent/claude/improve-install-and-setup-cli-2026-04-23-22-26
Apr 23, 2026
Merged

Group gx help commands + quickstart and bump to 7.0.28#408
NagyVikt merged 1 commit intomainfrom
agent/claude/improve-install-and-setup-cli-2026-04-23-22-26

Conversation

@NagyVikt
Copy link
Copy Markdown
Collaborator

Summary

Before:

```
COMMANDS
status Show GitGuardex CLI + service health ...
setup Install, repair, and verify guardrails ...
doctor Repair drift + verify ...
branch CLI-owned branch workflow surface ...
(… 16 more flat rows …)
```

A first-time user had to scan the whole 20-row list to figure out the intended "install → setup → first branch" sequence. This restructures the help surface into a grouped catalog with a Quickstart block that makes the bootstrap path visible up-front.

After (gx --help or gx with no args):

  • QUICKSTART
    1. `gx setup`
    2. `gx branch start "" ""`
    3. `gx branch finish --via-pr --wait-for-merge --cleanup`
  • COMMANDS (grouped)
    • Setup & health — Install, repair, and check a repo. Run these first on a new clone.
    • Branch workflow — The sandbox → commit → PR → merge loop for agent-owned branches.
    • Coordination — File locks, worktrees, hooks, and protected-branch policy.
    • Agents & reports — Review / cleanup bots, AI setup prompts, and safety reports.
    • Meta — Version + help.

Changes

  • `src/context.js`: add `CLI_COMMAND_GROUPS` and `CLI_QUICKSTART_STEPS` as the grouped source of truth; derive `CLI_COMMAND_DESCRIPTIONS` from the groups so existing callers keep working.
  • `src/output/index.js`: render the grouped catalog in both the plain (`NO_COLOR=1` / non-TTY) and colored tree-pipe layouts used by `usage()` and `printToolLogsSummary()`; add a QUICKSTART section to both surfaces.
  • `package.json` / `package-lock.json`: bump `@imdeadpool/guardex` from `7.0.27` → `7.0.28` so the CLI UX change can publish on a fresh npm version.
  • `README.md`: add a `### v7.0.28` release note (the metadata test requires a matching heading to exist for the current package version).

Test plan

  • `node --test test/metadata.test.js test/output.test.js test/cli-args-dispatch.test.js` — 35 pass, 0 new failures.
  • `NO_COLOR=1 node bin/multiagent-safety.js --help` — plain help renders the new QUICKSTART + grouped COMMANDS sections.
  • `FORCE_COLOR=1 node bin/multiagent-safety.js` — no-args output renders the same groups inside the existing tree-pipe layout with colored group headers.
  • Publish to npm (`npm publish`) once merged; `7.0.28` is still unpublished.

Known unrelated failures

  • `critical runtime helper scripts and active-agents sources stay in sync with templates` / `setup provisions workflow files and repo config` — both are pre-existing on `main` (verified via `git stash` + rerun); caused by `vscode/guardex-active-agents/extension.js` drifting from its template. Not touched in this PR.

🤖 Generated with Claude Code

The `gx --help` and `gx` (no-args) output used to render every CLI command
as one flat 20-row list, so a first-time user had to scan the entire
catalog to find the intended "install, setup, first branch" sequence.

Rework the help surface into a grouped catalog with a Quickstart block so
the expected bootstrap path is always visible before the exhaustive command
reference:

- Add `CLI_COMMAND_GROUPS` (Setup & health / Branch workflow / Coordination
  / Agents & reports / Meta) and `CLI_QUICKSTART_STEPS` in `src/context.js`
  as the source of truth, and derive the existing flat
  `CLI_COMMAND_DESCRIPTIONS` export from those groups so other callers keep
  working.
- Teach `src/output/index.js` to render the grouped catalog in both the
  plain (`NO_COLOR=1` / non-TTY) and colored tree-pipe layouts used by
  `usage()` (`gx --help`) and `printToolLogsSummary()` (`gx` with no
  arguments). A new QUICKSTART section shows the three-step bootstrap
  (`gx setup` → `gx branch start` → `gx branch finish --via-pr
  --wait-for-merge --cleanup`).

Bump the package version to 7.0.28 so this CLI UX change can ship on a
fresh npm publish; README release notes document the redesign under the
v7.0.28 heading (metadata tests require a matching heading to exist).

Verified locally with `node --test test/metadata.test.js test/output.test.js
test/cli-args-dispatch.test.js` (35 pass, 0 new failures; the single
remaining failure in the broader suite is the pre-existing
vscode-active-agents extension drift, present before this change).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@NagyVikt NagyVikt merged commit 8c9786a into main Apr 23, 2026
0 of 5 checks passed
@NagyVikt NagyVikt deleted the agent/claude/improve-install-and-setup-cli-2026-04-23-22-26 branch April 23, 2026 21:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant