@jacebenson/jsn 4.0.4 → 4.2.0

package/src/commands/dev/logs.js

@@ -92,6 +92,103 @@ export function logsCmd(wrap) {
             const level = getStringField(record, 'level') || '?';
             app.ok(record, { summary: `${logIcon(level)} ${level}: ${(getStringField(record, 'message') || '').substring(0, 80)}` });
           }),
+        })
+        .command({
+          command: 'follow',
+          describe: 'Tail system logs in real time (Ctrl+C to stop)',
+          builder: (y) => y
+            .option('query', { type: 'string', describe: 'Additional encoded query filter (e.g. "sourceLIKEscript")' })
+            .option('level', { type: 'string', describe: 'Filter by level (error, warning, information)' })
+            .option('source', { type: 'string', describe: 'Filter by source' })
+            .option('tail', { type: 'number', default: 0, describe: 'Show the last N existing entries first, then follow' })
+            .option('interval', { type: 'number', default: 2000, describe: 'Poll interval in ms (min 500)' }),
+          handler: wrap(async (argv, app) => {
+            app.requireInstance();
+            const filters = [argv.query || ''];
+            if (argv.level) filters.push(`level=${argv.level}`);
+            if (argv.source) filters.push(`sourceLIKE${argv.source}`);
+            const base = filters.filter(Boolean).join('^');
+            const intervalMs = Math.max(500, argv.interval || 2000);
+            let watermark = '';
+            const seen = new Set();
+
+            // sys_created_on> comparisons run in UTC; the display_value is server-local
+            // time, so a display-based watermark never advances on a non-UTC instance.
+            // Normalize the raw UTC .value to 'YYYY-MM-DD HH:mm:ss' for the query and
+            // lexicographic comparison. The sys_id seen-set guarantees a row can never
+            // re-print even if two polls fall in the same timestamp bucket.
+            const toQueryTs = (v) => {
+              if (typeof v !== 'string') return v;
+              return v.replace('T', ' ').replace(/\.\d{1,3}[Zz]?$/, '').replace(/[Zz]$/, '');
+            };
+            const rawTs = (r) => {
+              const f = r.sys_created_on;
+              if (f && typeof f === 'object') {
+                const v = f.value != null ? f.value : f.display_value;
+                return v ? toQueryTs(String(v)) : '';
+              }
+              return f ? toQueryTs(String(f)) : '';
+            };
+            const sysIdOf = (r) => getStringField(r, 'sys_id');
+
+            const formatRow = (r) => {
+              const ts = getStringField(r, 'sys_created_on');
+              const level = getStringField(r, 'level');
+              const src = getStringField(r, 'source');
+              const msg = getStringField(r, 'message');
+              return `${ts} ${logIcon(level).padEnd(2)} [${src}] ${msg}`;
+            };
+
+            const emit = (r) => {
+              const id = sysIdOf(r);
+              if (id) {
+                if (seen.has(id)) return; // never re-print a row this run
+                seen.add(id);
+              }
+              const ts = rawTs(r);
+              if (ts && !watermark) watermark = ts;
+              else if (ts && ts > watermark) watermark = ts;
+              process.stdout.write(formatRow(r) + '\n');
+            };
+
+            const fetchNew = async () => {
+              const params = new URLSearchParams();
+              params.set('sysparm_display_value', 'all');
+              params.set('sysparm_fields', 'sys_created_on,level,source,message,sys_id');
+              params.set('sysparm_limit', '100');
+              let q = watermark ? `sys_created_on>${watermark}^ORDERBYsys_created_on` : 'ORDERBYsys_created_on';
+              if (base) q = `${base}^${q}`;
+              params.set('sysparm_query', q);
+              let records;
+              try { records = await app.sdk.list('syslog', params); } catch (err) {
+                process.stderr.write(`⚠ poll error: ${err.message}\n`);
+                return;
+              }
+              for (const r of records) emit(r);
+            };
+
+            // Optional backfill: show last N newest-first, then follow.
+            if (argv.tail > 0) {
+              const params = new URLSearchParams();
+              params.set('sysparm_display_value', 'all');
+              params.set('sysparm_fields', 'sys_created_on,level,source,message,sys_id');
+              let q = base ? `${base}^ORDERBYDESCsys_created_on` : 'ORDERBYDESCsys_created_on';
+              params.set('sysparm_query', q);
+              params.set('sysparm_limit', String(argv.tail));
+              try {
+                const recent = await app.sdk.list('syslog', params);
+                const ordered = [...recent].reverse(); // oldest->newest on screen
+                for (const r of ordered) emit(r);
+              } catch (err) { process.stderr.write(`⚠ backfill error: ${err.message}\n`); }
+            }
+
+            await fetchNew();
+            const timer = setInterval(fetchNew, intervalMs);
+            process.stdout.write(`\n[jsn logs follow] watching syslog every ${intervalMs}ms — Ctrl+C to stop\n`);
+            const stop = () => { clearInterval(timer); process.exit(0); };
+            process.on('SIGINT', stop);
+            process.on('SIGTERM', stop);
+          }),
         });
     },
     handler: () => {

package/src/commands/dev/rest.js

@@ -1,3 +1,9 @@
+import { declareCapabilities } from '../../capabilities.js';
+
+// Raw REST passthrough — can hit any endpoint with any method, so the whole
+// command is a mutation surface on read-only profiles (both spellings).
+declareCapabilities('rest', { mutationSubcommands: [''], devAlias: true });
+
 export function restCmd(wrap) {
   return {
     command: 'rest [endpoint]',

package/src/commands/dev/restmessage.js

@@ -5,6 +5,7 @@ export const restmessageCmd = (wrap) => buildDevCmd('restmessage', 'sys_rest_mes
   ['name', 'endpoint', 'active', 'sys_scope'], wrap, {
     singular: 'REST message',
     scopeValidation: true,
+    devAlias: false,
     onShow: async (record, app) => {
       const sysID = getStringField(record, 'sys_id') || '';
       if (!sysID) return;

package/src/commands/dev/scopes.js

@@ -1,5 +1,50 @@
 import { formatRecordForDisplay, getStringField, interactiveList, assertSafeExactMatch } from '../../helpers.js';
 import { requireCurrentUserSysId, setCurrentApplication } from '../../context.js';
+import { declareCapabilities } from '../../capabilities.js';
+import { unwrapSysId } from '../../resolve-record.js';
+
+declareCapabilities('scopes', { mutationSubcommands: ['create', 'set'], devAlias: true });
+
+/**
+ * Resolve a scope identifier to a single sys_scope record.
+ *
+ * Precedence (issue #190):
+ *   1. sys_id — tried first so explicit selectors win. This catches both the
+ *      32-hex form AND the canonical Global record, whose sys_id is the
+ *      literal string 'global' (not hex, so isSysId() alone would miss it).
+ *   2. scope value — e.g. 'global', 'x_417611_daves_o_0'. When several rows
+ *      share the value (a third-party app can also report scope=global), the
+ *      canonical Global record (sys_id='global') is preferred; any other tie
+ *      is an ambiguous error naming the candidates.
+ *   3. name — the display name, last resort.
+ *
+ * @param {object} sdk — SDK handle (uses sdk.list)
+ * @param {string} identifier — sys_id, scope value, or name
+ * @returns {Promise<object>} the sys_scope record (display values requested)
+ * @throws {Error} 'Scope not found: <id>' when nothing matches, or an
+ *   'Ambiguous scope' error listing candidate sys_ids on a non-global tie.
+ */
+export async function resolveScope(sdk, identifier) {
+  assertSafeExactMatch(identifier);
+  for (const queryField of ['sys_id', 'scope', 'name']) {
+    const params = new URLSearchParams();
+    params.set('sysparm_query', `${queryField}=${identifier}`);
+    params.set('sysparm_display_value', 'all');
+    params.set('sysparm_fields', 'sys_id,scope,name');
+    const records = await sdk.list('sys_scope', params);
+    if (records.length === 0) continue;
+    if (records.length === 1) return records[0];
+    // Multiple matches on one field. Only the 'scope' value can legitimately
+    // collide (sys_id and name are unique). Prefer the canonical Global
+    // record when 'global' is in play; otherwise force an explicit choice.
+    const canonical = records.find(r => unwrapSysId(r) === 'global');
+    if (queryField === 'scope' && canonical) return canonical;
+    const candidates = records.map(r => `${unwrapSysId(r)} (${getStringField(r, 'name') || 'unnamed'})`).join(', ');
+    throw new Error(`Ambiguous scope '${identifier}' matches ${records.length} records: ${candidates}. Re-run with an explicit sys_id.`);
+  }
+  throw new Error(`Scope not found: ${identifier}`);
+}
+
 
 /** Format a picker label for a scope: "Name [scope]". */
 export function formatScopeLabel(r) {
@@ -117,21 +162,8 @@ export function scopesCmd(wrap) {
               type: 'string',
             }),
           handler: wrap(async (argv, app) => {
-            assertSafeExactMatch(argv.scope);
-            let records;
-            // Try by scope value first, then by name
-            for (const queryField of ['scope', 'name']) {
-              const params = new URLSearchParams();
-              params.set('sysparm_query', `${queryField}=${argv.scope}`);
-              params.set('sysparm_limit', '1');
-              params.set('sysparm_display_value', 'all');
-              records = await app.sdk.list('sys_scope', params);
-              if (records.length > 0) break;
-            }
-            if (!records || records.length === 0) {
-              throw new Error(`Scope not found: ${argv.scope}`);
-            }
-            const detail = await formatScopeDetail(app, records[0]);
+            const record = await resolveScope(app.sdk, argv.scope);
+            const detail = await formatScopeDetail(app, record);
             app.ok(detail, { summary: `Scope ${argv.scope}` });
           }),
         })
@@ -148,16 +180,8 @@ export function scopesCmd(wrap) {
               if (!picked) return; // cancelled or non-interactive
               scopeArg = getStringField(picked, 'scope');
             }
-            assertSafeExactMatch(scopeArg);
-            const params = new URLSearchParams();
-            params.set('sysparm_query', `scope=${scopeArg}`);
-            params.set('sysparm_limit', '1');
-            params.set('sysparm_fields', 'sys_id,scope,name');
-            const records = await app.sdk.list('sys_scope', params);
-            if (records.length === 0) {
-              throw new Error(`Scope not found: ${scopeArg}`);
-            }
-            const scopeSysID = getStringField(records[0], 'sys_id');
+            const record = await resolveScope(app.sdk, scopeArg);
+            const scopeSysID = unwrapSysId(record);
             const userSysID = await requireCurrentUserSysId(app.sdk);
             await setCurrentApplication(app.sdk, userSysID, scopeSysID);
             app.ok({ scope: scopeArg, sys_id: scopeSysID }, { summary: `Current scope: ${scopeArg}` });

package/src/commands/dev/scrapi.js

@@ -10,6 +10,11 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { formatRecordForDisplay, getStringField, isHexString } from '../../helpers.js';
 import { errUsageHint } from '../../errors.js';
+import { declareCapabilities } from '../../capabilities.js';
+
+// `scrapi create` builds a full Scripted REST API in one call (list/show are
+// reads). Registered at root and under `jsn dev`.
+declareCapabilities('scrapi', { mutationSubcommands: ['create'], devAlias: true });
 
 /**
  * Parse a --resource flag value of the form:

package/src/commands/dev/soapmessages.js

@@ -5,6 +5,7 @@ export const soapmessagesCmd = (wrap) => buildDevCmd('soapmessages', 'sys_soap_m
   ['name', 'active', 'sys_scope'], wrap, {
     singular: 'SOAP message',
     scopeValidation: true,
+    devAlias: false,
     onShow: async (record, app) => {
       const sysID = getStringField(record, 'sys_id') || '';
       if (!sysID) return;

package/src/commands/dev/updatesets.js

@@ -1,6 +1,13 @@
+import fs from 'node:fs';
 import { formatRecordForDisplay, getStringField, interactiveList, assertSafeExactMatch } from '../../helpers.js';
 import { getCurrentApplication, getCurrentUpdateSet, requireCurrentUserSysId, setCurrentApplication, setCurrentUpdateSet } from '../../context.js';
-import { errUsage } from '../../errors.js';
+import { errAPI, errUsage } from '../../errors.js';
+import { declareCapabilities } from '../../capabilities.js';
+
+declareCapabilities('updatesets', {
+  mutationSubcommands: ['create', 'set', 'complete', 'ignore', 'parent'],
+  devAlias: true,
+});
 
 /**
  * Scope-mismatch check for an update set vs the current app.
@@ -48,21 +55,38 @@ export async function resolveUpdateSetByName(app, name) {
   if (records.length === 1) return records[0];
 
   // Multiple sets share the name — prefer the one in the current scope.
+  let scopeNote = '';
   try {
     const userSysID = await requireCurrentUserSysId(app.sdk);
     const currentApp = await getCurrentApplication(app.sdk, userSysID);
     const appIdOf = (r) => r.application?.value || (typeof r.application === 'string' ? r.application : '');
-    const inScope = records.find((r) => {
+    const inScope = currentApp.appSysId ? records.find((r) => {
       const appId = appIdOf(r);
-      return appId && currentApp.appSysId && appId === currentApp.appSysId;
-    });
+      return appId && appId === currentApp.appSysId;
+    }) : undefined;
     if (inScope) return inScope;
-  } catch {
-    // fall through to ambiguity error
+
+    // OAuth/service accounts often lack the apps.current_app user preference,
+    // so getCurrentApplication yields an empty appSysId and nothing matches.
+    // Fall back to the user's CURRENT update set sys_id, then a unique
+    // Global-scope match.
+    let current;
+    try { current = await getCurrentUpdateSet(app.sdk, userSysID); } catch { current = null; }
+    if (current?.sys_id) {
+      const byId = records.find((r) => getStringField(r, 'sys_id') === current.sys_id);
+      if (byId) return byId;
+    }
+    const globalOnes = records.filter((r) => appIdOf(r) === 'global');
+    if (globalOnes.length === 1) return globalOnes[0];
+    if (!currentApp.appSysId) {
+      scopeNote = ' (no apps.current_app preference — resolved nothing by scope)';
+    }
+  } catch (err) {
+    scopeNote = ` (couldn't resolve scope: ${err.message})`;
   }
 
   const scopes = records.map((r) => r.application?.display_value || r.application || '?').join(', ');
-  throw errUsage(`Multiple update sets named "${name}" (${records.length}): ${scopes}.\nRun bare "jsn updatesets set" and pick by scope.`);
+  throw errUsage(`Multiple update sets named "${name}" (${records.length}): ${scopes}.${scopeNote}\nRun bare "jsn updatesets set" and pick by scope.`);
 }
 
 /**
@@ -101,16 +125,47 @@ export async function formatUpdateSetDetail(app, record) {
   const created = getStringField(full, 'sys_created_on') || '';
   const updated = getStringField(full, 'sys_updated_on') || '';
 
-  // Child updates: filename only, newest first by sys_updated_on
+  // Child updates: filename only, newest first by sys_updated_on.
+  // Also group by element type (sys_class_name) and flag risky types for
+  // pre-promotion review (update-set members that can clobber prod).
+  const RISKY_TYPES = new Set([
+    'sys_script',            // business rules
+    'sys_script_include',    // script includes
+    'sys_script_client',     // client scripts
+    'sys_security_acl',      // ACLs / access controls
+    'sys_ui_action',         // UI actions
+    'sys_process_flow',      // flows
+    'sys_flow',              // flow definitions
+    'sys_hub_flow',          // flow definitions (flow-designer)
+    'sys_script_trigger',    // workflow/script triggers
+    'sys_script_email_event',// email notifications/actions
+    'sys_script_queue',      // scheduled jobs
+    'sys_script_widget',
+  ]);
   let children = [];
+  const byType = {};
+  const risky = [];
   try {
     const params = new URLSearchParams();
     params.set('sysparm_query', `update_set=${sysID}^ORDERBYDESCsys_updated_on`);
     params.set('sysparm_limit', '500');
-    params.set('sysparm_fields', 'name,sys_updated_on');
+    params.set('sysparm_fields', 'name,sys_updated_on,sys_class_name');
     const updates = await app.sdk.list('sys_update_xml', params);
     if (Array.isArray(updates)) {
-      children = updates.map(u => getStringField(u, 'name')).filter(Boolean);
+      for (const u of updates) {
+        const name = getStringField(u, 'name');
+        if (!name) continue;
+        // sys_class_name is often empty on dev; fall back to the element-type
+        // prefix baked into the update name (e.g. sys_security_acl_<sysid32>).
+        let type = getStringField(u, 'sys_class_name');
+        if (!type) {
+          const m = /^(sys_[a-z_]+?)_[0-9a-f]{32}$/i.exec(name);
+          type = m ? m[1] : '?';
+        }
+        children.push({ name, type });
+        if (type && type !== '?') byType[type] = (byType[type] || 0) + 1;
+        if (type && RISKY_TYPES.has(type)) risky.push(name);
+      }
     }
   } catch {
     // children are best-effort — a broken query shouldn't kill the display
@@ -123,9 +178,20 @@ export async function formatUpdateSetDetail(app, record) {
   if (parent) lines.push(`  Parent:    ${parent}`);
   if (created) lines.push(`  Created:   ${created}`);
   if (updated) lines.push(`  Updated:   ${updated}`);
-  lines.push(`  Updates:   ${children.length}`);
+  lines.push(`Updates:   ${children.length}`);
+  const typeEntries = Object.entries(byType).sort((a, b) => b[1] - a[1]);
+  if (typeEntries.length > 0) {
+    lines.push(`  By type:  ${typeEntries.map(([t, n]) => `${t}×${n}`).join(', ')}`);
+  }
+  if (risky.length > 0) {
+    lines.push(`  ⚠️ Risky:  ${risky.length} (business rules, ACLs, client scripts, flows, ...)`);
+    for (const r of risky.slice(0, 10)) {
+      lines.push(`    ⚠️ ${r}`);
+    }
+    if (risky.length > 10) lines.push(`    … and ${risky.length - 10} more`);
+  }
   for (const c of children) {
-    lines.push(`    ${c}`);
+    lines.push(`    ${c.name}`);
   }
   lines.push(`  Link:      ${link}`);
 
@@ -152,6 +218,11 @@ export async function formatUpdateSetDetail(app, record) {
     cmd: `jsn updatesets parent "${name}" --parent "<parent set name>"`,
     description: 'Set the parent of this update set',
   });
+  hints.push({
+    action: 'export',
+    cmd: `jsn updatesets export "${name}" --out ${name.replace(/[^a-z0-9]+/gi, '-').toLowerCase()}.xml`,
+    description: 'Export this update set to XML',
+  });
   if (!isClosed) {
     hints.push({
       action: 'complete',
@@ -174,6 +245,9 @@ export async function formatUpdateSetDetail(app, record) {
     sys_created_on: created,
     sys_updated_on: updated,
     children,
+    by_type: byType,
+    risky_count: risky.length,
+    risky,
     link,
     _formatted: lines.join('\n'),
     hints,
@@ -227,14 +301,69 @@ export function updateSetsCmd(wrap) {
         })
         .command({
           command: 'show <name>',
-          aliases: ['get'],
-          describe: 'Show an update set',
+          aliases: ['get', 'review'],
+          describe: 'Show an update set (members, type counts, risky items)',
           handler: wrap(async (argv, app) => {
             const record = await resolveUpdateSetByName(app, argv.name);
             const detail = await formatUpdateSetDetail(app, record);
             app.ok(detail, { summary: `Update set ${argv.name}`, breadcrumbs: detail.hints });
           }),
         })
+        .command({
+          command: 'export <name>',
+          describe: 'Export an update set to XML (raw XML to stdout, or --out file)',
+          builder: (y) => y
+            .positional('name', { describe: 'Update set name', type: 'string' })
+            .option('out', { alias: 'o', type: 'string', describe: 'Write XML to this file instead of stdout' }),
+          handler: wrap(async (argv, app) => {
+            app.requireInstance();
+            const record = await resolveUpdateSetByName(app, argv.name);
+            const sysID = getStringField(record, 'sys_id');
+            // The fluent export endpoint wants the update set's SCOPE sys_id
+            // (application is a sys_scope reference) so it can resolve the
+            // app's update set members.
+            const appSysId = record.application?.value
+              || (typeof record.application === 'string' ? record.application : '');
+
+            // Fluent export endpoint: warm session → CSRF → GET. Returns the
+            // full update set XML (header + all sys_update_xml payloads).
+            const xml = await app.sdk.exportUpdateSet(sysID, appSysId);
+
+            // Guard: the endpoint returns the XML document itself. If we got
+            // anything that doesn't start like XML it's an error/login page.
+            const trimmed = xml.trimStart();
+            if (!/^(<\?xml|<unload)/i.test(trimmed)) {
+              throw errAPI(200, `Export returned a non-XML response (${trimmed.slice(0, 60)}…) — the instance may need an authenticated session.`);
+            }
+
+            const bytes = Buffer.byteLength(xml, 'utf-8');
+            if (argv.out) {
+              await fs.promises.writeFile(argv.out, xml);
+              app.ok({
+                update_set: getStringField(record, 'name'),
+                sys_id: sysID,
+                out: argv.out,
+                bytes,
+              }, { summary: `Exported update set "${getStringField(record, 'name')}" (${bytes} bytes) to ${argv.out}` });
+              return;
+            }
+
+            // No --out: raw XML to stdout so it pipes cleanly
+            // (`jsn updatesets export "X" > set.xml`). Only wrap in the JSON
+            // envelope when the user explicitly asks for it — auto format
+            // detection must NOT hijack the payload for piped consumers.
+            if (argv.json || argv.format === 'json') {
+              app.ok({
+                update_set: getStringField(record, 'name'),
+                sys_id: sysID,
+                xml,
+                bytes,
+              }, { summary: `Exported update set "${getStringField(record, 'name')}" (${bytes} bytes)` });
+              return;
+            }
+            process.stdout.write(xml + (xml.endsWith('\n') ? '' : '\n'));
+          }),
+        })
         .command({
           command: 'set [name]',
           describe: 'Set the current update set (interactive picker with scope when run bare)',
@@ -395,7 +524,8 @@ export function updateSetsCmd(wrap) {
         console.log('Manage ServiceNow update sets.\n');
         console.log('Commands:');
         console.log('  list           List update sets (shows scope)');
-        console.log('  show <name>    Show an update set');
+        console.log('  show <name>    Show an update set (type counts + risky items)');
+        console.log('  export <name>  Export an update set to XML (stdout or --out)');
         console.log('  set  [name]    Set the current update set (picker when run bare)');
         console.log('  create         Create a new update set (auto-sets as current)');
         console.log('  complete       Mark the current update set as complete');

package/src/commands/dev.js

@@ -2,13 +2,14 @@
 
 import {
   actionsCmd, includesCmd, rulesCmd,
-  clientScriptsCmd, uiActionsCmd, uiPoliciesCmd,
+  clientScriptsCmd, uiActionsCmd,
   tablesCmd, columnsCmd, importCmd,
   spPagesCmd, spWidgetsCmd, uiPagesCmd, appMenuCmd,
   aclsCmd, rolesCmd, propertiesCmd,
   relationshipsCmd, appmodulesCmd, listcontrolsCmd, viewsCmd,
   privilegesCmd, uxscriptsCmd, aliasesCmd,
   catalogscriptsCmd, cataloguipoliciesCmd,
+  uipoliciesCmd,
 } from './dev/_simple.js';
 import { flowsCmd } from './dev/flows.js';
 import { formsCmd } from './dev/forms.js';
@@ -33,7 +34,7 @@ export function devCmd(wrap) {
         .command(rulesCmd(wrap))
         .command(clientScriptsCmd(wrap))
         .command(uiActionsCmd(wrap))
-        .command(uiPoliciesCmd(wrap))
+        .command(uipoliciesCmd(wrap))
         .command(tablesCmd(wrap))
         .command(columnsCmd(wrap))
         .command(formsCmd(wrap))

package/src/commands/docs/db.js

@@ -171,6 +171,20 @@ export function getMeta(db, key, defaultValue = null) {
   }
 }
 
+/**
+ * Index statistics for `jsn docs status`: document/bundle/doc-type counts,
+ * embedding coverage, and the synced_at meta stamp. All docs-table aggregate
+ * SQL lives here so command handlers never touch the schema.
+ */
+export function getDocsIndexStats(db) {
+  const documents = db.prepare('SELECT COUNT(*) AS n FROM docs').get().n;
+  const bundles = db.prepare('SELECT COUNT(DISTINCT bundle) AS n FROM docs').get().n;
+  const docTypes = db.prepare('SELECT COUNT(DISTINCT doc_type) AS n FROM docs').get().n;
+  const embeddedCount = db.prepare('SELECT COUNT(*) AS n FROM docs WHERE hrr_vector IS NOT NULL').get().n;
+  const syncedAt = getMeta(db, 'synced_at');
+  return { documents, bundles, docTypes, embeddedCount, syncedAt };
+}
+
 export function setMeta(db, key, value) {
   db.prepare('INSERT OR REPLACE INTO meta(key, value) VALUES(?, ?)').run(key, value);
 }

package/src/commands/docs/docs.js

@@ -6,14 +6,17 @@ import net from 'node:net';
 import process from 'node:process';
 import {
   getDocsDbPath, getDocsSourceDir, getDocsSourceMarkdownDir, docsDbExists,
-  openDocsDb, closeDocsDb, getMeta,
+  openDocsDb, closeDocsDb, getDocsIndexStats,
 } from './db.js';
 import { syncDocs } from './sync.js';
 import { refreshDocs } from './refresh.js';
 import { embedDocs } from './embed.js';
-import { searchDocs } from './search.js';
+import { searchDocs, getDocByIdOrPath } from './search.js';
 import { serveDocs } from './serve.js';
 import { syncCommunity, listCommunityDocs } from './community.js';
+import { declareCapabilities } from '../../capabilities.js';
+
+declareCapabilities('docs', { noInstance: true, skipDailyChecks: true });
 
 function formatBytes(n) {
   if (n == null) return '-';
@@ -57,16 +60,13 @@ export function docsCmd(wrap) {
             let state, embedded, documents, bundles, docTypes, syncedAt, dbSize;
             if (dbExists) {
               const db = openDocsDb();
-              documents = db.prepare('SELECT COUNT(*) AS n FROM docs').get().n;
-              bundles = db.prepare('SELECT COUNT(DISTINCT bundle) AS n FROM docs').get().n;
-              docTypes = db.prepare('SELECT COUNT(DISTINCT doc_type) AS n FROM docs').get().n;
-              const embCount = db.prepare('SELECT COUNT(*) AS n FROM docs WHERE hrr_vector IS NOT NULL').get().n;
-              syncedAt = getMeta(db, 'synced_at');
+              const stats = getDocsIndexStats(db);
+              ({ documents, bundles, docTypes, syncedAt } = stats);
               const stat = fs.statSync(dbPath);
               dbSize = stat.size;
               closeDocsDb(db);
 
-              embedded = embCount >= documents && documents > 0;
+              embedded = stats.embeddedCount >= documents && documents > 0;
               if (embedded) state = 'ready';
               else if (documents > 0) state = 'indexed (not embedded)';
               else state = 'empty';
@@ -154,19 +154,7 @@ export function docsCmd(wrap) {
             .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 idOrPath = argv['id-or-path'];
-            const db = openDocsDb();
-            let row;
-            if (/^\d+$/.test(idOrPath)) {
-              row = db.prepare('SELECT * FROM docs WHERE id = ?').get(parseInt(idOrPath, 10));
-            } else {
-              row = db.prepare('SELECT * FROM docs WHERE path LIKE ?').get(`%${idOrPath}%`);
-              if (!row) {
-                row = db.prepare(
-                  `SELECT d.* FROM docs_fts JOIN docs d ON d.id = docs_fts.rowid WHERE docs_fts MATCH ? LIMIT 1`
-                ).get(idOrPath);
-              }
-            }
-            closeDocsDb(db);
+            const row = getDocByIdOrPath(idOrPath);
 
             if (!row) {
               throw Object.assign(new Error(`No doc found for "${idOrPath}"`), { code: 'not_found' });

package/src/commands/docs/search.js

@@ -1,8 +1,7 @@
 // CLI search against the docs SQLite database.
 
 import fs from 'node:fs';
-import Database from 'better-sqlite3';
-import { getDocsDbPath, hasEmbeddings } from './db.js';
+import { getDocsDbPath, hasEmbeddings, openDocsDb, closeDocsDb, getMeta } from './db.js';
 import { encodeText, similarity, bytesToPhases, DEFAULT_DIM } from './hrr.js';
 
 function safeParse(s) {
@@ -13,6 +12,33 @@ function safeParse(s) {
   }
 }
 
+/**
+ * Fetch one doc for `jsn docs show`: exact id when the argument is numeric,
+ * otherwise a path-substring match, falling back to a single best FTS match.
+ * Returns the docs row, or undefined when nothing matches. Owns its DB
+ * handle (pass opts.dbPath to target a non-default database — used by tests).
+ */
+export function getDocByIdOrPath(idOrPath, opts = {}) {
+  const dbPath = opts.dbPath || getDocsDbPath();
+  const db = openDocsDb({ dbPath });
+  try {
+    let row;
+    if (/^\d+$/.test(idOrPath)) {
+      row = db.prepare('SELECT * FROM docs WHERE id = ?').get(parseInt(idOrPath, 10));
+    } else {
+      row = db.prepare('SELECT * FROM docs WHERE path LIKE ?').get(`%${idOrPath}%`);
+      if (!row) {
+        row = db.prepare(
+          `SELECT d.* FROM docs_fts JOIN docs d ON d.id = docs_fts.rowid WHERE docs_fts MATCH ? LIMIT 1`
+        ).get(idOrPath);
+      }
+    }
+    return row;
+  } finally {
+    closeDocsDb(db);
+  }
+}
+
 export function searchDocs(opts = {}) {
   const dbPath = opts.dbPath || getDocsDbPath();
   const q = (opts.query || '').toString().trim();
@@ -24,7 +50,7 @@ export function searchDocs(opts = {}) {
     throw new Error(`Database not found: ${dbPath}. Run "jsn docs sync" first.`);
   }
 
-  const db = new Database(dbPath, { readonly: true });
+  const db = openDocsDb({ dbPath });
   const limit = Math.min(parseInt(opts.limit, 10) || 20, 1000);
   const offset = parseInt(opts.offset, 10) || 0;
   const bundle = opts.bundle ? String(opts.bundle) : null;
@@ -86,12 +112,9 @@ export function searchDocs(opts = {}) {
       rows = [];
     } else {
       const hrrDim = (() => {
-        try {
-          const row = db.prepare("SELECT value FROM meta WHERE key='hrr_dim'").get();
-          return row ? parseInt(row.value, 10) : DEFAULT_DIM;
-        } catch {
-          return DEFAULT_DIM;
-        }
+        const value = getMeta(db, 'hrr_dim');
+        const n = parseInt(value, 10);
+        return Number.isInteger(n) ? n : DEFAULT_DIM;
       })();
       const queryVec = encodeText(q, hrrDim);
       const queryTokens = new Set(q.toLowerCase().split(/\s+/).filter(Boolean));
@@ -128,7 +151,7 @@ export function searchDocs(opts = {}) {
     }
   }
 
-  db.close();
+  closeDocsDb(db);
 
   // Post-process canonical_url JSON strings that may contain escaped content.
   for (const row of rows) {