@lumenflow/core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @lumenflow/core - Battle-tested LumenFlow workflow framework
+ * @module @lumenflow/core
+ */
+export declare const VERSION = "0.0.0";
+export * from './arg-parser.js';
+export * from './date-utils.js';
+export * from './error-handler.js';
+export * from './retry-strategy.js';
+export { DEFAULT_DOMAIN, inferDefaultDomain, normalizeToEmail, isValidEmail, } from './user-normalizer.js';
+export * from './git-adapter.js';
+export * from './state-machine.js';
+export { WU_EVENT_TYPES, WU_STATUSES, WU_PATTERNS, CreateEventSchema, ClaimEventSchema, BlockEventSchema, UnblockEventSchema, CompleteEventSchema, CheckpointEventSchema, WUEventSchema, validateWUEvent, SpawnEventSchema as WUSpawnEventSchema, type CreateEvent, type ClaimEvent, type BlockEvent, type UnblockEvent, type CompleteEvent, type CheckpointEvent, type WUEvent, type SpawnEvent as WUSpawnEvent, } from './wu-state-schema.js';
+export { WU_EVENTS_FILE_NAME, WUStateStore, acquireLock, releaseLock, repairStateFile, isLockStale as isWULockStale, type WUStateEntry, type LockData as WULockData, type CheckpointOptions, type RepairResult, } from './wu-state-store.js';
+export * from './lane-checker.js';
+export * from './lane-inference.js';
+export { getStaleThresholdMs, getLocksDir, getLockFilePath, isLockStale, isZombieLock, readLockMetadata, acquireLaneLock, releaseLaneLock, checkLaneLock, forceRemoveStaleLock, getAllLaneLocks, auditedUnlock, } from './lane-lock.js';
+export * from './lane-validator.js';
+export * from './wu-yaml.js';
+export { getAssignedEmail } from './wu-claim-helpers.js';
+export * from './wu-done-worktree.js';
+export * from './wu-done-validators.js';
+export * from './wu-helpers.js';
+export * from './wu-schema.js';
+export * from './wu-validator.js';
+export * from './spawn-registry-store.js';
+export * from './spawn-registry-schema.js';
+export * from './spawn-tree.js';
+export * from './spawn-recovery.js';
+export * from './spawn-monitor.js';
+export * from './spawn-escalation.js';
+export * from './backlog-generator.js';
+export * from './backlog-parser.js';
+export * from './backlog-editor.js';
+export * from './backlog-sync-validator.js';
+export * from './worktree-scanner.js';
+export * from './worktree-ownership.js';
+export * from './micro-worktree.js';
+export * from './dependency-guard.js';
+export * from './stamp-utils.js';
+export * from './lumenflow-config.js';
+export * from './lumenflow-config-schema.js';

package/dist/index.js

@@ -0,0 +1,61 @@
+/**
+ * @lumenflow/core - Battle-tested LumenFlow workflow framework
+ * @module @lumenflow/core
+ */
+// Package version
+export const VERSION = '0.0.0';
+// Core utilities
+export * from './arg-parser.js';
+export * from './date-utils.js';
+export * from './error-handler.js';
+export * from './retry-strategy.js';
+// User normalizer (explicit exports to avoid conflicts)
+export { DEFAULT_DOMAIN, inferDefaultDomain, normalizeToEmail, isValidEmail, } from './user-normalizer.js';
+// Git operations
+export * from './git-adapter.js';
+// State machine
+export * from './state-machine.js';
+// WU State Schema (explicit exports to avoid SpawnEvent conflict with spawn-registry)
+export { WU_EVENT_TYPES, WU_STATUSES, WU_PATTERNS, CreateEventSchema, ClaimEventSchema, BlockEventSchema, UnblockEventSchema, CompleteEventSchema, CheckpointEventSchema, WUEventSchema, validateWUEvent, 
+// Rename conflicting exports
+SpawnEventSchema as WUSpawnEventSchema, } from './wu-state-schema.js';
+// WU State Store (explicit exports to avoid isLockStale conflict)
+export { WU_EVENTS_FILE_NAME, WUStateStore, acquireLock, releaseLock, repairStateFile, isLockStale as isWULockStale, } from './wu-state-store.js';
+// Lane management
+export * from './lane-checker.js';
+export * from './lane-inference.js';
+// Lane lock (explicit exports with proper names)
+export { getStaleThresholdMs, getLocksDir, getLockFilePath, isLockStale, isZombieLock, readLockMetadata, acquireLaneLock, releaseLaneLock, checkLaneLock, forceRemoveStaleLock, getAllLaneLocks, auditedUnlock, } from './lane-lock.js';
+export * from './lane-validator.js';
+// WU lifecycle
+export * from './wu-yaml.js';
+// WU claim helpers (skip isValidEmail which conflicts with user-normalizer)
+export { getAssignedEmail } from './wu-claim-helpers.js';
+export * from './wu-done-worktree.js';
+export * from './wu-done-validators.js';
+export * from './wu-helpers.js';
+export * from './wu-schema.js';
+export * from './wu-validator.js';
+// Spawn system
+export * from './spawn-registry-store.js';
+export * from './spawn-registry-schema.js';
+export * from './spawn-tree.js';
+export * from './spawn-recovery.js';
+export * from './spawn-monitor.js';
+export * from './spawn-escalation.js';
+// Backlog management
+export * from './backlog-generator.js';
+export * from './backlog-parser.js';
+export * from './backlog-editor.js';
+export * from './backlog-sync-validator.js';
+// Worktree utilities
+export * from './worktree-scanner.js';
+export * from './worktree-ownership.js';
+export * from './micro-worktree.js';
+// Guards and validators
+// NOTE: Configuration added below
+export * from './dependency-guard.js';
+export * from './stamp-utils.js';
+// Configuration
+export * from './lumenflow-config.js';
+export * from './lumenflow-config-schema.js';

package/dist/invariants/check-automated-tests.d.ts

@@ -0,0 +1,50 @@
+/**
+ * INV-AUTOMATED-TESTS-FOR-CODE Invariant Check (WU-2333)
+ *
+ * Validates that WUs with code files in code_paths have automated tests.
+ * Config files are excluded from this requirement.
+ *
+ * This invariant ensures that manual-only tests cannot satisfy validation
+ * for code changes, enforcing TDD discipline.
+ *
+ * Library-first check: This is custom validation logic for PatientPath WU workflow.
+ * No external library exists for WU YAML validation - this integrates with
+ * the existing manual-test-validator.mjs which already implements the core logic.
+ *
+ * @see {@link tools/lib/manual-test-validator.mjs} - Core validation logic
+ * @see {@link tools/invariants.yml} - Invariant registry
+ */
+/**
+ * Invariant metadata
+ */
+export declare const INVARIANT_ID = "INV-AUTOMATED-TESTS-FOR-CODE";
+export declare const INVARIANT_TYPE = "wu-automated-tests";
+/**
+ * Run the INV-AUTOMATED-TESTS-FOR-CODE invariant check.
+ *
+ * Scans WU YAML files and validates that any with code files in code_paths
+ * have automated tests (unit, e2e, or integration).
+ *
+ * WU-2425: When wuId is provided, only validates that specific WU instead of
+ * all active WUs. This prevents unrelated WUs from blocking wu:done completion.
+ *
+ * @param {CheckAutomatedTestsInvariantOptions} [options={}] - Options
+ * @returns {{ valid: boolean, violations: Array<object> }} Check result
+ */
+export interface CheckAutomatedTestsInvariantOptions {
+    /** Base directory for path resolution */
+    baseDir?: string;
+    /** Specific WU ID to validate (WU-2425: scoped validation) */
+    wuId?: string;
+}
+export declare function checkAutomatedTestsInvariant(options?: CheckAutomatedTestsInvariantOptions): {
+    valid: boolean;
+    violations: any[];
+};
+/**
+ * Format a violation for display.
+ *
+ * @param {object} violation - Violation object
+ * @returns {string} Formatted error message
+ */
+export declare function formatAutomatedTestsViolation(violation: any): string;

package/dist/invariants/check-automated-tests.js

@@ -0,0 +1,166 @@
+/**
+ * INV-AUTOMATED-TESTS-FOR-CODE Invariant Check (WU-2333)
+ *
+ * Validates that WUs with code files in code_paths have automated tests.
+ * Config files are excluded from this requirement.
+ *
+ * This invariant ensures that manual-only tests cannot satisfy validation
+ * for code changes, enforcing TDD discipline.
+ *
+ * Library-first check: This is custom validation logic for PatientPath WU workflow.
+ * No external library exists for WU YAML validation - this integrates with
+ * the existing manual-test-validator.mjs which already implements the core logic.
+ *
+ * @see {@link tools/lib/manual-test-validator.mjs} - Core validation logic
+ * @see {@link tools/invariants.yml} - Invariant registry
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseYAML } from '../wu-yaml.js';
+import { validateAutomatedTestRequirement, isCodeFile } from '../manual-test-validator.js';
+/**
+ * Invariant metadata
+ */
+export const INVARIANT_ID = 'INV-AUTOMATED-TESTS-FOR-CODE';
+export const INVARIANT_TYPE = 'wu-automated-tests';
+/**
+ * WU statuses that should be validated.
+ * Only validate active work - in_progress and blocked WUs.
+ * Done, ready, and waiting WUs are either already validated or not yet being worked.
+ */
+const ACTIVE_STATUSES = Object.freeze(['in_progress', 'blocked']);
+/**
+ * Default path to WU YAML files relative to base directory.
+ */
+const WU_YAML_PATH = 'docs/04-operations/tasks/wu';
+/**
+ * Check a single WU YAML file for automated test requirement.
+ *
+ * @param {string} filePath - Path to WU YAML file
+ * @param {CheckWUFileOptions} [options={}] - Options
+ * @returns {{ valid: boolean, wuId: string|null, error: string|null }} Check result
+ */
+function checkWUFile(filePath, options = {}) {
+    const { skipStatusCheck = false } = options;
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        const doc = parseYAML(content);
+        if (!doc) {
+            return { valid: true, wuId: null, error: null };
+        }
+        const wuId = doc.id || path.basename(filePath, '.yaml');
+        const status = doc.status || '';
+        // WU-2425: Skip status check when validating a specific WU (e.g., during wu:done)
+        // This is needed because wu:done may set status to 'done' before validation runs
+        if (!skipStatusCheck && !ACTIVE_STATUSES.includes(status)) {
+            return { valid: true, wuId, error: null };
+        }
+        // Use the existing validation logic from manual-test-validator.mjs
+        const result = validateAutomatedTestRequirement(doc);
+        if (!result.valid) {
+            return {
+                valid: false,
+                wuId,
+                error: result.errors.join('\n'),
+                codeFiles: getCodeFilesFromPaths(doc.code_paths || []),
+            };
+        }
+        return { valid: true, wuId, error: null };
+    }
+    catch {
+        // Skip files that can't be parsed
+        return { valid: true, wuId: null, error: null };
+    }
+}
+/**
+ * Get code files from code_paths (filtering out config files).
+ *
+ * @param {string[]} codePaths - Array of code paths
+ * @returns {string[]} Code files that require automated tests
+ */
+function getCodeFilesFromPaths(codePaths) {
+    if (!codePaths || !Array.isArray(codePaths)) {
+        return [];
+    }
+    return codePaths.filter((p) => isCodeFile(p));
+}
+export function checkAutomatedTestsInvariant(options = {}) {
+    const { baseDir = process.cwd(), wuId } = options;
+    const wuDir = path.join(baseDir, WU_YAML_PATH);
+    const violations = [];
+    // Check if WU directory exists
+    if (!existsSync(wuDir)) {
+        return { valid: true, violations: [] };
+    }
+    // WU-2425: If wuId is provided, only check that specific WU file
+    if (wuId) {
+        const filePath = path.join(wuDir, `${wuId}.yaml`);
+        // If the WU file doesn't exist, pass gracefully (nothing to validate)
+        if (!existsSync(filePath)) {
+            return { valid: true, violations: [] };
+        }
+        // When validating a specific WU, skip status check (validate regardless of status)
+        // This is needed because wu:done may set status to 'done' before validation runs
+        const result = checkWUFile(filePath, { skipStatusCheck: true });
+        if (!result.valid) {
+            violations.push({
+                id: INVARIANT_ID,
+                type: INVARIANT_TYPE,
+                wuId: result.wuId,
+                description: `WU ${result.wuId} has code files but no automated tests`,
+                message: result.error,
+                codeFiles: result.codeFiles,
+            });
+        }
+        return {
+            valid: violations.length === 0,
+            violations,
+        };
+    }
+    // Default behavior: check all WU files (existing behavior for gates)
+    let files;
+    try {
+        files = readdirSync(wuDir).filter((f) => f.startsWith('WU-') && (f.endsWith('.yaml') || f.endsWith('.yml')));
+    }
+    catch {
+        return { valid: true, violations: [] };
+    }
+    // Check each WU file
+    for (const file of files) {
+        const filePath = path.join(wuDir, file);
+        const result = checkWUFile(filePath);
+        if (!result.valid) {
+            violations.push({
+                id: INVARIANT_ID,
+                type: INVARIANT_TYPE,
+                wuId: result.wuId,
+                description: `WU ${result.wuId} has code files but no automated tests`,
+                message: result.error,
+                codeFiles: result.codeFiles,
+            });
+        }
+    }
+    return {
+        valid: violations.length === 0,
+        violations,
+    };
+}
+/**
+ * Format a violation for display.
+ *
+ * @param {object} violation - Violation object
+ * @returns {string} Formatted error message
+ */
+export function formatAutomatedTestsViolation(violation) {
+    const lines = [
+        `INVARIANT VIOLATION: ${violation.id}`,
+        `WU: ${violation.wuId}`,
+        `Description: ${violation.description}`,
+    ];
+    if (violation.codeFiles && violation.codeFiles.length > 0) {
+        lines.push(`Code files requiring tests: ${violation.codeFiles.join(', ')}`);
+    }
+    lines.push('');
+    lines.push('Action: Add automated tests (unit, e2e, or integration) to the tests field in the WU YAML.');
+    return lines.join('\n');
+}

package/dist/invariants-runner.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Invariants Runner (WU-2252)
+ *
+ * Validates durable repo invariants from invariants.yml.
+ * Runs as the first gate check and also inside wu:done even when --skip-gates is used.
+ *
+ * Supported invariant types:
+ * - required-file: File must exist
+ * - forbidden-file: File must NOT exist
+ * - mutual-exclusivity: Only one of the listed files may exist
+ * - forbidden-pattern: Pattern must not appear in scoped files
+ * - required-pattern: Pattern MUST appear at least once in scoped files (WU-2254)
+ * - forbidden-import: Files must not import forbidden modules (WU-2254)
+ * - wu-automated-tests: WUs with code files must have automated tests (WU-2333)
+ *
+ * Performance constraints:
+ * - Excludes node_modules/, worktrees/, .next/, dist/, .git/ from scanning
+ * - For forbidden-pattern rules, scans only the specified scope paths
+ *
+ * @module tools/lib/invariants-runner
+ */
+/**
+ * Invariant type constants
+ */
+export declare const INVARIANT_TYPES: {
+    REQUIRED_FILE: string;
+    FORBIDDEN_FILE: string;
+    MUTUAL_EXCLUSIVITY: string;
+    FORBIDDEN_PATTERN: string;
+    REQUIRED_PATTERN: string;
+    FORBIDDEN_IMPORT: string;
+    WU_AUTOMATED_TESTS: string;
+};
+/**
+ * Custom error class for invariant violations
+ */
+export declare class InvariantError extends Error {
+    /** The invariant ID */
+    invariantId: string;
+    /**
+     * @param {string} invariantId - The invariant ID (e.g., 'INV-001')
+     * @param {string} message - Error message
+     */
+    constructor(invariantId: string, message: string);
+}
+/**
+ * Load invariants from a YAML file
+ *
+ * @param {string} filePath - Path to invariants.yml
+ * @returns {Array<object>} Array of invariant definitions
+ * @throws {Error} If file doesn't exist or has invalid YAML
+ */
+export declare function loadInvariants(filePath: any): any;
+/**
+ * Validate all invariants against the current repo state
+ *
+ * WU-2425: When wuId is provided, WU-scoped invariants only validate that specific WU.
+ *
+ * @param {Array<object>} invariants - Array of invariant definitions
+ * @param {ValidateInvariantsOptions} [options={}] - Options
+ * @returns {{valid: boolean, violations: Array<object>}} Validation result
+ */
+export interface ValidateInvariantsOptions {
+    /** Base directory for path resolution */
+    baseDir?: string;
+    /** Specific WU ID for scoped validation (WU-2425) */
+    wuId?: string;
+}
+export declare function validateInvariants(invariants: any, options?: ValidateInvariantsOptions): {
+    valid: boolean;
+    violations: any[];
+};
+/**
+ * Format an invariant violation for display
+ *
+ * @param {object} violation - Violation object from validateInvariants
+ * @returns {string} Formatted error message
+ */
+export declare function formatInvariantError(violation: any): string;
+/**
+ * Run invariants validation and format results for gates output
+ *
+ * WU-2425: When wuId is provided, WU-scoped invariants (like automated tests)
+ * only validate that specific WU, preventing unrelated WUs from blocking wu:done.
+ *
+ * @param {RunInvariantsOptions} [options={}] - Options
+ * @returns {{success: boolean, violations: Array<object>, formatted: string}} Result
+ */
+export interface RunInvariantsOptions {
+    /** Path to invariants config */
+    configPath?: string;
+    /** Base directory */
+    baseDir?: string;
+    /** Suppress console output */
+    silent?: boolean;
+    /** Specific WU ID for scoped validation (WU-2425) */
+    wuId?: string;
+}
+export declare function runInvariants(options?: RunInvariantsOptions): {
+    success: boolean;
+    violations: any[];
+    formatted: string;
+};