@lumenflow/core 1.4.0 → 1.6.0

package/dist/ports/context.ports.js

@@ -0,0 +1,21 @@
+/**
+ * Context Ports
+ *
+ * WU-1093: INIT-002 Phase 1 - Define ports and domain schemas
+ *
+ * Port interfaces for context-aware validation system.
+ * These abstractions allow external users to inject custom implementations.
+ *
+ * Hexagonal Architecture - Input Ports:
+ * - ILocationResolver: Detect main checkout vs worktree
+ * - IGitStateReader: Read git branch, dirty state, ahead/behind
+ * - IWuStateReader: Read WU state from YAML and state store
+ *
+ * Current Implementations:
+ * - resolveLocation (location-resolver.ts)
+ * - readGitState (git-state-reader.ts)
+ * - readWuState (wu-state-reader.ts)
+ *
+ * @module ports/context
+ */
+export {};

package/dist/ports/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Ports Index
+ *
+ * WU-1093: INIT-002 Phase 1 - Define ports and domain schemas
+ *
+ * Re-exports all port interfaces for the context-aware validation system.
+ *
+ * @module ports
+ */
+export * from './context.ports.js';
+export * from './validation.ports.js';
+export * from './recovery.ports.js';
+export * from './metrics-collector.port.js';
+export * from './dashboard-renderer.port.js';

package/dist/ports/index.js

@@ -0,0 +1,14 @@
+/**
+ * Ports Index
+ *
+ * WU-1093: INIT-002 Phase 1 - Define ports and domain schemas
+ *
+ * Re-exports all port interfaces for the context-aware validation system.
+ *
+ * @module ports
+ */
+export * from './context.ports.js';
+export * from './validation.ports.js';
+export * from './recovery.ports.js';
+export * from './metrics-collector.port.js';
+export * from './dashboard-renderer.port.js';

package/dist/ports/recovery.ports.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Recovery Ports
+ *
+ * WU-1093: INIT-002 Phase 1 - Define ports and domain schemas
+ *
+ * Port interfaces for recovery-related operations.
+ * These abstractions allow external users to inject custom implementations.
+ *
+ * Hexagonal Architecture - Input Ports:
+ * - IRecoveryAnalyzer: Analyze WU state issues and suggest recovery actions
+ *
+ * Current Implementations:
+ * - analyzeRecovery (recovery-analyzer.ts)
+ *
+ * @module ports/recovery
+ */
+import type { WuContext } from '../validation/types.js';
+import type { RecoveryAnalysis } from '../recovery/recovery-analyzer.js';
+/**
+ * Recovery Analyzer Port Interface
+ *
+ * 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
+ *
+ * @example
+ * // Custom implementation for testing
+ * const mockAnalyzer: IRecoveryAnalyzer = {
+ *   analyzeRecovery: async (context) => ({
+ *     hasIssues: false,
+ *     issues: [],
+ *     actions: [],
+ *     wuId: context.wu?.id ?? null,
+ *   }),
+ * };
+ *
+ * @example
+ * // Using default implementation
+ * import { analyzeRecovery } from './recovery/recovery-analyzer.js';
+ * const analyzer: IRecoveryAnalyzer = { analyzeRecovery };
+ */
+export interface IRecoveryAnalyzer {
+    /**
+     * Analyze context for recovery issues.
+     *
+     * @param context - Current WU context
+     * @returns Promise<RecoveryAnalysis> - Recovery analysis with issues and suggested actions
+     */
+    analyzeRecovery(context: WuContext): Promise<RecoveryAnalysis>;
+}
+export type { WuContext, RecoveryAnalysis };

package/dist/ports/recovery.ports.js

@@ -0,0 +1,17 @@
+/**
+ * Recovery Ports
+ *
+ * WU-1093: INIT-002 Phase 1 - Define ports and domain schemas
+ *
+ * Port interfaces for recovery-related operations.
+ * These abstractions allow external users to inject custom implementations.
+ *
+ * Hexagonal Architecture - Input Ports:
+ * - IRecoveryAnalyzer: Analyze WU state issues and suggest recovery actions
+ *
+ * Current Implementations:
+ * - analyzeRecovery (recovery-analyzer.ts)
+ *
+ * @module ports/recovery
+ */
+export {};

package/dist/ports/validation.ports.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Validation Ports
+ *
+ * WU-1093: INIT-002 Phase 1 - Define ports and domain schemas
+ *
+ * Port interfaces for validation-related operations.
+ * These abstractions allow external users to inject custom implementations.
+ *
+ * Hexagonal Architecture - Input Ports:
+ * - ICommandRegistry: Lookup command definitions and validate commands
+ *
+ * Current Implementations:
+ * - COMMAND_REGISTRY, getCommandDefinition, getValidCommandsForContext (command-registry.ts)
+ *
+ * @module ports/validation
+ */
+import type { CommandDefinition, WuContext } from '../validation/types.js';
+/**
+ * Command Registry Port Interface
+ *
+ * Provides command definitions and validation logic for wu:* commands.
+ * Allows looking up command requirements and determining valid commands
+ * for a given context.
+ *
+ * @example
+ * // Custom implementation for testing
+ * const mockRegistry: ICommandRegistry = {
+ *   getCommandDefinition: (cmd) => cmd === 'wu:done' ? {...} : null,
+ *   getValidCommandsForContext: (ctx) => [...],
+ *   getAllCommands: () => [...],
+ * };
+ *
+ * @example
+ * // Using default implementation
+ * import {
+ *   getCommandDefinition,
+ *   getValidCommandsForContext,
+ *   COMMAND_REGISTRY,
+ * } from './validation/command-registry.js';
+ *
+ * const registry: ICommandRegistry = {
+ *   getCommandDefinition,
+ *   getValidCommandsForContext,
+ *   getAllCommands: () => Array.from(COMMAND_REGISTRY.values()),
+ * };
+ */
+export interface ICommandRegistry {
+    /**
+     * Get command definition by name.
+     *
+     * @param command - Command name (e.g., 'wu:create', 'wu:done')
+     * @returns CommandDefinition or null if not found
+     */
+    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
+     */
+    getValidCommandsForContext(context: WuContext): CommandDefinition[];
+    /**
+     * Get all registered command definitions.
+     *
+     * @returns Array of all CommandDefinitions
+     */
+    getAllCommands(): CommandDefinition[];
+}
+export type { CommandDefinition, WuContext };

package/dist/ports/validation.ports.js

@@ -0,0 +1,17 @@
+/**
+ * Validation Ports
+ *
+ * WU-1093: INIT-002 Phase 1 - Define ports and domain schemas
+ *
+ * Port interfaces for validation-related operations.
+ * These abstractions allow external users to inject custom implementations.
+ *
+ * Hexagonal Architecture - Input Ports:
+ * - ICommandRegistry: Lookup command definitions and validate commands
+ *
+ * Current Implementations:
+ * - COMMAND_REGISTRY, getCommandDefinition, getValidCommandsForContext (command-registry.ts)
+ *
+ * @module ports/validation
+ */
+export {};

package/dist/recovery/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Recovery Module
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Exports:
+ * - Recovery analysis (detect issues, suggest actions)
+ *
+ * @module
+ */
+export * from './recovery-analyzer.js';

package/dist/recovery/index.js

@@ -0,0 +1,11 @@
+/**
+ * Recovery Module
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Exports:
+ * - Recovery analysis (detect issues, suggest actions)
+ *
+ * @module
+ */
+export * from './recovery-analyzer.js';

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