SubMiner/backlog/tasks/task-238.2 - Extract-CLI-and-headless-command-wiring-from-src-main.ts.md

id, title, status, assignee, created_date, labels, milestone, dependencies, references, parent_task_id, priority

id	title	status	assignee	created_date	labels	milestone	dependencies	references	parent_task_id	priority
TASK-238.2	Extract CLI and headless command wiring from src/main.ts	Done		2026-03-26 20:49	tech-debt cli runtime maintainability	m-0	TASK-238.1	src/main.ts src/main/cli-runtime.ts src/cli/args.ts launcher	TASK-238	high

Description

src/main.ts still owns the headless-initial-command flow, argument handling, and a large amount of CLI/runtime bridging. That makes non-window startup paths difficult to reason about and keeps CLI behavior coupled to unrelated desktop boot logic. Extract the remaining CLI/headless orchestration into dedicated runtime services so the main entrypoint only decides which startup path to invoke.

Acceptance Criteria

• #1 CLI parsing, initial-command dispatch, and headless command execution no longer live as large inline flows in src/main.ts.
• #2 The new modules make the desktop startup path and headless startup path visibly separate and easier to test.
• #3 Existing CLI behaviors remain unchanged, including help output and startup gating behavior.
• #4 Targeted CLI/runtime tests cover the extracted path, and bun run typecheck passes.

Implementation Plan

1. Map the current parseArgs / handleInitialArgs / runHeadlessInitialCommand / handleCliCommand flow in src/main.ts.
2. Extract a small startup-path selector plus dedicated runtime services for headless execution and interactive startup dispatch.
3. Keep Electron app ownership in src/main.ts; move only CLI orchestration and context assembly.
4. Verify with CLI-focused tests plus bun run typecheck.

Completion Notes

• CLI and headless startup wiring now lives behind src/main/runtime/composers/cli-startup-composer.ts, src/main/runtime/cli-command-runtime-handler.ts, src/main/runtime/initial-args-handler.ts, and src/main/runtime/composers/headless-startup-composer.ts.
• src/main.ts now passes CLI/context dependencies into those runtime surfaces instead of holding the full orchestration inline.
• Verification:
  • bun test src/main/runtime/composers/cli-startup-composer.test.ts src/main/runtime/initial-args-handler.test.ts src/main/runtime/cli-command-runtime-handler.test.ts
  • bun run typecheck failed on unrelated existing errors in src/core/services/immersion-tracker/lifetime.ts, src/core/services/immersion-tracker/maintenance.ts, and src/core/services/stats-server.ts