@cleocode/cleo 2026.2.5 → 2026.2.7

package/dist/core/upgrade.js

@@ -1,649 +0,0 @@
-/**
- * Core upgrade logic - unified project maintenance.
- *
- * Handles:
- *   1. Storage engine migration (JSON → SQLite)
- *   2. Schema version upgrades
- *   3. Structural repairs (checksums, missing fields)
- *   4. Global ~/.cleo data migration
- *
- * Both CLI and MCP delegate here (shared-core pattern).
- *
- * @task T4699
- * @epic T4454
- */
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, copyFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { getCleoDirAbsolute, getCleoHome, getProjectRoot } from './paths.js';
-import { checkStorageMigration } from './migration/preflight.js';
-import { MigrationLogger } from './migration/logger.js';
-import { forceCheckpointBeforeOperation } from '../store/data-safety.js';
-import { createMigrationState, updateMigrationPhase, updateMigrationProgress, addMigrationWarning, completeMigration, failMigration, } from './migration/state.js';
-/**
- * Run a full upgrade pass on the project .cleo/ directory.
- *
- * Steps:
- *   1. Pre-flight storage check (JSON → SQLite)
- *   2. If migration needed and not dry-run, run auto-migration with backup
- *   3. Schema version checks on JSON files
- *   4. Structural repairs (checksums, missing fields)
- *
- * @param options.dryRun  Preview changes without applying
- * @param options.includeGlobal  Also check global ~/.cleo
- * @param options.autoMigrate  Auto-migrate storage if needed (default: true)
- * @param options.cwd  Project directory override
- */
-export async function runUpgrade(options = {}) {
-    const isDryRun = options.dryRun ?? false;
-    const autoMigrate = options.autoMigrate ?? true;
-    const actions = [];
-    const errors = [];
-    let storageMigrationResult;
-    // ── Step 1: Pre-flight storage check ──────────────────────────────
-    let preflight;
-    try {
-        preflight = checkStorageMigration(options.cwd);
-    }
-    catch (err) {
-        actions.push({
-            action: 'storage_preflight',
-            status: 'error',
-            details: `Pre-flight check failed: ${String(err)}`,
-        });
-        return { success: false, upToDate: false, dryRun: isDryRun, actions, applied: 0, errors: [String(err)] };
-    }
-    if (preflight.migrationNeeded) {
-        if (isDryRun) {
-            actions.push({
-                action: 'storage_migration',
-                status: 'preview',
-                details: preflight.summary,
-                fix: preflight.fix ?? undefined,
-            });
-        }
-        else if (autoMigrate) {
-            // Auto-migrate with SAFE backup-first approach.
-            // CRITICAL: Never delete tasks.db without a verified backup.
-            // Previous implementation (pre-2026.2.6) had a destructive bug
-            // that unconditionally deleted tasks.db before migration, causing
-            // total data loss of 4,295 tasks. This fix follows the project's
-            // atomic operation pattern: backup → migrate to temp → validate → rename.
-            try {
-                // CRITICAL: Force checkpoint before ANY destructive operations
-                await forceCheckpointBeforeOperation('storage-migration', options.cwd);
-                const cleoDir = getCleoDirAbsolute(options.cwd);
-                // Initialize migration state tracking
-                const logger = new MigrationLogger(cleoDir);
-                await createMigrationState(cleoDir, {
-                    todoJson: { path: join(cleoDir, 'todo.json'), checksum: '' },
-                    sessionsJson: { path: join(cleoDir, 'sessions.json'), checksum: '' },
-                    archiveJson: { path: join(cleoDir, 'todo-archive.json'), checksum: '' },
-                });
-                await updateMigrationPhase(cleoDir, 'backup');
-                logger.info('init', 'start', 'Migration state initialized');
-                const dbPath = join(cleoDir, 'tasks.db');
-                const dbBackupPath = join(cleoDir, 'backups', 'safety', `tasks.db.pre-migration.${Date.now()}`);
-                const dbTempPath = join(cleoDir, 'tasks.db.migrating');
-                // Step 1: Backup existing tasks.db if it exists (NEVER delete without backup)
-                if (existsSync(dbPath)) {
-                    const backupDir = join(cleoDir, 'backups', 'safety');
-                    if (!existsSync(backupDir)) {
-                        mkdirSync(backupDir, { recursive: true });
-                    }
-                    copyFileSync(dbPath, dbBackupPath);
-                    // Verify backup is valid before proceeding
-                    const origStat = await import('node:fs').then(fs => fs.statSync(dbPath));
-                    const backupStat = await import('node:fs').then(fs => fs.statSync(dbBackupPath));
-                    if (backupStat.size !== origStat.size) {
-                        throw new Error(`Backup verification failed: original=${origStat.size} bytes, backup=${backupStat.size} bytes. ` +
-                            `Aborting migration to prevent data loss.`);
-                    }
-                }
-                // Step 2: Remove temp DB if leftover from a previous failed attempt
-                if (existsSync(dbTempPath)) {
-                    const { unlinkSync } = await import('node:fs');
-                    unlinkSync(dbTempPath);
-                }
-                // Step 3: Temporarily set engine to json so migrate-storage reads from JSON source
-                const configPath = join(cleoDir, 'config.json');
-                let configBackup = null;
-                if (existsSync(configPath)) {
-                    configBackup = readFileSync(configPath, 'utf-8');
-                    const config = JSON.parse(configBackup);
-                    if (config?.storage?.engine === 'sqlite') {
-                        config.storage.engine = 'json';
-                        writeFileSync(configPath, JSON.stringify(config, null, 2));
-                    }
-                }
-                // Step 4: Close any existing DB connection before migration
-                const { closeDb } = await import('../store/sqlite.js');
-                closeDb();
-                // Step 5: Remove existing DB so migration creates a fresh one
-                // SAFE: backup verified at Step 1
-                if (existsSync(dbPath)) {
-                    const { unlinkSync } = await import('node:fs');
-                    unlinkSync(dbPath);
-                }
-                // Step 6: Run migration (creates new tasks.db from JSON sources)
-                await updateMigrationPhase(cleoDir, 'import');
-                const { migrateJsonToSqlite } = await import('../store/migration-sqlite.js');
-                const result = await migrateJsonToSqlite(options.cwd);
-                // Update progress
-                await updateMigrationProgress(cleoDir, {
-                    tasksImported: result.tasksImported,
-                    archivedImported: result.archivedImported,
-                    sessionsImported: result.sessionsImported,
-                });
-                // Log any warnings
-                for (const warning of result.warnings) {
-                    await addMigrationWarning(cleoDir, warning);
-                    logger.warn('import', 'warning', warning);
-                }
-                // Step 7: Close db connection so config update doesn't conflict
-                closeDb();
-                // Step 8: Validate migration result before committing
-                if (result.success) {
-                    // Verify the new DB has reasonable data
-                    const totalImported = result.tasksImported + result.archivedImported;
-                    if (totalImported === 0 && existsSync(dbBackupPath)) {
-                        // Migration "succeeded" but imported nothing — likely a bug.
-                        // Restore from backup to prevent silent data loss.
-                        copyFileSync(dbBackupPath, dbPath);
-                        if (configBackup) {
-                            writeFileSync(configPath, configBackup);
-                        }
-                        actions.push({
-                            action: 'storage_migration',
-                            status: 'error',
-                            details: 'Migration imported 0 tasks despite existing data. Restored from backup.',
-                            fix: 'Run `cleo upgrade --dry-run` to diagnose, then retry.',
-                        });
-                        errors.push('Migration imported 0 tasks — restored from backup to prevent data loss');
-                    }
-                    else {
-                        // Migration successful with data — update config to sqlite
-                        let config = {};
-                        if (existsSync(configPath)) {
-                            try {
-                                config = JSON.parse(readFileSync(configPath, 'utf-8'));
-                            }
-                            catch {
-                                // Start fresh config
-                            }
-                        }
-                        if (!config.storage || typeof config.storage !== 'object') {
-                            config.storage = {};
-                        }
-                        config.storage.engine = 'sqlite';
-                        writeFileSync(configPath, JSON.stringify(config, null, 2));
-                        actions.push({
-                            action: 'storage_migration',
-                            status: 'applied',
-                            details: `Migrated to SQLite: ${result.tasksImported} tasks, `
-                                + `${result.archivedImported} archived, ${result.sessionsImported} sessions`,
-                        });
-                        storageMigrationResult = {
-                            migrated: true,
-                            tasksImported: result.tasksImported,
-                            archivedImported: result.archivedImported,
-                            sessionsImported: result.sessionsImported,
-                            warnings: result.warnings,
-                        };
-                        // Mark migration as complete
-                        await updateMigrationPhase(cleoDir, 'complete');
-                        await completeMigration(cleoDir);
-                        logger.info('complete', 'finish', 'Migration completed successfully');
-                    }
-                }
-                else {
-                    // Migration had errors — restore DB and config from backup
-                    if (existsSync(dbBackupPath)) {
-                        copyFileSync(dbBackupPath, dbPath);
-                    }
-                    if (configBackup) {
-                        writeFileSync(configPath, configBackup);
-                    }
-                    // Mark migration as failed
-                    await updateMigrationPhase(cleoDir, 'failed');
-                    for (const error of result.errors) {
-                        await addMigrationWarning(cleoDir, `ERROR: ${error}`);
-                    }
-                    await failMigration(cleoDir, result.errors.join('; '));
-                    logger.error('failed', 'error', 'Migration failed', { errors: result.errors });
-                    actions.push({
-                        action: 'storage_migration',
-                        status: 'error',
-                        details: `Migration failed: ${result.errors.join('; ')}. Restored from backup.`,
-                        fix: preflight.fix ?? undefined,
-                    });
-                    errors.push(...result.errors);
-                }
-            }
-            catch (err) {
-                // Catastrophic error — attempt to restore from backup
-                try {
-                    const cleoDir = getCleoDirAbsolute(options.cwd);
-                    const dbPath = join(cleoDir, 'tasks.db');
-                    const safetyDir = join(cleoDir, 'backups', 'safety');
-                    if (existsSync(safetyDir)) {
-                        // Find most recent pre-migration backup
-                        const backups = readdirSync(safetyDir)
-                            .filter(f => f.startsWith('tasks.db.pre-migration.'))
-                            .sort()
-                            .reverse();
-                        if (backups.length > 0 && !existsSync(dbPath)) {
-                            copyFileSync(join(safetyDir, backups[0]), dbPath);
-                        }
-                    }
-                }
-                catch {
-                    // Best-effort recovery — don't mask original error
-                }
-                actions.push({
-                    action: 'storage_migration',
-                    status: 'error',
-                    details: `Migration error: ${String(err)}`,
-                    fix: preflight.fix ?? undefined,
-                });
-                errors.push(String(err));
-            }
-        }
-        else {
-            // autoMigrate=false: just report
-            actions.push({
-                action: 'storage_migration',
-                status: 'skipped',
-                details: preflight.summary,
-                fix: preflight.fix ?? undefined,
-            });
-        }
-    }
-    else {
-        actions.push({
-            action: 'storage_preflight',
-            status: 'skipped',
-            details: preflight.summary,
-        });
-    }
-    // ── Step 2: Schema + structural repairs (JSON-based) ──────────────
-    // Only run if data is still in JSON format (not just migrated to SQLite)
-    const cleoDir = getCleoDirAbsolute(options.cwd);
-    const todoPath = join(cleoDir, 'todo.json');
-    if (existsSync(todoPath)) {
-        try {
-            const { getAccessor } = await import('../store/data-accessor.js');
-            const { computeChecksum } = await import('../store/json.js');
-            const accessor = await getAccessor(options.cwd);
-            const data = await accessor.loadTaskFile();
-            // 2a. Schema version check
-            const schemaVersion = data._meta?.schemaVersion;
-            const currentVersion = '2.10.0';
-            if (!schemaVersion) {
-                if (isDryRun) {
-                    actions.push({
-                        action: 'add_schema_version',
-                        status: 'preview',
-                        details: `Would set _meta.schemaVersion to ${currentVersion}`,
-                    });
-                }
-                else {
-                    data._meta = data._meta ?? {};
-                    data._meta.schemaVersion = currentVersion;
-                    actions.push({
-                        action: 'add_schema_version',
-                        status: 'applied',
-                        details: `Set _meta.schemaVersion to ${currentVersion}`,
-                    });
-                }
-            }
-            else if (schemaVersion !== currentVersion) {
-                actions.push({
-                    action: 'schema_version_check',
-                    status: isDryRun ? 'preview' : 'skipped',
-                    details: `Schema version ${schemaVersion} differs from current ${currentVersion}`,
-                });
-            }
-            else {
-                actions.push({
-                    action: 'schema_version_check',
-                    status: 'skipped',
-                    details: 'Schema version up to date',
-                });
-            }
-            // 2b. Checksum repair
-            const storedChecksum = data._meta?.checksum;
-            const computedCk = computeChecksum(data.tasks);
-            if (storedChecksum !== computedCk) {
-                if (isDryRun) {
-                    actions.push({
-                        action: 'fix_checksum',
-                        status: 'preview',
-                        details: `Would update checksum from ${storedChecksum ?? 'none'} to ${computedCk}`,
-                    });
-                }
-                else {
-                    data._meta.checksum = computedCk;
-                    actions.push({
-                        action: 'fix_checksum',
-                        status: 'applied',
-                        details: `Updated checksum to ${computedCk}`,
-                    });
-                }
-            }
-            // 2c. Fix done tasks missing completedAt
-            const doneMissingDate = data.tasks.filter((t) => t.status === 'done' && !t.completedAt);
-            if (doneMissingDate.length > 0) {
-                if (isDryRun) {
-                    actions.push({
-                        action: 'fix_completed_at',
-                        status: 'preview',
-                        details: `Would set completedAt for ${doneMissingDate.length} done task(s)`,
-                    });
-                }
-                else {
-                    const now = new Date().toISOString();
-                    for (const t of doneMissingDate) {
-                        t.completedAt = now;
-                    }
-                    actions.push({
-                        action: 'fix_completed_at',
-                        status: 'applied',
-                        details: `Set completedAt for ${doneMissingDate.length} done task(s)`,
-                    });
-                }
-            }
-            // 2d. Fix missing size fields
-            const missingSizes = data.tasks.filter((t) => !t.size);
-            if (missingSizes.length > 0) {
-                if (isDryRun) {
-                    actions.push({
-                        action: 'fix_missing_sizes',
-                        status: 'preview',
-                        details: `Would set size='medium' for ${missingSizes.length} task(s)`,
-                    });
-                }
-                else {
-                    for (const t of missingSizes) {
-                        t.size = 'medium';
-                    }
-                    actions.push({
-                        action: 'fix_missing_sizes',
-                        status: 'applied',
-                        details: `Set size='medium' for ${missingSizes.length} task(s)`,
-                    });
-                }
-            }
-            // Save if changes were made to JSON
-            const appliedJson = actions.filter((a) => a.status === 'applied' && !['storage_migration', 'storage_preflight'].includes(a.action));
-            if (appliedJson.length > 0 && !isDryRun) {
-                data._meta.checksum = computeChecksum(data.tasks);
-                data.lastUpdated = new Date().toISOString();
-                await accessor.saveTaskFile(data);
-            }
-        }
-        catch {
-            // JSON data may no longer be the primary store (migrated to SQLite).
-            // This is expected after migration; not an error.
-        }
-    }
-    // ── Step 3: Global ~/.cleo check ──────────────────────────────────
-    if (options.includeGlobal) {
-        try {
-            const globalDir = getCleoHome();
-            const globalPreflight = checkStorageMigration(join(globalDir, '..'));
-            if (globalPreflight.migrationNeeded) {
-                actions.push({
-                    action: 'global_storage_check',
-                    status: isDryRun ? 'preview' : 'skipped',
-                    details: `Global (~/.cleo): ${globalPreflight.summary}`,
-                    fix: globalPreflight.fix ?? undefined,
-                });
-            }
-            else {
-                actions.push({
-                    action: 'global_storage_check',
-                    status: 'skipped',
-                    details: `Global (~/.cleo): ${globalPreflight.summary}`,
-                });
-            }
-        }
-        catch {
-            // Global check is best-effort
-        }
-    }
-    // ── Step 4: Gitignore integrity repair ───────────────────────────
-    try {
-        const gitignorePath = join(cleoDir, '.gitignore');
-        let templateContent = null;
-        // Try loading template
-        try {
-            const { getGitignoreTemplate } = await import('../cli/commands/init.js');
-            templateContent = getGitignoreTemplate();
-        }
-        catch {
-            // Template loading not available
-        }
-        if (templateContent) {
-            const normalizeContent = (s) => s.trim().replace(/\r\n/g, '\n');
-            if (!existsSync(gitignorePath)) {
-                if (isDryRun) {
-                    actions.push({
-                        action: 'gitignore_integrity',
-                        status: 'preview',
-                        details: 'Would create .cleo/.gitignore from template',
-                    });
-                }
-                else {
-                    writeFileSync(gitignorePath, templateContent);
-                    actions.push({
-                        action: 'gitignore_integrity',
-                        status: 'applied',
-                        details: 'Created .cleo/.gitignore from template',
-                    });
-                }
-            }
-            else {
-                const installedContent = readFileSync(gitignorePath, 'utf-8');
-                if (normalizeContent(installedContent) !== normalizeContent(templateContent)) {
-                    if (isDryRun) {
-                        actions.push({
-                            action: 'gitignore_integrity',
-                            status: 'preview',
-                            details: 'Would update .cleo/.gitignore to match template',
-                        });
-                    }
-                    else {
-                        writeFileSync(gitignorePath, templateContent);
-                        actions.push({
-                            action: 'gitignore_integrity',
-                            status: 'applied',
-                            details: 'Updated .cleo/.gitignore to match template',
-                        });
-                    }
-                }
-                else {
-                    actions.push({
-                        action: 'gitignore_integrity',
-                        status: 'skipped',
-                        details: '.cleo/.gitignore matches template',
-                    });
-                }
-            }
-        }
-    }
-    catch {
-        // Gitignore repair is best-effort
-    }
-    // ── Step 5: Agent-outputs migration ─────────────────────────────
-    try {
-        const projectRoot = getProjectRoot(options.cwd);
-        const legacyDir = join(projectRoot, 'claudedocs', 'agent-outputs');
-        const newDir = join(cleoDir, 'agent-outputs');
-        if (existsSync(legacyDir)) {
-            if (existsSync(newDir)) {
-                // Both exist — warn, do not overwrite
-                actions.push({
-                    action: 'agent_outputs_migration',
-                    status: 'skipped',
-                    details: 'Both claudedocs/agent-outputs/ and .cleo/agent-outputs/ exist. Manual cleanup needed.',
-                });
-            }
-            else {
-                if (isDryRun) {
-                    actions.push({
-                        action: 'agent_outputs_migration',
-                        status: 'preview',
-                        details: 'Would copy claudedocs/agent-outputs/ to .cleo/agent-outputs/',
-                    });
-                }
-                else {
-                    // Copy all files from old to new
-                    mkdirSync(newDir, { recursive: true });
-                    const files = readdirSync(legacyDir);
-                    for (const file of files) {
-                        const srcPath = join(legacyDir, file);
-                        const dstPath = join(newDir, file);
-                        try {
-                            copyFileSync(srcPath, dstPath);
-                        }
-                        catch {
-                            // Skip files that can't be copied (e.g., directories)
-                            try {
-                                // If it's a directory, mkdir and copy contents
-                                const stat = (await import('node:fs')).statSync(srcPath);
-                                if (stat.isDirectory()) {
-                                    mkdirSync(dstPath, { recursive: true });
-                                    const subFiles = readdirSync(srcPath);
-                                    for (const sf of subFiles) {
-                                        try {
-                                            copyFileSync(join(srcPath, sf), join(dstPath, sf));
-                                        }
-                                        catch { /* skip */ }
-                                    }
-                                }
-                            }
-                            catch { /* skip */ }
-                        }
-                    }
-                    // Update config if it still points to legacy path
-                    const configPath = join(cleoDir, 'config.json');
-                    if (existsSync(configPath)) {
-                        try {
-                            const config = JSON.parse(readFileSync(configPath, 'utf-8'));
-                            const currentDir = config.agentOutputs?.directory ?? config.agentOutputs;
-                            if (currentDir === 'claudedocs/agent-outputs') {
-                                if (typeof config.agentOutputs === 'object') {
-                                    config.agentOutputs.directory = '.cleo/agent-outputs';
-                                }
-                                else {
-                                    config.agentOutputs = { directory: '.cleo/agent-outputs' };
-                                }
-                                writeFileSync(configPath, JSON.stringify(config, null, 2));
-                            }
-                        }
-                        catch { /* config update is best-effort */ }
-                    }
-                    actions.push({
-                        action: 'agent_outputs_migration',
-                        status: 'applied',
-                        details: `Copied ${files.length} items from claudedocs/agent-outputs/ to .cleo/agent-outputs/`,
-                    });
-                }
-            }
-        }
-        else {
-            actions.push({
-                action: 'agent_outputs_migration',
-                status: 'skipped',
-                details: 'No legacy claudedocs/agent-outputs/ directory found',
-            });
-        }
-    }
-    catch {
-        // Agent outputs migration is best-effort
-    }
-    // ── Step 6: Project context re-detection ────────────────────────
-    try {
-        const projectRoot = getProjectRoot(options.cwd);
-        const contextPath = join(cleoDir, 'project-context.json');
-        if (!existsSync(contextPath)) {
-            if (isDryRun) {
-                actions.push({
-                    action: 'project_context_detection',
-                    status: 'preview',
-                    details: 'Would detect and create project-context.json',
-                });
-            }
-            else {
-                try {
-                    const { detectProjectType } = await import('../store/project-detect.js');
-                    const info = detectProjectType(projectRoot);
-                    const context = {
-                        ...info,
-                        detectedAt: new Date().toISOString(),
-                    };
-                    writeFileSync(contextPath, JSON.stringify(context, null, 2));
-                    actions.push({
-                        action: 'project_context_detection',
-                        status: 'applied',
-                        details: `Detected project type: ${info.type} (${info.testFramework})`,
-                    });
-                }
-                catch (err) {
-                    actions.push({
-                        action: 'project_context_detection',
-                        status: 'error',
-                        details: `Project detection failed: ${String(err)}`,
-                    });
-                }
-            }
-        }
-        else {
-            // Check if stale (older than 30 days)
-            try {
-                const context = JSON.parse(readFileSync(contextPath, 'utf-8'));
-                if (context.detectedAt) {
-                    const detectedDate = new Date(context.detectedAt);
-                    const daysSinceDetection = (Date.now() - detectedDate.getTime()) / (1000 * 60 * 60 * 24);
-                    if (daysSinceDetection > 30) {
-                        actions.push({
-                            action: 'project_context_detection',
-                            status: 'skipped',
-                            details: `project-context.json is ${Math.round(daysSinceDetection)} days old. Consider re-running 'cleo init --detect'.`,
-                        });
-                    }
-                    else {
-                        actions.push({
-                            action: 'project_context_detection',
-                            status: 'skipped',
-                            details: 'project-context.json is up to date',
-                        });
-                    }
-                }
-            }
-            catch {
-                actions.push({
-                    action: 'project_context_detection',
-                    status: 'skipped',
-                    details: 'project-context.json exists',
-                });
-            }
-        }
-    }
-    catch {
-        // Project context detection is best-effort
-    }
-    const applied = actions.filter((a) => a.status === 'applied');
-    const hasErrors = errors.length > 0 || actions.some((a) => a.status === 'error');
-    const upToDate = !actions.some((a) => a.status === 'applied' || a.status === 'preview');
-    return {
-        success: !hasErrors,
-        upToDate,
-        dryRun: isDryRun,
-        actions,
-        applied: applied.length,
-        errors,
-        storageMigration: storageMigrationResult,
-    };
-}
-//# sourceMappingURL=upgrade.js.map