@vibesdotdev/localdb 0.0.1

package/src/core/database.ts

@@ -0,0 +1,419 @@
+/**
+ * Local Database Manager
+ *
+ * High-level API for managing local SQLite databases in vibes dev.
+ * Provides connection pooling, migration management, and consistent configuration.
+ *
+ * Usage:
+ *   const db = localdb.getDatabase('atlas', '.vibes/atlas/project.db');
+ *   // db is ready to use with WAL mode, busy timeout, and migrations applied
+ */
+
+import { Database } from 'bun:sqlite';
+import { getLogger } from '@vibesdotdev/logging';
+import { connectionPool } from './connection-pool.ts';
+import { migrationRegistry, type Migration } from './migration-registry.ts';
+import { toErrorContext } from './error-context';
+import { isLocaldbServerRuntime } from './runtime.ts';
+
+const logger = getLogger('localdb:database');
+
+let mkdir: typeof import('node:fs/promises').mkdir;
+let copyFile: typeof import('node:fs/promises').copyFile;
+let unlink: typeof import('node:fs/promises').unlink;
+let readdir: typeof import('node:fs/promises').readdir;
+let dirname: typeof import('node:path').dirname;
+let basename: typeof import('node:path').basename;
+
+const BACKUP_RETENTION_COUNT = 12;
+const isServerRuntime = isLocaldbServerRuntime();
+
+if (isServerRuntime) {
+	({ mkdir, copyFile, unlink, readdir } = await import('node:fs/promises'));
+	({ dirname, basename } = await import('node:path'));
+}
+
+export interface DatabaseOptions {
+	/** Namespace for migrations (e.g., 'atlas', 'session') */
+	namespace: string;
+
+	/** Path to database file */
+	dbPath: string;
+
+	/** Consumer identifier for debugging */
+	consumer?: string;
+
+	/** Skip migration check/run on initialization */
+	skipMigrations?: boolean;
+
+	/** Use connection pool (default: true) */
+	usePool?: boolean;
+}
+
+interface NodeLikeError {
+	code?: string;
+}
+
+function isFileMissingError(error: unknown): boolean {
+	if (!error || typeof error !== 'object') return false;
+	return (error as NodeLikeError).code === 'ENOENT';
+}
+
+export class LocalDatabase {
+	private db!: Database;
+	private options: Required<DatabaseOptions>;
+	private initialized = false;
+
+	constructor(options: DatabaseOptions) {
+		this.options = {
+			consumer: 'unknown',
+			skipMigrations: false,
+			usePool: true,
+			...options
+		};
+	}
+
+	/**
+	 * Initialize the database connection
+	 * - Creates directory if needed
+	 * - Gets/creates pooled connection
+	 * - Runs pending migrations
+	 */
+	async initialize(): Promise<void> {
+		if (this.initialized) return;
+
+		// Ensure directory exists
+		if (!isServerRuntime) {
+			throw new Error('LocalDatabase is not available in browser builds');
+		}
+		await mkdir(dirname(this.options.dbPath), { recursive: true });
+
+		// Get connection (pooled or direct)
+		this.establishConnection();
+
+		// Run migrations if needed
+		if (!this.options.skipMigrations) {
+			try {
+				// Check for incompatible database from old migration system
+				if (migrationRegistry.isIncompatibleDatabase(this.db, this.options.namespace)) {
+					logger.error(
+						`[LocalDB] Detected incompatible database for ${this.options.namespace} (from legacy migration system). Initiating recovery...`
+					);
+					await this.performRecovery();
+				} else if (migrationRegistry.needsMigration(this.db, this.options.namespace)) {
+					await migrationRegistry.runMigrations(this.db, this.options.namespace);
+				}
+			} catch (error) {
+				logger.error(
+					`[LocalDB] Migration failed for ${this.options.namespace}. Initiating automatic recovery/trapdoor...`,
+					toErrorContext(error)
+				);
+
+				await this.performRecovery();
+			}
+		}
+
+		this.initialized = true;
+	}
+
+	/**
+	 * Establish initial connection
+	 */
+	private establishConnection(): void {
+		if (this.options.usePool) {
+			this.db = connectionPool.getConnection(this.options.dbPath, this.options.consumer);
+		} else {
+			// Direct connection (for special cases)
+			this.db = new Database(this.options.dbPath);
+			this.configureDatabase(this.db);
+		}
+	}
+
+	/**
+	 * Perform recovery from migration failure
+	 * 1. Close connection
+	 * 2. Backup corrupted DB
+	 * 3. Delete corrupted DB
+	 * 4. Re-initialize fresh DB
+	 * 5. Re-run migrations
+	 */
+	private async performRecovery(): Promise<void> {
+		// 1. Close the broken database
+		if (this.options.usePool) {
+			connectionPool.closeConnection(this.options.dbPath, true);
+		} else {
+			this.db.close();
+		}
+
+		// 2. Backup the broken file
+		const backupPath = `${this.options.dbPath}.bak-${Date.now()}`;
+		try {
+			await copyFile(this.options.dbPath, backupPath);
+			logger.info(`[LocalDB] Backed up corrupted database to: ${backupPath}`);
+			await this.pruneBackupFiles();
+		} catch (backupError) {
+			logger.error(
+				'[LocalDB] Failed to backup corrupted database:',
+				toErrorContext(backupError)
+			);
+		}
+
+		// 3. Delete the broken file and WAL artifacts
+		try {
+			await unlink(this.options.dbPath);
+			await unlink(`${this.options.dbPath}-wal`).catch(() => {});
+			await unlink(`${this.options.dbPath}-shm`).catch(() => {});
+			logger.info('[LocalDB] Deleted corrupted database file.');
+		} catch (deleteError) {
+			if (isFileMissingError(deleteError)) {
+				logger.info(
+					'[LocalDB] Corrupted database file already removed during recovery. Continuing...'
+				);
+			} else {
+				logger.error(
+					'[LocalDB] Failed to delete corrupted database:',
+					toErrorContext(deleteError)
+				);
+				throw deleteError; // If we can't delete, we can't recover.
+			}
+		}
+
+		// 4. Re-establish connection (creates new DB file)
+		logger.info('[LocalDB] Re-initializing fresh database...');
+		this.establishConnection();
+
+		// 5. Re-run migrations on fresh DB
+		try {
+			if (migrationRegistry.needsMigration(this.db, this.options.namespace)) {
+				await migrationRegistry.runMigrations(this.db, this.options.namespace);
+			}
+			logger.info('[LocalDB] Recovery successful. Database reset.');
+		} catch (retryError) {
+			logger.error(
+				'[LocalDB] Recovery failed. Fresh database migration failed:',
+				toErrorContext(retryError)
+			);
+			throw retryError;
+		}
+	}
+
+	private async pruneBackupFiles(): Promise<void> {
+		const directory = dirname(this.options.dbPath);
+		const filename = basename(this.options.dbPath);
+		const backupPrefix = `${filename}.bak-`;
+		const files = await readdir(directory).catch(() => []);
+		const backups = files
+			.filter((entry) => entry.startsWith(backupPrefix))
+			.map((entry) => ({ entry, timestamp: Number(entry.slice(backupPrefix.length)) }))
+			.sort((a, b) => {
+				if (Number.isNaN(a.timestamp) || Number.isNaN(b.timestamp)) {
+					return b.entry.localeCompare(a.entry);
+				}
+				return b.timestamp - a.timestamp;
+			});
+
+		for (const backup of backups.slice(BACKUP_RETENTION_COUNT)) {
+			await unlink(`${directory}/${backup.entry}`).catch(() => {});
+		}
+	}
+
+	/**
+	 * Configure database with optimal settings (for non-pooled connections)
+	 */
+	private configureDatabase(db: Database): void {
+		db.exec('PRAGMA journal_mode = WAL;');
+		db.exec('PRAGMA busy_timeout = 5000;');
+		db.exec('PRAGMA foreign_keys = ON;');
+		db.exec('PRAGMA synchronous = NORMAL;');
+		db.exec('PRAGMA temp_store = MEMORY;');
+	}
+
+	/**
+	 * Get the underlying Database instance
+	 */
+	getDatabase(): Database {
+		if (!this.initialized) {
+			throw new Error('Database not initialized. Call initialize() first.');
+		}
+		return this.db;
+	}
+
+	/**
+	 * Close the database connection
+	 */
+	close(): void {
+		if (!this.initialized) return;
+
+		if (this.options.usePool) {
+			// Release back to pool
+			connectionPool.releaseConnection(this.options.dbPath);
+		} else {
+			// Direct close
+			this.db.close();
+		}
+
+		this.initialized = false;
+	}
+
+	/**
+	 * Check if database is healthy
+	 */
+	healthCheck(): boolean {
+		if (!this.initialized) return false;
+
+		try {
+			const result = this.db.query('SELECT 1').get();
+			return result !== null;
+		} catch {
+			return false;
+		}
+	}
+
+	/**
+	 * Get migration status for this database
+	 */
+	getMigrationStatus() {
+		if (!this.initialized) {
+			throw new Error('Database not initialized');
+		}
+
+		return migrationRegistry.getDatabaseStatus(this.db, this.options.namespace);
+	}
+}
+
+/**
+ * LocalDB Manager
+ * Main entry point for accessing local databases
+ */
+class LocalDBManager {
+	private databases = new Map<
+		string,
+		{
+			database: LocalDatabase;
+			references: number;
+		}
+	>();
+	private dbPathLocks = new Map<string, Promise<void>>();
+
+	private async withDbPathLock<T>(dbPath: string, task: () => Promise<T>): Promise<T> {
+		const prior = this.dbPathLocks.get(dbPath) ?? Promise.resolve();
+		let release: (() => void) | undefined;
+		const current = new Promise<void>((resolve) => {
+			release = resolve;
+		});
+		const queued = prior.then(() => current);
+		this.dbPathLocks.set(dbPath, queued);
+		await prior;
+		try {
+			return await task();
+		} finally {
+			release?.();
+			if (this.dbPathLocks.get(dbPath) === queued) {
+				this.dbPathLocks.delete(dbPath);
+			}
+		}
+	}
+
+	/**
+	 * Register migrations for a namespace
+	 * Must be called before getDatabase() for that namespace
+	 */
+	registerMigrations(namespace: string, migrations: Migration[]): void {
+		migrationRegistry.register(namespace, migrations);
+	}
+
+	/**
+	 * Get or create a database instance
+	 *
+	 * @param namespace Migration namespace (e.g., 'atlas', 'session')
+	 * @param dbPath Path to database file
+	 * @param consumer Consumer identifier for debugging
+	 * @returns Initialized database instance
+	 */
+	getDatabase(namespace: string, dbPath: string, consumer?: string): Promise<LocalDatabase> {
+		const key = `${namespace}:${dbPath}`;
+		return this.withDbPathLock(dbPath, async () => {
+			const existing = this.databases.get(key);
+			if (existing) {
+				existing.references += 1;
+				return existing.database;
+			}
+
+			if (!this.databases.has(key)) {
+				const db = new LocalDatabase({
+					namespace,
+					dbPath,
+					consumer
+				});
+
+				await db.initialize();
+				this.databases.set(key, {
+					database: db,
+					references: 1
+				});
+			}
+
+			return this.databases.get(key)!.database;
+		});
+	}
+
+	/**
+	 * Get a raw Database instance (auto-configured with WAL, etc.)
+	 * For when you don't need migration management
+	 */
+	getRawDatabase(dbPath: string, consumer = 'raw'): Database {
+		return connectionPool.getConnection(dbPath, consumer);
+	}
+
+	/**
+	 * Release a database instance
+	 */
+	async releaseDatabase(namespace: string, dbPath: string): Promise<void> {
+		const key = `${namespace}:${dbPath}`;
+		await this.withDbPathLock(dbPath, async () => {
+			const entry = this.databases.get(key);
+			if (!entry) return;
+
+			entry.references = Math.max(0, entry.references - 1);
+			if (entry.references === 0) {
+				await entry.database.close();
+				this.databases.delete(key);
+			}
+		});
+	}
+
+	/**
+	 * Get connection pool statistics
+	 */
+	getPoolStats() {
+		return connectionPool.getStats();
+	}
+
+	/**
+	 * Get migration registry status
+	 */
+	getMigrationStatus() {
+		return migrationRegistry.getStatus();
+	}
+
+	/**
+	 * List all registered migration namespaces
+	 */
+	listNamespaces(): string[] {
+		return migrationRegistry.listNamespaces();
+	}
+
+	/**
+	 * Close all database connections
+	 */
+	async closeAll(): Promise<void> {
+		for (const entry of this.databases.values()) {
+			await entry.database.close();
+		}
+		this.databases.clear();
+		connectionPool.closeAll();
+	}
+}
+
+// Singleton instance
+export const localdb = new LocalDBManager();

package/src/core/error-context.ts

@@ -0,0 +1,19 @@
+export function toErrorContext(error: unknown): Record<string, unknown> | undefined {
+	if (error instanceof Error) {
+		return {
+			error: error.message,
+			name: error.name,
+			stack: error.stack
+		};
+	}
+
+	if (typeof error === 'object' && error !== null && !Array.isArray(error)) {
+		return error as Record<string, unknown>;
+	}
+
+	if (error === undefined) {
+		return undefined;
+	}
+
+	return { error: String(error) };
+}