@lumenflow/core 1.5.0 → 2.0.0

package/dist/adapters/validation-adapters.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Validation Adapters
+ *
+ * WU-1094: INIT-002 Phase 2 - Implement adapters and dependency injection
+ *
+ * Concrete adapter implementations for validation-related port interfaces.
+ * These adapters wrap the existing implementation functions to conform
+ * to the port interfaces, enabling dependency injection.
+ *
+ * Adapters:
+ * - CommandRegistryAdapter - Implements ICommandRegistry
+ *
+ * @module adapters/validation-adapters
+ */
+import type { ICommandRegistry, CommandDefinition, WuContext } from '../ports/validation.ports.js';
+/**
+ * CommandRegistryAdapter
+ *
+ * Implements ICommandRegistry by delegating to the command registry functions.
+ * Provides access to command definitions and context-based validation.
+ *
+ * @example
+ * // Use default adapter
+ * const adapter = new CommandRegistryAdapter();
+ * const def = adapter.getCommandDefinition('wu:done');
+ *
+ * @example
+ * // Use as port interface
+ * const registry: ICommandRegistry = new CommandRegistryAdapter();
+ */
+export declare class CommandRegistryAdapter implements 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.
+     *
+     * @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[];
+}

package/dist/adapters/validation-adapters.js

@@ -0,0 +1,59 @@
+/**
+ * Validation Adapters
+ *
+ * WU-1094: INIT-002 Phase 2 - Implement adapters and dependency injection
+ *
+ * Concrete adapter implementations for validation-related port interfaces.
+ * These adapters wrap the existing implementation functions to conform
+ * to the port interfaces, enabling dependency injection.
+ *
+ * Adapters:
+ * - CommandRegistryAdapter - Implements ICommandRegistry
+ *
+ * @module adapters/validation-adapters
+ */
+// Import existing implementations
+import { COMMAND_REGISTRY, getCommandDefinition, getValidCommandsForContext, } from '../validation/command-registry.js';
+/**
+ * CommandRegistryAdapter
+ *
+ * Implements ICommandRegistry by delegating to the command registry functions.
+ * Provides access to command definitions and context-based validation.
+ *
+ * @example
+ * // Use default adapter
+ * const adapter = new CommandRegistryAdapter();
+ * const def = adapter.getCommandDefinition('wu:done');
+ *
+ * @example
+ * // Use as port interface
+ * const registry: ICommandRegistry = new CommandRegistryAdapter();
+ */
+export class CommandRegistryAdapter {
+    /**
+     * Get command definition by name.
+     *
+     * @param command - Command name (e.g., 'wu:create', 'wu:done')
+     * @returns CommandDefinition or null if not found
+     */
+    getCommandDefinition(command) {
+        return getCommandDefinition(command);
+    }
+    /**
+     * Get all commands valid for the current context.
+     *
+     * @param context - Current WU context
+     * @returns Array of valid CommandDefinitions
+     */
+    getValidCommandsForContext(context) {
+        return getValidCommandsForContext(context);
+    }
+    /**
+     * Get all registered command definitions.
+     *
+     * @returns Array of all CommandDefinitions
+     */
+    getAllCommands() {
+        return Array.from(COMMAND_REGISTRY.values());
+    }
+}

package/dist/context/context-computer.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Context Computer for WU Operations
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ * WU-1092: Adds worktreeGit field for checking worktree state from main
+ *
+ * Computes the unified WuContext by gathering location, git, and WU state.
+ * Performance budget: <100ms for complete context computation.
+ *
+ * @module
+ */
+import type { WuContext } from '../validation/types.js';
+/**
+ * Options for computing context.
+ */
+export interface ComputeContextOptions {
+    /** Current working directory (defaults to process.cwd()) */
+    cwd?: string;
+    /** WU ID to look up (optional) */
+    wuId?: string;
+    /** Session ID if known */
+    sessionId?: string;
+}
+/**
+ * Result of context computation with timing.
+ */
+export interface ComputeContextResult {
+    /** The computed context */
+    context: WuContext;
+    /** Time taken to compute in milliseconds */
+    computationMs: number;
+    /** Whether computation exceeded budget */
+    exceededBudget: boolean;
+}
+/**
+ * Compute complete WuContext.
+ *
+ * Gathers location, git state, and WU state in parallel where possible.
+ * Performance budget: <100ms for complete computation.
+ *
+ * WU-1092: Also reads worktreeGit when running from main with in_progress WU.
+ *
+ * @param options - Options for context computation
+ * @returns Promise<ComputeContextResult> - Computed context with timing
+ */
+export declare function computeContext(options?: ComputeContextOptions): Promise<ComputeContextResult>;

package/dist/context/context-computer.js

@@ -0,0 +1,125 @@
+/**
+ * Context Computer for WU Operations
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ * WU-1092: Adds worktreeGit field for checking worktree state from main
+ *
+ * Computes the unified WuContext by gathering location, git, and WU state.
+ * Performance budget: <100ms for complete context computation.
+ *
+ * @module
+ */
+import { join } from 'node:path';
+import { CONTEXT_VALIDATION, WU_STATUS, getWorktreePath } from '../wu-constants.js';
+import { resolveLocation } from './location-resolver.js';
+import { readGitState } from './git-state-reader.js';
+import { readWuState } from './wu-state-reader.js';
+const { THRESHOLDS, LOCATION_TYPES } = CONTEXT_VALIDATION;
+/**
+ * Convert WuStateResult to WuState interface used in WuContext.
+ */
+function toWuState(result) {
+    return {
+        id: result.id,
+        status: result.status,
+        lane: result.lane,
+        title: result.title,
+        yamlPath: result.yamlPath,
+        isConsistent: result.isConsistent,
+        inconsistencyReason: result.inconsistencyReason,
+    };
+}
+/**
+ * Extract WU ID from context if available.
+ *
+ * Priority:
+ * 1. Explicit wuId option
+ * 2. WU ID from worktree path
+ */
+function getWuIdToLookup(options, location) {
+    if (options.wuId) {
+        return options.wuId;
+    }
+    if (location.worktreeWuId) {
+        return location.worktreeWuId;
+    }
+    return null;
+}
+/**
+ * Determine if we should read worktree git state (WU-1092).
+ *
+ * We need worktreeGit when:
+ * - Running from main checkout (not already in worktree)
+ * - WU is specified and found
+ * - WU is in_progress (implying worktree exists)
+ */
+function shouldReadWorktreeGit(location, wuState) {
+    return (location.type === LOCATION_TYPES.MAIN &&
+        wuState !== null &&
+        wuState.status === WU_STATUS.IN_PROGRESS);
+}
+/**
+ * Get the absolute path to a WU's worktree.
+ *
+ * @param mainCheckout - Path to main checkout
+ * @param lane - WU lane name
+ * @param wuId - WU ID
+ * @returns Absolute path to worktree
+ */
+function getWorktreeAbsolutePath(mainCheckout, lane, wuId) {
+    const relativePath = getWorktreePath(lane, wuId);
+    return join(mainCheckout, relativePath);
+}
+/**
+ * Compute complete WuContext.
+ *
+ * Gathers location, git state, and WU state in parallel where possible.
+ * Performance budget: <100ms for complete computation.
+ *
+ * WU-1092: Also reads worktreeGit when running from main with in_progress WU.
+ *
+ * @param options - Options for context computation
+ * @returns Promise<ComputeContextResult> - Computed context with timing
+ */
+export async function computeContext(options = {}) {
+    const startTime = performance.now();
+    const cwd = options.cwd ?? process.cwd();
+    // Step 1: Resolve location first (needed to determine WU ID and main checkout)
+    const location = await resolveLocation(cwd);
+    // Step 2: Get WU ID to look up
+    const wuId = getWuIdToLookup(options, location);
+    // Step 3: Read git state and WU state in parallel
+    const [gitState, wuStateResult] = await Promise.all([
+        readGitState(cwd),
+        wuId ? readWuState(wuId, location.mainCheckout) : Promise.resolve(null),
+    ]);
+    // Step 4: Build WU state (null if no WU found)
+    const wuState = wuStateResult ? toWuState(wuStateResult) : null;
+    // Step 5: Build session state
+    const session = {
+        isActive: !!options.sessionId,
+        sessionId: options.sessionId ?? null,
+    };
+    // Step 6: Read worktree git state if applicable (WU-1092)
+    let worktreeGit;
+    if (shouldReadWorktreeGit(location, wuState)) {
+        const worktreePath = getWorktreeAbsolutePath(location.mainCheckout, wuState.lane, wuState.id);
+        worktreeGit = await readGitState(worktreePath);
+    }
+    // Step 7: Build complete context
+    const context = {
+        location,
+        git: gitState,
+        wu: wuState,
+        session,
+        ...(worktreeGit !== undefined && { worktreeGit }),
+    };
+    const endTime = performance.now();
+    const computationMs = endTime - startTime;
+    const exceededBudget = computationMs > THRESHOLDS.CONTEXT_COMPUTATION_MS;
+    return {
+        context,
+        computationMs,
+        exceededBudget,
+    };
+}

package/dist/context/git-state-reader.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Git State Reader for WU Context
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Reads git state including:
+ * - Current branch
+ * - Dirty working tree (uncommitted changes)
+ * - Staged changes
+ * - Ahead/behind tracking branch
+ *
+ * Uses simple-git library (NOT execSync) per library-first mandate.
+ *
+ * @module
+ */
+/**
+ * Git state information for WU operations.
+ *
+ * Captures the current git state relevant to command execution.
+ */
+export interface GitState {
+    /** Current branch name (null if detached) */
+    branch: string | null;
+    /** Whether HEAD is detached */
+    isDetached: boolean;
+    /** Whether working tree has uncommitted changes */
+    isDirty: boolean;
+    /** Whether there are staged changes */
+    hasStaged: boolean;
+    /** Commits ahead of tracking branch */
+    ahead: number;
+    /** Commits behind tracking branch */
+    behind: number;
+    /** Tracking branch (e.g., 'origin/main') */
+    tracking: string | null;
+    /** List of modified files */
+    modifiedFiles: string[];
+    /** Whether an error occurred reading state */
+    hasError: boolean;
+    /** Error message if hasError is true */
+    errorMessage: string | null;
+}
+/**
+ * Read current git state using simple-git library.
+ *
+ * Uses git status to efficiently gather all state in one operation.
+ *
+ * @param cwd - Current working directory (defaults to process.cwd())
+ * @returns Promise<GitState> - Current git state
+ */
+export declare function readGitState(cwd?: string): Promise<GitState>;

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

@@ -0,0 +1,61 @@
+/**
+ * Git State Reader for WU Context
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Reads git state including:
+ * - Current branch
+ * - Dirty working tree (uncommitted changes)
+ * - Staged changes
+ * - Ahead/behind tracking branch
+ *
+ * Uses simple-git library (NOT execSync) per library-first mandate.
+ *
+ * @module
+ */
+import { simpleGit } from 'simple-git';
+/**
+ * Read current git state using simple-git library.
+ *
+ * Uses git status to efficiently gather all state in one operation.
+ *
+ * @param cwd - Current working directory (defaults to process.cwd())
+ * @returns Promise<GitState> - Current git state
+ */
+export async function readGitState(cwd = process.cwd()) {
+    try {
+        const git = simpleGit(cwd);
+        const status = await git.status();
+        // Determine if working tree is dirty
+        const isDirty = !status.isClean();
+        // Check for staged changes - simple-git provides staged array
+        const hasStaged = status.staged.length > 0;
+        return {
+            branch: status.current,
+            isDetached: status.detached === true,
+            isDirty,
+            hasStaged,
+            ahead: status.ahead,
+            behind: status.behind,
+            tracking: status.tracking,
+            modifiedFiles: status.modified || [],
+            hasError: false,
+            errorMessage: null,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            branch: null,
+            isDetached: false,
+            isDirty: false,
+            hasStaged: false,
+            ahead: 0,
+            behind: 0,
+            tracking: null,
+            modifiedFiles: [],
+            hasError: true,
+            errorMessage: message,
+        };
+    }
+}

package/dist/context/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Context Module
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Exports:
+ * - Location resolution (main vs worktree detection)
+ * - Git state reading (branch, dirty, staged, ahead/behind)
+ * - WU state reading (YAML + state store)
+ * - Context computation (unified context model)
+ *
+ * @module
+ */
+export * from './location-resolver.js';
+export * from './git-state-reader.js';
+export * from './wu-state-reader.js';
+export * from './context-computer.js';

package/dist/context/index.js

@@ -0,0 +1,17 @@
+/**
+ * Context Module
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Exports:
+ * - Location resolution (main vs worktree detection)
+ * - Git state reading (branch, dirty, staged, ahead/behind)
+ * - WU state reading (YAML + state store)
+ * - Context computation (unified context model)
+ *
+ * @module
+ */
+export * from './location-resolver.js';
+export * from './git-state-reader.js';
+export * from './wu-state-reader.js';
+export * from './context-computer.js';

package/dist/context/location-resolver.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Location Resolver for WU Context
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Detects whether the current working directory is:
+ * - Main checkout (primary repo clone)
+ * - Worktree (isolated workspace for a WU)
+ * - Detached HEAD
+ * - Unknown (not a git repository)
+ *
+ * Uses simple-git library (NOT execSync) per library-first mandate.
+ *
+ * @module
+ */
+import { type LocationType } from '../wu-constants.js';
+/**
+ * Location context information for WU operations.
+ *
+ * Captures where the command is being run from and related paths.
+ */
+export interface LocationContext {
+    /** Location type: 'main', 'worktree', 'detached', or 'unknown' */
+    type: LocationType;
+    /** Absolute path to current working directory */
+    cwd: string;
+    /** Absolute path to git root (top-level of working tree) */
+    gitRoot: string;
+    /** Absolute path to main checkout (primary repo) */
+    mainCheckout: string;
+    /** Worktree name if in a worktree (e.g., 'framework-core-wu-1090') */
+    worktreeName: string | null;
+    /** WU ID extracted from worktree path (e.g., 'WU-1090') */
+    worktreeWuId: string | null;
+}
+/**
+ * Resolve current location context using simple-git library.
+ *
+ * Detection logic:
+ * 1. Use simple-git revparse to find git root and git dir
+ * 2. If .git is a file (not dir), we're in a worktree
+ * 3. Parse worktree path to extract WU ID
+ * 4. Find main checkout via simple-git worktree list
+ *
+ * @param cwd - Current working directory (defaults to process.cwd())
+ * @returns Promise<LocationContext> - Resolved location context
+ */
+export declare function resolveLocation(cwd?: string): Promise<LocationContext>;

package/dist/context/location-resolver.js

@@ -0,0 +1,175 @@
+/**
+ * Location Resolver for WU Context
+ *
+ * WU-1090: Context-aware state machine for WU lifecycle commands
+ *
+ * Detects whether the current working directory is:
+ * - Main checkout (primary repo clone)
+ * - Worktree (isolated workspace for a WU)
+ * - Detached HEAD
+ * - Unknown (not a git repository)
+ *
+ * Uses simple-git library (NOT execSync) per library-first mandate.
+ *
+ * @module
+ */
+import { simpleGit } from 'simple-git';
+import { statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { CONTEXT_VALIDATION, PATTERNS } from '../wu-constants.js';
+const { LOCATION_TYPES } = CONTEXT_VALIDATION;
+/**
+ * Resolve current location context using simple-git library.
+ *
+ * Detection logic:
+ * 1. Use simple-git revparse to find git root and git dir
+ * 2. If .git is a file (not dir), we're in a worktree
+ * 3. Parse worktree path to extract WU ID
+ * 4. Find main checkout via simple-git worktree list
+ *
+ * @param cwd - Current working directory (defaults to process.cwd())
+ * @returns Promise<LocationContext> - Resolved location context
+ */
+export async function resolveLocation(cwd = process.cwd()) {
+    const resolvedCwd = resolve(cwd);
+    try {
+        const git = simpleGit(resolvedCwd);
+        // Get git root and git dir using simple-git revparse
+        const gitRoot = (await git.revparse(['--show-toplevel'])).trim();
+        const gitDir = (await git.revparse(['--git-dir'])).trim();
+        // Detect if we're in a worktree (in worktrees, .git is a file not a dir)
+        const isWorktree = isGitDirFile(gitDir);
+        const mainCheckout = isWorktree ? await findMainCheckout(git) : gitRoot;
+        // Parse worktree info
+        const worktreeName = isWorktree ? parseWorktreeName(gitRoot, mainCheckout) : null;
+        const worktreeWuId = worktreeName ? parseWuIdFromWorktree(worktreeName) : null;
+        // Check if HEAD is detached (WU-1096)
+        const isDetached = await isHeadDetached(git);
+        // Determine location type
+        const type = determineLocationType(gitRoot, mainCheckout, isWorktree, isDetached);
+        return {
+            type,
+            cwd: resolvedCwd,
+            gitRoot,
+            mainCheckout,
+            worktreeName,
+            worktreeWuId,
+        };
+    }
+    catch {
+        // Not a git repository or other error
+        return {
+            type: LOCATION_TYPES.UNKNOWN,
+            cwd: resolvedCwd,
+            gitRoot: resolvedCwd,
+            mainCheckout: resolvedCwd,
+            worktreeName: null,
+            worktreeWuId: null,
+        };
+    }
+}
+/**
+ * Check if git dir is a file (worktree) vs directory (main checkout)
+ *
+ * In a main checkout, .git is a directory containing the repository data.
+ * In a worktree, .git is a file that points to the main .git directory.
+ */
+function isGitDirFile(gitDir) {
+    try {
+        const stat = statSync(gitDir);
+        return stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Find main checkout path using simple-git worktree list
+ *
+ * The first worktree listed is always the main checkout.
+ */
+async function findMainCheckout(git) {
+    try {
+        // simple-git doesn't have direct worktree support, use raw command
+        const result = await git.raw(['worktree', 'list', '--porcelain']);
+        // First worktree listed is always the main checkout
+        // Format: "worktree /path/to/repo\nHEAD ...\nbranch ...\n\nworktree ..."
+        const match = result.match(/^worktree (.+)$/m);
+        return match ? match[1] : process.cwd();
+    }
+    catch {
+        return process.cwd();
+    }
+}
+/**
+ * Extract worktree name from path
+ *
+ * @example
+ * parseWorktreeName('/repo/worktrees/framework-core-wu-1090', '/repo')
+ * // Returns 'framework-core-wu-1090'
+ */
+function parseWorktreeName(gitRoot, mainCheckout) {
+    // Remove main checkout prefix to get relative path
+    let relativePath = gitRoot;
+    if (gitRoot.startsWith(mainCheckout)) {
+        relativePath = gitRoot.slice(mainCheckout.length);
+    }
+    // Remove leading slashes
+    relativePath = relativePath.replace(/^\/+/, '');
+    // The worktree name is the last path component
+    const parts = relativePath.split('/');
+    const lastPart = parts[parts.length - 1];
+    return lastPart || null;
+}
+/**
+ * Extract WU ID from worktree name
+ *
+ * Uses PATTERNS.WU_ID_EXTRACT_CI (case-insensitive) from wu-constants.ts
+ * because worktree names use lowercase (e.g., 'framework-core-wu-1090').
+ *
+ * @example
+ * parseWuIdFromWorktree('framework-core-wu-1090') // 'WU-1090'
+ * parseWuIdFromWorktree('some-feature') // null
+ */
+function parseWuIdFromWorktree(worktreeName) {
+    // Use case-insensitive pattern for worktree names
+    const match = worktreeName.match(PATTERNS.WU_ID_EXTRACT_CI);
+    return match ? match[0].toUpperCase() : null;
+}
+/**
+ * Check if HEAD is detached using git symbolic-ref
+ *
+ * WU-1096: Detect detached HEAD state and return DETACHED location type.
+ *
+ * When HEAD is attached to a branch, `git symbolic-ref HEAD` returns
+ * the ref name (e.g., 'refs/heads/main'). When detached, it fails
+ * with 'fatal: ref HEAD is not a symbolic ref'.
+ *
+ * @param git - SimpleGit instance
+ * @returns Promise<boolean> - true if HEAD is detached
+ */
+async function isHeadDetached(git) {
+    try {
+        // git symbolic-ref HEAD succeeds when HEAD is attached to a branch
+        await git.raw(['symbolic-ref', 'HEAD']);
+        return false; // HEAD is attached
+    }
+    catch {
+        // git symbolic-ref HEAD fails when HEAD is detached
+        return true;
+    }
+}
+/**
+ * Determine location type from context
+ *
+ * WU-1096: Added isDetached parameter to detect detached HEAD state.
+ */
+function determineLocationType(gitRoot, mainCheckout, isWorktree, isDetached = false) {
+    if (isWorktree)
+        return LOCATION_TYPES.WORKTREE;
+    if (isDetached)
+        return LOCATION_TYPES.DETACHED;
+    if (gitRoot === mainCheckout)
+        return LOCATION_TYPES.MAIN;
+    return LOCATION_TYPES.UNKNOWN;
+}

package/dist/context/wu-state-reader.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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
+ */
+/**
+ * Result of reading WU state.
+ */
+export interface WuStateResult {
+    /** WU ID (uppercase, e.g., 'WU-1090') */
+    id: string;
+    /** Current status from YAML */
+    status: string;
+    /** Lane name */
+    lane: string;
+    /** WU title */
+    title: string;
+    /** Absolute 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;
+}
+/**
+ * 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 declare function readWuState(wuId: string, repoRoot: string): Promise<WuStateResult | null>;