Refactoring Opportunity

Summary

• File: src/cli.ts
• Current size: 2,444 lines
• Responsibilities identified: 4+ distinct concerns

Evidence

The file mixes validation utilities, configuration logic, and command orchestration:

1. Domain/IP parsing utilities (lines 41–204): parseDomains, parseDomainsFile, isValidIPv4, isValidIPv6, validateAgentImage, processAgentImageOption — pure utilities with no CLI dependency.

2. API proxy configuration and validation (lines 256–569): validateApiProxyConfig, validateAnthropicCacheTailTtl, validateApiTargetInAllowedDomains, emitApiProxyTargetWarnings, emitCliProxyStatusLogs, warnClassicPATWithCopilotModel, extractGhecDomainsFromServerUrl, extractGhesDomainsFromEngineApiTarget, resolveApiTargetsToAllowedDomains — a cohesive group with no direct Commander dependency.

3. Input parsing helpers (lines 659–1230): buildRateLimitConfig, validateRateLimitFlags, parseMemoryLimit, parseAgentTimeout, parseDnsServers, parseDnsOverHttps, parseEnvironmentVariables, parseVolumeMounts, validateAllowHostPorts, validateAllowHostServicePorts, applyHostServicePortsConfig, escapeShellArg, joinShellArgs.

4. CLI program definition and action handlers (lines 1231–2444): Commander program setup, all .option() definitions, the main .action() handler (~640 lines), and subcommands (logs stats, logs summary, predownload).

Proposed Split

src/cli.ts (2,444 lines) could be split into:

• src/domain-utils.ts — domain/IP parsing and agent image validation (~170 lines)
• src/api-proxy-config.ts — API proxy validation, domain resolution, warnings (~320 lines)
• src/option-parsers.ts — rate limit, memory, timeout, DNS, env-var, volume-mount, port parsers (~580 lines)
• src/cli.ts — Commander program, option definitions, action handlers only (~900 lines)

Note: src/domain-patterns.ts and src/domain-patterns.test.ts already exist — the domain utilities above are a different, CLI-focused layer.

Affected Callers

grep -rn "from.*['\"]\.\/cli['\"]" src/ 2>/dev/null

Currently most consumers go through src/cli.ts directly; after splitting they would import from the relevant focused module.

Effort Estimate

Medium — many exported symbols but low interdependency between the groups.

Benefits

• Main action handler (currently ~640 lines) shrinks to a readable orchestration layer
• Validation logic becomes independently testable (some is already tested in src/cli.test.ts)
• Easier onboarding: contributors can find domain handling vs. proxy config vs. CLI wiring separately

Detected by Refactoring Scanner workflow. Run date: 2026-05-04

Generated by Refactoring Opportunity Scanner · ● 233.7K · ◷

• expires on Jul 3, 2026, 6:39 AM UTC