@lumenflow/core 1.4.0 → 1.6.0

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

package/dist/validation/command-registry.js

@@ -0,0 +1,229 @@
+/**
+ * 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 { CONTEXT_VALIDATION, WU_STATUS } from '../wu-constants.js';
+const { LOCATION_TYPES, COMMANDS, SEVERITY } = CONTEXT_VALIDATION;
+/**
+ * Predicate: Check if worktree is clean (no uncommitted changes).
+ *
+ * WU-1092: Checks worktreeGit.isDirty when available (running from main),
+ * falls back to git.isDirty otherwise (running from worktree itself).
+ */
+const worktreeCleanPredicate = {
+    id: 'worktree-clean',
+    description: 'Worktree must not have uncommitted changes',
+    severity: SEVERITY.ERROR,
+    check: (context) => {
+        // WU-1092: Prefer worktreeGit when available (running wu:done from main)
+        if (context.worktreeGit !== undefined) {
+            return !context.worktreeGit.isDirty;
+        }
+        // Fallback: check current git state (running from worktree itself)
+        return !context.git.isDirty;
+    },
+    getFixMessage: (context) => {
+        const worktreePath = context.location.worktreeName
+            ? `worktrees/${context.location.worktreeName}`
+            : 'worktree';
+        return `Commit or stash changes in ${worktreePath} before running wu:done`;
+    },
+};
+/**
+ * Predicate: Check if branch has commits to push.
+ */
+const hasCommitsPredicate = {
+    id: 'has-commits',
+    description: 'Branch must have commits ahead of tracking branch',
+    severity: SEVERITY.WARNING,
+    check: (context) => context.git.ahead > 0,
+    getFixMessage: () => 'No new commits to merge. Did you forget to commit your changes?',
+};
+/**
+ * Predicate: Check if WU state is consistent between YAML and state store.
+ */
+const stateConsistentPredicate = {
+    id: 'state-consistent',
+    description: 'WU state must be consistent between YAML and state store',
+    severity: SEVERITY.WARNING,
+    check: (context) => context.wu?.isConsistent ?? true,
+    getFixMessage: (context) => context.wu?.inconsistencyReason || 'State store and YAML are inconsistent',
+};
+/**
+ * Command definition for wu:create.
+ */
+const wuCreate = {
+    name: COMMANDS.WU_CREATE,
+    description: 'Create a new WU YAML spec',
+    requiredLocation: LOCATION_TYPES.MAIN,
+    requiredWuStatus: null, // Creates new WU, no existing status required
+    predicates: [],
+    getNextSteps: (context) => [
+        `1. Edit the WU spec with acceptance criteria`,
+        `2. Run: pnpm wu:claim --id ${context.wu?.id || 'WU-XXX'} --lane "<lane>"`,
+    ],
+};
+/**
+ * Command definition for wu:claim.
+ */
+const wuClaim = {
+    name: COMMANDS.WU_CLAIM,
+    description: 'Claim a WU and create worktree',
+    requiredLocation: LOCATION_TYPES.MAIN,
+    requiredWuStatus: WU_STATUS.READY,
+    predicates: [],
+    getNextSteps: (context) => {
+        const wuId = context.wu?.id?.toLowerCase() || 'wu-xxx';
+        const lane = context.wu?.lane?.toLowerCase().replace(/[: ]+/g, '-') || 'lane';
+        return [
+            `1. cd worktrees/${lane}-${wuId}`,
+            '2. Implement changes per acceptance criteria',
+            '3. Run: pnpm gates',
+            `4. Return to main and run: pnpm wu:done --id ${context.wu?.id || 'WU-XXX'}`,
+        ];
+    },
+};
+/**
+ * Command definition for wu:done.
+ */
+const wuDone = {
+    name: COMMANDS.WU_DONE,
+    description: 'Complete WU (merge, stamp, cleanup)',
+    requiredLocation: LOCATION_TYPES.MAIN,
+    requiredWuStatus: WU_STATUS.IN_PROGRESS,
+    predicates: [worktreeCleanPredicate, hasCommitsPredicate, stateConsistentPredicate],
+    getNextSteps: () => [
+        'WU completed successfully!',
+        'Check backlog.md for your next task or run: pnpm wu:status',
+    ],
+};
+/**
+ * Command definition for wu:block.
+ */
+const wuBlock = {
+    name: COMMANDS.WU_BLOCK,
+    description: 'Block WU due to external dependency',
+    requiredLocation: null, // Can run from main or worktree
+    requiredWuStatus: WU_STATUS.IN_PROGRESS,
+    predicates: [],
+    getNextSteps: () => [
+        'WU blocked. The lane is now available for other work.',
+        'When blocker is resolved, run: pnpm wu:unblock --id WU-XXX',
+    ],
+};
+/**
+ * Command definition for wu:unblock.
+ */
+const wuUnblock = {
+    name: COMMANDS.WU_UNBLOCK,
+    description: 'Unblock a blocked WU',
+    requiredLocation: null, // Can run from main or worktree
+    requiredWuStatus: WU_STATUS.BLOCKED,
+    predicates: [],
+    getNextSteps: (context) => [
+        'WU unblocked and returned to in_progress.',
+        `Continue working in the worktree or run: pnpm wu:done --id ${context.wu?.id || 'WU-XXX'}`,
+    ],
+};
+/**
+ * Command definition for wu:status.
+ */
+const wuStatus = {
+    name: COMMANDS.WU_STATUS,
+    description: 'Show WU status, location, and valid commands',
+    requiredLocation: null, // Informational, works anywhere
+    requiredWuStatus: null, // Works without WU context too
+    predicates: [],
+};
+/**
+ * Command definition for wu:recover.
+ */
+const wuRecover = {
+    name: COMMANDS.WU_RECOVER,
+    description: 'Analyze and fix WU state inconsistencies',
+    requiredLocation: LOCATION_TYPES.MAIN,
+    requiredWuStatus: null, // Handles any state
+    predicates: [],
+    getNextSteps: () => ['Review recovery actions and confirm to proceed.'],
+};
+/**
+ * Command registry mapping command names to definitions.
+ */
+export const COMMAND_REGISTRY = new Map([
+    [COMMANDS.WU_CREATE, wuCreate],
+    [COMMANDS.WU_CLAIM, wuClaim],
+    [COMMANDS.WU_DONE, wuDone],
+    [COMMANDS.WU_BLOCK, wuBlock],
+    [COMMANDS.WU_UNBLOCK, wuUnblock],
+    [COMMANDS.WU_STATUS, wuStatus],
+    [COMMANDS.WU_RECOVER, wuRecover],
+]);
+/**
+ * Get command definition by name.
+ *
+ * @param command - Command name (e.g., 'wu:create')
+ * @returns CommandDefinition or null if not found
+ */
+export function getCommandDefinition(command) {
+    return COMMAND_REGISTRY.get(command) ?? null;
+}
+/**
+ * Check if a command's location requirement is satisfied.
+ */
+function isLocationValid(def, locationType) {
+    // null means any location is valid
+    if (def.requiredLocation === null)
+        return true;
+    return def.requiredLocation === locationType;
+}
+/**
+ * Check if a command's WU status requirement is satisfied.
+ */
+function isStatusValid(def, wuStatus) {
+    // null requirement means no status check needed
+    if (def.requiredWuStatus === null)
+        return true;
+    return def.requiredWuStatus === wuStatus;
+}
+/**
+ * Check if all predicates pass (ignoring warnings).
+ */
+function arePredicatesValid(def, context) {
+    if (!def.predicates || def.predicates.length === 0)
+        return true;
+    // Only check error-severity predicates for validity
+    return def.predicates.filter((p) => p.severity === SEVERITY.ERROR).every((p) => p.check(context));
+}
+/**
+ * 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 function getValidCommandsForContext(context) {
+    const validCommands = [];
+    const locationType = context.location.type;
+    const wuStatus = context.wu?.status ?? null;
+    for (const def of COMMAND_REGISTRY.values()) {
+        if (isLocationValid(def, locationType) &&
+            isStatusValid(def, wuStatus) &&
+            arePredicatesValid(def, context)) {
+            validCommands.push(def);
+        }
+    }
+    return validCommands;
+}

package/dist/validation/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Validation Module
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Exports:
+ * - Type definitions
+ * - Command registry
+ * - Validation functions
+ *
+ * @module
+ */
+export * from './types.js';
+export * from './command-registry.js';
+export * from './validate-command.js';

package/dist/validation/index.js

@@ -0,0 +1,15 @@
+/**
+ * Validation Module
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Exports:
+ * - Type definitions
+ * - Command registry
+ * - Validation functions
+ *
+ * @module
+ */
+export * from './types.js';
+export * from './command-registry.js';
+export * from './validate-command.js';