@cleocode/cleo 2026.2.5

package/dist/core/upgrade.js

@@ -0,0 +1,649 @@
+/**
+ * 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