@lumenflow/core 2.2.2 → 2.3.2

package/dist/state-cleanup-core.js

@@ -0,0 +1,240 @@
+/**
+ * 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
+ */
+/**
+ * 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,
+        },
+    };
+}

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

@@ -0,0 +1,168 @@
+/**
+ * State Doctor Core (WU-1209)
+ *
+ * Integrity checker for LumenFlow state that detects:
+ * - Orphaned WUs (done status but no stamp)
+ * - Dangling signals (reference non-existent WUs)
+ * - Broken memory relationships (events for missing WU specs)
+ *
+ * Inspired by Beads bd doctor command.
+ *
+ * Design principles:
+ * - Non-destructive by default (read-only diagnosis)
+ * - --fix flag for safe auto-repair of resolvable issues
+ * - Dependency injection for testability
+ * - Human-readable output with actionable suggestions
+ *
+ * @see {@link packages/@lumenflow/cli/src/state-doctor.ts} - CLI wrapper
+ * @see {@link packages/@lumenflow/core/src/__tests__/state-doctor-core.test.ts} - Tests
+ */
+/**
+ * Issue type constants
+ */
+export declare const ISSUE_TYPES: {
+    /** WU has done status but no stamp file */
+    readonly ORPHANED_WU: "orphaned_wu";
+    /** Signal references a WU that doesn't exist */
+    readonly DANGLING_SIGNAL: "dangling_signal";
+    /** Event references a WU that doesn't exist */
+    readonly BROKEN_EVENT: "broken_event";
+};
+/**
+ * Issue severity levels
+ */
+export declare const ISSUE_SEVERITY: {
+    /** Critical issues that may cause data loss */
+    readonly ERROR: "error";
+    /** Issues that should be fixed but aren't blocking */
+    readonly WARNING: "warning";
+    /** Informational findings */
+    readonly INFO: "info";
+};
+/**
+ * Issue type (union)
+ */
+export type IssueType = (typeof ISSUE_TYPES)[keyof typeof ISSUE_TYPES];
+/**
+ * Issue severity (union)
+ */
+export type IssueSeverity = (typeof ISSUE_SEVERITY)[keyof typeof ISSUE_SEVERITY];
+/**
+ * Mock WU YAML content
+ */
+export interface MockWU {
+    id: string;
+    status: string;
+    lane?: string;
+    title?: string;
+}
+/**
+ * Mock signal content
+ */
+export interface MockSignal {
+    id: string;
+    wuId?: string;
+    timestamp?: string;
+    message?: string;
+}
+/**
+ * Mock event content
+ */
+export interface MockEvent {
+    wuId: string;
+    type: string;
+    timestamp?: string;
+}
+/**
+ * Dependencies for state doctor (injectable for testing)
+ */
+export interface StateDoctorDeps {
+    /** List all WU YAML files */
+    listWUs: () => Promise<MockWU[]>;
+    /** List all stamp file IDs */
+    listStamps: () => Promise<string[]>;
+    /** List all signals */
+    listSignals: () => Promise<MockSignal[]>;
+    /** List all events */
+    listEvents: () => Promise<MockEvent[]>;
+    /** Remove a signal by ID (for --fix) */
+    removeSignal?: (id: string) => Promise<void>;
+    /** Remove events for a WU (for --fix) */
+    removeEvent?: (wuId: string) => Promise<void>;
+    /** Create a stamp for a WU (for --fix) */
+    createStamp?: (wuId: string, title: string) => Promise<void>;
+}
+/**
+ * A detected issue in the state
+ */
+export interface DiagnosisIssue {
+    /** Type of issue */
+    type: IssueType;
+    /** Severity level */
+    severity: IssueSeverity;
+    /** WU ID involved (if applicable) */
+    wuId?: string;
+    /** Signal ID involved (if applicable) */
+    signalId?: string;
+    /** Human-readable description */
+    description: string;
+    /** Suggested fix */
+    suggestion: string;
+    /** Whether this issue can be auto-fixed */
+    canAutoFix: boolean;
+}
+/**
+ * A fix error that occurred during auto-repair
+ */
+export interface FixError {
+    /** Type of issue that failed to fix */
+    type: IssueType;
+    /** WU ID involved (if applicable) */
+    wuId?: string;
+    /** Signal ID involved (if applicable) */
+    signalId?: string;
+    /** Error message */
+    error: string;
+}
+/**
+ * Summary statistics
+ */
+export interface DiagnosisSummary {
+    /** Number of orphaned WUs */
+    orphanedWUs: number;
+    /** Number of dangling signals */
+    danglingSignals: number;
+    /** Number of broken events */
+    brokenEvents: number;
+    /** Total number of issues */
+    totalIssues: number;
+}
+/**
+ * Options for diagnosis
+ */
+export interface DiagnosisOptions {
+    /** Whether to attempt auto-fixes */
+    fix?: boolean;
+    /** Dry-run mode (report what would be fixed) */
+    dryRun?: boolean;
+}
+/**
+ * Result of state diagnosis
+ */
+export interface StateDiagnosis {
+    /** Whether the state is healthy */
+    healthy: boolean;
+    /** List of detected issues */
+    issues: DiagnosisIssue[];
+    /** Summary statistics */
+    summary: DiagnosisSummary;
+    /** Issues that were fixed */
+    fixed: DiagnosisIssue[];
+    /** Errors that occurred during fixing */
+    fixErrors: FixError[];
+    /** Whether this was a dry-run */
+    dryRun?: boolean;
+    /** Issues that would be fixed (in dry-run mode) */
+    wouldFix?: DiagnosisIssue[];
+}
+export declare function diagnoseState(_baseDir: string, deps: StateDoctorDeps, options?: DiagnosisOptions): Promise<StateDiagnosis>;

package/dist/state-doctor-core.js

@@ -0,0 +1,251 @@
+/**
+ * State Doctor Core (WU-1209)
+ *
+ * Integrity checker for LumenFlow state that detects:
+ * - Orphaned WUs (done status but no stamp)
+ * - Dangling signals (reference non-existent WUs)
+ * - Broken memory relationships (events for missing WU specs)
+ *
+ * Inspired by Beads bd doctor command.
+ *
+ * Design principles:
+ * - Non-destructive by default (read-only diagnosis)
+ * - --fix flag for safe auto-repair of resolvable issues
+ * - Dependency injection for testability
+ * - Human-readable output with actionable suggestions
+ *
+ * @see {@link packages/@lumenflow/cli/src/state-doctor.ts} - CLI wrapper
+ * @see {@link packages/@lumenflow/core/src/__tests__/state-doctor-core.test.ts} - Tests
+ */
+/**
+ * Issue type constants
+ */
+export const ISSUE_TYPES = {
+    /** WU has done status but no stamp file */
+    ORPHANED_WU: 'orphaned_wu',
+    /** Signal references a WU that doesn't exist */
+    DANGLING_SIGNAL: 'dangling_signal',
+    /** Event references a WU that doesn't exist */
+    BROKEN_EVENT: 'broken_event',
+};
+/**
+ * Issue severity levels
+ */
+export const ISSUE_SEVERITY = {
+    /** Critical issues that may cause data loss */
+    ERROR: 'error',
+    /** Issues that should be fixed but aren't blocking */
+    WARNING: 'warning',
+    /** Informational findings */
+    INFO: 'info',
+};
+/**
+ * Detect orphaned WUs (done status but no stamp)
+ */
+function detectOrphanedWUs(wus, stamps) {
+    const issues = [];
+    for (const wu of wus) {
+        if (wu.status === 'done' && !stamps.has(wu.id)) {
+            issues.push({
+                type: ISSUE_TYPES.ORPHANED_WU,
+                severity: ISSUE_SEVERITY.WARNING,
+                wuId: wu.id,
+                description: `WU ${wu.id} has status 'done' but no stamp file exists`,
+                suggestion: `Create stamp file for ${wu.id} using: pnpm state:doctor --fix`,
+                canAutoFix: true,
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Detect dangling signals (reference non-existent WUs)
+ */
+function detectDanglingSignals(signals, wuIds) {
+    const issues = [];
+    for (const signal of signals) {
+        // Skip signals without WU references
+        if (!signal.wuId) {
+            continue;
+        }
+        if (!wuIds.has(signal.wuId)) {
+            issues.push({
+                type: ISSUE_TYPES.DANGLING_SIGNAL,
+                severity: ISSUE_SEVERITY.WARNING,
+                wuId: signal.wuId,
+                signalId: signal.id,
+                description: `Signal ${signal.id} references non-existent WU ${signal.wuId}`,
+                suggestion: `Remove dangling signal using: pnpm state:doctor --fix`,
+                canAutoFix: true,
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Detect broken events (reference non-existent WUs)
+ */
+function detectBrokenEvents(events, wuIds) {
+    const issues = [];
+    const seenWuIds = new Set();
+    for (const event of events) {
+        // Only report once per WU
+        if (seenWuIds.has(event.wuId)) {
+            continue;
+        }
+        if (!wuIds.has(event.wuId)) {
+            seenWuIds.add(event.wuId);
+            issues.push({
+                type: ISSUE_TYPES.BROKEN_EVENT,
+                severity: ISSUE_SEVERITY.WARNING,
+                wuId: event.wuId,
+                description: `Events exist for non-existent WU ${event.wuId}`,
+                suggestion: `Archive or remove events for missing WU using: pnpm state:doctor --fix`,
+                canAutoFix: true,
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Calculate summary statistics from issues
+ */
+function calculateSummary(issues) {
+    let orphanedWUs = 0;
+    let danglingSignals = 0;
+    let brokenEvents = 0;
+    for (const issue of issues) {
+        switch (issue.type) {
+            case ISSUE_TYPES.ORPHANED_WU:
+                orphanedWUs++;
+                break;
+            case ISSUE_TYPES.DANGLING_SIGNAL:
+                danglingSignals++;
+                break;
+            case ISSUE_TYPES.BROKEN_EVENT:
+                brokenEvents++;
+                break;
+        }
+    }
+    return {
+        orphanedWUs,
+        danglingSignals,
+        brokenEvents,
+        totalIssues: issues.length,
+    };
+}
+/**
+ * Attempt to fix an issue
+ */
+async function fixIssue(issue, deps, wus) {
+    try {
+        switch (issue.type) {
+            case ISSUE_TYPES.DANGLING_SIGNAL:
+                if (deps.removeSignal && issue.signalId) {
+                    await deps.removeSignal(issue.signalId);
+                    return { fixed: true };
+                }
+                return { fixed: false, error: 'No removeSignal function provided' };
+            case ISSUE_TYPES.BROKEN_EVENT:
+                if (deps.removeEvent && issue.wuId) {
+                    await deps.removeEvent(issue.wuId);
+                    return { fixed: true };
+                }
+                return { fixed: false, error: 'No removeEvent function provided' };
+            case ISSUE_TYPES.ORPHANED_WU:
+                if (deps.createStamp && issue.wuId) {
+                    const wu = wus.find((w) => w.id === issue.wuId);
+                    await deps.createStamp(issue.wuId, wu?.title || `WU ${issue.wuId}`);
+                    return { fixed: true };
+                }
+                return { fixed: false, error: 'No createStamp function provided' };
+            default:
+                return { fixed: false, error: `Unknown issue type: ${issue.type}` };
+        }
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        return { fixed: false, error };
+    }
+}
+/**
+ * Diagnose state integrity issues.
+ *
+ * Detects:
+ * - Orphaned WUs (done status but no stamp)
+ * - Dangling signals (reference non-existent WUs)
+ * - Broken events (events for missing WU specs)
+ *
+ * @param baseDir - Project base directory
+ * @param deps - Dependency functions for reading/writing state
+ * @param options - Diagnosis options
+ * @returns Diagnosis result with issues and optional fixes
+ *
+ * @example
+ * // Diagnose without fixing
+ * const result = await diagnoseState(baseDir, deps);
+ *
+ * @example
+ * // Diagnose and fix
+ * const result = await diagnoseState(baseDir, deps, { fix: true });
+ *
+ * @example
+ * // Dry-run (report what would be fixed)
+ * const result = await diagnoseState(baseDir, deps, { fix: true, dryRun: true });
+ */
+/**
+ * Apply fixes to auto-fixable issues
+ */
+async function applyFixes(issues, deps, wus, result) {
+    const fixableIssues = issues.filter((i) => i.canAutoFix);
+    for (const issue of fixableIssues) {
+        const fixResult = await fixIssue(issue, deps, wus);
+        if (fixResult.fixed) {
+            result.fixed.push(issue);
+        }
+        else if (fixResult.error) {
+            result.fixErrors.push({
+                type: issue.type,
+                wuId: issue.wuId,
+                signalId: issue.signalId,
+                error: fixResult.error,
+            });
+        }
+    }
+}
+export async function diagnoseState(_baseDir, deps, options = {}) {
+    const { fix = false, dryRun = false } = options;
+    // Gather state data
+    const [wus, stamps, signals, events] = await Promise.all([
+        deps.listWUs(),
+        deps.listStamps(),
+        deps.listSignals(),
+        deps.listEvents(),
+    ]);
+    // Build lookup sets
+    const wuIds = new Set(wus.map((wu) => wu.id));
+    const stampIds = new Set(stamps);
+    // Detect issues
+    const orphanedWUissues = detectOrphanedWUs(wus, stampIds);
+    const danglingSignalIssues = detectDanglingSignals(signals, wuIds);
+    const brokenEventIssues = detectBrokenEvents(events, wuIds);
+    const issues = [...orphanedWUissues, ...danglingSignalIssues, ...brokenEventIssues];
+    const summary = calculateSummary(issues);
+    // Initialize result
+    const result = {
+        healthy: issues.length === 0,
+        issues,
+        summary,
+        fixed: [],
+        fixErrors: [],
+    };
+    // Handle fixing
+    if (fix && dryRun) {
+        result.dryRun = true;
+        result.wouldFix = issues.filter((i) => i.canAutoFix);
+    }
+    else if (fix) {
+        await applyFixes(issues, deps, wus, result);
+    }
+    return result;
+}