@proletariat/cli 0.3.87 → 0.3.89

package/dist/lib/database/db-safety.js

@@ -0,0 +1,295 @@
+/**
+ * Database Safety — WAL mode, auto-backup, corruption recovery.
+ *
+ * Provides:
+ * - WAL journal mode configuration
+ * - Rotating backup (keeps last 5 copies)
+ * - Integrity check on open with auto-recovery
+ * - Manual repair via dump/reimport
+ *
+ * See: PRLT-1081
+ */
+import Database from 'better-sqlite3';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const MAX_BACKUPS = 5;
+/**
+ * Enable WAL journal mode on a database connection.
+ * WAL allows concurrent readers with one writer and is significantly
+ * more resistant to corruption than the default journal_mode=delete.
+ */
+export function enableWALMode(db) {
+    db.pragma('journal_mode = WAL');
+}
+/**
+ * Get the backup path for a given database path and backup number.
+ */
+export function getBackupPath(dbPath, n) {
+    return `${dbPath}.backup.${n}`;
+}
+/**
+ * Create a rotating backup of the database file.
+ * Keeps the last MAX_BACKUPS copies, numbered 1 (newest) through MAX_BACKUPS (oldest).
+ * Rotates existing backups before copying the current database.
+ *
+ * Returns true if backup was created, false if source didn't exist.
+ */
+export function createRotatingBackup(dbPath) {
+    if (!fs.existsSync(dbPath)) {
+        return false;
+    }
+    // Rotate existing backups: delete oldest, shift others up
+    const oldest = getBackupPath(dbPath, MAX_BACKUPS);
+    if (fs.existsSync(oldest)) {
+        fs.unlinkSync(oldest);
+    }
+    for (let i = MAX_BACKUPS - 1; i >= 1; i--) {
+        const src = getBackupPath(dbPath, i);
+        const dst = getBackupPath(dbPath, i + 1);
+        if (fs.existsSync(src)) {
+            fs.renameSync(src, dst);
+        }
+    }
+    // Copy current database as backup.1 (newest)
+    try {
+        fs.copyFileSync(dbPath, getBackupPath(dbPath, 1));
+        // Also copy WAL and SHM files if they exist (for WAL-mode databases)
+        const walPath = `${dbPath}-wal`;
+        const shmPath = `${dbPath}-shm`;
+        if (fs.existsSync(walPath)) {
+            fs.copyFileSync(walPath, `${getBackupPath(dbPath, 1)}-wal`);
+        }
+        if (fs.existsSync(shmPath)) {
+            fs.copyFileSync(shmPath, `${getBackupPath(dbPath, 1)}-shm`);
+        }
+        return true;
+    }
+    catch {
+        // Backup failure is not fatal — log and continue
+        return false;
+    }
+}
+/**
+ * Run PRAGMA integrity_check on a database.
+ * Returns { ok: true } if the database is healthy, or { ok: false, errors } with details.
+ */
+export function checkIntegrity(db) {
+    try {
+        const rows = db.pragma('integrity_check');
+        const errors = rows
+            .map(r => r.integrity_check)
+            .filter(msg => msg !== 'ok');
+        return { ok: errors.length === 0, errors };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            errors: [error instanceof Error ? error.message : String(error)],
+        };
+    }
+}
+/**
+ * Quick integrity check using PRAGMA quick_check (faster than full integrity_check).
+ * Skips checking that the contents of table rows match the indexes.
+ */
+export function quickCheckIntegrity(db) {
+    try {
+        const rows = db.pragma('quick_check');
+        const errors = rows
+            .map(r => r.quick_check)
+            .filter(msg => msg !== 'ok');
+        return { ok: errors.length === 0, errors };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            errors: [error instanceof Error ? error.message : String(error)],
+        };
+    }
+}
+/**
+ * Attempt to repair a corrupted database.
+ *
+ * Strategy:
+ * 1. Try dump/reimport — opens the corrupt DB, dumps all SQL, creates a new DB
+ * 2. If dump fails, fall back to the most recent backup
+ *
+ * The original corrupt file is preserved as dbPath.corrupt for forensics.
+ */
+export function repairDatabase(dbPath) {
+    // Try dump/reimport first
+    const dumpResult = attemptDumpReimport(dbPath);
+    if (dumpResult.success) {
+        return dumpResult;
+    }
+    // Fall back to backup restore
+    const backupResult = attemptBackupRestore(dbPath);
+    if (backupResult.success) {
+        return backupResult;
+    }
+    return {
+        success: false,
+        method: 'none',
+        message: `Could not repair database. Dump failed: ${dumpResult.message}. No usable backups found.`,
+    };
+}
+/**
+ * Attempt recovery via .dump and reimport.
+ * Opens the corrupt database, extracts as much SQL as possible,
+ * then creates a fresh database from that SQL.
+ */
+function attemptDumpReimport(dbPath) {
+    let corruptDb = null;
+    let newDb = null;
+    const tempPath = `${dbPath}.repair-temp`;
+    try {
+        // Open corrupt database — may partially work
+        corruptDb = new Database(dbPath, { readonly: true });
+        // Dump all recoverable SQL
+        const tables = corruptDb.prepare("SELECT sql FROM sqlite_master WHERE sql IS NOT NULL ORDER BY CASE type WHEN 'table' THEN 1 WHEN 'index' THEN 2 ELSE 3 END").all();
+        if (tables.length === 0) {
+            return { success: false, method: 'dump-reimport', message: 'No tables found in corrupt database' };
+        }
+        // Create new database with recovered schema
+        newDb = new Database(tempPath);
+        newDb.pragma('journal_mode = WAL');
+        for (const { sql } of tables) {
+            try {
+                newDb.exec(sql);
+            }
+            catch {
+                // Skip objects that fail to recreate (e.g., references to missing tables)
+            }
+        }
+        // Copy data table by table
+        const tableNames = corruptDb.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'").all();
+        let rowsRecovered = 0;
+        for (const { name } of tableNames) {
+            try {
+                const rows = corruptDb.prepare(`SELECT * FROM "${name}"`).all();
+                if (rows.length === 0)
+                    continue;
+                const columns = Object.keys(rows[0]);
+                const placeholders = columns.map(() => '?').join(', ');
+                const insertSql = `INSERT OR IGNORE INTO "${name}" (${columns.map(c => `"${c}"`).join(', ')}) VALUES (${placeholders})`;
+                const insertStmt = newDb.prepare(insertSql);
+                const insertAll = newDb.transaction((data) => {
+                    for (const row of data) {
+                        insertStmt.run(...columns.map(c => row[c]));
+                    }
+                });
+                insertAll(rows);
+                rowsRecovered += rows.length;
+            }
+            catch {
+                // Skip tables that can't be read
+            }
+        }
+        corruptDb.close();
+        corruptDb = null;
+        newDb.close();
+        newDb = null;
+        // Swap files: corrupt → .corrupt, repaired → original
+        const corruptBackupPath = `${dbPath}.corrupt`;
+        if (fs.existsSync(corruptBackupPath)) {
+            fs.unlinkSync(corruptBackupPath);
+        }
+        fs.renameSync(dbPath, corruptBackupPath);
+        fs.renameSync(tempPath, dbPath);
+        // Clean up old WAL/SHM files from the corrupt database
+        for (const suffix of ['-wal', '-shm']) {
+            const f = `${dbPath}${suffix}`;
+            if (fs.existsSync(f)) {
+                fs.unlinkSync(f);
+            }
+        }
+        return {
+            success: true,
+            method: 'dump-reimport',
+            message: `Recovered ${rowsRecovered} rows from ${tableNames.length} tables. Corrupt file saved as ${path.basename(corruptBackupPath)}.`,
+        };
+    }
+    catch (error) {
+        // Clean up on failure
+        if (corruptDb) {
+            try {
+                corruptDb.close();
+            }
+            catch { /* ignore */ }
+        }
+        if (newDb) {
+            try {
+                newDb.close();
+            }
+            catch { /* ignore */ }
+        }
+        if (fs.existsSync(tempPath)) {
+            try {
+                fs.unlinkSync(tempPath);
+            }
+            catch { /* ignore */ }
+        }
+        return {
+            success: false,
+            method: 'dump-reimport',
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Attempt recovery by restoring from the most recent valid backup.
+ * Tries backups 1 through MAX_BACKUPS, validates each with integrity_check.
+ */
+function attemptBackupRestore(dbPath) {
+    for (let i = 1; i <= MAX_BACKUPS; i++) {
+        const backupPath = getBackupPath(dbPath, i);
+        if (!fs.existsSync(backupPath)) {
+            continue;
+        }
+        // Validate the backup
+        let backupDb = null;
+        try {
+            backupDb = new Database(backupPath, { readonly: true });
+            const check = checkIntegrity(backupDb);
+            backupDb.close();
+            backupDb = null;
+            if (!check.ok) {
+                continue;
+            }
+            // Backup is valid — swap it in
+            const corruptBackupPath = `${dbPath}.corrupt`;
+            if (fs.existsSync(corruptBackupPath)) {
+                fs.unlinkSync(corruptBackupPath);
+            }
+            fs.renameSync(dbPath, corruptBackupPath);
+            fs.copyFileSync(backupPath, dbPath);
+            // Clean up old WAL/SHM files
+            for (const suffix of ['-wal', '-shm']) {
+                const f = `${dbPath}${suffix}`;
+                if (fs.existsSync(f)) {
+                    fs.unlinkSync(f);
+                }
+            }
+            return {
+                success: true,
+                method: 'backup-restore',
+                message: `Restored from backup.${i}. Corrupt file saved as ${path.basename(corruptBackupPath)}.`,
+            };
+        }
+        catch {
+            if (backupDb) {
+                try {
+                    backupDb.close();
+                }
+                catch { /* ignore */ }
+            }
+            continue;
+        }
+    }
+    return {
+        success: false,
+        method: 'backup-restore',
+        message: 'No valid backups found',
+    };
+}
+//# sourceMappingURL=db-safety.js.map

package/dist/lib/database/db-safety.js.map

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

package/dist/lib/database/driver.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Database Driver Abstraction Layer
+ *
+ * Defines a driver-agnostic interface for SQLite database access.
+ * This allows swapping the underlying implementation (better-sqlite3, sql.js, etc.)
+ * without changing consumer code.
+ *
+ * All database access in the codebase should go through this interface
+ * rather than importing better-sqlite3 directly.
+ */
+import Database from 'better-sqlite3';
+/**
+ * Result of executing a statement that modifies data.
+ */
+export interface RunResult {
+    /** Number of rows changed by the statement */
+    changes: number;
+    /** Row ID of the last inserted row */
+    lastInsertRowid: number | bigint;
+}
+/**
+ * A prepared SQL statement that can be executed with parameters.
+ */
+export interface PreparedStatement<T = Record<string, unknown>> {
+    /** Execute the statement and return change info (INSERT/UPDATE/DELETE) */
+    run(...params: unknown[]): RunResult;
+    /** Execute the statement and return the first matching row */
+    get(...params: unknown[]): T | undefined;
+    /** Execute the statement and return all matching rows */
+    all(...params: unknown[]): T[];
+}
+/**
+ * Database driver interface that abstracts over the underlying SQLite implementation.
+ *
+ * This is the single interface through which all database access should flow.
+ * Implementations exist for better-sqlite3 (current) with sql.js planned.
+ *
+ * Usage:
+ * ```typescript
+ * const driver = createDriver(dbPath)
+ * const row = driver.prepare<{ count: number }>('SELECT COUNT(*) as count FROM users').get()
+ * driver.close()
+ * ```
+ */
+export interface DatabaseDriver {
+    /** Prepare a SQL statement for execution */
+    prepare<T = Record<string, unknown>>(sql: string): PreparedStatement<T>;
+    /** Execute raw SQL (DDL, multi-statement, no return value) */
+    exec(sql: string): void;
+    /** Get or set SQLite pragmas */
+    pragma(source: string, options?: {
+        simple?: boolean;
+    }): unknown;
+    /**
+     * Create a transaction function.
+     * Returns a new function that, when called, runs the wrapped function
+     * inside a SQLite transaction.
+     */
+    transaction<F extends (...args: unknown[]) => unknown>(fn: F): F;
+    /** Close the database connection */
+    close(): void;
+    /** Whether the connection is open */
+    readonly open: boolean;
+    /**
+     * Access the underlying raw database connection.
+     * Use this ONLY for interop with libraries that need the raw connection
+     * (e.g., Drizzle ORM). New code should use the driver interface instead.
+     * @internal
+     */
+    readonly raw: unknown;
+}
+/**
+ * DatabaseDriver implementation backed by better-sqlite3.
+ *
+ * This is the primary driver used in production. It wraps a better-sqlite3
+ * Database instance behind the DatabaseDriver interface.
+ */
+export declare class BetterSqlite3Driver implements DatabaseDriver {
+    private db;
+    constructor(db: Database.Database);
+    prepare<T = Record<string, unknown>>(sql: string): PreparedStatement<T>;
+    exec(sql: string): void;
+    pragma(source: string, options?: {
+        simple?: boolean;
+    }): unknown;
+    transaction<F extends (...args: unknown[]) => unknown>(fn: F): F;
+    close(): void;
+    get open(): boolean;
+    /**
+     * Access the underlying better-sqlite3 Database instance.
+     * @internal Use for Drizzle ORM interop only.
+     */
+    get raw(): Database.Database;
+}
+/**
+ * Create a DatabaseDriver from an existing better-sqlite3 Database instance.
+ * Useful when migrating existing code that already has a Database object.
+ */
+export declare function wrapDatabase(db: Database.Database): DatabaseDriver;
+/**
+ * Create a DatabaseDriver by opening a new better-sqlite3 connection.
+ * Configures standard pragmas (WAL mode, foreign keys, busy timeout).
+ */
+export declare function openDriver(dbPath: string, options?: {
+    foreignKeys?: boolean;
+    busyTimeout?: number;
+}): DatabaseDriver;
+/**
+ * Extract the raw better-sqlite3 Database from a driver.
+ * Throws if the driver is not a BetterSqlite3Driver.
+ *
+ * Use this for interop with code that still requires the raw connection
+ * (e.g., Drizzle ORM, legacy code being migrated).
+ */
+export declare function getRawDatabase(driver: DatabaseDriver): Database.Database;

package/dist/lib/database/driver.js

@@ -0,0 +1,110 @@
+/**
+ * Database Driver Abstraction Layer
+ *
+ * Defines a driver-agnostic interface for SQLite database access.
+ * This allows swapping the underlying implementation (better-sqlite3, sql.js, etc.)
+ * without changing consumer code.
+ *
+ * All database access in the codebase should go through this interface
+ * rather than importing better-sqlite3 directly.
+ */
+import Database from 'better-sqlite3';
+// =============================================================================
+// BetterSqlite3 Driver Implementation
+// =============================================================================
+/**
+ * DatabaseDriver implementation backed by better-sqlite3.
+ *
+ * This is the primary driver used in production. It wraps a better-sqlite3
+ * Database instance behind the DatabaseDriver interface.
+ */
+export class BetterSqlite3Driver {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    prepare(sql) {
+        const stmt = this.db.prepare(sql);
+        return {
+            run: (...params) => {
+                const result = stmt.run(...params);
+                return { changes: result.changes, lastInsertRowid: result.lastInsertRowid };
+            },
+            get: (...params) => {
+                return stmt.get(...params);
+            },
+            all: (...params) => {
+                return stmt.all(...params);
+            },
+        };
+    }
+    exec(sql) {
+        this.db.exec(sql);
+    }
+    pragma(source, options) {
+        return this.db.pragma(source, options);
+    }
+    transaction(fn) {
+        return this.db.transaction(fn);
+    }
+    close() {
+        this.db.close();
+    }
+    get open() {
+        return this.db.open;
+    }
+    /**
+     * Access the underlying better-sqlite3 Database instance.
+     * @internal Use for Drizzle ORM interop only.
+     */
+    get raw() {
+        return this.db;
+    }
+}
+// =============================================================================
+// Factory Functions
+// =============================================================================
+/**
+ * Create a DatabaseDriver from an existing better-sqlite3 Database instance.
+ * Useful when migrating existing code that already has a Database object.
+ */
+export function wrapDatabase(db) {
+    return new BetterSqlite3Driver(db);
+}
+/**
+ * Create a DatabaseDriver by opening a new better-sqlite3 connection.
+ * Configures standard pragmas (WAL mode, foreign keys, busy timeout).
+ */
+export function openDriver(dbPath, options) {
+    const db = new Database(dbPath);
+    db.pragma('journal_mode = WAL');
+    if (options?.foreignKeys !== false) {
+        db.pragma('foreign_keys = ON');
+    }
+    if (options?.busyTimeout !== undefined) {
+        db.pragma(`busy_timeout = ${options.busyTimeout}`);
+    }
+    else {
+        db.pragma('busy_timeout = 5000');
+    }
+    return new BetterSqlite3Driver(db);
+}
+/**
+ * Extract the raw better-sqlite3 Database from a driver.
+ * Throws if the driver is not a BetterSqlite3Driver.
+ *
+ * Use this for interop with code that still requires the raw connection
+ * (e.g., Drizzle ORM, legacy code being migrated).
+ */
+export function getRawDatabase(driver) {
+    if (driver instanceof BetterSqlite3Driver) {
+        return driver.raw;
+    }
+    // For other driver implementations, check the raw property
+    const raw = driver.raw;
+    if (raw && typeof raw === 'object' && 'prepare' in raw) {
+        return raw;
+    }
+    throw new Error('Cannot extract raw database from this driver implementation');
+}
+//# sourceMappingURL=driver.js.map

package/dist/lib/database/driver.js.map

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