@lumenflow/core 1.0.0

package/dist/wu-transaction.js

@@ -0,0 +1,273 @@
+/**
+ * WU Transaction - Atomic write operations for wu:done
+ *
+ * WU-1369: Implements transactional pattern for metadata updates.
+ * Collects all changes in memory, validates, then writes atomically.
+ *
+ * Pattern:
+ * 1. Create transaction
+ * 2. Collect all pending writes (in memory)
+ * 3. Validate pending state
+ * 4. Commit (write all files) or abort (discard)
+ *
+ * This ensures no partial state on validation failure:
+ * - If validation fails → no files written
+ * - If any write fails → error with cleanup info
+ */
+import { existsSync, writeFileSync, mkdirSync, readFileSync, unlinkSync } from 'node:fs';
+import path from 'node:path';
+import { LOG_PREFIX, EMOJI } from './wu-constants.js';
+import { createError, ErrorCodes } from './error-handler.js';
+/**
+ * Transaction for atomic metadata updates
+ *
+ * Usage:
+ * ```js
+ * const tx = new WUTransaction(id);
+ *
+ * // Collect pending changes
+ * tx.addWrite(wuPath, yamlContent, 'WU YAML');
+ * tx.addWrite(statusPath, statusContent, 'status.md');
+ *
+ * // Validate (no writes happen yet)
+ * const validation = tx.validate();
+ * if (!validation.valid) {
+ *   tx.abort();
+ *   return;
+ * }
+ *
+ * // Commit all changes atomically
+ * const result = tx.commit();
+ * ```
+ */
+export class WUTransaction {
+    wuId;
+    pendingWrites;
+    committed;
+    aborted;
+    createdAt;
+    /**
+     * Create a new transaction
+     * @param {string} wuId - WU ID for logging context
+     */
+    constructor(wuId) {
+        this.wuId = wuId;
+        this.pendingWrites = new Map();
+        this.committed = false;
+        this.aborted = false;
+        this.createdAt = new Date();
+    }
+    /**
+     * Add a pending file write operation
+     *
+     * @param {string} filePath - File path to write
+     * @param {string} content - Content to write
+     * @param {string} description - Human-readable description
+     * @throws {Error} If transaction already committed or aborted
+     */
+    addWrite(filePath, content, description) {
+        if (this.committed) {
+            throw createError(ErrorCodes.TRANSACTION_ERROR, `Cannot add writes to committed transaction (${this.wuId})`, { wuId: this.wuId, path: filePath });
+        }
+        if (this.aborted) {
+            throw createError(ErrorCodes.TRANSACTION_ERROR, `Cannot add writes to aborted transaction (${this.wuId})`, { wuId: this.wuId, path: filePath });
+        }
+        this.pendingWrites.set(filePath, {
+            path: filePath,
+            content,
+            description,
+        });
+    }
+    /**
+     * Get pending writes for inspection
+     * @returns {PendingWrite[]}
+     */
+    getPendingWrites() {
+        return Array.from(this.pendingWrites.values());
+    }
+    /**
+     * Get count of pending writes
+     * @returns {number}
+     */
+    get size() {
+        return this.pendingWrites.size;
+    }
+    /**
+     * Check if transaction has been committed
+     * @returns {boolean}
+     */
+    get isCommitted() {
+        return this.committed;
+    }
+    /**
+     * Check if transaction has been aborted
+     * @returns {boolean}
+     */
+    get isAborted() {
+        return this.aborted;
+    }
+    /**
+     * Validate pending writes (pre-commit checks)
+     *
+     * Checks:
+     * - All parent directories can be created
+     * - No duplicate paths with different content
+     * - Content is valid (non-empty for critical files)
+     *
+     * @returns {{ valid: boolean, errors: string[] }}
+     */
+    validate() {
+        const errors = [];
+        if (this.pendingWrites.size === 0) {
+            errors.push('No pending writes in transaction');
+            return { valid: false, errors };
+        }
+        for (const [filePath, write] of this.pendingWrites) {
+            // Check content is defined
+            if (write.content === undefined || write.content === null) {
+                errors.push(`${write.description}: Content is undefined`);
+                continue;
+            }
+            // Check parent directory exists or can be created
+            const dir = path.dirname(filePath);
+            if (dir && dir !== '.' && !existsSync(dir)) {
+                // Will be created during commit - just note for logging
+                console.log(`${LOG_PREFIX.DONE} Will create directory: ${dir}`);
+            }
+        }
+        return { valid: errors.length === 0, errors };
+    }
+    /**
+     * Commit all pending writes atomically
+     *
+     * Writes all files in a single batch. If any write fails,
+     * reports which files were written vs failed.
+     *
+     * @returns {{ success: boolean, written: string[], failed: { path: string, error: string }[] }}
+     * @throws {Error} If transaction already committed or aborted
+     */
+    commit() {
+        if (this.committed) {
+            throw createError(ErrorCodes.TRANSACTION_ERROR, `Transaction already committed (${this.wuId})`, { wuId: this.wuId });
+        }
+        if (this.aborted) {
+            throw createError(ErrorCodes.TRANSACTION_ERROR, `Cannot commit aborted transaction (${this.wuId})`, { wuId: this.wuId });
+        }
+        const written = [];
+        const failed = [];
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.SUCCESS} Transaction COMMIT - writing ${this.pendingWrites.size} files atomically`);
+        for (const [filePath, write] of this.pendingWrites) {
+            try {
+                // Ensure parent directory exists
+                const dir = path.dirname(filePath);
+                if (dir && dir !== '.' && !existsSync(dir)) {
+                    mkdirSync(dir, { recursive: true });
+                }
+                // Write file
+                writeFileSync(filePath, write.content, { encoding: 'utf-8' });
+                written.push(filePath);
+                console.log(`${LOG_PREFIX.DONE}   ${EMOJI.SUCCESS} ${write.description}`);
+            }
+            catch (err) {
+                const errMessage = err instanceof Error ? err.message : String(err);
+                failed.push({ path: filePath, error: errMessage });
+                console.error(`${LOG_PREFIX.DONE}   ${EMOJI.FAILURE} ${write.description}: ${errMessage}`);
+            }
+        }
+        this.committed = true;
+        this.pendingWrites.clear();
+        const success = failed.length === 0;
+        if (!success) {
+            console.error(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Transaction completed with ${failed.length} failures`);
+        }
+        return { success, written, failed };
+    }
+    /**
+     * Abort transaction (discard pending writes)
+     *
+     * Since no writes have been made, this just clears pending changes.
+     * This is the key benefit of the transactional pattern.
+     */
+    abort() {
+        if (this.committed) {
+            console.warn(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Aborting already-committed transaction`);
+            return;
+        }
+        const count = this.pendingWrites.size;
+        this.pendingWrites.clear();
+        this.aborted = true;
+        console.log(`${LOG_PREFIX.DONE} ${EMOJI.WARNING} Transaction ABORTED - ${count} pending writes discarded`);
+    }
+    /**
+     * Get transaction state for debugging
+     */
+    getState() {
+        return {
+            wuId: this.wuId,
+            committed: this.committed,
+            aborted: this.aborted,
+            pendingCount: this.pendingWrites.size,
+            files: Array.from(this.pendingWrites.keys()),
+            createdAt: this.createdAt.toISOString(),
+        };
+    }
+}
+/**
+ * Read file content for transaction (pre-compute backup)
+ *
+ * @param {string} filePath - File to read
+ * @returns {string|null} - File content or null if doesn't exist
+ */
+export function readFileForTransaction(filePath) {
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    return readFileSync(filePath, { encoding: 'utf-8' });
+}
+/**
+ * Create a transaction state snapshot for rollback
+ *
+ * Captures current file contents before any modifications.
+ * Used if git operations fail after transaction commit.
+ *
+ * @param {string[]} filePaths - Paths to snapshot
+ * @returns {Map<string, string|null>} - Map of path to content (null = didn't exist)
+ */
+export function createTransactionSnapshot(filePaths) {
+    const snapshot = new Map();
+    for (const filePath of filePaths) {
+        snapshot.set(filePath, readFileForTransaction(filePath));
+    }
+    return snapshot;
+}
+/**
+ * Restore files from snapshot (for rollback after commit)
+ *
+ * @param {Map<string, string|null>} snapshot - Snapshot from createTransactionSnapshot
+ * @returns {{ restored: string[], errors: { path: string, error: string }[] }}
+ */
+export function restoreFromSnapshot(snapshot) {
+    const restored = [];
+    const errors = [];
+    for (const [filePath, content] of snapshot) {
+        try {
+            if (content === null) {
+                // File didn't exist before - delete if it exists now
+                if (existsSync(filePath)) {
+                    unlinkSync(filePath);
+                    restored.push(filePath);
+                }
+            }
+            else {
+                // Restore original content
+                writeFileSync(filePath, content, { encoding: 'utf-8' });
+                restored.push(filePath);
+            }
+        }
+        catch (err) {
+            const errMessage = err instanceof Error ? err.message : String(err);
+            errors.push({ path: filePath, error: errMessage });
+        }
+    }
+    return { restored, errors };
+}

package/dist/wu-validation-constants.d.ts

@@ -0,0 +1,60 @@
+/**
+ * WU Validation Constants (WU-1243)
+ *
+ * Centralizes magic numbers for lane inference and incident validation.
+ * Extracted from lane-inference.mjs and agent-incidents.mjs for DRY compliance.
+ *
+ * @module wu-validation-constants
+ */
+/**
+ * Lane inference scoring weights.
+ * Code path matches are weighted higher than keywords because
+ * file paths are more reliable signals for lane classification.
+ *
+ * The 10:3 ratio (~3.3x) reflects that a code path match is approximately
+ * 3x more indicative of the correct lane than a keyword match.
+ */
+export declare const WEIGHTS: {
+    /** Weight for code path pattern matches (more reliable signal) */
+    CODE_PATH_MATCH: number;
+    /** Weight for keyword matches in description (less specific signal) */
+    KEYWORD_MATCH: number;
+};
+/**
+ * Confidence score configuration for lane inference.
+ *
+ * WU-2438: Changed from percentage-based (0-100) to absolute scoring.
+ * Raw scores (sum of WEIGHTS) are now returned directly.
+ * Higher score = better match, regardless of config size.
+ */
+export declare const CONFIDENCE: {
+    /** Minimum confidence value (no matches) */
+    MIN: number;
+    /** Maximum confidence value (legacy, kept for backward compatibility) */
+    MAX: number;
+    /**
+     * Minimum confidence threshold to return a suggestion.
+     * Set to 0 to always return best match (even low confidence).
+     * Note: With absolute scoring, this threshold is compared against raw scores.
+     */
+    THRESHOLD: number;
+};
+/**
+ * String length validation limits for incident logging.
+ * Prevents abuse while allowing meaningful content.
+ */
+export declare const VALIDATION_LIMITS: {
+    /** Minimum title length (prevents truncated/empty titles) */
+    TITLE_MIN: number;
+    /** Maximum title length (keeps logs readable) */
+    TITLE_MAX: number;
+    /** Minimum description length (prevents one-liners) */
+    DESCRIPTION_MIN: number;
+    /** Maximum description length (prevents unbounded logging) */
+    DESCRIPTION_MAX: number;
+};
+/**
+ * Valid incident categories for agent issue logging.
+ * Duplicated from agent-incidents.mjs z.enum for use in default arrays.
+ */
+export declare const INCIDENT_CATEGORIES: readonly ["workflow", "tooling", "confusion", "violation", "error"];

package/dist/wu-validation-constants.js

@@ -0,0 +1,66 @@
+/**
+ * WU Validation Constants (WU-1243)
+ *
+ * Centralizes magic numbers for lane inference and incident validation.
+ * Extracted from lane-inference.mjs and agent-incidents.mjs for DRY compliance.
+ *
+ * @module wu-validation-constants
+ */
+/**
+ * Lane inference scoring weights.
+ * Code path matches are weighted higher than keywords because
+ * file paths are more reliable signals for lane classification.
+ *
+ * The 10:3 ratio (~3.3x) reflects that a code path match is approximately
+ * 3x more indicative of the correct lane than a keyword match.
+ */
+export const WEIGHTS = {
+    /** Weight for code path pattern matches (more reliable signal) */
+    CODE_PATH_MATCH: 10,
+    /** Weight for keyword matches in description (less specific signal) */
+    KEYWORD_MATCH: 3,
+};
+/**
+ * Confidence score configuration for lane inference.
+ *
+ * WU-2438: Changed from percentage-based (0-100) to absolute scoring.
+ * Raw scores (sum of WEIGHTS) are now returned directly.
+ * Higher score = better match, regardless of config size.
+ */
+export const CONFIDENCE = {
+    /** Minimum confidence value (no matches) */
+    MIN: 0,
+    /** Maximum confidence value (legacy, kept for backward compatibility) */
+    MAX: 100,
+    /**
+     * Minimum confidence threshold to return a suggestion.
+     * Set to 0 to always return best match (even low confidence).
+     * Note: With absolute scoring, this threshold is compared against raw scores.
+     */
+    THRESHOLD: 0,
+};
+/**
+ * String length validation limits for incident logging.
+ * Prevents abuse while allowing meaningful content.
+ */
+export const VALIDATION_LIMITS = {
+    /** Minimum title length (prevents truncated/empty titles) */
+    TITLE_MIN: 5,
+    /** Maximum title length (keeps logs readable) */
+    TITLE_MAX: 100,
+    /** Minimum description length (prevents one-liners) */
+    DESCRIPTION_MIN: 10,
+    /** Maximum description length (prevents unbounded logging) */
+    DESCRIPTION_MAX: 2000,
+};
+/**
+ * Valid incident categories for agent issue logging.
+ * Duplicated from agent-incidents.mjs z.enum for use in default arrays.
+ */
+export const INCIDENT_CATEGORIES = [
+    'workflow',
+    'tooling',
+    'confusion',
+    'violation',
+    'error',
+];

package/dist/wu-validation.d.ts

@@ -0,0 +1,118 @@
+/**
+ * WU Exposure Validation (WU-1999, WU-2022)
+ *
+ * WU-1999: Validates exposure field and UI pairing for wu:done.
+ *          Provides warnings (not errors) to guide completion without blocking.
+ *
+ * WU-2022: Adds BLOCKING validation for feature accessibility.
+ *          When exposure=ui, ensures the feature is actually accessible via navigation.
+ *
+ * Part of INIT-031 Phase 4: Prevent backend-without-UI pattern.
+ *
+ * @see {@link tools/wu-done.mjs} - Consumer
+ * @see {@link tools/lib/wu-schema.mjs} - WU schema with exposure field
+ * @see {@link tools/lib/wu-constants.mjs} - WU_EXPOSURE values
+ */
+/**
+ * Warning message templates with remediation guidance.
+ * All messages include the WU ID for context.
+ */
+export declare const EXPOSURE_WARNING_MESSAGES: {
+    /**
+     * Warning when exposure field is missing entirely.
+     * @param {string} wuId - The WU identifier
+     * @returns {string} Warning message with remediation
+     */
+    MISSING_EXPOSURE: (wuId: any) => string;
+    /**
+     * Warning when API exposure lacks UI pairing WUs.
+     * @param {string} wuId - The WU identifier
+     * @returns {string} Warning message with remediation
+     */
+    MISSING_UI_PAIRING: (wuId: any) => string;
+    /**
+     * Warning when API exposure lacks UI verification in acceptance criteria.
+     * @param {string} wuId - The WU identifier
+     * @returns {string} Warning message with remediation
+     */
+    MISSING_UI_VERIFICATION: (wuId: any) => string;
+    /**
+     * Recommendation for user_journey when exposure is UI.
+     * @param {string} wuId - The WU identifier
+     * @returns {string} Warning message with remediation
+     */
+    MISSING_USER_JOURNEY: (wuId: any) => string;
+};
+/**
+ * Validate exposure field and UI pairing for a WU.
+ *
+ * This is a non-blocking validation that returns warnings, not errors.
+ * Use during wu:done to guide completion without preventing it.
+ *
+ * Checks:
+ * 1. exposure field is present (warns if missing)
+ * 2. If exposure=api, warns if no ui_pairing_wus specified
+ * 3. If exposure=api, checks acceptance criteria for UI verification mention
+ * 4. If exposure=ui, recommends user_journey field if not present
+ *
+ * @param {object} wu - WU YAML object
+ * @param {string} wu.id - WU identifier
+ * @param {string} [wu.exposure] - Exposure type (ui, api, backend-only, documentation)
+ * @param {string[]} [wu.ui_pairing_wus] - Related UI WU IDs for API exposure
+ * @param {string} [wu.user_journey] - User journey description for UI exposure
+ * @param {string[]|object} [wu.acceptance] - Acceptance criteria
+ * @param {ValidateExposureOptions} [options] - Validation options
+ * @returns {{valid: boolean, warnings: string[]}} Validation result
+ */
+interface ValidateExposureOptions {
+    /** Skip all exposure validation */
+    skipExposureCheck?: boolean;
+}
+export declare function validateExposure(wu: any, options?: ValidateExposureOptions): {
+    valid: boolean;
+    warnings: any[];
+};
+/**
+ * Error message templates for accessibility validation (WU-2022).
+ * These are BLOCKING errors, not warnings.
+ */
+export declare const ACCESSIBILITY_ERROR_MESSAGES: {
+    /**
+     * Error when UI exposure lacks navigation accessibility proof.
+     * @param {string} wuId - The WU identifier
+     * @returns {string} Error message with remediation guidance
+     */
+    UI_NOT_ACCESSIBLE: (wuId: any) => string;
+};
+/**
+ * Validate feature accessibility for UI-exposed WUs (WU-2022).
+ *
+ * This is a BLOCKING validation that returns errors (not warnings).
+ * When exposure=ui, the feature must be verifiably accessible.
+ *
+ * Accessibility is verified by ANY of:
+ * 1. navigation_path field is specified (explicit route)
+ * 2. code_paths includes a page.tsx file (Next.js page)
+ * 3. tests.manual includes navigation/accessibility verification
+ *
+ * Non-UI exposures (api, backend-only, documentation) pass automatically.
+ * Missing exposure field passes (legacy WUs, handled by WU-1999 warning).
+ *
+ * @param {object} wu - WU YAML object
+ * @param {string} wu.id - WU identifier
+ * @param {string} [wu.exposure] - Exposure type (ui, api, backend-only, documentation)
+ * @param {string} [wu.navigation_path] - Route where UI is accessible
+ * @param {string[]} [wu.code_paths] - Files modified by this WU
+ * @param {object} [wu.tests] - Test specifications
+ * @param {ValidateFeatureAccessibilityOptions} [options] - Validation options
+ * @returns {{valid: boolean, errors: string[]}} Validation result
+ */
+interface ValidateFeatureAccessibilityOptions {
+    /** Skip all accessibility validation */
+    skipAccessibilityCheck?: boolean;
+}
+export declare function validateFeatureAccessibility(wu: any, options?: ValidateFeatureAccessibilityOptions): {
+    valid: boolean;
+    errors: any[];
+};
+export {};