@lumenflow/core 1.5.0 → 2.0.0

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

package/dist/validation/types.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Validation Types for WU Context
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Type definitions for the unified context model, command definitions,
+ * and validation results.
+ *
+ * @module
+ */
+import type { LocationType, PredicateSeverity, ValidationErrorCode } from '../wu-constants.js';
+import type { LocationContext } from '../context/location-resolver.js';
+import type { GitState } from '../context/git-state-reader.js';
+/**
+ * WU state information from YAML and state store.
+ */
+export interface WuState {
+    /** WU ID (e.g., 'WU-1090') */
+    id: string;
+    /** Current status (ready, in_progress, blocked, done, etc.) */
+    status: string;
+    /** Lane name */
+    lane: string;
+    /** WU title */
+    title: string;
+    /** Path to WU YAML file */
+    yamlPath: string;
+    /** Whether YAML and state store are consistent */
+    isConsistent: boolean;
+    /** Reason for inconsistency if not consistent */
+    inconsistencyReason: string | null;
+}
+/**
+ * Session state for active WU work.
+ */
+export interface SessionState {
+    /** Whether a session is active */
+    isActive: boolean;
+    /** Session ID if active */
+    sessionId: string | null;
+}
+/**
+ * Unified context model for WU operations.
+ *
+ * Captures all environmental state relevant to command execution.
+ */
+export interface WuContext {
+    /** Location context (main vs worktree) */
+    location: LocationContext;
+    /** Git state (branch, dirty, staged, ahead/behind) */
+    git: GitState;
+    /** WU state (null if no WU specified) */
+    wu: WuState | null;
+    /** Session state */
+    session: SessionState;
+    /**
+     * Git state of the WU's worktree (WU-1092).
+     *
+     * When running wu:done from main checkout, we need to check the worktree's
+     * git state, not main's. This field is populated when:
+     * - Running from main checkout (location.type === 'main')
+     * - A WU is specified (wu !== null)
+     * - WU has an active worktree (status === 'in_progress')
+     *
+     * If undefined, predicates should fall back to checking `git.isDirty`.
+     */
+    worktreeGit?: GitState;
+}
+/**
+ * Command predicate for custom validation checks.
+ */
+export interface CommandPredicate {
+    /** Unique identifier for the predicate */
+    id: string;
+    /** Human-readable description */
+    description: string;
+    /** Severity: 'error' blocks execution, 'warning' allows with warning */
+    severity: PredicateSeverity;
+    /** Function that checks the predicate against context */
+    check: (context: WuContext) => boolean;
+    /** Function that generates fix message if check fails */
+    getFixMessage?: (context: WuContext) => string;
+}
+/**
+ * Command definition for a wu:* command.
+ */
+export interface CommandDefinition {
+    /** Command name (e.g., 'wu:create') */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Required location type (null = any location) */
+    requiredLocation: LocationType | null;
+    /** Required WU status (null = no status requirement) */
+    requiredWuStatus: string | null;
+    /** Custom predicates for additional checks */
+    predicates?: CommandPredicate[];
+    /** Function to get next steps after success */
+    getNextSteps?: (context: WuContext) => string[];
+}
+/**
+ * Validation error with fix guidance.
+ */
+export interface ValidationError {
+    /** Error code */
+    code: ValidationErrorCode;
+    /** Human-readable message */
+    message: string;
+    /** Copy-paste ready fix command (if available) */
+    fixCommand: string | null;
+    /** Additional context for debugging */
+    context?: Record<string, unknown>;
+}
+/**
+ * Validation warning (non-blocking).
+ */
+export interface ValidationWarning {
+    /** Warning ID */
+    id: string;
+    /** Human-readable message */
+    message: string;
+}
+/**
+ * Validation result for a command.
+ */
+export interface ValidationResult {
+    /** Whether command can proceed */
+    valid: boolean;
+    /** Errors that block execution */
+    errors: ValidationError[];
+    /** Warnings that don't block execution */
+    warnings: ValidationWarning[];
+    /** Context used for validation (for debugging) */
+    context: WuContext;
+}

package/dist/validation/types.js

@@ -0,0 +1,11 @@
+/**
+ * Validation Types for WU Context
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Type definitions for the unified context model, command definitions,
+ * and validation results.
+ *
+ * @module
+ */
+export {};

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

@@ -0,0 +1,27 @@
+/**
+ * Command Validation for WU Lifecycle Commands
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Validates commands against the current context and provides:
+ * - Location validation with copy-paste fix commands
+ * - WU status validation with guidance
+ * - Predicate validation with severity levels
+ *
+ * @module
+ */
+import type { ValidationResult, WuContext } from './types.js';
+/**
+ * Validate a command against the current context.
+ *
+ * Returns a ValidationResult with:
+ * - valid: boolean - whether command can proceed
+ * - errors: array of blocking errors with fix guidance
+ * - warnings: array of non-blocking warnings
+ * - context: the input context for debugging
+ *
+ * @param command - Command name (e.g., 'wu:done')
+ * @param context - Current WU context
+ * @returns ValidationResult
+ */
+export declare function validateCommand(command: string, context: WuContext): ValidationResult;

package/dist/validation/validate-command.js

@@ -0,0 +1,160 @@
+/**
+ * Command Validation for WU Lifecycle Commands
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Validates commands against the current context and provides:
+ * - Location validation with copy-paste fix commands
+ * - WU status validation with guidance
+ * - Predicate validation with severity levels
+ *
+ * @module
+ */
+import { CONTEXT_VALIDATION, } from '../wu-constants.js';
+import { getCommandDefinition } from './command-registry.js';
+const { LOCATION_TYPES, ERROR_CODES, SEVERITY } = CONTEXT_VALIDATION;
+/**
+ * Create a validation error with fix command.
+ */
+function createError(code, message, fixCommand = null, context) {
+    return { code, message, fixCommand, context };
+}
+/**
+ * Create a validation warning.
+ */
+function createWarning(id, message) {
+    return { id, message };
+}
+/**
+ * Get human-readable location name.
+ */
+function locationName(type) {
+    switch (type) {
+        case LOCATION_TYPES.MAIN:
+            return 'main checkout';
+        case LOCATION_TYPES.WORKTREE:
+            return 'worktree';
+        case LOCATION_TYPES.DETACHED:
+            return 'detached HEAD';
+        default:
+            return 'unknown location';
+    }
+}
+/**
+ * Validate location requirement.
+ */
+function validateLocation(def, context) {
+    if (def.requiredLocation === null)
+        return null;
+    const currentLocation = context.location.type;
+    if (currentLocation === def.requiredLocation)
+        return null;
+    const requiredName = locationName(def.requiredLocation);
+    const currentName = locationName(currentLocation);
+    // Generate copy-paste fix command with actual path
+    let fixCommand = null;
+    if (def.requiredLocation === LOCATION_TYPES.MAIN) {
+        fixCommand = `cd ${context.location.mainCheckout}`;
+    }
+    else if (def.requiredLocation === LOCATION_TYPES.WORKTREE) {
+        // If we know the WU ID, suggest the expected worktree path
+        if (context.wu?.id) {
+            const laneKebab = (context.wu.lane || 'lane').toLowerCase().replace(/[: ]+/g, '-');
+            const wuIdLower = context.wu.id.toLowerCase();
+            fixCommand = `cd ${context.location.mainCheckout}/worktrees/${laneKebab}-${wuIdLower}`;
+        }
+    }
+    return createError(ERROR_CODES.WRONG_LOCATION, `${def.name} requires ${requiredName}, but you are in ${currentName}`, fixCommand, {
+        required: def.requiredLocation,
+        current: currentLocation,
+    });
+}
+/**
+ * Validate WU status requirement.
+ */
+function validateWuStatus(def, context) {
+    // No status requirement means no WU needed
+    if (def.requiredWuStatus === null)
+        return null;
+    // Status requirement but no WU provided
+    if (context.wu === null) {
+        return createError(ERROR_CODES.WU_NOT_FOUND, `${def.name} requires a WU with status '${def.requiredWuStatus}', but no WU was specified`, null, { required: def.requiredWuStatus });
+    }
+    // Check if status matches
+    if (context.wu.status !== def.requiredWuStatus) {
+        return createError(ERROR_CODES.WRONG_WU_STATUS, `${def.name} requires WU status '${def.requiredWuStatus}', but ${context.wu.id} is '${context.wu.status}'`, null, {
+            required: def.requiredWuStatus,
+            current: context.wu.status,
+            wuId: context.wu.id,
+        });
+    }
+    return null;
+}
+/**
+ * Validate command predicates.
+ */
+function validatePredicates(def, context) {
+    const errors = [];
+    const warnings = [];
+    if (!def.predicates || def.predicates.length === 0) {
+        return { errors, warnings };
+    }
+    for (const predicate of def.predicates) {
+        const passed = predicate.check(context);
+        if (!passed) {
+            const fixMessage = predicate.getFixMessage ? predicate.getFixMessage(context) : null;
+            if (predicate.severity === SEVERITY.ERROR) {
+                errors.push(createError(ERROR_CODES.GATES_NOT_PASSED, // Using as generic predicate failure
+                predicate.description, fixMessage, { predicateId: predicate.id }));
+            }
+            else {
+                warnings.push(createWarning(predicate.id, predicate.description));
+            }
+        }
+    }
+    return { errors, warnings };
+}
+/**
+ * Validate a command against the current context.
+ *
+ * Returns a ValidationResult with:
+ * - valid: boolean - whether command can proceed
+ * - errors: array of blocking errors with fix guidance
+ * - warnings: array of non-blocking warnings
+ * - context: the input context for debugging
+ *
+ * @param command - Command name (e.g., 'wu:done')
+ * @param context - Current WU context
+ * @returns ValidationResult
+ */
+export function validateCommand(command, context) {
+    const errors = [];
+    const warnings = [];
+    // Get command definition
+    const def = getCommandDefinition(command);
+    if (!def) {
+        errors.push(createError(ERROR_CODES.WU_NOT_FOUND, // Reusing for unknown command
+        `Unknown command: ${command}`, null));
+        return { valid: false, errors, warnings, context };
+    }
+    // Validate location requirement
+    const locationError = validateLocation(def, context);
+    if (locationError) {
+        errors.push(locationError);
+    }
+    // Validate WU status requirement
+    const statusError = validateWuStatus(def, context);
+    if (statusError) {
+        errors.push(statusError);
+    }
+    // Validate predicates
+    const predicateResults = validatePredicates(def, context);
+    errors.push(...predicateResults.errors);
+    warnings.push(...predicateResults.warnings);
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+        context,
+    };
+}