@lumenflow/core 1.0.0

package/dist/core/worktree-guard.js

@@ -0,0 +1,242 @@
+/**
+ * @file worktree-guard.mjs
+ * @description WU context validation and main branch protection (WU-1396)
+ *
+ * Provides runtime guards to enforce worktree discipline:
+ * - Detect if current directory is inside a worktree
+ * - Extract WU ID and lane from worktree path or git branch
+ * - Throw descriptive error when write operations attempted outside worktree
+ * - Check if on main/master branch
+ *
+ * Used by wu- scripts to prevent writes to main checkout when worktrees exist.
+ * Complements .claude/hooks/user-prompt-submit-hook (human agent protection).
+ *
+ * @see {@link .claude/hooks/user-prompt-submit-hook} - Agent blocking hook
+ * @see {@link docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md} - Worktree discipline
+ */
+import path from 'node:path';
+import { createGitForPath } from '../git-adapter.js';
+import { BRANCHES } from '../wu-constants.js';
+/**
+ * Worktree path pattern: worktrees/<lane-kebab>-wu-<id>
+ * Captures: lane (kebab-case) and WU ID number
+ *
+ * Examples:
+ * - worktrees/operations-tooling-wu-1396
+ * - worktrees/intelligence-wu-789
+ * - worktrees/core-systems-api-wu-456
+ */
+const WORKTREE_PATH_PATTERN = /worktrees\/([\w-]+)-wu-(\d+)/;
+/**
+ * Lane branch pattern: lane/<lane-kebab>/wu-<id>
+ * Captures: lane (kebab-case) and WU ID number
+ *
+ * Examples:
+ * - lane/operations-tooling/wu-1396
+ * - lane/intelligence/wu-789
+ * - lane/core-systems-api/wu-456
+ */
+const LANE_BRANCH_PATTERN = /^lane\/([\w-]+)\/wu-(\d+)$/;
+/**
+ * Check if on main or master branch
+ *
+ * @param {GitOptions} [options] - Options
+ * @returns {Promise<boolean>} True if on main/master branch
+ *
+ * @example
+ * if (await isMainBranch()) {
+ *   console.log('On main branch');
+ * }
+ */
+export async function isMainBranch(options = {}) {
+    const git = options.git || createGitForPath(process.cwd());
+    const branch = await git.getCurrentBranch();
+    return branch === BRANCHES.MAIN || branch === BRANCHES.MASTER;
+}
+/**
+ * Normalize path separators to forward slashes
+ *
+ * Handles both Unix and Windows path separators for cross-platform compatibility.
+ *
+ * @param {string} p - Path to normalize
+ * @returns {string} Path with forward slashes
+ * @private
+ */
+function normalizePath(p) {
+    // Replace both backslashes and path.sep with forward slashes
+    // This handles Windows paths on Linux during testing
+    return p.replace(/\\/g, '/').split(path.sep).join('/');
+}
+/**
+ * Check if current directory is inside a worktree
+ *
+ * Detects worktree by checking if path contains worktrees/<lane>-wu-<id> pattern.
+ * Works correctly from nested directories within worktree.
+ *
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Current working directory (defaults to process.cwd())
+ * @returns {boolean} True if inside a worktree directory
+ *
+ * @example
+ * if (isInWorktree()) {
+ *   console.log('Working in a worktree');
+ * }
+ *
+ * // From nested directory
+ * isInWorktree({ cwd: '/project/worktrees/operations-wu-123/tools/lib' }); // true
+ */
+export function isInWorktree(options = {}) {
+    const cwd = options.cwd || process.cwd();
+    // Normalize path separators for cross-platform compatibility
+    const normalizedPath = normalizePath(cwd);
+    return WORKTREE_PATH_PATTERN.test(normalizedPath);
+}
+/**
+ * Extract WU context from worktree path
+ *
+ * @param {string} cwd - Current working directory
+ * @returns {Object|null} Context object or null if not a worktree path
+ * @private
+ */
+function extractFromWorktreePath(cwd) {
+    const normalizedPath = normalizePath(cwd);
+    const match = normalizedPath.match(WORKTREE_PATH_PATTERN);
+    if (!match) {
+        return null;
+    }
+    const [fullMatch, lane, wuIdNumber] = match;
+    const wuId = `WU-${wuIdNumber}`;
+    // Extract just the worktrees/<lane>-wu-<id> part (not full absolute path)
+    const worktreePathMatch = fullMatch.match(/(worktrees\/[\w-]+-wu-\d+)/);
+    const worktreePath = worktreePathMatch ? worktreePathMatch[1] : null;
+    return {
+        wuId,
+        lane,
+        worktreePath,
+    };
+}
+/**
+ * Extract WU context from git branch name
+ *
+ * @param {Object} git - GitAdapter instance
+ * @returns {Promise<Object|null>} Context object or null if not a lane branch
+ * @private
+ */
+async function extractFromBranch(git) {
+    const branch = await git.getCurrentBranch();
+    const match = branch.match(LANE_BRANCH_PATTERN);
+    if (!match) {
+        return null;
+    }
+    const [, lane, wuIdNumber] = match;
+    const wuId = `WU-${wuIdNumber}`;
+    return {
+        wuId,
+        lane,
+        worktreePath: null, // Not in worktree, on lane branch
+    };
+}
+/**
+ * Get WU context from current directory or git branch
+ *
+ * Extracts WU ID, lane, and worktree path from:
+ * 1. Worktree directory path (priority) - works from nested directories
+ * 2. Git branch name (fallback) - lane/operations-tooling/wu-1396
+ *
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Current working directory (defaults to process.cwd())
+ * @param {Object} [options.git] - GitAdapter instance (for testing)
+ * @returns {Promise<Object|null>} WU context or null if not in WU workspace
+ *
+ * @example
+ * // From worktree
+ * const ctx = await getWUContext();
+ * // { wuId: 'WU-1396', lane: 'operations-tooling', worktreePath: 'worktrees/operations-tooling-wu-1396' }
+ *
+ * // From lane branch (not in worktree)
+ * const ctx = await getWUContext();
+ * // { wuId: 'WU-1396', lane: 'operations-tooling', worktreePath: null }
+ *
+ * // From main checkout on main branch
+ * const ctx = await getWUContext();
+ * // null
+ */
+export async function getWUContext(options = {}) {
+    const cwd = options.cwd || process.cwd();
+    // Fast path: Try worktree path first (no git operations needed)
+    const worktreeContext = extractFromWorktreePath(cwd);
+    if (worktreeContext) {
+        return worktreeContext;
+    }
+    // Fallback to git branch detection (requires git operations)
+    // Only create git adapter if we have one provided or if we need to check branch
+    if (options.git) {
+        return await extractFromBranch(options.git);
+    }
+    // Create git adapter only if needed (path wasn't a worktree)
+    const git = createGitForPath(cwd);
+    return await extractFromBranch(git);
+}
+/**
+ * Assert that current context is inside a worktree or on a lane branch
+ *
+ * Throws descriptive error if:
+ * - On main/master branch AND
+ * - Not in a worktree directory
+ *
+ * Used by write operations to prevent modifications to main checkout.
+ *
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Current working directory (defaults to process.cwd())
+ * @param {Object} [options.git] - GitAdapter instance (for testing)
+ * @param {string} [options.operation] - Operation name for error message
+ * @throws {Error} If not in worktree and on main branch
+ *
+ * @example
+ * // In a wu- script write operation
+ * await assertWorktreeRequired({ operation: 'wu:claim' });
+ *
+ * // Will throw if on main in main checkout:
+ * // Error: BLOCKED: Operation 'wu:claim' requires a worktree.
+ * //        You are on 'main' branch in main checkout.
+ * //        ...
+ */
+export async function assertWorktreeRequired(options = {}) {
+    const cwd = options.cwd || process.cwd();
+    const operation = options.operation || 'this operation';
+    // Fast path: Check worktree path first (no git operations needed)
+    const worktreeContext = extractFromWorktreePath(cwd);
+    if (worktreeContext) {
+        return; // In worktree, allow operation
+    }
+    // Need git operations to check branch
+    const git = options.git || createGitForPath(cwd);
+    // Check if on lane branch
+    const branchContext = await extractFromBranch(git);
+    if (branchContext) {
+        return; // On lane branch, allow operation
+    }
+    // Check if on main branch
+    const onMain = await isMainBranch({ git });
+    if (onMain) {
+        throw new Error(`❌ BLOCKED: Operation '${operation}' requires a worktree.
+
+You are on 'main' branch in main checkout.
+
+To fix:
+  1. Claim a WU first:
+     pnpm wu:claim --id WU-1234 --lane "Operations: Tooling"
+
+  2. Navigate to the worktree:
+     cd worktrees/operations-tooling-wu-1234/
+
+  3. Run your operation from the worktree.
+
+For more information:
+  See CLAUDE.md §2 (Worktree Discipline)
+  See .claude/skills/worktree-discipline/SKILL.md
+`);
+    }
+    // Pass if on a non-main branch (e.g., feature branch) - allow for flexibility
+    // This case is less strict since it's not the main branch
+}

package/dist/coverage-gate.d.ts

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * Coverage Gate for Quality Gates
+ *
+ * WU-1433: Adds coverage checking to gates with configurable mode (warn/block).
+ * Enforces ≥90% coverage on hex core files (application layer).
+ *
+ * Mode flag allows gradual rollout:
+ * - warn: Log failures but don't block (default)
+ * - block: Fail the gate if thresholds not met
+ *
+ * @see {@link tools/gates.mjs} - Integration point
+ * @see {@link vitest.config.ts} - Coverage thresholds
+ */
+/**
+ * Coverage gate modes
+ * @constant
+ */
+export declare const COVERAGE_GATE_MODES: Readonly<{
+    /** Log warnings but don't fail the gate */
+    WARN: "warn";
+    /** Fail the gate if thresholds not met */
+    BLOCK: "block";
+}>;
+/**
+ * Glob patterns for hex core files that require ≥90% coverage.
+ * These are the critical application layer files.
+ *
+ * @constant {string[]}
+ */
+export declare const HEX_CORE_PATTERNS: readonly string[];
+/**
+ * Coverage threshold for hex core files (percentage)
+ * @constant {number}
+ */
+export declare const COVERAGE_THRESHOLD = 90;
+/**
+ * Default path to coverage summary JSON
+ * @constant {string}
+ */
+export declare const DEFAULT_COVERAGE_PATH = "coverage/coverage-summary.json";
+/**
+ * Check if a file path is in the hex core layer.
+ *
+ * WU-2448: Coverage reporters may emit absolute paths (e.g., /home/.../packages/...)
+ * or file:// URLs; use substring matching so hex-core checks still apply.
+ *
+ * @param {string|null|undefined} filePath - File path to check
+ * @returns {boolean} True if file is in hex core layer
+ */
+export declare function isHexCoreFile(filePath: any): boolean;
+/**
+ * Parse coverage JSON file.
+ *
+ * @param {string} coveragePath - Path to coverage-summary.json
+ * @returns {object|null} Parsed coverage data or null if invalid
+ */
+export declare function parseCoverageJson(coveragePath: any): {
+    total: any;
+    files: {};
+};
+/**
+ * Check if coverage meets thresholds for hex core files.
+ *
+ * @param {object|null} coverageData - Parsed coverage data
+ * @returns {{ pass: boolean, failures: Array<{ file: string, actual: number, threshold: number, metric: string }> }}
+ */
+export declare function checkCoverageThresholds(coverageData: any): {
+    pass: boolean;
+    failures: any[];
+};
+/**
+ * Format coverage data for display.
+ *
+ * @param {object|null} coverageData - Parsed coverage data
+ * @returns {string} Formatted output string
+ */
+export declare function formatCoverageDelta(coverageData: any): string;
+/**
+ * Logger interface for coverage gate output
+ */
+interface CoverageGateLogger {
+    log: (...args: unknown[]) => void;
+}
+/**
+ * Options for running coverage gate
+ */
+export interface CoverageGateOptions {
+    /** Gate mode ('warn' or 'block') */
+    mode?: string;
+    /** Path to coverage JSON */
+    coveragePath?: string;
+    /** Logger for output */
+    logger?: CoverageGateLogger;
+}
+/**
+ * Run coverage gate.
+ *
+ * @param {CoverageGateOptions} options - Gate options
+ * @returns {Promise<{ ok: boolean, mode: string, duration: number, message: string }>}
+ */
+export declare function runCoverageGate(options?: CoverageGateOptions): Promise<{
+    ok: boolean;
+    mode: string;
+    duration: number;
+    message: string;
+}>;
+export {};

package/dist/coverage-gate.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+/**
+ * Coverage Gate for Quality Gates
+ *
+ * WU-1433: Adds coverage checking to gates with configurable mode (warn/block).
+ * Enforces ≥90% coverage on hex core files (application layer).
+ *
+ * Mode flag allows gradual rollout:
+ * - warn: Log failures but don't block (default)
+ * - block: Fail the gate if thresholds not met
+ *
+ * @see {@link tools/gates.mjs} - Integration point
+ * @see {@link vitest.config.ts} - Coverage thresholds
+ */
+/* eslint-disable security/detect-non-literal-fs-filename, security/detect-object-injection */
+import { readFileSync, existsSync } from 'node:fs';
+import { EMOJI, STRING_LITERALS } from './wu-constants.js';
+/**
+ * Coverage gate modes
+ * @constant
+ */
+export const COVERAGE_GATE_MODES = Object.freeze({
+    /** Log warnings but don't fail the gate */
+    WARN: 'warn',
+    /** Fail the gate if thresholds not met */
+    BLOCK: 'block',
+});
+/**
+ * Glob patterns for hex core files that require ≥90% coverage.
+ * These are the critical application layer files.
+ *
+ * @constant {string[]}
+ */
+export const HEX_CORE_PATTERNS = Object.freeze([
+    'packages/@patientpath/application/',
+    'packages/@patientpath/prompts/',
+]);
+/**
+ * Coverage threshold for hex core files (percentage)
+ * @constant {number}
+ */
+export const COVERAGE_THRESHOLD = 90;
+/**
+ * Default path to coverage summary JSON
+ * @constant {string}
+ */
+export const DEFAULT_COVERAGE_PATH = 'coverage/coverage-summary.json';
+/**
+ * Check if a file path is in the hex core layer.
+ *
+ * WU-2448: Coverage reporters may emit absolute paths (e.g., /home/.../packages/...)
+ * or file:// URLs; use substring matching so hex-core checks still apply.
+ *
+ * @param {string|null|undefined} filePath - File path to check
+ * @returns {boolean} True if file is in hex core layer
+ */
+export function isHexCoreFile(filePath) {
+    if (!filePath || typeof filePath !== 'string') {
+        return false;
+    }
+    // Normalize backslashes to forward slashes for cross-platform compatibility
+    const normalizedPath = filePath.replace(/\\/g, '/');
+    return HEX_CORE_PATTERNS.some((pattern) => normalizedPath.includes(pattern));
+}
+/**
+ * Parse coverage JSON file.
+ *
+ * @param {string} coveragePath - Path to coverage-summary.json
+ * @returns {object|null} Parsed coverage data or null if invalid
+ */
+export function parseCoverageJson(coveragePath) {
+    if (!existsSync(coveragePath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(coveragePath, { encoding: 'utf-8' });
+        const data = JSON.parse(content);
+        // Transform to consistent format
+        const files = {};
+        for (const [key, value] of Object.entries(data)) {
+            if (key === 'total')
+                continue;
+            files[key] = value;
+        }
+        return {
+            total: data.total,
+            files,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if coverage meets thresholds for hex core files.
+ *
+ * @param {object|null} coverageData - Parsed coverage data
+ * @returns {{ pass: boolean, failures: Array<{ file: string, actual: number, threshold: number, metric: string }> }}
+ */
+export function checkCoverageThresholds(coverageData) {
+    if (!coverageData || !coverageData.files) {
+        return { pass: true, failures: [] };
+    }
+    const failures = [];
+    for (const [file, metricsValue] of Object.entries(coverageData.files)) {
+        if (!isHexCoreFile(file)) {
+            continue;
+        }
+        // Check lines coverage (primary metric)
+        const metrics = metricsValue;
+        const linesCoverage = metrics.lines?.pct ?? 0;
+        if (linesCoverage < COVERAGE_THRESHOLD) {
+            failures.push({
+                file,
+                actual: linesCoverage,
+                threshold: COVERAGE_THRESHOLD,
+                metric: 'lines',
+            });
+        }
+    }
+    return {
+        pass: failures.length === 0,
+        failures,
+    };
+}
+/**
+ * Format coverage data for display.
+ *
+ * @param {object|null} coverageData - Parsed coverage data
+ * @returns {string} Formatted output string
+ */
+export function formatCoverageDelta(coverageData) {
+    if (!coverageData) {
+        return '';
+    }
+    const lines = [];
+    const totalPct = coverageData.total?.lines?.pct ?? 0;
+    lines.push(`${STRING_LITERALS.NEWLINE}Coverage Summary: ${totalPct.toFixed(1)}% lines${STRING_LITERALS.NEWLINE}`);
+    // Show hex core files
+    const hexCoreFiles = Object.entries(coverageData.files || {}).filter(([file]) => isHexCoreFile(file));
+    if (hexCoreFiles.length > 0) {
+        lines.push('Hex Core Files:');
+        for (const [file, metricsValue] of hexCoreFiles) {
+            const metrics = metricsValue;
+            const pct = metrics.lines?.pct ?? 0;
+            const status = pct >= COVERAGE_THRESHOLD ? EMOJI.SUCCESS : EMOJI.FAILURE;
+            const shortFile = file.replace('packages/@patientpath/', '');
+            lines.push(`  ${status} ${shortFile}: ${pct.toFixed(1)}%`);
+        }
+    }
+    return lines.join(STRING_LITERALS.NEWLINE);
+}
+/**
+ * Run coverage gate.
+ *
+ * @param {CoverageGateOptions} options - Gate options
+ * @returns {Promise<{ ok: boolean, mode: string, duration: number, message: string }>}
+ */
+export async function runCoverageGate(options = {}) {
+    const start = Date.now();
+    const mode = options.mode || COVERAGE_GATE_MODES.WARN;
+    const coveragePath = options.coveragePath || DEFAULT_COVERAGE_PATH;
+    const logger = options.logger && typeof options.logger.log === 'function' ? options.logger : console;
+    // Parse coverage data
+    const coverageData = parseCoverageJson(coveragePath);
+    if (!coverageData) {
+        const duration = Date.now() - start;
+        logger.log(`\n${EMOJI.WARNING} Coverage gate: No coverage data found at ${coveragePath}`);
+        logger.log('  Run tests with coverage first: pnpm test:coverage\n');
+        return { ok: true, mode, duration, message: 'No coverage data' };
+    }
+    // Check thresholds
+    const { pass, failures } = checkCoverageThresholds(coverageData);
+    // Format and display
+    const output = formatCoverageDelta(coverageData);
+    logger.log(output);
+    const duration = Date.now() - start;
+    if (!pass) {
+        logger.log(`\n${EMOJI.FAILURE} Coverage below ${COVERAGE_THRESHOLD}% for hex core files:`);
+        for (const failure of failures) {
+            const shortFile = failure.file.replace('packages/@patientpath/', '');
+            logger.log(`  - ${shortFile}: ${failure.actual.toFixed(1)}% (requires ${failure.threshold}%)`);
+        }
+        if (mode === COVERAGE_GATE_MODES.BLOCK) {
+            logger.log(`\n${EMOJI.FAILURE} Coverage gate FAILED (mode: block)\n`);
+            return { ok: false, mode, duration, message: 'Coverage threshold not met' };
+        }
+        else {
+            logger.log(`\n${EMOJI.WARNING} Coverage gate WARNING (mode: warn)\n`);
+            logger.log('  Note: This will become blocking in future. Fix coverage now.\n');
+            return { ok: true, mode, duration, message: 'Coverage warning' };
+        }
+    }
+    logger.log(`\n${EMOJI.SUCCESS} Coverage gate passed\n`);
+    return { ok: true, mode, duration, message: 'Coverage OK' };
+}

package/dist/date-utils.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @file date-utils.mjs
+ * @description Date formatting utilities using date-fns library
+ * WU-1082: Extract shared utilities (eliminate date formatting duplication)
+ *
+ * Replaces manual date formatting in:
+ * - tools/wu-block.mjs (todayISO)
+ * - tools/wu-unblock.mjs (todayISO)
+ * - tools/wu-done.mjs (todayISO - already uses date-fns)
+ */
+/**
+ * Get current date in ISO format (YYYY-MM-DD)
+ * @returns {string} Current date in YYYY-MM-DD format
+ * @example
+ * todayISO(); // "2025-11-12"
+ */
+export declare function todayISO(): string;
+/**
+ * Format a date with a custom format string
+ * @param {Date|string|number} date - Date to format
+ * @param {string} formatString - date-fns format string
+ * @returns {string} Formatted date string
+ * @example
+ * formatDate(new Date(), 'yyyy-MM-dd HH:mm:ss');
+ * formatDate('2025-11-12', 'MMMM d, yyyy'); // "November 12, 2025"
+ */
+export declare function formatDate(date: any, formatString: any): string;
+/**
+ * Normalize a Date object or ISO timestamp string to YYYY-MM-DD format
+ *
+ * WU-1442: Fix date corruption when js-yaml parses YYYY-MM-DD as Date objects
+ * Library-First: Uses date-fns for date formatting (no manual parsing)
+ *
+ * Use case: js-yaml parses `created: 2025-12-04` (unquoted) as a Date object.
+ * When yaml.dump() serializes it back, it outputs `2025-12-04T00:00:00.000Z`.
+ * This function normalizes Date objects back to YYYY-MM-DD string format.
+ *
+ * Handles:
+ * - Date objects → YYYY-MM-DD string
+ * - ISO timestamp strings → YYYY-MM-DD string (date portion)
+ * - YYYY-MM-DD strings → preserved as-is
+ * - undefined/null → preserved as undefined
+ *
+ * @param {Date|string|undefined|null} value - Date value to normalize
+ * @returns {string|undefined} Date in YYYY-MM-DD format or undefined
+ *
+ * @example
+ * normalizeToDateString(new Date('2025-12-04')); // '2025-12-04'
+ * normalizeToDateString('2025-12-04T00:00:00.000Z'); // '2025-12-04'
+ * normalizeToDateString('2025-12-04'); // '2025-12-04'
+ * normalizeToDateString(undefined); // undefined
+ */
+export declare function normalizeToDateString(value: any): string;
+/**
+ * Normalize various date formats to ISO 8601 datetime (YYYY-MM-DDTHH:mm:ss.sssZ)
+ *
+ * WU-1337: Auto-repair date fields in WU YAML to consistent format
+ * Library-First: Uses date-fns for date handling (no manual parsing)
+ *
+ * Handles:
+ * - ISO date strings (YYYY-MM-DD) → midnight UTC
+ * - ISO datetime strings (already valid) → preserved
+ * - Unix timestamps (milliseconds) → converted
+ * - undefined/null → preserved as undefined
+ *
+ * @param {string|number|undefined|null} value - Date value to normalize
+ * @returns {string|undefined} ISO datetime string or undefined
+ *
+ * @example
+ * normalizeISODateTime('2025-11-29'); // '2025-11-29T00:00:00.000Z'
+ * normalizeISODateTime('2025-11-29T14:30:00.000Z'); // '2025-11-29T14:30:00.000Z'
+ * normalizeISODateTime(1732896000000); // '2024-11-29T16:00:00.000Z'
+ * normalizeISODateTime(undefined); // undefined
+ */
+export declare function normalizeISODateTime(value: any): string;