@vibesdotdev/localdb 0.0.1

package/src/migrations/atlas/003-config-id-dedup.sql

@@ -0,0 +1,31 @@
+-- Atlas Migration 003: Deduplicated Indexing by Config ID
+-- Symbols, files, and edges now belong to config_id (project+branch) not run_id
+-- This enables incremental indexing and prevents duplicate results
+
+-- Add config_id to symbols for direct config association
+ALTER TABLE symbols ADD COLUMN config_id TEXT REFERENCES index_configs(id) ON DELETE CASCADE;
+
+-- Add config_id to files for direct config association
+ALTER TABLE files ADD COLUMN config_id TEXT REFERENCES index_configs(id) ON DELETE CASCADE;
+
+-- Add last_indexed_at to files to track when file was last processed
+ALTER TABLE files ADD COLUMN last_indexed_at TEXT;
+
+-- Add config_id to edges for direct config association
+ALTER TABLE edges ADD COLUMN config_id TEXT REFERENCES index_configs(id) ON DELETE CASCADE;
+
+-- Backfill config_id from run_id for existing data
+UPDATE symbols SET config_id = (SELECT config_id FROM index_runs WHERE index_runs.id = symbols.run_id);
+UPDATE files SET config_id = (SELECT config_id FROM index_runs WHERE index_runs.id = files.run_id);
+UPDATE files SET last_indexed_at = created_at WHERE last_indexed_at IS NULL;
+UPDATE edges SET config_id = (SELECT config_id FROM index_runs WHERE index_runs.id = edges.run_id);
+
+-- Create indexes for config_id lookups
+CREATE INDEX IF NOT EXISTS idx_symbols_config ON symbols(config_id);
+CREATE INDEX IF NOT EXISTS idx_files_config ON files(config_id);
+CREATE INDEX IF NOT EXISTS idx_edges_config ON edges(config_id);
+
+-- Create unique constraint to prevent duplicate files per config
+CREATE UNIQUE INDEX IF NOT EXISTS idx_files_config_path ON files(config_id, path);
+
+-- Note: We keep run_id for audit/history but queries should use config_id

package/src/migrations/atlas/004-fix-on-conflict-constraints.sql

@@ -0,0 +1,25 @@
+-- Atlas Migration 004: Fix ON CONFLICT Constraint for Files Table
+-- Migration 3 created a UNIQUE INDEX which doesn't work with ON CONFLICT
+-- SQLite requires a table-level UNIQUE constraint for ON CONFLICT to work
+
+-- Step 1: Delete duplicate files, keeping only the most recently indexed one
+DELETE FROM files WHERE rowid NOT IN (
+  SELECT MAX(rowid) FROM files GROUP BY config_id, path
+);
+
+-- Step 2: Drop the broken unique index if it exists (may not exist due to duplicates)
+DROP INDEX IF EXISTS idx_files_config_path;
+
+-- Step 3: Create proper unique index now that duplicates are removed
+-- Note: In SQLite, a UNIQUE INDEX does work with ON CONFLICT when created on
+-- a table that already has the constraint enforced (no duplicates exist)
+CREATE UNIQUE INDEX idx_files_config_path ON files(config_id, path);
+
+-- Step 4: Same fix for symbols - dedupe by (config_id, file_path, name, kind, start_line)
+DELETE FROM symbols WHERE rowid NOT IN (
+  SELECT MAX(rowid) FROM symbols GROUP BY config_id, file_path, name, kind, start_line
+);
+
+-- Step 5: Create unique index for symbols deduplication
+CREATE UNIQUE INDEX IF NOT EXISTS idx_symbols_config_unique
+  ON symbols(config_id, file_path, name, kind, start_line);

package/src/migrations/atlas/005-diagnostics.sql

@@ -0,0 +1,66 @@
+-- 005-diagnostics.sql
+-- Atlas diagnostics + signals storage
+
+-- Diagnostics captured from LSP / tooling output.
+-- Stored per config_id (index_configs.id) and file_path (workspace-relative).
+
+CREATE TABLE IF NOT EXISTS diagnostics (
+  id TEXT PRIMARY KEY,
+  config_id TEXT NOT NULL,
+  file_path TEXT NOT NULL,
+  file_id TEXT,
+  file_mtime INTEGER,
+
+  line INTEGER NOT NULL,
+  column INTEGER,
+  end_line INTEGER,
+  end_column INTEGER,
+
+  source TEXT NOT NULL,
+  severity TEXT NOT NULL,
+  code TEXT,
+  message TEXT NOT NULL,
+  raw_line TEXT,
+
+  detected_at TEXT NOT NULL,
+  stale INTEGER NOT NULL DEFAULT 0,
+
+  FOREIGN KEY(config_id) REFERENCES index_configs(id)
+);
+
+CREATE INDEX IF NOT EXISTS diagnostics_by_config_file ON diagnostics (config_id, file_path);
+CREATE INDEX IF NOT EXISTS diagnostics_by_config_severity ON diagnostics (config_id, severity);
+CREATE INDEX IF NOT EXISTS diagnostics_by_config_stale ON diagnostics (config_id, stale);
+
+-- De-duplication key: same diagnostic in same file range.
+CREATE UNIQUE INDEX IF NOT EXISTS diagnostics_dedupe
+  ON diagnostics (
+    config_id,
+    file_path,
+    line,
+    COALESCE(column, 1),
+    COALESCE(end_line, line),
+    COALESCE(end_column, COALESCE(column, 1)),
+    source,
+    severity,
+    COALESCE(code, ''),
+    message
+  );
+
+-- Full-text search on diagnostic message.
+CREATE VIRTUAL TABLE IF NOT EXISTS diagnostics_fts
+  USING fts5(message, content='diagnostics', content_rowid='rowid');
+
+CREATE TRIGGER IF NOT EXISTS diagnostics_ai AFTER INSERT ON diagnostics BEGIN
+  INSERT INTO diagnostics_fts(rowid, message) VALUES (new.rowid, new.message);
+END;
+
+CREATE TRIGGER IF NOT EXISTS diagnostics_ad AFTER DELETE ON diagnostics BEGIN
+  INSERT INTO diagnostics_fts(diagnostics_fts, rowid, message) VALUES ('delete', old.rowid, old.message);
+END;
+
+CREATE TRIGGER IF NOT EXISTS diagnostics_au AFTER UPDATE ON diagnostics BEGIN
+  INSERT INTO diagnostics_fts(diagnostics_fts, rowid, message) VALUES ('delete', old.rowid, old.message);
+  INSERT INTO diagnostics_fts(rowid, message) VALUES (new.rowid, new.message);
+END;
+

package/src/migrations/atlas/006-diagnostic-summaries.sql

@@ -0,0 +1,65 @@
+-- 006-diagnostic-summaries.sql
+-- Aggregated diagnostics snapshot for fast workspace-wide cache reads.
+
+CREATE TABLE IF NOT EXISTS diagnostic_file_summaries (
+  config_id TEXT NOT NULL,
+  file_path TEXT NOT NULL,
+  file_mtime INTEGER,
+
+  diagnostic_count INTEGER NOT NULL DEFAULT 0,
+  error_count INTEGER NOT NULL DEFAULT 0,
+  warning_count INTEGER NOT NULL DEFAULT 0,
+  info_count INTEGER NOT NULL DEFAULT 0,
+  hint_count INTEGER NOT NULL DEFAULT 0,
+
+  detected_at TEXT NOT NULL,
+  stale INTEGER NOT NULL DEFAULT 0,
+
+  PRIMARY KEY (config_id, file_path),
+  FOREIGN KEY(config_id) REFERENCES index_configs(id)
+);
+
+CREATE INDEX IF NOT EXISTS diagnostic_file_summaries_by_config
+  ON diagnostic_file_summaries (config_id);
+
+CREATE INDEX IF NOT EXISTS diagnostic_file_summaries_by_config_stale
+  ON diagnostic_file_summaries (config_id, stale);
+
+-- Backfill summaries from existing diagnostics table.
+INSERT INTO diagnostic_file_summaries (
+  config_id,
+  file_path,
+  file_mtime,
+  diagnostic_count,
+  error_count,
+  warning_count,
+  info_count,
+  hint_count,
+  detected_at,
+  stale
+)
+SELECT
+  d.config_id,
+  d.file_path,
+  MAX(CASE WHEN d.stale = 0 THEN d.file_mtime END) AS file_mtime,
+  SUM(CASE WHEN d.stale = 0 THEN 1 ELSE 0 END) AS diagnostic_count,
+  SUM(CASE WHEN d.stale = 0 AND d.severity = 'error' THEN 1 ELSE 0 END) AS error_count,
+  SUM(CASE WHEN d.stale = 0 AND d.severity = 'warning' THEN 1 ELSE 0 END) AS warning_count,
+  SUM(CASE WHEN d.stale = 0 AND d.severity = 'info' THEN 1 ELSE 0 END) AS info_count,
+  SUM(CASE WHEN d.stale = 0 AND d.severity = 'hint' THEN 1 ELSE 0 END) AS hint_count,
+  MAX(d.detected_at) AS detected_at,
+  CASE
+    WHEN SUM(CASE WHEN d.stale = 0 THEN 1 ELSE 0 END) > 0 THEN 0
+    ELSE 1
+  END AS stale
+FROM diagnostics d
+GROUP BY d.config_id, d.file_path
+ON CONFLICT(config_id, file_path) DO UPDATE SET
+  file_mtime = excluded.file_mtime,
+  diagnostic_count = excluded.diagnostic_count,
+  error_count = excluded.error_count,
+  warning_count = excluded.warning_count,
+  info_count = excluded.info_count,
+  hint_count = excluded.hint_count,
+  detected_at = excluded.detected_at,
+  stale = excluded.stale;

package/src/migrations/atlas/007-diagnostic-slice.sql

@@ -0,0 +1,83 @@
+-- 007-diagnostic-slice.sql
+-- Slice-level aggregates for diagnostics backlog and feature-level health.
+
+ALTER TABLE diagnostic_file_summaries
+  ADD COLUMN slice_path TEXT;
+
+CREATE INDEX IF NOT EXISTS diagnostic_file_summaries_by_config_slice
+  ON diagnostic_file_summaries (config_id, slice_path);
+
+CREATE INDEX IF NOT EXISTS diagnostic_file_summaries_by_config_slice_stale
+  ON diagnostic_file_summaries (config_id, slice_path, stale);
+
+CREATE TABLE IF NOT EXISTS diagnostic_slice_summaries (
+  config_id TEXT NOT NULL,
+  slice_path TEXT NOT NULL,
+
+  file_count INTEGER NOT NULL DEFAULT 0,
+  stale_file_count INTEGER NOT NULL DEFAULT 0,
+  diagnostic_file_count INTEGER NOT NULL DEFAULT 0,
+  diagnostic_count INTEGER NOT NULL DEFAULT 0,
+  error_count INTEGER NOT NULL DEFAULT 0,
+  warning_count INTEGER NOT NULL DEFAULT 0,
+  info_count INTEGER NOT NULL DEFAULT 0,
+  hint_count INTEGER NOT NULL DEFAULT 0,
+
+  detected_at TEXT,
+  updated_at TEXT NOT NULL,
+
+  PRIMARY KEY (config_id, slice_path),
+  FOREIGN KEY(config_id) REFERENCES index_configs(id)
+);
+
+CREATE INDEX IF NOT EXISTS diagnostic_slice_summaries_by_config
+  ON diagnostic_slice_summaries (config_id);
+
+CREATE INDEX IF NOT EXISTS diagnostic_slice_summaries_by_config_errors
+  ON diagnostic_slice_summaries (config_id, error_count DESC);
+
+CREATE INDEX IF NOT EXISTS diagnostic_slice_summaries_by_config_stale
+  ON diagnostic_slice_summaries (config_id, stale_file_count DESC);
+
+-- Best-effort backfill from already-sliced file summaries.
+INSERT INTO diagnostic_slice_summaries (
+  config_id,
+  slice_path,
+  file_count,
+  stale_file_count,
+  diagnostic_file_count,
+  diagnostic_count,
+  error_count,
+  warning_count,
+  info_count,
+  hint_count,
+  detected_at,
+  updated_at
+)
+SELECT
+  config_id,
+  slice_path,
+  COUNT(*) AS file_count,
+  SUM(CASE WHEN stale = 1 THEN 1 ELSE 0 END) AS stale_file_count,
+  SUM(CASE WHEN stale = 0 AND diagnostic_count > 0 THEN 1 ELSE 0 END) AS diagnostic_file_count,
+  SUM(CASE WHEN stale = 0 THEN diagnostic_count ELSE 0 END) AS diagnostic_count,
+  SUM(CASE WHEN stale = 0 THEN error_count ELSE 0 END) AS error_count,
+  SUM(CASE WHEN stale = 0 THEN warning_count ELSE 0 END) AS warning_count,
+  SUM(CASE WHEN stale = 0 THEN info_count ELSE 0 END) AS info_count,
+  SUM(CASE WHEN stale = 0 THEN hint_count ELSE 0 END) AS hint_count,
+  MAX(detected_at) AS detected_at,
+  CURRENT_TIMESTAMP AS updated_at
+FROM diagnostic_file_summaries
+WHERE slice_path IS NOT NULL AND slice_path != ''
+GROUP BY config_id, slice_path
+ON CONFLICT(config_id, slice_path) DO UPDATE SET
+  file_count = excluded.file_count,
+  stale_file_count = excluded.stale_file_count,
+  diagnostic_file_count = excluded.diagnostic_file_count,
+  diagnostic_count = excluded.diagnostic_count,
+  error_count = excluded.error_count,
+  warning_count = excluded.warning_count,
+  info_count = excluded.info_count,
+  hint_count = excluded.hint_count,
+  detected_at = excluded.detected_at,
+  updated_at = excluded.updated_at;

package/src/migrations/load-sql.ts

@@ -0,0 +1,133 @@
+/**
+ * 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.ts';
+
+const isServerRuntime = isLocaldbServerRuntime();
+const __dirname = isServerRuntime ? dirname(fileURLToPath(import.meta.url)) : '';
+
+function throwIfBrowser(): void {
+	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: string, filename: string): Promise<string> {
+	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: string, filename: string): string {
+	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: string): string[] {
+	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: string): string | null {
+	// 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: string): number {
+	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: string): string {
+	// Remove version prefix and .sql extension
+	const withoutVersion = filename.replace(/^\d+-/, '');
+	const withoutExtension = withoutVersion.replace(/\.sql$/, '');
+	// Convert hyphens to underscores
+	return withoutExtension.replace(/-/g, '_');
+}

package/src/schemas/api.ts

@@ -0,0 +1,92 @@
+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>;
+}