Skip to content

fix(cli): print help for init/update/uninstall instead of running them#460

Merged
latekvo merged 6 commits into
mainfrom
fix/cli-help-shortcircuit-installer-subcommands
Jul 10, 2026
Merged

fix(cli): print help for init/update/uninstall instead of running them#460
latekvo merged 6 commits into
mainfrom
fix/cli-help-shortcircuit-installer-subcommands

Conversation

@latekvo

@latekvo latekvo commented Jul 2, 2026

Copy link
Copy Markdown
Member

The bug

argent <cmd> --help for the installer subcommands init / install / update / uninstall / remove did not print help — it ran the real, side-effecting command. argent uninstall --help even opened the destructive "Remove argent configuration from this workspace?" prompt (with Yes pre-selected).

Root cause: main() in packages/argent/src/cli.ts dispatched these subcommands and forwarded rest (including --help) to the installer functions, which have no help handling. Only the top-level --help case called printHelp().

The fix

Intercept --help/-h for exactly the installer command set before dispatching, and print a short per-subcommand usage block without loading or invoking any installer code (no network, no wizard, no prompt).

  • New side-effect-free module packages/argent/src/installer-help.ts exports the pure decision function installerHelpRequested(command, rest) plus printInstallerHelp(command).
  • cli.ts calls the guard at the top of main() and returns early when help is requested.
  • The other subcommands (run, tools, server, link, flags, enable, disable, telemetry) already handle --help themselves, so they are deliberately excluded — argent run <tool> --help still prints that tool's flags.

Verification

  • npm run build (root tsc) + npm run build -w @swmansion/argent — green.
  • Ran the built CLI end-to-end (stdin from /dev/null): init --help, update --help, uninstall --help, install --help, remove --help, uninstall -h all print usage and exit 0 with no wizard/network/prompt.
  • Regression: argent --help still prints top-level help; argent run --help still prints the run usage (not intercepted).
  • Added unit tests in packages/argent/test/installer-help.test.ts for installerHelpRequested / isInstallerCommand (8 tests, all pass).
  • prettier and eslint clean on the touched files; test typecheck passes.

Fixes #451

`argent <cmd> --help` for the installer subcommands (init / install /
update / uninstall / remove) forwarded `--help` straight to the
side-effecting installer functions, which don't short-circuit on help —
so `argent uninstall --help` ran the real uninstall and opened the
destructive removal prompt.

Intercept `--help`/`-h` for exactly that command set before dispatching
and print a short per-subcommand usage block without loading or invoking
any installer code. All other subcommands (run / tools / server / …)
keep handling `--help` themselves, so `argent run <tool> --help` is
unaffected.

Fixes #451
@latekvo
latekvo marked this pull request as ready for review July 2, 2026 17:20

@hubgan hubgan left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the installer-help short-circuit and exercised it end-to-end against the built CLI: the five installer subcommands now print usage and exit 0 without running, argent uninstall --help and remove --help leave an existing workspace's config byte-for-byte unchanged (no prompt, nothing deleted), and run / tools / server still handle their own --help unaffected. I also confirmed the pre-fix behaviour — uninstall derives non-interactivity only from --yes, so --help previously fell through to the destructive confirm. The fix is correct; the inline notes are mostly about test coverage of the dispatch path.

Comment thread packages/argent/src/cli.ts
Comment thread packages/argent/src/installer-help.ts
Comment thread packages/argent/src/installer-help.ts Outdated
Comment thread packages/argent/src/installer-help.ts Outdated
Comment thread packages/argent/src/installer-help.ts Outdated
latekvo added 2 commits July 7, 2026 16:17
…atching

Resolves the review feedback on the installer-help short-circuit:

- Guard coverage: add cli-dispatch.test.ts, a spawn-based E2E that transpiles
  the real dispatcher (type-only workspace imports erase) and stages fake
  bundles recording invocation. It proves `uninstall --help` never reaches the
  installer while the control `uninstall` does — so dropping the guard's
  return / moving it below the switch fails the suite.
- printInstallerHelp: cover per-command output (usage, summary, options,
  alias pointer, footer) and its side-effect-free contract.
- Help now lists each command's real flags (init: --yes/-y, --no-telemetry,
  --from; update: --yes/-y, --no-telemetry, --version; uninstall: --yes/-y),
  instead of only `argent <cmd> [options]`.
- Match help leniently on the destructive commands: case-insensitive
  --help/-h, --help=<value>, and the bareword `help` in first position all
  short-circuit rather than falling through to the real uninstall prompt.
- Single source of truth for the command summaries in INSTALLER_COMMAND_META;
  the top-level `argent --help` table reads them so the two copies can't drift.
- installer-help.test.ts referenced cli-dispatch.e2e.test.ts; the file is
  cli-dispatch.test.ts.
- Clarify that INSTALLER_COMMAND_META's option lists are a hand-maintained
  mirror of the installer parsers (nothing links them automatically), rather
  than implying they're a single source of truth for the flags themselves.

@hubgan hubgan left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed and verified this end-to-end: built the CLI and ran every installer --help form against the real dispatcher. Each prints usage and exits 0 without loading the installer bundle, and uninstall --help in a workspace populated with argent config leaves every file untouched. The option lists in INSTALLER_COMMAND_META match the real init/update/uninstall parsers, and non-installer commands (run/tools) still handle their own --help. A few low-severity notes inline.

Comment thread packages/argent/src/installer-help.ts Outdated
Comment thread packages/argent/src/installer-help.ts
Comment thread packages/argent/src/installer-help.ts
Comment thread packages/argent/test/cli-dispatch.test.ts Outdated
Comment thread packages/argent/test/installer-help.test.ts Outdated
latekvo added 3 commits July 10, 2026 00:14
Reconciles the help text with main's installer changes (#428): the top-level
table keeps its per-command detail lines but now renders them from
INSTALLER_COMMAND_META (single source), and the per-command option lists gain
the --global/--local flags the installers now parse.
…st the dispatch both ways

Review follow-ups:

- `argent uninstall --yes help` (and `-y help`) fell through to the real
  uninstall, and --yes makes it non-interactive — config pruned with no
  prompt and no help. The bareword `help` now counts in any position
  unless it directly follows a value-taking flag (--from/--version/
  --project-root), so `init --from help` still reaches the installer.
- isHelpFlag also accepts single-dash `-help` and smart-dash `—help`/
  `–help` spellings; its comment now states exactly what is (and is not)
  matched instead of overpromising leniency.
- New installer-flags-sync.test.ts reads the installer parser sources and
  fails when INSTALLER_COMMAND_META's option lists (or VALUE_TAKING_FLAGS)
  drift from the flags the parsers consult.
- cli-dispatch fakes now record every bundle dispatch with its argv, so
  the suite asserts the complementary guarantees too: run/tools --help
  forward to their own bundle, top-level --help loads no bundle, unknown
  commands exit 1.
- printInstallerHelp side-effect test no longer pins the console.log call
  count (an implementation detail); it asserts output and undefined return.
…tighten value-flag tripwire

Follow-ups from a post-merge review sweep:

- README listed `argent remove` as the primary command with `uninstall` as
  its alias — the inverse of the dispatcher and of the help this branch
  prints (`remove --help` points at `uninstall`). Swapped to match.
- The top-level --help E2E only matched a substring that main's old
  hard-coded table also contained, so a revert of the META-sourced
  rendering kept tests green. It now pins the meta-only summary wording,
  a detail line, and an alias row (mutation-checked: dropping the details
  rendering fails it).
- The value-taking-flag check accepted the inline `--flag=` form, which
  consumes no token — removing update's `--version` lookahead branch kept
  the suite green while VALUE_TAKING_FLAGS lied. Replaced (together with
  the weaker subset test) by a per-command set-equality against the
  token-consuming idioms only (mutation-checked both ways).
- Word-boundary on the args.includes extraction pattern; reworded the
  installerHelpEntry comment — only the summary is drift-shared, details
  are table-only.
@latekvo
latekvo merged commit 3f26807 into main Jul 10, 2026
5 checks passed
@latekvo
latekvo deleted the fix/cli-help-shortcircuit-installer-subcommands branch July 10, 2026 10:48
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.

<cmd> --help runs the command instead of printing help for init/update/uninstall (uninstall --help opens the destructive prompt)

2 participants