@lumenflow/core 3.2.0 → 3.2.1

package/dist/stamp-utils.js

@@ -0,0 +1,245 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Stamp File Utilities
+ *
+ * Centralized stamp file operations (create, validate)
+ * Eliminates magic string for stamp body template
+ *
+ * WU-2242: Added format validation for corrupted stamp detection
+ *
+ * Stamp files (.lumenflow/stamps/WU-{id}.done) serve as completion markers
+ * Used by wu:done, wu:recovery, and validation tools
+ */
+import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
+import { readFile, access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import { parse, isValid } from 'date-fns';
+import { WU_PATHS } from './wu-paths.js';
+import { todayISO } from './date-utils.js';
+/**
+ * Stamp format error types (WU-2242)
+ * @readonly
+ * @enum {string}
+ */
+export const STAMP_FORMAT_ERRORS = Object.freeze({
+    /** Stamp file is empty or contains only whitespace */
+    EMPTY_FILE: 'EMPTY_FILE',
+    /** Missing WU identifier line (format: WU WU-123 (em dash) Title) */
+    MISSING_WU_LINE: 'MISSING_WU_LINE',
+    /** Missing Completed: YYYY-MM-DD line */
+    MISSING_COMPLETED_LINE: 'MISSING_COMPLETED_LINE',
+    /** Date is not in valid YYYY-MM-DD format or is invalid */
+    INVALID_DATE_FORMAT: 'INVALID_DATE_FORMAT',
+    /** WU ID in stamp does not match expected ID */
+    WU_ID_MISMATCH: 'WU_ID_MISMATCH',
+});
+/**
+ * Valid date regex: YYYY-MM-DD format (for format checking before parsing)
+ * @type {RegExp}
+ */
+const DATE_FORMAT_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * Validate that a date string is a valid ISO date (YYYY-MM-DD)
+ *
+ * WU-1006: Uses date-fns parse() and isValid() instead of manual parseInt parsing
+ * Library-First principle: leverage well-known libraries over brittle custom code
+ *
+ * @param {string} dateStr - Date string in YYYY-MM-DD format
+ * @returns {boolean} True if date is valid
+ */
+export function isValidDateString(dateStr) {
+    // Quick format check - must be YYYY-MM-DD pattern
+    if (!dateStr || !DATE_FORMAT_PATTERN.test(dateStr)) {
+        return false;
+    }
+    // Parse with date-fns and validate the result
+    // parse() with strict format ensures proper date validation
+    const parsed = parse(dateStr, 'yyyy-MM-dd', new Date());
+    return isValid(parsed);
+}
+// Internal alias for backward compatibility
+const isValidDate = isValidDateString;
+/**
+ * Stamp file body template (eliminates magic string)
+ * Single source of truth for stamp format
+ */
+const STAMP_TEMPLATE = (id, title, timestamp) => `WU ${id} — ${title}\nCompleted: ${timestamp}\n`;
+/**
+ * Create stamp file (idempotent - safe to call multiple times)
+ *
+ * @param {object} params - Parameters
+ * @param {string} params.id - WU ID (e.g., 'WU-123')
+ * @param {string} params.title - WU title
+ * @returns {object} Result { created: boolean, path: string, reason?: string }
+ */
+export function createStamp({ id, title }) {
+    const stampsDir = WU_PATHS.STAMPS_DIR();
+    const stampPath = WU_PATHS.STAMP(id);
+    // Ensure stamps directory exists
+    if (!existsSync(stampsDir)) {
+        mkdirSync(stampsDir, { recursive: true });
+    }
+    // Idempotent: skip if stamp already exists
+    if (existsSync(stampPath)) {
+        return { created: false, path: stampPath, reason: 'already_exists' };
+    }
+    // Create stamp file
+    const body = STAMP_TEMPLATE(id, title, todayISO());
+    writeFileSync(stampPath, body, { encoding: 'utf-8' });
+    return { created: true, path: stampPath };
+}
+/**
+ * Validate stamp exists
+ *
+ * @param {string} stampPath - Path to stamp file
+ * @returns {boolean} True if stamp exists
+ */
+export function validateStamp(stampPath) {
+    return existsSync(stampPath);
+}
+/**
+ * Get stamp path using WU_PATHS (consistent with codebase)
+ *
+ * @param {string} id - WU ID
+ * @returns {string} Absolute path to stamp file
+ */
+export function getStampPath(id) {
+    return WU_PATHS.STAMP(id);
+}
+/**
+ * Validate WU line in stamp content
+ * Checks for format: "WU WU-123 (em dash) Title"
+ * @param {string[]} lines - Stamp file lines
+ * @param {string} expectedWuId - Expected WU ID
+ * @returns {string|null} Error type or null if valid
+ */
+function validateWuLine(lines, expectedWuId) {
+    const wuLine = lines.find((line) => line.startsWith('WU '));
+    if (!wuLine) {
+        return STAMP_FORMAT_ERRORS.MISSING_WU_LINE;
+    }
+    const wuIdMatch = wuLine.match(/^WU (WU-\d+)/);
+    if (!wuIdMatch) {
+        return STAMP_FORMAT_ERRORS.MISSING_WU_LINE;
+    }
+    const wuId = wuIdMatch[1];
+    if (!wuId) {
+        return STAMP_FORMAT_ERRORS.MISSING_WU_LINE;
+    }
+    if (wuId !== expectedWuId) {
+        return STAMP_FORMAT_ERRORS.WU_ID_MISMATCH;
+    }
+    return null;
+}
+/**
+ * Validate Completed line in stamp content
+ * @param {string[]} lines - Stamp file lines
+ * @returns {string|null} Error type or null if valid
+ */
+function validateCompletedLine(lines) {
+    const completedLine = lines.find((line) => line.startsWith('Completed:'));
+    if (!completedLine) {
+        return STAMP_FORMAT_ERRORS.MISSING_COMPLETED_LINE;
+    }
+    const dateMatch = completedLine.match(/^Completed:\s*(.+)/);
+    if (!dateMatch) {
+        return STAMP_FORMAT_ERRORS.MISSING_COMPLETED_LINE;
+    }
+    const dateStr = dateMatch[1]?.trim();
+    if (!dateStr) {
+        return STAMP_FORMAT_ERRORS.MISSING_COMPLETED_LINE;
+    }
+    if (!isValidDate(dateStr)) {
+        return STAMP_FORMAT_ERRORS.INVALID_DATE_FORMAT;
+    }
+    return null;
+}
+/**
+ * Validate stamp file format (WU-2242)
+ *
+ * Expected format:
+ * ```
+ * WU WU-123 (em dash) Title here
+ * Completed: 2025-12-31
+ * ```
+ *
+ * @param {string} wuId - WU ID (e.g., 'WU-123')
+ * @param {string} [projectRoot=process.cwd()] - Project root directory
+ * @returns {Promise<{valid: boolean, errors: string[], missing?: boolean}>}
+ */
+export async function validateStampFormat(wuId, projectRoot = process.cwd()) {
+    const stampPath = path.join(projectRoot, WU_PATHS.STAMP(wuId));
+    // Check if stamp file exists
+    try {
+        await access(stampPath, constants.R_OK);
+    }
+    catch {
+        return { valid: false, errors: [], missing: true };
+    }
+    // Read stamp content
+    let content;
+    try {
+        content = await readFile(stampPath, { encoding: 'utf-8' });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { valid: false, errors: [`Failed to read stamp: ${message}`] };
+    }
+    // Check for empty file
+    if (content.trim() === '') {
+        return { valid: false, errors: [STAMP_FORMAT_ERRORS.EMPTY_FILE] };
+    }
+    const lines = content.split('\n');
+    const errors = [];
+    // Validate WU line
+    const wuLineError = validateWuLine(lines, wuId);
+    if (wuLineError) {
+        errors.push(wuLineError);
+    }
+    // Validate Completed line
+    const completedError = validateCompletedLine(lines);
+    if (completedError) {
+        errors.push(completedError);
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Parse stamp content to extract metadata
+ *
+ * @param {string} content - Stamp file content
+ * @returns {StampMetadata}
+ */
+export function parseStampContent(content) {
+    const result = {};
+    const lines = content.split('\n');
+    // Parse WU line
+    const wuLine = lines.find((line) => line.startsWith('WU '));
+    if (wuLine) {
+        const match = wuLine.match(/^WU (WU-\d+)\s*[—-]\s*(.+)/);
+        if (match) {
+            const wuId = match[1];
+            const title = match[2];
+            if (wuId) {
+                result.wuId = wuId;
+            }
+            if (title) {
+                result.title = title.trim();
+            }
+        }
+    }
+    // Parse Completed line
+    const completedLine = lines.find((line) => line.startsWith('Completed:'));
+    if (completedLine) {
+        const match = completedLine.match(/^Completed:\s*(.+)/);
+        if (match) {
+            const completedDate = match[1];
+            if (completedDate) {
+                result.completedDate = completedDate.trim();
+            }
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=stamp-utils.js.map

package/dist/stamp-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stamp-utils.js","sourceRoot":"","sources":["../src/stamp-utils.ts"],"names":[],"mappings":"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"}

package/dist/state-cleanup-core.d.ts

@@ -0,0 +1,206 @@
+/**
+ * State Cleanup Core (WU-1208)
+ *
+ * Unified orchestration of all state cleanup operations:
+ * - Signal cleanup (TTL-based, from @lumenflow/memory)
+ * - Memory cleanup (lifecycle-based, from @lumenflow/memory)
+ * - Event archival (age-based, from @lumenflow/core)
+ *
+ * Cleanup order: signals -> memory -> events (dependency order)
+ *
+ * Design principles:
+ * - Non-fatal errors: failures in one cleanup type don't block others
+ * - Consistent summary: aggregated counts for all cleanup types
+ * - Configurable: supports --dry-run and type-specific flags
+ *
+ * @see {@link packages/@lumenflow/cli/src/state-cleanup.ts} - CLI wrapper
+ * @see {@link packages/@lumenflow/core/src/__tests__/state-cleanup-core.test.ts} - Tests
+ */
+/**
+ * Cleanup types supported by state:cleanup
+ */
+export type CleanupType = 'signals' | 'memory' | 'events';
+/**
+ * Signal cleanup result (from @lumenflow/memory/signal-cleanup-core)
+ */
+export interface SignalCleanupResult {
+    success: boolean;
+    removedIds: string[];
+    retainedIds: string[];
+    bytesFreed: number;
+    compactionRatio: number;
+    dryRun?: boolean;
+    breakdown: {
+        ttlExpired: number;
+        unreadTtlExpired: number;
+        countLimitExceeded: number;
+        activeWuProtected: number;
+    };
+}
+/**
+ * Memory cleanup result (from @lumenflow/memory/mem-cleanup-core)
+ */
+export interface MemoryCleanupResult {
+    success: boolean;
+    removedIds: string[];
+    retainedIds: string[];
+    bytesFreed: number;
+    compactionRatio: number;
+    dryRun?: boolean;
+    breakdown: {
+        ephemeral: number;
+        session: number;
+        wu: number;
+        sensitive: number;
+        ttlExpired: number;
+        activeSessionProtected: number;
+    };
+}
+/**
+ * Event archival result (from @lumenflow/core/wu-events-cleanup)
+ */
+export interface EventArchivalResult {
+    success: boolean;
+    archivedWuIds: string[];
+    retainedWuIds: string[];
+    archivedEventCount: number;
+    retainedEventCount: number;
+    bytesArchived: number;
+    dryRun?: boolean;
+    breakdown: {
+        archivedOlderThanThreshold: number;
+        retainedActiveWu: number;
+        retainedWithinThreshold: number;
+    };
+}
+/**
+ * Signal cleanup function type
+ */
+export type CleanupSignalsFn = (baseDir: string, options: {
+    dryRun?: boolean;
+}) => Promise<SignalCleanupResult>;
+/**
+ * Memory cleanup function type
+ */
+export type CleanupMemoryFn = (baseDir: string, options: {
+    dryRun?: boolean;
+}) => Promise<MemoryCleanupResult>;
+/**
+ * Event archival function type
+ */
+export type ArchiveEventsFn = (baseDir: string, options: {
+    dryRun?: boolean;
+}) => Promise<EventArchivalResult>;
+/**
+ * Error that occurred during a specific cleanup type
+ */
+export interface CleanupError {
+    type: CleanupType;
+    message: string;
+    error?: Error;
+}
+/**
+ * Summary of signal cleanup
+ */
+export interface SignalCleanupSummary {
+    removedCount: number;
+    retainedCount: number;
+    bytesFreed: number;
+    breakdown: SignalCleanupResult['breakdown'];
+}
+/**
+ * Summary of memory cleanup
+ */
+export interface MemoryCleanupSummary {
+    removedCount: number;
+    retainedCount: number;
+    bytesFreed: number;
+    breakdown: MemoryCleanupResult['breakdown'];
+}
+/**
+ * Summary of event archival
+ */
+export interface EventArchivalSummary {
+    archivedWuCount: number;
+    retainedWuCount: number;
+    archivedEventCount: number;
+    retainedEventCount: number;
+    bytesArchived: number;
+    breakdown: EventArchivalResult['breakdown'];
+}
+/**
+ * Overall summary of state cleanup
+ */
+export interface StateCleanupSummary {
+    totalBytesFreed: number;
+    typesExecuted: CleanupType[];
+    typesSkipped: CleanupType[];
+}
+/**
+ * Options for unified state cleanup
+ */
+export interface StateCleanupOptions {
+    /** If true, preview without modifications */
+    dryRun?: boolean;
+    /** Only execute signal cleanup */
+    signalsOnly?: boolean;
+    /** Only execute memory cleanup */
+    memoryOnly?: boolean;
+    /** Only execute event archival */
+    eventsOnly?: boolean;
+    /** Signal cleanup function (injectable for testing) */
+    cleanupSignals?: CleanupSignalsFn;
+    /** Memory cleanup function (injectable for testing) */
+    cleanupMemory?: CleanupMemoryFn;
+    /** Event archival function (injectable for testing) */
+    archiveEvents?: ArchiveEventsFn;
+}
+/**
+ * Result of unified state cleanup
+ */
+export interface StateCleanupResult {
+    /** Whether all executed cleanups succeeded */
+    success: boolean;
+    /** True if in dry-run mode */
+    dryRun?: boolean;
+    /** Signal cleanup summary (undefined if skipped) */
+    signals?: SignalCleanupSummary;
+    /** Memory cleanup summary (undefined if skipped) */
+    memory?: MemoryCleanupSummary;
+    /** Event archival summary (undefined if skipped) */
+    events?: EventArchivalSummary;
+    /** Errors from failed cleanups (non-fatal) */
+    errors: CleanupError[];
+    /** Aggregated summary */
+    summary: StateCleanupSummary;
+}
+/**
+ * Orchestrate all state cleanup operations in dependency order.
+ *
+ * Executes cleanups in order: signals -> memory -> events
+ *
+ * Non-fatal: failures in one cleanup type don't block others.
+ * All errors are collected and reported in the result.
+ *
+ * @param baseDir - Project base directory
+ * @param options - State cleanup options
+ * @returns Unified cleanup result with summaries and errors
+ *
+ * @example
+ * // Full cleanup with dry-run
+ * const result = await cleanupState(baseDir, { dryRun: true });
+ *
+ * @example
+ * // Signals only
+ * const result = await cleanupState(baseDir, { signalsOnly: true });
+ *
+ * @example
+ * // With injected cleanup functions (for testing or custom implementations)
+ * const result = await cleanupState(baseDir, {
+ *   cleanupSignals: myCustomSignalCleanup,
+ *   cleanupMemory: myCustomMemoryCleanup,
+ *   archiveEvents: myCustomEventArchival,
+ * });
+ */
+export declare function cleanupState(baseDir: string, options?: StateCleanupOptions): Promise<StateCleanupResult>;
+//# sourceMappingURL=state-cleanup-core.d.ts.map

package/dist/state-cleanup-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-cleanup-core.d.ts","sourceRoot":"","sources":["../src/state-cleanup-core.ts"],"names":[],"mappings":"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"}

package/dist/state-cleanup-core.js

@@ -0,0 +1,225 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * All cleanup types in dependency order
+ */
+const ALL_CLEANUP_TYPES = ['signals', 'memory', 'events'];
+/**
+ * Determine which cleanup types to execute based on options
+ *
+ * @param options - State cleanup options
+ * @returns Array of cleanup types to execute
+ */
+function getTypesToExecute(options) {
+    if (options.signalsOnly) {
+        return ['signals'];
+    }
+    if (options.memoryOnly) {
+        return ['memory'];
+    }
+    if (options.eventsOnly) {
+        return ['events'];
+    }
+    return ALL_CLEANUP_TYPES;
+}
+/**
+ * Execute signal cleanup and capture results or errors
+ *
+ * @param baseDir - Project base directory
+ * @param options - Cleanup options
+ * @returns Signal cleanup summary or undefined on error
+ */
+async function executeSignalCleanup(baseDir, options) {
+    if (!options.cleanupSignals) {
+        return { error: { type: 'signals', message: 'No cleanupSignals function provided' } };
+    }
+    try {
+        const result = await options.cleanupSignals(baseDir, { dryRun: options.dryRun });
+        return {
+            summary: {
+                removedCount: result.removedIds.length,
+                retainedCount: result.retainedIds.length,
+                bytesFreed: result.bytesFreed,
+                breakdown: result.breakdown,
+            },
+        };
+    }
+    catch (err) {
+        const error = err;
+        return {
+            error: {
+                type: 'signals',
+                message: error.message,
+                error,
+            },
+        };
+    }
+}
+/**
+ * Execute memory cleanup and capture results or errors
+ *
+ * @param baseDir - Project base directory
+ * @param options - Cleanup options
+ * @returns Memory cleanup summary or undefined on error
+ */
+async function executeMemoryCleanup(baseDir, options) {
+    if (!options.cleanupMemory) {
+        return { error: { type: 'memory', message: 'No cleanupMemory function provided' } };
+    }
+    try {
+        const result = await options.cleanupMemory(baseDir, { dryRun: options.dryRun });
+        return {
+            summary: {
+                removedCount: result.removedIds.length,
+                retainedCount: result.retainedIds.length,
+                bytesFreed: result.bytesFreed,
+                breakdown: result.breakdown,
+            },
+        };
+    }
+    catch (err) {
+        const error = err;
+        return {
+            error: {
+                type: 'memory',
+                message: error.message,
+                error,
+            },
+        };
+    }
+}
+/**
+ * Execute event archival and capture results or errors
+ *
+ * @param baseDir - Project base directory
+ * @param options - Cleanup options
+ * @returns Event archival summary or undefined on error
+ */
+async function executeEventArchival(baseDir, options) {
+    if (!options.archiveEvents) {
+        return { error: { type: 'events', message: 'No archiveEvents function provided' } };
+    }
+    try {
+        const result = await options.archiveEvents(baseDir, { dryRun: options.dryRun });
+        return {
+            summary: {
+                archivedWuCount: result.archivedWuIds.length,
+                retainedWuCount: result.retainedWuIds.length,
+                archivedEventCount: result.archivedEventCount,
+                retainedEventCount: result.retainedEventCount,
+                bytesArchived: result.bytesArchived,
+                breakdown: result.breakdown,
+            },
+        };
+    }
+    catch (err) {
+        const error = err;
+        return {
+            error: {
+                type: 'events',
+                message: error.message,
+                error,
+            },
+        };
+    }
+}
+/**
+ * Calculate total bytes freed from all cleanup summaries
+ *
+ * @param signals - Signal cleanup summary
+ * @param memory - Memory cleanup summary
+ * @param events - Event archival summary
+ * @returns Total bytes freed
+ */
+function calculateTotalBytesFreed(signals, memory, events) {
+    let total = 0;
+    if (signals) {
+        total += signals.bytesFreed;
+    }
+    if (memory) {
+        total += memory.bytesFreed;
+    }
+    if (events) {
+        total += events.bytesArchived;
+    }
+    return total;
+}
+/**
+ * Orchestrate all state cleanup operations in dependency order.
+ *
+ * Executes cleanups in order: signals -> memory -> events
+ *
+ * Non-fatal: failures in one cleanup type don't block others.
+ * All errors are collected and reported in the result.
+ *
+ * @param baseDir - Project base directory
+ * @param options - State cleanup options
+ * @returns Unified cleanup result with summaries and errors
+ *
+ * @example
+ * // Full cleanup with dry-run
+ * const result = await cleanupState(baseDir, { dryRun: true });
+ *
+ * @example
+ * // Signals only
+ * const result = await cleanupState(baseDir, { signalsOnly: true });
+ *
+ * @example
+ * // With injected cleanup functions (for testing or custom implementations)
+ * const result = await cleanupState(baseDir, {
+ *   cleanupSignals: myCustomSignalCleanup,
+ *   cleanupMemory: myCustomMemoryCleanup,
+ *   archiveEvents: myCustomEventArchival,
+ * });
+ */
+export async function cleanupState(baseDir, options = {}) {
+    const typesToExecute = getTypesToExecute(options);
+    const typesSkipped = ALL_CLEANUP_TYPES.filter((t) => !typesToExecute.includes(t));
+    const errors = [];
+    let signalsSummary;
+    let memorySummary;
+    let eventsSummary;
+    // Execute cleanups in dependency order: signals -> memory -> events
+    if (typesToExecute.includes('signals')) {
+        const result = await executeSignalCleanup(baseDir, options);
+        if (result.error) {
+            errors.push(result.error);
+        }
+        else {
+            signalsSummary = result.summary;
+        }
+    }
+    if (typesToExecute.includes('memory')) {
+        const result = await executeMemoryCleanup(baseDir, options);
+        if (result.error) {
+            errors.push(result.error);
+        }
+        else {
+            memorySummary = result.summary;
+        }
+    }
+    if (typesToExecute.includes('events')) {
+        const result = await executeEventArchival(baseDir, options);
+        if (result.error) {
+            errors.push(result.error);
+        }
+        else {
+            eventsSummary = result.summary;
+        }
+    }
+    const totalBytesFreed = calculateTotalBytesFreed(signalsSummary, memorySummary, eventsSummary);
+    return {
+        success: errors.length === 0,
+        dryRun: options.dryRun,
+        signals: signalsSummary,
+        memory: memorySummary,
+        events: eventsSummary,
+        errors,
+        summary: {
+            totalBytesFreed,
+            typesExecuted: typesToExecute,
+            typesSkipped,
+        },
+    };
+}
+//# sourceMappingURL=state-cleanup-core.js.map