Skip to content

feat(cli): add qawolf help ref for a command subtree's help - #1651

Merged
Erzhan Torokulov (erzhtor) merged 1 commit into
mainfrom
erzhan/age-5384-help-ref
Oct 6, 2026
Merged

Erzhan Torokulov (erzhtor) merged 1 commit into
mainfrom
erzhan/age-5384-help-ref

Conversation

@erzhtor

@erzhtor Erzhan Torokulov (erzhtor) commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Relates to AGE-5384.

Overview of Changes

Agents learn the runner commands from three hand-written copies: each command's --help, references/runner.md, and the platform's own Tester skill. They drift, and only --help is versioned with the binary an agent actually runs. This stack makes the CLI's help the one source.

This PR adds the read side. qawolf help ref [command...] (alias reference) prints the full --help of a command and of every visible command under it as Markdown: one heading per command, nested by depth, each followed by its help in a text block. qawolf help ref runner is every runner command in one read instead of 29.

  • Commander's built-in help [command] can't take a subcommand of its own, so program.ts turns it off and help/index.ts registers a replacement. qawolf help <command> behaves as before; an unknown path exits 2.
  • The help is captured through outputHelp(), not helpInformation(), because the latter drops addHelpText (every Examples block). It wraps at a fixed 100 columns so the output doesn't depend on the terminal.
  • The tree walk is shared with the generated command table in skill.ts.

Stack:

# PR Contribution
1 #1651 (this PR) qawolf help ref [command...] prints a command subtree's full help as Markdown
2 #1652 runner.md's knowledge moves into each runner command's --help; runner.md is generated from qawolf help ref runner
3 qawolf/platform#34845 Tester's qawolf-cli skill points at the CLI's help instead of restating it

#1652 is stacked on this PR, and both ship together in 1.40.0. qawolf/platform#34845 waits for that release.

Testing

bun run typecheck && bun run lint && bun run format:check && bun run knip && bun run test && bun run build

New tests cover nested headings, hidden commands, addHelpText text, the reference alias, help <command>, and unknown paths. A snapshot pins help ref runner. Only the root --help snapshot changed (the help row). All tests pass except 3 keychain tests that also fail on main on this machine.

Checklist

  • Changes follow the code style of this project
  • Self-review completed
  • Tests added/updated (or not applicable)
  • No breaking changes (or described below)

@erzhtor
Erzhan Torokulov (erzhtor) marked this pull request as ready for review October 6, 2026 11:52
@erzhtor
Erzhan Torokulov (erzhtor) added this pull request to stack #1653 October 6, 2026 12:29
@erzhtor
Erzhan Torokulov (erzhtor) requested review from a team October 6, 2026 13:10
@erzhtor
Erzhan Torokulov (erzhtor) merged commit e52cce9 into main Oct 6, 2026
6 checks passed
@erzhtor
Erzhan Torokulov (erzhtor) deleted the erzhan/age-5384-help-ref branch October 6, 2026 15:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants