@cleocode/core 2026.4.7 → 2026.4.11

package/dist/store/sqlite-backup.js

@@ -0,0 +1,241 @@
+/**
+ * SQLite backup via VACUUM INTO with snapshot rotation.
+ *
+ * Produces self-contained, WAL-free copies of CLEO SQLite databases
+ * (tasks.db and brain.db) into `.cleo/backups/sqlite/` with a configurable
+ * rotation limit. All errors are swallowed — backup failure must never
+ * interrupt normal operation.
+ *
+ * @task T4873
+ * @task T5158 — extended to cover brain.db
+ * @epic T4867
+ */
+import { existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { getCleoDir } from '../paths.js';
+import { getBrainNativeDb } from './brain-sqlite.js';
+import { getNativeDb } from './sqlite.js';
+/** Maximum number of snapshots retained per database (oldest rotated out). */
+const MAX_SNAPSHOTS = 10;
+/** Debounce window (ms) during which duplicate snapshot requests are suppressed. */
+const DEBOUNCE_MS = 30_000; // 30 seconds
+/**
+ * Per-database snapshot book-keeping: last snapshot timestamp (epoch ms)
+ * keyed by the canonical snapshot prefix (e.g. `"tasks"` / `"brain"`).
+ */
+const _lastBackupEpoch = {};
+/**
+ * Canonical list of snapshot targets. Ordering is insertion order — tasks.db
+ * snapshots first (highest-value operational state), then brain.db.
+ */
+const SNAPSHOT_TARGETS = [
+    { prefix: 'tasks', getDb: getNativeDb },
+    { prefix: 'brain', getDb: getBrainNativeDb },
+];
+/**
+ * Format a Date as `YYYYMMDD-HHmmss` (local time) for snapshot filenames.
+ *
+ * Matches the regex `/^(?:tasks|brain)-\d{8}-\d{6}\.db$/` used by the rotation
+ * and listing logic below.
+ */
+function formatTimestamp(d) {
+    const pad = (n, len = 2) => String(n).padStart(len, '0');
+    return (`${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}` +
+        `-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`);
+}
+/**
+ * Build the regex that matches snapshot filenames for the given prefix.
+ * Isolated so both {@link rotateSnapshots} and {@link listSqliteBackupsForPrefix}
+ * share a single source of truth.
+ */
+function snapshotPattern(prefix) {
+    // Escape the prefix in case it ever contains regex metacharacters.
+    const safe = prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`^${safe}-\\d{8}-\\d{6}\\.db$`);
+}
+/**
+ * Rotate snapshots for a single prefix: delete the oldest files until fewer
+ * than {@link MAX_SNAPSHOTS} remain. Non-fatal on any filesystem error.
+ */
+function rotateSnapshots(backupDir, prefix) {
+    try {
+        const pattern = snapshotPattern(prefix);
+        const files = readdirSync(backupDir)
+            .filter((f) => pattern.test(f))
+            .map((f) => ({
+            name: f,
+            path: join(backupDir, f),
+            mtimeMs: statSync(join(backupDir, f)).mtimeMs,
+        }))
+            .sort((a, b) => a.mtimeMs - b.mtimeMs); // oldest first
+        while (files.length >= MAX_SNAPSHOTS) {
+            const oldest = files.shift();
+            if (!oldest)
+                break;
+            unlinkSync(oldest.path);
+        }
+    }
+    catch {
+        // non-fatal
+    }
+}
+/**
+ * Create a VACUUM INTO snapshot of a single SQLite database.
+ *
+ * Runs `PRAGMA wal_checkpoint(TRUNCATE)` first to flush the WAL for a
+ * consistent snapshot, then issues `VACUUM INTO '<dest>'` which SQLite
+ * implements as an atomic, fully defragmented clone.
+ *
+ * Non-fatal: all errors are swallowed via the outer try in
+ * {@link vacuumIntoBackupAll}; failures here must never block normal
+ * operation.
+ *
+ * @param target — snapshot target descriptor (prefix + native DB getter)
+ * @param backupDir — absolute path to `.cleo/backups/sqlite/`
+ * @param now — reference timestamp for the filename
+ */
+function snapshotOne(target, backupDir, now) {
+    const db = target.getDb();
+    if (!db)
+        return; // DB not initialized in this process — skip silently
+    const dest = join(backupDir, `${target.prefix}-${formatTimestamp(now)}.db`);
+    // TRUNCATE checkpoint: flushes all WAL frames to the main DB and truncates
+    // the WAL file to zero bytes, ensuring a consistent DB state before the
+    // VACUUM INTO snapshot (ADR-013, section 3 point 7). This is safe because
+    // the .db files are excluded from project git tracking (.gitignore + git
+    // rm --cached), so git operations cannot restore a stale WAL. The root
+    // cause of the 2026-02-25 data loss was that WAL files were still tracked
+    // in the project git index; that has been resolved (T4894, T5158).
+    db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+    rotateSnapshots(backupDir, target.prefix);
+    // Escape single quotes in path (path is programmatic, but be safe).
+    const safeDest = dest.replace(/'/g, "''");
+    db.exec(`VACUUM INTO '${safeDest}'`);
+}
+/**
+ * Create a VACUUM INTO snapshot of the primary SQLite database (tasks.db).
+ *
+ * Debounced by default (30s). Pass `force: true` to bypass debounce. This
+ * function is retained for backward compatibility with existing call sites
+ * in `data-safety.ts` / `data-safety-central.ts` that only snapshot tasks.db.
+ *
+ * Prefer {@link vacuumIntoBackupAll} for new code — it snapshots every
+ * registered database (currently tasks.db + brain.db) and shares the same
+ * debounce + rotation guarantees.
+ *
+ * Non-fatal: all errors are swallowed — backup failure must never
+ * interrupt normal operation.
+ */
+export async function vacuumIntoBackup(opts = {}) {
+    const now = Date.now();
+    const prefix = 'tasks';
+    const last = _lastBackupEpoch[prefix] ?? 0;
+    if (!opts.force && now - last < DEBOUNCE_MS) {
+        return; // debounced
+    }
+    try {
+        const cleoDir = getCleoDir(opts.cwd);
+        const backupDir = join(cleoDir, 'backups', 'sqlite');
+        mkdirSync(backupDir, { recursive: true });
+        const target = SNAPSHOT_TARGETS.find((t) => t.prefix === prefix);
+        if (!target)
+            return;
+        snapshotOne(target, backupDir, new Date());
+        _lastBackupEpoch[prefix] = Date.now();
+    }
+    catch {
+        // non-fatal — backup failure must never interrupt normal operation
+    }
+}
+/**
+ * Create VACUUM INTO snapshots of all registered CLEO SQLite databases
+ * (currently tasks.db + brain.db). Each database is debounced independently.
+ *
+ * This is the preferred entry point for session-lifecycle hooks and
+ * pre-destructive-operation snapshots — it guarantees that BRAIN memory is
+ * snapshotted alongside task state.
+ *
+ * Non-fatal: errors are swallowed per database so a brain.db failure cannot
+ * block a tasks.db snapshot (and vice versa).
+ */
+export async function vacuumIntoBackupAll(opts = {}) {
+    const nowMs = Date.now();
+    const now = new Date();
+    let backupDir;
+    try {
+        const cleoDir = getCleoDir(opts.cwd);
+        backupDir = join(cleoDir, 'backups', 'sqlite');
+        mkdirSync(backupDir, { recursive: true });
+    }
+    catch {
+        return; // cannot resolve backup dir — abort silently
+    }
+    for (const target of SNAPSHOT_TARGETS) {
+        const last = _lastBackupEpoch[target.prefix] ?? 0;
+        if (!opts.force && nowMs - last < DEBOUNCE_MS) {
+            continue; // debounced — skip this target only
+        }
+        try {
+            snapshotOne(target, backupDir, now);
+            _lastBackupEpoch[target.prefix] = Date.now();
+        }
+        catch {
+            // non-fatal — continue with remaining targets
+        }
+    }
+}
+/**
+ * List existing snapshots for a given prefix (`"tasks"` or `"brain"`),
+ * newest first. Returns an empty array if the backup directory does not
+ * exist.
+ */
+function listSqliteBackupsForPrefix(prefix, cwd) {
+    try {
+        const cleoDir = getCleoDir(cwd);
+        const backupDir = join(cleoDir, 'backups', 'sqlite');
+        if (!existsSync(backupDir))
+            return [];
+        const pattern = snapshotPattern(prefix);
+        return readdirSync(backupDir)
+            .filter((f) => pattern.test(f))
+            .map((f) => ({
+            name: f,
+            path: join(backupDir, f),
+            mtimeMs: statSync(join(backupDir, f)).mtimeMs,
+        }))
+            .sort((a, b) => b.mtimeMs - a.mtimeMs); // newest first
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * List existing tasks.db snapshots (newest first).
+ *
+ * Retained for backward compatibility. For new code prefer
+ * {@link listSqliteBackupsAll}.
+ */
+export function listSqliteBackups(cwd) {
+    return listSqliteBackupsForPrefix('tasks', cwd);
+}
+/**
+ * List existing brain.db snapshots (newest first).
+ */
+export function listBrainBackups(cwd) {
+    return listSqliteBackupsForPrefix('brain', cwd);
+}
+/**
+ * Aggregated listing of all registered SQLite snapshots.
+ *
+ * Returns an object keyed by snapshot prefix (`tasks`, `brain`) where each
+ * value is the per-prefix list sorted newest-first. Missing prefixes are
+ * represented as empty arrays.
+ */
+export function listSqliteBackupsAll(cwd) {
+    const out = {};
+    for (const target of SNAPSHOT_TARGETS) {
+        out[target.prefix] = listSqliteBackupsForPrefix(target.prefix, cwd);
+    }
+    return out;
+}
+//# sourceMappingURL=sqlite-backup.js.map

package/dist/store/sqlite-backup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-backup.js","sourceRoot":"","sources":["../../src/store/sqlite-backup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACnF,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,8EAA8E;AAC9E,MAAM,aAAa,GAAG,EAAE,CAAC;AACzB,oFAAoF;AACpF,MAAM,WAAW,GAAG,MAAM,CAAC,CAAC,aAAa;AAEzC;;;GAGG;AACH,MAAM,gBAAgB,GAA2B,EAAE,CAAC;AAepD;;;GAGG;AACH,MAAM,gBAAgB,GAAqB;IACzC,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE;IACvC,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE;CAC7C,CAAC;AAEF;;;;;GAKG;AACH,SAAS,eAAe,CAAC,CAAO;IAC9B,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,GAAG,GAAG,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACjE,OAAO,CACL,GAAG,CAAC,CAAC,WAAW,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE;QAC/D,IAAI,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,EAAE,CACpE,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,eAAe,CAAC,MAAc;IACrC,mEAAmE;IACnE,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;IAC3D,OAAO,IAAI,MAAM,CAAC,IAAI,IAAI,sBAAsB,CAAC,CAAC;AACpD,CAAC;AAED;;;GAGG;AACH,SAAS,eAAe,CAAC,SAAiB,EAAE,MAAc;IACxD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QACxC,MAAM,KAAK,GAAG,WAAW,CAAC,SAAS,CAAC;aACjC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;aAC9B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACX,IAAI,EAAE,CAAC;YACP,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;YACxB,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO;SAC9C,CAAC,CAAC;aACF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;QAEzD,OAAO,KAAK,CAAC,MAAM,IAAI,aAAa,EAAE,CAAC;YACrC,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;YAC7B,IAAI,CAAC,MAAM;gBAAE,MAAM;YACnB,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,YAAY;IACd,CAAC;AACH,CAAC;AAaD;;;;;;;;;;;;;;GAcG;AACH,SAAS,WAAW,CAAC,MAAsB,EAAE,SAAiB,EAAE,GAAS;IACvE,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC;IAC1B,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,qDAAqD;IAEtE,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE,GAAG,MAAM,CAAC,MAAM,IAAI,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAE5E,2EAA2E;IAC3E,wEAAwE;IACxE,0EAA0E;IAC1E,yEAAyE;IACzE,uEAAuE;IACvE,0EAA0E;IAC1E,mEAAmE;IACnE,EAAE,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC;IAE3C,eAAe,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAE1C,oEAAoE;IACpE,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC1C,EAAE,CAAC,IAAI,CAAC,gBAAgB,QAAQ,GAAG,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,OAAsB,EAAE;IAC7D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,MAAM,GAAG,OAAO,CAAC;IACvB,MAAM,IAAI,GAAG,gBAAgB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,GAAG,GAAG,IAAI,GAAG,WAAW,EAAE,CAAC;QAC5C,OAAO,CAAC,YAAY;IACtB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;QACrD,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAE1C,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;QACjE,IAAI,CAAC,MAAM;YAAE,OAAO;QAEpB,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;QAC3C,gBAAgB,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,mEAAmE;IACrE,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAAsB,EAAE;IAChE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IAEvB,IAAI,SAAiB,CAAC;IACtB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrC,SAAS,GAAG,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;QAC/C,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,6CAA6C;IACvD,CAAC;IAED,KAAK,MAAM,MAAM,IAAI,gBAAgB,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,gBAAgB,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,KAAK,GAAG,IAAI,GAAG,WAAW,EAAE,CAAC;YAC9C,SAAS,CAAC,oCAAoC;QAChD,CAAC;QACD,IAAI,CAAC;YACH,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;YACpC,gBAAgB,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC/C,CAAC;QAAC,MAAM,CAAC;YACP,8CAA8C;QAChD,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,0BAA0B,CACjC,MAAc,EACd,GAAY;IAEZ,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;QAChC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;QACrD,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,EAAE,CAAC;QAEtC,MAAM,OAAO,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QACxC,OAAO,WAAW,CAAC,SAAS,CAAC;aAC1B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;aAC9B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACX,IAAI,EAAE,CAAC;YACP,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;YACxB,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO;SAC9C,CAAC,CAAC;aACF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,GAAY;IAEZ,OAAO,0BAA0B,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;AAClD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAC9B,GAAY;IAEZ,OAAO,0BAA0B,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAAY;IAEZ,MAAM,GAAG,GAA2E,EAAE,CAAC;IACvF,KAAK,MAAM,MAAM,IAAI,gBAAgB,EAAE,CAAC;QACtC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,0BAA0B,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}