@cleocode/core 2026.4.9 → 2026.4.11

package/dist/migration/agent-outputs.js

@@ -0,0 +1,316 @@
+/**
+ * Agent-outputs directory migration utility.
+ *
+ * Single source of truth for detecting, migrating, and cleaning up
+ * legacy agent-output directories. Handles the full lineage:
+ *
+ *   1. claudedocs/research-outputs/  (oldest, pre-v0.61.0)
+ *   2. claudedocs/agent-outputs/     (intermediate, pre-v0.70.0)
+ *   3. .cleo/agent-outputs/          (canonical, v0.80.0+)
+ *
+ * NOTE: The "research-outputs" naming predates the "agent-outputs" rename
+ * (T2348). Projects that still have research-outputs/ get their content
+ * merged into .cleo/agent-outputs/ in a single unified pass with
+ * MANIFEST.jsonl path rewriting and deduplication.
+ *
+ * Used by: upgrade.ts (cleo upgrade) and init.ts (cleo init).
+ *
+ * @task T4700
+ * @epic T4454
+ */
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+// ── Constants ────────────────────────────────────────────────────────
+/** Canonical agent-outputs directory (relative to project root). */
+const CANONICAL_DIR = '.cleo/agent-outputs';
+/** Path rewrites applied to MANIFEST.jsonl entries during migration. */
+const MANIFEST_PATH_REWRITES = [
+    [/claudedocs\/research-outputs\//g, `${CANONICAL_DIR}/`],
+    [/claudedocs\/agent-outputs\//g, `${CANONICAL_DIR}/`],
+];
+// ── Detection ────────────────────────────────────────────────────────
+/**
+ * Detect legacy agent-output directories in a project.
+ *
+ * Read-only check — never modifies the filesystem.
+ *
+ * @param projectRoot - Absolute path to project root
+ * @param cleoDir - Absolute path to .cleo/ directory
+ */
+export function detectLegacyAgentOutputs(projectRoot, cleoDir) {
+    const hasResearchOutputs = existsSync(join(projectRoot, 'claudedocs', 'research-outputs'));
+    const hasLegacyAgentOutputs = existsSync(join(projectRoot, 'claudedocs', 'agent-outputs'));
+    const hasCanonical = existsSync(join(cleoDir, 'agent-outputs'));
+    const legacyPaths = [];
+    if (hasResearchOutputs)
+        legacyPaths.push('claudedocs/research-outputs/');
+    if (hasLegacyAgentOutputs)
+        legacyPaths.push('claudedocs/agent-outputs/');
+    return {
+        hasLegacy: hasResearchOutputs || hasLegacyAgentOutputs,
+        hasResearchOutputs,
+        hasLegacyAgentOutputs,
+        hasCanonical,
+        legacyPaths,
+    };
+}
+// ── Migration ────────────────────────────────────────────────────────
+/**
+ * Run the full agent-outputs migration.
+ *
+ * Copies files from all legacy locations into .cleo/agent-outputs/,
+ * merges MANIFEST.jsonl entries with path rewriting and deduplication,
+ * updates config.json, and removes legacy directories.
+ *
+ * Safe to call when no legacy directories exist (returns early).
+ * Safe to call when canonical directory already exists (merges).
+ *
+ * @param projectRoot - Absolute path to project root
+ * @param cleoDir - Absolute path to .cleo/ directory
+ */
+export function migrateAgentOutputs(projectRoot, cleoDir) {
+    const detection = detectLegacyAgentOutputs(projectRoot, cleoDir);
+    if (!detection.hasLegacy) {
+        return {
+            migrated: false,
+            filesCopied: 0,
+            manifestEntries: 0,
+            removed: [],
+            summary: 'No legacy output directories found',
+        };
+    }
+    const newDir = join(cleoDir, 'agent-outputs');
+    const hadCanonical = detection.hasCanonical;
+    mkdirSync(newDir, { recursive: true });
+    let totalCopied = 0;
+    const mergedManifestLines = [];
+    const copiedFiles = new Set();
+    // ── Phase 1: Copy files from legacy dirs (oldest first) ──────────
+    const legacySources = [
+        {
+            path: join(projectRoot, 'claudedocs', 'research-outputs'),
+            exists: detection.hasResearchOutputs,
+        },
+        {
+            path: join(projectRoot, 'claudedocs', 'agent-outputs'),
+            exists: detection.hasLegacyAgentOutputs,
+        },
+    ];
+    for (const source of legacySources) {
+        if (!source.exists)
+            continue;
+        totalCopied += copyDirContents(source.path, newDir, mergedManifestLines, copiedFiles);
+    }
+    // ── Phase 2: Merge manifests ─────────────────────────────────────
+    const manifestEntries = mergeManifests(newDir, hadCanonical, mergedManifestLines);
+    // ── Phase 3: Update config ───────────────────────────────────────
+    updateConfigPaths(cleoDir);
+    // ── Phase 4: Remove legacy directories ───────────────────────────
+    const removed = removeLegacyDirs(projectRoot, detection);
+    // ── Build summary ────────────────────────────────────────────────
+    const parts = [`Migrated ${totalCopied} files → ${CANONICAL_DIR}/`];
+    if (manifestEntries > 0)
+        parts.push(`merged ${manifestEntries} manifest entries`);
+    if (removed.length > 0)
+        parts.push(`removed: ${removed.join(', ')}`);
+    return {
+        migrated: true,
+        filesCopied: totalCopied,
+        manifestEntries,
+        removed,
+        summary: parts.join('; '),
+    };
+}
+// ── Internal helpers ─────────────────────────────────────────────────
+/**
+ * Recursively copy a source directory's contents into the target directory.
+ *
+ * - Skips MANIFEST.jsonl (collected separately for merge).
+ * - Skips files already present in copiedFiles set (newer wins).
+ * - Handles one level of subdirectories.
+ */
+function copyDirContents(srcDir, dstDir, manifestLines, copiedFiles) {
+    let count = 0;
+    const entries = readdirSync(srcDir);
+    for (const entry of entries) {
+        if (entry === 'MANIFEST.jsonl') {
+            collectManifestLines(join(srcDir, entry), manifestLines);
+            continue;
+        }
+        const srcPath = join(srcDir, entry);
+        const dstPath = join(dstDir, entry);
+        try {
+            const st = statSync(srcPath);
+            if (st.isDirectory()) {
+                mkdirSync(dstPath, { recursive: true });
+                for (const sf of readdirSync(srcPath)) {
+                    if (!copiedFiles.has(sf)) {
+                        try {
+                            copyFileSync(join(srcPath, sf), join(dstPath, sf));
+                            copiedFiles.add(sf);
+                            count++;
+                        }
+                        catch {
+                            /* skip individual file errors */
+                        }
+                    }
+                }
+            }
+            else if (!copiedFiles.has(entry)) {
+                copyFileSync(srcPath, dstPath);
+                copiedFiles.add(entry);
+                count++;
+            }
+        }
+        catch {
+            /* skip individual file errors */
+        }
+    }
+    return count;
+}
+/**
+ * Read MANIFEST.jsonl lines from a source file and rewrite paths.
+ */
+function collectManifestLines(manifestPath, out) {
+    try {
+        const content = readFileSync(manifestPath, 'utf-8');
+        for (const line of content.split('\n')) {
+            if (!line.trim())
+                continue;
+            let rewritten = line;
+            for (const [pattern, replacement] of MANIFEST_PATH_REWRITES) {
+                rewritten = rewritten.replace(pattern, replacement);
+            }
+            out.push(rewritten);
+        }
+    }
+    catch {
+        /* skip unreadable manifest */
+    }
+}
+/**
+ * Merge manifest entries: existing canonical entries take priority,
+ * legacy entries are appended with deduplication by ID.
+ *
+ * @returns Total number of entries in the merged manifest.
+ */
+function mergeManifests(newDir, hadCanonical, legacyLines) {
+    const manifestPath = join(newDir, 'MANIFEST.jsonl');
+    // Collect existing canonical entries
+    const existingLines = [];
+    if (hadCanonical && existsSync(manifestPath)) {
+        try {
+            const existing = readFileSync(manifestPath, 'utf-8');
+            for (const line of existing.split('\n')) {
+                if (line.trim())
+                    existingLines.push(line);
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    // Deduplicate: existing IDs take priority
+    const seenIds = new Set();
+    const finalLines = [];
+    for (const line of existingLines) {
+        try {
+            const p = JSON.parse(line);
+            if (p.id)
+                seenIds.add(p.id);
+        }
+        catch {
+            /* keep */
+        }
+        finalLines.push(line);
+    }
+    for (const line of legacyLines) {
+        try {
+            const p = JSON.parse(line);
+            if (p.id && seenIds.has(p.id))
+                continue;
+            if (p.id)
+                seenIds.add(p.id);
+        }
+        catch {
+            /* keep */
+        }
+        finalLines.push(line);
+    }
+    if (finalLines.length > 0) {
+        writeFileSync(manifestPath, finalLines.join('\n') + '\n');
+    }
+    return finalLines.length;
+}
+/**
+ * Update config.json to point to the canonical path and remove deprecated keys.
+ */
+function updateConfigPaths(cleoDir) {
+    const configPath = join(cleoDir, 'config.json');
+    if (!existsSync(configPath))
+        return;
+    try {
+        const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+        const currentDir = config.agentOutputs?.directory ?? config.agentOutputs ?? config.research?.outputDir;
+        if (currentDir && currentDir !== CANONICAL_DIR) {
+            if (typeof config.agentOutputs === 'object') {
+                config.agentOutputs.directory = CANONICAL_DIR;
+            }
+            else {
+                config.agentOutputs = { directory: CANONICAL_DIR };
+            }
+            // Remove deprecated research.outputDir
+            if (config.research?.outputDir) {
+                delete config.research.outputDir;
+                if (Object.keys(config.research).length === 0) {
+                    delete config.research;
+                }
+            }
+            writeFileSync(configPath, JSON.stringify(config, null, 2));
+        }
+    }
+    catch {
+        /* config update is best-effort */
+    }
+}
+/**
+ * Remove legacy directories and clean up empty claudedocs/.
+ *
+ * @returns List of removed directory paths (relative).
+ */
+function removeLegacyDirs(projectRoot, detection) {
+    const removed = [];
+    if (detection.hasResearchOutputs) {
+        try {
+            rmSync(join(projectRoot, 'claudedocs', 'research-outputs'), { recursive: true, force: true });
+            removed.push('claudedocs/research-outputs/');
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    if (detection.hasLegacyAgentOutputs) {
+        try {
+            rmSync(join(projectRoot, 'claudedocs', 'agent-outputs'), { recursive: true, force: true });
+            removed.push('claudedocs/agent-outputs/');
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    // Remove empty claudedocs/ parent
+    const claudedocsDir = join(projectRoot, 'claudedocs');
+    if (existsSync(claudedocsDir)) {
+        try {
+            if (readdirSync(claudedocsDir).length === 0) {
+                rmSync(claudedocsDir, { recursive: true, force: true });
+                removed.push('claudedocs/ (empty)');
+            }
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    return removed;
+}
+//# sourceMappingURL=agent-outputs.js.map

package/dist/migration/agent-outputs.js.map

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

package/dist/migration/checksum.js

@@ -0,0 +1,92 @@
+/**
+ * Checksum utilities for backup verification.
+ *
+ * Provides SHA-256 checksum computation and backup verification
+ * to ensure data integrity during migrations.
+ *
+ * @task T4728
+ * @epic T4454
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+const _require = createRequire(import.meta.url);
+const { DatabaseSync } = _require('node:sqlite');
+/**
+ * Compute SHA-256 checksum of a file.
+ *
+ * @param filePath - Path to the file
+ * @returns Hex-encoded SHA-256 checksum
+ * @task T4728
+ */
+export async function computeChecksum(filePath) {
+    const content = readFileSync(filePath);
+    return createHash('sha256').update(content).digest('hex');
+}
+/**
+ * Verify that a backup file matches the source file and is a valid SQLite database.
+ *
+ * Performs three checks:
+ * 1. Computes SHA-256 checksum of both files
+ * 2. Compares checksums to detect any content differences
+ * 3. Verifies the backup can be opened as a valid SQLite database
+ *
+ * @param sourcePath - Path to the source database file
+ * @param backupPath - Path to the backup file
+ * @returns VerificationResult with checksums and validity status
+ * @task T4728
+ */
+export async function verifyBackup(sourcePath, backupPath) {
+    // Compute checksums for both files
+    const sourceChecksum = await computeChecksum(sourcePath);
+    const backupChecksum = await computeChecksum(backupPath);
+    // Compare checksums - any difference means corruption or tampering
+    if (sourceChecksum !== backupChecksum) {
+        return {
+            valid: false,
+            error: `Checksum mismatch: source=${sourceChecksum}, backup=${backupChecksum}`,
+            sourceChecksum,
+            backupChecksum,
+        };
+    }
+    // Verify backup can be opened as a valid SQLite database
+    // This catches cases where the file is intact but not a valid SQLite file
+    try {
+        const db = new DatabaseSync(backupPath, { readOnly: true });
+        try {
+            db.prepare('SELECT 1').get();
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch (err) {
+        return {
+            valid: false,
+            error: `Backup is not a valid SQLite database: ${String(err)}`,
+            sourceChecksum,
+            backupChecksum,
+        };
+    }
+    // All checks passed
+    return {
+        valid: true,
+        sourceChecksum,
+        backupChecksum,
+    };
+}
+/**
+ * Quick checksum comparison without SQLite verification.
+ * Use when you only need to compare file contents.
+ *
+ * @param filePath1 - First file path
+ * @param filePath2 - Second file path
+ * @returns true if checksums match, false otherwise
+ * @task T4728
+ */
+export async function compareChecksums(filePath1, filePath2) {
+    const checksum1 = await computeChecksum(filePath1);
+    const checksum2 = await computeChecksum(filePath2);
+    return checksum1 === checksum2;
+}
+//# sourceMappingURL=checksum.js.map

package/dist/migration/checksum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checksum.js","sourceRoot":"","sources":["../../src/migration/checksum.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAChD,MAAM,EAAE,YAAY,EAAE,GAAG,QAAQ,CAAC,aAAa,CAAiC,CAAC;AAgBjF;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,QAAgB;IACpD,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACvC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,UAAkB,EAClB,UAAkB;IAElB,mCAAmC;IACnC,MAAM,cAAc,GAAG,MAAM,eAAe,CAAC,UAAU,CAAC,CAAC;IACzD,MAAM,cAAc,GAAG,MAAM,eAAe,CAAC,UAAU,CAAC,CAAC;IAEzD,mEAAmE;IACnE,IAAI,cAAc,KAAK,cAAc,EAAE,CAAC;QACtC,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,6BAA6B,cAAc,YAAY,cAAc,EAAE;YAC9E,cAAc;YACd,cAAc;SACf,CAAC;IACJ,CAAC;IAED,yDAAyD;IACzD,0EAA0E;IAC1E,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,IAAI,YAAY,CAAC,UAAU,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC;YACH,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,EAAE,CAAC;QAC/B,CAAC;gBAAS,CAAC;YACT,EAAE,CAAC,KAAK,EAAE,CAAC;QACb,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,0CAA0C,MAAM,CAAC,GAAG,CAAC,EAAE;YAC9D,cAAc;YACd,cAAc;SACf,CAAC;IACJ,CAAC;IAED,oBAAoB;IACpB,OAAO;QACL,KAAK,EAAE,IAAI;QACX,cAAc;QACd,cAAc;KACf,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,SAAiB,EAAE,SAAiB;IACzE,MAAM,SAAS,GAAG,MAAM,eAAe,CAAC,SAAS,CAAC,CAAC;IACnD,MAAM,SAAS,GAAG,MAAM,eAAe,CAAC,SAAS,CAAC,CAAC;IACnD,OAAO,SAAS,KAAK,SAAS,CAAC;AACjC,CAAC"}