@lumenflow/core 1.5.0 → 2.0.0

package/dist/context/wu-state-reader.js

@@ -0,0 +1,76 @@
+/**
+ * WU State Reader for WU Context
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Reads WU state from YAML file and optionally cross-references
+ * with state store for inconsistency detection.
+ *
+ * @module
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { DIRECTORIES } from '../wu-constants.js';
+/**
+ * Normalize WU ID to uppercase format.
+ */
+function normalizeWuId(id) {
+    const upper = id.toUpperCase();
+    // Ensure it starts with WU-
+    if (upper.startsWith('WU-'))
+        return upper;
+    return `WU-${upper.replace(/^WU-?/i, '')}`;
+}
+/**
+ * Build the path to WU YAML file.
+ */
+function getWuYamlPath(wuId, repoRoot) {
+    const normalizedId = normalizeWuId(wuId);
+    return join(repoRoot, DIRECTORIES.WU_DIR, `${normalizedId}.yaml`);
+}
+/**
+ * Read WU state from YAML and detect inconsistencies.
+ *
+ * @param wuId - WU ID (e.g., 'WU-1090' or 'wu-1090')
+ * @param repoRoot - Repository root path
+ * @returns WuStateResult or null if WU not found
+ */
+export async function readWuState(wuId, repoRoot) {
+    const normalizedId = normalizeWuId(wuId);
+    const yamlPath = getWuYamlPath(normalizedId, repoRoot);
+    // Check if YAML exists
+    if (!existsSync(yamlPath)) {
+        return null;
+    }
+    try {
+        // Read and parse YAML
+        const content = readFileSync(yamlPath, 'utf8');
+        const yaml = parseYaml(content);
+        if (!yaml || typeof yaml !== 'object') {
+            return null;
+        }
+        // Extract fields with defaults
+        const status = yaml.status || 'unknown';
+        const lane = yaml.lane || '';
+        const title = yaml.title || '';
+        // For now, we consider YAML-only reading as consistent
+        // Full state store integration would compare with wu-events.jsonl
+        // That can be added when the state store is properly integrated
+        const isConsistent = true;
+        const inconsistencyReason = null;
+        return {
+            id: normalizedId,
+            status,
+            lane,
+            title,
+            yamlPath,
+            isConsistent,
+            inconsistencyReason,
+        };
+    }
+    catch {
+        // Parse error or read error
+        return null;
+    }
+}

package/dist/context-di.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Context Dependency Injection
+ *
+ * WU-1094: INIT-002 Phase 2 - Implement adapters and dependency injection
+ *
+ * Composition root for wiring concrete adapter implementations to use cases.
+ * This file provides factory functions for creating use cases with default
+ * or custom adapters.
+ *
+ * Design Principles:
+ * - Factory functions return fully wired use cases
+ * - Custom adapters can be injected for testing
+ * - Legacy function exports maintain backwards compatibility
+ *
+ * @module context-di
+ */
+import type { ILocationResolver, IGitStateReader, IWuStateReader } from './ports/context.ports.js';
+import type { ICommandRegistry } from './ports/validation.ports.js';
+import type { IRecoveryAnalyzer, WuContext, RecoveryAnalysis } from './ports/recovery.ports.js';
+import type { ValidationResult } from './validation/types.js';
+import { ComputeContextUseCase, type ComputeContextOptions } from './usecases/compute-context.usecase.js';
+import { ValidateCommandUseCase } from './usecases/validate-command.usecase.js';
+import { AnalyzeRecoveryUseCase } from './usecases/analyze-recovery.usecase.js';
+/**
+ * Context adapters bundle.
+ */
+export interface ContextAdapters {
+    locationResolver: ILocationResolver;
+    gitStateReader: IGitStateReader;
+    wuStateReader: IWuStateReader;
+}
+/**
+ * Create all context adapters with default implementations.
+ *
+ * @example
+ * const adapters = createContextAdapters();
+ * const location = await adapters.locationResolver.resolveLocation();
+ */
+export declare function createContextAdapters(): ContextAdapters;
+/**
+ * Validation adapters bundle.
+ */
+export interface ValidationAdapters {
+    commandRegistry: ICommandRegistry;
+}
+/**
+ * Create all validation adapters with default implementations.
+ *
+ * @example
+ * const adapters = createValidationAdapters();
+ * const def = adapters.commandRegistry.getCommandDefinition('wu:done');
+ */
+export declare function createValidationAdapters(): ValidationAdapters;
+/**
+ * Recovery adapters bundle.
+ */
+export interface RecoveryAdapters {
+    recoveryAnalyzer: IRecoveryAnalyzer;
+}
+/**
+ * Create all recovery adapters with default implementations.
+ *
+ * @example
+ * const adapters = createRecoveryAdapters();
+ * const analysis = await adapters.recoveryAnalyzer.analyzeRecovery(context);
+ */
+export declare function createRecoveryAdapters(): RecoveryAdapters;
+/**
+ * Options for creating ComputeContextUseCase.
+ * All adapters are optional - defaults will be used if not provided.
+ */
+export interface CreateComputeContextOptions {
+    locationResolver?: ILocationResolver;
+    gitStateReader?: IGitStateReader;
+    wuStateReader?: IWuStateReader;
+}
+/**
+ * Create a ComputeContextUseCase with default or custom adapters.
+ *
+ * @example
+ * // Use default adapters
+ * const useCase = createComputeContextUseCase();
+ * const context = await useCase.execute({ wuId: 'WU-1094' });
+ *
+ * @example
+ * // Use custom adapters for testing
+ * const useCase = createComputeContextUseCase({
+ *   locationResolver: mockLocationResolver,
+ * });
+ */
+export declare function createComputeContextUseCase(options?: CreateComputeContextOptions): ComputeContextUseCase;
+/**
+ * Options for creating ValidateCommandUseCase.
+ */
+export interface CreateValidateCommandOptions {
+    commandRegistry?: ICommandRegistry;
+}
+/**
+ * Create a ValidateCommandUseCase with default or custom registry.
+ *
+ * @example
+ * // Use default registry
+ * const useCase = createValidateCommandUseCase();
+ * const result = await useCase.execute('wu:done', context);
+ *
+ * @example
+ * // Use custom registry for testing
+ * const useCase = createValidateCommandUseCase({
+ *   commandRegistry: mockRegistry,
+ * });
+ */
+export declare function createValidateCommandUseCase(options?: CreateValidateCommandOptions): ValidateCommandUseCase;
+/**
+ * Options for creating AnalyzeRecoveryUseCase.
+ */
+export interface CreateAnalyzeRecoveryOptions {
+    recoveryAnalyzer?: IRecoveryAnalyzer;
+}
+/**
+ * Create an AnalyzeRecoveryUseCase with default or custom analyzer.
+ *
+ * @example
+ * // Use default analyzer
+ * const useCase = createAnalyzeRecoveryUseCase();
+ * const analysis = await useCase.execute(context);
+ *
+ * @example
+ * // Use custom analyzer for testing
+ * const useCase = createAnalyzeRecoveryUseCase({
+ *   recoveryAnalyzer: mockAnalyzer,
+ * });
+ */
+export declare function createAnalyzeRecoveryUseCase(options?: CreateAnalyzeRecoveryOptions): AnalyzeRecoveryUseCase;
+/**
+ * Compute WU context for the given options.
+ *
+ * This is a convenience function that creates a use case with default adapters
+ * and executes it. Use createComputeContextUseCase() for more control.
+ *
+ * @param options - Options including optional wuId and cwd
+ * @returns Promise<WuContext> - Computed WU context
+ *
+ * @example
+ * const context = await computeWuContext({ wuId: 'WU-1094' });
+ * console.log(context.location.type); // 'main' or 'worktree'
+ */
+export declare function computeWuContext(options?: ComputeContextOptions): Promise<WuContext>;
+/**
+ * Validate a command against the given context.
+ *
+ * This is a convenience function that creates a use case with default registry
+ * and executes it. Use createValidateCommandUseCase() for more control.
+ *
+ * @param command - Command name (e.g., 'wu:done')
+ * @param context - Current WU context
+ * @returns Promise<ValidationResult> - Validation result
+ *
+ * @example
+ * const context = await computeWuContext({ wuId: 'WU-1094' });
+ * const result = await validateCommand('wu:done', context);
+ * if (!result.valid) {
+ *   console.error(result.errors[0].message);
+ * }
+ */
+export declare function validateCommand(command: string, context: WuContext): Promise<ValidationResult>;
+/**
+ * Analyze recovery issues for the given context.
+ *
+ * This is a convenience function that creates a use case with default analyzer
+ * and executes it. Use createAnalyzeRecoveryUseCase() for more control.
+ *
+ * @param context - Current WU context
+ * @returns Promise<RecoveryAnalysis> - Recovery analysis
+ *
+ * @example
+ * const context = await computeWuContext({ wuId: 'WU-1094' });
+ * const analysis = await analyzeRecoveryIssues(context);
+ * if (analysis.hasIssues) {
+ *   console.log('Issues:', analysis.issues);
+ *   console.log('Suggested actions:', analysis.actions);
+ * }
+ */
+export declare function analyzeRecoveryIssues(context: WuContext): Promise<RecoveryAnalysis>;
+export type { ComputeContextOptions };

package/dist/context-di.js

@@ -0,0 +1,178 @@
+/**
+ * Context Dependency Injection
+ *
+ * WU-1094: INIT-002 Phase 2 - Implement adapters and dependency injection
+ *
+ * Composition root for wiring concrete adapter implementations to use cases.
+ * This file provides factory functions for creating use cases with default
+ * or custom adapters.
+ *
+ * Design Principles:
+ * - Factory functions return fully wired use cases
+ * - Custom adapters can be injected for testing
+ * - Legacy function exports maintain backwards compatibility
+ *
+ * @module context-di
+ */
+// Import adapters
+import { SimpleGitLocationAdapter, SimpleGitStateAdapter, FileSystemWuStateAdapter, } from './adapters/context-adapters.js';
+import { CommandRegistryAdapter } from './adapters/validation-adapters.js';
+import { RecoveryAnalyzerAdapter } from './adapters/recovery-adapters.js';
+// Import use cases
+import { ComputeContextUseCase, } from './usecases/compute-context.usecase.js';
+import { ValidateCommandUseCase } from './usecases/validate-command.usecase.js';
+import { AnalyzeRecoveryUseCase } from './usecases/analyze-recovery.usecase.js';
+/**
+ * Create all context adapters with default implementations.
+ *
+ * @example
+ * const adapters = createContextAdapters();
+ * const location = await adapters.locationResolver.resolveLocation();
+ */
+export function createContextAdapters() {
+    return {
+        locationResolver: new SimpleGitLocationAdapter(),
+        gitStateReader: new SimpleGitStateAdapter(),
+        wuStateReader: new FileSystemWuStateAdapter(),
+    };
+}
+/**
+ * Create all validation adapters with default implementations.
+ *
+ * @example
+ * const adapters = createValidationAdapters();
+ * const def = adapters.commandRegistry.getCommandDefinition('wu:done');
+ */
+export function createValidationAdapters() {
+    return {
+        commandRegistry: new CommandRegistryAdapter(),
+    };
+}
+/**
+ * Create all recovery adapters with default implementations.
+ *
+ * @example
+ * const adapters = createRecoveryAdapters();
+ * const analysis = await adapters.recoveryAnalyzer.analyzeRecovery(context);
+ */
+export function createRecoveryAdapters() {
+    return {
+        recoveryAnalyzer: new RecoveryAnalyzerAdapter(),
+    };
+}
+/**
+ * Create a ComputeContextUseCase with default or custom adapters.
+ *
+ * @example
+ * // Use default adapters
+ * const useCase = createComputeContextUseCase();
+ * const context = await useCase.execute({ wuId: 'WU-1094' });
+ *
+ * @example
+ * // Use custom adapters for testing
+ * const useCase = createComputeContextUseCase({
+ *   locationResolver: mockLocationResolver,
+ * });
+ */
+export function createComputeContextUseCase(options = {}) {
+    const defaults = createContextAdapters();
+    return new ComputeContextUseCase(options.locationResolver ?? defaults.locationResolver, options.gitStateReader ?? defaults.gitStateReader, options.wuStateReader ?? defaults.wuStateReader);
+}
+/**
+ * Create a ValidateCommandUseCase with default or custom registry.
+ *
+ * @example
+ * // Use default registry
+ * const useCase = createValidateCommandUseCase();
+ * const result = await useCase.execute('wu:done', context);
+ *
+ * @example
+ * // Use custom registry for testing
+ * const useCase = createValidateCommandUseCase({
+ *   commandRegistry: mockRegistry,
+ * });
+ */
+export function createValidateCommandUseCase(options = {}) {
+    const defaults = createValidationAdapters();
+    return new ValidateCommandUseCase(options.commandRegistry ?? defaults.commandRegistry);
+}
+/**
+ * Create an AnalyzeRecoveryUseCase with default or custom analyzer.
+ *
+ * @example
+ * // Use default analyzer
+ * const useCase = createAnalyzeRecoveryUseCase();
+ * const analysis = await useCase.execute(context);
+ *
+ * @example
+ * // Use custom analyzer for testing
+ * const useCase = createAnalyzeRecoveryUseCase({
+ *   recoveryAnalyzer: mockAnalyzer,
+ * });
+ */
+export function createAnalyzeRecoveryUseCase(options = {}) {
+    const defaults = createRecoveryAdapters();
+    return new AnalyzeRecoveryUseCase(options.recoveryAnalyzer ?? defaults.recoveryAnalyzer);
+}
+// ============================================================================
+// Backwards Compatible Function Exports
+// ============================================================================
+/**
+ * Compute WU context for the given options.
+ *
+ * This is a convenience function that creates a use case with default adapters
+ * and executes it. Use createComputeContextUseCase() for more control.
+ *
+ * @param options - Options including optional wuId and cwd
+ * @returns Promise<WuContext> - Computed WU context
+ *
+ * @example
+ * const context = await computeWuContext({ wuId: 'WU-1094' });
+ * console.log(context.location.type); // 'main' or 'worktree'
+ */
+export async function computeWuContext(options = {}) {
+    const useCase = createComputeContextUseCase();
+    return useCase.execute(options);
+}
+/**
+ * Validate a command against the given context.
+ *
+ * This is a convenience function that creates a use case with default registry
+ * and executes it. Use createValidateCommandUseCase() for more control.
+ *
+ * @param command - Command name (e.g., 'wu:done')
+ * @param context - Current WU context
+ * @returns Promise<ValidationResult> - Validation result
+ *
+ * @example
+ * const context = await computeWuContext({ wuId: 'WU-1094' });
+ * const result = await validateCommand('wu:done', context);
+ * if (!result.valid) {
+ *   console.error(result.errors[0].message);
+ * }
+ */
+export async function validateCommand(command, context) {
+    const useCase = createValidateCommandUseCase();
+    return useCase.execute(command, context);
+}
+/**
+ * Analyze recovery issues for the given context.
+ *
+ * This is a convenience function that creates a use case with default analyzer
+ * and executes it. Use createAnalyzeRecoveryUseCase() for more control.
+ *
+ * @param context - Current WU context
+ * @returns Promise<RecoveryAnalysis> - Recovery analysis
+ *
+ * @example
+ * const context = await computeWuContext({ wuId: 'WU-1094' });
+ * const analysis = await analyzeRecoveryIssues(context);
+ * if (analysis.hasIssues) {
+ *   console.log('Issues:', analysis.issues);
+ *   console.log('Suggested actions:', analysis.actions);
+ * }
+ */
+export async function analyzeRecoveryIssues(context) {
+    const useCase = createAnalyzeRecoveryUseCase();
+    return useCase.execute(context);
+}

package/dist/context-validation-integration.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Context Validation Integration
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Shared module for integrating context validation into CLI commands.
+ * Reads validation_mode from config and applies validation accordingly.
+ *
+ * @module
+ */
+import type { WuContext, ValidationResult } from './validation/types.js';
+declare const COMMANDS: {
+    readonly WU_CREATE: "wu:create";
+    readonly WU_CLAIM: "wu:claim";
+    readonly WU_DONE: "wu:done";
+    readonly WU_BLOCK: "wu:block";
+    readonly WU_UNBLOCK: "wu:unblock";
+    readonly WU_STATUS: "wu:status";
+    readonly WU_RECOVER: "wu:recover";
+    readonly GATES: "gates";
+};
+/**
+ * Validation mode from config
+ */
+export type ValidationMode = 'off' | 'warn' | 'error';
+/**
+ * Result of running context validation
+ */
+export interface ContextValidationResult {
+    /** Whether the command can proceed */
+    canProceed: boolean;
+    /** The computed context */
+    context: WuContext;
+    /** Validation result (null if validation was off) */
+    validation: ValidationResult | null;
+    /** Validation mode that was applied */
+    mode: ValidationMode;
+    /** Formatted output for display (if any) */
+    output: string | null;
+}
+/**
+ * Get validation mode from config
+ */
+export declare function getValidationMode(): ValidationMode;
+/**
+ * Check if next steps should be shown
+ */
+export declare function shouldShowNextSteps(): boolean;
+/**
+ * Format next steps for display
+ */
+export declare function formatNextSteps(context: WuContext, commandName: string): string;
+/**
+ * Run context validation for a command
+ *
+ * @param commandName - The wu:* command name (e.g., 'wu:claim')
+ * @param wuId - Optional WU ID for context
+ * @returns ContextValidationResult
+ */
+export declare function runContextValidation(commandName: string, wuId?: string): Promise<ContextValidationResult>;
+/**
+ * Apply context validation to a command
+ *
+ * This is the main integration function. It:
+ * 1. Runs validation according to config
+ * 2. Logs warnings/errors as appropriate
+ * 3. Returns whether the command should proceed
+ * 4. Exits with error if mode is 'error' and validation fails
+ *
+ * @param commandName - The wu:* command name
+ * @param wuId - Optional WU ID for context
+ * @param logPrefix - Log prefix for output
+ * @returns The computed context if validation passes
+ * @throws Exits process if mode is 'error' and validation fails
+ */
+export declare function applyContextValidation(commandName: string, wuId?: string, logPrefix?: string): Promise<WuContext>;
+export { COMMANDS };

package/dist/context-validation-integration.js

@@ -0,0 +1,157 @@
+/**
+ * Context Validation Integration
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Shared module for integrating context validation into CLI commands.
+ * Reads validation_mode from config and applies validation accordingly.
+ *
+ * @module
+ */
+import { computeContext } from './context/context-computer.js';
+import { validateCommand } from './validation/validate-command.js';
+import { getValidCommandsForContext } from './validation/command-registry.js';
+import { getConfig } from './lumenflow-config.js';
+import { EMOJI, CONTEXT_VALIDATION } from './wu-constants.js';
+const { COMMANDS } = CONTEXT_VALIDATION;
+/**
+ * Get validation mode from config
+ */
+export function getValidationMode() {
+    try {
+        const config = getConfig();
+        const experimental = config?.experimental;
+        if (!experimental?.context_validation) {
+            return 'off';
+        }
+        return experimental.validation_mode || 'warn';
+    }
+    catch {
+        // Config not available, default to warn
+        return 'warn';
+    }
+}
+/**
+ * Check if next steps should be shown
+ */
+export function shouldShowNextSteps() {
+    try {
+        const config = getConfig();
+        return config?.experimental?.show_next_steps !== false;
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Format validation errors for display
+ */
+function formatErrors(validation) {
+    const lines = [];
+    for (const error of validation.errors) {
+        lines.push(`${EMOJI.FAILURE} ${error.code}: ${error.message}`);
+        if (error.fixCommand) {
+            lines.push(`   Fix: ${error.fixCommand}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Format validation warnings for display
+ */
+function formatWarnings(validation) {
+    const lines = [];
+    for (const warning of validation.warnings) {
+        lines.push(`${EMOJI.WARNING} ${warning.id}: ${warning.message}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Format next steps for display
+ */
+export function formatNextSteps(context, commandName) {
+    const validCommands = getValidCommandsForContext(context);
+    const commandDef = validCommands.find((c) => c.name === commandName);
+    if (!commandDef?.getNextSteps) {
+        return '';
+    }
+    const steps = commandDef.getNextSteps(context);
+    if (steps.length === 0) {
+        return '';
+    }
+    return '\n## Next Steps\n' + steps.map((s) => `  ${s}`).join('\n');
+}
+/**
+ * Run context validation for a command
+ *
+ * @param commandName - The wu:* command name (e.g., 'wu:claim')
+ * @param wuId - Optional WU ID for context
+ * @returns ContextValidationResult
+ */
+export async function runContextValidation(commandName, wuId) {
+    const mode = getValidationMode();
+    // Compute context
+    const { context } = await computeContext({ wuId });
+    // If validation is off, just return context
+    if (mode === 'off') {
+        return {
+            canProceed: true,
+            context,
+            validation: null,
+            mode,
+            output: null,
+        };
+    }
+    // Run validation
+    const validation = validateCommand(commandName, context);
+    // Format output
+    let output = null;
+    if (!validation.valid) {
+        output = formatErrors(validation);
+    }
+    else if (validation.warnings.length > 0) {
+        output = formatWarnings(validation);
+    }
+    // Determine if command can proceed
+    const canProceed = mode === 'warn' || validation.valid;
+    return {
+        canProceed,
+        context,
+        validation,
+        mode,
+        output,
+    };
+}
+/**
+ * Apply context validation to a command
+ *
+ * This is the main integration function. It:
+ * 1. Runs validation according to config
+ * 2. Logs warnings/errors as appropriate
+ * 3. Returns whether the command should proceed
+ * 4. Exits with error if mode is 'error' and validation fails
+ *
+ * @param commandName - The wu:* command name
+ * @param wuId - Optional WU ID for context
+ * @param logPrefix - Log prefix for output
+ * @returns The computed context if validation passes
+ * @throws Exits process if mode is 'error' and validation fails
+ */
+export async function applyContextValidation(commandName, wuId, logPrefix = '[context]') {
+    const result = await runContextValidation(commandName, wuId);
+    // Log output if any
+    if (result.output) {
+        if (result.mode === 'error' && !result.canProceed) {
+            console.error(`${logPrefix} Context validation failed:`);
+            console.error(result.output);
+            process.exit(1);
+        }
+        else if (result.mode === 'warn') {
+            console.warn(`${logPrefix} Context validation warnings:`);
+            console.warn(result.output);
+        }
+    }
+    return result.context;
+}
+// Re-export commands for convenience
+export { COMMANDS };