refactor: decompose CLI entry point into focused modules

[sjnims]

Description

Reduces src/index.ts from 1,154 lines to 37 lines by extracting CLI commands and utilities into a dedicated src/cli/ directory structure. Each CLI command is now in its own file, making the codebase easier to navigate, test, and maintain.

Type of Change

• Refactoring (code change that neither fixes a bug nor adds a feature)

Component(s) Affected

Core Infrastructure

• CLI & Pipeline Orchestration (src/index.ts)

Other

• Other (please specify): New src/cli/ directory with command modules

Motivation and Context

Issue #245 identified src/index.ts (1,154 lines) as the largest file in the codebase, making it hard to navigate and maintain. This refactoring:

• Separates each CLI command into its own focused module
• Extracts shared utilities (formatters, helpers, options parsing)
• Reduces the main entry point to just public API exports + CLI initialization
• Follows the existing patterns established in the codebase

Fixes #245

How Has This Been Tested?

Test Configuration:

• Node.js version: v25.3.0
• OS: macOS (Darwin 25.2.0)

Test Steps:

1. Run npm run typecheck - TypeScript passes
2. Run npm run lint - ESLint passes
3. Run npm run format - Prettier passes
4. Run npm test - All 1,499 tests pass
5. Run npm run build - Build succeeds
6. Run node dist/index.js --help - CLI help displays correctly
7. Run node dist/index.js run --help - Command help displays correctly

Checklist

General

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• My changes generate no new warnings or errors

TypeScript / Code Quality

• All functions have explicit return types
• Strict TypeScript checks pass (npm run typecheck)
• ESM import/export patterns used correctly
• Unused parameters prefixed with _
• No any types without justification

Documentation

• I have updated CLAUDE.md if behavior or commands changed (no behavior change)
• I have updated inline JSDoc comments where applicable
• I have verified all links work correctly

Linting

• I have run npm run lint and fixed all issues
• I have run npm run format:check
• I have run markdownlint "*.md" on Markdown files (no MD changes)
• I have run uvx yamllint -c .yamllint.yml on YAML files (if modified) - N/A
• I have run actionlint on workflow files (if modified) - N/A

Testing

• I have run npm test and all tests pass
• I have added tests for new functionality (refactor, no new functionality)
• Test coverage meets thresholds (78% lines, 75% functions, 65% branches)
• I have tested with a sample plugin (if applicable) - CLI commands verified

New File Structure

src/cli/
  commands/
    run.ts       - Full pipeline command (196 lines)
    resume.ts    - Resume with handlers (335 lines)
    execute.ts   - Stages 1-3 (110 lines)
    report.ts    - Report generation (87 lines)
    generate.ts  - Stages 1-2 (84 lines)
    list.ts      - List runs (54 lines)
    analyze.ts   - Stage 1 only (44 lines)
    index.ts     - Command registration (42 lines)
  formatters.ts  - Output formatters (161 lines)
  helpers.ts     - State lookup utilities (97 lines)
  options.ts     - CLI option parsing (97 lines)
  index.ts       - Program setup (43 lines)
  styles.ts      - Commander help styling (26 lines)

Key metric: src/index.ts reduced from 1,154 → 37 lines (97% reduction)

Example Output

$ node dist/index.js --help
Usage: cc-plugin-eval [options] [command]

Claude Code plugin component triggering evaluation framework

Options:
  -V, --version       output the version number
  -h, --help          display help for command

Pipeline Commands:
  run [options]       Run full evaluation pipeline
  analyze [options]   Run Stage 1: Plugin Analysis only
  generate [options]  Run Stages 1-2: Analysis and Scenario Generation
  execute [options]   Run Stages 1-3: Analysis, Generation, and Execution

State Management:
  resume [options]    Resume from saved state
  report [options]    Generate report from existing results
  list [options]      List previous runs

Commands:
  help [command]      display help for command

Additional Notes

This is Phase 1 of the file decomposition effort described in #245. Future phases may include:

• Splitting src/state/state-manager.ts (722 lines)
• Splitting stage index.ts files as they're modified for other work

Reviewer Notes

Areas that need special attention:

• Verify the public API exports from src/index.ts are preserved correctly
• Verify the CLI commands work identically to before

Known limitations or trade-offs:

• New CLI files don't have test coverage (0%), matching the previous lack of CLI testing
• Some duplication exists across command files (e.g., config loading pattern)

---

🤖 Generated with Claude Code

[claude]

Claude finished @sjnims's task in 2m 58s —— View job

---

PR Review: CLI Entry Point Decomposition

I've completed a comprehensive review of this refactoring. Here are my findings:

✅ Verdict: Looks Good

This is a well-executed refactoring that successfully decomposes a 1,154-line file into focused, maintainable modules without changing any behavior.

---

Quality Checks Results

• ✅ TypeScript: No errors
• ✅ ESLint: No issues
• ✅ Prettier: All files formatted correctly
• ✅ Tests: All 1,499 tests pass
• ✅ Coverage: Meets thresholds (78% lines, 75% functions, 65% branches)

---

What's Good

Architecture & Design

• Clean separation of concerns with logical directory structure (commands/, formatters.ts, helpers.ts, options.ts)
• Each command file is focused and single-purpose (~30-335 lines vs original 1,154 lines)
• Resume handlers use a clean map-based dispatch pattern rather than conditional logic
• Public API exports are preserved correctly in src/index.ts

Code Quality

• All imports use .js extensions (ESM requirement) ✅
• Zero any types - all code is properly typed ✅
• Proper error handling with typed errors throughout
• Good use of JSDoc @internal markers for CLI-only functions
• Consistent option parsing pattern across all commands

Testing & Validation

• No regressions - all existing tests pass
• Build succeeds without warnings
• Package.json exports correctly configured

Documentation

• Inline JSDoc comments explain command purposes
• Clear file-level documentation in each module
• Helpful comments in complex areas (e.g., resume handler map)

---

Suggestions

Minor Code Duplication (Non-blocking)

Several commands share similar config loading patterns. Example from analyze.ts, execute.ts, generate.ts:

const cliOptions: Partial<CLIOptions> = {};
if (typeof options["plugin"] === "string") {
  cliOptions.plugin = options["plugin"];
}
const configPath = typeof options["config"] === "string" ? options["config"] : undefined;
const config = loadConfigWithOverrides(configPath, cliOptions);

This is acceptable for now - the duplication is minimal and each command may evolve independently. If this pattern spreads to more commands, consider extracting a shared helper.

Test Coverage for CLI (Acknowledged)

The PR notes that new CLI files have 0% test coverage, matching the previous lack of CLI testing. While this is being tracked in the "known limitations," consider adding CLI integration tests in a future PR to ensure commands work end-to-end.

CLAUDE.md Update (Optional)

The Architecture section's "Key Entry Points" table could mention the new src/cli/ structure, but this is a minor documentation enhancement rather than a requirement.

---

Architecture Review

4-Stage Pipeline: ✅ Not affected - stage logic remains unchanged

Type Safety: ✅ Excellent - uses Zod schemas, proper type guards, no any types

Error Handling: ✅ Proper - all commands have try/catch with process.exit(1) on failure

Configuration: ✅ Correct - uses loadConfigWithOverrides consistently

State Management: ✅ Proper - resume handlers correctly chain state updates

---

Specific Technical Highlights

Good Pattern: Resume Handler Map (src/cli/commands/resume.ts:240-247)

const resumeHandlers: Record<PipelineStage, ResumeHandler> = {
  pending: resumeFromAnalysis,
  analysis: resumeFromAnalysis,
  generation: resumeFromGeneration,
  execution: resumeFromExecution,
  evaluation: resumeFromEvaluation,
  complete: resumeFromEvaluation,
};

This replaces complex conditional logic with a clean lookup table.

Good Pattern: Command Registration (src/cli/commands/index.ts)
Grouped command registration makes the CLI structure clear and extensible.

Good Pattern: Option Extraction (src/cli/options.ts)
Centralized validation with clear error messages for invalid stage names.

---

Summary

This refactoring achieves its goal of making the codebase more navigable and maintainable. The 1,154-line src/index.ts is now a clean 31-line entry point with well-organized supporting modules. The implementation is high quality with no behavioral changes, proper typing, and zero test regressions.

Recommendation: Approve and merge. The known limitations (CLI test coverage, minor duplication) are acceptable and don't block this improvement.

---

[codecov]

Codecov Report

❌ Patch coverage is 0% with 379 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/cli/commands/resume.ts	0.00%	100 Missing ⚠️
src/cli/formatters.ts	0.00%	60 Missing ⚠️
src/cli/commands/run.ts	0.00%	45 Missing ⚠️
src/cli/commands/report.ts	0.00%	34 Missing ⚠️
src/cli/commands/execute.ts	0.00%	30 Missing ⚠️
src/cli/commands/generate.ts	0.00%	26 Missing ⚠️
src/cli/options.ts	0.00%	22 Missing ⚠️
src/cli/helpers.ts	0.00%	21 Missing ⚠️
src/cli/commands/list.ts	0.00%	20 Missing ⚠️
src/cli/commands/analyze.ts	0.00%	13 Missing ⚠️
... and 1 more

📢 Thoughts on this report? Let us know!

[claude]

Claude finished @sjnims's task in 3m 50s —— View job

---

PR Review: CLI Entry Point Decomposition

I've completed a comprehensive review of this refactoring PR. Here are my findings:

---

✅ Verdict: Looks Good

This is a well-executed refactoring that successfully decomposes a 1,154-line file into focused, maintainable modules without changing any behavior.

---

Quality Checks Results

• ✅ TypeScript: No errors (passes npm run typecheck)
• ✅ ESLint: No issues (passes npm run lint)
• ✅ Prettier: All files formatted correctly
• ✅ Tests: All 1,499 tests pass (57 test files, 11.5s duration)
• ✅ Coverage: Meets thresholds (78% lines, 75% functions, 65% branches)

---

What's Good

Architecture & Design

• Clean separation of concerns with logical directory structure (commands/, formatters.ts, helpers.ts, options.ts, styles.ts)
• Each command file is focused and single-purpose (~30-335 lines vs original 1,154 lines)
• Resume handlers use a clean map-based dispatch pattern (src/cli/commands/resume.ts:240-247) rather than complex conditional logic
• Public API exports are preserved correctly in src/index.ts (lines 22-35)
• Proper grouping of CLI commands (Pipeline Commands vs State Management)

Code Quality

• Zero any types - all code is properly typed ✅
• All imports use .js extensions (ESM requirement) ✅
• Proper error handling with typed errors throughout
• Good use of JSDoc @internal markers for CLI-only functions
• Consistent option parsing pattern across all commands
• Runtime type validation in formatters (e.g., formatters.ts:66-77) prevents runtime errors

Testing & Validation

• No regressions - all existing tests pass
• Build succeeds without warnings
• Package.json exports correctly configured (main entry + types subpath)

Documentation

• CLAUDE.md updated with new CLI structure (lines 259-272)
• README.md and CONTRIBUTING.md updated consistently
• PR template updated to reflect new structure
• Inline JSDoc comments explain command purposes
• Clear file-level documentation in each module

---

Suggestions

Minor Code Duplication (Non-blocking)

Several commands share similar config loading patterns. Example from analyze.ts, execute.ts, generate.ts:

const cliOptions: Partial<CLIOptions> = {};
if (typeof options["plugin"] === "string") {
  cliOptions.plugin = options["plugin"];
}
const configPath = typeof options["config"] === "string" ? options["config"] : undefined;
const config = loadConfigWithOverrides(configPath, cliOptions);

This is acceptable for now - the duplication is minimal (3-5 lines) and each command may evolve independently. If this pattern spreads to more commands, consider extracting a shared helper like loadConfigFromOptions().

Test Coverage for CLI (Acknowledged)

The PR notes that new CLI files have 0% test coverage, matching the previous lack of CLI testing. While this is being tracked in the "known limitations" section of the PR, consider adding CLI integration tests in a future PR to ensure:

• Commands parse options correctly
• Error handling works as expected
• State transitions work correctly for resume scenarios

CLAUDE.md Enhancement (Optional)

The "Code Navigation" section could mention the new src/cli/ structure and how to navigate commands, but this is a minor documentation enhancement rather than a requirement.

---

Architecture Review

4-Stage Pipeline: ✅ Not affected - stage logic remains unchanged, only CLI orchestration was refactored

Type Safety: ✅ Excellent - uses Zod schemas, proper type guards, no any types, runtime validation in formatters

Error Handling: ✅ Proper - all commands have try/catch with process.exit(1) on failure, consistent error logging

Configuration: ✅ Correct - uses loadConfigWithOverrides consistently across all commands

State Management: ✅ Proper - resume handlers correctly chain state updates (resume.ts:69-74)

Public API: ✅ Preserved - all public exports remain unchanged in src/index.ts

---

Specific Technical Highlights

Good Pattern: Resume Handler Map (src/cli/commands/resume.ts:240-247)

const resumeHandlers: Record<PipelineStage, ResumeHandler> = {
  pending: resumeFromAnalysis,
  analysis: resumeFromAnalysis,
  generation: resumeFromGeneration,
  execution: resumeFromExecution,
  evaluation: resumeFromEvaluation,
  complete: resumeFromEvaluation,
};

This replaces complex conditional logic with a clean lookup table, making the code more maintainable.

Good Pattern: Command Registration (src/cli/commands/index.ts:18-34)
Grouped command registration makes the CLI structure clear and extensible. Pipeline commands and state management commands are logically separated.

Good Pattern: Option Extraction (src/cli/options.ts:35-66)
Centralized validation with clear error messages for invalid stage names. Type guards ensure type safety.

Good Pattern: Runtime Validation (src/cli/formatters.ts:66-77)
Runtime type validation in formatters prevents runtime errors when processing evaluation results:

const scenarioId = typeof result["scenario_id"] === "string" 
  ? result["scenario_id"] 
  : "unknown";

Good Pattern: Commander v13+ Features (src/cli/commands/run.ts:48-77)
Uses modern Commander features like .optionsGroup() for better help text organization and dual long flag aliases (--dr, --dry-run).

---

Edge Cases Verified

✅ Option parsing: Handles undefined, null, and wrong-type options gracefully
✅ Error handling: All commands properly catch errors and exit with status 1
✅ State loading: Resume command handles missing state files and searches for run IDs
✅ XML/TAP output: Runtime validation prevents injection in JUnit XML and TAP formats
✅ Path handling: Uses existing getResultsDir() and findPluginByRunId() utilities

---

No Security Issues Found

• No command injection vulnerabilities (uses proper path utilities)
• No XSS vulnerabilities in XML output (uses proper encoding)
• No unsafe file operations (uses existing file-io utilities)
• No unvalidated user input passed to dangerous operations

---

Summary

This refactoring achieves its goal of making the codebase more navigable and maintainable. The 1,154-line src/index.ts is now a clean 37-line entry point with well-organized supporting modules. The implementation is high quality with:

• ✅ No behavioral changes
• ✅ Proper typing (zero any types)
• ✅ Zero test regressions (all 1,499 tests pass)
• ✅ Consistent patterns across all commands
• ✅ Good documentation updates
• ✅ Clean architecture with proper separation of concerns

Recommendation: Approve and merge. The known limitations (CLI test coverage, minor duplication) are acceptable and don't block this improvement. This is a significant quality-of-life improvement for future development.

---