@lumenflow/core 3.1.3 → 3.2.1

package/dist/wu-transaction.js

@@ -0,0 +1,288 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * 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 UnsafeAny write fails → error with cleanup info
+ *
+ * WU-1665: Adds executeSnapshotRestore for state-machine-driven recovery.
+ * The restoreFromSnapshot function is the low-level primitive;
+ * executeSnapshotRestore is the entry point for pipeline-state-aware rollback.
+ */
+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 of this.pendingWrites.keys()) {
+            // 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 UnsafeAny 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 UnsafeAny 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 };
+}
+/**
+ * WU-1665: Execute snapshot restore for state-machine-driven recovery.
+ *
+ * This is the high-level entry point for snapshot-based rollback, used by the
+ * centralized rollbackFromPipelineState function in rollback-utils.ts.
+ * It delegates to restoreFromSnapshot but accepts a serializable Map format.
+ *
+ * @param {Map<string, string|null>} snapshot - Map of file paths to original content
+ * @returns {{ restored: string[], errors: { path: string, error: string }[] }}
+ */
+export function executeSnapshotRestore(snapshot) {
+    return restoreFromSnapshot(snapshot);
+}
+//# sourceMappingURL=wu-transaction.js.map

package/dist/wu-transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wu-transaction.js","sourceRoot":"","sources":["../src/wu-transaction.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACzF,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAc7D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,aAAa;IACP,IAAI,CAAS;IACb,aAAa,CAA4B;IAClD,SAAS,CAAU;IACnB,OAAO,CAAU;IACR,SAAS,CAAO;IAEjC;;;OAGG;IACH,YAAY,IAAY;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,aAAa,GAAG,IAAI,GAAG,EAAE,CAAC;QAC/B,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;IAC9B,CAAC;IAED;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAgB,EAAE,OAAe,EAAE,WAAmB;QAC7D,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,WAAW,CACf,UAAU,CAAC,iBAAiB,EAC5B,+CAA+C,IAAI,CAAC,IAAI,GAAG,EAC3D,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,CACpC,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,WAAW,CACf,UAAU,CAAC,iBAAiB,EAC5B,6CAA6C,IAAI,CAAC,IAAI,GAAG,EACzD,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,CACpC,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,EAAE;YAC/B,IAAI,EAAE,QAAQ;YACd,OAAO;YACP,WAAW;SACZ,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,gBAAgB;QACd,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,CAAC,CAAC;IACjD,CAAC;IAED;;;OAGG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;IACjC,CAAC;IAED;;;OAGG;IACH,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED;;;OAGG;IACH,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;;;;;;;;OASG;IACH,QAAQ;QACN,MAAM,MAAM,GAAa,EAAE,CAAC;QAE5B,IAAI,IAAI,CAAC,aAAa,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YAClC,MAAM,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAC;YAChD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAClC,CAAC;QAED,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC;YACjD,kDAAkD;YAClD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YACnC,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC3C,wDAAwD;gBACxD,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,IAAI,2BAA2B,GAAG,EAAE,CAAC,CAAC;YAClE,CAAC;QACH,CAAC;QAED,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAChD,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM;QACJ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,WAAW,CACf,UAAU,CAAC,iBAAiB,EAC5B,kCAAkC,IAAI,CAAC,IAAI,GAAG,EAC9C,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CACpB,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,WAAW,CACf,UAAU,CAAC,iBAAiB,EAC5B,sCAAsC,IAAI,CAAC,IAAI,GAAG,EAClD,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CACpB,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAsC,EAAE,CAAC;QAErD,OAAO,CAAC,GAAG,CACT,GAAG,UAAU,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO,iCAAiC,IAAI,CAAC,aAAa,CAAC,IAAI,mBAAmB,CAC/G,CAAC;QAEF,KAAK,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACnD,IAAI,CAAC;gBACH,iCAAiC;gBACjC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;gBACnC,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;oBAC3C,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;gBACtC,CAAC;gBAED,aAAa;gBACb,aAAa,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;gBAC9D,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACvB,OAAO,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,IAAI,MAAM,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;YAC5E,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,UAAU,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACpE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;gBACnD,OAAO,CAAC,KAAK,CAAC,GAAG,UAAU,CAAC,IAAI,MAAM,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,WAAW,KAAK,UAAU,EAAE,CAAC,CAAC;YAC7F,CAAC;QACH,CAAC;QAED,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QAE3B,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC;QAEpC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CACX,GAAG,UAAU,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO,+BAA+B,MAAM,CAAC,MAAM,WAAW,CAC3F,CAAC;QACJ,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IACtC,CAAC;IAED;;;;;OAKG;IACH,KAAK;QACH,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,OAAO,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO,yCAAyC,CAAC,CAAC;YAC3F,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;QACtC,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QAEpB,OAAO,CAAC,GAAG,CACT,GAAG,UAAU,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO,0BAA0B,KAAK,2BAA2B,CAC9F,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,QAAQ;QAQN,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,YAAY,EAAE,IAAI,CAAC,aAAa,CAAC,IAAI;YACrC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC;YAC5C,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE;SACxC,CAAC;IACJ,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAgB;IACrD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,YAAY,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,yBAAyB,CAAC,SAAmB;IAC3D,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAyB,CAAC;IAElD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,sBAAsB,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAoC;IAItE,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,MAAM,GAAsC,EAAE,CAAC;IAErD,KAAK,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,QAAQ,EAAE,CAAC;QAC3C,IAAI,CAAC;YACH,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACrB,qDAAqD;gBACrD,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;oBACzB,UAAU,CAAC,QAAQ,CAAC,CAAC;oBACrB,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBAC1B,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,2BAA2B;gBAC3B,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;gBACxD,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,UAAU,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACpE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AAC9B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAoC;IAIzE,OAAO,mBAAmB,CAAC,QAAQ,CAAC,CAAC;AACvC,CAAC"}

package/dist/wu-type-helpers.d.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * WU type/test helper predicates (WU-1444)
+ *
+ * Purpose: avoid duplicating policy via string literals across CLI/MCP.
+ */
+export declare function isDocumentationType(type: unknown): boolean;
+export declare function isProcessType(type: unknown): boolean;
+export declare function isDocsOrProcessType(type: unknown): boolean;
+export type TestsLike = {
+    manual?: unknown;
+    unit?: unknown;
+    e2e?: unknown;
+    integration?: unknown;
+} | undefined;
+/**
+ * True when UnsafeAny supported test array has at least one item.
+ * Supports the canonical tests object shape from WU YAML.
+ */
+export declare function hasAnyTests(tests: TestsLike): boolean;
+/**
+ * True when tests.manual has at least one item.
+ * Used for early lifecycle enforcement where manual verification is mandatory.
+ */
+export declare function hasManualTests(tests: TestsLike): boolean;
+//# sourceMappingURL=wu-type-helpers.d.ts.map

package/dist/wu-type-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wu-type-helpers.d.ts","sourceRoot":"","sources":["../src/wu-type-helpers.ts"],"names":[],"mappings":";AAGA;;;;GAIG;AAQH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAEpD;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED,MAAM,MAAM,SAAS,GACjB;IACE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GACD,SAAS,CAAC;AAEd;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAUrD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAIxD"}

package/dist/wu-type-helpers.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * WU type/test helper predicates (WU-1444)
+ *
+ * Purpose: avoid duplicating policy via string literals across CLI/MCP.
+ */
+import { TEST_TYPES, WU_TYPES } from './wu-constants.js';
+function isNonEmptyArray(value) {
+    return Array.isArray(value) && value.length > 0;
+}
+export function isDocumentationType(type) {
+    return typeof type === 'string' && type === WU_TYPES.DOCUMENTATION;
+}
+export function isProcessType(type) {
+    return typeof type === 'string' && type === WU_TYPES.PROCESS;
+}
+export function isDocsOrProcessType(type) {
+    return isDocumentationType(type) || isProcessType(type);
+}
+/**
+ * True when UnsafeAny supported test array has at least one item.
+ * Supports the canonical tests object shape from WU YAML.
+ */
+export function hasAnyTests(tests) {
+    if (!tests || typeof tests !== 'object')
+        return false;
+    const t = tests;
+    return (isNonEmptyArray(t[TEST_TYPES.MANUAL]) ||
+        isNonEmptyArray(t[TEST_TYPES.UNIT]) ||
+        isNonEmptyArray(t[TEST_TYPES.E2E]) ||
+        isNonEmptyArray(t[TEST_TYPES.INTEGRATION]));
+}
+/**
+ * True when tests.manual has at least one item.
+ * Used for early lifecycle enforcement where manual verification is mandatory.
+ */
+export function hasManualTests(tests) {
+    if (!tests || typeof tests !== 'object')
+        return false;
+    const t = tests;
+    return isNonEmptyArray(t[TEST_TYPES.MANUAL]);
+}
+//# sourceMappingURL=wu-type-helpers.js.map

package/dist/wu-type-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wu-type-helpers.js","sourceRoot":"","sources":["../src/wu-type-helpers.ts"],"names":[],"mappings":";AACA,iCAAiC;AACjC,yCAAyC;AACzC;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAEzD,SAAS,eAAe,CAAC,KAAc;IACrC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAAa;IAC/C,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,QAAQ,CAAC,aAAa,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAa;IACzC,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,QAAQ,CAAC,OAAO,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAAa;IAC/C,OAAO,mBAAmB,CAAC,IAAI,CAAC,IAAI,aAAa,CAAC,IAAI,CAAC,CAAC;AAC1D,CAAC;AAWD;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAgB;IAC1C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAEtD,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,OAAO,CACL,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QACrC,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACnC,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QAClC,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAC3C,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,KAAgB;IAC7C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,OAAO,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;AAC/C,CAAC"}

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

@@ -0,0 +1,235 @@
+/**
+ * UI and Display Constants
+ *
+ * WU-1549: Extracted from wu-constants.ts for domain-specific modularity.
+ * Contains backlog sections, status sections, log prefixes, emoji, box drawing,
+ * display limits, string literals, YAML options, and readiness UI.
+ *
+ * @module wu-ui-constants
+ */
+/**
+ * Backlog section headings (with emojis)
+ *
+ * These match the frontmatter config in backlog.md
+ */
+export declare const BACKLOG_SECTIONS: {
+    READY: string;
+    IN_PROGRESS: string;
+    BLOCKED: string;
+    DONE: string;
+};
+/**
+ * Backlog bullet format types (WU-1444)
+ *
+ * Used by BacklogManager to format list items in each section.
+ * Each format produces a different markdown bullet style.
+ */
+export declare const BACKLOG_BULLET_FORMAT: {
+    /** Ready format: '- [ ] [WU-ID -- Title](link)' */
+    READY: string;
+    /** Progress format: '- [WU-ID -- Title](link)' */
+    PROGRESS: string;
+    /** Blocked format: '- [ ] [WU-ID -- Title](link) -- Reason' */
+    BLOCKED: string;
+    /** Done format: '- [x] [WU-ID -- Title](link) (YYYY-MM-DD)' */
+    DONE: string;
+};
+/**
+ * Status.md section headings (simpler format)
+ */
+export declare const STATUS_SECTIONS: {
+    IN_PROGRESS: string;
+    BLOCKED: string;
+    COMPLETED: string;
+};
+/**
+ * Log prefixes for wu- scripts
+ *
+ * Consistent prefixes for console output
+ */
+export declare const LOG_PREFIX: {
+    DONE: string;
+    CLAIM: string;
+    CREATE: string;
+    EDIT: string;
+    DELETE: string;
+    BLOCK: string;
+    UNBLOCK: string;
+    UNLOCK_LANE: string;
+    CLEANUP: string;
+    PRUNE: string;
+    REPAIR: string;
+    CONSISTENCY: string;
+    PREFLIGHT: string;
+    INITIATIVE_PLAN: string;
+    PLAN_CREATE: string;
+    PLAN_LINK: string;
+    PLAN_EDIT: string;
+    PLAN_PROMOTE: string;
+};
+/**
+ * Emoji constants for consistent console output
+ *
+ * WU-1281: Centralized from hardcoded emojis across wu-* scripts
+ */
+export declare const EMOJI: {
+    SUCCESS: string;
+    FAILURE: string;
+    WARNING: string;
+    INFO: string;
+    BLOCKED: string;
+    ROCKET: string;
+    WRENCH: string;
+    TARGET: string;
+    MEMO: string;
+    FOLDER: string;
+};
+/**
+ * Box drawing characters for console output
+ *
+ * Emergency fix (Session 2): Centralized to eliminate sonarjs/no-duplicate-string errors
+ * Used for recovery dialogs and error boxes in wu-* scripts
+ */
+export declare const BOX: {
+    /** Top border: ╔══...══╗ (66 chars inside + corners = 68 total) */
+    TOP: string;
+    /** Middle separator: ╠══...══╣ */
+    MID: string;
+    /** Bottom border: ╚══...══╝ */
+    BOT: string;
+    /** Side border for content lines */
+    SIDE: string;
+};
+/**
+ * UI display constants
+ *
+ * WU-1281: Centralized from hardcoded values in wu-done.ts
+ */
+export declare const UI: {
+    /** Width for error/info boxes in console output */
+    ERROR_BOX_WIDTH: number;
+    /** Number of lines to show in status file preview */
+    STATUS_PREVIEW_LINES: number;
+};
+/**
+ * Display limits for CLI output (WU-1068)
+ *
+ * Centralized limits for truncating display strings to avoid magic numbers.
+ */
+export declare const DISPLAY_LIMITS: {
+    /** Maximum items to show in lists before truncating */
+    LIST_ITEMS: number;
+    /** Maximum items to show in short lists */
+    SHORT_LIST: number;
+    /** Maximum characters for content preview */
+    CONTENT_PREVIEW: number;
+    /** Maximum characters for short preview */
+    SHORT_PREVIEW: number;
+    /** Maximum characters for title display */
+    TITLE: number;
+    /** Maximum characters for truncated title */
+    TRUNCATED_TITLE: number;
+    /** Maximum characters for command preview */
+    CMD_PREVIEW: number;
+    /** Maximum lines to preview from files */
+    FILE_LINES: number;
+    /** Maximum commits to show in lists */
+    COMMITS: number;
+    /** Maximum overlaps to display */
+    OVERLAPS: number;
+};
+/**
+ * YAML serialization options
+ *
+ * Centralized from duplicated { lineWidth: 100 } across wu-* scripts (WU-1256).
+ * Use with yaml stringify() options.
+ */
+export declare const YAML_OPTIONS: {
+    /** Standard line width for YAML dump (100 chars) */
+    LINE_WIDTH: number;
+    /** No line wrapping (-1 disables wrapping) */
+    NO_WRAP: number;
+};
+/**
+ * Process argv indices (WU-1068)
+ *
+ * Centralized indices for process.argv access to eliminate magic numbers.
+ * In Node.js: argv[0] = node, argv[1] = script, argv[2+] = args
+ */
+export declare const ARGV_INDICES: {
+    /** Node executable path */
+    NODE: number;
+    /** Script path */
+    SCRIPT: number;
+    /** First user argument */
+    FIRST_ARG: number;
+    /** Second user argument */
+    SECOND_ARG: number;
+};
+/**
+ * String formatting constants
+ *
+ * Centralized string literals for consistent formatting across scripts.
+ * Eliminates hardcoded '\n', ' ', etc. throughout the codebase.
+ */
+export declare const STRING_LITERALS: {
+    /** Newline character */
+    NEWLINE: string;
+    /** Double newline (paragraph separator) */
+    DOUBLE_NEWLINE: string;
+    /** Space character */
+    SPACE: string;
+    /** Empty string */
+    EMPTY: string;
+    /** Tab character */
+    TAB: string;
+    /** Comma separator */
+    COMMA: string;
+    /** Colon separator */
+    COLON: string;
+    /** Dash/hyphen */
+    DASH: string;
+    /** Forward slash */
+    SLASH: string;
+};
+/**
+ * Readiness summary UI constants (WU-1620)
+ *
+ * Constants for the readiness summary box displayed after wu:create and wu:edit.
+ * Provides visual feedback on whether WU is ready for wu:claim.
+ *
+ * @see tools/wu-create.ts - displayReadinessSummary()
+ * @see tools/wu-edit.ts - displayReadinessSummary()
+ */
+export declare const READINESS_UI: {
+    /** Box width (inner content area) */
+    BOX_WIDTH: number;
+    /** Box drawing characters */
+    BOX: {
+        TOP_LEFT: string;
+        TOP_RIGHT: string;
+        BOTTOM_LEFT: string;
+        BOTTOM_RIGHT: string;
+        HORIZONTAL: string;
+        VERTICAL: string;
+    };
+    /** Status messages */
+    MESSAGES: {
+        READY_YES: string;
+        READY_NO: string;
+        MISSING_HEADER: string;
+        BULLET: string;
+    };
+    /** Error truncation length */
+    ERROR_MAX_LENGTH: number;
+    ERROR_TRUNCATE_LENGTH: number;
+    TRUNCATION_SUFFIX: string;
+    /** Padding calculations (relative to BOX_WIDTH) */
+    PADDING: {
+        READY_YES: number;
+        READY_NO: number;
+        MISSING_HEADER: number;
+        ERROR_BULLET: number;
+    };
+};
+//# sourceMappingURL=wu-ui-constants.d.ts.map

package/dist/wu-ui-constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wu-ui-constants.d.ts","sourceRoot":"","sources":["../src/wu-ui-constants.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;;CAK5B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;IAChC,mDAAmD;;IAEnD,kDAAkD;;IAElD,+DAA+D;;IAE/D,+DAA+D;;CAEhE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe;;;;CAI3B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;CAmBtB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,KAAK;;;;;;;;;;;CAWjB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,GAAG;IACd,mEAAmE;;IAGnE,kCAAkC;;IAGlC,+BAA+B;;IAG/B,oCAAoC;;CAErC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,EAAE;IACb,mDAAmD;;IAGnD,qDAAqD;;CAEtD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc;IACzB,uDAAuD;;IAEvD,2CAA2C;;IAE3C,6CAA6C;;IAE7C,2CAA2C;;IAE3C,2CAA2C;;IAE3C,6CAA6C;;IAE7C,6CAA6C;;IAE7C,0CAA0C;;IAE1C,uCAAuC;;IAEvC,kCAAkC;;CAEnC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,YAAY;IACvB,oDAAoD;;IAGpD,8CAA8C;;CAE/C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,YAAY;IACvB,2BAA2B;;IAE3B,kBAAkB;;IAElB,0BAA0B;;IAE1B,2BAA2B;;CAE5B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,eAAe;IAC1B,wBAAwB;;IAGxB,2CAA2C;;IAG3C,sBAAsB;;IAGtB,mBAAmB;;IAGnB,oBAAoB;;IAGpB,sBAAsB;;IAGtB,sBAAsB;;IAGtB,kBAAkB;;IAGlB,oBAAoB;;CAErB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY;IACvB,qCAAqC;;IAGrC,6BAA6B;;;;;;;;;IAU7B,sBAAsB;;;;;;;IAQtB,8BAA8B;;;;IAK9B,mDAAmD;;;;;;;CAOpD,CAAC"}