fix(surgical): Establish a single source of truth for "this command cann... (#1589)

[aidandaly24]

Refs aws#1589

Issues

• bug: inconsistent behavior for unsupported TUI commands. aws/agentcore-cli#1589 — In the TUI command list, feedback and config appear in the MAIN (interactive) command list, but selecting them dead-ends on the "this command runs in the terminal" CliOnlyScreen instead of doing anything. feedback is the worst case: it has a real interactive FeedbackScreen the TUI could render, but the TUI tells the user to go run it in the terminal instead. Meanwhile genuinely CLI-only commands behave a third way and preview-gated export simply doesn't appear. Net effect is inconsistent, confusing UX across unsupported/partially-supported commands.

Root cause

Two manually-synced lists have diverged: CLI_ONLY_COMMANDS (commands.ts:20) sets the cliOnly flag that HelpScreen.tsx:232,236 uses for list placement, while CLI_ONLY_EXAMPLES (copy.ts:68) controls App.tsx:138-142 dead-end routing. config (copy.ts:142) and feedback (copy.ts:138) are in the second but not the first and are registered unconditionally (cli.ts:101,122), so they render in the main interactive list (cliOnly=false) yet route to the CliOnlyScreen dead-end. feedback has a real FeedbackScreen (commands/feedback/command.tsx:27) the TUI never reaches. Verified at v0.20.2 by reading all files and running the coverage test (passes, so it does not catch this).

The fix

Establish a single source of truth for "this command cannot run interactively in the TUI" and reconcile membership, then enforce consistency in tests. Concretely: derive the cliOnly flag in commands.ts from the keys of CLI_ONLY_EXAMPLES (or vice versa) so a command can never be in the main list yet dead-end. Then decide membership per the issue author's lean toward hiding: feedback should NOT be CLI-only — wire its existing FeedbackScreen (commands/feedback/command.tsx:27) into App.tsx onSelectCommand so it opens interactively; config should either get a tiny TUI screen or, at minimum, be flagged cliOnly consistently (or hidden via HIDDEN_FROM_TUI) so it isn't shown-then-dead-ended. Also drop the unused insights key from CLI_ONLY_EXAMPLES. Strengthen app-command-coverage.test.ts to assert the two lists agree: every CLI_ONLY_EXAMPLES key that is a registered top-level command must be flagged cliOnly, and every cliOnly command must have examples. Design decision required: hide-all-unsupported vs show-in-CLI-only-section-with-usage; author recommends hide.

Files touched: src/cli/tui/utils/commands.ts (CLI_ONLY_COMMANDS:20, HIDDEN_FROM_TUI:15, cliOnly derivation:56); src/cli/tui/copy.ts (CLI_ONLY_EXAMPLES:68 — feedback:138, config:142, unused insights:146); src/cli/tui/App.tsx (onSelectCommand CLI_ONLY_EXAMPLES branch:138-142, add a feedback route alongside FeedbackScreen); src/cli/tui/screens/home/HelpScreen.tsx (interactive vs cliOnly split:231-237); src/cli/tui/tests/app-command-coverage.test.ts (add list-consistency assertion)

Validation evidence

The fix was verified by reproducing the original symptom and re-running after the change:

Drove the actual TUI via tui-harness against the built dist (node /local/home/aidandal/workplace/issues/bugfix-run/clusters/1589/repo/dist/cli/index.mjs).

PASS CONDITION 1 (feedback opens interactive screen): Tab -> command list -> filtered "feedback" -> Enter. AFTER FIX: opens the interactive Ink FeedbackScreen ("Message -> Screenshot -> Consent -> Submitting -> Done" stepper with "Tell us what's on your mind / Feedback" text input). It NO LONGER routes to the generic "this command runs in the terminal" CliOnlyScreen. BEFORE FIX (per symptom + code): feedback was in CLI_ONLY_EXAMPLES so App.tsx:140-142 short-circuited every feedback selection to the cli-only dead-end, while cliOnly=false placed it in the main interactive list.

PASS CONDITION 2 (config consistent): In the main interactive list, "config" is ABSENT. Pressing "/" reveals a separate "CLI only" section containing pause/resume/stop/traces/config/archive. Selecting CLI-only "config" routes to the CliOnlyScreen ("Usage: $ agentcore config"). So config is now flagged cliOnly consistently (CLI-only section AND dead-end route agree) instead of being in the main list while routing to the dead-end.

PASS CONDITION 3 (single source of truth): commands.ts:25 now derives CLI_ONLY_COMMANDS = new Set(Object.keys(CLI_ONLY_EXAMPLES)); the cliOnly flag (HelpScreen list placement) and App.tsx CLI_ONLY_EXAMPLES dead-end routing can no longer diverge.

PASS CONDITION 4 (test fails pre-fix, passes post-fix): Verified empirically.

Test suite: green.

---

Staged on the fork as a draft for human review. Promote to aws/agentcore-cli after vetting.