@cleocode/cleo 2026.2.5

package/dist/store/atomic.js

@@ -0,0 +1,167 @@
+/**
+ * Atomic file write operations using write-file-atomic.
+ * Ensures writes are crash-safe: temp file -> validate -> rename.
+ * @epic T4454
+ * @task T4457
+ * @task T4721 - Added atomic database operations
+ */
+import writeFileAtomic from 'write-file-atomic';
+import { readFile, mkdir, rename, unlink } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { CleoError } from '../core/errors.js';
+import { ExitCode } from '../types/exit-codes.js';
+/**
+ * Write data to a file atomically.
+ * Creates parent directories if they don't exist.
+ * Uses write-file-atomic for crash-safe writes (temp file -> rename).
+ */
+export async function atomicWrite(filePath, data, options) {
+    try {
+        await mkdir(dirname(filePath), { recursive: true });
+        await writeFileAtomic(filePath, data, {
+            encoding: options?.encoding ?? 'utf8',
+            mode: options?.mode,
+        });
+    }
+    catch (err) {
+        throw new CleoError(ExitCode.FILE_ERROR, `Atomic write failed: ${filePath}`, { cause: err });
+    }
+}
+/**
+ * Read a file and return its contents.
+ * Returns null if the file does not exist.
+ */
+export async function safeReadFile(filePath) {
+    try {
+        return await readFile(filePath, 'utf8');
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+            return null;
+        }
+        throw new CleoError(ExitCode.FILE_ERROR, `Failed to read: ${filePath}`, { cause: err });
+    }
+}
+/**
+ * Write JSON data atomically with consistent formatting.
+ */
+export async function atomicWriteJson(filePath, data, options) {
+    const json = JSON.stringify(data, null, options?.indent ?? 2) + '\n';
+    await atomicWrite(filePath, json);
+}
+/**
+ * Perform atomic database migration using rename operations.
+ *
+ * Pattern:
+ *   1. Write new database to temp file (tasks.db.new)
+ *   2. Validate temp database integrity
+ *   3. Rename existing tasks.db → tasks.db.backup
+ *   4. Rename temp → tasks.db (atomic)
+ *   5. Only delete backup on success
+ *
+ * @param dbPath - Path to the database file (e.g., tasks.db)
+ * @param tempPath - Path to temporary database (e.g., tasks.db.new)
+ * @param validateFn - Async function to validate the temp database
+ * @returns Result with paths and success status
+ */
+export async function atomicDatabaseMigration(dbPath, tempPath, validateFn) {
+    const backupPath = `${dbPath}.backup`;
+    try {
+        // Step 1: Validate temp database exists
+        if (!existsSync(tempPath)) {
+            throw new Error(`Temp database not found: ${tempPath}`);
+        }
+        // Step 2: Validate the temp database integrity
+        const isValid = await validateFn(tempPath);
+        if (!isValid) {
+            throw new Error(`Temp database validation failed: ${tempPath}`);
+        }
+        // Step 3: If existing database exists, rename to backup
+        if (existsSync(dbPath)) {
+            await rename(dbPath, backupPath);
+        }
+        // Step 4: Atomically rename temp to final (atomic on POSIX systems)
+        await rename(tempPath, dbPath);
+        return {
+            success: true,
+            tempPath,
+            backupPath: existsSync(backupPath) ? backupPath : undefined,
+        };
+    }
+    catch (err) {
+        return {
+            success: false,
+            tempPath,
+            backupPath: existsSync(backupPath) ? backupPath : undefined,
+            error: String(err),
+        };
+    }
+}
+/**
+ * Restore database from backup after failed migration.
+ *
+ * @param dbPath - Path to the database file
+ * @param backupPath - Path to the backup file
+ * @returns true if restore succeeded
+ */
+export async function restoreDatabaseFromBackup(dbPath, backupPath) {
+    try {
+        if (!existsSync(backupPath)) {
+            return false;
+        }
+        // If a partial database exists, remove it
+        if (existsSync(dbPath)) {
+            await unlink(dbPath);
+        }
+        // Restore from backup
+        await rename(backupPath, dbPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Clean up migration artifacts after successful migration.
+ *
+ * @param backupPath - Path to backup file to delete
+ * @returns true if cleanup succeeded
+ */
+export async function cleanupMigrationArtifacts(backupPath) {
+    try {
+        if (existsSync(backupPath)) {
+            await unlink(backupPath);
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validate SQLite database integrity by attempting to open it.
+ *
+ * @param dbPath - Path to database file
+ * @returns true if database is valid
+ */
+export async function validateSqliteDatabase(dbPath) {
+    try {
+        const initSqlJs = (await import('sql.js')).default;
+        const { readFileSync } = await import('node:fs');
+        const SQL = await initSqlJs();
+        const buffer = readFileSync(dbPath);
+        const db = new SQL.Database(buffer);
+        // Try to run a simple query to verify integrity
+        db.run('PRAGMA integrity_check;');
+        // Check for basic tables
+        const result = db.exec("SELECT name FROM sqlite_master WHERE type='table' AND name='tasks';");
+        const hasTasksTable = result.length > 0 && result[0].values.length > 0;
+        db.close();
+        return hasTasksTable;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=atomic.js.map

package/dist/store/atomic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic.js","sourceRoot":"","sources":["../../src/store/atomic.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,eAAe,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAElD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,QAAgB,EAChB,IAAY,EACZ,OAAsD;IAEtD,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACpD,MAAM,eAAe,CAAC,QAAQ,EAAE,IAAI,EAAE;YACpC,QAAQ,EAAE,OAAO,EAAE,QAAQ,IAAI,MAAM;YACrC,IAAI,EAAE,OAAO,EAAE,IAAI;SACpB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,SAAS,CACjB,QAAQ,CAAC,UAAU,EACnB,wBAAwB,QAAQ,EAAE,EAClC,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,QAAgB;IACjD,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,IAAI,GAAG,YAAY,KAAK,IAAI,MAAM,IAAI,GAAG,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC9F,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,IAAI,SAAS,CACjB,QAAQ,CAAC,UAAU,EACnB,mBAAmB,QAAQ,EAAE,EAC7B,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,QAAgB,EAChB,IAAa,EACb,OAA6B;IAE7B,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;IACrE,MAAM,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;AACpC,CAAC;AAYD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,MAAc,EACd,QAAgB,EAChB,UAA8C;IAE9C,MAAM,UAAU,GAAG,GAAG,MAAM,SAAS,CAAC;IAEtC,IAAI,CAAC;QACH,wCAAwC;QACxC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,4BAA4B,QAAQ,EAAE,CAAC,CAAC;QAC1D,CAAC;QAED,+CAA+C;QAC/C,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,CAAC;QAC3C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,oCAAoC,QAAQ,EAAE,CAAC,CAAC;QAClE,CAAC;QAED,wDAAwD;QACxD,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACvB,MAAM,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;QACnC,CAAC;QAED,oEAAoE;QACpE,MAAM,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAE/B,OAAO;YACL,OAAO,EAAE,IAAI;YACb,QAAQ;YACR,UAAU,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;SAC5D,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,OAAO,EAAE,KAAK;YACd,QAAQ;YACR,UAAU,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;YAC3D,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC;SACnB,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,MAAc,EACd,UAAkB;IAElB,IAAI,CAAC;QACH,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAC5B,OAAO,KAAK,CAAC;QACf,CAAC;QAED,0CAA0C;QAC1C,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACvB,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;QACvB,CAAC;QAED,sBAAsB;QACtB,MAAM,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,UAAkB;IAChE,IAAI,CAAC;QACH,IAAI,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAC3B,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;QAC3B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,MAAc;IACzD,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,CAAC,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC;QACnD,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;QAEjD,MAAM,GAAG,GAAG,MAAM,SAAS,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QACpC,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAEpC,gDAAgD;QAChD,EAAE,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;QAElC,yBAAyB;QACzB,MAAM,MAAM,GAAG,EAAE,CAAC,IAAI,CAAC,qEAAqE,CAAC,CAAC;QAC9F,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;QAEvE,EAAE,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,aAAa,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/store/backup.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Numbered backup system for CLEO data files.
+ * Maintains a rotating window of recent backups for rollback protection.
+ * @epic T4454
+ * @task T4457
+ */
+/**
+ * Create a numbered backup of a file.
+ * Rotates existing backups (file.1 -> file.2, etc.) and removes excess.
+ */
+export declare function createBackup(filePath: string, backupDir: string, maxBackups?: number): Promise<string>;
+/**
+ * List existing backups for a file, sorted by number (newest first).
+ */
+export declare function listBackups(fileName: string, backupDir: string): Promise<string[]>;
+/**
+ * Restore a file from its most recent backup.
+ * Returns the path of the backup that was restored.
+ */
+export declare function restoreFromBackup(fileName: string, backupDir: string, targetPath: string): Promise<string>;
+//# sourceMappingURL=backup.d.ts.map

package/dist/store/backup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.d.ts","sourceRoot":"","sources":["../../src/store/backup.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH;;;GAGG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,GAAE,MAA4B,GACvC,OAAO,CAAC,MAAM,CAAC,CAiDjB;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,EAAE,CAAC,CAenB;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAWjB"}

package/dist/store/backup.js

@@ -0,0 +1,94 @@
+/**
+ * Numbered backup system for CLEO data files.
+ * Maintains a rotating window of recent backups for rollback protection.
+ * @epic T4454
+ * @task T4457
+ */
+import { copyFile, rename as fsRename, readdir, unlink, stat, mkdir } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+import { CleoError } from '../core/errors.js';
+import { ExitCode } from '../types/exit-codes.js';
+const DEFAULT_MAX_BACKUPS = 5;
+/**
+ * Create a numbered backup of a file.
+ * Rotates existing backups (file.1 -> file.2, etc.) and removes excess.
+ */
+export async function createBackup(filePath, backupDir, maxBackups = DEFAULT_MAX_BACKUPS) {
+    try {
+        await mkdir(backupDir, { recursive: true });
+        const fileName = basename(filePath);
+        // Check if source file exists
+        try {
+            await stat(filePath);
+        }
+        catch {
+            throw new CleoError(ExitCode.FILE_ERROR, `Cannot backup: source file not found: ${filePath}`);
+        }
+        // Rotate existing backups (shift numbers up)
+        for (let i = maxBackups; i >= 1; i--) {
+            const current = join(backupDir, `${fileName}.${i}`);
+            if (i === maxBackups) {
+                // Remove oldest backup
+                try {
+                    await unlink(current);
+                }
+                catch {
+                    // File may not exist
+                }
+            }
+            else {
+                const next = join(backupDir, `${fileName}.${i + 1}`);
+                try {
+                    await stat(current);
+                    await fsRename(current, next);
+                }
+                catch {
+                    // File may not exist
+                }
+            }
+        }
+        // Create new backup as .1
+        const backupPath = join(backupDir, `${fileName}.1`);
+        await copyFile(filePath, backupPath);
+        return backupPath;
+    }
+    catch (err) {
+        if (err instanceof CleoError)
+            throw err;
+        throw new CleoError(ExitCode.FILE_ERROR, `Backup failed for: ${filePath}`, { cause: err });
+    }
+}
+/**
+ * List existing backups for a file, sorted by number (newest first).
+ */
+export async function listBackups(fileName, backupDir) {
+    try {
+        const entries = await readdir(backupDir);
+        const prefix = `${fileName}.`;
+        return entries
+            .filter((e) => e.startsWith(prefix) && /^\d+$/.test(e.slice(prefix.length)))
+            .sort((a, b) => {
+            const numA = parseInt(a.slice(prefix.length), 10);
+            const numB = parseInt(b.slice(prefix.length), 10);
+            return numA - numB;
+        })
+            .map((e) => join(backupDir, e));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Restore a file from its most recent backup.
+ * Returns the path of the backup that was restored.
+ */
+export async function restoreFromBackup(fileName, backupDir, targetPath) {
+    const backups = await listBackups(fileName, backupDir);
+    if (backups.length === 0) {
+        throw new CleoError(ExitCode.NOT_FOUND, `No backups found for: ${fileName}`);
+    }
+    const newest = backups[0];
+    await copyFile(newest, targetPath);
+    return newest;
+}
+//# sourceMappingURL=backup.js.map

package/dist/store/backup.js.map

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

package/dist/store/cache.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Index caching for O(1) label/phase/hierarchy lookups.
+ * Ported from lib/data/cache.sh
+ *
+ * @epic T4454
+ * @task T4530
+ */
+import type { Task } from '../types/task.js';
+/** Cache index mapping labels/phases to task IDs. */
+export type IndexMap = Map<string, string[]>;
+/**
+ * In-memory cache for task indices with checksum-based staleness detection.
+ */
+export declare class TaskCache {
+    private labelIndex;
+    private phaseIndex;
+    private parentIndex;
+    private childrenIndex;
+    private depthIndex;
+    private checksum;
+    private initialized;
+    /**
+     * Compute a checksum from task data for staleness detection.
+     */
+    private computeChecksum;
+    /**
+     * Initialize or rebuild cache from tasks.
+     * Returns true if cache was rebuilt, false if already valid.
+     */
+    init(tasks: Task[]): boolean;
+    private buildLabelIndex;
+    private buildPhaseIndex;
+    private buildHierarchyIndex;
+    /** Get task IDs by label. */
+    getTasksByLabel(label: string): string[];
+    /** Get task IDs by phase. */
+    getTasksByPhase(phase: string): string[];
+    /** Get all labels. */
+    getAllLabels(): string[];
+    /** Get all phases. */
+    getAllPhases(): string[];
+    /** Get label count for a specific label. */
+    getLabelCount(label: string): number;
+    /** Get parent ID for a task. */
+    getParent(taskId: string): string | null;
+    /** Get children IDs for a task. */
+    getChildren(taskId: string): string[];
+    /** Get depth for a task. */
+    getDepth(taskId: string): number;
+    /** Get child count. */
+    getChildCount(taskId: string): number;
+    /** Get root tasks (no parent). */
+    getRootTasks(): string[];
+    /** Get leaf tasks (no children). */
+    getLeafTasks(): string[];
+    /** Force invalidation and rebuild. */
+    invalidate(): void;
+    /** Get cache statistics. */
+    getStats(): {
+        initialized: boolean;
+        labelCount: number;
+        phaseCount: number;
+        taskCount: number;
+        maxDepth: number;
+    };
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/store/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/store/cache.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C,qDAAqD;AACrD,MAAM,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AAE7C;;GAEG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,aAAa,CAA+B;IACpD,OAAO,CAAC,UAAU,CAA6B;IAC/C,OAAO,CAAC,QAAQ,CAAM;IACtB,OAAO,CAAC,WAAW,CAAS;IAE5B;;OAEG;IACH,OAAO,CAAC,eAAe;IAOvB;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO;IAc5B,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,mBAAmB;IAgC3B,6BAA6B;IAC7B,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE;IAIxC,6BAA6B;IAC7B,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE;IAIxC,sBAAsB;IACtB,YAAY,IAAI,MAAM,EAAE;IAIxB,sBAAsB;IACtB,YAAY,IAAI,MAAM,EAAE;IAIxB,4CAA4C;IAC5C,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAIpC,gCAAgC;IAChC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIxC,mCAAmC;IACnC,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAIrC,4BAA4B;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAIhC,uBAAuB;IACvB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAIrC,kCAAkC;IAClC,YAAY,IAAI,MAAM,EAAE;IAMxB,oCAAoC;IACpC,YAAY,IAAI,MAAM,EAAE;IAKxB,sCAAsC;IACtC,UAAU,IAAI,IAAI;IAUlB,4BAA4B;IAC5B,QAAQ,IAAI;QACV,WAAW,EAAE,OAAO,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;KAClB;CAaF"}

package/dist/store/cache.js

@@ -0,0 +1,168 @@
+/**
+ * Index caching for O(1) label/phase/hierarchy lookups.
+ * Ported from lib/data/cache.sh
+ *
+ * @epic T4454
+ * @task T4530
+ */
+/**
+ * In-memory cache for task indices with checksum-based staleness detection.
+ */
+export class TaskCache {
+    labelIndex = new Map();
+    phaseIndex = new Map();
+    parentIndex = new Map();
+    childrenIndex = new Map();
+    depthIndex = new Map();
+    checksum = '';
+    initialized = false;
+    /**
+     * Compute a checksum from task data for staleness detection.
+     */
+    computeChecksum(tasks) {
+        return tasks
+            .map((t) => `${t.id}:${t.status}:${t.parentId ?? ''}:${t.phase ?? ''}:${(t.labels ?? []).join(',')}`)
+            .sort()
+            .join('|');
+    }
+    /**
+     * Initialize or rebuild cache from tasks.
+     * Returns true if cache was rebuilt, false if already valid.
+     */
+    init(tasks) {
+        const newChecksum = this.computeChecksum(tasks);
+        if (this.initialized && newChecksum === this.checksum) {
+            return false;
+        }
+        this.buildLabelIndex(tasks);
+        this.buildPhaseIndex(tasks);
+        this.buildHierarchyIndex(tasks);
+        this.checksum = newChecksum;
+        this.initialized = true;
+        return true;
+    }
+    buildLabelIndex(tasks) {
+        this.labelIndex.clear();
+        for (const task of tasks) {
+            if (!task.labels?.length)
+                continue;
+            for (const label of task.labels) {
+                const existing = this.labelIndex.get(label) ?? [];
+                existing.push(task.id);
+                this.labelIndex.set(label, existing);
+            }
+        }
+    }
+    buildPhaseIndex(tasks) {
+        this.phaseIndex.clear();
+        for (const task of tasks) {
+            if (!task.phase)
+                continue;
+            const existing = this.phaseIndex.get(task.phase) ?? [];
+            existing.push(task.id);
+            this.phaseIndex.set(task.phase, existing);
+        }
+    }
+    buildHierarchyIndex(tasks) {
+        this.parentIndex.clear();
+        this.childrenIndex.clear();
+        this.depthIndex.clear();
+        const taskMap = new Map(tasks.map((t) => [t.id, t]));
+        for (const task of tasks) {
+            this.parentIndex.set(task.id, task.parentId ?? null);
+            if (task.parentId) {
+                const siblings = this.childrenIndex.get(task.parentId) ?? [];
+                siblings.push(task.id);
+                this.childrenIndex.set(task.parentId, siblings);
+            }
+        }
+        // Compute depths
+        for (const task of tasks) {
+            let depth = 0;
+            let current = task;
+            const visited = new Set();
+            while (current.parentId && !visited.has(current.parentId)) {
+                visited.add(current.parentId);
+                const parent = taskMap.get(current.parentId);
+                if (!parent)
+                    break;
+                depth++;
+                current = parent;
+            }
+            this.depthIndex.set(task.id, depth);
+        }
+    }
+    /** Get task IDs by label. */
+    getTasksByLabel(label) {
+        return this.labelIndex.get(label) ?? [];
+    }
+    /** Get task IDs by phase. */
+    getTasksByPhase(phase) {
+        return this.phaseIndex.get(phase) ?? [];
+    }
+    /** Get all labels. */
+    getAllLabels() {
+        return [...this.labelIndex.keys()];
+    }
+    /** Get all phases. */
+    getAllPhases() {
+        return [...this.phaseIndex.keys()];
+    }
+    /** Get label count for a specific label. */
+    getLabelCount(label) {
+        return this.getTasksByLabel(label).length;
+    }
+    /** Get parent ID for a task. */
+    getParent(taskId) {
+        return this.parentIndex.get(taskId) ?? null;
+    }
+    /** Get children IDs for a task. */
+    getChildren(taskId) {
+        return this.childrenIndex.get(taskId) ?? [];
+    }
+    /** Get depth for a task. */
+    getDepth(taskId) {
+        return this.depthIndex.get(taskId) ?? 0;
+    }
+    /** Get child count. */
+    getChildCount(taskId) {
+        return this.getChildren(taskId).length;
+    }
+    /** Get root tasks (no parent). */
+    getRootTasks() {
+        return [...this.parentIndex.entries()]
+            .filter(([, parent]) => parent === null)
+            .map(([id]) => id);
+    }
+    /** Get leaf tasks (no children). */
+    getLeafTasks() {
+        const parentSet = new Set(this.childrenIndex.keys());
+        return [...this.parentIndex.keys()].filter((id) => !parentSet.has(id) || this.getChildCount(id) === 0);
+    }
+    /** Force invalidation and rebuild. */
+    invalidate() {
+        this.labelIndex.clear();
+        this.phaseIndex.clear();
+        this.parentIndex.clear();
+        this.childrenIndex.clear();
+        this.depthIndex.clear();
+        this.checksum = '';
+        this.initialized = false;
+    }
+    /** Get cache statistics. */
+    getStats() {
+        let maxDepth = 0;
+        for (const d of this.depthIndex.values()) {
+            if (d > maxDepth)
+                maxDepth = d;
+        }
+        return {
+            initialized: this.initialized,
+            labelCount: this.labelIndex.size,
+            phaseCount: this.phaseIndex.size,
+            taskCount: this.parentIndex.size,
+            maxDepth,
+        };
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/store/cache.js.map

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

package/dist/store/data-accessor.d.ts

@@ -0,0 +1,77 @@
+/**
+ * DataAccessor: File-level storage abstraction for core modules.
+ *
+ * Core modules operate on whole-file data structures (TaskFile, ArchiveFile, SessionsFile).
+ * The DataAccessor abstracts WHERE that data is stored (JSON files vs SQLite)
+ * while preserving the read-modify-write pattern that core business logic relies on.
+ *
+ * This is the DRY/SOLID injection point: core modules accept a DataAccessor parameter
+ * instead of calling readJson/saveJson directly.
+ *
+ * Two implementations:
+ * - JsonDataAccessor: reads/writes .cleo/*.json files (current behavior)
+ * - SqliteDataAccessor: materializes/dematerializes from SQLite tables
+ *
+ * @epic T4454
+ */
+import type { TaskFile } from '../types/task.js';
+import type { Session } from '../types/session.js';
+/** Archive file structure. */
+export interface ArchiveFile {
+    archivedTasks: Array<import('../types/task.js').Task>;
+    version?: string;
+}
+/** Sessions file structure. Must match types/session.ts SessionsFile. */
+export interface SessionsFile {
+    sessions: Session[];
+    version: string;
+    _meta: {
+        schemaVersion: string;
+        lastUpdated: string;
+    };
+}
+/**
+ * DataAccessor interface.
+ *
+ * Core modules call these methods instead of readJson/saveJson.
+ * Each method maps directly to the file-level operations that
+ * core modules already perform.
+ */
+export interface DataAccessor {
+    /** The storage engine backing this accessor. */
+    readonly engine: 'json' | 'sqlite' | 'dual';
+    /** Load the full TaskFile (tasks + project meta + work state). */
+    loadTaskFile(): Promise<TaskFile>;
+    /** Save the full TaskFile atomically. Creates backup before write. */
+    saveTaskFile(data: TaskFile): Promise<void>;
+    /** @deprecated Use loadTaskFile() instead. */
+    loadTodoFile(): Promise<TaskFile>;
+    /** @deprecated Use saveTaskFile() instead. */
+    saveTodoFile(data: TaskFile): Promise<void>;
+    /** Load the archive file. Returns null if archive doesn't exist. */
+    loadArchive(): Promise<ArchiveFile | null>;
+    /** Save the archive file atomically. Creates backup before write. */
+    saveArchive(data: ArchiveFile): Promise<void>;
+    /** Load the sessions file. Returns empty sessions array if file doesn't exist. */
+    loadSessions(): Promise<SessionsFile>;
+    /** Save the sessions file atomically. */
+    saveSessions(data: SessionsFile): Promise<void>;
+    /** Append an entry to the audit log. */
+    appendLog(entry: Record<string, unknown>): Promise<void>;
+    /** Release any resources (close DB connections, etc.). */
+    close(): Promise<void>;
+}
+/**
+ * Create a DataAccessor for the given working directory.
+ * Auto-detects engine from .cleo/config.json (storage.engine field).
+ *
+ * ALL accessors returned are safety-enabled by default via SafetyDataAccessor wrapper.
+ * Use CLEO_DISABLE_SAFETY=true to bypass (emergency only).
+ *
+ * @param engine - Force a specific engine, or undefined for auto-detect
+ * @param cwd - Working directory (defaults to process.cwd())
+ */
+export declare function createDataAccessor(engine?: 'json' | 'sqlite' | 'dual', cwd?: string): Promise<DataAccessor>;
+/** Convenience: get a DataAccessor with auto-detected engine. */
+export declare function getAccessor(cwd?: string): Promise<DataAccessor>;
+//# sourceMappingURL=data-accessor.d.ts.map

package/dist/store/data-accessor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-accessor.d.ts","sourceRoot":"","sources":["../../src/store/data-accessor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD,8BAA8B;AAC9B,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,KAAK,CAAC,OAAO,kBAAkB,EAAE,IAAI,CAAC,CAAC;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QACL,aAAa,EAAE,MAAM,CAAC;QACtB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;IAI5C,kEAAkE;IAClE,YAAY,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC;IAElC,sEAAsE;IACtE,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5C,8CAA8C;IAC9C,YAAY,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC;IAElC,8CAA8C;IAC9C,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAI5C,oEAAoE;IACpE,WAAW,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAE3C,qEAAqE;IACrE,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAI9C,kFAAkF;IAClF,YAAY,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;IAEtC,yCAAyC;IACzC,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAIhD,wCAAwC;IACxC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAIzD,0DAA0D;IAC1D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,EACnC,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,YAAY,CAAC,CAgCvB;AAED,iEAAiE;AACjE,wBAAsB,WAAW,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAErE"}