Skip to content

feat(help): structured help for daemon/plugin/adapter/profile namespaces#1407

Open
jackwener wants to merge 1 commit intomainfrom
feat/help-structured-daemon-plugin-adapter
Open

feat(help): structured help for daemon/plugin/adapter/profile namespaces#1407
jackwener wants to merge 1 commit intomainfrom
feat/help-structured-daemon-plugin-adapter

Conversation

@jackwener
Copy link
Copy Markdown
Owner

Summary

Extends A0 (PR #1404) by dogfooding installCommanderNamespaceStructuredHelp on the four remaining built-in Commander namespaces:

  • opencli daemon --help -f yaml|json (3 leaves)
  • opencli plugin --help -f yaml|json (5 leaves)
  • opencli adapter --help -f yaml|json (3 leaves)
  • opencli profile --help -f yaml|json (3 leaves)

Each emits the same payload shape as browser: namespace metadata, every leaf's positionals + command_options + description + usage, namespace_options (empty for these), and program-level global_options.

Agents can fetch every leaf's contract in a single call — no per-leaf --help follow-ups. Same call-count reduction as A0, applied to the remaining built-in namespaces.

external (passthrough binaries — gh / vercel / docker) is correctly out of scope; their help is owned by the foreign tool.

Why the description snapshot

Each namespace snapshots its original .description() at declaration time because applyRootSubcommandSummaries(program) later overwrites it with a child-name listing ("restart, status, stop"). Without the snapshot, structured help would surface that listing instead of the product description ("Manage the opencli daemon"). The adapter test asserts this explicitly.

Test plan

  • npm test src/cli.test.ts src/help → 138/138 pass (4 new tests, one per namespace)
  • npm run build clean (799 manifest entries unchanged)
  • npm run typecheck clean
  • Smoke opencli daemon --help -f yaml / plugin / adapter / profile — each returns structured YAML, descriptions preserved
  • Smoke leaves: daemon status, plugin update, adapter reset, profile rename — single-leaf structured shape with positionals/options correctly extracted
  • No regression on browser --help -f yaml (still 35 leaves, description preserved)

cc @codex-coder per A0 thread #OpenCLI:968cb389

Extends A0 (PR #1404) by dogfooding `installCommanderNamespaceStructuredHelp`
on the four remaining built-in Commander namespaces:

- `opencli daemon --help -f yaml|json`
- `opencli plugin --help -f yaml|json`
- `opencli adapter --help -f yaml|json`
- `opencli profile --help -f yaml|json`

Each emits the same payload shape as `browser`: namespace metadata, every
leaf command's positionals + command_options + description + usage,
namespace_options (empty for these), and program-level global_options.
Agents can fetch every leaf's contract in a single call — no per-leaf
`--help` follow-ups.

Each namespace snapshots its original description at declaration time
because `applyRootSubcommandSummaries(program)` later overwrites
`.description()` with a child-name listing; without the snapshot,
structured help would surface `"restart, status, stop"` instead of
`"Manage the opencli daemon"`. Tests lock the snapshot semantics for
`adapter` explicitly.

Tests: 138/138 (4 new — one per namespace, covering description
preservation, leaf names, positionals, command_options).
Typecheck + build clean.
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