Add lint/test to ensure help documentation stays in sync with commands

[bjcoombs]

Problem Statement

The help documentation in scripts/modules/ui.js (displayHelp()) can become outdated when commands are added, removed, or modified. This was discovered in #1588 where the tag commands and list options were out of sync with the actual implementations.

Proposed Solution

Add a lint rule or test that fails when help documentation doesn't match the actual command implementations.

Approaches to Consider

1. Command registry comparison test

   • Extract command names/options from apps/cli/src/commands/*.ts files
   • Compare against entries in displayHelp()
   • Fail if commands exist in CLI but not in help (or vice versa)

2. Single source of truth refactor

   • Define command metadata (name, args, description) in one place
   • Have both Commander setup and help display read from the same source
   • Eliminates drift by design

3. Snapshot test with review requirement

   • Snapshot the help output
   • Require explicit update when commands change
   • Forces developer to consciously update help

Suggested Implementation

Option 1 (lint/test) is probably the quickest win:

// test: help-documentation-sync.spec.ts
it('should have help entries for all CLI commands', () => {
  const cliCommands = extractCommandsFromCLI(); // parse apps/cli/src/commands/
  const helpCommands = extractCommandsFromHelp(); // parse displayHelp()
  
  const missingInHelp = cliCommands.filter(c => !helpCommands.includes(c));
  const extraInHelp = helpCommands.filter(c => !cliCommands.includes(c));
  
  expect(missingInHelp).toEqual([]);
  expect(extraInHelp).toEqual([]);
});

Context

• Related PR: docs: Update help command with current tags and list options #1593 (manual fix for outdated help)
• Help location: scripts/modules/ui.js line ~547
• Commands location: apps/cli/src/commands/*.ts

Acceptance Criteria

• CI fails when a new command is added without updating help
• CI fails when a command is removed without updating help
• CI fails when command options change significantly without updating help