@cleocode/core 2026.4.9 → 2026.4.11

package/dist/store/lock.js

@@ -0,0 +1,70 @@
+/**
+ * File locking using proper-lockfile.
+ * Prevents concurrent modifications to CLEO data files.
+ * @epic T4454
+ * @task T4457
+ */
+import { ExitCode } from '@cleocode/contracts';
+import lockfile from 'proper-lockfile';
+import { CleoError } from '../errors.js';
+/** Default lock options. */
+const DEFAULT_LOCK_OPTIONS = {
+    retries: {
+        retries: 3,
+        minTimeout: 100,
+        maxTimeout: 1000,
+        factor: 2,
+    },
+    stale: 10_000,
+    realpath: false,
+};
+/**
+ * Acquire an exclusive lock on a file.
+ * Returns a release function that must be called when done.
+ */
+export async function acquireLock(filePath, options) {
+    try {
+        const release = await lockfile.lock(filePath, {
+            ...DEFAULT_LOCK_OPTIONS,
+            ...(options?.stale !== undefined && { stale: options.stale }),
+            ...(options?.retries !== undefined && {
+                retries: {
+                    ...DEFAULT_LOCK_OPTIONS.retries,
+                    retries: options.retries,
+                },
+            }),
+        });
+        return release;
+    }
+    catch (err) {
+        throw new CleoError(ExitCode.LOCK_TIMEOUT, `Failed to acquire lock: ${filePath}`, {
+            fix: `Another process may be writing to this file. Wait and retry.`,
+            cause: err,
+        });
+    }
+}
+/**
+ * Check if a file is currently locked.
+ */
+export async function isLocked(filePath) {
+    try {
+        return await lockfile.check(filePath, { realpath: false });
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Execute a function while holding an exclusive lock on a file.
+ * The lock is automatically released when the function completes (or throws).
+ */
+export async function withLock(filePath, fn, options) {
+    const release = await acquireLock(filePath, options);
+    try {
+        return await fn();
+    }
+    finally {
+        await release();
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/store/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/store/lock.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,QAAQ,MAAM,iBAAiB,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,4BAA4B;AAC5B,MAAM,oBAAoB,GAAG;IAC3B,OAAO,EAAE;QACP,OAAO,EAAE,CAAC;QACV,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,IAAI;QAChB,MAAM,EAAE,CAAC;KACV;IACD,KAAK,EAAE,MAAM;IACb,QAAQ,EAAE,KAAK;CAChB,CAAC;AAKF;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,QAAgB,EAChB,OAA8C;IAE9C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE;YAC5C,GAAG,oBAAoB;YACvB,GAAG,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;YAC7D,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,SAAS,IAAI;gBACpC,OAAO,EAAE;oBACP,GAAG,oBAAoB,CAAC,OAAO;oBAC/B,OAAO,EAAE,OAAO,CAAC,OAAO;iBACzB;aACF,CAAC;SACH,CAAC,CAAC;QACH,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,2BAA2B,QAAQ,EAAE,EAAE;YAChF,GAAG,EAAE,8DAA8D;YACnE,KAAK,EAAE,GAAG;SACX,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,QAAgB;IAC7C,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,QAAgB,EAChB,EAAoB,EACpB,OAA8C;IAE9C,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACrD,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,EAAE,CAAC;IACpB,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,EAAE,CAAC;IAClB,CAAC;AACH,CAAC"}

package/dist/store/migration-manager.js

@@ -0,0 +1,151 @@
+/**
+ * Unified migration manager for SQLite databases.
+ *
+ * Consolidates duplicated reconciliation, bootstrap, retry, and column-safety
+ * logic that was previously copy-pasted between sqlite.ts (tasks.db) and
+ * brain-sqlite.ts (brain.db). Both modules now delegate to these shared functions.
+ *
+ * @task T132
+ * @see https://github.com/anthropics/cleo/issues/82
+ * @see https://github.com/anthropics/cleo/issues/63
+ * @see https://github.com/anthropics/cleo/issues/65
+ */
+import { copyFileSync, existsSync } from 'node:fs';
+import { readMigrationFiles } from 'drizzle-orm/migrator';
+import { migrate } from 'drizzle-orm/node-sqlite/migrator';
+import { getLogger } from '../logger.js';
+/** Migration retry constants for SQLITE_BUSY handling (T5185). */
+const MAX_MIGRATION_RETRIES = 5;
+const MIGRATION_RETRY_BASE_DELAY_MS = 100;
+const MIGRATION_RETRY_MAX_DELAY_MS = 2000;
+/**
+ * Check whether a table exists in a SQLite database.
+ */
+export function tableExists(nativeDb, tableName) {
+    const result = nativeDb
+        .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?")
+        .get(tableName);
+    return !!result;
+}
+/**
+ * Check if an error is a SQLite BUSY error (database locked by another process).
+ * node:sqlite throws native Error with message containing the SQLite error code.
+ * @task T5185
+ */
+export function isSqliteBusy(err) {
+    if (!(err instanceof Error))
+        return false;
+    const msg = err.message.toLowerCase();
+    return msg.includes('sqlite_busy') || msg.includes('database is locked');
+}
+/**
+ * Create a pre-migration safety backup of the database file.
+ *
+ * Only creates the backup once (idempotent). Non-fatal on failure.
+ */
+export function createSafetyBackup(dbPath) {
+    const backupPath = dbPath.replace(/\.db$/, '-pre-cleo.db.bak');
+    if (!existsSync(backupPath)) {
+        try {
+            copyFileSync(dbPath, backupPath);
+        }
+        catch {
+            /* non-fatal */
+        }
+    }
+}
+/**
+ * Bootstrap and reconcile the Drizzle migration journal.
+ *
+ * Handles three scenarios:
+ * 1. Tables exist but no __drizzle_migrations — bootstrap baseline as applied
+ * 2. Journal has orphaned hashes (from older CLEO version) — clear and re-mark all as applied
+ * 3. Journal is healthy — no-op
+ *
+ * @param nativeDb - Native SQLite database handle
+ * @param migrationsFolder - Path to the drizzle migrations folder
+ * @param existenceTable - A table name used to detect if the DB has data (e.g., 'tasks' or 'brain_decisions')
+ * @param logSubsystem - Logger subsystem name for reconciliation warnings
+ */
+export function reconcileJournal(nativeDb, migrationsFolder, existenceTable, logSubsystem) {
+    // Scenario 1: Tables exist but no migration journal — bootstrap baseline
+    if (tableExists(nativeDb, existenceTable) && !tableExists(nativeDb, '__drizzle_migrations')) {
+        const migrations = readMigrationFiles({ migrationsFolder });
+        const baseline = migrations[0];
+        if (baseline) {
+            nativeDb.exec(`
+        CREATE TABLE IF NOT EXISTS "__drizzle_migrations" (
+          id SERIAL PRIMARY KEY,
+          hash text NOT NULL,
+          created_at numeric
+        )
+      `);
+            nativeDb.exec(`INSERT INTO "__drizzle_migrations" ("hash", "created_at") VALUES ('${baseline.hash}', ${baseline.folderMillis})`);
+        }
+    }
+    // Scenario 2: Journal has orphaned entries from a previous CLEO version
+    if (tableExists(nativeDb, '__drizzle_migrations') && tableExists(nativeDb, existenceTable)) {
+        const localMigrations = readMigrationFiles({ migrationsFolder });
+        const localHashes = new Set(localMigrations.map((m) => m.hash));
+        const dbEntries = nativeDb.prepare('SELECT hash FROM "__drizzle_migrations"').all();
+        const hasOrphanedEntries = dbEntries.some((e) => !localHashes.has(e.hash));
+        if (hasOrphanedEntries) {
+            const log = getLogger(logSubsystem);
+            log.warn({ orphaned: dbEntries.filter((e) => !localHashes.has(e.hash)).length }, `Detected stale migration journal entries from a previous CLEO version. Reconciling.`);
+            nativeDb.exec('DELETE FROM "__drizzle_migrations"');
+            for (const m of localMigrations) {
+                nativeDb.exec(`INSERT INTO "__drizzle_migrations" ("hash", "created_at") VALUES ('${m.hash}', ${m.folderMillis})`);
+            }
+        }
+    }
+}
+/**
+ * Run Drizzle migrations with SQLITE_BUSY retry and exponential backoff.
+ *
+ * @param db - Drizzle database instance
+ * @param migrationsFolder - Path to the drizzle migrations folder
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Drizzle's NodeSQLiteDatabase is generic — accepting any schema avoids coupling to a specific schema type
+export function migrateWithRetry(db, migrationsFolder) {
+    for (let attempt = 1; attempt <= MAX_MIGRATION_RETRIES; attempt++) {
+        try {
+            migrate(db, { migrationsFolder });
+            return;
+        }
+        catch (err) {
+            if (!isSqliteBusy(err) || attempt === MAX_MIGRATION_RETRIES) {
+                throw err;
+            }
+            const delay = Math.min(MIGRATION_RETRY_BASE_DELAY_MS * 2 ** (attempt - 1) * (1 + Math.random() * 0.5), MIGRATION_RETRY_MAX_DELAY_MS);
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.round(delay));
+        }
+    }
+}
+/**
+ * Ensure all required columns exist on a table.
+ *
+ * Uses PRAGMA table_info to inspect the schema and adds any missing columns
+ * via ALTER TABLE ADD COLUMN. Safety net for databases where Drizzle migrations
+ * could not run due to journal corruption or version skew.
+ *
+ * @param nativeDb - Native SQLite database handle
+ * @param tableName - Table to check (e.g., 'tasks')
+ * @param requiredColumns - Columns that must exist
+ * @param logSubsystem - Logger subsystem name
+ */
+export function ensureColumns(nativeDb, tableName, requiredColumns, logSubsystem) {
+    if (!tableExists(nativeDb, tableName))
+        return;
+    if (requiredColumns.length === 0)
+        return;
+    const columns = nativeDb.prepare(`PRAGMA table_info(${tableName})`).all();
+    const existingCols = new Set(columns.map((c) => c.name));
+    for (const req of requiredColumns) {
+        if (!existingCols.has(req.name)) {
+            const log = getLogger(logSubsystem);
+            log.warn({ column: req.name }, `Adding missing column ${tableName}.${req.name} via ALTER TABLE`);
+            nativeDb.exec(`ALTER TABLE ${tableName} ADD COLUMN ${req.name} ${req.ddl}`);
+        }
+    }
+}
+//# sourceMappingURL=migration-manager.js.map

package/dist/store/migration-manager.js.map

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