fix: four CLI improvements (embed --db, concurrent DB safety, prerelease update suppression, incremental build logging)

- Add missing --db flag to `embed` command, passing customDbPath to buildEmbeddings
- Add busy_timeout pragma (5s) and advisory lockfile to openDb/closeDb for concurrent access safety
- Suppress update-check notifications for prerelease/dev versions (contains '-')
- Log changed/removed file names at debug level during incremental builds

Impact: 8 functions changed, 14 affected

Author: github-actions[bot]

src/builder.js

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { loadConfig } from './config.js';
 import { EXTENSIONS, IGNORE_DIRS, normalizePath } from './constants.js';
-import { getBuildMeta, initSchema, openDb, setBuildMeta } from './db.js';
+import { closeDb, getBuildMeta, initSchema, openDb, setBuildMeta } from './db.js';
 import { readJournal, writeJournalHeader } from './journal.js';
 import { debug, info, warn } from './logger.js';
 import { getActiveEngine, parseFilesAuto } from './parser.js';
@@ -418,7 +418,7 @@ export async function buildGraph(rootDir, opts = {}) {
       }
     }
     info('No changes detected. Graph is up to date.');
-    db.close();
+    closeDb(db);
     writeJournalHeader(rootDir, Date.now());
     return;
   }
@@ -442,6 +442,8 @@ export async function buildGraph(rootDir, opts = {}) {
     );
   } else {
     info(`Incremental: ${parseChanges.length} changed, ${removed.length} removed`);
+    if (parseChanges.length > 0) debug(`Changed files: ${parseChanges.map((c) => c.relPath).join(', ')}`);
+    if (removed.length > 0) debug(`Removed files: ${removed.join(', ')}`);
     // Remove embeddings/metrics/edges/nodes for changed and removed files
     // Embeddings must be deleted BEFORE nodes (we need node IDs to find them)
     const deleteEmbeddingsForFile = hasEmbeddings
@@ -958,7 +960,7 @@ export async function buildGraph(rootDir, opts = {}) {
     debug(`Failed to write build metadata: ${err.message}`);
   }
 
-  db.close();
+  closeDb(db);
 
   // Write journal header after successful build
   writeJournalHeader(rootDir, Date.now());

src/cli.js

@@ -470,6 +470,7 @@ program
     `Embedding strategy: ${EMBEDDING_STRATEGIES.join(', ')}. "structured" uses graph context (callers/callees), "source" embeds raw code`,
     'structured',
   )
+  .option('-d, --db <path>', 'Path to graph.db')
   .action(async (dir, opts) => {
     if (!EMBEDDING_STRATEGIES.includes(opts.strategy)) {
       console.error(
@@ -479,7 +480,7 @@ program
     }
     const root = path.resolve(dir || '.');
     const model = opts.model || config.embeddings?.model || DEFAULT_MODEL;
-    await buildEmbeddings(root, model, undefined, { strategy: opts.strategy });
+    await buildEmbeddings(root, model, opts.db, { strategy: opts.strategy });
   });
 
 program

src/db.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import Database from 'better-sqlite3';
-import { debug } from './logger.js';
+import { debug, warn } from './logger.js';
 
 // ─── Schema Migrations ─────────────────────────────────────────────────
 export const MIGRATIONS = [
@@ -134,11 +134,59 @@ export function setBuildMeta(db, entries) {
 export function openDb(dbPath) {
   const dir = path.dirname(dbPath);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  acquireAdvisoryLock(dbPath);
   const db = new Database(dbPath);
   db.pragma('journal_mode = WAL');
+  db.pragma('busy_timeout = 5000');
+  db.__lockPath = `${dbPath}.lock`;
   return db;
 }
 
+export function closeDb(db) {
+  db.close();
+  if (db.__lockPath) releaseAdvisoryLock(db.__lockPath);
+}
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function acquireAdvisoryLock(dbPath) {
+  const lockPath = `${dbPath}.lock`;
+  try {
+    if (fs.existsSync(lockPath)) {
+      const content = fs.readFileSync(lockPath, 'utf-8').trim();
+      const pid = Number(content);
+      if (pid && pid !== process.pid && isProcessAlive(pid)) {
+        warn(`Another process (PID ${pid}) may be using this database. Proceeding with caution.`);
+      }
+    }
+  } catch {
+    /* ignore read errors */
+  }
+  try {
+    fs.writeFileSync(lockPath, String(process.pid), 'utf-8');
+  } catch {
+    /* best-effort */
+  }
+}
+
+function releaseAdvisoryLock(lockPath) {
+  try {
+    const content = fs.readFileSync(lockPath, 'utf-8').trim();
+    if (Number(content) === process.pid) {
+      fs.unlinkSync(lockPath);
+    }
+  } catch {
+    /* ignore */
+  }
+}
+
 export function initSchema(db) {
   db.exec(`CREATE TABLE IF NOT EXISTS schema_version (version INTEGER NOT NULL DEFAULT 0)`);
 

src/update-check.js

@@ -109,6 +109,7 @@ export async function checkForUpdates(currentVersion, options = {}) {
   if (process.env.CI) return null;
   if (process.env.NO_UPDATE_CHECK) return null;
   if (!process.stderr.isTTY) return null;
+  if (currentVersion.includes('-')) return null;
 
   const cachePath = options.cachePath || CACHE_PATH;
   const fetchFn = options._fetchLatest || fetchLatestVersion;

src/watcher.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { readFileSafe } from './builder.js';
 import { EXTENSIONS, IGNORE_DIRS, normalizePath } from './constants.js';
-import { initSchema, openDb } from './db.js';
+import { closeDb, initSchema, openDb } from './db.js';
 import { appendJournalEntries } from './journal.js';
 import { info, warn } from './logger.js';
 import { createParseTreeCache, getActiveEngine, parseFileIncremental } from './parser.js';
@@ -261,7 +261,7 @@ export async function watchProject(rootDir, opts = {}) {
       }
     }
     if (cache) cache.clear();
-    db.close();
+    closeDb(db);
     process.exit(0);
   });
 }

tests/unit/db.test.js

@@ -8,6 +8,7 @@ import path from 'node:path';
 import Database from 'better-sqlite3';
 import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
 import {
+  closeDb,
   findDbPath,
   getBuildMeta,
   initSchema,
@@ -91,6 +92,24 @@ describe('openDb', () => {
     expect(row.name).toBe('test');
     db.close();
   });
+
+  it('sets busy_timeout pragma to 5000', () => {
+    const dbPath = path.join(tmpDir, 'busy-timeout.db');
+    const db = openDb(dbPath);
+    const timeout = db.pragma('busy_timeout', { simple: true });
+    expect(timeout).toBe(5000);
+    closeDb(db);
+  });
+
+  it('creates lock file on open and removes on closeDb', () => {
+    const dbPath = path.join(tmpDir, 'locktest.db');
+    const lockPath = `${dbPath}.lock`;
+    const db = openDb(dbPath);
+    expect(fs.existsSync(lockPath)).toBe(true);
+    expect(fs.readFileSync(lockPath, 'utf-8').trim()).toBe(String(process.pid));
+    closeDb(db);
+    expect(fs.existsSync(lockPath)).toBe(false);
+  });
 });
 
 describe('findDbPath', () => {

tests/unit/update-check.test.js

@@ -240,6 +240,34 @@ describe('checkForUpdates', () => {
     }
   });
 
+  it('returns null for prerelease versions (e.g. beta)', async () => {
+    const origIsTTY = process.stderr.isTTY;
+    process.stderr.isTTY = true;
+    try {
+      const result = await checkForUpdates('2.0.0-beta.1', {
+        cachePath,
+        _fetchLatest: async () => '2.0.0',
+      });
+      expect(result).toBeNull();
+    } finally {
+      process.stderr.isTTY = origIsTTY;
+    }
+  });
+
+  it('returns null for dev versions (e.g. -dev)', async () => {
+    const origIsTTY = process.stderr.isTTY;
+    process.stderr.isTTY = true;
+    try {
+      const result = await checkForUpdates('1.5.0-dev', {
+        cachePath,
+        _fetchLatest: async () => '2.0.0',
+      });
+      expect(result).toBeNull();
+    } finally {
+      process.stderr.isTTY = origIsTTY;
+    }
+  });
+
   it('returns null from fresh cache when version is current', async () => {
     const origIsTTY = process.stderr.isTTY;
     process.stderr.isTTY = true;