@lumenflow/core 1.0.0

package/dist/wu-paths.d.ts

@@ -0,0 +1,171 @@
+/**
+ * WU Paths - Centralized path management for Work Units
+ *
+ * All paths are configurable via .lumenflow.config.yaml
+ *
+ * @module wu-paths
+ */
+/**
+ * Resolve repo root from an absolute file path by traversing up N directory levels.
+ *
+ * @param absolutePath - Absolute path to a file within the repo
+ * @param depth - Number of directory levels to traverse up
+ * @returns Absolute path to repo root
+ */
+export declare function resolveRepoRoot(absolutePath: string, depth: number): string;
+/**
+ * Get the state store directory path from backlog.md path.
+ *
+ * @param backlogPath - Absolute path to backlog.md
+ * @returns Absolute path to state store directory
+ */
+export declare function getStateStoreDirFromBacklog(backlogPath: string): string;
+/**
+ * Create WU paths object with configurable base paths
+ *
+ * @param options - Options for path generation
+ * @param options.projectRoot - Override project root
+ * @returns WU paths object
+ */
+export declare function createWuPaths(options?: {
+    projectRoot?: string;
+}): {
+    /**
+     * Get path to WU YAML file
+     * @param id - WU ID (e.g., 'WU-123')
+     * @returns Path to WU YAML file
+     */
+    WU: (id: string) => string;
+    /**
+     * Get path to WU directory
+     * @returns Path to WU directory
+     */
+    WU_DIR: () => string;
+    /**
+     * Get path to status.md
+     * @returns Path to status.md
+     */
+    STATUS: () => string;
+    /**
+     * Get path to backlog.md
+     * @returns Path to backlog.md
+     */
+    BACKLOG: () => string;
+    /**
+     * Get path to stamps directory
+     * @returns Path to stamps directory
+     */
+    STAMPS_DIR: () => string;
+    /**
+     * Get path to WU done stamp file
+     * @param id - WU ID (e.g., 'WU-123')
+     * @returns Path to stamp file
+     */
+    STAMP: (id: string) => string;
+    /**
+     * Get path to state directory
+     * @returns Path to state directory
+     */
+    STATE_DIR: () => string;
+    /**
+     * Get path to initiatives directory
+     * @returns Path to initiatives directory
+     */
+    INITIATIVES_DIR: () => string;
+    /**
+     * Get path to worktrees directory
+     * @returns Path to worktrees directory
+     */
+    WORKTREES_DIR: () => string;
+};
+/**
+ * Default WU paths using default config
+ * For backwards compatibility with existing code
+ */
+export declare const WU_PATHS: {
+    /**
+     * Get path to WU YAML file
+     * @param id - WU ID (e.g., 'WU-123')
+     * @returns Path to WU YAML file
+     */
+    WU: (id: string) => string;
+    /**
+     * Get path to WU directory
+     * @returns Path to WU directory
+     */
+    WU_DIR: () => string;
+    /**
+     * Get path to status.md
+     * @returns Path to status.md
+     */
+    STATUS: () => string;
+    /**
+     * Get path to backlog.md
+     * @returns Path to backlog.md
+     */
+    BACKLOG: () => string;
+    /**
+     * Get path to stamps directory
+     * @returns Path to stamps directory
+     */
+    STAMPS_DIR: () => string;
+    /**
+     * Get path to WU done stamp file
+     * @param id - WU ID (e.g., 'WU-123')
+     * @returns Path to stamp file
+     */
+    STAMP: (id: string) => string;
+    /**
+     * Get path to state directory
+     * @returns Path to state directory
+     */
+    STATE_DIR: () => string;
+    /**
+     * Get path to initiatives directory
+     * @returns Path to initiatives directory
+     */
+    INITIATIVES_DIR: () => string;
+    /**
+     * Get path to worktrees directory
+     * @returns Path to worktrees directory
+     */
+    WORKTREES_DIR: () => string;
+};
+/**
+ * Generate default worktree path from WU document
+ *
+ * @param doc - WU document with lane and id fields
+ * @returns Worktree path or null if inputs are invalid
+ */
+export declare function defaultWorktreeFrom(doc: {
+    lane?: string;
+    id?: string;
+} | null | undefined): string | null;
+/**
+ * Resolve a repo-root-relative path to an absolute path using project root.
+ *
+ * @param relativePath - Path relative to project root
+ * @param moduleUrl - import.meta.url of the calling module (for backwards compat)
+ * @returns Absolute path resolved from project root
+ */
+export declare function resolveFromProjectRoot(relativePath: string, moduleUrl?: string): string;
+/**
+ * Get absolute path to WU YAML file
+ *
+ * @param id - WU ID (e.g., 'WU-123')
+ * @param options - Options
+ * @returns Absolute path to WU YAML file
+ */
+export declare function getAbsoluteWuPath(id: string, options?: {
+    projectRoot?: string;
+}): string;
+/**
+ * Get absolute path to stamp file
+ *
+ * @param id - WU ID (e.g., 'WU-123')
+ * @param options - Options
+ * @returns Absolute path to stamp file
+ */
+export declare function getAbsoluteStampPath(id: string, options?: {
+    projectRoot?: string;
+}): string;

package/dist/wu-paths.js

@@ -0,0 +1,178 @@
+/**
+ * WU Paths - Centralized path management for Work Units
+ *
+ * All paths are configurable via .lumenflow.config.yaml
+ *
+ * @module wu-paths
+ */
+import * as path from 'node:path';
+import { getWorktreePath, getProjectRoot as getProjectRootFromConstants } from './wu-constants.js';
+import { getConfig, getProjectRoot as getProjectRootFromConfig } from './lumenflow-config.js';
+/**
+ * Directory depth constants for path resolution.
+ * These define how many levels deep each standard file is from repo root.
+ */
+const PATH_DEPTHS = {
+    /** backlog.md is 4 levels deep: docs/04-operations/tasks/backlog.md */
+    BACKLOG: 4,
+    /** status.md is 4 levels deep: docs/04-operations/tasks/status.md */
+    STATUS: 4,
+    /** WU YAML files are 5 levels deep: docs/04-operations/tasks/wu/{id}.yaml */
+    WU_YAML: 5,
+    /** State store is 3 levels deep: .beacon/state/wu-events.jsonl */
+    STATE_STORE: 3,
+};
+/**
+ * Resolve repo root from an absolute file path by traversing up N directory levels.
+ *
+ * @param absolutePath - Absolute path to a file within the repo
+ * @param depth - Number of directory levels to traverse up
+ * @returns Absolute path to repo root
+ */
+export function resolveRepoRoot(absolutePath, depth) {
+    let result = absolutePath;
+    for (let i = 0; i < depth; i++) {
+        result = path.dirname(result);
+    }
+    return result;
+}
+/**
+ * Get the state store directory path from backlog.md path.
+ *
+ * @param backlogPath - Absolute path to backlog.md
+ * @returns Absolute path to state store directory
+ */
+export function getStateStoreDirFromBacklog(backlogPath) {
+    const config = getConfig();
+    const repoRoot = resolveRepoRoot(backlogPath, PATH_DEPTHS.BACKLOG);
+    return path.join(repoRoot, config.beacon.stateDir);
+}
+/**
+ * Create WU paths object with configurable base paths
+ *
+ * @param options - Options for path generation
+ * @param options.projectRoot - Override project root
+ * @returns WU paths object
+ */
+export function createWuPaths(options = {}) {
+    const config = getConfig({ projectRoot: options.projectRoot });
+    return {
+        /**
+         * Get path to WU YAML file
+         * @param id - WU ID (e.g., 'WU-123')
+         * @returns Path to WU YAML file
+         */
+        WU: (id) => path.join(config.directories.wuDir, `${id}.yaml`),
+        /**
+         * Get path to WU directory
+         * @returns Path to WU directory
+         */
+        WU_DIR: () => config.directories.wuDir,
+        /**
+         * Get path to status.md
+         * @returns Path to status.md
+         */
+        STATUS: () => config.directories.statusPath,
+        /**
+         * Get path to backlog.md
+         * @returns Path to backlog.md
+         */
+        BACKLOG: () => config.directories.backlogPath,
+        /**
+         * Get path to stamps directory
+         * @returns Path to stamps directory
+         */
+        STAMPS_DIR: () => config.beacon.stampsDir,
+        /**
+         * Get path to WU done stamp file
+         * @param id - WU ID (e.g., 'WU-123')
+         * @returns Path to stamp file
+         */
+        STAMP: (id) => path.join(config.beacon.stampsDir, `${id}.done`),
+        /**
+         * Get path to state directory
+         * @returns Path to state directory
+         */
+        STATE_DIR: () => config.beacon.stateDir,
+        /**
+         * Get path to initiatives directory
+         * @returns Path to initiatives directory
+         */
+        INITIATIVES_DIR: () => config.directories.initiativesDir,
+        /**
+         * Get path to worktrees directory
+         * @returns Path to worktrees directory
+         */
+        WORKTREES_DIR: () => config.directories.worktrees,
+    };
+}
+/**
+ * Default WU paths using default config
+ * For backwards compatibility with existing code
+ */
+export const WU_PATHS = createWuPaths();
+/**
+ * Generate default worktree path from WU document
+ *
+ * @param doc - WU document with lane and id fields
+ * @returns Worktree path or null if inputs are invalid
+ */
+export function defaultWorktreeFrom(doc) {
+    if (!doc)
+        return null;
+    const lane = doc.lane;
+    const id = doc.id;
+    // Validate inputs
+    if (!lane || !id)
+        return null;
+    // Convert to string and trim
+    const laneStr = String(lane).trim();
+    const idStr = String(id).trim();
+    // Check for empty strings after trimming
+    if (laneStr === '' || idStr === '')
+        return null;
+    // Use centralized getWorktreePath from wu-constants
+    return getWorktreePath(laneStr, idStr);
+}
+/**
+ * Resolve a repo-root-relative path to an absolute path using project root.
+ *
+ * @param relativePath - Path relative to project root
+ * @param moduleUrl - import.meta.url of the calling module (for backwards compat)
+ * @returns Absolute path resolved from project root
+ */
+export function resolveFromProjectRoot(relativePath, moduleUrl) {
+    // Try config-based project root first, fall back to constants-based
+    let projectRoot;
+    try {
+        projectRoot = getProjectRootFromConfig();
+    }
+    catch {
+        projectRoot = moduleUrl ? getProjectRootFromConstants(moduleUrl) : process.cwd();
+    }
+    return path.join(projectRoot, relativePath);
+}
+/**
+ * Get absolute path to WU YAML file
+ *
+ * @param id - WU ID (e.g., 'WU-123')
+ * @param options - Options
+ * @returns Absolute path to WU YAML file
+ */
+export function getAbsoluteWuPath(id, options = {}) {
+    const projectRoot = options.projectRoot || getProjectRootFromConfig();
+    const paths = createWuPaths({ projectRoot });
+    return path.join(projectRoot, paths.WU(id));
+}
+/**
+ * Get absolute path to stamp file
+ *
+ * @param id - WU ID (e.g., 'WU-123')
+ * @param options - Options
+ * @returns Absolute path to stamp file
+ */
+export function getAbsoluteStampPath(id, options = {}) {
+    const projectRoot = options.projectRoot || getProjectRootFromConfig();
+    const paths = createWuPaths({ projectRoot });
+    return path.join(projectRoot, paths.STAMP(id));
+}

package/dist/wu-preflight-validators.d.ts

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * Preflight validation functions for wu:preflight command
+ *
+ * WU-1803: Fast validation of code_paths and test paths before gates run.
+ * WU-1810: Upgraded to use canonical Zod schema validation (catches created format issues).
+ *
+ * This catches YAML mismatches early, saving time compared to full wu:done validation.
+ *
+ * Key validations:
+ * - WU YAML schema is valid (full canonical schema, not just required fields)
+ * - created field is YYYY-MM-DD format (fails fast on ISO timestamps)
+ * - code_paths files exist
+ * - test file paths exist (unit, e2e, integration - not manual)
+ *
+ * Design goals:
+ * - Complete in under 5 seconds
+ * - Clear error messages pointing to missing files
+ * - Reusable by wu:done for early validation
+ */
+/**
+ * Result structure for preflight validation
+ * @typedef {object} PreflightResult
+ * @property {boolean} valid - Whether all validations passed
+ * @property {string[]} errors - List of error messages
+ * @property {string[]} missingCodePaths - Code paths that don't exist
+ * @property {string[]} missingTestPaths - Test file paths that don't exist
+ */
+/**
+ * Create a PreflightResult object
+ *
+ * @param {object} params - Result parameters
+ * @param {boolean} params.valid - Whether validation passed
+ * @param {string[]} [params.errors=[]] - Error messages
+ * @param {string[]} [params.missingCodePaths=[]] - Missing code paths
+ * @param {string[]} [params.missingTestPaths=[]] - Missing test paths
+ * @returns {PreflightResult}
+ */
+export declare function createPreflightResult({ valid, errors, missingCodePaths, missingTestPaths, }: {
+    valid: any;
+    errors?: any[];
+    missingCodePaths?: any[];
+    missingTestPaths?: any[];
+}): {
+    valid: any;
+    errors: any[];
+    missingCodePaths: any[];
+    missingTestPaths: any[];
+};
+/**
+ * Run preflight validation for a WU
+ *
+ * Validates:
+ * 1. WU YAML schema is valid
+ * 2. code_paths files exist
+ * 3. test file paths exist (unit, e2e, integration)
+ *
+ * WU-1830: When worktreePath is provided, YAML is read from worktree (not rootDir).
+ * This ensures that when agent runs wu:edit to update code_paths in worktree,
+ * preflight validation uses the updated YAML, not stale main.
+ *
+ * @param {string} id - WU ID (e.g., 'WU-999')
+ * @param {ValidatePreflightOptions} [options={}] - Options
+ * @returns {Promise<PreflightResult>}
+ */
+export interface ValidatePreflightOptions {
+    /** Root directory for path resolution (fallback) */
+    rootDir?: string;
+    /** Worktree path (preferred source for YAML and file checks) */
+    worktreePath?: string | null;
+}
+export declare function validatePreflight(id: any, options?: ValidatePreflightOptions): Promise<{
+    valid: any;
+    errors: any[];
+    missingCodePaths: any[];
+    missingTestPaths: any[];
+}>;
+/**
+ * Format preflight result as user-friendly message
+ *
+ * @param {string} id - WU ID
+ * @param {PreflightResult} result - Validation result
+ * @returns {string} Formatted message
+ */
+export declare function formatPreflightResult(id: any, result: any): string;
+export declare const PreflightResult: {};

package/dist/wu-preflight-validators.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+/**
+ * Preflight validation functions for wu:preflight command
+ *
+ * WU-1803: Fast validation of code_paths and test paths before gates run.
+ * WU-1810: Upgraded to use canonical Zod schema validation (catches created format issues).
+ *
+ * This catches YAML mismatches early, saving time compared to full wu:done validation.
+ *
+ * Key validations:
+ * - WU YAML schema is valid (full canonical schema, not just required fields)
+ * - created field is YYYY-MM-DD format (fails fast on ISO timestamps)
+ * - code_paths files exist
+ * - test file paths exist (unit, e2e, integration - not manual)
+ *
+ * Design goals:
+ * - Complete in under 5 seconds
+ * - Clear error messages pointing to missing files
+ * - Reusable by wu:done for early validation
+ */
+/* eslint-disable security/detect-non-literal-fs-filename, security/detect-object-injection */
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { WU_PATHS } from './wu-paths.js';
+import { readWURaw } from './wu-yaml.js';
+import { TEST_TYPES, LOG_PREFIX, EMOJI } from './wu-constants.js';
+// WU-1810: Import canonical schema for full validation
+import { BaseWUSchema } from './wu-schema.js';
+// WU-1810: Import fixer to detect fixable issues
+import { detectFixableIssues, FIXABLE_ISSUES } from './wu-yaml-fixer.js';
+/**
+ * Result structure for preflight validation
+ * @typedef {object} PreflightResult
+ * @property {boolean} valid - Whether all validations passed
+ * @property {string[]} errors - List of error messages
+ * @property {string[]} missingCodePaths - Code paths that don't exist
+ * @property {string[]} missingTestPaths - Test file paths that don't exist
+ */
+/**
+ * Create a PreflightResult object
+ *
+ * @param {object} params - Result parameters
+ * @param {boolean} params.valid - Whether validation passed
+ * @param {string[]} [params.errors=[]] - Error messages
+ * @param {string[]} [params.missingCodePaths=[]] - Missing code paths
+ * @param {string[]} [params.missingTestPaths=[]] - Missing test paths
+ * @returns {PreflightResult}
+ */
+export function createPreflightResult({ valid, errors = [], missingCodePaths = [], missingTestPaths = [], }) {
+    return {
+        valid,
+        errors,
+        missingCodePaths,
+        missingTestPaths,
+    };
+}
+/**
+ * WU-1810: Validate WU YAML schema using canonical Zod schema
+ *
+ * Uses BaseWUSchema (structural validation) rather than minimal required fields.
+ * This catches created format issues, invalid type/status enums, etc. early.
+ *
+ * Special handling for created field:
+ * - Detects ISO timestamps and Date scalars via wu-yaml-fixer
+ * - Provides actionable error message suggesting auto-fix
+ *
+ * @param {object} doc - Parsed WU YAML document
+ * @param {string} id - Expected WU ID
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+function validateSchema(doc, id) {
+    const errors = [];
+    // Check ID matches (before schema validation for clear error)
+    if (doc.id !== id) {
+        errors.push(`WU ID mismatch: expected ${id}, found ${doc.id}`);
+    }
+    // WU-1810: Check for fixable issues (especially created field)
+    // This provides better error messages than raw Zod schema errors
+    const fixableIssues = detectFixableIssues(doc);
+    const createdIssue = fixableIssues.find((issue) => issue.type === FIXABLE_ISSUES.DATE_ISO_TIMESTAMP);
+    if (createdIssue) {
+        errors.push(`created field has invalid format: "${createdIssue.current}" is an ISO timestamp. ` +
+            `Expected YYYY-MM-DD format. Suggested fix: change to "${createdIssue.suggested}". ` +
+            `Fix by editing the WU YAML file (created: '${createdIssue.suggested}').`);
+    }
+    // WU-1810: Validate against canonical Zod schema
+    const schemaResult = BaseWUSchema.safeParse(doc);
+    if (!schemaResult.success) {
+        // Format Zod errors with field paths
+        for (const issue of schemaResult.error.issues) {
+            const fieldPath = issue.path.join('.');
+            const message = issue.message;
+            // Skip created errors if we already reported a fixable issue
+            if (fieldPath === 'created' && createdIssue) {
+                continue;
+            }
+            errors.push(`${fieldPath}: ${message}`);
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Validate code_paths files exist
+ *
+ * @param {string[]} codePaths - List of code paths from WU YAML
+ * @param {string} rootDir - Root directory to resolve paths against
+ * @returns {{ valid: boolean, errors: string[], missing: string[] }}
+ */
+function validateCodePathsExistence(codePaths, rootDir) {
+    if (!codePaths || !Array.isArray(codePaths) || codePaths.length === 0) {
+        return { valid: true, errors: [], missing: [] };
+    }
+    const missing = [];
+    for (const filePath of codePaths) {
+        if (!filePath || typeof filePath !== 'string')
+            continue;
+        const fullPath = path.join(rootDir, filePath);
+        if (!existsSync(fullPath)) {
+            missing.push(filePath);
+        }
+    }
+    if (missing.length > 0) {
+        const errors = [
+            `code_paths validation failed - ${missing.length} file(s) not found:`,
+            ...missing.map((p) => `  - ${p}`),
+        ];
+        return { valid: false, errors, missing };
+    }
+    return { valid: true, errors: [], missing: [] };
+}
+/**
+ * Validate test file paths exist (unit, e2e, integration - not manual)
+ *
+ * Manual tests are descriptions, not file paths, so they're skipped.
+ *
+ * @param {object} tests - tests object from WU YAML
+ * @param {string} rootDir - Root directory to resolve paths against
+ * @returns {{ valid: boolean, errors: string[], missing: string[] }}
+ */
+function validateTestPathsExistence(tests, rootDir) {
+    if (!tests || typeof tests !== 'object') {
+        return { valid: true, errors: [], missing: [] };
+    }
+    const missing = [];
+    // Test types that are file paths (not manual descriptions)
+    const fileTestTypes = [TEST_TYPES.UNIT, TEST_TYPES.E2E, TEST_TYPES.INTEGRATION];
+    for (const testType of fileTestTypes) {
+        const paths = tests[testType];
+        if (!paths || !Array.isArray(paths))
+            continue;
+        for (const filePath of paths) {
+            if (!filePath || typeof filePath !== 'string')
+                continue;
+            const fullPath = path.join(rootDir, filePath);
+            if (!existsSync(fullPath)) {
+                missing.push(filePath);
+            }
+        }
+    }
+    if (missing.length > 0) {
+        const errors = [
+            `test paths validation failed - ${missing.length} test file(s) not found:`,
+            ...missing.map((p) => `  - ${p}`),
+        ];
+        return { valid: false, errors, missing };
+    }
+    return { valid: true, errors: [], missing: [] };
+}
+export async function validatePreflight(id, options = {}) {
+    const rootDir = options.rootDir || process.cwd();
+    const worktreePath = options.worktreePath || rootDir;
+    const allErrors = [];
+    const missingCodePaths = [];
+    const missingTestPaths = [];
+    // Step 1: Read WU YAML from worktree (WU-1830)
+    // When worktreePath is provided, read YAML from there to get latest code_paths
+    const wuPath = path.join(worktreePath, WU_PATHS.WU(id));
+    // Debug logging for YAML source (WU-1830)
+    if (options.worktreePath && options.worktreePath !== rootDir) {
+        process.env.DEBUG && console.log(`[wu-preflight] Reading WU YAML from worktree: ${wuPath}`);
+    }
+    let doc;
+    try {
+        // First try to read raw (without ID validation) to provide better errors
+        doc = readWURaw(wuPath);
+    }
+    catch (err) {
+        return createPreflightResult({
+            valid: false,
+            errors: [`Failed to read WU YAML: ${err.message}`],
+        });
+    }
+    // Step 2: Validate schema
+    const schemaResult = validateSchema(doc, id);
+    if (!schemaResult.valid) {
+        allErrors.push(...schemaResult.errors);
+    }
+    // Step 3: Validate code_paths exist
+    const codePathsResult = validateCodePathsExistence(doc.code_paths, worktreePath);
+    if (!codePathsResult.valid) {
+        allErrors.push(...codePathsResult.errors);
+        missingCodePaths.push(...codePathsResult.missing);
+    }
+    // Step 4: Validate test file paths exist
+    // Support both 'tests' and legacy 'test_paths' field
+    const testsObj = doc.tests || doc.test_paths || {};
+    const testPathsResult = validateTestPathsExistence(testsObj, worktreePath);
+    if (!testPathsResult.valid) {
+        allErrors.push(...testPathsResult.errors);
+        missingTestPaths.push(...testPathsResult.missing);
+    }
+    return createPreflightResult({
+        valid: allErrors.length === 0,
+        errors: allErrors,
+        missingCodePaths,
+        missingTestPaths,
+    });
+}
+/**
+ * Format preflight result as user-friendly message
+ *
+ * @param {string} id - WU ID
+ * @param {PreflightResult} result - Validation result
+ * @returns {string} Formatted message
+ */
+export function formatPreflightResult(id, result) {
+    if (result.valid) {
+        return `${LOG_PREFIX.PREFLIGHT} ${EMOJI.SUCCESS} Preflight validation passed for ${id}`;
+    }
+    const lines = [
+        `${LOG_PREFIX.PREFLIGHT} ${EMOJI.FAILURE} Preflight validation failed for ${id}`,
+        '',
+        ...result.errors,
+    ];
+    if (result.missingCodePaths.length > 0) {
+        lines.push('');
+        lines.push('Fix options:');
+        lines.push('  1. Create the missing files');
+        lines.push(`  2. Update code_paths in ${id}.yaml to match actual files`);
+    }
+    if (result.missingTestPaths.length > 0) {
+        lines.push('');
+        lines.push('For test paths:');
+        lines.push('  1. Create the missing test files');
+        lines.push(`  2. Update tests in ${id}.yaml to match actual files`);
+        lines.push('  3. Or use tests.manual for non-file test descriptions');
+    }
+    return lines.join('\n');
+}
+// Export PreflightResult type for documentation
+export const PreflightResult = {};