@cleocode/cleo 2026.2.5

package/dist/core/migration/logger.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Structured logging for migration operations.
+ *
+ * Provides audit trail and debugging support for all migration phases.
+ * Logs are written in JSONL format for easy parsing and appending.
+ *
+ * @task T4727
+ * @epic T4454
+ */
+/** Log entry severity level */
+export type LogLevel = 'info' | 'warn' | 'error' | 'debug';
+/** Single migration log entry */
+export interface MigrationLogEntry {
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Log level */
+    level: LogLevel;
+    /** Migration phase (init, backup, import, verify, complete, etc.) */
+    phase: string;
+    /** Specific operation within phase */
+    operation: string;
+    /** Human-readable message */
+    message: string;
+    /** Duration since migration start in milliseconds */
+    durationMs: number;
+    /** Additional structured data */
+    data?: Record<string, unknown>;
+}
+/** Migration logger configuration */
+export interface MigrationLoggerConfig {
+    /** Maximum number of log files to retain */
+    maxLogFiles?: number;
+    /** Minimum log level to record */
+    minLevel?: LogLevel;
+    /** Enable console output in addition to file logging */
+    consoleOutput?: boolean;
+}
+/** Structured logger for migration operations */
+export declare class MigrationLogger {
+    private logPath;
+    private entries;
+    private startTime;
+    private cleoDir;
+    private config;
+    /**
+     * Create a new migration logger.
+     * @param cleoDir - Path to .cleo directory
+     * @param config - Optional configuration
+     */
+    constructor(cleoDir: string, config?: MigrationLoggerConfig);
+    /**
+     * Get numeric priority for log level comparison.
+     */
+    private getLevelPriority;
+    /**
+     * Check if a log level should be recorded.
+     */
+    private shouldLog;
+    /**
+     * Write a log entry.
+     */
+    private log;
+    /**
+     * Log an info-level message.
+     */
+    info(phase: string, operation: string, message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log a warning-level message.
+     */
+    warn(phase: string, operation: string, message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log an error-level message.
+     */
+    error(phase: string, operation: string, message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log a debug-level message.
+     */
+    debug(phase: string, operation: string, message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log file operation with size information.
+     */
+    logFileOperation(phase: string, operation: 'read' | 'write' | 'backup' | 'rename' | 'delete', sourcePath: string, targetPath?: string, additionalData?: Record<string, unknown>): void;
+    /**
+     * Log validation result.
+     */
+    logValidation(phase: string, target: string, valid: boolean, details?: Record<string, unknown>, errors?: string[]): void;
+    /**
+     * Log import progress.
+     */
+    logImportProgress(phase: string, entityType: string, imported: number, total: number, additionalData?: Record<string, unknown>): void;
+    /**
+     * Log phase start.
+     */
+    phaseStart(phase: string, data?: Record<string, unknown>): void;
+    /**
+     * Log phase completion.
+     */
+    phaseComplete(phase: string, data?: Record<string, unknown>): void;
+    /**
+     * Log phase failure.
+     */
+    phaseFailed(phase: string, error: Error | string, data?: Record<string, unknown>): void;
+    /**
+     * Clean up old log files, keeping only the most recent ones.
+     */
+    private cleanupOldLogs;
+    /**
+     * Get the absolute path to the log file.
+     */
+    getLogPath(): string;
+    /**
+     * Get the path to the log file relative to cleoDir.
+     */
+    getRelativeLogPath(): string;
+    /**
+     * Get all logged entries.
+     */
+    getEntries(): MigrationLogEntry[];
+    /**
+     * Get entries filtered by level.
+     */
+    getEntriesByLevel(level: LogLevel): MigrationLogEntry[];
+    /**
+     * Get entries for a specific phase.
+     */
+    getEntriesByPhase(phase: string): MigrationLogEntry[];
+    /**
+     * Get the total duration of the migration so far.
+     */
+    getDurationMs(): number;
+    /**
+     * Get summary statistics for the migration.
+     */
+    getSummary(): {
+        totalEntries: number;
+        durationMs: number;
+        errors: number;
+        warnings: number;
+        info: number;
+        debug: number;
+        phases: string[];
+    };
+}
+/**
+ * Create a migration logger for the given cleo directory.
+ * Convenience function for functional programming style.
+ */
+export declare function createMigrationLogger(cleoDir: string, config?: MigrationLoggerConfig): MigrationLogger;
+/**
+ * Read and parse a migration log file.
+ */
+export declare function readMigrationLog(logPath: string): MigrationLogEntry[];
+/**
+ * Check if a log file exists and is readable.
+ */
+export declare function logFileExists(logPath: string): boolean;
+/**
+ * Get the most recent migration log file for a cleo directory.
+ */
+export declare function getLatestMigrationLog(cleoDir: string): string | null;
+//# sourceMappingURL=logger.d.ts.map

package/dist/core/migration/logger.d.ts.map

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

package/dist/core/migration/logger.js

@@ -0,0 +1,364 @@
+/**
+ * Structured logging for migration operations.
+ *
+ * Provides audit trail and debugging support for all migration phases.
+ * Logs are written in JSONL format for easy parsing and appending.
+ *
+ * @task T4727
+ * @epic T4454
+ */
+import { existsSync, mkdirSync, statSync, appendFileSync } from 'node:fs';
+import { join, dirname, relative } from 'node:path';
+/** Structured logger for migration operations */
+export class MigrationLogger {
+    logPath;
+    entries = [];
+    startTime;
+    cleoDir;
+    config;
+    /**
+     * Create a new migration logger.
+     * @param cleoDir - Path to .cleo directory
+     * @param config - Optional configuration
+     */
+    constructor(cleoDir, config = {}) {
+        this.cleoDir = cleoDir;
+        this.config = {
+            maxLogFiles: config.maxLogFiles ?? 10,
+            minLevel: config.minLevel ?? 'debug',
+            consoleOutput: config.consoleOutput ?? false,
+        };
+        // Generate timestamped log filename
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        this.logPath = join(cleoDir, 'logs', `migration-${timestamp}.jsonl`);
+        // Ensure logs directory exists
+        const logsDir = dirname(this.logPath);
+        if (!existsSync(logsDir)) {
+            mkdirSync(logsDir, { recursive: true });
+        }
+        this.startTime = Date.now();
+        // Clean up old log files
+        this.cleanupOldLogs();
+    }
+    /**
+     * Get numeric priority for log level comparison.
+     */
+    getLevelPriority(level) {
+        const priorities = {
+            debug: 0,
+            info: 1,
+            warn: 2,
+            error: 3,
+        };
+        return priorities[level];
+    }
+    /**
+     * Check if a log level should be recorded.
+     */
+    shouldLog(level) {
+        return this.getLevelPriority(level) >= this.getLevelPriority(this.config.minLevel);
+    }
+    /**
+     * Write a log entry.
+     */
+    log(level, phase, operation, message, data) {
+        if (!this.shouldLog(level)) {
+            return;
+        }
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            phase,
+            operation,
+            message,
+            durationMs: Date.now() - this.startTime,
+            data,
+        };
+        this.entries.push(entry);
+        // Append to file
+        try {
+            appendFileSync(this.logPath, JSON.stringify(entry) + '\n');
+        }
+        catch (err) {
+            // If file logging fails, try console as fallback
+            console.error(`Failed to write to migration log: ${String(err)}`);
+        }
+        // Console output if enabled
+        if (this.config.consoleOutput) {
+            const prefix = `[${level.toUpperCase()}] ${phase}.${operation}:`;
+            if (level === 'error') {
+                console.error(prefix, message, data ?? '');
+            }
+            else if (level === 'warn') {
+                console.warn(prefix, message, data ?? '');
+            }
+            else {
+                console.log(prefix, message, data ?? '');
+            }
+        }
+    }
+    /**
+     * Log an info-level message.
+     */
+    info(phase, operation, message, data) {
+        this.log('info', phase, operation, message, data);
+    }
+    /**
+     * Log a warning-level message.
+     */
+    warn(phase, operation, message, data) {
+        this.log('warn', phase, operation, message, data);
+    }
+    /**
+     * Log an error-level message.
+     */
+    error(phase, operation, message, data) {
+        this.log('error', phase, operation, message, data);
+    }
+    /**
+     * Log a debug-level message.
+     */
+    debug(phase, operation, message, data) {
+        this.log('debug', phase, operation, message, data);
+    }
+    /**
+     * Log file operation with size information.
+     */
+    logFileOperation(phase, operation, sourcePath, targetPath, additionalData) {
+        const data = {
+            sourcePath: relative(this.cleoDir, sourcePath),
+            ...additionalData,
+        };
+        // Get source file size if it exists
+        if (existsSync(sourcePath)) {
+            try {
+                const stats = statSync(sourcePath);
+                data.sourceSize = stats.size;
+                data.sourceModified = stats.mtime.toISOString();
+            }
+            catch {
+                // Size not available
+            }
+        }
+        // Get target file size if provided and exists
+        if (targetPath) {
+            data.targetPath = relative(this.cleoDir, targetPath);
+            if (existsSync(targetPath)) {
+                try {
+                    const stats = statSync(targetPath);
+                    data.targetSize = stats.size;
+                    data.targetModified = stats.mtime.toISOString();
+                }
+                catch {
+                    // Size not available
+                }
+            }
+        }
+        this.info(phase, `file-${operation}`, `File ${operation} operation`, data);
+    }
+    /**
+     * Log validation result.
+     */
+    logValidation(phase, target, valid, details, errors) {
+        const data = {
+            target,
+            valid,
+            ...details,
+        };
+        if (errors && errors.length > 0) {
+            data.errors = errors;
+            this.error(phase, 'validation', `Validation failed for ${target}`, data);
+        }
+        else if (!valid) {
+            this.warn(phase, 'validation', `Validation warning for ${target}`, data);
+        }
+        else {
+            this.info(phase, 'validation', `Validation passed for ${target}`, data);
+        }
+    }
+    /**
+     * Log import progress.
+     */
+    logImportProgress(phase, entityType, imported, total, additionalData) {
+        const percent = total > 0 ? Math.round((imported / total) * 100) : 0;
+        this.info(phase, 'import-progress', `Imported ${imported} of ${total} ${entityType}`, {
+            imported,
+            total,
+            percent,
+            remaining: total - imported,
+            ...additionalData,
+        });
+    }
+    /**
+     * Log phase start.
+     */
+    phaseStart(phase, data) {
+        this.info(phase, 'start', `Starting phase: ${phase}`, data);
+    }
+    /**
+     * Log phase completion.
+     */
+    phaseComplete(phase, data) {
+        this.info(phase, 'complete', `Completed phase: ${phase}`, data);
+    }
+    /**
+     * Log phase failure.
+     */
+    phaseFailed(phase, error, data) {
+        this.error(phase, 'failed', `Phase failed: ${phase}`, {
+            error: error instanceof Error ? error.message : error,
+            stack: error instanceof Error ? error.stack : undefined,
+            ...data,
+        });
+    }
+    /**
+     * Clean up old log files, keeping only the most recent ones.
+     */
+    cleanupOldLogs() {
+        try {
+            const logsDir = join(this.cleoDir, 'logs');
+            if (!existsSync(logsDir)) {
+                return;
+            }
+            const { readdirSync, unlinkSync } = require('node:fs');
+            const files = readdirSync(logsDir)
+                .filter((f) => f.startsWith('migration-') && f.endsWith('.jsonl'))
+                .map((f) => ({
+                name: f,
+                path: join(logsDir, f),
+                mtime: statSync(join(logsDir, f)).mtime.getTime(),
+            }))
+                .sort((a, b) => b.mtime - a.mtime);
+            // Remove files beyond the retention limit
+            const filesToRemove = files.slice(this.config.maxLogFiles);
+            for (const file of filesToRemove) {
+                try {
+                    unlinkSync(file.path);
+                }
+                catch {
+                    // Ignore cleanup errors
+                }
+            }
+        }
+        catch {
+            // Cleanup is best-effort
+        }
+    }
+    /**
+     * Get the absolute path to the log file.
+     */
+    getLogPath() {
+        return this.logPath;
+    }
+    /**
+     * Get the path to the log file relative to cleoDir.
+     */
+    getRelativeLogPath() {
+        return relative(this.cleoDir, this.logPath);
+    }
+    /**
+     * Get all logged entries.
+     */
+    getEntries() {
+        return [...this.entries];
+    }
+    /**
+     * Get entries filtered by level.
+     */
+    getEntriesByLevel(level) {
+        return this.entries.filter(e => e.level === level);
+    }
+    /**
+     * Get entries for a specific phase.
+     */
+    getEntriesByPhase(phase) {
+        return this.entries.filter(e => e.phase === phase);
+    }
+    /**
+     * Get the total duration of the migration so far.
+     */
+    getDurationMs() {
+        return Date.now() - this.startTime;
+    }
+    /**
+     * Get summary statistics for the migration.
+     */
+    getSummary() {
+        const counts = {
+            error: 0,
+            warn: 0,
+            info: 0,
+            debug: 0,
+        };
+        const phases = new Set();
+        for (const entry of this.entries) {
+            counts[entry.level]++;
+            phases.add(entry.phase);
+        }
+        return {
+            totalEntries: this.entries.length,
+            durationMs: this.getDurationMs(),
+            errors: counts.error,
+            warnings: counts.warn,
+            info: counts.info,
+            debug: counts.debug,
+            phases: Array.from(phases).sort(),
+        };
+    }
+}
+/**
+ * Create a migration logger for the given cleo directory.
+ * Convenience function for functional programming style.
+ */
+export function createMigrationLogger(cleoDir, config) {
+    return new MigrationLogger(cleoDir, config);
+}
+/**
+ * Read and parse a migration log file.
+ */
+export function readMigrationLog(logPath) {
+    const { readFileSync } = require('node:fs');
+    const content = readFileSync(logPath, 'utf-8');
+    return content
+        .split('\n')
+        .filter((line) => line.trim())
+        .map((line) => JSON.parse(line));
+}
+/**
+ * Check if a log file exists and is readable.
+ */
+export function logFileExists(logPath) {
+    try {
+        const { accessSync, constants } = require('node:fs');
+        accessSync(logPath, constants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get the most recent migration log file for a cleo directory.
+ */
+export function getLatestMigrationLog(cleoDir) {
+    try {
+        const { readdirSync, statSync } = require('node:fs');
+        const logsDir = join(cleoDir, 'logs');
+        if (!existsSync(logsDir)) {
+            return null;
+        }
+        const files = readdirSync(logsDir)
+            .filter((f) => f.startsWith('migration-') && f.endsWith('.jsonl'))
+            .map((f) => ({
+            name: f,
+            path: join(logsDir, f),
+            mtime: statSync(join(logsDir, f)).mtime.getTime(),
+        }))
+            .sort((a, b) => b.mtime - a.mtime);
+        return files.length > 0 ? files[0].path : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=logger.js.map

package/dist/core/migration/logger.js.map

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

package/dist/core/migration/preflight.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Pre-flight migration checks.
+ *
+ * Detects when JSON data exists but hasn't been migrated to SQLite,
+ * and provides actionable diagnostics for users upgrading to v2.
+ *
+ * Core module: CLI and MCP both call these functions.
+ *
+ * @task T4699
+ */
+/** Pre-flight check result. */
+export interface PreflightResult {
+    /** Whether a storage migration is needed. */
+    migrationNeeded: boolean;
+    /** Current detected storage engine. */
+    currentEngine: 'json' | 'sqlite' | 'dual' | 'none';
+    /** Human-readable summary of what was detected. */
+    summary: string;
+    /** Actionable fix command. */
+    fix: string | null;
+    /** Detailed diagnostics. */
+    details: {
+        todoJsonExists: boolean;
+        todoJsonTaskCount: number;
+        archiveJsonExists: boolean;
+        archiveJsonTaskCount: number;
+        sessionsJsonExists: boolean;
+        sessionsJsonCount: number;
+        tasksDbExists: boolean;
+        tasksDbSize: number;
+        configEngine: string | null;
+    };
+}
+/**
+ * Check whether JSON data needs to be migrated to SQLite.
+ *
+ * Returns a diagnostic result that callers can use to warn users.
+ * This function is read-only and never modifies any files.
+ *
+ * @task T4699
+ */
+export declare function checkStorageMigration(cwd?: string): PreflightResult;
+//# sourceMappingURL=preflight.d.ts.map

package/dist/core/migration/preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../../src/core/migration/preflight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,+BAA+B;AAC/B,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,eAAe,EAAE,OAAO,CAAC;IACzB,uCAAuC;IACvC,aAAa,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IACnD,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,4BAA4B;IAC5B,OAAO,EAAE;QACP,cAAc,EAAE,OAAO,CAAC;QACxB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,iBAAiB,EAAE,OAAO,CAAC;QAC3B,oBAAoB,EAAE,MAAM,CAAC;QAC7B,kBAAkB,EAAE,OAAO,CAAC;QAC5B,iBAAiB,EAAE,MAAM,CAAC;QAC1B,aAAa,EAAE,OAAO,CAAC;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;KAC7B,CAAC;CACH;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,eAAe,CA+InE"}