@lumenflow/core 2.2.2 → 2.3.2

package/dist/wu-events-cleanup.js

@@ -0,0 +1,401 @@
+/**
+ * WU Events Cleanup (WU-1207)
+ *
+ * Archive old WU events to prevent unbounded growth of wu-events.jsonl.
+ * Moves completed WU events older than 90d to .lumenflow/archive/wu-events-YYYY-MM.jsonl.
+ * Keeps active WU events intact.
+ *
+ * Features:
+ * - Configurable archiveAfter threshold (default: 90 days)
+ * - Groups events by WU ID for atomic archival
+ * - Monthly archive file rollup
+ * - Active WU protection (in_progress/blocked/waiting never archived)
+ * - Dry-run mode for preview
+ *
+ * Reuses atomic write patterns from wu-state-store.ts.
+ *
+ * @see {@link packages/@lumenflow/core/src/__tests__/wu-events-cleanup.test.ts} - Tests
+ */
+import fs from 'node:fs/promises';
+import { writeFileSync, mkdirSync, openSync, closeSync, fsyncSync, renameSync, unlinkSync, } from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const ms = require('ms');
+import { validateWUEvent } from './wu-state-schema.js';
+import { WUStateStore, WU_EVENTS_FILE_NAME } from './wu-state-store.js';
+/**
+ * One day in milliseconds
+ */
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * LumenFlow paths for state and archive
+ */
+const LUMENFLOW_PATHS = {
+    STATE_DIR: '.lumenflow/state',
+    ARCHIVE_DIR: '.lumenflow/archive',
+};
+/**
+ * Default event archival configuration
+ */
+export const DEFAULT_EVENT_ARCHIVAL_CONFIG = {
+    archiveAfter: 90 * ONE_DAY_MS,
+    keepArchives: true,
+};
+/**
+ * Parse an archiveAfter duration string into milliseconds.
+ *
+ * Uses the `ms` package to parse human-readable duration strings.
+ *
+ * @param archiveAfterString - Duration string (e.g., '90d', '30d', '24h')
+ * @returns Duration in milliseconds
+ * @throws If format is invalid
+ *
+ * @example
+ * parseArchiveAfter('90d');  // 7776000000 (90 days in ms)
+ * parseArchiveAfter('30d');  // 2592000000 (30 days in ms)
+ */
+export function parseArchiveAfter(archiveAfterString) {
+    if (!archiveAfterString || typeof archiveAfterString !== 'string') {
+        throw new Error('Invalid archiveAfter format: duration string is required');
+    }
+    const trimmed = archiveAfterString.trim();
+    if (!trimmed) {
+        throw new Error('Invalid archiveAfter format: duration string is required');
+    }
+    const result = ms(trimmed);
+    if (result === undefined || result <= 0) {
+        throw new Error(`Invalid archiveAfter format: "${archiveAfterString}" is not a valid duration`);
+    }
+    return result;
+}
+/**
+ * Get the archive file path for a given event timestamp.
+ *
+ * Groups events by month into files like:
+ * .lumenflow/archive/wu-events-2026-01.jsonl
+ *
+ * @param timestamp - ISO 8601 timestamp string
+ * @returns Relative path to archive file
+ *
+ * @example
+ * getArchiveFilePath('2026-01-15T10:30:00.000Z');
+ * // Returns: '.lumenflow/archive/wu-events-2026-01.jsonl'
+ */
+export function getArchiveFilePath(timestamp) {
+    const date = new Date(timestamp);
+    const year = date.getUTCFullYear();
+    const month = String(date.getUTCMonth() + 1).padStart(2, '0');
+    return `${LUMENFLOW_PATHS.ARCHIVE_DIR}/wu-events-${year}-${month}.jsonl`;
+}
+/**
+ * Check if an event's WU is older than the archive threshold.
+ *
+ * Uses the complete event timestamp (if WU is done) to determine age.
+ *
+ * @param timestamp - Event timestamp
+ * @param archiveAfterMs - Threshold in milliseconds
+ * @param now - Current timestamp
+ * @returns True if event is older than threshold
+ */
+function isOlderThanThreshold(timestamp, archiveAfterMs, now) {
+    const eventTime = new Date(timestamp).getTime();
+    if (Number.isNaN(eventTime)) {
+        return false; // Invalid timestamp - safer to retain
+    }
+    const age = now - eventTime;
+    return age > archiveAfterMs;
+}
+/**
+ * Determine if an event should be archived based on WU status and age.
+ *
+ * Policy rules (checked in order):
+ * 1. Active WU events (in_progress/blocked/waiting) are never archived
+ * 2. Completed WU events older than threshold are archived
+ * 3. Otherwise, event is retained
+ *
+ * @param event - WU event to check
+ * @param config - Archival configuration
+ * @param context - Archive context (now timestamp, active WU IDs)
+ * @returns Archive decision with reason
+ */
+export function shouldArchiveEvent(event, config, context) {
+    const { now, activeWuIds } = context;
+    // Active WU protection: events linked to in_progress/blocked/waiting WUs are always retained
+    if (activeWuIds.has(event.wuId)) {
+        return { archive: false, reason: 'active-wu-protected' };
+    }
+    // Check age threshold
+    if (isOlderThanThreshold(event.timestamp, config.archiveAfter, now)) {
+        return { archive: true, reason: 'completed-older-than-threshold' };
+    }
+    // Default: retain
+    return { archive: false, reason: 'within-retention-period' };
+}
+/**
+ * Load all events from wu-events.jsonl file.
+ *
+ * @param baseDir - Project base directory
+ * @returns Array of all WU events
+ */
+async function loadAllEvents(baseDir) {
+    const eventsPath = path.join(baseDir, LUMENFLOW_PATHS.STATE_DIR, WU_EVENTS_FILE_NAME);
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool reads known path
+        const content = await fs.readFile(eventsPath, { encoding: 'utf-8' });
+        const lines = content.split('\n').filter((line) => line.trim());
+        return lines.map((line) => {
+            const parsed = JSON.parse(line);
+            const validation = validateWUEvent(parsed);
+            if (!validation.success) {
+                // Return as-is if validation fails (repair later)
+                return parsed;
+            }
+            return validation.data;
+        });
+    }
+    catch (err) {
+        const error = err;
+        if (error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+/**
+ * Get active WU IDs by replaying events to determine current state.
+ *
+ * A WU is active if its last status-changing event leaves it in:
+ * - in_progress (claim without complete)
+ * - blocked (block without unblock)
+ * - waiting (could be future state)
+ *
+ * @param baseDir - Project base directory
+ * @returns Set of active WU IDs
+ */
+async function getActiveWuIdsFromStore(baseDir) {
+    const store = new WUStateStore(path.join(baseDir, LUMENFLOW_PATHS.STATE_DIR));
+    await store.load();
+    const activeStatuses = ['in_progress', 'blocked', 'waiting'];
+    const activeIds = new Set();
+    for (const status of activeStatuses) {
+        const wuIds = store.getByStatus(status);
+        for (const wuId of wuIds) {
+            activeIds.add(wuId);
+        }
+    }
+    return activeIds;
+}
+/**
+ * Build archival configuration from options.
+ *
+ * @param options - Archive options
+ * @returns Effective archival configuration
+ */
+function buildArchivalConfig(options) {
+    const { archiveAfter, archiveAfterMs: providedArchiveAfterMs } = options;
+    let archiveAfterMs = providedArchiveAfterMs ?? DEFAULT_EVENT_ARCHIVAL_CONFIG.archiveAfter;
+    if (archiveAfter && !providedArchiveAfterMs) {
+        archiveAfterMs = parseArchiveAfter(archiveAfter);
+    }
+    return {
+        archiveAfter: archiveAfterMs,
+        keepArchives: DEFAULT_EVENT_ARCHIVAL_CONFIG.keepArchives,
+    };
+}
+/**
+ * Group events by WU ID for atomic archival.
+ *
+ * @param events - Array of WU events
+ * @returns Map of WU ID to events array
+ */
+function groupEventsByWuId(events) {
+    const grouped = new Map();
+    for (const event of events) {
+        const existing = grouped.get(event.wuId) ?? [];
+        existing.push(event);
+        grouped.set(event.wuId, existing);
+    }
+    return grouped;
+}
+/**
+ * Get the most recent event timestamp for a WU.
+ *
+ * @param events - Events for a single WU
+ * @returns Most recent timestamp
+ */
+function getMostRecentTimestamp(events) {
+    let mostRecent = events[0].timestamp;
+    for (const event of events) {
+        if (new Date(event.timestamp) > new Date(mostRecent)) {
+            mostRecent = event.timestamp;
+        }
+    }
+    return mostRecent;
+}
+/**
+ * Group events by archive file path (monthly buckets).
+ *
+ * @param events - Events to group
+ * @returns Map of archive file path to events
+ */
+function groupEventsByArchivePath(events) {
+    const grouped = new Map();
+    for (const event of events) {
+        const archivePath = getArchiveFilePath(event.timestamp);
+        const existing = grouped.get(archivePath) ?? [];
+        existing.push(event);
+        grouped.set(archivePath, existing);
+    }
+    return grouped;
+}
+/**
+ * Calculate byte size of events when serialized.
+ *
+ * @param events - Events to measure
+ * @returns Approximate byte size
+ */
+function estimateEventsBytes(events) {
+    return events.reduce((total, event) => total + JSON.stringify(event).length + 1, 0);
+}
+/**
+ * Write retained events back to wu-events.jsonl.
+ *
+ * Uses atomic write pattern: temp file + fsync + rename.
+ *
+ * @param baseDir - Project base directory
+ * @param events - Events to write
+ */
+async function writeRetainedEvents(baseDir, events) {
+    const eventsPath = path.join(baseDir, LUMENFLOW_PATHS.STATE_DIR, WU_EVENTS_FILE_NAME);
+    const tempPath = `${eventsPath}.tmp.${process.pid}`;
+    const content = events.map((e) => JSON.stringify(e)).join('\n') + (events.length > 0 ? '\n' : '');
+    try {
+        const fd = openSync(tempPath, 'w');
+        writeFileSync(fd, content, 'utf-8');
+        fsyncSync(fd);
+        closeSync(fd);
+        // Atomic rename
+        renameSync(tempPath, eventsPath);
+        // Fsync directory
+        const dirPath = path.dirname(eventsPath);
+        const dirFd = openSync(dirPath, 'r');
+        fsyncSync(dirFd);
+        closeSync(dirFd);
+    }
+    catch (error) {
+        // Cleanup temp file on failure
+        try {
+            unlinkSync(tempPath);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        throw error;
+    }
+}
+/**
+ * Append events to archive file.
+ *
+ * Creates archive directory and file if they don't exist.
+ * Appends to existing archive file for monthly rollup.
+ *
+ * @param baseDir - Project base directory
+ * @param archivePath - Relative path to archive file
+ * @param events - Events to append
+ */
+async function appendToArchive(baseDir, archivePath, events) {
+    const fullPath = path.join(baseDir, archivePath);
+    const dirPath = path.dirname(fullPath);
+    // Ensure archive directory exists
+    mkdirSync(dirPath, { recursive: true });
+    const content = events.map((e) => JSON.stringify(e)).join('\n') + '\n';
+    // Append to archive file (creates if doesn't exist)
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool writes known path
+    await fs.appendFile(fullPath, content, 'utf-8');
+}
+/**
+ * Archive old WU events to monthly archive files.
+ *
+ * Moves completed WU events older than threshold to archive files.
+ * Events are grouped by WU ID so all events for a WU are archived together.
+ * Active WU events (in_progress/blocked/waiting) are never archived.
+ *
+ * @param baseDir - Project base directory
+ * @param options - Archive options
+ * @returns Archive result with statistics
+ *
+ * @example
+ * // Preview archival
+ * const preview = await archiveWuEvents(baseDir, { dryRun: true });
+ * console.log(`Would archive ${preview.archivedWuIds.length} WUs`);
+ *
+ * @example
+ * // Archive with custom threshold
+ * const result = await archiveWuEvents(baseDir, { archiveAfter: '30d' });
+ */
+export async function archiveWuEvents(baseDir, options = {}) {
+    const { dryRun = false, now = Date.now(), getActiveWuIds = getActiveWuIdsFromStore } = options;
+    const config = buildArchivalConfig(options);
+    const events = await loadAllEvents(baseDir);
+    const activeWuIds = await getActiveWuIds(baseDir);
+    // Group events by WU ID for atomic archival decisions
+    const eventsByWu = groupEventsByWuId(events);
+    // Determine which WUs to archive
+    const archivedWuIds = [];
+    const retainedWuIds = [];
+    const eventsToArchive = [];
+    const eventsToRetain = [];
+    const breakdown = {
+        archivedOlderThanThreshold: 0,
+        retainedActiveWu: 0,
+        retainedWithinThreshold: 0,
+    };
+    for (const [wuId, wuEvents] of eventsByWu) {
+        // Check if WU is active - if so, retain all events
+        if (activeWuIds.has(wuId)) {
+            retainedWuIds.push(wuId);
+            eventsToRetain.push(...wuEvents);
+            breakdown.retainedActiveWu++;
+            continue;
+        }
+        // Check age based on most recent event
+        const mostRecentTimestamp = getMostRecentTimestamp(wuEvents);
+        const decision = shouldArchiveEvent({ wuId, timestamp: mostRecentTimestamp }, config, { now, activeWuIds });
+        if (decision.archive) {
+            archivedWuIds.push(wuId);
+            eventsToArchive.push(...wuEvents);
+            breakdown.archivedOlderThanThreshold++;
+        }
+        else {
+            retainedWuIds.push(wuId);
+            eventsToRetain.push(...wuEvents);
+            breakdown.retainedWithinThreshold++;
+        }
+    }
+    const bytesArchived = estimateEventsBytes(eventsToArchive);
+    const baseResult = {
+        success: true,
+        archivedWuIds,
+        retainedWuIds,
+        archivedEventCount: eventsToArchive.length,
+        retainedEventCount: eventsToRetain.length,
+        bytesArchived,
+        breakdown,
+    };
+    if (dryRun) {
+        return { ...baseResult, dryRun: true };
+    }
+    // Actually archive events
+    if (eventsToArchive.length > 0) {
+        // Group by archive file path (monthly)
+        const archiveGroups = groupEventsByArchivePath(eventsToArchive);
+        // Write to archive files
+        for (const [archivePath, archiveEvents] of archiveGroups) {
+            await appendToArchive(baseDir, archivePath, archiveEvents);
+        }
+        // Write retained events back to main file
+        await writeRetainedEvents(baseDir, eventsToRetain);
+    }
+    return baseResult;
+}

package/dist/wu-helpers.d.ts

@@ -10,8 +10,8 @@
 /**
  * Validate WU ID format
  *
- * WU-1593: Extracted from duplicate implementations in wu-create.mjs and wu-edit.mjs (DRY).
- * Uses centralized PATTERNS.WU_ID regex from wu-constants.mjs.
+ * WU-1593: Extracted from duplicate implementations in wu-create.ts and wu-edit.ts (DRY).
+ * Uses centralized PATTERNS.WU_ID regex from wu-constants.ts.
  *
  * @param {string} id - WU ID to validate (e.g., 'WU-123')
  * @throws {Error} If ID format is invalid

package/dist/wu-helpers.js

@@ -17,8 +17,8 @@ import { isAgentBranchWithDetails } from './branch-check.js';
 /**
  * Validate WU ID format
  *
- * WU-1593: Extracted from duplicate implementations in wu-create.mjs and wu-edit.mjs (DRY).
- * Uses centralized PATTERNS.WU_ID regex from wu-constants.mjs.
+ * WU-1593: Extracted from duplicate implementations in wu-create.ts and wu-edit.ts (DRY).
+ * Uses centralized PATTERNS.WU_ID regex from wu-constants.ts.
  *
  * @param {string} id - WU ID to validate (e.g., 'WU-123')
  * @throws {Error} If ID format is invalid

package/dist/wu-id-generator.d.ts

@@ -0,0 +1,58 @@
+/**
+ * WU ID Generator (WU-1246)
+ *
+ * Auto-generates sequential WU IDs by scanning existing WU YAML files.
+ * Provides race-condition handling via retry mechanism.
+ *
+ * @module wu-id-generator
+ */
+/** WU ID prefix constant */
+export declare const WU_ID_PREFIX = "WU-";
+/**
+ * Parse the numeric part from a WU ID string.
+ *
+ * Supports formats:
+ * - WU-123 (direct ID)
+ * - WU-123.yaml (filename)
+ *
+ * @param wuIdOrFilename - WU ID or filename to parse
+ * @returns Numeric ID or null if invalid format
+ */
+export declare function parseWuIdNumber(wuIdOrFilename: string): number | null;
+/**
+ * Get the highest WU ID number from the WU directory.
+ *
+ * Scans all WU-*.yaml files and returns the highest numeric ID found.
+ * Returns 0 if directory doesn't exist or contains no valid WU files.
+ *
+ * @returns Highest WU ID number or 0 if none found
+ */
+export declare function getHighestWuId(): number;
+/**
+ * Get the next available WU ID.
+ *
+ * Returns the next sequential ID after the highest existing WU.
+ * Does not fill gaps - always returns highest + 1.
+ *
+ * @returns Next WU ID in format "WU-{number}"
+ */
+export declare function getNextWuId(): string;
+/** Options for generateWuIdWithRetry */
+interface GenerateOptions {
+    /** Maximum number of retry attempts (default: 5) */
+    maxRetries?: number;
+}
+/**
+ * Generate a unique WU ID with retry handling for race conditions.
+ *
+ * This function handles concurrent wu:create calls by:
+ * 1. Generating the next sequential ID
+ * 2. Checking if the file already exists (race condition detection)
+ * 3. Retrying with exponential backoff if conflict detected
+ *
+ * @param options - Generation options
+ * @returns Promise resolving to unique WU ID
+ * @throws Error if max retries exceeded
+ */
+export declare function generateWuIdWithRetry(options?: GenerateOptions): Promise<string>;
+export {};

package/dist/wu-id-generator.js

@@ -0,0 +1,103 @@
+/**
+ * WU ID Generator (WU-1246)
+ *
+ * Auto-generates sequential WU IDs by scanning existing WU YAML files.
+ * Provides race-condition handling via retry mechanism.
+ *
+ * @module wu-id-generator
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { WU_PATHS } from './wu-paths.js';
+/** WU ID prefix constant */
+export const WU_ID_PREFIX = 'WU-';
+/** Default maximum retry attempts for race condition handling */
+const DEFAULT_MAX_RETRIES = 5;
+/** Retry delay in milliseconds (exponential backoff base) */
+const RETRY_DELAY_BASE_MS = 50;
+/**
+ * Parse the numeric part from a WU ID string.
+ *
+ * Supports formats:
+ * - WU-123 (direct ID)
+ * - WU-123.yaml (filename)
+ *
+ * @param wuIdOrFilename - WU ID or filename to parse
+ * @returns Numeric ID or null if invalid format
+ */
+export function parseWuIdNumber(wuIdOrFilename) {
+    if (!wuIdOrFilename || typeof wuIdOrFilename !== 'string') {
+        return null;
+    }
+    // Remove .yaml extension if present
+    const wuId = wuIdOrFilename.replace(/\.yaml$/, '');
+    // Match WU-{number} pattern using RegExp method per sonarjs/prefer-regexp-exec
+    const WU_ID_PATTERN = /^WU-(\d+)$/;
+    const regexResult = WU_ID_PATTERN.exec(wuId);
+    if (!regexResult) {
+        return null;
+    }
+    const num = parseInt(regexResult[1], 10);
+    return isNaN(num) ? null : num;
+}
+/**
+ * Get the highest WU ID number from the WU directory.
+ *
+ * Scans all WU-*.yaml files and returns the highest numeric ID found.
+ * Returns 0 if directory doesn't exist or contains no valid WU files.
+ *
+ * @returns Highest WU ID number or 0 if none found
+ */
+export function getHighestWuId() {
+    const wuDir = WU_PATHS.WU_DIR();
+    if (!existsSync(wuDir)) {
+        return 0;
+    }
+    const files = readdirSync(wuDir);
+    let highest = 0;
+    for (const file of files) {
+        const num = parseWuIdNumber(file);
+        if (num !== null && num > highest) {
+            highest = num;
+        }
+    }
+    return highest;
+}
+/**
+ * Get the next available WU ID.
+ *
+ * Returns the next sequential ID after the highest existing WU.
+ * Does not fill gaps - always returns highest + 1.
+ *
+ * @returns Next WU ID in format "WU-{number}"
+ */
+export function getNextWuId() {
+    const highest = getHighestWuId();
+    return `${WU_ID_PREFIX}${highest + 1}`;
+}
+/**
+ * Generate a unique WU ID with retry handling for race conditions.
+ *
+ * This function handles concurrent wu:create calls by:
+ * 1. Generating the next sequential ID
+ * 2. Checking if the file already exists (race condition detection)
+ * 3. Retrying with exponential backoff if conflict detected
+ *
+ * @param options - Generation options
+ * @returns Promise resolving to unique WU ID
+ * @throws Error if max retries exceeded
+ */
+export async function generateWuIdWithRetry(options = {}) {
+    const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        const nextId = getNextWuId();
+        const wuPath = WU_PATHS.WU(nextId);
+        // Check if file already exists (race condition)
+        if (!existsSync(wuPath)) {
+            return nextId;
+        }
+        // Exponential backoff before retry
+        const delay = RETRY_DELAY_BASE_MS * Math.pow(2, attempt);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+    throw new Error(`Failed to generate unique WU ID after ${maxRetries} attempts`);
+}

package/dist/wu-lint.js

@@ -22,7 +22,7 @@ export const WU_LINT_ERROR_TYPES = {
 };
 /**
  * Regex to detect file paths in acceptance criteria text
- * Matches patterns like: apps/web/src/file.ts, tools/lib/helper.mjs
+ * Matches patterns like: apps/web/src/file.ts, tools/lib/helper.ts
  * Uses explicit character sets to avoid regex backtracking issues
  */
 const FILE_PATH_PATTERN = /(?:^|[\s'"`])([a-zA-Z0-9_-]+\/[a-zA-Z0-9_./-]+\.[a-zA-Z0-9]+)/g;

package/dist/wu-preflight-validators.d.ts

@@ -34,18 +34,21 @@
  * @param {string[]} [params.errors=[]] - Error messages
  * @param {string[]} [params.missingCodePaths=[]] - Missing code paths
  * @param {string[]} [params.missingTestPaths=[]] - Missing test paths
+ * @param {Record<string, string[]>} [params.suggestedTestPaths={}] - Suggested test paths
  * @returns {PreflightResult}
  */
-export declare function createPreflightResult({ valid, errors, missingCodePaths, missingTestPaths, }: {
+export declare function createPreflightResult({ valid, errors, missingCodePaths, missingTestPaths, suggestedTestPaths, }: {
     valid: any;
     errors?: any[];
     missingCodePaths?: any[];
     missingTestPaths?: any[];
+    suggestedTestPaths?: {};
 }): {
     valid: any;
     errors: any[];
     missingCodePaths: any[];
     missingTestPaths: any[];
+    suggestedTestPaths: {};
 };
 /**
  * Run preflight validation for a WU
@@ -74,6 +77,7 @@ export declare function validatePreflight(id: any, options?: ValidatePreflightOp
     errors: any[];
     missingCodePaths: any[];
     missingTestPaths: any[];
+    suggestedTestPaths: {};
 }>;
 /**
  * Format preflight result as user-friendly message
@@ -84,3 +88,11 @@ export declare function validatePreflight(id: any, options?: ValidatePreflightOp
  */
 export declare function formatPreflightResult(id: any, result: any): string;
 export declare const PreflightResult: {};
+/**
+ * Find suggested paths for missing test files
+ *
+ * @param {string[]} missingPaths - List of missing test paths
+ * @param {string} rootDir - Root directory to search in
+ * @returns {Promise<Record<string, string[]>>} Map of missing path -> suggestions
+ */
+export declare function findSuggestedTestPaths(missingPaths: any, rootDir: any): Promise<{}>;