Use learnings and implementation from issues 289 and 304 to add a --json flag to 'cleanup' and 'finish' commands

[acreeger]

Make sure the analysis includes all called modules that will require an optional logger to be passed in order to pass through the stdErrLogger to all modules in the code paths - for that reason, make this a complex task

[acreeger]

Enhancement Request Analysis

Questions for Reporter

Question	Answer
Should logger propagation follow the same constructor injection pattern from issue #304 (logger as optional parameter defaulting to defaultLogger)?	Assumption: Yes - this is the established pattern
Should cleanup and finish commands return result objects similar to StartResult? If so, what fields should they include?	Assumption: Yes - CleanupResult and FinishResult should include: success (boolean), operations (array of operation details), and relevant identifiers
Should interactive prompts in cleanup/finish be handled the same way as start command in JSON mode (error with clear message requiring explicit flags)?	Assumption: Yes - consistency across commands

Problem Summary
The cleanup and finish commands need a --json flag to output machine-readable results, following the pattern established in issues #289 and #304 for the start, add-issue, and enhance commands.

User Impact
Developers and CI/CD automation tools need programmatic access to cleanup and finish command output. Currently, all logging goes to stdout, making it impossible to parse results in automated workflows. This prevents full automation of the iloom workflow from start to finish.

Enhancement Goal
Add a --json flag to the cleanup and finish commands that redirects all progress logging to stderr and outputs a structured JSON result to stdout. This requires passing an optional logger through all modules in the code paths to ensure no logging pollutes stdout in JSON mode.

Next Steps

• Reporter to confirm assumptions about result object structure and error handling patterns
• Technical analysis to trace complete logger propagation paths through all affected modules
• Implementation following the bottom-up approach established in issue Add new --json flag to start simlar to the one recently added to enhance and add-issue in 023e98 #304

---

📋 Complete Context & Details (click to expand)

Pattern to Follow (from issues #289 and #304)

The implementation should follow the proven pattern from commit 023e98 and the start command:

1. Add json flag to CleanupOptions and FinishOptions interfaces (types/index.ts)
2. Create CleanupResult and FinishResult interfaces with relevant output fields (types/index.ts)
3. Update CleanupCommand.execute() and FinishCommand.execute() to:
   • Accept a logger instance parameter for stderr redirection in JSON mode
   • Skip interactive prompts in JSON mode (error with clear message requiring explicit flags)
   • Return a result object instead of void
4. Update cli.ts to:
   • Create stderr logger when --json flag is present
   • Pass logger to command constructors
   • Print JSON result to stdout on success
   • Use JSON.stringify with proper formatting

Key Challenge: Cross-Cutting Logger Propagation

Based on the learnings from issue #304, the main complexity is ensuring ALL logging is redirected from stdout to stderr in JSON mode. This requires passing the logger through all modules in the code paths:

Cleanup Command Code Path:

• CleanupCommand
• GitWorktreeManager (3 logger calls)
• ResourceCleanup (29 logger calls)
• ProcessManager
• DatabaseManager (25 logger calls)
• EnvironmentManager (10 logger calls)
• CLIIsolationManager (14 logger calls)
• SettingsManager (13 logger calls)
• LoomManager (53 logger calls) - used for child loom detection
• LoomLauncher (10 logger calls)
• MetadataManager (8 logger calls)
• BranchNamingService (1 logger call)
• IdentifierParser

Finish Command Code Path:

• FinishCommand
• GitWorktreeManager (3 logger calls)
• ValidationRunner (23 logger calls)
• CommitManager (27 logger calls)
• MergeManager (26 logger calls)
• ResourceCleanup (29 logger calls)
• ProcessManager
• BuildRunner (6 logger calls)
• DatabaseManager (25 logger calls)
• EnvironmentManager (10 logger calls)
• CLIIsolationManager (14 logger calls)
• SettingsManager (13 logger calls)
• PRManager (7 logger calls)
• LoomManager (53 logger calls)
• ClaudeContextManager (1 logger call)
• ProjectCapabilityDetector
• BranchNamingService (1 logger call)
• LoomLauncher (10 logger calls)
• MetadataManager (8 logger calls)
• IdentifierParser

Modules Requiring Logger Injection (Conservative Estimate)

Many of these modules were already modified in issue #304, but some are unique to cleanup/finish:

New Modules (not in start command path):

• ValidationRunner (23 logger calls)
• CommitManager (27 logger calls)
• MergeManager (26 logger calls)
• ResourceCleanup (29 logger calls)
• BuildRunner (6 logger calls)
• PRManager (7 logger calls)
• ProcessManager (0 direct logger calls, but may log through dependencies)

Already Modified in #304:

• LoomManager
• LoomLauncher
• EnvironmentManager
• DatabaseManager
• CLIIsolationManager
• MetadataManager
• BranchNamingService
• SettingsManager (optional - only debug logs)

Implementation Pattern from Issue #304

Each module should:

1. Accept optional logger in constructor: constructor(..., logger?: Logger)
2. Store as instance property: private logger: Logger
3. Default to existing logger: this.logger = logger ?? defaultLogger or this.logger = logger ?? createLogger({ prefix: '...' })
4. Replace all logger.xxx calls with this.logger.xxx
5. Propagate logger to dependencies created in the module

Interactive Prompts to Handle

Cleanup Command:

• Child loom confirmation (handled by LoomManager.checkAndWarnChildLooms)
• Worktree removal confirmation (skip in JSON mode with --force flag required)
• Branch deletion confirmation (skip in JSON mode with --force flag required)

Finish Command:

• Child loom confirmation (handled by LoomManager.checkAndWarnChildLooms)
• Commit message prompt (error in JSON mode - uncommitted changes require pre-commit)
• PR cleanup prompt after GitHub PR creation (error in JSON mode - require explicit --cleanup or --no-cleanup flag)
• Closed issue force confirmation (error in JSON mode - require explicit --force flag)

Expected Result Object Structures

CleanupResult Interface (already exists in types/cleanup.ts):

export interface CleanupResult {
  success: boolean
  operations: Array<{
    type: 'worktree' | 'branch' | 'database' | 'symlink' | 'processes'
    message: string
    success: boolean
    error?: string
    deleted?: boolean
  }>
  errors: string[]
}

FinishResult Interface (new - to be created):

export interface FinishResult {
  success: boolean
  type: 'issue' | 'pr' | 'branch'
  identifier: string | number
  operations: Array<{
    type: 'validation' | 'commit' | 'rebase' | 'merge' | 'cleanup' | 'pr-creation' | 'build'
    message: string
    success: boolean
    error?: string
  }>
  prUrl?: string // For github-pr workflow
  cleanupResult?: CleanupResult // For cleanup phase
}

Files to Modify

Primary Changes:

• src/types/index.ts - Add json flags to CleanupOptions and FinishOptions, create FinishResult interface
• src/commands/cleanup.ts - Add logger property, constructor param, JSON mode handling, return CleanupResult
• src/commands/finish.ts - Add logger property, constructor param, JSON mode handling, return FinishResult
• src/cli.ts - Handle --json flag for cleanup and finish commands, create stderr logger, print JSON output

Secondary Changes (logger propagation - NEW modules not in #304):

• src/lib/ValidationRunner.ts - Add optional logger constructor param
• src/lib/CommitManager.ts - Add optional logger constructor param
• src/lib/MergeManager.ts - Add optional logger constructor param
• src/lib/ResourceCleanup.ts - Add optional logger constructor param
• src/lib/BuildRunner.ts - Add optional logger constructor param
• src/lib/PRManager.ts - Add optional logger constructor param
• src/lib/ProcessManager.ts - Add optional logger constructor param (if needed)

Test Updates Required:

• src/commands/cleanup.test.ts - Update constructor calls, add JSON mode tests
• src/commands/finish.test.ts - Update constructor calls, add JSON mode tests

Implementation Order (Bottom-Up)

Following the proven approach from issue #304:

1. Phase 1: New utility modules (not already modified in Add new --json flag to start simlar to the one recently added to enhance and add-issue in 023e98 #304)

   • ValidationRunner
   • CommitManager
   • MergeManager
   • ResourceCleanup
   • BuildRunner
   • PRManager
   • ProcessManager

2. Phase 2: CleanupCommand

   • Add logger property, constructor param
   • Add JSON mode checks for interactive prompts
   • Return CleanupResult when JSON mode

3. Phase 3: FinishCommand

   • Add logger property, constructor param
   • Add JSON mode checks for interactive prompts
   • Return FinishResult when JSON mode

4. Phase 4: cli.ts entry points

   • Handle --json flag for cleanup command
   • Handle --json flag for finish command
   • Create stderr logger, pass to commands
   • Print JSON results to stdout

5. Phase 5: Tests and build

   • Update test files
   • Run pnpm build
   • Run pnpm test

Critical Implementation Note

This is a complex, cross-cutting change affecting 15+ modules (7 new + 8 already modified in #304). Each module must accept optional logger parameter and fall back to default logger. Missing any module in this chain will cause logging to go to stdout, polluting JSON output. The issue explicitly requests treating this as a complex task with focus on passing optional logger through all modules.

Related Context

• Issue Add new --json flag to start simlar to the one recently added to enhance and add-issue in 023e98 #304 implementation provides the proven pattern for logger injection
• Issue Vitest worker processes become orphaned and consume >2GB RAM each #289 established the stderr logger approach and identified the importance of complete stdout isolation
• createStderrLogger() utility already exists at src/utils/logger.ts
• CleanupResult interface already exists at src/types/cleanup.ts

[acreeger]

Complexity Assessment

Classification: COMPLEX

Metrics:

• Estimated files affected: 11 (9 primary modules + 2 command files + CLI entry point)
• Estimated lines of code: 1100-1400 (logger parameter + optional handling across 9 large modules)
• Breaking changes: No
• Database migrations: No
• Cross-cutting changes: Yes - CRITICAL
• File architecture quality: Poor - Multiple large files (finish.ts: 1140 LOC, cleanup.ts: 552 LOC) with complex responsibilities
• Overall risk level: High

Reasoning: This issue exemplifies a complex cross-cutting change. While appearing simple ("add --json flag"), it requires passing an optional logger parameter through a chain of 9+ interdependent modules across two different code paths (cleanup and finish). The issue explicitly identifies this as complex with focus on "passing optional logger through all modules in code paths." Multiple modules exceed 500 LOC (finish: 1140, ResourceCleanup: 793, cli.ts: 1169) requiring modifications in deeply nested class structures. Missing logger injection in any module causes stdout pollution, making this a high-risk, coordinatively complex task despite moderate LOC changes.

[acreeger]

Analysis Phase

• Review existing --json implementation from issue Add new --json flag to start simlar to the one recently added to enhance and add-issue in 023e98 #304 (start command)
• Trace cleanup command code path and identify all modules requiring logger injection
• Trace finish command code path and identify all modules requiring logger injection
• Identify modules already modified in Add new --json flag to start simlar to the one recently added to enhance and add-issue in 023e98 #304 vs new modules requiring changes
• Document all console.log/warn/error calls that need stderr redirection
• Cross-cutting architectural flow analysis
• Document findings

Status: Analysis complete

---

Executive Summary

Adding --json flag to cleanup and finish commands requires propagating an optional logger through 9 modules that were NOT modified in issue #304, in addition to properly wiring up the 7 modules that were already modified. The cleanup command has 34 logger calls and finish has 89 logger calls that must be redirected to stderr in JSON mode.

Question	Answer
Should new modules (ValidationRunner, CommitManager, etc.) follow the same constructor injection pattern from #304?	Yes - constructor(..., logger?: Logger) with this.logger = logger ?? defaultLogger
Should CleanupResult and FinishResult interfaces be created for JSON output?	CleanupResult already exists in types/cleanup.ts. FinishResult needs to be created in types/index.ts
Should interactive prompts in cleanup/finish be handled the same as start command?	Yes - error with clear message requiring explicit flags (e.g., --force, --cleanup/--no-cleanup)

HIGH/CRITICAL Risks

• Cross-cutting logger propagation across 16 modules: Missing any module causes logging to go to stdout, polluting JSON output. This is a coordinated change where partial implementation will fail silently.

Impact Summary

• 2 command files (cleanup.ts, finish.ts) require logger property + constructor param + JSON mode handling
• 9 NEW modules need logger injection (not modified in Add new --json flag to start simlar to the one recently added to enhance and add-issue in 023e98 #304): ValidationRunner, CommitManager, MergeManager, ResourceCleanup, BuildRunner, PRManager, ProcessManager, SettingsManager (in finish path), GitWorktreeManager
• 7 modules already have logger injection from Add new --json flag to start simlar to the one recently added to enhance and add-issue in 023e98 #304 but need wiring: LoomManager, EnvironmentManager, DatabaseManager, CLIIsolationManager, MetadataManager, BranchNamingService, LoomLauncher
• 2 type additions: json?: boolean to CleanupOptions and FinishOptions, new FinishResult interface
• cli.ts needs --json option for cleanup and finish commands with createStderrLogger() pattern
• ~247 total logger calls across affected modules need instance-based routing

---

Complete Technical Reference (click to expand for implementation details)

Problem Space Research

Problem Understanding

The cleanup and finish commands need machine-readable output for CI/CD automation and tooling integration. Currently all progress logging goes to stdout, making it impossible to parse results programmatically. This enables full automation of the iloom workflow from start to finish.

Architectural Context

This follows the established --json flag pattern from commit 95a7d57 (issue #304):

1. Create stderr logger when --json flag present: createStderrLogger()
2. Pass logger through constructor to command and dependent services
3. Skip interactive prompts in JSON mode (error with clear message)
4. Return structured result object
5. cli.ts prints JSON to stdout

Edge Cases Identified

• Interactive prompts in cleanup: worktree removal confirmation, branch deletion confirmation
• Interactive prompts in finish: commit message prompt, PR cleanup prompt, closed issue force confirmation
• Child loom confirmation handled by LoomManager.checkAndWarnChildLooms
• Dry-run mode messaging

Architectural Flow Analysis

Data Flow: logger parameter (CleanupCommand)

Entry Point: /Users/adam/Documents/Projects/iloom-cli/feat-issue-306__add-json-flag/src/cli.ts:569-585 - cleanup command action

Flow Path:

1. cli.ts:569-585 - CLI action creates stderr logger if --json, passes to CleanupCommand constructor
2. CleanupCommand constructor stores logger as this.logger
3. CleanupCommand.ensureResourceCleanup() creates ResourceCleanup - must pass logger
4. CleanupCommand.ensureResourceCleanup() creates LoomManager - must pass logger
5. ResourceCleanup uses: GitWorktreeManager, ProcessManager, DatabaseManager, CLIIsolationManager - all must receive logger
6. LoomManager uses: GitWorktreeManager, EnvironmentManager, CLIIsolationManager, MetadataManager, BranchNamingService, DatabaseManager, LoomLauncher - all must receive logger

Affected Interfaces (ALL must be updated for cleanup path):

• CleanupCommand at cleanup.ts - Add logger property and constructor param
• ResourceCleanup at ResourceCleanup.ts:29-38 - Add logger constructor param
• GitWorktreeManager at GitWorktreeManager.ts - Add optional logger constructor param
• ProcessManager at process/ProcessManager.ts - Add optional logger constructor param (no direct logging, but for consistency)

Data Flow: logger parameter (FinishCommand)

Entry Point: /Users/adam/Documents/Projects/iloom-cli/feat-issue-306__add-json-flag/src/cli.ts:452-463 - finish command action

Flow Path:

1. cli.ts:452-463 - CLI action creates stderr logger if --json, passes to FinishCommand constructor
2. FinishCommand constructor stores logger as this.logger
3. FinishCommand creates/uses: ValidationRunner, CommitManager, MergeManager, ResourceCleanup, BuildRunner, PRManager - all must receive logger
4. FinishCommand.ensureResourceCleanup() creates LoomManager - must pass logger
5. Each sub-manager may create additional dependencies that need logger

Affected Interfaces (ALL must be updated for finish path):

• FinishCommand at finish.ts:56-97 - Add logger property and constructor param
• ValidationRunner at ValidationRunner.ts - Add logger constructor param (24 logger calls)
• CommitManager at CommitManager.ts - Add logger constructor param (28 logger calls)
• MergeManager at MergeManager.ts - Add logger constructor param (27 logger calls)
• ResourceCleanup at ResourceCleanup.ts - Add logger constructor param (30 logger calls)
• BuildRunner at BuildRunner.ts - Add logger constructor param (7 logger calls)
• PRManager at PRManager.ts - Add logger constructor param (8 logger calls)

Critical Implementation Note: This is a cross-cutting change affecting 16 modules (9 new + 7 already modified in #304). Each module must accept optional logger parameter and fall back to default logger. Missing any module in this chain will cause logging to go to stdout, polluting JSON output.

Logger Call Counts by Module

NEW Modules (not in start command path, NOT modified in #304):

Module	File	Logger Calls	Notes
CleanupCommand	commands/cleanup.ts	34	Primary orchestrator - uses logger. directly
FinishCommand	commands/finish.ts	89	Primary orchestrator - uses logger. directly
ValidationRunner	lib/ValidationRunner.ts	24	Uses logger. directly
CommitManager	lib/CommitManager.ts	28	Uses logger. directly
MergeManager	lib/MergeManager.ts	27	Uses logger. directly
ResourceCleanup	lib/ResourceCleanup.ts	30	Uses logger. directly
BuildRunner	lib/BuildRunner.ts	7	Uses logger. directly
PRManager	lib/PRManager.ts	8	Uses logger. directly
GitWorktreeManager	lib/GitWorktreeManager.ts	3	Uses logger. directly

Already Modified in #304 (have logger constructor param):

Module	File	Logger Calls	Notes
LoomManager	lib/LoomManager.ts	53	Has this.logger property
EnvironmentManager	lib/EnvironmentManager.ts	10	Has this.logger property
DatabaseManager	lib/DatabaseManager.ts	25	Has this.logger property
CLIIsolationManager	lib/CLIIsolationManager.ts	14	Has this.logger property
MetadataManager	lib/MetadataManager.ts	8	Has this.logger property
BranchNamingService	lib/BranchNamingService.ts	1	Has this.logger property in DefaultBranchNamingService
LoomLauncher	lib/LoomLauncher.ts	10	Has this.logger property

Interactive Prompts to Handle

Cleanup Command:

• cleanup.ts:359 - Worktree removal confirmation (promptConfirmation)
• cleanup.ts:465-472 - Batch worktree removal confirmation
• Child loom confirmation via LoomManager.checkAndWarnChildLooms - already exits on true

JSON mode behavior: Require --force flag, error otherwise

Finish Command:

• finish.ts:92-96 - promptCommitAction in CommitManager for commit message review
• finish.ts:846-849 - PR cleanup prompt (promptConfirmation) after GitHub PR creation
• Child loom confirmation via LoomManager.checkAndWarnChildLooms - already exits on true

JSON mode behavior:

• Commit changes: Require explicit commit message or --no-review flag
• PR cleanup: Require explicit --cleanup or --no-cleanup flag
• Closed issue: Require --force flag

Expected Result Object Structures

CleanupResult Interface (already exists at types/cleanup.ts):

export interface CleanupResult {
  success: boolean
  operations: Array<{
    type: 'worktree' | 'branch' | 'database' | 'symlink' | 'processes'
    message: string
    success: boolean
    error?: string
    deleted?: boolean
  }>
  errors: string[]
}

FinishResult Interface (NEW - to be created at types/index.ts):

export interface FinishResult {
  success: boolean
  type: 'issue' | 'pr' | 'branch'
  identifier: string | number
  operations: Array<{
    type: 'validation' | 'commit' | 'rebase' | 'merge' | 'cleanup' | 'pr-creation' | 'build'
    message: string
    success: boolean
    error?: string
  }>
  prUrl?: string // For github-pr workflow
  cleanupResult?: CleanupResult // For cleanup phase
}

Files to Modify

Primary Changes (Types):

• /Users/adam/Documents/Projects/iloom-cli/feat-issue-306__add-json-flag/src/types/index.ts:189-200 - Add json?: boolean to CleanupOptions and FinishOptions
• /Users/adam/Documents/Projects/iloom-cli/feat-issue-306__add-json-flag/src/types/index.ts:222-231 - Create FinishResult interface

Primary Changes (Commands):

• /Users/adam/Documents/Projects/iloom-cli/feat-issue-306__add-json-flag/src/commands/cleanup.ts:46-75 - Add logger property, constructor param, JSON mode handling
• /Users/adam/Documents/Projects/iloom-cli/feat-issue-306__add-json-flag/src/commands/finish.ts:44-97 - Add logger property, constructor param, JSON mode handling

Primary Changes (CLI Entry Points):

• /Users/adam/Documents/Projects/iloom-cli/feat-issue-306__add-json-flag/src/cli.ts:559-585 - Add --json option to cleanup command, create stderr logger, pass to command
• /Users/adam/Documents/Projects/iloom-cli/feat-issue-306__add-json-flag/src/cli.ts:441-463 - Add --json option to finish command, create stderr logger, pass to command

Secondary Changes (NEW modules - logger injection):

• /Users/adam/Documents/Projects/iloom-cli/feat-issue-306__add-json-flag/src/lib/ValidationRunner.ts:15-18 - Add optional logger constructor param
• /Users/adam/Documents/Projects/iloom-cli/feat-issue-306__add-json-flag/src/lib/CommitManager.ts:12 - Add optional logger constructor param
• /Users/adam/Documents/Projects/iloom-cli/feat-issue-306__add-json-flag/src/lib/MergeManager.ts:13-18 - Add optional logger constructor param
• /Users/adam/Documents/Projects/iloom-cli/feat-issue-306__add-json-flag/src/lib/ResourceCleanup.ts:25-38 - Add optional logger constructor param
• /Users/adam/Documents/Projects/iloom-cli/feat-issue-306__add-json-flag/src/lib/BuildRunner.ts:21-26 - Add optional logger constructor param
• /Users/adam/Documents/Projects/iloom-cli/feat-issue-306__add-json-flag/src/lib/PRManager.ts:19-20 - Add optional logger constructor param
• /Users/adam/Documents/Projects/iloom-cli/feat-issue-306__add-json-flag/src/lib/GitWorktreeManager.ts - Add optional logger constructor param

Wiring Changes (pass logger through to already-modified modules):

• CleanupCommand.ensureResourceCleanup() at cleanup.ts:80-120 - Pass logger to LoomManager, ResourceCleanup
• FinishCommand.ensureResourceCleanup() at finish.ts:102-136 - Pass logger to LoomManager, ResourceCleanup
• FinishCommand constructor at finish.ts:56-97 - Pass logger to ValidationRunner, CommitManager, MergeManager, BuildRunner

Implementation Order (Bottom-Up)

Following the proven approach from issue #304:

1. Phase 1: Types - Add json flag to CleanupOptions and FinishOptions, create FinishResult interface

2. Phase 2: NEW utility modules (no inter-dependencies)

   • ValidationRunner
   • CommitManager
   • MergeManager
   • ResourceCleanup
   • BuildRunner
   • PRManager
   • GitWorktreeManager (if needed)

3. Phase 3: CleanupCommand

   • Add logger property, constructor param
   • Replace all logger.xxx with this.logger.xxx
   • Add JSON mode checks for interactive prompts
   • Return CleanupResult when JSON mode
   • Wire logger to ResourceCleanup, LoomManager

4. Phase 4: FinishCommand

   • Add logger property, constructor param
   • Replace all logger.xxx with this.logger.xxx
   • Add JSON mode checks for interactive prompts
   • Return FinishResult when JSON mode
   • Wire logger to all sub-managers

5. Phase 5: cli.ts entry points

   • Handle --json flag for cleanup command (add option, create stderr logger, print JSON)
   • Handle --json flag for finish command (add option, create stderr logger, print JSON)

6. Phase 6: Tests and build

   • Update cleanup.test.ts for JSON mode
   • Update finish.test.ts for JSON mode
   • Run pnpm build
   • Run pnpm test

Medium Severity Risks

• Test updates required: All modules with logger injection will need test updates for mock logger
• API compatibility: Adding optional logger param to constructors should be backward compatible
• Interactive prompt handling: Need to identify all prompts and add appropriate JSON mode guards

Related Context

• Issue Add new --json flag to start simlar to the one recently added to enhance and add-issue in 023e98 #304 implementation (commit 95a7d57) provides the proven pattern for logger injection
• Issue Vitest worker processes become orphaned and consume >2GB RAM each #289 established the stderr logger approach
• createStderrLogger() utility at /Users/adam/Documents/Projects/iloom-cli/feat-issue-306__add-json-flag/src/utils/logger.ts:179-234
• CleanupResult interface at /Users/adam/Documents/Projects/iloom-cli/feat-issue-306__add-json-flag/src/types/cleanup.ts

[acreeger]

Implementation Plan for Issue #306

Summary

Add --json flag to cleanup and finish commands to output machine-readable JSON results for CI/CD automation. This requires propagating an optional logger through 8 NEW modules and properly wiring 7 modules already modified in issue #304. The pattern follows the established implementation from commit 95a7d57 (StartCommand).

Questions and Key Decisions

Question	Answer	Rationale
Should logger propagation follow the same constructor injection pattern from issue #304?	Yes - constructor(..., logger?: Logger) with this.logger = logger ?? defaultLogger	Established pattern, backward compatible
Should FinishResult interface be created for JSON output?	Yes - create in types/index.ts	CleanupResult already exists, FinishResult needed for parity
Should interactive prompts in cleanup/finish error in JSON mode?	Yes - require explicit flags (--force, --cleanup/--no-cleanup)	Consistency with start command behavior

High-Level Execution Phases

1. Phase 1: Types - Add json?: boolean to CleanupOptions/FinishOptions, create FinishResult interface
2. Phase 2: Utility Modules - Add logger injection to 8 NEW modules (ValidationRunner, CommitManager, MergeManager, ResourceCleanup, BuildRunner, PRManager, GitWorktreeManager, SettingsManager)
3. Phase 3: CleanupCommand - Add logger property, constructor param, replace logger calls with this.logger, JSON mode handling
4. Phase 4: FinishCommand - Add logger property, constructor param, replace logger calls with this.logger, JSON mode handling, wire logger to sub-managers
5. Phase 5: cli.ts Entry Points - Add --json option to cleanup/finish commands, create stderr logger, print JSON results
6. Phase 6: Tests - Update cleanup.test.ts and finish.test.ts for JSON mode scenarios

Quick Stats

• 0 files for deletion
• 12 files to modify
• 0 new files to create
• Dependencies: None
• Estimated complexity: Complex (cross-cutting change affecting 15 modules)

Potential Risks (HIGH/CRITICAL only)

• Cross-cutting logger propagation: Missing any module in the chain causes logging to pollute stdout in JSON mode. This is a coordinated change where partial implementation fails silently.

---

Complete Implementation Guide (click to expand for step-by-step details)

Automated Test Cases to Create

Test File: src/commands/cleanup.test.ts (MODIFY)

Purpose: Add JSON mode test coverage for CleanupCommand

Click to expand complete test structure (25 lines)

describe('JSON Mode', () => {
  it('should accept logger through constructor', () => {
    // Create mock logger, pass to CleanupCommand constructor
    // Verify command instantiates without error
  })

  it('should use injected logger for all output', async () => {
    // Create mock logger with vi.fn() for all methods
    // Pass to CleanupCommand constructor
    // Execute cleanup operation
    // Verify mock logger methods were called (not default logger)
  })

  it('should return CleanupResult when json option is true', async () => {
    // Execute with { json: true, force: true, identifier: 'test-branch' }
    // Verify return value is CleanupResult object
  })

  it('should require --force flag in JSON mode for confirmations', async () => {
    // Execute with { json: true } without --force
    // Verify error is thrown about requiring explicit flags
  })
})

Test File: src/commands/finish.test.ts (MODIFY)

Purpose: Add JSON mode test coverage for FinishCommand

Click to expand complete test structure (30 lines)

describe('JSON Mode', () => {
  it('should accept logger through constructor', () => {
    // Create mock logger, pass to FinishCommand constructor
    // Verify command instantiates without error
  })

  it('should use injected logger for all output', async () => {
    // Create mock logger with vi.fn() for all methods
    // Pass to FinishCommand constructor
    // Execute finish operation
    // Verify mock logger methods were called
  })

  it('should return FinishResult when json option is true', async () => {
    // Execute with { json: true } on a valid worktree
    // Verify return value is FinishResult object with expected fields
  })

  it('should require explicit --cleanup/--no-cleanup flag in JSON mode for github-pr workflow', async () => {
    // Configure settings for github-pr mode
    // Execute with { json: true } without cleanup flag
    // Verify error about requiring explicit flags
  })

  it('should wire logger through to all sub-managers', async () => {
    // Create mock logger, execute finish
    // Verify logger was passed to ValidationRunner, CommitManager, etc.
  })
})

Files to Modify

1. src/types/index.ts:189-200

Change: Add json?: boolean to CleanupOptions and FinishOptions interfaces

// Add to CleanupOptions (around line 199)
json?: boolean

// Add to FinishOptions (around line 183)
json?: boolean

2. src/types/index.ts:232+

Change: Create FinishResult interface after StartResult

Click to expand FinishResult interface (15 lines)

export interface FinishResult {
  success: boolean
  type: 'issue' | 'pr' | 'branch'
  identifier: string | number
  operations: Array<{
    type: 'validation' | 'commit' | 'rebase' | 'merge' | 'cleanup' | 'pr-creation' | 'build'
    message: string
    success: boolean
    error?: string
  }>
  prUrl?: string
  cleanupResult?: import('./cleanup.js').CleanupResult
}

3. src/lib/ValidationRunner.ts:1-16

Change: Add logger injection following established pattern

• Line 1: Change import { logger } to import { logger as defaultLogger, type Logger }
• Line 15: Add private logger: Logger property to class
• Add constructor with logger parameter and this.logger = logger ?? defaultLogger
• Replace all logger.xxx calls with this.logger.xxx (24 occurrences at lines 95, 106, 125, 134, 138, 193, 203, 221, 230, 234, 286, 296, 314, 324, 328, 383, 394, 406, 411, 415, 420)

4. src/lib/CommitManager.ts:1-12

Change: Add logger injection following established pattern

• Line 2: Change import { logger } to import { logger as defaultLogger, type Logger }
• Add private logger: Logger property to class (after line 12)
• Add constructor with logger parameter and this.logger = logger ?? defaultLogger
• Replace all logger.xxx calls with this.logger.xxx (28 occurrences)

5. src/lib/MergeManager.ts:1-18

Change: Add logger injection following established pattern

• Line 2: Change import { logger } to import { logger as defaultLogger, type Logger }
• Add private logger: Logger property after settingsManager (line 14)
• Update constructor (lines 16-18) to accept logger?: Logger and add this.logger = logger ?? defaultLogger
• Replace all logger.xxx calls with this.logger.xxx (27 occurrences)

6. src/lib/ResourceCleanup.ts:25-38

Change: Add logger injection following established pattern

• Line 8: Change import { logger } to import { logger as defaultLogger, type Logger }
• Add private logger: Logger property (around line 27)
• Update constructor (lines 29-38) to accept logger?: Logger parameter and add this.logger = logger ?? defaultLogger
• Replace all logger.xxx calls with this.logger.xxx (30 occurrences)

7. src/lib/BuildRunner.ts:1-26

Change: Add logger injection following established pattern

• Line 1: Change import { logger } to import { logger as defaultLogger, type Logger }
• Add private logger: Logger property (around line 22)
• Update constructor (lines 24-26) to accept logger?: Logger and add this.logger = logger ?? defaultLogger
• Replace all logger.xxx calls with this.logger.xxx (7 occurrences)

8. src/lib/PRManager.ts:1-20

Change: Add logger injection following established pattern

• Line 5: Change import { logger } to import { logger as defaultLogger, type Logger }
• Add private logger: Logger property (around line 19)
• Update constructor (line 20) to accept logger?: Logger and add this.logger = logger ?? defaultLogger
• Replace all logger.xxx calls with this.logger.xxx (8 occurrences)

9. src/lib/GitWorktreeManager.ts:29-35

Change: Add logger injection following established pattern

Note: GitWorktreeManager currently has dynamic imports for logger (line 159). Convert to constructor injection.

• Add import at top: import { logger as defaultLogger, type Logger } from '../utils/logger.js'
• Add private logger: Logger property (around line 31)
• Update constructor (lines 33-35) to accept logger?: Logger and add this.logger = logger ?? defaultLogger
• Lines 159-164: Remove dynamic import and use this.logger instead of logger

10. src/commands/cleanup.ts:1-75

Change: Add logger property, constructor param, JSON mode handling

• Line 1: Change import { logger } to import { logger as defaultLogger, type Logger }
• Add private logger: Logger property (around line 50)
• Update constructor (lines 52-55) to accept logger?: Logger and add this.logger = logger ?? defaultLogger
• Replace all logger.xxx calls with this.logger.xxx (34 occurrences)
• Line 163: Update execute() signature to return Promise<CleanupResult | void>
• Add JSON mode check: if json and not force for confirmations, throw error requiring --force
• Return CleanupResult when input.options.json === true
• In ensureResourceCleanup() (lines 80-120): Pass this.logger to EnvironmentManager, DatabaseManager, CLIIsolationManager, ResourceCleanup, LoomManager constructors

11. src/commands/finish.ts:1-97

Change: Add logger property, constructor param, JSON mode handling

• Line 1: Change import { logger } to import { logger as defaultLogger, type Logger }
• Add import for FinishResult from types/index.js (line 26)
• Add private logger: Logger property (around line 55)
• Update constructor (lines 56-97) to accept logger?: Logger and add this.logger = logger ?? defaultLogger
• Replace all logger.xxx calls with this.logger.xxx (89 occurrences)
• Line 187: Update execute() signature to return Promise<FinishResult | void>
• Add JSON mode checks for interactive prompts (commit prompt, cleanup prompt)
• Return FinishResult when input.options.json === true
• In constructor: Pass logger to ValidationRunner, CommitManager, MergeManager, BuildRunner constructors
• In ensureResourceCleanup() (lines 102-136): Pass this.logger to EnvironmentManager, DatabaseManager, CLIIsolationManager, ResourceCleanup, LoomManager, PRManager

12. src/cli.ts:558-585

Change: Add --json option to cleanup command, handle JSON output

• Line 568: Add .option('--json', 'Output result as JSON')
• Lines 569-585: Update action to:
  • Create stderr logger when --json: const jsonLogger = options?.json ? createStderrLogger() : undefined
  • Pass logger to CleanupCommand constructor: new CleanupCommand(undefined, undefined, jsonLogger)
  • Capture result from execute: const result = await command.execute(input)
  • Print JSON to stdout: if (options?.json && result) { console.log(JSON.stringify(result, null, 2)) }

13. src/cli.ts:440-463

Change: Add --json option to finish command, handle JSON output

• Line 451: Add .option('--json', 'Output result as JSON')
• Lines 452-463: Update action to:
  • Create stderr logger when --json: const jsonLogger = options.json ? createStderrLogger() : undefined
  • Pass logger to FinishCommand constructor: new FinishCommand(issueTracker, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, jsonLogger)
  • Capture result from execute: const result = await command.execute({ identifier, options })
  • Print JSON to stdout: if (options.json && result) { console.log(JSON.stringify(result, null, 2)) }

Detailed Execution Order

Phase 1: Types

1. Add json?: boolean to CleanupOptions interface in types/index.ts:199 -> Verify: TypeScript compiles
2. Add json?: boolean to FinishOptions interface in types/index.ts:183 -> Verify: TypeScript compiles
3. Create FinishResult interface in types/index.ts:232+ -> Verify: TypeScript compiles

Phase 2: Utility Modules (logger injection)

1. Update ValidationRunner.ts with logger injection -> Verify: pnpm build succeeds
2. Update CommitManager.ts with logger injection -> Verify: pnpm build succeeds
3. Update MergeManager.ts with logger injection -> Verify: pnpm build succeeds
4. Update ResourceCleanup.ts with logger injection -> Verify: pnpm build succeeds
5. Update BuildRunner.ts with logger injection -> Verify: pnpm build succeeds
6. Update PRManager.ts with logger injection -> Verify: pnpm build succeeds
7. Update GitWorktreeManager.ts with logger injection -> Verify: pnpm build succeeds

Phase 3: CleanupCommand

1. Add logger property and constructor param to cleanup.ts -> Verify: TypeScript compiles
2. Replace all logger.xxx with this.logger.xxx in cleanup.ts -> Verify: pnpm build succeeds
3. Update execute() return type to Promise<CleanupResult | void> -> Verify: TypeScript compiles
4. Add JSON mode validation (require --force flag) -> Verify: pnpm build succeeds
5. Wire logger to ResourceCleanup and LoomManager in ensureResourceCleanup() -> Verify: pnpm build succeeds
6. Return CleanupResult when json option is true -> Verify: pnpm build succeeds

Phase 4: FinishCommand

1. Add logger property and constructor param to finish.ts -> Verify: TypeScript compiles
2. Replace all logger.xxx with this.logger.xxx in finish.ts -> Verify: pnpm build succeeds
3. Update execute() return type to Promise<FinishResult | void> -> Verify: TypeScript compiles
4. Add JSON mode validation (require explicit flags) -> Verify: pnpm build succeeds
5. Wire logger to all sub-managers in constructor and ensureResourceCleanup() -> Verify: pnpm build succeeds
6. Return FinishResult when json option is true -> Verify: pnpm build succeeds

Phase 5: cli.ts Entry Points

1. Add --json option to cleanup command in cli.ts:558-585 -> Verify: pnpm build succeeds
2. Add --json option to finish command in cli.ts:440-463 -> Verify: pnpm build succeeds
3. Update cleanup action to create stderr logger and handle JSON output -> Verify: Manual test
4. Update finish action to create stderr logger and handle JSON output -> Verify: Manual test

Phase 6: Tests

1. Add JSON mode tests to cleanup.test.ts -> Verify: pnpm test passes
2. Add JSON mode tests to finish.test.ts -> Verify: pnpm test passes
3. Run full test suite -> Verify: pnpm test passes
4. Run build -> Verify: pnpm build succeeds

Dependencies and Configuration

None - all dependencies already exist in the codebase.

Logger Call Counts by Module

Module	File	Logger Calls	Status
CleanupCommand	commands/cleanup.ts	34	NEW - needs injection
FinishCommand	commands/finish.ts	89	NEW - needs injection
ValidationRunner	lib/ValidationRunner.ts	24	NEW - needs injection
CommitManager	lib/CommitManager.ts	28	NEW - needs injection
MergeManager	lib/MergeManager.ts	27	NEW - needs injection
ResourceCleanup	lib/ResourceCleanup.ts	30	NEW - needs injection
BuildRunner	lib/BuildRunner.ts	7	NEW - needs injection
PRManager	lib/PRManager.ts	8	NEW - needs injection
GitWorktreeManager	lib/GitWorktreeManager.ts	3	NEW - needs injection
ProcessManager	lib/process/ProcessManager.ts	0	No logger calls - skip
LoomManager	lib/LoomManager.ts	53	Already has logger (wire it)
EnvironmentManager	lib/EnvironmentManager.ts	10	Already has logger (wire it)
DatabaseManager	lib/DatabaseManager.ts	25	Already has logger (wire it)
CLIIsolationManager	lib/CLIIsolationManager.ts	14	Already has logger (wire it)
MetadataManager	lib/MetadataManager.ts	8	Already has logger (wire it)
BranchNamingService	lib/BranchNamingService.ts	1	Already has logger (wire it)
LoomLauncher	lib/LoomLauncher.ts	10	Already has logger (wire it)

Total: ~247 logger calls need instance-based routing across 15 active modules

[acreeger]

Implementation Complete - Issue #306

Summary

Added --json flag to cleanup and finish commands for programmatic output, following the established pattern from issue #304. All logging in JSON mode redirects to stderr with structured JSON results to stdout.

Changes Made

• src/types/index.ts: Added json?: boolean to CleanupOptions and FinishOptions, created FinishResult interface
• 7 utility modules: Added logger injection (ValidationRunner, CommitManager, MergeManager, ResourceCleanup, BuildRunner, PRManager, GitWorktreeManager)
• src/commands/cleanup.ts: Added logger property, JSON mode validation requiring --force flag, returns CleanupResult
• src/commands/finish.ts: Added logger property, JSON mode validation for github-pr workflow requiring --cleanup flag
• src/cli.ts: Added --json options for cleanup and finish commands with stderr logger and JSON output

Validation Results

• Tests: 2751 passed / 2752 total (1 skipped)
• Typecheck: Passed
• Lint: Passed

---

Detailed Changes by File (click to expand)

Files Modified

src/types/index.ts

Changes: Added json?: boolean to CleanupOptions and FinishOptions interfaces, created FinishResult interface with operations array

src/lib/ValidationRunner.ts

Changes: Added logger constructor param with this.logger instance property, replaced 24 logger calls

src/lib/CommitManager.ts

Changes: Added logger constructor param with this.logger instance property, replaced 28 logger calls

src/lib/MergeManager.ts

Changes: Added logger constructor param with this.logger instance property, replaced 27 logger calls

src/lib/ResourceCleanup.ts

Changes: Added logger constructor param with this.logger instance property, replaced 30 logger calls

src/lib/BuildRunner.ts

Changes: Added logger constructor param with this.logger instance property, replaced 7 logger calls

src/lib/PRManager.ts

Changes: Added logger constructor param with this.logger instance property, replaced 8 logger calls

src/lib/GitWorktreeManager.ts

Changes: Added logger constructor param with this.logger instance property, replaced dynamic import with static import

src/commands/cleanup.ts

Changes: Added logger property/constructor param, JSON mode validation (requires --force), execute() returns CleanupResult in JSON mode

src/commands/finish.ts

Changes: Added logger property/constructor param, JSON mode validation (requires --cleanup for github-pr mode), wired logger to sub-managers

src/cli.ts

Changes: Added --json options to cleanup and finish commands, createStderrLogger() pattern, JSON error output handling

Dependencies Added

None