@jacebenson/jsn 4.3.13 → 4.4.0-dev.114.1

package/src/commands/docs/snapshot.js

@@ -0,0 +1,130 @@
+// Shared, versioned docs artifact format. Never touches mutation history.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { gzipSync, gunzipSync } from 'node:zlib';
+import Database from 'better-sqlite3';
+import { getDocsDbPath, getDocsCacheDir } from './db.js';
+import { docsReaderLease } from './locks.js';
+import { ingestDocs } from './ingest.js';
+import { installDatabase } from './replace.js';
+export { installDatabase } from './replace.js';
+
+export const SNAPSHOT_SCHEMA = 1;
+export const DEFAULT_MANIFEST_URL = 'https://jsn.jace.pro/docs-index/manifest.json';
+const MAX_COMPRESSED = 512 * 1024 * 1024;
+const MAX_DATABASE = 2 * 1024 * 1024 * 1024;
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+export function validateManifest(manifest) {
+  if (manifest?.format !== 1 || manifest.schema !== SNAPSHOT_SCHEMA || manifest.cliCompatibility !== 'docs-schema-1') throw new Error('Incompatible docs snapshot format/schema');
+  if (!/^[a-f0-9]{64}$/.test(manifest.sha256 || '') || !/^[a-f0-9]{7,64}$/.test(manifest.revision || '')) throw new Error('Invalid snapshot checksum or revision');
+  for (const [field, max] of [['compressedBytes', MAX_COMPRESSED], ['databaseBytes', MAX_DATABASE]]) {
+    if (!Number.isSafeInteger(manifest[field]) || manifest[field] <= 0 || manifest[field] > max) throw new Error(`Invalid snapshot ${field}`);
+  }
+  const url = new URL(manifest.url);
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname))) throw new Error('Snapshot downloads require HTTPS');
+  return manifest;
+}
+export function validateDatabase(filename) {
+  const db = new Database(filename, { readonly: true, fileMustExist: true });
+  try {
+    if (db.pragma('integrity_check', { simple: true }) !== 'ok') throw new Error('Snapshot SQLite integrity check failed');
+    if (db.prepare("SELECT value FROM meta WHERE key='schema_version'").get()?.value !== String(SNAPSHOT_SCHEMA)) throw new Error('Incompatible snapshot database schema');
+    const count = db.prepare('SELECT count(*) AS n FROM docs').get().n;
+    if (!count) throw new Error('Snapshot index is empty');
+    db.prepare("SELECT rowid FROM docs_fts WHERE docs_fts MATCH 'documentation' LIMIT 1").all();
+    return count;
+  } finally { db.close(); }
+}
+export function buildSnapshot({ docsDir, outputDir, revision, artifactBaseURL, embed = true }) {
+  if (!/^[a-f0-9]{7,64}$/.test(revision || '')) throw new Error('A source commit revision is required');
+  fs.mkdirSync(outputDir, { recursive: true });
+  const temporary = fs.mkdtempSync(path.join(outputDir, '.build-'));
+  try {
+    const filename = path.join(temporary, 'docs.db');
+    const result = ingestDocs({ dbPath: filename, roots: [{ dir: docsDir, prefix: '' }], embed });
+    if (result.errors || !result.count) throw new Error(`Docs build rejected: ${result.errors} ingestion errors, ${result.count} documents`);
+    const db = new Database(filename);
+    try {
+      db.prepare("INSERT OR REPLACE INTO meta(key,value) VALUES('snapshot_revision', ?)").run(revision);
+      db.pragma('wal_checkpoint(TRUNCATE)'); db.pragma('journal_mode = DELETE');
+    } finally { db.close(); }
+    const documents = validateDatabase(filename);
+    const bytes = fs.readFileSync(filename), compressed = gzipSync(bytes);
+    const name = `docs-schema-${SNAPSHOT_SCHEMA}-${revision}.sqlite.gz`;
+    const manifest = validateManifest({ format: 1, schema: SNAPSHOT_SCHEMA, cliCompatibility: 'docs-schema-1', revision,
+      sha256: digest(compressed), compressedBytes: compressed.length, databaseBytes: bytes.length,
+      documents, buildSeconds: result.secs, builtAt: new Date().toISOString(), url: new URL(name, artifactBaseURL.endsWith('/') ? artifactBaseURL : artifactBaseURL + '/').href });
+    const artifact = path.join(outputDir, name);
+    if (fs.existsSync(artifact) && digest(fs.readFileSync(artifact)) !== manifest.sha256) throw new Error('Immutable artifact already exists with different content');
+    fs.writeFileSync(path.join(temporary, name), compressed);
+    fs.renameSync(path.join(temporary, name), artifact);
+    // Publish this manifest only after uploading the immutable artifact successfully.
+    fs.writeFileSync(path.join(temporary, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
+    fs.renameSync(path.join(temporary, 'manifest.json'), path.join(outputDir, 'manifest.json'));
+    return manifest;
+  } finally { fs.rmSync(temporary, { recursive: true, force: true }); }
+}
+async function download(url, maxBytes, fetchFn, timeout = 600000) {
+  const response = await fetchFn(url, { signal: AbortSignal.timeout(timeout) });
+  if (response.url && new URL(response.url).protocol !== 'https:' && !['localhost', '127.0.0.1', '[::1]'].includes(new URL(response.url).hostname)) throw new Error('Docs download redirected to insecure transport');
+  if (!response.ok) throw new Error(`Docs download rejected (HTTP ${response.status})`);
+  if (Number(response.headers.get('content-length')) > maxBytes) { await response.body?.cancel(); throw new Error('Docs download exceeds size limit'); }
+  const parts = []; let size = 0;
+  for await (const chunk of response.body) {
+    size += chunk.length;
+    if (size > maxBytes) throw new Error('Docs download exceeds size limit');
+    parts.push(chunk);
+  }
+  return Buffer.concat(parts);
+}
+export async function fetchManifest(url = DEFAULT_MANIFEST_URL, { fetchFn = fetch } = {}) {
+  // Validate transport before making a request, including configured mirrors.
+  validateManifest({ format: 1, schema: 1, cliCompatibility: 'docs-schema-1', revision: 'abcdef0', sha256: '0'.repeat(64), compressedBytes: 1, databaseBytes: 1, url });
+  return validateManifest(JSON.parse((await download(url, 65536, fetchFn, 15000)).toString('utf8')));
+}
+export function snapshotEstimate(manifest) {
+  return `${(manifest.compressedBytes / 1048576).toFixed(1)} MiB; estimated ${Math.max(1, Math.ceil(manifest.compressedBytes / 5242880))} seconds at 5 MiB/s plus verification (actual time varies)`;
+}
+export async function installSnapshot({ manifestURL = DEFAULT_MANIFEST_URL, manifest, dbPath = getDocsDbPath(), fetchFn = fetch } = {}) {
+  manifest = manifest ? validateManifest(manifest) : await fetchManifest(manifestURL, { fetchFn });
+  const compressed = await download(manifest.url, manifest.compressedBytes, fetchFn);
+  if (compressed.length !== manifest.compressedBytes || digest(compressed) !== manifest.sha256) throw new Error('Docs snapshot checksum/size mismatch; existing index retained');
+  const bytes = gunzipSync(compressed, { maxOutputLength: manifest.databaseBytes });
+  if (bytes.length !== manifest.databaseBytes) throw new Error('Docs database size mismatch');
+  fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+  const staged = `${dbPath}.${randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(staged, bytes, { mode: 0o600, flag: 'wx' });
+    validateDatabase(staged);
+    const db = new Database(staged, { readonly: true });
+    try {
+      if (db.prepare("SELECT value FROM meta WHERE key='snapshot_revision'").get()?.value !== manifest.revision) throw new Error('Snapshot source revision mismatch');
+    } finally { db.close(); }
+    const receipt = `${dbPath}.snapshot.json`, receiptStage = `${staged}.receipt`;
+    try {
+      fs.writeFileSync(receiptStage, JSON.stringify({ ...manifest, manifestURL, checkedAt: Date.now() }), { mode: 0o600 });
+      installDatabase(staged, dbPath, { afterInstall: () => fs.renameSync(receiptStage, receipt) });
+    } finally { fs.rmSync(receiptStage, { force: true }); }
+    return { revision: manifest.revision, documents: manifest.documents, dbPath, source: 'snapshot' };
+  } finally { fs.rmSync(staged, { force: true }); }
+}
+export function rollbackSnapshot(dbPath = getDocsDbPath()) {
+  const previous = `${dbPath}.previous`;
+  if (!fs.existsSync(previous)) throw new Error('No previous docs snapshot is available');
+  validateDatabase(previous);
+  const staged = `${dbPath}.${randomUUID()}.tmp`;
+  try { fs.copyFileSync(previous, staged); installDatabase(staged, dbPath, { afterInstall: () => fs.rmSync(`${dbPath}.snapshot.json`, { force: true }) }); }
+  finally { fs.rmSync(staged, { force: true }); }
+  return { dbPath, rolledBack: true };
+}
+export function docsSnapshotStatus() {
+  const receipt = path.join(getDocsCacheDir(), 'docs.db.snapshot.json');
+  let release, db;
+  try {
+    release = docsReaderLease(getDocsDbPath());
+    const value = JSON.parse(fs.readFileSync(receipt, 'utf8'));
+    db = new Database(getDocsDbPath(), { readonly: true, fileMustExist: true });
+    return db.prepare("SELECT value FROM meta WHERE key='snapshot_revision'").get()?.value === value.revision ? value : null;
+  } catch { return null; } finally { db?.close(); release?.(); }
+}

package/src/commands/docs/sync.js

@@ -2,6 +2,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { docsInstallLease, docsHaveReaders } from './locks.js';
 import { spawnSync } from 'node:child_process';
 import { getDocsSourceDir, getDocsSourceMarkdownDir, getDocsDbPath, docsDbExists } from './db.js';
 import { ingestDocs } from './ingest.js';
@@ -21,6 +22,15 @@ function git(args, cwd, stdio = 'inherit') {
 }
 
 export function syncDocs(opts = {}) {
+  const repoDir = opts.repoDir || getDocsSourceDir();
+  fs.mkdirSync(path.dirname(repoDir), { recursive: true });
+  const release = docsInstallLease(repoDir);
+  try {
+    if (docsHaveReaders(repoDir)) throw new Error('Raw documentation source is in use; retry after the current refresh finishes.');
+    return syncDocsLocked(opts);
+  } finally { release(); }
+}
+function syncDocsLocked(opts = {}) {
   const repoDir = opts.repoDir || getDocsSourceDir();
   const markdownDir = opts.markdownDir || getDocsSourceMarkdownDir();
   const dbPath = opts.dbPath || getDocsDbPath();
@@ -29,13 +39,13 @@ export function syncDocs(opts = {}) {
 
   const initialStatus = {
     clone: !fs.existsSync(path.join(repoDir, '.git')),
-    docsApprox: 45000,
+    docsApprox: 51000,
     willEmbed: embed && noIngest === false,
-    minutesHint: embed ? 3 : 1,
+    minutesHint: embed ? 5 : 1,
   };
 
-  process.stderr.write('Note: docs sync downloads ~45k markdown files and builds an FTS5 + HRR index. ');
-  process.stderr.write(`This normally takes ${initialStatus.minutesHint}-${initialStatus.minutesHint + 2} minutes.\n`);
+  process.stderr.write('Note: docs sync downloads ~51k markdown files and builds an FTS5 + HRR index. ');
+  process.stderr.write(`Estimated ${embed ? '5–25' : '1–5'} minutes; actual time varies by host and indexing options.\n`);
   if (initialStatus.willEmbed) {
     process.stderr.write('Pass --no-embed to skip semantic embeddings and finish faster.\n');
   }
@@ -68,11 +78,11 @@ export function syncDocs(opts = {}) {
   // If the DB already exists, use incremental refresh. Otherwise, full ingest.
   if (docsDbExists()) {
     process.stderr.write(`Docs DB found — running incremental refresh...\n`);
-    const result = refreshDocs({ docsDir: markdownDir, dbPath });
+    const result = refreshDocs({ docsDir: markdownDir, dbPath, sourceResource: repoDir, sourceLeaseHeld: true });
     return { repoDir, markdownDir, dbPath, ingested: true, incremental: true, ...result };
   }
 
   process.stderr.write('No existing DB — running full ingest...\n');
-  const result = ingestDocs({ docsDir: markdownDir, dbPath, embed });
+  const result = ingestDocs({ docsDir: markdownDir, dbPath, embed, sourceResource: repoDir, sourceLeaseHeld: true });
   return { repoDir, markdownDir, dbPath, ingested: true, incremental: false, ...result };
 }

package/src/commands/forms.js

@@ -1,105 +1,29 @@
 import { getStringField, interactiveList } from '../helpers.js';
 
-function getDisplayValue(record, key) {
-  if (!record || typeof record !== 'object') return '';
-  const val = record[key];
-  if (val == null) return '';
-  if (typeof val === 'string') return val;
-  if (typeof val === 'object') {
-    if (val.display_value != null && val.display_value !== '') return String(val.display_value);
-    if (val.value != null) return String(val.value);
-  }
-  return String(val);
-}
-
-function getIntValue(record, key) {
-  if (!record || typeof record !== 'object') return 0;
-  const val = record[key];
-  if (val == null) return 0;
-  if (typeof val === 'number') return Math.floor(val);
-  if (typeof val === 'string') { const n = parseInt(val, 10); return isNaN(n) ? 0 : n; }
-  if (typeof val === 'object' && val.value != null) { const n = parseInt(val.value, 10); return isNaN(n) ? 0 : n; }
-  return 0;
-}
-
-async function showForm(app, table, viewName) {
-  // 1) Look up the view
-  const viewParams = new URLSearchParams();
-  viewParams.set('sysparm_limit', '1');
-  viewParams.set('sysparm_fields', 'sys_id');
-  viewParams.set('sysparm_display_value', 'all');
-  viewParams.set('sysparm_query', `name=${viewName}`);
-  let viewSysID = '';
-  try { const vr = await app.sdk.list('sys_ui_view', viewParams); if (vr.length > 0) viewSysID = getStringField(vr[0], 'sys_id'); } catch { /* ignore */ }
-  if (!viewSysID) {
-    viewParams.set('sysparm_query', `title=${viewName}`);
-    try { const vr = await app.sdk.list('sys_ui_view', viewParams); if (vr.length > 0) viewSysID = getStringField(vr[0], 'sys_id'); } catch { /* ignore */ }
-  }
-
-  // 2) Get sections for this table + view
-  const secParams = new URLSearchParams();
-  secParams.set('sysparm_limit', '200');
-  secParams.set('sysparm_fields', 'sys_id,caption');
-  secParams.set('sysparm_display_value', 'all');
-  secParams.set('sysparm_query', `name=${table}^view=${viewName}^ORDERBYposition`);
-  if (viewSysID) {
-    secParams.set('sysparm_query', `name=${table}^view=${viewSysID}^ORDERBYposition`);
-  }
-  const sections = await app.sdk.list('sys_ui_section', secParams);
-
-  // 3) Get elements for each section
-  const sectionsOut = [];
-  for (const sec of sections) {
-    const secSysID = getStringField(sec, 'sys_id');
-    const sectionCaption = getDisplayValue(sec, 'caption') || '(unnamed)';
+import { createRecordMetadataReader } from '../metadata/records.js';
 
-    let elements = [];
-    if (secSysID) {
-      const elemParams = new URLSearchParams();
-      elemParams.set('sysparm_limit', '500');
-      elemParams.set('sysparm_fields', 'element,type,label,position');
-      elemParams.set('sysparm_display_value', 'all');
-      elemParams.set('sysparm_query', `sys_ui_section=${secSysID}^ORDERBYposition`);
-      try { elements = await app.sdk.list('sys_ui_element', elemParams); } catch { /* ignore */ }
-    }
-
-    sectionsOut.push({
-      caption: sectionCaption,
-      position: getIntValue(sec, 'position'),
-      elements: elements
-        .map(e => ({
-          type: getDisplayValue(e, 'type'),
-          label: getDisplayValue(e, 'label'),
-          element: getDisplayValue(e, 'element'),
-          position: getIntValue(e, 'position'),
-        }))
-        .sort((a, b) => a.position - b.position),
-    });
+export function formatFormMetadata(metadata) {
+  const lines = [`Form: ${metadata.table} → ${metadata.requested_view}`];
+  if (metadata.form?.inherited) lines.push(`  Inherited layout: ${metadata.form.table}`);
+  if (!metadata.form) lines.push('  No unambiguous shared form layout is visible.');
+  for (const section of metadata.form?.sections || []) {
+    lines.push('', `── ${section.caption || '(unnamed)'} ──`);
+    for (const element of section.elements) lines.push(`  ${element.label || element.element || '(unnamed)'}${element.type ? ` (${element.type})` : ''}`);
+    if (!section.elements.length) lines.push('  (no visible elements)');
   }
-
-  sectionsOut.sort((a, b) => a.position - b.position);
-
-  // Build formatted output
-  const lines = [];
-  lines.push(`Form: ${table} → ${viewName}`);
-  if (viewSysID) lines.push(`  View: ${app.getEffectiveInstance()}/nav_to.do?uri=sys_ui_view.do?sys_id=${viewSysID}`);
-  lines.push('');
-
-  for (const sec of sectionsOut) {
-    const secLabel = sec.caption || '(unnamed)';
-    lines.push(`── ${secLabel} ──`);
-    if (sec.elements.length === 0) {
-      lines.push('  (no elements)');
-    }
-    for (const el of sec.elements) {
-      const elLabel = el.label || el.element || '(unnamed)';
-      const typeStr = el.type ? ` (${el.type})` : '';
-      lines.push(`  ${elLabel}${typeStr}`);
-    }
-    lines.push('');
+  const configured = metadata.related_lists.filter(item => item.configured);
+  if (configured.length) {
+    lines.push('', 'Configured related lists:');
+    for (const list of configured) lines.push(`  ${list.label || list.id} (${list.query_status})`);
   }
+  lines.push('', metadata.coverage.scope);
+  for (const warning of metadata.coverage.warnings) lines.push(`  ${warning.source}: ${warning.reason}`);
+  return lines.join('\n');
+}
 
-  process.stdout.write(lines.join('\n') + '\n');
+async function showForm(app, table, view) {
+  const metadata = await createRecordMetadataReader(app.sdk).read({ table, view });
+  app.ok({ ...metadata, _formatted: formatFormMetadata(metadata) }, { summary: `Form metadata for ${table}` });
 }
 
 export function formsCmd(wrap) {
@@ -164,7 +88,8 @@ export function formsCmd(wrap) {
           aliases: ['get'],
           describe: 'Show form layout',
           builder: (y) => y
-            .option('view', { type: 'string', default: 'Default view', describe: 'View name' }),
+            .option('view', { type: 'string', default: 'Default view', describe: 'Shared view name, title or sys_id' })
+            .epilogue('Discovers shared layouts, inherited forms and related-list metadata. JSON includes coverage limits; custom relationship scripts are never executed. Generic records get presentation is unchanged.'),
           handler: wrap(async (argv, app) => {
             app.requireInstance();
             await showForm(app, argv.table, argv.view);

package/src/commands/history.js

@@ -0,0 +1,57 @@
+import { declareCapabilities } from '../capabilities.js';
+import { listHistory, pruneHistory } from '../mutation-history.js';
+
+export function historyCmd(wrap) {
+  declareCapabilities('history', { noInstance: true, skipDailyChecks: true });
+  const list = wrap(async (argv, app) => {
+    const entries = listHistory({ ...argv, instance: argv['instance-url'], profile: argv['profile-name'] });
+    app.ok({ entries, retentionDays: 7, _formatted: renderHistory(entries, { details: argv.details }) });
+  });
+  const filters = b => b
+    .option('details', { type: 'boolean', default: false, describe: 'Show full record IDs, instance URLs and reasons' })
+    .option('since', { type: 'string', describe: 'Earliest ISO timestamp' })
+    .option('until', { type: 'string', describe: 'Latest ISO timestamp' })
+    .option('instance-url', { type: 'string', describe: 'Filter by instance origin' })
+    .option('profile-name', { type: 'string', describe: 'Filter by recorded profile name (including removed profiles)' })
+    .option('table', { type: 'string', describe: 'Filter by table' })
+    .option('operation', { choices: ['create', 'update', 'delete'], type: 'string' })
+    .option('record', { type: 'string', describe: 'Filter by full resolved sys_id' })
+    .option('limit', { type: 'number', default: 50, describe: 'Maximum entries (1–10000)' });
+  return { command: 'history [subcommand]', describe: 'Local seven-day mutation history (not a durable ServiceNow audit)',
+    builder: y => filters(y).command({ command: 'list', describe: 'List local mutations', builder: filters, handler: list })
+      .command({ command: 'prune', describe: 'Remove expired entries only', handler: wrap(async (_argv, app) => {
+        app.ok({ ...pruneHistory(), _formatted: 'Expired local history removed; seven days retained.' });
+      }) }), handler: list };
+}
+
+export function renderHistory(entries, { details = false, timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone } = {}) {
+  if (!entries.length) return 'No local mutations in the last seven days.';
+  const date = new Intl.DateTimeFormat('en-GB', { timeZone, month: 'short', day: '2-digit',
+    hour: '2-digit', minute: '2-digit', hourCycle: 'h23' });
+  // Strip terminal control characters from stored identifiers and labels.
+  // eslint-disable-next-line no-control-regex
+  const clean = value => String(value ?? '').replace(/[\x00-\x1f\x7f]/g, ' ');
+  const clip = (value, length) => value.length > length ? `${value.slice(0, length - 1)}…` : value;
+  const rows = entries.map(entry => {
+    let connection = entry.profile;
+    if (!connection) {
+      try { connection = new URL(entry.instance).host; } catch { connection = entry.instance; }
+    }
+    return [date.format(new Date(entry.timestamp)), entry.operation, clip(clean(entry.table), 22),
+      clip(clean(entry.sys_id || '(unknown)'), 12), entry.outcome, clip(clean(connection), 22)];
+  });
+  const headers = ['WHEN', 'ACTION', 'TABLE', 'RECORD', 'RESULT', 'CONNECTION'];
+  const widths = headers.map((header, i) => Math.max(header.length, ...rows.map(row => row[i].length)));
+  const format = row => row.map((cell, i) => cell.padEnd(widths[i])).join('  ').trimEnd();
+  const lines = [`Recent mutations · ${timeZone}`, '', format(headers)];
+  rows.forEach((row, i) => {
+    lines.push(format(row));
+    if (details) {
+      const entry = entries[i];
+      lines.push(`  ${clean(entry.timestamp)} · ${clean(entry.table)}/${clean(entry.sys_id || '(unknown)')}`,
+        `  ${clean(entry.instance)}${entry.reason ? ` · ${clean(entry.reason)}` : ''}`);
+    }
+  });
+  if (!details) lines.push('', 'Use --details for full IDs, URLs and reasons; --json for structured history.');
+  return lines.join('\n');
+}

package/src/commands/incidents.js

@@ -1,7 +1,5 @@
-import { buildTicketCommands } from './_ticket.js';
-
-const incidentDefaultColumns = ['number', 'short_description', 'priority', 'state', 'assigned_to'];
+import { buildProfileCommand } from '../record-profiles.js';
 
 export function incidentsCmd(wrap) {
-  return buildTicketCommands('incident', 'incidents', 'inc', incidentDefaultColumns, {}, null, wrap);
+  return buildProfileCommand('incidents', wrap);
 }

package/src/commands/knowledge.js

@@ -0,0 +1,75 @@
+import TurndownService from 'turndown';
+import { formatCommandList, quoteShellArg } from '../helpers.js';
+import { errAPI, errUsage } from '../errors.js';
+
+const API = '/api/sn_km_api/knowledge/articles';
+const markdown = new TurndownService();
+const sysId = /^[a-f0-9]{32}$/i;
+const articleId = value => typeof value === 'string' && (sysId.test(value) || /^KB\d+$/i.test(value));
+
+function emit(app, argv, data, summary, breadcrumbs = []) {
+  const connection = argv.profile ? ` --profile ${quoteShellArg(argv.profile)}`
+    : argv.instance ? ` --instance ${quoteShellArg(argv.instance)}` : '';
+  app.ok(data, { summary, breadcrumbs: breadcrumbs.map(h => ({ ...h, cmd: h.cmd + connection })) });
+}
+
+async function read(sdk, path, params) {
+  const response = await sdk.request(`${sdk.baseURL}${API}${path}?${params}`, { method: 'GET' });
+  const result = response?.result;
+  if (!result || typeof result !== 'object' || Array.isArray(result)) throw errAPI(200, 'Malformed Knowledge API response.');
+  const code = result.meta?.status?.code;
+  if (code !== undefined && Number(code) !== 200) throw errAPI(Number(code) || 500, 'Knowledge API rejected the request.');
+  return result;
+}
+
+export function knowledgeCmd(wrap) {
+  return {
+    command: 'knowledge [subcommand]', aliases: ['kb'],
+    describe: 'Search and read knowledge articles through the Knowledge API',
+    handler: wrap(async (argv, app) => emit(app, argv,
+      { subcommands: argv.subcommands || [], _formatted: formatCommandList({ title: 'Knowledge articles', commands: argv.subcommands || [] }) },
+      'Search and read knowledge articles', [{ action: 'search', cmd: 'jsn knowledge search <text>', description: 'Find accessible articles' }])),
+    builder: y => y
+      .epilogue('Requires the Knowledge API (sn_km_api). Uses its access checks; no fallback to direct knowledge-table reads. Reading does not request view-count updates.')
+      .command({ command: 'search <text>', describe: 'Search accessible knowledge articles',
+        builder: p => p.positional('text', { type: 'string', describe: 'Search text; quote multiple words' })
+          .option('limit', { type: 'number', default: 20, describe: 'Maximum articles (1–100)' })
+          .option('offset', { type: 'number', default: 0, describe: 'Starting result offset' })
+          .option('kb', { type: 'string', describe: 'Comma-separated knowledge-base sys_ids' })
+          .option('language', { type: 'string', describe: 'Two-letter language codes, comma-separated, or all' }),
+        handler: wrap(async (argv, app) => {
+          if (typeof argv.text !== 'string' || !argv.text.trim()) throw errUsage('Provide nonempty search text.');
+          if (!Number.isInteger(argv.limit) || argv.limit < 1 || argv.limit > 100) throw errUsage('--limit must be from 1 to 100.');
+          if (!Number.isInteger(argv.offset) || argv.offset < 0) throw errUsage('--offset must be a nonnegative integer.');
+          if (argv.kb !== undefined && !String(argv.kb).split(',').every(id => sysId.test(id))) throw errUsage('--kb requires knowledge-base sys_ids.');
+          if (argv.language !== undefined && !/^(all|[a-z]{2}(,[a-z]{2})*)$/i.test(argv.language)) throw errUsage('Use two-letter --language codes or all.');
+          const params = new URLSearchParams({ query: argv.text.trim(), limit: String(argv.limit), offset: String(argv.offset) });
+          if (argv.kb) params.set('kb', argv.kb);
+          if (argv.language) params.set('language', argv.language);
+          const result = await read(app.sdk, '', params);
+          if (!Array.isArray(result.articles) || result.articles.some(a => !a || typeof a !== 'object' || Array.isArray(a))) throw errAPI(200, 'Knowledge API returned no valid article list.');
+          const breadcrumbs = result.articles.flatMap(a => {
+            const id = articleId(a.number) ? a.number : String(a.id || '').replace(/^kb_knowledge:/, '');
+            return articleId(id) ? [{ action: 'show', cmd: `jsn knowledge show ${id}`, description: a.title || id }] : [];
+          });
+          const base = `jsn knowledge search ${quoteShellArg(argv.text.trim())} --limit ${argv.limit}`
+            + (argv.kb ? ` --kb ${quoteShellArg(argv.kb)}` : '') + (argv.language ? ` --language ${quoteShellArg(argv.language)}` : '');
+          const total = result.meta?.count;
+          const hasMore = typeof total === 'number' ? argv.offset + result.articles.length < total : result.articles.length === argv.limit;
+          if (hasMore) breadcrumbs.push({ action: 'next', cmd: `${base} --offset ${argv.offset + argv.limit}`, description: 'Next result page' });
+          emit(app, argv, { ...result, count: result.articles.length,
+            _formatted: result.articles.map(a => `${a.number || a.id || ''}  ${a.title || ''}\n${a.snippet || ''}`).join('\n\n') || 'No accessible articles matched.' },
+          `${result.articles.length} knowledge article(s)`, breadcrumbs);
+        }) })
+      .command({ command: 'show <id>', describe: 'Read an article by KB number or sys_id',
+        builder: p => p.positional('id', { type: 'string' }),
+        handler: wrap(async (argv, app) => {
+          if (!articleId(argv.id)) throw errUsage('Use a KB number or full article sys_id.');
+          const article = await read(app.sdk, `/${encodeURIComponent(argv.id)}`, new URLSearchParams());
+          if (!sysId.test(article.sys_id || '') || typeof article.content !== 'string') throw errAPI(200, 'Knowledge API returned no readable article content.');
+          emit(app, argv, { ...article, _formatted: `${article.number || argv.id}: ${article.short_description || ''}\n\n${markdown.turndown(article.content)}` },
+            article.short_description || article.number || argv.id,
+            [{ action: 'search', cmd: 'jsn knowledge search <text>', description: 'Find more articles' }]);
+        }) }),
+  };
+}