@cleocode/core 2026.4.9 → 2026.4.11

package/dist/migration/state.js

@@ -0,0 +1,421 @@
+/**
+ * Migration state tracking and recovery.
+ *
+ * Provides persistent tracking of migration progress to enable:
+ * - Resumable migrations after interruptions
+ * - Debugging of failed migrations
+ * - Progress monitoring during long operations
+ *
+ * @task T4726
+ * @epic T4454
+ */
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { readFile, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** State file name */
+const STATE_FILENAME = '.migration-state.json';
+/**
+ * Compute SHA-256 checksum of file content.
+ * @param filePath - Path to the file
+ * @returns Hex-encoded SHA-256 checksum, or empty string if file doesn't exist
+ */
+async function computeFileChecksum(filePath) {
+    try {
+        const content = await readFile(filePath);
+        return createHash('sha256').update(content).digest('hex');
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Count records in a JSON file.
+ * @param filePath - Path to the JSON file
+ * @param key - Key to count (e.g., 'tasks', 'sessions')
+ * @returns Count of records, or 0 if file doesn't exist or is invalid
+ */
+async function countRecords(filePath, key) {
+    try {
+        const content = await readFile(filePath, 'utf-8');
+        const data = JSON.parse(content);
+        return (data[key] ?? []).length;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Create initial migration state at the start of migration.
+ *
+ * Captures source file checksums and initializes progress tracking.
+ * Uses atomic write pattern to ensure state is never in an inconsistent state.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @param sourceFiles - Optional pre-computed source file info
+ * @returns The created migration state
+ * @task T4726
+ */
+export async function createMigrationState(cleoDir, sourceFiles) {
+    // If source files not provided, compute them
+    const files = sourceFiles ?? {};
+    if (!files.todoJson) {
+        const todoPath = join(cleoDir, 'todo.json');
+        if (existsSync(todoPath)) {
+            files.todoJson = {
+                path: todoPath,
+                checksum: await computeFileChecksum(todoPath),
+                taskCount: await countRecords(todoPath, 'tasks'),
+            };
+        }
+    }
+    if (!files.sessionsJson) {
+        const sessionsPath = join(cleoDir, 'sessions.json');
+        if (existsSync(sessionsPath)) {
+            files.sessionsJson = {
+                path: sessionsPath,
+                checksum: await computeFileChecksum(sessionsPath),
+                sessionCount: await countRecords(sessionsPath, 'sessions'),
+            };
+        }
+    }
+    if (!files.archiveJson) {
+        const archivePath = join(cleoDir, 'todo-archive.json');
+        if (existsSync(archivePath)) {
+            files.archiveJson = {
+                path: archivePath,
+                checksum: await computeFileChecksum(archivePath),
+                archivedCount: (await countRecords(archivePath, 'tasks')) ||
+                    (await countRecords(archivePath, 'archivedTasks')),
+            };
+        }
+    }
+    const state = {
+        version: '1.0.0',
+        startedAt: new Date().toISOString(),
+        phase: 'init',
+        sourceFiles: files,
+        progress: {
+            tasksImported: 0,
+            archivedImported: 0,
+            sessionsImported: 0,
+            totalTasks: files.todoJson?.taskCount ?? 0,
+            totalArchived: files.archiveJson?.archivedCount ?? 0,
+            totalSessions: files.sessionsJson?.sessionCount ?? 0,
+        },
+        errors: [],
+        warnings: [],
+    };
+    await writeMigrationState(cleoDir, state);
+    return state;
+}
+/**
+ * Write migration state to disk atomically.
+ * Uses write-to-temp-then-rename pattern for safety.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @param state - Migration state to write
+ */
+async function writeMigrationState(cleoDir, state) {
+    const statePath = join(cleoDir, STATE_FILENAME);
+    const tempPath = `${statePath}.tmp`;
+    await writeFile(tempPath, JSON.stringify(state, null, 2));
+    await writeFile(statePath, await readFile(tempPath));
+    // Clean up temp file
+    try {
+        await unlink(tempPath);
+    }
+    catch {
+        // Ignore cleanup errors
+    }
+}
+/**
+ * Update migration state with partial updates.
+ *
+ * Merges updates with existing state and writes atomically.
+ * Automatically adds timestamp to phase transitions.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @param updates - Partial state updates to apply
+ * @returns The updated migration state
+ * @task T4726
+ */
+export async function updateMigrationState(cleoDir, updates) {
+    const current = await loadMigrationState(cleoDir);
+    if (!current) {
+        throw new Error('No migration state exists. Call createMigrationState first.');
+    }
+    // Deep merge progress if provided
+    const mergedProgress = updates.progress
+        ? {
+            tasksImported: updates.progress.tasksImported ?? current.progress.tasksImported,
+            archivedImported: updates.progress.archivedImported ?? current.progress.archivedImported,
+            sessionsImported: updates.progress.sessionsImported ?? current.progress.sessionsImported,
+            totalTasks: updates.progress.totalTasks ?? current.progress.totalTasks,
+            totalArchived: updates.progress.totalArchived ?? current.progress.totalArchived,
+            totalSessions: updates.progress.totalSessions ?? current.progress.totalSessions,
+        }
+        : current.progress;
+    // Deep merge sourceFiles if provided
+    const mergedSourceFiles = updates.sourceFiles
+        ? { ...current.sourceFiles, ...updates.sourceFiles }
+        : current.sourceFiles;
+    // Merge arrays
+    const mergedErrors = updates.errors ? [...current.errors, ...updates.errors] : current.errors;
+    const mergedWarnings = updates.warnings
+        ? [...current.warnings, ...updates.warnings]
+        : current.warnings;
+    const updated = {
+        ...current,
+        ...updates,
+        progress: mergedProgress,
+        sourceFiles: mergedSourceFiles,
+        errors: mergedErrors,
+        warnings: mergedWarnings,
+    };
+    await writeMigrationState(cleoDir, updated);
+    return updated;
+}
+/**
+ * Update just the migration phase.
+ * Convenience wrapper for common phase transition.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @param phase - New phase
+ * @returns The updated migration state
+ * @task T4726
+ */
+export async function updateMigrationPhase(cleoDir, phase) {
+    return updateMigrationState(cleoDir, { phase });
+}
+/**
+ * Update progress counters during import.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @param progress - Progress updates (only changed counters needed)
+ * @returns The updated migration state
+ * @task T4726
+ */
+export async function updateMigrationProgress(cleoDir, progress) {
+    const current = await loadMigrationState(cleoDir);
+    if (!current) {
+        throw new Error('No migration state exists');
+    }
+    const mergedProgress = {
+        tasksImported: progress.tasksImported ?? current.progress.tasksImported,
+        archivedImported: progress.archivedImported ?? current.progress.archivedImported,
+        sessionsImported: progress.sessionsImported ?? current.progress.sessionsImported,
+        totalTasks: progress.totalTasks ?? current.progress.totalTasks,
+        totalArchived: progress.totalArchived ?? current.progress.totalArchived,
+        totalSessions: progress.totalSessions ?? current.progress.totalSessions,
+    };
+    return updateMigrationState(cleoDir, { progress: mergedProgress });
+}
+/**
+ * Add an error to the migration state.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @param error - Error message
+ * @returns The updated migration state
+ * @task T4726
+ */
+export async function addMigrationError(cleoDir, error) {
+    const state = await loadMigrationState(cleoDir);
+    if (!state) {
+        throw new Error('No migration state exists');
+    }
+    state.errors.push(error);
+    state.phase = 'failed';
+    await writeMigrationState(cleoDir, state);
+    return state;
+}
+/**
+ * Add a warning to the migration state.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @param warning - Warning message
+ * @returns The updated migration state
+ * @task T4726
+ */
+export async function addMigrationWarning(cleoDir, warning) {
+    const state = await loadMigrationState(cleoDir);
+    if (!state) {
+        throw new Error('No migration state exists');
+    }
+    state.warnings.push(warning);
+    await writeMigrationState(cleoDir, state);
+    return state;
+}
+/**
+ * Load existing migration state.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @returns Migration state, or null if no state file exists
+ * @task T4726
+ */
+export async function loadMigrationState(cleoDir) {
+    try {
+        const statePath = join(cleoDir, STATE_FILENAME);
+        const content = await readFile(statePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if a migration is in progress.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @returns true if migration state exists and is not complete/failed
+ * @task T4726
+ */
+export async function isMigrationInProgress(cleoDir) {
+    const state = await loadMigrationState(cleoDir);
+    if (!state)
+        return false;
+    return state.phase !== 'complete' && state.phase !== 'failed';
+}
+/**
+ * Check if migration can be resumed.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @returns Object with resume info, or null if cannot resume
+ * @task T4726
+ */
+export async function canResumeMigration(cleoDir) {
+    const state = await loadMigrationState(cleoDir);
+    if (!state)
+        return null;
+    // Can resume if we're not complete and not failed
+    const canResume = state.phase !== 'complete' && state.phase !== 'failed';
+    return {
+        canResume,
+        phase: state.phase,
+        progress: state.progress,
+        errors: state.errors,
+    };
+}
+/**
+ * Mark migration as complete.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @returns The completed migration state
+ * @task T4726
+ */
+export async function completeMigration(cleoDir) {
+    const state = await updateMigrationState(cleoDir, {
+        phase: 'complete',
+        completedAt: new Date().toISOString(),
+    });
+    // Auto-cleanup completed state after a delay
+    // Keep it for a short while for verification purposes
+    setTimeout(() => {
+        clearMigrationState(cleoDir).catch(() => {
+            // Ignore cleanup errors
+        });
+    }, 5000);
+    return state;
+}
+/**
+ * Mark migration as failed with error details.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @param error - Primary error message
+ * @returns The failed migration state
+ * @task T4726
+ */
+export async function failMigration(cleoDir, error) {
+    return updateMigrationState(cleoDir, {
+        phase: 'failed',
+        errors: [error],
+    });
+}
+/**
+ * Clear migration state file.
+ * Safe to call even if state doesn't exist.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @task T4726
+ */
+export async function clearMigrationState(cleoDir) {
+    try {
+        const statePath = join(cleoDir, STATE_FILENAME);
+        await unlink(statePath);
+    }
+    catch {
+        // Ignore if doesn't exist
+    }
+}
+/**
+ * Get a summary of migration state for display.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @returns Human-readable summary, or null if no state
+ * @task T4726
+ */
+export async function getMigrationSummary(cleoDir) {
+    const state = await loadMigrationState(cleoDir);
+    if (!state)
+        return null;
+    const { phase, progress, errors, warnings, startedAt, completedAt } = state;
+    const lines = [
+        `Migration Status: ${phase.toUpperCase()}`,
+        `Started: ${new Date(startedAt).toLocaleString()}`,
+    ];
+    if (completedAt) {
+        lines.push(`Completed: ${new Date(completedAt).toLocaleString()}`);
+    }
+    lines.push(`Progress: ${progress.tasksImported}/${progress.totalTasks} tasks, ` +
+        `${progress.archivedImported}/${progress.totalArchived} archived, ` +
+        `${progress.sessionsImported}/${progress.totalSessions} sessions`);
+    if (errors.length > 0) {
+        lines.push(`\nErrors (${errors.length}):`);
+        for (const e of errors) {
+            lines.push(`  - ${e}`);
+        }
+    }
+    if (warnings.length > 0) {
+        lines.push(`\nWarnings (${warnings.length}):`);
+        for (const w of warnings) {
+            lines.push(`  - ${w}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Verify source files haven't changed since migration started.
+ *
+ * Compares current checksums with stored checksums to detect
+ * if source files were modified during migration.
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @returns Object with verification results
+ * @task T4726
+ */
+export async function verifySourceIntegrity(cleoDir) {
+    const state = await loadMigrationState(cleoDir);
+    if (!state) {
+        return { valid: false, changed: [], missing: ['state'] };
+    }
+    const changed = [];
+    const missing = [];
+    for (const [key, fileInfo] of Object.entries(state.sourceFiles)) {
+        if (!fileInfo)
+            continue;
+        if (!existsSync(fileInfo.path)) {
+            missing.push(key);
+            continue;
+        }
+        const currentChecksum = await computeFileChecksum(fileInfo.path);
+        if (currentChecksum !== fileInfo.checksum) {
+            changed.push(key);
+        }
+    }
+    return {
+        valid: changed.length === 0 && missing.length === 0,
+        changed,
+        missing,
+    };
+}
+//# sourceMappingURL=state.js.map

package/dist/migration/state.js.map

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

package/dist/migration/validate.js

@@ -0,0 +1,241 @@
+/**
+ * Pre-migration JSON validation.
+ *
+ * Validates all JSON source files BEFORE any destructive database operations.
+ * This prevents data loss scenarios where the database is deleted but JSON parsing fails.
+ *
+ * @task T4725
+ * @epic T4454
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Parse a JSON parse error to extract line and column information.
+ */
+function parseJsonError(error) {
+    const message = String(error);
+    // Try to extract line/column from standard JSON parse errors
+    // Format: "Unexpected token X in JSON at position Y" or similar
+    const lineMatch = message.match(/line\s+(\d+)/i);
+    const columnMatch = message.match(/column\s+(\d+)/i);
+    return {
+        message,
+        line: lineMatch ? parseInt(lineMatch[1], 10) : undefined,
+        column: columnMatch ? parseInt(columnMatch[1], 10) : undefined,
+    };
+}
+/**
+ * Validate a single JSON file.
+ *
+ * @param filePath - Full path to the JSON file
+ * @param countExtractor - Function to extract count from parsed data
+ * @returns Validation result
+ */
+function validateJsonFile(filePath, countExtractor) {
+    const result = {
+        valid: false,
+        exists: false,
+        count: 0,
+    };
+    if (!existsSync(filePath)) {
+        // File doesn't exist - this is OK, just means no data of this type
+        result.valid = true;
+        return result;
+    }
+    result.exists = true;
+    try {
+        // Check if file is readable and non-empty
+        const stats = statSync(filePath);
+        if (stats.size === 0) {
+            result.error = 'File is empty (0 bytes)';
+            return result;
+        }
+        const content = readFileSync(filePath, 'utf-8');
+        if (content.trim().length === 0) {
+            result.error = 'File contains only whitespace';
+            return result;
+        }
+        // Attempt to parse
+        const data = JSON.parse(content);
+        result.valid = true;
+        result.count = countExtractor(data);
+    }
+    catch (err) {
+        const parsed = parseJsonError(err);
+        result.error = `Parse error: ${parsed.message}`;
+        if (parsed.line)
+            result.line = parsed.line;
+        if (parsed.column)
+            result.column = parsed.column;
+    }
+    return result;
+}
+/**
+ * Validate all JSON source files before migration.
+ *
+ * This function MUST be called BEFORE any destructive database operations.
+ * It checks that all JSON files are parseable and contain expected data.
+ *
+ * @param cleoDir - Path to the .cleo directory
+ * @returns Validation result with details for each file
+ * @task T4725
+ */
+export function validateSourceFiles(cleoDir) {
+    const warnings = [];
+    // Validate todo.json
+    const todoPath = join(cleoDir, 'todo.json');
+    const todoJson = validateJsonFile(todoPath, (data) => {
+        const record = data;
+        return Array.isArray(record.tasks) ? record.tasks.length : 0;
+    });
+    if (todoJson.exists && todoJson.valid && todoJson.count === 0) {
+        warnings.push(`todo.json has 0 tasks (file exists but task array is empty)`);
+    }
+    if (todoJson.exists && !todoJson.valid) {
+        const location = todoJson.line
+            ? ` at line ${todoJson.line}${todoJson.column ? `, column ${todoJson.column}` : ''}`
+            : '';
+        todoJson.error = `${todoJson.error}${location} in ${todoPath}`;
+    }
+    // Validate sessions.json
+    const sessionsPath = join(cleoDir, 'sessions.json');
+    const sessionsJson = validateJsonFile(sessionsPath, (data) => {
+        const record = data;
+        return Array.isArray(record.sessions) ? record.sessions.length : 0;
+    });
+    if (sessionsJson.exists && sessionsJson.valid && sessionsJson.count === 0) {
+        warnings.push(`sessions.json has 0 sessions`);
+    }
+    if (sessionsJson.exists && !sessionsJson.valid) {
+        const location = sessionsJson.line
+            ? ` at line ${sessionsJson.line}${sessionsJson.column ? `, column ${sessionsJson.column}` : ''}`
+            : '';
+        sessionsJson.error = `${sessionsJson.error}${location} in ${sessionsPath}`;
+    }
+    // Validate todo-archive.json
+    const archivePath = join(cleoDir, 'todo-archive.json');
+    const archiveJson = validateJsonFile(archivePath, (data) => {
+        const record = data;
+        // Support both 'tasks' and 'archivedTasks' keys
+        const tasks = Array.isArray(record.tasks) ? record.tasks : [];
+        const archivedTasks = Array.isArray(record.archivedTasks) ? record.archivedTasks : [];
+        return tasks.length + archivedTasks.length;
+    });
+    if (archiveJson.exists && archiveJson.valid && archiveJson.count === 0) {
+        warnings.push(`todo-archive.json has 0 archived tasks`);
+    }
+    if (archiveJson.exists && !archiveJson.valid) {
+        const location = archiveJson.line
+            ? ` at line ${archiveJson.line}${archiveJson.column ? `, column ${archiveJson.column}` : ''}`
+            : '';
+        archiveJson.error = `${archiveJson.error}${location} in ${archivePath}`;
+    }
+    // Calculate totals
+    const totalTasks = (todoJson.valid ? todoJson.count : 0) + (archiveJson.valid ? archiveJson.count : 0);
+    // Determine overall validity
+    const valid = todoJson.valid && sessionsJson.valid && archiveJson.valid;
+    return {
+        valid,
+        todoJson,
+        sessionsJson,
+        archiveJson,
+        totalTasks,
+        warnings,
+    };
+}
+/**
+ * Format validation result for human-readable output.
+ *
+ * @param result - Validation result
+ * @returns Formatted string
+ */
+export function formatValidationResult(result) {
+    const lines = [];
+    if (result.valid) {
+        lines.push('✓ All JSON files are valid');
+    }
+    else {
+        lines.push('✗ JSON validation failed');
+    }
+    // todo.json status
+    if (result.todoJson.exists) {
+        if (result.todoJson.valid) {
+            lines.push(`  todo.json: ${result.todoJson.count} tasks`);
+        }
+        else {
+            lines.push(`  todo.json: ERROR - ${result.todoJson.error}`);
+        }
+    }
+    else {
+        lines.push('  todo.json: not found (will be skipped)');
+    }
+    // sessions.json status
+    if (result.sessionsJson.exists) {
+        if (result.sessionsJson.valid) {
+            lines.push(`  sessions.json: ${result.sessionsJson.count} sessions`);
+        }
+        else {
+            lines.push(`  sessions.json: ERROR - ${result.sessionsJson.error}`);
+        }
+    }
+    else {
+        lines.push('  sessions.json: not found (will be skipped)');
+    }
+    // archive.json status
+    if (result.archiveJson.exists) {
+        if (result.archiveJson.valid) {
+            lines.push(`  todo-archive.json: ${result.archiveJson.count} archived tasks`);
+        }
+        else {
+            lines.push(`  todo-archive.json: ERROR - ${result.archiveJson.error}`);
+        }
+    }
+    else {
+        lines.push('  todo-archive.json: not found (will be skipped)');
+    }
+    // Warnings
+    if (result.warnings.length > 0) {
+        lines.push('\nWarnings:');
+        for (const warning of result.warnings) {
+            lines.push(`  ⚠ ${warning}`);
+        }
+    }
+    // Total
+    if (result.valid) {
+        lines.push(`\nTotal tasks to migrate: ${result.totalTasks}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Check for task count mismatch between existing database and JSON.
+ *
+ * This helps detect cases where the database has data but JSON is empty
+ * (indicating a potential configuration or path issue).
+ *
+ * @param cleoDir - Path to .cleo directory
+ * @param jsonTaskCount - Number of tasks found in JSON
+ * @returns Warning message if mismatch detected, null otherwise
+ */
+export function checkTaskCountMismatch(cleoDir, jsonTaskCount) {
+    const dbPath = join(cleoDir, 'tasks.db');
+    if (!existsSync(dbPath)) {
+        return null; // No existing DB, no mismatch possible
+    }
+    try {
+        const stats = statSync(dbPath);
+        if (stats.size === 0) {
+            return null; // Empty DB file
+        }
+        // DB exists and has content, but JSON has 0 tasks
+        if (jsonTaskCount === 0) {
+            return (`WARNING: Existing database (${stats.size} bytes) found but JSON has 0 tasks. ` +
+                `This may indicate wrong directory or missing JSON files. ` +
+                `Migration will result in data loss unless JSON files are in the correct location.`);
+        }
+    }
+    catch {
+        // Can't stat the DB, ignore
+    }
+    return null;
+}
+//# sourceMappingURL=validate.js.map