@jacebenson/jsn 4.3.10-dev.67 → 4.3.11-dev.68

package/src/auth.js

@@ -5,76 +5,20 @@
 // same instance have separate credential slots.
 
 import fs from 'node:fs';
-import path from 'node:path';
-import crypto from 'node:crypto';
-import { execFileSync } from 'node:child_process';
 import { password as passwordPrompt } from './prompts.js';
-import { globalConfigDir, normalizeInstanceURL } from './config.js';
+import { normalizeInstanceURL } from './config.js';
 import { errAuth } from './errors.js';
 import { pendingBrowserLogin } from './browser-auth.js';
+import { defaultCredentialStore } from './auth/credential-store.js';
+import { savePKCEState, loadPKCEState, removePKCEState, getOAuthClientID, generatePKCE, buildAuthURL, REDIRECT_URI } from './auth/oauth.js';
+import { parseBrowserSessionInput } from './auth/browser-session.js';
+import { normalizeAuthMethod, normalizeAuthSource, sourceMethod, probeFailure, classifyProbeError, classifyCredentialState } from './auth/credential-state.js';
 
-// ─── Credential key helpers ───
-
-/**
- * Sanitize an instance URL into a filesystem/arg-safe key part.
- *
- * Whitelist approach (issue #143 findings #2/#3): first map the `://`
- * protocol separator to `_` exactly as the Go version's encoding does
- * (so existing keyring keys like `https_dev437538.service-now.com` keep
- * matching), then drop everything outside [a-zA-Z0-9._-]. Blacklist
- * stripping of just `/` and `:` left quotes, `$()`, backticks, `;`,
- * spaces, and backslashes — which broke out of double-quoted shell args
- * in keyring calls and, on Windows, out of path.join() credential dirs.
- */
-export function sanitizeKeyPart(instance) {
-  return instance.replace(/:\/\//g, '_').replace(/[^a-zA-Z0-9._-]/g, '_');
-}
-
-/**
- * Build a compound key for credential storage: <username>@<instance>
- * When username is omitted (legacy), just the normalized instance URL is used.
- */
-function credKey(instance, username) {
-  const normalized = sanitizeKeyPart(instance);
-  if (!username) return normalized;
-  return `${username.replace(/[^a-zA-Z0-9._@-]/g, '_')}@${normalized}`;
-}
-
-// ─── PKCE state persistence (shared with Go version) ───
-
-function pkceStatePath(instance, username) {
-  const dir = path.join(globalConfigDir(), 'pkce');
-  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  // A known profile identity gets its own pending-login slot. Keep the bare
-  // instance slot for legacy/no-profile flows, where no identity exists yet.
-  const filename = credKey(instance, username) + '.json';
-  return path.join(dir, filename);
-}
-
-function savePKCEState(instance, pkce, username) {
-  const filePath = pkceStatePath(instance, username);
-  fs.writeFileSync(filePath, JSON.stringify(pkce, null, 2), { mode: 0o600 });
-}
-
-function loadPKCEState(instance, username) {
-  try {
-    const data = fs.readFileSync(pkceStatePath(instance, username), 'utf-8');
-    return JSON.parse(data);
-  } catch {
-    return null;
-  }
-}
-
-function removePKCEState(instance, username) {
-  try {
-    fs.unlinkSync(pkceStatePath(instance, username));
-  } catch {
-    // ignore
-  }
-}
+// Preserve the public auth module API while implementation stays separated.
+export { sanitizeKeyPart } from './auth/credential-store.js';
+export { parseBrowserSessionInput } from './auth/browser-session.js';
+export { classifyCredentialState } from './auth/credential-state.js';
 
-const DEFAULT_OAUTH_CLIENT_ID = '543e5655f77746a28228c6009a599dfb';
-const REDIRECT_URI = '/sdk-oauth.do';
 
 // ─── Basic auth from environment variables ───
 // SN_USERNAME / SN_PASSWORD — global credentials
@@ -110,322 +54,10 @@ function getBasicAuthFromEnv(instance) {
   return null;
 }
 
-// Keychain constants — same as Go version (internal/auth/store.go)
-const KEYRING_SERVICE = 'servicenow-cli';
-const KEYRING_ATTR_SERVICE = 'service';
-const KEYRING_ATTR_USERNAME = 'username';
-
-function credentialsFilePath(key) {
-  const dir = path.join(globalConfigDir(), 'credentials');
-  // Match Go's filename encoding: replace :// and / and : with _
-  const filename = key + '.json';
-  return path.join(dir, filename);
-}
-
-function credentialsPath(key) {
-  const filePath = credentialsFilePath(key);
-  fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
-  return filePath;
-}
-
-function getOAuthClientID() {
-  return process.env.SERVICENOW_OAUTH_CLIENT_ID || DEFAULT_OAUTH_CLIENT_ID;
-}
-
-function generatePKCE() {
-  const verifier = crypto.randomBytes(32).toString('base64url');
-  const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
-  const state = crypto.randomBytes(16).toString('base64url');
-  return { code_verifier: verifier, code_challenge: challenge, state };
-}
-
-function buildAuthURL(instanceURL, clientID, pkce) {
-  const u = new URL('/oauth_auth.do', instanceURL);
-  u.searchParams.set('response_type', 'code');
-  u.searchParams.set('client_id', clientID);
-  u.searchParams.set('redirect_uri', REDIRECT_URI);
-  u.searchParams.set('state', pkce.state);
-  u.searchParams.set('code_challenge', pkce.code_challenge);
-  u.searchParams.set('code_challenge_method', 'S256');
-  u.searchParams.set('scope', 'openid');
-  u.searchParams.set('approval_prompt', 'force');
-  return u.toString();
-}
-
-// ─── Keyring via secret-tool (libsecret, same backend as Go's go-keyring) ───
-
-function keyringLookup(key) {
-  try {
-    // execFileSync with an arg array — no shell, so `key` can never
-    // break out into command injection (issue #143 finding #2).
-    const result = execFileSync(
-      'secret-tool',
-      ['lookup', KEYRING_ATTR_SERVICE, KEYRING_SERVICE, KEYRING_ATTR_USERNAME, key],
-      { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' }
-    );
-    const trimmed = result.trim();
-    if (!trimmed) return null;
-    const parsed = JSON.parse(trimmed);
-    // Spread all fields from keyring first, then normalize known fields
-    // so username, password, and other extras are preserved.
-    return {
-      ...parsed,
-      auth_method: parsed.auth_method || 'oauth',
-      access_token: parsed.access_token || parsed.AccessToken || '',
-      refresh_token: parsed.refresh_token || parsed.RefreshToken || '',
-      expires_at: parsed.expires_at || parsed.ExpiresAt || 0,
-      created_at: parsed.created_at || parsed.CreatedAt || 0,
-      auth_source: ['oauth', 'env_token', 'env_basic', undefined].includes(parsed.auth_source)
-        ? (parsed.auth_method === 'gck' ? 'gck' : 'keyring')
-        : parsed.auth_source,
-    };
-  } catch {
-    return null;
-  }
-}
-
-function keyringStore(key, creds) {
-  try {
-    execFileSync(
-      'secret-tool',
-      ['store', `--label=Password for '${key}' on '${KEYRING_SERVICE}'`,
-        KEYRING_ATTR_SERVICE, KEYRING_SERVICE, KEYRING_ATTR_USERNAME, key],
-      { stdio: ['pipe', 'ignore', 'ignore'], input: JSON.stringify(creds) }
-    );
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function keyringDelete(key) {
-  try {
-    execFileSync(
-      'secret-tool',
-      ['clear', KEYRING_ATTR_SERVICE, KEYRING_SERVICE, KEYRING_ATTR_USERNAME, key],
-      { stdio: 'ignore' }
-    );
-  } catch {
-    // ignore
-  }
-}
-
-// ─── File-based storage (fallback) ───
-
-/**
- * Load credentials for an instance keyed by <username>@<instance>.
- * When username is omitted (legacy configs without profile user), uses
- * bare instance key for lookup.
- */
-function loadCredentials(instance, username, injectedStore) {
-  if (injectedStore) return injectedStore.load(instance, username);
-  const key = username ? credKey(instance, username) : credKey(instance);
-  const keyringCreds = keyringLookup(key);
-  if (keyringCreds) {
-    return {
-      ...keyringCreds,
-      auth_source: keyringCreds.auth_source || (keyringCreds.auth_method === 'gck' ? 'gck' : 'keyring'),
-    };
-  }
-  try {
-    const data = fs.readFileSync(credentialsFilePath(key), 'utf-8');
-    const creds = JSON.parse(data);
-    return {
-      ...creds,
-      auth_source: ['oauth', 'env_token', 'env_basic', undefined].includes(creds.auth_source)
-        ? (creds.auth_method === 'gck' ? 'gck' : 'file')
-        : creds.auth_source,
-    };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Save credentials for an instance.
- * Uses <username>@<instance> key when username is available.
- */
-function saveCredentials(instance, creds, username, injectedStore) {
-  if (injectedStore) {
-    creds.last_seen = creds.last_seen || Math.floor(Date.now() / 1000);
-    return injectedStore.save(instance, creds, username);
-  }
-  const key = username ? credKey(instance, username) : credKey(instance);
-  // Stamp last_seen on every credential save
-  creds.last_seen = creds.last_seen || Math.floor(Date.now() / 1000);
-  // Try keyring first, fall back to file
-  if (!keyringStore(key, creds)) {
-    fs.writeFileSync(credentialsPath(key), JSON.stringify(creds, null, 2), { mode: 0o600 });
-  }
-}
-
-/**
- * Delete credentials for an instance keyed by <username>@<instance>.
- */
-function deleteCredentials(instance, username, injectedStore) {
-  if (injectedStore) return injectedStore.delete(instance, username);
-  const key = username ? credKey(instance, username) : credKey(instance);
-  keyringDelete(key);
-  try {
-    fs.unlinkSync(credentialsPath(key));
-  } catch {
-    // ignore
-  }
-}
-
-const defaultCredentialStore = {
-  load: loadCredentials,
-  save: saveCredentials,
-  delete: deleteCredentials,
-};
-
 function askHidden(promptText) {
   return passwordPrompt({ message: promptText });
 }
 
-/**
- * Extract the browser session token and cookies from pasted DevTools headers
- * or a "Copy as cURL" command. Only these two values are retained.
- */
-export function parseBrowserSessionInput(input) {
-  const text = String(input || '');
-  const tokenMatch = text.match(/(?:x-usertoken|x-user-token)\s*:\s*([^\s'";,]+)/i);
-  const cookieArgMatch = text.match(/(?:^|\s)(?:-b|--cookie)\s+(['"])(.*?)\1/s);
-  const quotedCookieMatch = text.match(/cookie\s*:\s*(['"])(.*?)\1/i);
-  const plainCookieMatch = text.match(/cookie\s*:\s*([^\r\n]+)/i);
-  const token = tokenMatch?.[1]?.trim() || '';
-  const cookies = (cookieArgMatch?.[2] || quotedCookieMatch?.[2] || plainCookieMatch?.[1] || '')
-    .trim()
-    .replace(/['"`]\s*(?:\\\s*)?$/, '');
-  if (!token) throw errAuth('No X-UserToken header found');
-  if (!cookies) throw errAuth('No Cookie header found. Paste the complete request headers or cURL command.');
-  return { auth_method: 'gck', access_token: token, cookies, auth_source: 'gck' };
-}
-
-const AUTH_METHODS = new Set(['oauth', 'basic', 'gck']);
-const AUTH_SOURCES = new Set(['env_token', 'env_basic', 'gck', 'keyring', 'file', 'unavailable']);
-
-function normalizeAuthMethod(value, fallback = 'unconfigured') {
-  return AUTH_METHODS.has(value) ? value : fallback;
-}
-
-function normalizeAuthSource(value, fallback = 'unavailable') {
-  return AUTH_SOURCES.has(value) ? value : fallback;
-}
-
-function sourceMethod(source) {
-  return { env_token: 'oauth', env_basic: 'basic', gck: 'gck' }[source] || null;
-}
-
-const PROBE_FAILURES = {
-  missing_credentials: {
-    message: 'Credentials are not available for this profile.',
-    hint: 'Run: jsn auth login',
-  },
-  credentials_expired: {
-    message: 'Credentials have expired and cannot be refreshed.',
-    hint: 'Run: jsn auth login',
-  },
-  refresh_required: {
-    message: 'Credentials require refresh before probing.',
-    hint: 'Run: jsn auth refresh',
-  },
-  refresh_failed: {
-    message: 'Credential refresh failed before the authenticated probe.',
-    hint: 'Run: jsn auth login',
-  },
-  invalid_browser_session: {
-    message: 'Browser session credentials are incomplete or invalid.',
-    hint: 'Capture a fresh ServiceNow browser request and run: jsn auth login --gck',
-  },
-  malformed_credentials: {
-    message: 'Credentials are malformed for the selected authentication method.',
-    hint: 'Run: jsn auth login',
-  },
-  permission_denied: {
-    message: 'The authenticated user lacks permission for the current-user probe.',
-    hint: 'Ask an administrator to grant access to the sys_user table/API.',
-  },
-  unauthorized: {
-    message: 'The instance rejected the selected credentials.',
-    hint: 'Run: jsn auth login',
-  },
-  network: {
-    message: 'The authenticated probe could not reach the instance.',
-    hint: 'Check your internet connection and instance URL.',
-  },
-  unknown: {
-    message: 'The authenticated probe failed for an unknown reason.',
-    hint: 'Retry the probe; if it persists, check the instance logs.',
-  },
-  missing_instance: {
-    message: 'No instance is configured for this profile.',
-    hint: 'Set an instance URL and run: jsn auth login',
-  },
-  sdk_construction_failed: {
-    message: 'The authenticated probe could not be initialized for this profile.',
-    hint: 'Check the profile configuration and run: jsn auth status again',
-  },
-};
-
-const PROBE_CLASSIFICATIONS = {
-  missing_credentials: 'unavailable', credentials_expired: 'expired', refresh_required: 'refresh_required',
-  refresh_failed: 'refresh_failed', invalid_browser_session: 'browser_session_invalid',
-  malformed_credentials: 'malformed', permission_denied: 'permission_denied', unauthorized: 'unauthorized',
-  network: 'network_error', unknown: 'unknown',
-  missing_instance: 'unavailable', sdk_construction_failed: 'configuration_error',
-};
-
-function probeFailure(code, status = 'failed') {
-  return { status, code, classification: PROBE_CLASSIFICATIONS[code] || 'unknown', ...PROBE_FAILURES[code] };
-}
-
-function classifyProbeError(error, method) {
-  if (error?.status === 401 || error?.status === 403) {
-    return error.status === 403 ? 'permission_denied' : 'unauthorized';
-  }
-  if (error?.code === 'network_error' || ['ECONNREFUSED', 'ENOTFOUND', 'ETIMEDOUT'].includes(error?.code)) {
-    return 'network';
-  }
-  const text = String(error?.message || '').toLowerCase();
-  if (error?.code === 'auth_error' && text.includes('refresh')) return 'refresh_failed';
-  if (method === 'gck' && error?.code === 'auth_error') return 'invalid_browser_session';
-  return 'unknown';
-}
-
-/**
- * Classify credentials without returning or logging any credential material.
- * This is deliberately pure so diagnostics cannot refresh, persist, or probe.
- */
-export function classifyCredentialState(credentials, method, now = Date.now()) {
-  if (!credentials) return 'missing';
-  if (!AUTH_METHODS.has(method)) return 'malformed';
-
-  if (method === 'basic') {
-    const hasUser = typeof credentials.username === 'string' && credentials.username.length > 0;
-    const hasPassword = typeof credentials.password === 'string' && credentials.password.length > 0;
-    return hasUser && hasPassword ? 'available' : 'malformed';
-  }
-
-  if (method === 'gck') {
-    const hasToken = typeof credentials.access_token === 'string' && credentials.access_token.length > 0;
-    const hasCookies = typeof credentials.cookies === 'string' && credentials.cookies.length > 0;
-    return hasToken && hasCookies ? 'available' : 'malformed';
-  }
-
-  if (credentials.access_token !== undefined && typeof credentials.access_token !== 'string') return 'malformed';
-  if (credentials.refresh_token !== undefined && typeof credentials.refresh_token !== 'string') return 'malformed';
-
-  const hasToken = typeof credentials.access_token === 'string' && credentials.access_token.length > 0;
-  if (!hasToken) return credentials.refresh_token ? 'refreshable' : 'missing';
-  if (credentials.expires_at !== undefined && credentials.expires_at !== null && credentials.expires_at !== 0) {
-    const expiresAt = Number(credentials.expires_at);
-    if (!Number.isFinite(expiresAt)) return 'malformed';
-    if (now >= (expiresAt - 300) * 1000) return credentials.refresh_token ? 'refreshable' : 'expired';
-  }
-  return 'available';
-}
-
 export class AuthManager {
   /**
    * @param {object} identity — the resolved-identity provider. Production
@@ -1002,4 +634,5 @@ export class AuthManager {
   }
 }
 
-export { saveCredentials, loadCredentials, deleteCredentials, askHidden };
+export { saveCredentials, loadCredentials, deleteCredentials } from './auth/credential-store.js';
+export { askHidden };

package/src/cli.js

@@ -303,7 +303,7 @@ export function buildCLI() {
 
         if (shouldCheck) {
           const version = getVersion();
-          checkLatest().then(latest => {
+          checkLatest({ background: true }).then(latest => {
             if (latest && version !== latest) {
               process.stderr.write(`\n⚠ jsn ${latest} available (you have ${version}) — run "npm install -g @jacebenson/jsn" to update\n\n`);
             }
@@ -584,3 +584,5 @@ export function buildCLI() {
 
 // Run if invoked directly (bin/jsn.js calls cli.parse())
 export const cli = buildCLI();
+
+export { cancelBackgroundChecks } from './commands/version.js';

package/src/commands/docs/db.js

@@ -132,8 +132,13 @@ export function openDocsDb(opts = {}) {
   const dbPath = opts.dbPath || getDocsDbPath();
   ensureDocsCacheDir();
   const db = new Database(dbPath);
-  db.exec('PRAGMA journal_mode = WAL');
-  return db;
+  try {
+    db.exec('PRAGMA journal_mode = WAL');
+    return db;
+  } catch (error) {
+    closeDocsDb(db);
+    throw error;
+  }
 }
 
 export function closeDocsDb(db) {
@@ -246,3 +251,18 @@ export function getDocsIndexStats(db) {
 export function setMeta(db, key, value) {
   db.prepare('INSERT OR REPLACE INTO meta(key, value) VALUES(?, ?)').run(key, value);
 }
+
+/** Own a synchronous docs connection and roll back unfinished work on failure. */
+export function withDocsDb(opts, operation) {
+  const db = openDocsDb(opts);
+  try {
+    return operation(db);
+  } catch (error) {
+    if (db.inTransaction) {
+      try { db.exec('ROLLBACK'); } catch { /* Preserve the original error. */ }
+    }
+    throw error;
+  } finally {
+    closeDocsDb(db);
+  }
+}

package/src/commands/docs/docs.js

@@ -4,16 +4,6 @@ import fs from 'node:fs';
 import path from 'node:path';
 import net from 'node:net';
 import process from 'node:process';
-import {
-  getDocsDbPath, getDocsSourceDir, getDocsSourceMarkdownDir, docsDbExists,
-  openDocsDb, closeDocsDb, getDocsIndexStats,
-} from './db.js';
-import { syncDocs } from './sync.js';
-import { refreshDocs } from './refresh.js';
-import { embedDocs } from './embed.js';
-import { searchDocs, getDocByIdOrPath } from './search.js';
-import { serveDocs } from './serve.js';
-import { syncCommunity, listCommunityDocs } from './community.js';
 import { declareCapabilities } from '../../capabilities.js';
 import { formatCommandList } from '../../helpers.js';
 
@@ -39,6 +29,8 @@ export function docsCmd(wrap) {
             .option('no-embed', { type: 'boolean', describe: 'Skip HRR semantic embeddings' })
             .option('no-ingest', { type: 'boolean', describe: 'Clone/pull only; do not rebuild index' }),
           handler: wrap(async (argv, app) => {
+            const { getDocsDbPath, getDocsSourceMarkdownDir } = await import('./db.js');
+            const { syncDocs } = await import('./sync.js');
             const result = syncDocs({
               markdownDir: getDocsSourceMarkdownDir(),
               dbPath: getDocsDbPath(),
@@ -52,6 +44,7 @@ export function docsCmd(wrap) {
           command: 'status',
           describe: 'Show docs database status',
           handler: wrap(async (argv, app) => {
+            const { getDocsDbPath, getDocsSourceDir, getDocsSourceMarkdownDir, docsDbExists, withDocsDb, getDocsIndexStats } = await import('./db.js');
             const dbPath = getDocsDbPath();
             const repoDir = getDocsSourceDir();
             const markdownDir = getDocsSourceMarkdownDir();
@@ -60,12 +53,10 @@ export function docsCmd(wrap) {
 
             let state, embedded, documents, bundles, docTypes, syncedAt, dbSize;
             if (dbExists) {
-              const db = openDocsDb();
-              const stats = getDocsIndexStats(db);
+              const stats = withDocsDb({}, (db) => getDocsIndexStats(db));
               ({ documents, bundles, docTypes, syncedAt } = stats);
               const stat = fs.statSync(dbPath);
               dbSize = stat.size;
-              closeDocsDb(db);
 
               embedded = stats.embeddedCount >= documents && documents > 0;
               if (embedded) state = 'ready';
@@ -108,6 +99,7 @@ export function docsCmd(wrap) {
             .option('doc-type', { type: 'string', describe: 'Filter by doc type' })
             .option('mode', { type: 'string', choices: ['keyword', 'hybrid'], default: 'hybrid', describe: 'Search mode' }),
           handler: wrap(async (argv, app) => {
+            const { searchDocs } = await import('./search.js');
             const result = searchDocs({
               query: argv.query,
               limit: argv.limit,
@@ -154,6 +146,7 @@ export function docsCmd(wrap) {
             .positional('id-or-path', { type: 'string', describe: 'Document id (number) or file path' })
             .option('lines', { type: 'number', default: 80, describe: 'Lines of body to show in terminal (use --json for full content)' }),
           handler: wrap(async (argv, app) => {
+            const { getDocByIdOrPath } = await import('./search.js');
             const idOrPath = argv['id-or-path'];
             const row = getDocByIdOrPath(idOrPath);
 
@@ -192,6 +185,7 @@ export function docsCmd(wrap) {
             .option('host', { type: 'string', default: '127.0.0.1', describe: 'Bind address' })
             .option('expose', { type: 'boolean', default: false, describe: 'Bind to 0.0.0.0 to expose on the network' }),
           handler: wrap(async (argv, _app) => {
+            const { serveDocs } = await import('./serve.js');
             try {
               const host = argv.expose ? '0.0.0.0' : argv.host;
               await serveDocs({ port: argv.port, host });
@@ -205,6 +199,7 @@ export function docsCmd(wrap) {
           command: 'embed',
           describe: 'Backfill or refresh HRR semantic embeddings',
           handler: wrap(async (argv, app) => {
+            const { embedDocs } = await import('./embed.js');
             const result = embedDocs();
             app.ok(result, { summary: `Embedded ${result.embedded} of ${result.total} docs` });
           }),
@@ -213,6 +208,8 @@ export function docsCmd(wrap) {
           command: 'refresh',
           describe: 'Incrementally refresh docs.db from existing source clone',
           handler: wrap(async (argv, app) => {
+            const { getDocsSourceMarkdownDir } = await import('./db.js');
+            const { refreshDocs } = await import('./refresh.js');
             const result = refreshDocs({ docsDir: getDocsSourceMarkdownDir() });
             app.ok(result, { summary: `Refresh complete: +${result.added} ~${result.updated} -${result.removed} =${result.unchanged}` });
           }),
@@ -230,6 +227,7 @@ export function docsCmd(wrap) {
                 .option('sources', { type: 'string', describe: 'Path to a community-sources.json (default: bundled)' })
                 .option('delay-ms', { type: 'number', describe: 'Delay between article fetches (default: 500)' }),
               handler: wrap(async (argv, app) => {
+                const { syncCommunity } = await import('./community.js');
                 const result = await syncCommunity({
                   sourcesFile: argv.sources,
                   expand: argv.expand === true,
@@ -245,6 +243,7 @@ export function docsCmd(wrap) {
               command: 'list',
               describe: 'List community docs currently in the index',
               handler: wrap(async (argv, app) => {
+                const { listCommunityDocs } = await import('./community.js');
                 const result = listCommunityDocs();
                 const lines = result.docs.map((d) => `[${d.id}] ${d.title || d.path} (${d.doc_type})`);
                 app.ok({
@@ -258,6 +257,7 @@ export function docsCmd(wrap) {
         });
     },
     handler: wrap(async (argv, app) => {
+      const { getDocsDbPath } = await import('./db.js');
       const subcommands = argv.subcommands || [];
       const summary = 'jsn docs — ServiceNow documentation search (sync, status, search, show, serve).';
       app.ok({

package/src/commands/docs/embed.js

@@ -1,7 +1,7 @@
 // Populate HRR phase-vector embeddings for semantic reranking.
 
 import fs from 'node:fs';
-import { openDocsDb, closeDocsDb, getDocsDbPath } from './db.js';
+import { withDocsDb, getDocsDbPath } from './db.js';
 import { encodeText, phasesToBytes, docSurface, DEFAULT_DIM } from './hrr.js';
 
 export function embedDocs(opts = {}) {
@@ -11,36 +11,36 @@ export function embedDocs(opts = {}) {
     throw new Error(`Database not found: ${dbPath}. Run "jsn docs sync" first.`);
   }
 
-  const db = openDocsDb({ dbPath });
-
-  const cols = db.prepare('PRAGMA table_info(docs)').all();
-  if (!cols.some((c) => c.name === 'hrr_vector')) {
-    db.exec('ALTER TABLE docs ADD COLUMN hrr_vector BLOB');
-  }
-
-  db.exec("CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT)");
-  db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES('hrr_dim', ?)").run(String(DEFAULT_DIM));
-
-  const rows = db.prepare('SELECT id, title, body FROM docs WHERE hrr_vector IS NULL').all();
-  const total = db.prepare('SELECT COUNT(*) AS n FROM docs').get().n;
-
-  const update = db.prepare('UPDATE docs SET hrr_vector = ? WHERE id = ?');
-  const started = Date.now();
-  let n = 0;
-
-  db.exec('BEGIN');
-  for (const row of rows) {
-    const surface = docSurface(row.title, row.body);
-    const vec = encodeText(surface, DEFAULT_DIM);
-    update.run(phasesToBytes(vec), row.id);
-    n++;
-    if (n % 5000 === 0) process.stderr.write(`  ...${n}\n`);
-  }
-  db.exec('COMMIT');
-  db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
-  db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES('embeddings', ?)").run('true');
-  closeDocsDb(db);
-
-  const secs = ((Date.now() - started) / 1000).toFixed(1);
-  return { embedded: n, total, secs, dbPath };
+  return withDocsDb({ dbPath }, (db) => {
+
+    const cols = db.prepare('PRAGMA table_info(docs)').all();
+    if (!cols.some((c) => c.name === 'hrr_vector')) {
+      db.exec('ALTER TABLE docs ADD COLUMN hrr_vector BLOB');
+    }
+
+    db.exec("CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT)");
+    db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES('hrr_dim', ?)").run(String(DEFAULT_DIM));
+
+    const rows = db.prepare('SELECT id, title, body FROM docs WHERE hrr_vector IS NULL').all();
+    const total = db.prepare('SELECT COUNT(*) AS n FROM docs').get().n;
+
+    const update = db.prepare('UPDATE docs SET hrr_vector = ? WHERE id = ?');
+    const started = Date.now();
+    let n = 0;
+
+    db.exec('BEGIN');
+    for (const row of rows) {
+      const surface = docSurface(row.title, row.body);
+      const vec = encodeText(surface, DEFAULT_DIM);
+      update.run(phasesToBytes(vec), row.id);
+      n++;
+      if (n % 5000 === 0) process.stderr.write(`  ...${n}\n`);
+    }
+    db.exec('COMMIT');
+    db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+    db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES('embeddings', ?)").run('true');
+
+    const secs = ((Date.now() - started) / 1000).toFixed(1);
+    return { embedded: n, total, secs, dbPath };
+  });
 }