Skip to content

feat: add per-command help - #148

Merged
Bccorb merged 1 commit into
mainfrom
feat/per-command-help
Aug 1, 2026
Merged

feat: add per-command help#148
Bccorb merged 1 commit into
mainfrom
feat/per-command-help

Conversation

@Bccorb

@Bccorb Bccorb commented Aug 1, 2026

Copy link
Copy Markdown
Contributor

seamless <command> -h / --help (and seamless help <command>) now print help for that command instead of the full manual.

$ seamless verify -h

seamless verify — seamless v0.10.2

USAGE

  seamless verify [--local] [--api-only] [--no-react] [--filter=<flow>] [--keep-up]

DESCRIPTION

  Stand up the auth stack and run the conformance suite across the API and
  the cookie (adapter) paths. Requires Docker. ...

  --api-only
    • Run the API layer only, skipping the adapter and browser layers
  ...

What changed

  • One registry, two renderings. src/commands/helpTopics.ts holds an entry per command (usage lines, description sections, examples). Both the full seamless --help output and the per-command output render from it, so a flag is documented once. COMMANDS is derived from the same registry, replacing the hardcoded list the dispatcher used for its unknown-command message.
  • src/commands/help.ts now formats instead of hardcoding: printHelp() composes the USAGE and COMMANDS sections, printCommandHelp(name) prints the scoped view and returns false for an unknown topic so the caller falls back to the unknown-command error.
  • The help check runs before a command parses its own args (src/index.ts). That also fixes a bug: seamless init -h previously fell through init's positional parsing and was treated as a project name, so it would have scaffolded ./-h.
  • hasHelpFlag (src/core/args.ts) stops at a literal --, leaving room for a command that legitimately takes -h as a value: seamless config set key -- -h.

Top-level seamless --help output is unchanged apart from a new seamless <command> --help usage line, and --no-react on verify, which was a real flag that had never been documented.

Checks

  • npm run build clean.
  • npm test: 718 passed, 4 skipped.
  • npm run coverage passes; 100% on index.ts, help.ts, helpTopics.ts, and args.ts.

New tests cover the flag parsing (including the -- escape), every command's scoped output, and the dispatcher paths (init -h not scaffolding, help <command>, unknown topic).

README gained a "Getting help" section, AGENTS.md points future changes at the registry, and there is a changeset (minor).

Every command now answers -h / --help with usage, flags, subcommands, and
examples scoped to that command, and seamless help <command> prints the same
thing. The text lives in one registry (src/commands/helpTopics.ts) that both
the full seamless --help output and the per-command output render from, so a
flag is documented once. The dispatcher's known-command list comes from there
too.

The help check runs before a command parses its own arguments, so seamless
init -h prints help instead of scaffolding ./-h. A -- separator ends the check,
leaving room for a literal -h operand (seamless config set key -- -h).
@Bccorb
Bccorb merged commit 64cdf80 into main Aug 1, 2026
2 checks passed
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