@lumenflow/core 1.5.0 → 1.6.0

package/dist/recovery/recovery-analyzer.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Recovery Analyzer for WU State Issues
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Analyzes WU context to detect state inconsistencies and suggests
+ * appropriate recovery actions.
+ *
+ * Issue types detected:
+ * - Partial claim: worktree exists but status is ready
+ * - Orphan claim: status is in_progress but worktree missing
+ * - Inconsistent state: YAML and state store disagree
+ * - Orphan branch: branch exists but worktree missing
+ * - Stale lock: lock file from old session
+ * - Leftover worktree: WU is done but worktree exists
+ *
+ * @module
+ */
+import { type RecoveryActionType, type RecoveryIssueCode } from '../wu-constants.js';
+import type { WuContext } from '../validation/types.js';
+/**
+ * Issue detected during recovery analysis.
+ */
+export interface RecoveryIssue {
+    /** Issue code from RECOVERY_ISSUES */
+    code: RecoveryIssueCode;
+    /** Human-readable description */
+    description: string;
+    /** Additional context for the issue */
+    context?: Record<string, unknown>;
+}
+/**
+ * Suggested recovery action.
+ */
+export interface WuRecoveryAction {
+    /** Action type from RECOVERY_ACTIONS */
+    type: RecoveryActionType;
+    /** Human-readable description of what this action does */
+    description: string;
+    /** Command to execute (copy-paste ready) */
+    command: string;
+    /** Whether this action requires --force flag */
+    requiresForce: boolean;
+    /** Warning message if any */
+    warning?: string;
+}
+/**
+ * Result of recovery analysis.
+ */
+export interface RecoveryAnalysis {
+    /** Whether any issues were found */
+    hasIssues: boolean;
+    /** List of detected issues */
+    issues: RecoveryIssue[];
+    /** Suggested recovery actions */
+    actions: WuRecoveryAction[];
+    /** WU ID analyzed */
+    wuId: string | null;
+}
+/**
+ * Analyze context for recovery issues.
+ *
+ * @param context - Current WU context
+ * @returns Recovery analysis with issues and suggested actions
+ */
+export declare function analyzeRecovery(context: WuContext): Promise<RecoveryAnalysis>;

package/dist/recovery/recovery-analyzer.js

@@ -0,0 +1,129 @@
+/**
+ * Recovery Analyzer for WU State Issues
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Analyzes WU context to detect state inconsistencies and suggests
+ * appropriate recovery actions.
+ *
+ * Issue types detected:
+ * - Partial claim: worktree exists but status is ready
+ * - Orphan claim: status is in_progress but worktree missing
+ * - Inconsistent state: YAML and state store disagree
+ * - Orphan branch: branch exists but worktree missing
+ * - Stale lock: lock file from old session
+ * - Leftover worktree: WU is done but worktree exists
+ *
+ * @module
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { CONTEXT_VALIDATION, WU_STATUS, DEFAULTS, toKebab, } from '../wu-constants.js';
+const { RECOVERY_ISSUES, RECOVERY_ACTIONS } = CONTEXT_VALIDATION;
+/**
+ * Get expected worktree path for a WU.
+ */
+function getExpectedWorktreePath(mainCheckout, lane, wuId) {
+    const laneKebab = toKebab(lane);
+    const wuIdLower = wuId.toLowerCase();
+    return join(mainCheckout, DEFAULTS.WORKTREES_DIR, `${laneKebab}-${wuIdLower}`);
+}
+/**
+ * Check if worktree exists for a WU.
+ */
+function worktreeExists(mainCheckout, lane, wuId) {
+    const worktreePath = getExpectedWorktreePath(mainCheckout, lane, wuId);
+    return existsSync(worktreePath);
+}
+/**
+ * Analyze context for recovery issues.
+ *
+ * @param context - Current WU context
+ * @returns Recovery analysis with issues and suggested actions
+ */
+export async function analyzeRecovery(context) {
+    const issues = [];
+    const actions = [];
+    // No WU context means nothing to analyze
+    if (!context.wu) {
+        return {
+            hasIssues: false,
+            issues: [],
+            actions: [],
+            wuId: null,
+        };
+    }
+    const { wu } = context;
+    const mainCheckout = context.location.mainCheckout;
+    const hasWorktree = worktreeExists(mainCheckout, wu.lane, wu.id);
+    const worktreePath = getExpectedWorktreePath(mainCheckout, wu.lane, wu.id);
+    // Check for partial claim: worktree exists but status is ready
+    if (hasWorktree && wu.status === WU_STATUS.READY) {
+        issues.push({
+            code: RECOVERY_ISSUES.PARTIAL_CLAIM,
+            description: `Worktree exists for ${wu.id} but status is 'ready'. The claim may have been interrupted.`,
+            context: { worktreePath, status: wu.status },
+        });
+        actions.push({
+            type: RECOVERY_ACTIONS.RESUME,
+            description: 'Reconcile state and continue working (preserves work)',
+            command: `pnpm wu:recover --id ${wu.id} --action resume`,
+            requiresForce: false,
+        });
+        actions.push({
+            type: RECOVERY_ACTIONS.RESET,
+            description: 'Discard worktree and reset WU to ready',
+            command: `pnpm wu:recover --id ${wu.id} --action reset`,
+            requiresForce: false,
+            warning: 'This will discard any uncommitted work in the worktree',
+        });
+    }
+    // Check for orphan claim: status is in_progress but worktree missing
+    if (!hasWorktree && wu.status === WU_STATUS.IN_PROGRESS) {
+        issues.push({
+            code: RECOVERY_ISSUES.ORPHAN_CLAIM,
+            description: `${wu.id} is 'in_progress' but worktree is missing. The worktree may have been manually deleted.`,
+            context: { expectedPath: worktreePath, status: wu.status },
+        });
+        actions.push({
+            type: RECOVERY_ACTIONS.RESET,
+            description: 'Reset WU status back to ready for re-claiming',
+            command: `pnpm wu:recover --id ${wu.id} --action reset`,
+            requiresForce: false,
+        });
+    }
+    // Check for leftover worktree: WU is done but worktree exists
+    if (hasWorktree && wu.status === WU_STATUS.DONE) {
+        issues.push({
+            code: RECOVERY_ISSUES.LEFTOVER_WORKTREE,
+            description: `${wu.id} is 'done' but worktree still exists. The cleanup may have failed.`,
+            context: { worktreePath, status: wu.status },
+        });
+        actions.push({
+            type: RECOVERY_ACTIONS.CLEANUP,
+            description: 'Remove leftover worktree for completed WU',
+            command: `pnpm wu:recover --id ${wu.id} --action cleanup`,
+            requiresForce: false,
+        });
+    }
+    // Check for inconsistent state
+    if (!wu.isConsistent && wu.inconsistencyReason) {
+        issues.push({
+            code: RECOVERY_ISSUES.INCONSISTENT_STATE,
+            description: wu.inconsistencyReason,
+            context: { wuId: wu.id },
+        });
+        actions.push({
+            type: RECOVERY_ACTIONS.RESET,
+            description: 'Reconcile YAML and state store',
+            command: `pnpm wu:recover --id ${wu.id} --action reset`,
+            requiresForce: false,
+        });
+    }
+    return {
+        hasIssues: issues.length > 0,
+        issues,
+        actions,
+        wuId: wu.id,
+    };
+}

package/dist/usecases/analyze-recovery.usecase.d.ts

@@ -0,0 +1,42 @@
+/**
+ * AnalyzeRecoveryUseCase
+ *
+ * WU-1094: INIT-002 Phase 2 - Implement adapters and dependency injection
+ *
+ * Use case for analyzing WU state and suggesting recovery actions.
+ * Uses constructor injection for recovery analyzer dependency.
+ *
+ * Hexagonal Architecture - Application Layer
+ * - Depends on port interface (IRecoveryAnalyzer)
+ * - Does NOT import from infrastructure layer
+ *
+ * @module usecases/analyze-recovery.usecase
+ */
+import type { IRecoveryAnalyzer, WuContext, RecoveryAnalysis } from '../ports/recovery.ports.js';
+/**
+ * AnalyzeRecoveryUseCase
+ *
+ * Analyzes WU context to detect state inconsistencies and suggests
+ * recovery actions.
+ *
+ * @example
+ * // Using default analyzer via DI factory
+ * const useCase = createAnalyzeRecoveryUseCase();
+ * const analysis = await useCase.execute(context);
+ *
+ * @example
+ * // Using custom analyzer for testing
+ * const useCase = new AnalyzeRecoveryUseCase(mockAnalyzer);
+ * const analysis = await useCase.execute(context);
+ */
+export declare class AnalyzeRecoveryUseCase {
+    private readonly recoveryAnalyzer;
+    constructor(recoveryAnalyzer: IRecoveryAnalyzer);
+    /**
+     * Execute the use case to analyze recovery issues.
+     *
+     * @param context - Current WU context
+     * @returns Promise<RecoveryAnalysis> - Analysis with issues and suggested actions
+     */
+    execute(context: WuContext): Promise<RecoveryAnalysis>;
+}

package/dist/usecases/analyze-recovery.usecase.js

@@ -0,0 +1,45 @@
+/**
+ * AnalyzeRecoveryUseCase
+ *
+ * WU-1094: INIT-002 Phase 2 - Implement adapters and dependency injection
+ *
+ * Use case for analyzing WU state and suggesting recovery actions.
+ * Uses constructor injection for recovery analyzer dependency.
+ *
+ * Hexagonal Architecture - Application Layer
+ * - Depends on port interface (IRecoveryAnalyzer)
+ * - Does NOT import from infrastructure layer
+ *
+ * @module usecases/analyze-recovery.usecase
+ */
+/**
+ * AnalyzeRecoveryUseCase
+ *
+ * Analyzes WU context to detect state inconsistencies and suggests
+ * recovery actions.
+ *
+ * @example
+ * // Using default analyzer via DI factory
+ * const useCase = createAnalyzeRecoveryUseCase();
+ * const analysis = await useCase.execute(context);
+ *
+ * @example
+ * // Using custom analyzer for testing
+ * const useCase = new AnalyzeRecoveryUseCase(mockAnalyzer);
+ * const analysis = await useCase.execute(context);
+ */
+export class AnalyzeRecoveryUseCase {
+    recoveryAnalyzer;
+    constructor(recoveryAnalyzer) {
+        this.recoveryAnalyzer = recoveryAnalyzer;
+    }
+    /**
+     * Execute the use case to analyze recovery issues.
+     *
+     * @param context - Current WU context
+     * @returns Promise<RecoveryAnalysis> - Analysis with issues and suggested actions
+     */
+    async execute(context) {
+        return this.recoveryAnalyzer.analyzeRecovery(context);
+    }
+}

package/dist/usecases/compute-context.usecase.d.ts

@@ -0,0 +1,62 @@
+/**
+ * ComputeContextUseCase
+ *
+ * WU-1094: INIT-002 Phase 2 - Implement adapters and dependency injection
+ *
+ * Use case for computing WU context by orchestrating multiple adapters.
+ * Uses constructor injection for all dependencies.
+ *
+ * Hexagonal Architecture - Application Layer
+ * - Depends on port interfaces (ILocationResolver, IGitStateReader, IWuStateReader)
+ * - Does NOT import from infrastructure layer
+ *
+ * @module usecases/compute-context.usecase
+ */
+import type { ILocationResolver, IGitStateReader, IWuStateReader } from '../ports/context.ports.js';
+import type { WuContext } from '../validation/types.js';
+/**
+ * Options for computing WU context.
+ */
+export interface ComputeContextOptions {
+    /** WU ID to look up (optional - will detect from worktree if not provided) */
+    wuId?: string;
+    /** Current working directory (defaults to process.cwd()) */
+    cwd?: string;
+}
+/**
+ * ComputeContextUseCase
+ *
+ * Orchestrates the computation of WU context by calling multiple adapters
+ * and assembling the unified context model.
+ *
+ * @example
+ * // Using default adapters via DI factory
+ * const useCase = createComputeContextUseCase();
+ * const context = await useCase.execute({ wuId: 'WU-1094' });
+ *
+ * @example
+ * // Using custom adapters for testing
+ * const useCase = new ComputeContextUseCase(
+ *   mockLocationResolver,
+ *   mockGitStateReader,
+ *   mockWuStateReader,
+ * );
+ * const context = await useCase.execute({});
+ */
+export declare class ComputeContextUseCase {
+    private readonly locationResolver;
+    private readonly gitStateReader;
+    private readonly wuStateReader;
+    constructor(locationResolver: ILocationResolver, gitStateReader: IGitStateReader, wuStateReader: IWuStateReader);
+    /**
+     * Execute the use case to compute WU context.
+     *
+     * @param options - Options including optional wuId and cwd
+     * @returns Promise<WuContext> - Computed WU context
+     */
+    execute(options?: ComputeContextOptions): Promise<WuContext>;
+    /**
+     * Get expected worktree path for a WU.
+     */
+    private getWorktreePath;
+}

package/dist/usecases/compute-context.usecase.js

@@ -0,0 +1,101 @@
+/**
+ * ComputeContextUseCase
+ *
+ * WU-1094: INIT-002 Phase 2 - Implement adapters and dependency injection
+ *
+ * Use case for computing WU context by orchestrating multiple adapters.
+ * Uses constructor injection for all dependencies.
+ *
+ * Hexagonal Architecture - Application Layer
+ * - Depends on port interfaces (ILocationResolver, IGitStateReader, IWuStateReader)
+ * - Does NOT import from infrastructure layer
+ *
+ * @module usecases/compute-context.usecase
+ */
+/**
+ * ComputeContextUseCase
+ *
+ * Orchestrates the computation of WU context by calling multiple adapters
+ * and assembling the unified context model.
+ *
+ * @example
+ * // Using default adapters via DI factory
+ * const useCase = createComputeContextUseCase();
+ * const context = await useCase.execute({ wuId: 'WU-1094' });
+ *
+ * @example
+ * // Using custom adapters for testing
+ * const useCase = new ComputeContextUseCase(
+ *   mockLocationResolver,
+ *   mockGitStateReader,
+ *   mockWuStateReader,
+ * );
+ * const context = await useCase.execute({});
+ */
+export class ComputeContextUseCase {
+    locationResolver;
+    gitStateReader;
+    wuStateReader;
+    constructor(locationResolver, gitStateReader, wuStateReader) {
+        this.locationResolver = locationResolver;
+        this.gitStateReader = gitStateReader;
+        this.wuStateReader = wuStateReader;
+    }
+    /**
+     * Execute the use case to compute WU context.
+     *
+     * @param options - Options including optional wuId and cwd
+     * @returns Promise<WuContext> - Computed WU context
+     */
+    async execute(options = {}) {
+        const { wuId, cwd } = options;
+        // Step 1: Resolve location context
+        const location = await this.locationResolver.resolveLocation(cwd);
+        // Step 2: Read git state for current directory
+        const git = await this.gitStateReader.readGitState(cwd);
+        // Step 3: Determine WU ID (explicit or from worktree)
+        const effectiveWuId = wuId ?? location.worktreeWuId;
+        // Step 4: Read WU state if we have a WU ID
+        let wu = null;
+        let worktreeGit;
+        if (effectiveWuId) {
+            const wuStateResult = await this.wuStateReader.readWuState(effectiveWuId, location.mainCheckout);
+            if (wuStateResult) {
+                wu = {
+                    id: wuStateResult.id,
+                    status: wuStateResult.status,
+                    lane: wuStateResult.lane,
+                    title: wuStateResult.title,
+                    yamlPath: wuStateResult.yamlPath,
+                    isConsistent: wuStateResult.isConsistent,
+                    inconsistencyReason: wuStateResult.inconsistencyReason,
+                };
+                // Step 5: If running from main and WU is in_progress, read worktree git state
+                if (location.type === 'main' && wu.status === 'in_progress') {
+                    const worktreePath = this.getWorktreePath(location.mainCheckout, wu.lane, wu.id);
+                    worktreeGit = await this.gitStateReader.readGitState(worktreePath);
+                }
+            }
+        }
+        // Step 6: Create session state (inactive by default)
+        const session = {
+            isActive: false,
+            sessionId: null,
+        };
+        return {
+            location,
+            git,
+            wu,
+            session,
+            worktreeGit,
+        };
+    }
+    /**
+     * Get expected worktree path for a WU.
+     */
+    getWorktreePath(mainCheckout, lane, wuId) {
+        const laneKebab = lane.toLowerCase().replace(/[: ]+/g, '-');
+        const wuIdLower = wuId.toLowerCase();
+        return `${mainCheckout}/worktrees/${laneKebab}-${wuIdLower}`;
+    }
+}

package/dist/usecases/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Use Cases Index
+ *
+ * WU-1094: INIT-002 Phase 2 - Implement adapters and dependency injection
+ *
+ * Re-exports all use case classes.
+ *
+ * @module usecases
+ */
+export { ComputeContextUseCase, type ComputeContextOptions } from './compute-context.usecase.js';
+export { ValidateCommandUseCase } from './validate-command.usecase.js';
+export { AnalyzeRecoveryUseCase } from './analyze-recovery.usecase.js';
+export { GetDashboardDataUseCase, type GetDashboardDataOptions, } from './get-dashboard-data.usecase.js';
+export { GetSuggestionsUseCase, type GetSuggestionsOptions } from './get-suggestions.usecase.js';

package/dist/usecases/index.js

@@ -0,0 +1,18 @@
+/**
+ * Use Cases Index
+ *
+ * WU-1094: INIT-002 Phase 2 - Implement adapters and dependency injection
+ *
+ * Re-exports all use case classes.
+ *
+ * @module usecases
+ */
+// Context use cases
+export { ComputeContextUseCase } from './compute-context.usecase.js';
+// Validation use cases
+export { ValidateCommandUseCase } from './validate-command.usecase.js';
+// Recovery use cases
+export { AnalyzeRecoveryUseCase } from './analyze-recovery.usecase.js';
+// Existing use cases (pre-WU-1094)
+export { GetDashboardDataUseCase, } from './get-dashboard-data.usecase.js';
+export { GetSuggestionsUseCase } from './get-suggestions.usecase.js';

package/dist/usecases/validate-command.usecase.d.ts

@@ -0,0 +1,55 @@
+/**
+ * ValidateCommandUseCase
+ *
+ * WU-1094: INIT-002 Phase 2 - Implement adapters and dependency injection
+ *
+ * Use case for validating commands against WU context.
+ * Uses constructor injection for command registry dependency.
+ *
+ * Hexagonal Architecture - Application Layer
+ * - Depends on port interface (ICommandRegistry)
+ * - Does NOT import from infrastructure layer
+ *
+ * @module usecases/validate-command.usecase
+ */
+import type { ICommandRegistry, CommandDefinition, WuContext } from '../ports/validation.ports.js';
+import type { ValidationResult } from '../validation/types.js';
+/**
+ * ValidateCommandUseCase
+ *
+ * Validates a command against the current WU context, returning
+ * validation errors and warnings with fix suggestions.
+ *
+ * @example
+ * // Using default registry via DI factory
+ * const useCase = createValidateCommandUseCase();
+ * const result = await useCase.execute('wu:done', context);
+ *
+ * @example
+ * // Using custom registry for testing
+ * const useCase = new ValidateCommandUseCase(mockRegistry);
+ * const result = await useCase.execute('wu:claim', context);
+ */
+export declare class ValidateCommandUseCase {
+    private readonly commandRegistry;
+    constructor(commandRegistry: ICommandRegistry);
+    /**
+     * Execute the use case to validate a command.
+     *
+     * @param command - Command name (e.g., 'wu:done')
+     * @param context - Current WU context
+     * @returns Promise<ValidationResult> - Validation result with errors/warnings
+     */
+    execute(command: string, context: WuContext): Promise<ValidationResult>;
+    /**
+     * Get valid commands for the current context.
+     *
+     * @param context - Current WU context
+     * @returns Promise<CommandDefinition[]> - Array of valid commands
+     */
+    getValidCommands(context: WuContext): Promise<CommandDefinition[]>;
+    /**
+     * Generate fix command for location errors.
+     */
+    private getLocationFixCommand;
+}

package/dist/usecases/validate-command.usecase.js

@@ -0,0 +1,154 @@
+/**
+ * ValidateCommandUseCase
+ *
+ * WU-1094: INIT-002 Phase 2 - Implement adapters and dependency injection
+ *
+ * Use case for validating commands against WU context.
+ * Uses constructor injection for command registry dependency.
+ *
+ * Hexagonal Architecture - Application Layer
+ * - Depends on port interface (ICommandRegistry)
+ * - Does NOT import from infrastructure layer
+ *
+ * @module usecases/validate-command.usecase
+ */
+import { CONTEXT_VALIDATION } from '../wu-constants.js';
+const { ERROR_CODES, SEVERITY } = CONTEXT_VALIDATION;
+/**
+ * ValidateCommandUseCase
+ *
+ * Validates a command against the current WU context, returning
+ * validation errors and warnings with fix suggestions.
+ *
+ * @example
+ * // Using default registry via DI factory
+ * const useCase = createValidateCommandUseCase();
+ * const result = await useCase.execute('wu:done', context);
+ *
+ * @example
+ * // Using custom registry for testing
+ * const useCase = new ValidateCommandUseCase(mockRegistry);
+ * const result = await useCase.execute('wu:claim', context);
+ */
+export class ValidateCommandUseCase {
+    commandRegistry;
+    constructor(commandRegistry) {
+        this.commandRegistry = commandRegistry;
+    }
+    /**
+     * Execute the use case to validate a command.
+     *
+     * @param command - Command name (e.g., 'wu:done')
+     * @param context - Current WU context
+     * @returns Promise<ValidationResult> - Validation result with errors/warnings
+     */
+    async execute(command, context) {
+        const errors = [];
+        const warnings = [];
+        // Step 1: Look up command definition
+        const commandDef = this.commandRegistry.getCommandDefinition(command);
+        if (!commandDef) {
+            errors.push({
+                // Use WU_NOT_FOUND as a general "not found" error code
+                // The message clarifies it's an unknown command
+                code: ERROR_CODES.WU_NOT_FOUND,
+                message: `Unknown command: ${command}`,
+                fixCommand: null,
+            });
+            return {
+                valid: false,
+                errors,
+                warnings,
+                context,
+            };
+        }
+        // Step 2: Check location requirement
+        if (commandDef.requiredLocation !== null) {
+            if (context.location.type !== commandDef.requiredLocation) {
+                const fixCommand = this.getLocationFixCommand(commandDef.requiredLocation, context, command);
+                errors.push({
+                    code: ERROR_CODES.WRONG_LOCATION,
+                    message: `${command} must be run from ${commandDef.requiredLocation} checkout`,
+                    fixCommand,
+                    context: {
+                        required: commandDef.requiredLocation,
+                        actual: context.location.type,
+                    },
+                });
+            }
+        }
+        // Step 3: Check WU status requirement
+        if (commandDef.requiredWuStatus !== null) {
+            const actualStatus = context.wu?.status ?? null;
+            if (actualStatus !== commandDef.requiredWuStatus) {
+                errors.push({
+                    code: ERROR_CODES.WRONG_WU_STATUS,
+                    message: `${command} requires WU status '${commandDef.requiredWuStatus}' but got '${actualStatus ?? 'no WU'}'`,
+                    fixCommand: null,
+                    context: {
+                        required: commandDef.requiredWuStatus,
+                        actual: actualStatus,
+                    },
+                });
+            }
+        }
+        // Step 4: Check predicates
+        if (commandDef.predicates && commandDef.predicates.length > 0) {
+            for (const predicate of commandDef.predicates) {
+                const passed = predicate.check(context);
+                if (!passed) {
+                    const message = predicate.getFixMessage
+                        ? predicate.getFixMessage(context)
+                        : predicate.description;
+                    if (predicate.severity === SEVERITY.ERROR) {
+                        errors.push({
+                            // Use GATES_NOT_PASSED for predicate failures (e.g., dirty worktree)
+                            code: ERROR_CODES.GATES_NOT_PASSED,
+                            message,
+                            fixCommand: null,
+                            context: { predicateId: predicate.id },
+                        });
+                    }
+                    else {
+                        warnings.push({
+                            id: predicate.id,
+                            message,
+                        });
+                    }
+                }
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings,
+            context,
+        };
+    }
+    /**
+     * Get valid commands for the current context.
+     *
+     * @param context - Current WU context
+     * @returns Promise<CommandDefinition[]> - Array of valid commands
+     */
+    async getValidCommands(context) {
+        return this.commandRegistry.getValidCommandsForContext(context);
+    }
+    /**
+     * Generate fix command for location errors.
+     */
+    getLocationFixCommand(requiredLocation, context, command) {
+        if (requiredLocation === 'main') {
+            // Need to cd to main checkout
+            const wuIdParam = context.wu?.id ? ` --id ${context.wu.id}` : '';
+            return `cd ${context.location.mainCheckout} && pnpm ${command}${wuIdParam}`;
+        }
+        else if (requiredLocation === 'worktree') {
+            // Need to cd to worktree
+            if (context.location.worktreeName) {
+                return `cd ${context.location.mainCheckout}/worktrees/${context.location.worktreeName}`;
+            }
+        }
+        return '';
+    }
+}