@vibesdotdev/localdb 0.0.1

package/dist/migrations/load-sql.js

@@ -0,0 +1,117 @@
+/**
+ * SQL Migration Loader
+ *
+ * Utility for loading SQL migration files from the filesystem.
+ * Uses Bun's file API for fast synchronous reads.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isLocaldbServerRuntime } from "../core/runtime.js";
+const isServerRuntime = isLocaldbServerRuntime();
+const __dirname = isServerRuntime ? dirname(fileURLToPath(import.meta.url)) : '';
+function throwIfBrowser() {
+    if (!isServerRuntime) {
+        throw new Error('SQL migrations are not available in browser builds');
+    }
+}
+/**
+ * Load a SQL migration file by namespace and filename (async)
+ *
+ * @param namespace - The migration namespace (atlas, session, external)
+ * @param filename - The SQL filename (e.g., '001-initial-schema.sql')
+ * @returns Promise resolving to the SQL content as a string
+ */
+export function loadMigrationSQL(namespace, filename) {
+    throwIfBrowser();
+    const namespaceDir = resolveMigrationNamespaceDir(namespace);
+    if (!namespaceDir) {
+        throw new Error(`Migration namespace not found: ${namespace}`);
+    }
+    const filePath = join(namespaceDir, filename);
+    if (!existsSync(filePath)) {
+        throw new Error(`Migration file not found: ${filePath}`);
+    }
+    return Bun.file(filePath).text();
+}
+/**
+ * Synchronously load a SQL migration file
+ * Uses Node's fs.readFileSync for truly synchronous reads
+ *
+ * @param namespace - The migration namespace (atlas, session, external)
+ * @param filename - The SQL filename (e.g., '001-initial-schema.sql')
+ * @returns The SQL content as a string
+ */
+export function loadMigrationSQLSync(namespace, filename) {
+    throwIfBrowser();
+    const namespaceDir = resolveMigrationNamespaceDir(namespace);
+    if (!namespaceDir) {
+        throw new Error(`Migration namespace not found: ${namespace}`);
+    }
+    const filePath = join(namespaceDir, filename);
+    if (!existsSync(filePath)) {
+        throw new Error(`Migration file not found: ${filePath}`);
+    }
+    return readFileSync(filePath, 'utf-8');
+}
+/**
+ * List all SQL files in a namespace directory
+ *
+ * @param namespace - The migration namespace (atlas, session, external)
+ * @returns Array of SQL filenames sorted by version number
+ */
+export function listMigrationFiles(namespace) {
+    throwIfBrowser();
+    const dirPath = resolveMigrationNamespaceDir(namespace);
+    if (!dirPath || !existsSync(dirPath)) {
+        return [];
+    }
+    return readdirSync(dirPath)
+        .filter((f) => f.endsWith('.sql') && !f.startsWith('.'))
+        .sort((a, b) => {
+        // Extract version numbers (e.g., '001' from '001-initial-schema.sql')
+        const versionA = parseInt(a.split('-')[0], 10);
+        const versionB = parseInt(b.split('-')[0], 10);
+        return versionA - versionB;
+    });
+}
+function resolveMigrationNamespaceDir(namespace) {
+    // If the namespace is already an absolute path that exists, use it directly.
+    // External packages (e.g. PM) pass their own migration directory as a full path.
+    if (namespace.startsWith('/') && existsSync(namespace)) {
+        return namespace;
+    }
+    // Bundled migrations are loaded from the package-local migrations directory.
+    const bundledPath = join(__dirname, namespace);
+    if (existsSync(bundledPath)) {
+        return bundledPath;
+    }
+    return null;
+}
+/**
+ * Parse version number from a migration filename
+ *
+ * @param filename - The SQL filename (e.g., '001-initial-schema.sql')
+ * @returns The version number
+ */
+export function parseVersionFromFilename(filename) {
+    const match = filename.match(/^(\d+)-/);
+    if (!match) {
+        throw new Error(`Invalid migration filename format: ${filename}`);
+    }
+    return parseInt(match[1], 10);
+}
+/**
+ * Parse migration name from a filename
+ *
+ * @param filename - The SQL filename (e.g., '001-initial-schema.sql')
+ * @returns The migration name (e.g., 'initial_schema')
+ */
+export function parseMigrationName(filename) {
+    // Remove version prefix and .sql extension
+    const withoutVersion = filename.replace(/^\d+-/, '');
+    const withoutExtension = withoutVersion.replace(/\.sql$/, '');
+    // Convert hyphens to underscores
+    return withoutExtension.replace(/-/g, '_');
+}
+//# sourceMappingURL=load-sql.js.map

package/dist/migrations/load-sql.js.map

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

package/dist/schemas/api.d.ts

@@ -0,0 +1,82 @@
+import type { Database } from 'bun:sqlite';
+export type LocaldbBinding = string | number | bigint | boolean | null | Uint8Array;
+export interface LocaldbQuery<T> {
+    all(...params: LocaldbBinding[]): T[];
+    get(...params: LocaldbBinding[]): T | null;
+}
+export interface LocaldbStatementResult {
+    changes: number;
+    lastInsertRowid: number | bigint | null;
+}
+export interface LocaldbStatement {
+    run(...params: LocaldbBinding[]): LocaldbStatementResult;
+    get<T>(...params: LocaldbBinding[]): T;
+    all<T>(...params: LocaldbBinding[]): T[];
+}
+export interface LocaldbRawDatabase {
+    exec(sql: string): void;
+    query<T>(sql: string): LocaldbQuery<T>;
+    prepare(sql: string): LocaldbStatement;
+    run(sql: string, ...params: LocaldbBinding[]): LocaldbStatementResult;
+}
+export type MigrationFunction = (db: Database) => void | Promise<void>;
+export interface Migration {
+    version: number;
+    name: string;
+    up: MigrationFunction;
+    down?: MigrationFunction;
+}
+export interface LocalDatabase {
+    initialize(): Promise<void>;
+    getDatabase(): Database;
+    close(): void;
+}
+export interface ConnectionStats {
+    total: number;
+    active: number;
+    idle: number;
+    connections: Array<{
+        path: string;
+        refCount: number;
+        ageMs: number;
+        consumer: string;
+    }>;
+}
+export interface MigrationRegistryApi {
+    listNamespaces(): string[];
+    getMigrations(namespace: string): Migration[];
+    getDatabaseStatus(db: Database, namespace: string): {
+        namespace: string;
+        currentVersion: number;
+        targetVersion: number;
+        pendingMigrations: number;
+        migrations: Array<{
+            version: number;
+            name: string;
+            applied: boolean;
+        }>;
+    };
+    needsMigration(db: Database, namespace: string): boolean;
+    runMigrations(db: Database, namespace: string): Promise<void>;
+    getStatus(): Array<{
+        namespace: string;
+        currentVersion: number;
+        targetVersion: number;
+        pendingMigrations: number;
+    }>;
+}
+export interface ConnectionPoolApi {
+    getStats(): ConnectionStats;
+    closeAll(): void;
+}
+export interface LocaldbApi {
+    registerMigrations(namespace: string, migrations: Migration[]): void;
+    getDatabase(namespace: string, dbPath: string, consumer?: string): Promise<LocalDatabase>;
+    getRawDatabase(dbPath: string, consumer?: string): Database;
+    releaseDatabase(namespace: string, dbPath: string): Promise<void>;
+    getPoolStats(): ConnectionStats;
+    getMigrationStatus(): ReturnType<MigrationRegistryApi['getStatus']>;
+    listNamespaces(): string[];
+    closeAll(): Promise<void>;
+}
+//# sourceMappingURL=api.d.ts.map

package/dist/schemas/api.d.ts.map

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

package/dist/schemas/api.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=api.js.map

package/dist/schemas/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/schemas/api.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,146 @@
+{
+  "name": "@vibesdotdev/localdb",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/localdb.plugin.d.ts",
+      "bun": "./src/localdb.plugin.ts",
+      "import": "./dist/localdb.plugin.js",
+      "default": "./dist/localdb.plugin.js"
+    },
+    "./cloud.plugin": {
+      "types": "./dist/localdb.cloud.plugin.d.ts",
+      "bun": "./src/localdb.cloud.plugin.ts",
+      "import": "./dist/localdb.cloud.plugin.js",
+      "default": "./dist/localdb.cloud.plugin.js"
+    },
+    "./schemas": {
+      "types": "./dist/schemas/api.d.ts",
+      "bun": "./src/schemas/api.ts",
+      "import": "./dist/schemas/api.js",
+      "default": "./dist/schemas/api.js"
+    },
+    "./migrations/load-sql": {
+      "types": "./dist/migrations/load-sql.d.ts",
+      "bun": "./src/migrations/load-sql.ts",
+      "import": "./dist/migrations/load-sql.js",
+      "default": "./dist/migrations/load-sql.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "bun": "./src/*.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    },
+    "./*.js": {
+      "types": "./dist/*.d.ts",
+      "bun": "./src/*.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    },
+    "./*/*": {
+      "types": "./dist/*/*.d.ts",
+      "bun": "./src/*/*.ts",
+      "import": "./dist/*/*.js",
+      "default": "./dist/*/*.js"
+    },
+    "./*/*.js": {
+      "types": "./dist/*/*.d.ts",
+      "bun": "./src/*/*.ts",
+      "import": "./dist/*/*.js",
+      "default": "./dist/*/*.js"
+    },
+    "./*/*/*": {
+      "types": "./dist/*/*/*.d.ts",
+      "bun": "./src/*/*/*.ts",
+      "import": "./dist/*/*/*.js",
+      "default": "./dist/*/*/*.js"
+    },
+    "./*/*/*.js": {
+      "types": "./dist/*/*/*.d.ts",
+      "bun": "./src/*/*/*.ts",
+      "import": "./dist/*/*/*.js",
+      "default": "./dist/*/*/*.js"
+    },
+    "./*/*/*/*": {
+      "types": "./dist/*/*/*/*.d.ts",
+      "bun": "./src/*/*/*/*.ts",
+      "import": "./dist/*/*/*/*.js",
+      "default": "./dist/*/*/*/*.js"
+    },
+    "./*/*/*/*.js": {
+      "types": "./dist/*/*/*/*.d.ts",
+      "bun": "./src/*/*/*/*.ts",
+      "import": "./dist/*/*/*/*.js",
+      "default": "./dist/*/*/*/*.js"
+    },
+    "./*/*/*/*/*": {
+      "types": "./dist/*/*/*/*/*.d.ts",
+      "bun": "./src/*/*/*/*/*.ts",
+      "import": "./dist/*/*/*/*/*.js",
+      "default": "./dist/*/*/*/*/*.js"
+    },
+    "./*/*/*/*/*.js": {
+      "types": "./dist/*/*/*/*/*.d.ts",
+      "bun": "./src/*/*/*/*/*.ts",
+      "import": "./dist/*/*/*/*/*.js",
+      "default": "./dist/*/*/*/*/*.js"
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vibesdotdev/monorepo.git",
+    "directory": "packages/localdb"
+  },
+  "peerDependencies": {
+    "@vibesdotdev/runtime": "0.0.1",
+    "@vibesdotdev/logging": "0.0.1",
+    "@vibesdotdev/cli": "0.0.1"
+  },
+  "scripts": {
+    "test": "bun test",
+    "check": "bun --bun tsc -p tsconfig.json --noEmit",
+    "build": "tsc -p tsconfig.json"
+  },
+  "license": "MIT",
+  "files": [
+    "dist",
+    "src",
+    "bin",
+    "README.md",
+    "SPEC.md",
+    "LICENSE",
+    "!src/**/__tests__/**",
+    "!src/**/__stubs__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/*.spec.tsx",
+    "!dist/**/__tests__/**",
+    "!dist/**/__stubs__/**",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.d.ts.map",
+    "!dist/**/*.spec.js",
+    "!dist/**/*.spec.js.map",
+    "!dist/**/*.spec.d.ts",
+    "!dist/**/*.spec.d.ts.map"
+  ],
+  "vibes": {
+    "visibility": "public-framework"
+  }
+}

package/src/cli/commands/_shared.consumer.ts

@@ -0,0 +1,20 @@
+import { resolve } from 'node:path';
+
+export const databasePathsByNamespace: Record<string, string> = {
+	atlas: '.vibes/atlas/vibes.db',
+	session: '.vibes/session/sessions.db'
+};
+
+export function resolveDatabasePathForNamespace(namespace: string): string | undefined {
+	return databasePathsByNamespace[namespace];
+}
+
+export function resolveFromCwd(p: string): string {
+	return resolve(process.cwd(), p);
+}
+
+export function formatAgeMs(ageMs: number): string {
+	const ageMin = Math.floor(ageMs / 60000);
+	const ageSec = Math.floor((ageMs % 60000) / 1000);
+	return ageMin > 0 ? `${ageMin}m ${ageSec}s` : `${ageSec}s`;
+}

package/src/cli/commands/migrate/dev.localdb.migrate.cli-command.descriptor.ts

@@ -0,0 +1,20 @@
+/**
+ * Dev LocalDB Migrate CLI Command Descriptor
+ */
+
+import { createRuntimeAsset } from '@vibesdotdev/runtime';
+
+export default createRuntimeAsset({
+	id: 'dev.localdb.migrate',
+	kind: 'cli/command',
+	name: 'migrate',
+	description: 'Run pending migrations',
+	group: 'dev.localdb',
+	surfaces: ['cli'],
+	hardware: ['consumer'],
+	enabled: true,
+	options: [
+		{ flags: '--namespace <name>', description: 'Run migrations for a specific namespace' },
+		{ flags: '--dry-run', description: 'Show pending migrations without applying them' }
+	]
+});

package/src/cli/commands/migrate/dev.localdb.migrate.cli-command.impl.consumer.ts

@@ -0,0 +1,97 @@
+import { existsSync } from 'node:fs';
+import { getVibesRuntime } from '@vibesdotdev/runtime';
+import { requestCLIExit, type UIContext } from '@vibesdotdev/cli/providers';
+import type { LocaldbApi, MigrationRegistryApi } from '../../..';
+import { resolveDatabasePathForNamespace, resolveFromCwd } from '../_shared.consumer';
+
+export default {
+	async execute(_args: Record<string, unknown>, opts: Record<string, unknown>): Promise<void> {
+		const runtime = getVibesRuntime();
+		const ui = (await runtime.context('cli/ui')) as UIContext;
+		const localdb = (await runtime.context('dev/localdb')) as LocaldbApi;
+
+		const namespaceOpt = typeof opts.namespace === 'string' ? opts.namespace : undefined;
+		const dryRun = Boolean(opts.dryRun);
+
+		ui.log(`\n=== LocalDB Migrate${dryRun ? ' (Dry Run)' : ''} ===\n`);
+
+		const namespaces = localdb.listNamespaces();
+		if (namespaces.length === 0) {
+			ui.info('No migration namespaces registered.');
+			return;
+		}
+
+		const namespacesToMigrate = namespaceOpt
+			? namespaces.filter((ns) => ns === namespaceOpt)
+			: namespaces;
+
+		if (namespacesToMigrate.length === 0) {
+			ui.error(`Namespace '${namespaceOpt}' not found.`);
+			ui.info(`Available namespaces: ${namespaces.join(', ')}`);
+			requestCLIExit(1);
+		}
+
+		const { migrationRegistry } =
+			(await import('../../../core/migration-registry')) as {
+				migrationRegistry: MigrationRegistryApi;
+			};
+
+		let migratedCount = 0;
+		let errorCount = 0;
+
+		for (const ns of namespacesToMigrate) {
+			const dbPath = resolveDatabasePathForNamespace(ns);
+			if (!dbPath) {
+				ui.warn(`Skipping '${ns}': no known database path`);
+				continue;
+			}
+
+			const fullPath = resolveFromCwd(dbPath);
+			if (!existsSync(fullPath)) {
+				ui.warn(`Skipping '${ns}': database not found (${dbPath})`);
+				continue;
+			}
+
+			ui.log(`\nNamespace: ${ns}`);
+			ui.log(`Database: ${dbPath}`);
+
+			try {
+				const db = localdb.getRawDatabase(fullPath, 'localdb-migrate');
+				const needsMigration = migrationRegistry.needsMigration(db, ns);
+
+				if (!needsMigration) {
+					ui.success('Already up to date');
+					continue;
+				}
+
+				const status = migrationRegistry.getDatabaseStatus(db, ns);
+				ui.log(
+					`Pending: ${status.pendingMigrations} migration(s) (v${status.currentVersion} → v${status.targetVersion})`
+				);
+
+				if (dryRun) {
+					ui.log('Would apply:');
+					for (const m of status.migrations) {
+						if (!m.applied) ui.log(`  • v${m.version}: ${m.name}`);
+					}
+				} else {
+					await migrationRegistry.runMigrations(db, ns);
+					ui.success('Migrations completed');
+					migratedCount++;
+				}
+			} catch (error) {
+				ui.error(`Error: ${String(error)}`);
+				errorCount++;
+			}
+		}
+
+		ui.log('\n' + '─'.repeat(50));
+		if (dryRun) {
+			ui.info(`Dry run complete. Checked ${namespacesToMigrate.length} namespace(s).`);
+		} else {
+			ui.info(`Migration complete: ${migratedCount} migrated, ${errorCount} errors`);
+		}
+
+		if (errorCount > 0) requestCLIExit(1);
+	}
+};

package/src/cli/commands/namespaces/dev.localdb.namespaces.cli-command.descriptor.ts

@@ -0,0 +1,17 @@
+/**
+ * Dev LocalDB Namespaces CLI Command Descriptor
+ */
+
+import { createRuntimeAsset } from '@vibesdotdev/runtime';
+
+export default createRuntimeAsset({
+	id: 'dev.localdb.namespaces',
+	kind: 'cli/command',
+	name: 'namespaces',
+	description: 'List registered migration namespaces',
+	group: 'dev.localdb',
+	surfaces: ['cli'],
+	hardware: ['consumer'],
+	enabled: true,
+	options: [{ flags: '--verbose', description: 'Show migration details for each namespace' }]
+});

package/src/cli/commands/namespaces/dev.localdb.namespaces.cli-command.impl.ts

@@ -0,0 +1,46 @@
+import { getVibesRuntime } from '@vibesdotdev/runtime';
+import type { UIContext } from '@vibesdotdev/cli/providers';
+import type { LocaldbApi, MigrationRegistryApi } from '../../..';
+
+export default {
+	async execute(_args: Record<string, unknown>, opts: Record<string, unknown>): Promise<void> {
+		const runtime = getVibesRuntime();
+		const ui = (await runtime.context('cli/ui')) as UIContext;
+		const localdb = (await runtime.context('dev/localdb')) as LocaldbApi;
+
+		const verbose = Boolean(opts.verbose);
+
+		ui.log('\n=== Registered Migration Namespaces ===\n');
+
+		const namespaces = localdb.listNamespaces();
+		if (namespaces.length === 0) {
+			ui.info('No migration namespaces registered.');
+			ui.info('Namespaces are registered when their modules are loaded.');
+			ui.info('Try running a command that uses the database first.');
+			return;
+		}
+
+		if (!verbose) {
+			ui.table(namespaces.map((ns) => ({ namespace: ns })));
+			ui.info('\nUse --verbose to see migration details\n');
+			return;
+		}
+
+		const { migrationRegistry } =
+			(await import('../../../core/migration-registry')) as {
+				migrationRegistry: MigrationRegistryApi;
+			};
+
+		for (const ns of namespaces) {
+			ui.log(`\nNamespace: ${ns}`);
+			const migrations = migrationRegistry.getMigrations(ns);
+			ui.log(`Migrations: ${migrations.length}`);
+
+			for (const m of migrations) {
+				ui.log(`  • v${m.version}: ${m.name}${m.down ? ' (reversible)' : ''}`);
+			}
+		}
+
+		ui.log('\n');
+	}
+};

package/src/cli/commands/pools/dev.localdb.pools.cli-command.descriptor.ts

@@ -0,0 +1,16 @@
+/**
+ * Dev LocalDB Pools CLI Command Descriptor
+ */
+
+import { createRuntimeAsset } from '@vibesdotdev/runtime';
+
+export default createRuntimeAsset({
+	id: 'dev.localdb.pools',
+	kind: 'cli/command',
+	name: 'pools',
+	description: 'Show connection pool statistics',
+	group: 'dev.localdb',
+	surfaces: ['cli'],
+	hardware: ['consumer'],
+	enabled: true
+});

package/src/cli/commands/pools/dev.localdb.pools.cli-command.impl.ts

@@ -0,0 +1,37 @@
+import { getVibesRuntime } from '@vibesdotdev/runtime';
+import type { UIContext } from '@vibesdotdev/cli/providers';
+import type { LocaldbApi } from '../../..';
+import { formatAgeMs } from '../_shared.consumer';
+
+export default {
+	async execute(_args: Record<string, unknown>, _opts: Record<string, unknown>): Promise<void> {
+		const runtime = getVibesRuntime();
+		const ui = (await runtime.context('cli/ui')) as UIContext;
+		const localdb = (await runtime.context('dev/localdb')) as LocaldbApi;
+
+		ui.log('\n=== Connection Pool Statistics ===\n');
+
+		const stats = localdb.getPoolStats();
+
+		ui.log(`Total Connections: ${stats.total}`);
+		ui.log(`Active (in use):   ${stats.active}`);
+		ui.log(`Idle (pooled):     ${stats.idle}`);
+
+		if (stats.connections.length === 0) {
+			ui.info('\nNo active connections.\n');
+			return;
+		}
+
+		ui.log('\nConnections:\n' + '─'.repeat(80));
+		ui.table(
+			stats.connections.map((c) => ({
+				path: c.path,
+				status: c.refCount > 0 ? 'ACTIVE' : 'IDLE',
+				refs: c.refCount,
+				age: formatAgeMs(c.ageMs),
+				consumer: c.consumer
+			}))
+		);
+		ui.log('');
+	}
+};

package/src/cli/commands/query/dev.localdb.query.cli-command.descriptor.ts

@@ -0,0 +1,21 @@
+/**
+ * Dev LocalDB Query CLI Command Descriptor
+ */
+
+import { createRuntimeAsset } from '@vibesdotdev/runtime';
+
+export default createRuntimeAsset({
+	id: 'dev.localdb.query',
+	kind: 'cli/command',
+	name: 'query',
+	description: 'Execute an SQL query on a database',
+	group: 'dev.localdb',
+	surfaces: ['cli'],
+	hardware: ['consumer'],
+	enabled: true,
+	arguments: [{ name: 'sql', description: 'SQL statement to execute', required: true }],
+	options: [
+		{ flags: '--db <path>', description: 'Database file path (required)' },
+		{ flags: '--json', description: 'Output results as JSON' }
+	]
+});