fix: add consistent focused help for nested CLI commands #290

Merged

erik merged 1 commit from fix/task-521ffebf-nested-help into main

2026-10-04 16:16:17 -05:00

erik commented

2026-10-04 15:29:44 -05:00

Owner

Summary

Route --help and -h before global/command validation or execution, including help after operands/options.
Add centralized focused help for all 72 supported levels (root, parent namespaces and leaf commands), with usage, required inputs, options, defaults and examples.
Keep parent/top-level help concise; move existing search guidance into the relevant command help.
Preserve short -h values of value-taking options as data, unknown-command errors and normal execution behavior.
Document help usage and verify it with mocked unit tests.

Verification

./scripts/pre-pr.sh passed: generated CSS, formatting, lint, types, and 1,077 local tests.
181 help-specific unit tests cover every supported path with both flags, successful main exits, focused text, global options, and absence of filesystem/config/network/prompt/browser side effects.
npm run build --workspace @evcraddock/slug-cli passed.
Built CLI post create --help, post import -h, site config set --help, login -h and config site add --help exited 0 locally without site configuration or command operands.
git diff --check passed.

CI remains unchanged and unit-only: no integration tests, browser/E2E or container validation added. No dependency, package version or release changes.

Task: #task-521ffebf

Awaiting CI, independent review and explicit human merge approval.

## Summary - Route --help and -h before global/command validation or execution, including help after operands/options. - Add centralized focused help for all 72 supported levels (root, parent namespaces and leaf commands), with usage, required inputs, options, defaults and examples. - Keep parent/top-level help concise; move existing search guidance into the relevant command help. - Preserve short -h values of value-taking options as data, unknown-command errors and normal execution behavior. - Document help usage and verify it with mocked unit tests. ## Verification - ./scripts/pre-pr.sh passed: generated CSS, formatting, lint, types, and 1,077 local tests. - 181 help-specific unit tests cover every supported path with both flags, successful main exits, focused text, global options, and absence of filesystem/config/network/prompt/browser side effects. - npm run build --workspace @evcraddock/slug-cli passed. - Built CLI post create --help, post import -h, site config set --help, login -h and config site add --help exited 0 locally without site configuration or command operands. - git diff --check passed. CI remains unchanged and unit-only: no integration tests, browser/E2E or container validation added. No dependency, package version or release changes. Task: #task-521ffebf Awaiting CI, independent review and explicit human merge approval.

erik added 1 commit

2026-10-04 15:29:44 -05:00

fix: make nested CLI help focused and side-effect free

CI / build-lint-test (pull_request) Successful in 53s

Details

ed266bb76d

Route help before global and command validation, document all command levels in one registry, and keep top-level help concise. Unit tests cover both flags, successful exits, focused guidance and absence of config, file, network or authentication side effects.

Task: #task-521ffebf

erik commented

2026-10-04 15:33:26 -05:00

Author

Owner

Independent PR review

PR: #290 (ed266bb76d) is open.
Result: approved.
Scope: reviewed the Forgejo PR diff against task task-521ffebf; no project files were edited and no verification was rerun.

Acceptance criteria

All supported command levels accept --help and -h: cli/src/help.ts centralizes the route inventory, including root, parent, and leaf command paths, and resolves both flags before command execution.
Explicit help exits with status 0: main and runCommand return ExitCode.Ok when focused help resolves, before global validation or command handling.
Help does not perform network calls, authentication, or mutations: help routing precedes config/API/login/import execution, and the added unit tests mock/forbid filesystem, fetch, prompt, and browser effects for help paths.
Focused help exists for post create/import/edit/publish, media, site config, and authentication workflows: the registry includes targeted usage, required inputs, relevant options/defaults, notes, and examples for those paths.
Automated tests cover help output and successful exit behavior across representative nested commands: new help tests cover every registered supported path with both flags plus precedence, side-effect, unknown-command, and focused-content cases.
Top-level help remains concise and points users toward command-level help: root/parent help lists subcommands, omits leaf-specific option floods, and points to slug <command> --help; existing search guidance moved into focused help.

Quality checks

Scope alignment: aligned with the nested-help task; no workflow, dependency, version, or CI integration-test changes are present.
Code quality/maintainability: the resolver is pure and separated from command handlers; help text is centralized beside a single route inventory.
Tests: adequate unit coverage for the changed resolver/routing behavior and edge cases.
Security/docs: no new credential exposure or external effects; CLI README documents the new help behavior.

Blocking issues

None.

Warnings

None.

Final verdict

Approved. Stop at the human merge gate; do not merge without explicit human approval.

### Independent PR review - PR: #290 (`ed266bb76d`) is open. - Result: approved. - Scope: reviewed the Forgejo PR diff against task `task-521ffebf`; no project files were edited and no verification was rerun. #### Acceptance criteria - [x] All supported command levels accept `--help` and `-h`: `cli/src/help.ts` centralizes the route inventory, including root, parent, and leaf command paths, and resolves both flags before command execution. - [x] Explicit help exits with status 0: `main` and `runCommand` return `ExitCode.Ok` when focused help resolves, before global validation or command handling. - [x] Help does not perform network calls, authentication, or mutations: help routing precedes config/API/login/import execution, and the added unit tests mock/forbid filesystem, fetch, prompt, and browser effects for help paths. - [x] Focused help exists for post create/import/edit/publish, media, site config, and authentication workflows: the registry includes targeted usage, required inputs, relevant options/defaults, notes, and examples for those paths. - [x] Automated tests cover help output and successful exit behavior across representative nested commands: new help tests cover every registered supported path with both flags plus precedence, side-effect, unknown-command, and focused-content cases. - [x] Top-level help remains concise and points users toward command-level help: root/parent help lists subcommands, omits leaf-specific option floods, and points to `slug <command> --help`; existing search guidance moved into focused help. #### Quality checks - Scope alignment: aligned with the nested-help task; no workflow, dependency, version, or CI integration-test changes are present. - Code quality/maintainability: the resolver is pure and separated from command handlers; help text is centralized beside a single route inventory. - Tests: adequate unit coverage for the changed resolver/routing behavior and edge cases. - Security/docs: no new credential exposure or external effects; CLI README documents the new help behavior. #### Blocking issues - None. #### Warnings - None. #### Final verdict Approved. Stop at the human merge gate; do not merge without explicit human approval.

erik merged commit ae4ceef3b1 into main

2026-10-04 16:16:17 -05:00

erik deleted branch fix/task-521ffebf-nested-help

2026-10-04 16:16:17 -05:00

erik referenced this pull request from a commit

2026-10-04 16:16:19 -05:00

Merge pull request 'fix: add consistent focused help for nested CLI commands' (#290) from fix/task-521ffebf-nested-help into main