SubMiner/backlog/tasks/task-81 - Refactor-launcher-into-command-modules-and-process-adapters.md

id, title, status, assignee, created_date, updated_date, labels, dependencies, priority, ordinal

id	title	status	assignee	created_date	updated_date	labels	dependencies	priority	ordinal
TASK-81	Refactor launcher into command modules and process adapters	Done	opencode-task81-launcher-modules	2026-02-18 11:43	2026-02-22 07:49	launcher cli architecture	TASK-70 TASK-73 TASK-74	medium	74000

Description

Launcher code is still large and process-control heavy (launcher/main.ts, launcher/mpv.ts, launcher/config.ts). This task refactors launcher flows into command modules plus explicit process adapters to reduce branching complexity and improve testability.

Suggestions

• Split by command domain (doctor, config, mpv, jellyfin, play).
• Isolate shell/process invocations behind adapter interfaces.
• Keep argv parsing independent from command execution side effects.

Action Steps

1. Define launcher command dispatcher and command handler interfaces.
2. Extract command handlers from launcher/main.ts.
3. Move spawn/fs/net operations into process + platform adapter modules.
4. Keep CLI UX and exit-code behavior stable.
5. Add unit tests per command module with mocked adapters.
6. Update launcher docs for module structure and extension guidance.

Acceptance Criteria

• #1 Launcher commands are implemented as focused modules
• #2 Process side effects are isolated behind adapter interfaces
• #3 Existing CLI behavior and exit codes remain compatible
• #4 Launcher testability improves via mocked adapter tests

Implementation Plan

1. Add launcher/process-adapter.ts and launcher/commands/context.ts so command handlers receive a shared context and explicit process/stdout/signal/exit seam instead of hardcoding process.* calls.
2. Extract early-return command branches from launcher/main.ts into focused modules under launcher/commands/ (config, doctor, mpv, app, texthooker) while preserving existing outputs and exit-code behavior.
3. Extract jellyfin and default playback orchestration into dedicated command modules so launcher/main.ts becomes thin command dispatch + lifecycle wiring.
4. Add adapter-mocked command tests (launcher/commands/command-modules.test.ts) and keep integration regressions in launcher/main.test.ts to prove behavior parity.
5. Wire new command test file into launcher/core source test scripts, run required gates (bun run test:launcher, bun run test:core:src), then finalize TASK-81 notes/AC/DoD without commit.

Implementation Notes

Planning complete. Detailed execution plan saved at docs/plans/2026-02-22-task-81-launcher-command-modules-process-adapters.md. Proceeding directly per user request to execute via writing-plans + executing-plans flow without commit.

Implemented launcher refactor by extracting command handlers into launcher/commands/* (config, doctor, mpv, app, jellyfin, playback) and converting launcher/main.ts into thin context+dispatch orchestration.

Added explicit process side-effect seam in launcher/process-adapter.ts and routed command output/exit/signal behavior through adapter-aware command modules.

Added mocked-adapter regression tests in launcher/commands/command-modules.test.ts and wired that file into test:launcher:src + test:core:src scripts.

Verification: bun test launcher/commands/command-modules.test.ts launcher/main.test.ts launcher/parse-args.test.ts and bun run test:launcher && bun run test:core:src all passing.

Final Summary

Refactored launcher command branching into focused command modules and introduced a dedicated process adapter interface to isolate output/exit/signal side effects from orchestration code. Preserved existing CLI behavior by keeping helper flows intact, added adapter-mocked command tests, and validated compatibility with full launcher and core source test gates.

Definition of Done

• #1 Launcher tests and core test gate pass
• #2 No regression in wrapper command behavior