@lumenflow/core 1.5.0 → 2.0.0

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/ports/wu-helpers.ports.d.ts

@@ -0,0 +1,224 @@
+/**
+ * WU Helpers Port Interfaces
+ *
+ * WU-1102: INIT-003 Phase 2b - Port interfaces for WU helper modules
+ *
+ * Hexagonal Architecture - Input Ports:
+ * These abstractions allow external users to inject custom implementations
+ * for WU lifecycle operations.
+ *
+ * @module ports/wu-helpers
+ */
+/**
+ * Git adapter interface for ensureOnMain and ensureMainUpToDate operations
+ */
+export interface IWuGitAdapter {
+    /**
+     * Get the current git branch name
+     * @returns Promise resolving to branch name
+     */
+    getCurrentBranch(): Promise<string>;
+    /**
+     * Fetch from a remote
+     * @param remote - Remote name (e.g., 'origin')
+     * @param branch - Branch name (e.g., 'main')
+     */
+    fetch(remote: string, branch: string): Promise<void>;
+    /**
+     * Get commit hash for a ref
+     * @param ref - Git ref (branch, tag, or commit)
+     * @returns Promise resolving to commit hash
+     */
+    getCommitHash(ref: string): Promise<string>;
+}
+/**
+ * WU status check result
+ */
+export interface IWuStatusCheckResult {
+    /** Whether the operation is allowed */
+    allowed: boolean;
+    /** Current WU status */
+    status: string | null;
+    /** Error message if not allowed */
+    error: string | null;
+}
+/**
+ * Branch validation result
+ */
+export interface IBranchValidationResult {
+    /** Whether the branch name is valid */
+    valid: boolean;
+    /** Lane name (kebab-case) or null */
+    lane: string | null;
+    /** WU ID (uppercase) or null */
+    wuid: string | null;
+    /** Error message if invalid */
+    error: string | null;
+}
+/**
+ * WU YAML reader interface
+ */
+export interface IWuYamlReader {
+    /**
+     * Read and parse WU YAML file
+     * @param wuPath - Path to WU YAML file
+     * @param expectedId - Expected WU ID for validation
+     * @returns Parsed WU document
+     */
+    readWU(wuPath: string, expectedId: string): unknown;
+    /**
+     * Read YAML file without ID validation
+     * @param yamlPath - Path to YAML file
+     * @returns Parsed document
+     */
+    readWURaw(yamlPath: string): unknown;
+}
+/**
+ * WU YAML writer interface
+ */
+export interface IWuYamlWriter {
+    /**
+     * Write WU document to file
+     * @param wuPath - Path to WU YAML file
+     * @param doc - Document to write
+     */
+    writeWU(wuPath: string, doc: unknown): void;
+}
+/**
+ * WU state store interface (subset for dependency injection)
+ */
+export interface IWuStateStore {
+    /**
+     * Load state from events file
+     */
+    load(): Promise<void>;
+    /**
+     * Claim a WU (transition to in_progress)
+     * @param wuId - WU identifier
+     * @param lane - Lane name
+     * @param title - WU title
+     */
+    claim(wuId: string, lane: string, title: string): Promise<void>;
+    /**
+     * Complete a WU (transition to done)
+     * @param wuId - WU identifier
+     */
+    complete(wuId: string): Promise<void>;
+    /**
+     * Block a WU (transition to blocked)
+     * @param wuId - WU identifier
+     * @param reason - Block reason
+     */
+    block(wuId: string, reason: string): Promise<void>;
+    /**
+     * Unblock a WU (transition back to in_progress)
+     * @param wuId - WU identifier
+     */
+    unblock(wuId: string): Promise<void>;
+    /**
+     * Release a WU (transition to ready)
+     * @param wuId - WU identifier
+     * @param reason - Release reason
+     */
+    release(wuId: string, reason: string): Promise<void>;
+    /**
+     * Get WU state entry
+     * @param wuId - WU identifier
+     * @returns State entry or undefined
+     */
+    getWUState(wuId: string): {
+        status: string;
+        lane: string;
+        title: string;
+    } | undefined;
+    /**
+     * Get all WU IDs by status
+     * @param status - Status to filter by
+     * @returns Set of WU IDs
+     */
+    getByStatus(status: string): Set<string>;
+    /**
+     * Get all WU IDs by lane
+     * @param lane - Lane to filter by
+     * @returns Set of WU IDs
+     */
+    getByLane(lane: string): Set<string>;
+}
+/**
+ * WU checkpoint interface
+ */
+export interface IWuCheckpointManager {
+    /**
+     * Create a pre-gates checkpoint
+     */
+    createPreGatesCheckpoint(params: {
+        wuId: string;
+        worktreePath: string;
+        branchName: string;
+        gatesPassed?: boolean;
+    }, options?: {
+        baseDir?: string;
+    }): Promise<{
+        checkpointId: string;
+        gatesPassed: boolean;
+    }>;
+    /**
+     * Mark checkpoint as gates passed
+     * @param wuId - WU identifier
+     * @returns True if updated
+     */
+    markGatesPassed(wuId: string, options?: {
+        baseDir?: string;
+    }): boolean;
+    /**
+     * Get checkpoint for a WU
+     * @param wuId - WU identifier
+     * @returns Checkpoint or null
+     */
+    getCheckpoint(wuId: string, options?: {
+        baseDir?: string;
+    }): {
+        gatesPassed: boolean;
+        worktreeHeadSha: string;
+    } | null;
+    /**
+     * Clear checkpoint
+     * @param wuId - WU identifier
+     */
+    clearCheckpoint(wuId: string, options?: {
+        baseDir?: string;
+    }): void;
+    /**
+     * Check if gates can be skipped
+     */
+    canSkipGates(wuId: string, options?: {
+        baseDir?: string;
+        currentHeadSha?: string;
+    }): {
+        canSkip: boolean;
+        reason?: string;
+    };
+}
+/**
+ * WU paths interface
+ */
+export interface IWuPaths {
+    /** Get path to WU YAML file */
+    WU(id: string): string;
+    /** Get path to WU directory */
+    WU_DIR(): string;
+    /** Get path to status.md */
+    STATUS(): string;
+    /** Get path to backlog.md */
+    BACKLOG(): string;
+    /** Get path to stamps directory */
+    STAMPS_DIR(): string;
+    /** Get path to WU done stamp file */
+    STAMP(id: string): string;
+    /** Get path to state directory */
+    STATE_DIR(): string;
+    /** Get path to initiatives directory */
+    INITIATIVES_DIR(): string;
+    /** Get path to worktrees directory */
+    WORKTREES_DIR(): string;
+}

package/dist/ports/wu-helpers.ports.js

@@ -0,0 +1,12 @@
+/**
+ * WU Helpers Port Interfaces
+ *
+ * WU-1102: INIT-003 Phase 2b - Port interfaces for WU helper modules
+ *
+ * Hexagonal Architecture - Input Ports:
+ * These abstractions allow external users to inject custom implementations
+ * for WU lifecycle operations.
+ *
+ * @module ports/wu-helpers
+ */
+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>;
+}