@lumenflow/core 1.0.0

package/dist/lumenflow-config.js

@@ -0,0 +1,236 @@
+/**
+ * LumenFlow Configuration Loader
+ *
+ * Loads and manages LumenFlow configuration from .lumenflow.config.yaml
+ * Falls back to sensible defaults if no config file exists.
+ *
+ * @module lumenflow-config
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as yaml from 'yaml';
+import { parseConfig, getDefaultConfig, validateConfig, } from './lumenflow-config-schema.js';
+/** Default config file name */
+const CONFIG_FILE_NAME = '.lumenflow.config.yaml';
+/** Cached config instance */
+let cachedConfig = null;
+/** Cached project root */
+let cachedProjectRoot = null;
+/**
+ * Find project root by looking for .lumenflow.config.yaml or .git
+ *
+ * @param startDir - Directory to start searching from
+ * @returns Project root path or current working directory
+ */
+export function findProjectRoot(startDir = process.cwd()) {
+    let currentDir = path.resolve(startDir);
+    const root = path.parse(currentDir).root;
+    while (currentDir !== root) {
+        // Check for config file first
+        if (fs.existsSync(path.join(currentDir, CONFIG_FILE_NAME))) {
+            return currentDir;
+        }
+        // Fall back to .git directory
+        if (fs.existsSync(path.join(currentDir, '.git'))) {
+            return currentDir;
+        }
+        currentDir = path.dirname(currentDir);
+    }
+    return process.cwd();
+}
+/**
+ * Load configuration from file
+ *
+ * @param projectRoot - Project root directory
+ * @returns Parsed configuration or null if file doesn't exist
+ */
+function loadConfigFile(projectRoot) {
+    const configPath = path.join(projectRoot, CONFIG_FILE_NAME);
+    if (!fs.existsSync(configPath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(configPath, 'utf8');
+        const data = yaml.parse(content);
+        return data || {};
+    }
+    catch (error) {
+        console.warn(`Warning: Failed to parse ${CONFIG_FILE_NAME}:`, error);
+        return null;
+    }
+}
+/**
+ * Get LumenFlow configuration
+ *
+ * Loads config from .lumenflow.config.yaml if present, otherwise uses defaults.
+ * Configuration is cached for performance.
+ *
+ * @param options - Options for loading config
+ * @param options.projectRoot - Override project root detection
+ * @param options.reload - Force reload from disk (bypass cache)
+ * @returns LumenFlow configuration
+ */
+export function getConfig(options = {}) {
+    const { projectRoot: overrideRoot, reload = false } = options;
+    // Use cached config if available and not reloading
+    if (cachedConfig && !reload && !overrideRoot) {
+        return cachedConfig;
+    }
+    // Find or use provided project root
+    const projectRoot = overrideRoot || findProjectRoot();
+    // Load config file if exists
+    const fileConfig = loadConfigFile(projectRoot);
+    // Parse with defaults
+    const config = parseConfig(fileConfig || {});
+    // Cache if using default project root
+    if (!overrideRoot) {
+        cachedConfig = config;
+        cachedProjectRoot = projectRoot;
+    }
+    return config;
+}
+/**
+ * Get the project root directory
+ *
+ * @returns Cached project root or finds it
+ */
+export function getProjectRoot() {
+    if (cachedProjectRoot) {
+        return cachedProjectRoot;
+    }
+    cachedProjectRoot = findProjectRoot();
+    return cachedProjectRoot;
+}
+/**
+ * Clear cached configuration
+ *
+ * Useful for testing or when config file changes
+ */
+export function clearConfigCache() {
+    cachedConfig = null;
+    cachedProjectRoot = null;
+}
+/**
+ * Resolve a path relative to project root
+ *
+ * @param relativePath - Relative path from config
+ * @param projectRoot - Optional project root override
+ * @returns Absolute path
+ */
+export function resolvePath(relativePath, projectRoot) {
+    const root = projectRoot || getProjectRoot();
+    return path.join(root, relativePath);
+}
+/**
+ * Get resolved paths for common directories
+ *
+ * Convenience function that resolves all directory paths to absolute paths
+ *
+ * @param options - Options
+ * @param options.projectRoot - Override project root
+ * @returns Object with absolute paths
+ */
+export function getResolvedPaths(options = {}) {
+    const projectRoot = options.projectRoot || getProjectRoot();
+    const config = getConfig({ projectRoot });
+    return {
+        wuDir: path.join(projectRoot, config.directories.wuDir),
+        initiativesDir: path.join(projectRoot, config.directories.initiativesDir),
+        backlogPath: path.join(projectRoot, config.directories.backlogPath),
+        statusPath: path.join(projectRoot, config.directories.statusPath),
+        worktrees: path.join(projectRoot, config.directories.worktrees),
+        stampsDir: path.join(projectRoot, config.beacon.stampsDir),
+        stateDir: path.join(projectRoot, config.beacon.stateDir),
+        skillsDir: path.join(projectRoot, config.directories.skillsDir),
+        agentsDir: path.join(projectRoot, config.directories.agentsDir),
+        memoryBank: path.join(projectRoot, config.directories.memoryBank),
+    };
+}
+/**
+ * Validate a config file
+ *
+ * @param configPath - Path to config file
+ * @returns Validation result
+ */
+export function validateConfigFile(configPath) {
+    if (!fs.existsSync(configPath)) {
+        return { valid: false, errors: ['Config file not found'] };
+    }
+    try {
+        const content = fs.readFileSync(configPath, 'utf8');
+        const data = yaml.parse(content);
+        const result = validateConfig(data);
+        if (result.success) {
+            return { valid: true, errors: [], config: result.data };
+        }
+        const errors = result.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`);
+        return { valid: false, errors };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            errors: [`Failed to parse YAML: ${error instanceof Error ? error.message : String(error)}`],
+        };
+    }
+}
+/**
+ * Create a sample config file
+ *
+ * @param outputPath - Path to write config file
+ * @param options - Options for sample config
+ */
+export function createSampleConfig(outputPath, options = {}) {
+    const { includeComments = true } = options;
+    const defaultConfig = getDefaultConfig();
+    const configContent = includeComments
+        ? `# LumenFlow Configuration
+# This file configures paths and settings for the LumenFlow workflow framework.
+# All paths are relative to the project root.
+
+version: "${defaultConfig.version}"
+
+# Directory paths
+directories:
+  # WU YAML files directory
+  wuDir: "${defaultConfig.directories.wuDir}"
+  # Initiatives directory
+  initiativesDir: "${defaultConfig.directories.initiativesDir}"
+  # Backlog file path
+  backlogPath: "${defaultConfig.directories.backlogPath}"
+  # Status file path
+  statusPath: "${defaultConfig.directories.statusPath}"
+  # Worktrees directory
+  worktrees: "${defaultConfig.directories.worktrees}"
+  # Skills directory
+  skillsDir: "${defaultConfig.directories.skillsDir}"
+  # Agents directory
+  agentsDir: "${defaultConfig.directories.agentsDir}"
+
+# Beacon paths (.beacon directory structure)
+beacon:
+  base: "${defaultConfig.beacon.base}"
+  stampsDir: "${defaultConfig.beacon.stampsDir}"
+  stateDir: "${defaultConfig.beacon.stateDir}"
+
+# Git configuration
+git:
+  mainBranch: "${defaultConfig.git.mainBranch}"
+  defaultRemote: "${defaultConfig.git.defaultRemote}"
+  maxBranchDrift: ${defaultConfig.git.maxBranchDrift}
+
+# WU configuration
+wu:
+  minDescriptionLength: ${defaultConfig.wu.minDescriptionLength}
+  maxCommitSubject: ${defaultConfig.wu.maxCommitSubject}
+  defaultPriority: "${defaultConfig.wu.defaultPriority}"
+  defaultStatus: "${defaultConfig.wu.defaultStatus}"
+
+# Gates configuration
+gates:
+  maxEslintWarnings: ${defaultConfig.gates.maxEslintWarnings}
+  enableCoverage: ${defaultConfig.gates.enableCoverage}
+  minCoverage: ${defaultConfig.gates.minCoverage}
+`
+        : yaml.stringify(defaultConfig);
+    fs.writeFileSync(outputPath, configContent, 'utf8');
+}

package/dist/manual-test-validator.d.ts

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * Manual Test Escape Hatch Validator
+ *
+ * WU-1433: Restricts manual-only tests for WUs touching hex core code.
+ * WU-2332: Require automated tests for all code files, remove lane exemptions.
+ *
+ * Implementation WUs must have at least one automated test (unit/e2e/integration).
+ *
+ * Exemptions:
+ * - type: documentation only
+ * - code_paths containing only documentation/config files (no code files)
+ *
+ * @see {@link tools/lib/wu-done-validators.mjs} - Integration point
+ * @see {@link docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md} - TDD requirements
+ */
+/**
+ * Path prefixes for hex core code requiring automated tests.
+ * These are the critical application layer paths.
+ *
+ * @constant {string[]}
+ */
+export declare const HEX_CORE_CODE_PATTERNS: readonly string[];
+/**
+ * @deprecated Lane-based exemptions removed in WU-2332.
+ * Test requirements are now based on file types, not lanes.
+ * Kept for backward compatibility but no longer used.
+ * @constant {string[]}
+ */
+export declare const EXEMPT_LANES: readonly any[];
+/**
+ * WU types exempt from automated test requirement.
+ * Only 'documentation' type is exempt - actual code changes require automated tests.
+ *
+ * @constant {string[]}
+ */
+export declare const EXEMPT_TYPES: readonly string[];
+/**
+ * Determine if a file path represents a code file requiring automated tests.
+ *
+ * Code files are those with extensions like .mjs, .ts, .tsx, .js
+ * EXCEPT config files (vitest.config.ts, .eslintrc.js, etc.)
+ *
+ * @param {string} filePath - File path to check
+ * @returns {boolean} True if the file is a code file requiring tests
+ */
+export declare function isCodeFile(filePath: any): boolean;
+/**
+ * Check if code_paths contains any hex core code.
+ *
+ * @param {string[]|null|undefined} codePaths - Array of file paths from WU YAML
+ * @returns {boolean} True if any path is in hex core layer
+ */
+export declare function containsHexCoreCode(codePaths: any): boolean;
+/**
+ * Check if a WU is exempt from automated test requirement.
+ *
+ * WU-2332: Only type: 'documentation' is exempt.
+ * Lane-based exemptions have been removed - test requirements
+ * are now based on file types in code_paths.
+ *
+ * @param {object} doc - WU YAML document
+ * @returns {boolean} True if WU is exempt
+ */
+export declare function isExemptFromAutomatedTests(doc: any): boolean;
+/**
+ * Validate automated test requirement for WU.
+ *
+ * WU-2332: Requirements are based on file types, not lanes.
+ * - WUs with ANY code files in code_paths must have automated tests
+ * - WUs with only docs/config files can use manual-only tests
+ * - type: 'documentation' is always exempt
+ *
+ * @param {object} doc - WU YAML document
+ * @returns {{ valid: boolean, errors: string[] }} Validation result
+ */
+export declare function validateAutomatedTestRequirement(doc: any): {
+    valid: boolean;
+    errors: any[];
+};

package/dist/manual-test-validator.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * Manual Test Escape Hatch Validator
+ *
+ * WU-1433: Restricts manual-only tests for WUs touching hex core code.
+ * WU-2332: Require automated tests for all code files, remove lane exemptions.
+ *
+ * Implementation WUs must have at least one automated test (unit/e2e/integration).
+ *
+ * Exemptions:
+ * - type: documentation only
+ * - code_paths containing only documentation/config files (no code files)
+ *
+ * @see {@link tools/lib/wu-done-validators.mjs} - Integration point
+ * @see {@link docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md} - TDD requirements
+ */
+import path from 'node:path';
+import { TEST_TYPES, WU_TYPES } from './wu-constants.js';
+/**
+ * Code file extensions that require automated tests.
+ * @constant {string[]}
+ */
+const CODE_EXTENSIONS = Object.freeze(['.js', '.ts', '.tsx', '.js']);
+/**
+ * Non-code file extensions (documentation, data, config).
+ * @constant {string[]}
+ */
+const NON_CODE_EXTENSIONS = Object.freeze(['.md', '.yaml', '.yml', '.json']);
+/**
+ * Patterns that indicate a config file (even with code extensions).
+ * @constant {RegExp[]}
+ */
+const CONFIG_PATTERNS = Object.freeze([
+    /config\./i, // vitest.config.ts, eslint.config.js
+    /\.config\./i, // *.config.ts, *.config.js
+    /rc\.[jt]s$/i, // .eslintrc.js, .prettierrc.ts
+    /^\.[a-z]+rc\./i, // .eslintrc.*, .prettierrc.*
+]);
+/**
+ * Path prefixes for hex core code requiring automated tests.
+ * These are the critical application layer paths.
+ *
+ * @constant {string[]}
+ */
+export const HEX_CORE_CODE_PATTERNS = Object.freeze([
+    'packages/@patientpath/application/',
+    'packages/@patientpath/prompts/',
+    'packages/@patientpath/ports/',
+]);
+/**
+ * @deprecated Lane-based exemptions removed in WU-2332.
+ * Test requirements are now based on file types, not lanes.
+ * Kept for backward compatibility but no longer used.
+ * @constant {string[]}
+ */
+export const EXEMPT_LANES = Object.freeze([]);
+/**
+ * WU types exempt from automated test requirement.
+ * Only 'documentation' type is exempt - actual code changes require automated tests.
+ *
+ * @constant {string[]}
+ */
+export const EXEMPT_TYPES = Object.freeze([WU_TYPES.DOCUMENTATION]);
+/**
+ * Determine if a file path represents a code file requiring automated tests.
+ *
+ * Code files are those with extensions like .mjs, .ts, .tsx, .js
+ * EXCEPT config files (vitest.config.ts, .eslintrc.js, etc.)
+ *
+ * @param {string} filePath - File path to check
+ * @returns {boolean} True if the file is a code file requiring tests
+ */
+export function isCodeFile(filePath) {
+    if (!filePath || typeof filePath !== 'string') {
+        return false;
+    }
+    // Get the filename from the path
+    const fileName = path.basename(filePath);
+    const ext = path.extname(filePath).toLowerCase();
+    // Check if it's a non-code extension (docs, data)
+    if (NON_CODE_EXTENSIONS.includes(ext)) {
+        return false;
+    }
+    // Check if it's a code extension
+    if (!CODE_EXTENSIONS.includes(ext)) {
+        return false;
+    }
+    // Check if it's a config file (even with code extension)
+    const isConfig = CONFIG_PATTERNS.some((pattern) => pattern.test(fileName));
+    if (isConfig) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Check if code_paths contains any hex core code.
+ *
+ * @param {string[]|null|undefined} codePaths - Array of file paths from WU YAML
+ * @returns {boolean} True if any path is in hex core layer
+ */
+export function containsHexCoreCode(codePaths) {
+    if (!codePaths || !Array.isArray(codePaths) || codePaths.length === 0) {
+        return false;
+    }
+    return codePaths.some((path) => {
+        if (!path || typeof path !== 'string')
+            return false;
+        return HEX_CORE_CODE_PATTERNS.some((pattern) => path.startsWith(pattern));
+    });
+}
+/**
+ * Check if a WU is exempt from automated test requirement.
+ *
+ * WU-2332: Only type: 'documentation' is exempt.
+ * Lane-based exemptions have been removed - test requirements
+ * are now based on file types in code_paths.
+ *
+ * @param {object} doc - WU YAML document
+ * @returns {boolean} True if WU is exempt
+ */
+export function isExemptFromAutomatedTests(doc) {
+    if (!doc)
+        return false;
+    // Only type: documentation is exempt
+    const type = doc.type || '';
+    if (typeof type === 'string' && EXEMPT_TYPES.includes(type)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Check if WU has at least one automated test.
+ *
+ * @param {object} tests - Tests object from WU YAML
+ * @returns {boolean} True if has at least one automated test
+ */
+function hasAutomatedTest(tests) {
+    if (!tests)
+        return false;
+    const hasItems = (arr) => Array.isArray(arr) && arr.length > 0;
+    return (hasItems(tests[TEST_TYPES.UNIT]) ||
+        hasItems(tests[TEST_TYPES.E2E]) ||
+        hasItems(tests[TEST_TYPES.INTEGRATION]));
+}
+/**
+ * Check if any code_paths contain actual code files (not docs/config).
+ *
+ * @param {string[]} codePaths - Array of file paths from WU YAML
+ * @returns {{ hasCodeFiles: boolean, codeFiles: string[] }} Result with list of code files
+ */
+function analyzeCodePaths(codePaths) {
+    if (!codePaths || !Array.isArray(codePaths) || codePaths.length === 0) {
+        return { hasCodeFiles: false, codeFiles: [] };
+    }
+    const codeFiles = codePaths.filter((p) => isCodeFile(p));
+    return {
+        hasCodeFiles: codeFiles.length > 0,
+        codeFiles,
+    };
+}
+/**
+ * Validate automated test requirement for WU.
+ *
+ * WU-2332: Requirements are based on file types, not lanes.
+ * - WUs with ANY code files in code_paths must have automated tests
+ * - WUs with only docs/config files can use manual-only tests
+ * - type: 'documentation' is always exempt
+ *
+ * @param {object} doc - WU YAML document
+ * @returns {{ valid: boolean, errors: string[] }} Validation result
+ */
+export function validateAutomatedTestRequirement(doc) {
+    const errors = [];
+    if (!doc) {
+        return { valid: true, errors: [] };
+    }
+    // Check if WU is exempt by type
+    if (isExemptFromAutomatedTests(doc)) {
+        return { valid: true, errors: [] };
+    }
+    // Analyze code_paths for actual code files
+    const codePaths = doc.code_paths || [];
+    const { hasCodeFiles, codeFiles } = analyzeCodePaths(codePaths);
+    // If no code files, manual tests are fine
+    if (!hasCodeFiles) {
+        return { valid: true, errors: [] };
+    }
+    // WU has code files - require automated tests
+    // Support both tests: (current) and test_paths: (legacy)
+    const tests = doc.tests || doc.test_paths || {};
+    if (!hasAutomatedTest(tests)) {
+        errors.push(`WU modifies code files but has no automated tests.\n` +
+            `  Code files: ${codeFiles.join(', ')}\n` +
+            `  Required: At least one automated test (unit, e2e, or integration)\n` +
+            `  Manual-only tests are not allowed for code changes.\n\n` +
+            `  Fix: Add tests to tests.unit, tests.e2e, or tests.integration in WU YAML.`);
+        return { valid: false, errors };
+    }
+    return { valid: true, errors: [] };
+}

package/dist/merge-lock.d.ts

@@ -0,0 +1,115 @@
+/**
+ * WU-1747: Merge Lock Module
+ *
+ * Provides atomic locking mechanism for wu:done merge operations
+ * to prevent race conditions during concurrent completions.
+ *
+ * Features:
+ * - File-based lock with PID and timestamp
+ * - Stale lock detection and auto-cleanup
+ * - Idempotent re-acquisition for same WU
+ * - Guaranteed cleanup via withMergeLock wrapper
+ *
+ * @module merge-lock
+ */
+/**
+ * Default timeout for waiting to acquire lock (ms)
+ * After this time, acquisition fails if lock is held
+ */
+export declare const MERGE_LOCK_TIMEOUT_MS = 30000;
+/**
+ * Time after which a lock is considered stale and can be forcibly released (ms)
+ * Should be greater than expected merge operation duration
+ */
+export declare const MERGE_LOCK_STALE_MS = 60000;
+/**
+ * @typedef {Object} LockInfo
+ * @property {string} wuId - WU ID that holds the lock
+ * @property {string} lockId - Unique lock identifier
+ * @property {string} createdAt - ISO timestamp when lock was created
+ * @property {number} pid - Process ID of lock holder
+ * @property {string} hostname - Hostname of lock holder
+ */
+/**
+ * @typedef {Object} AcquireResult
+ * @property {boolean} acquired - Whether lock was acquired
+ * @property {string} [lockId] - Lock ID if acquired
+ * @property {string} [heldBy] - WU ID holding the lock if not acquired
+ * @property {string} [heldSince] - ISO timestamp if not acquired
+ */
+/**
+ * Options for lock file operations
+ */
+interface MergeLockBaseDirOptions {
+    /** Base directory (defaults to cwd) */
+    baseDir?: string;
+}
+/**
+ * Check if merge lock is currently held
+ *
+ * @param {MergeLockBaseDirOptions} [options]
+ * @returns {boolean} True if lock is held (and not stale)
+ */
+export declare function isMergeLocked(options?: MergeLockBaseDirOptions): boolean;
+/**
+ * Get information about current merge lock
+ *
+ * @param {MergeLockBaseDirOptions} [options]
+ * @returns {LockInfo|null} Lock info or null if unlocked
+ */
+export declare function getMergeLockInfo(options?: MergeLockBaseDirOptions): any;
+/**
+ * Options for acquiring merge lock
+ */
+export interface AcquireMergeLockOptions extends MergeLockBaseDirOptions {
+    /** Max time to wait for lock (default: MERGE_LOCK_TIMEOUT_MS) */
+    waitMs?: number;
+}
+/**
+ * Attempt to acquire the merge lock
+ *
+ * Will wait up to waitMs for lock to become available.
+ * If the same WU already holds the lock, re-acquisition succeeds (idempotent).
+ * Stale locks are automatically cleaned up.
+ *
+ * @param {string} wuId - WU ID requesting the lock
+ * @param {AcquireMergeLockOptions} [options]
+ * @returns {Promise<AcquireResult>} Acquisition result
+ */
+export declare function acquireMergeLock(wuId: any, options?: AcquireMergeLockOptions): Promise<{
+    acquired: boolean;
+    lockId: any;
+    heldBy?: undefined;
+    heldSince?: undefined;
+} | {
+    acquired: boolean;
+    heldBy: any;
+    heldSince: any;
+    lockId?: undefined;
+}>;
+/**
+ * Release the merge lock
+ *
+ * Only releases if the provided lockId matches the current lock.
+ * This prevents accidentally releasing another WU's lock.
+ *
+ * @param {string} lockId - Lock ID to release
+ * @param {MergeLockBaseDirOptions} [options]
+ * @returns {boolean} True if lock was released
+ */
+export declare function releaseMergeLock(lockId: any, options?: MergeLockBaseDirOptions): boolean;
+/**
+ * Execute a function while holding the merge lock
+ *
+ * Guarantees the lock is released after function completes,
+ * even if the function throws an error.
+ *
+ * @template T
+ * @param {string} wuId - WU ID requesting the lock
+ * @param {function(): Promise<T>} fn - Async function to execute
+ * @param {AcquireMergeLockOptions} [options]
+ * @returns {Promise<T>} Result of function execution
+ * @throws {Error} If lock cannot be acquired or function throws
+ */
+export declare function withMergeLock<T>(wuId: string, fn: () => Promise<T>, options?: AcquireMergeLockOptions): Promise<T>;
+export {};