@lumenflow/core 1.5.0 → 2.0.0

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 '';
+    }
+}

package/dist/validation/command-registry.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Command Registry for WU Lifecycle Commands
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Declarative definitions for all wu:* commands specifying:
+ * - Required location (main vs worktree)
+ * - Required WU status
+ * - Custom validation predicates
+ * - Success next steps
+ *
+ * @module
+ */
+import type { CommandDefinition, CommandPredicate, WuContext } from './types.js';
+/**
+ * Command registry mapping command names to definitions.
+ */
+export declare const COMMAND_REGISTRY: Map<string, CommandDefinition>;
+/**
+ * Get command definition by name.
+ *
+ * @param command - Command name (e.g., 'wu:create')
+ * @returns CommandDefinition or null if not found
+ */
+export declare function getCommandDefinition(command: string): CommandDefinition | null;
+/**
+ * Get all commands valid for the current context.
+ *
+ * A command is valid if:
+ * - Location requirement is satisfied (or null = any)
+ * - WU status requirement is satisfied (or null = no WU required)
+ * - All error-severity predicates pass
+ *
+ * @param context - Current WU context
+ * @returns Array of valid CommandDefinitions
+ */
+export declare function getValidCommandsForContext(context: WuContext): CommandDefinition[];
+export type { CommandDefinition, CommandPredicate, WuContext };