A

CLI Refactor Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Make the CLI entrypoint easier to read by moving command wiring and help formatting into named modules without changing command behavior.

Architecture: Keep src/cli.ts as the process-level entrypoint: invocation-name handling, update scheduling, setup shortcut routing, and program.parseAsync. Move Commander registration into src/cli/register-commands.ts, shared CLI helpers into src/cli/helpers.ts, and root help rendering into src/cli/help.ts. Do not introduce a framework, domain layer, or new runtime behavior.

Tech Stack: TypeScript, Commander, Vitest.

Task 1: Extract Shared CLI Helpers#

Files:

  • Create: src/cli/helpers.ts
  • Modify: src/cli.ts

Steps:

  1. Move emit, collectOption, parsePositiveInt, and readStdin into src/cli/helpers.ts.
  2. Export a small CommandResult interface from src/cli/helpers.ts.
  3. Import helpers from src/cli.ts.
  4. Run npm run lint.

Task 2: Extract Help Rendering#

Files:

  • Create: src/cli/help.ts
  • Modify: src/cli.ts

Steps:

  1. Move HELP_GROUPS, configureGroupedHelp, and the default subcommand help renderer into src/cli/help.ts.
  2. Keep the existing ANSI formatting and Commander behavior unchanged.
  3. Import configureGroupedHelp from src/cli.ts.
  4. Run npm test -- test/cli.test.ts.

Task 3: Extract Command Registration#

Files:

  • Create: src/cli/register-commands.ts
  • Modify: src/cli.ts

Steps:

  1. Move all program.command(...) wiring into registerCommands(program).
  2. Keep command actions calling the same command modules with the same option mapping.
  3. Keep src/cli.ts responsible for creating the Command, configuring metadata, setup shortcut routing, grouped help, and parsing.
  4. Run npm test -- test/cli.test.ts.

Task 4: Verify Full Baseline#

Commands:

  • npm run lint
  • npm test

Expected: TypeScript passes and the full Vitest suite remains green.