@jacebenson/jsn 4.3.13-dev.85.1 → 4.3.13-dev.87.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.13-dev.85.1",
+  "version": "4.3.13-dev.87.1",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {

package/src/commands/docs/db.js

@@ -4,6 +4,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import Database from 'better-sqlite3';
+import { docsReaderLease } from './locks.js';
 
 const LEGACY_DOCS_DIR_NAME = 'servicenow-cli/docs';
 const DOCS_DIR_NAME = 'docs';
@@ -131,7 +132,14 @@ export function defaultDocsRoots(opts = {}) {
 export function openDocsDb(opts = {}) {
   const dbPath = opts.dbPath || getDocsDbPath();
   ensureDocsCacheDir();
-  const db = new Database(dbPath);
+  fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+  const release = docsReaderLease(dbPath);
+  let db;
+  try {
+    db = new Database(dbPath);
+  } catch (error) { release(); throw error; }
+  const close = db.close.bind(db);
+  db.close = () => { try { return close(); } finally { release(); } };
   try {
     db.exec('PRAGMA journal_mode = WAL');
     return db;

package/src/commands/docs/docs.js

@@ -19,9 +19,24 @@ function formatBytes(n) {
 export function docsCmd(wrap) {
   return {
     command: 'docs [subcommand]',
-    describe: 'Search ServiceNow documentation locally (sync, status, search, serve)',
+    describe: 'Search ServiceNow documentation locally (install, sync, status, search, serve)',
     builder: (yargs) => {
       return yargs
+        .command({ command: 'install', describe: 'Install optional docs: raw GitHub files or a verified prebuilt searchable database',
+          builder: y => y.option('source', { type: 'string', choices: ['snapshot', 'github', 'skip'], describe: 'Explicit source; raw GitHub estimated ~5 minutes; snapshot estimate comes from manifest' })
+            .option('manifest-url', { type: 'string', describe: 'HTTPS snapshot manifest mirror' }),
+          handler: wrap(async (argv, app) => {
+            const { installDocumentation, offerDocumentation } = await import('./install.js');
+            const { canUsePicker } = await import('../../helpers.js');
+            const result = argv.source ? await installDocumentation(argv.source, { manifestURL: argv['manifest-url'] })
+              : canUsePicker(app, argv) ? await offerDocumentation(app, argv) : await installDocumentation(undefined);
+            app.ok(result, { summary: result.skipped ? 'Documentation skipped' : 'Documentation installed' });
+          }),
+        })
+        .command({ command: 'rollback', describe: 'Restore the previously installed local docs database', handler: wrap(async (_argv, app) => {
+          const { rollbackSnapshot } = await import('./snapshot.js');
+          app.ok(rollbackSnapshot(), { summary: 'Previous documentation index restored' });
+        }) })
         .command({
           command: 'sync',
           describe: 'Clone/update ServiceNowDocs and build the docs.db index',
@@ -77,8 +92,14 @@ export function docsCmd(wrap) {
               sock.connect(3000, '127.0.0.1');
             });
 
+            const { docsSnapshotStatus } = await import('./snapshot.js');
+            const snapshot = docsSnapshotStatus();
+            let available = null;
+            try { available = JSON.parse(fs.readFileSync(`${dbPath}.available.json`, 'utf8')); } catch { /* No background update information. */ }
             app.ok({
               state,
+              ...(snapshot ? { snapshot: { revision: snapshot.revision, schema: snapshot.schema } } : {}),
+              ...(snapshot && available?.installed === snapshot.revision && available.revision !== snapshot.revision ? { updateAvailable: { revision: available.revision, command: 'jsn docs install --source snapshot' } } : {}),
               downloaded: { ok: downloaded, path: repoDir },
               db: { ok: dbExists, path: dbPath },
               embedded: { ok: embedded },
@@ -99,6 +120,8 @@ 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 { ensureDocumentation } = await import('./install.js');
+            await ensureDocumentation(app, argv);
             const { searchDocs } = await import('./search.js');
             const result = searchDocs({
               query: argv.query,
@@ -259,7 +282,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).';
+      const summary = 'jsn docs — optional local documentation (install, sync, status, search, show, serve, rollback).';
       app.ok({
         command: 'docs',
         subcommands,

package/src/commands/docs/ingest.js

@@ -1,18 +1,35 @@
 // Ingest ServiceNow markdown docs into a SQLite database with FTS5 full-text search.
 
 import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { docsReaderLease } from './locks.js';
+import { installDatabase } from './replace.js';
 import { createHash } from 'node:crypto';
 import { parseFrontmatter } from '../../frontmatter.js';
-import { withDocsDb, initDocsSchema, getDocsDbPath, walkDocs, defaultDocsRoots } from './db.js';
+import { withDocsDb, initDocsSchema, getDocsDbPath, walkDocs, defaultDocsRoots, getDocsSourceDir } from './db.js';
 import { encodeText, phasesToBytes, docSurface, DEFAULT_DIM } from './hrr.js';
 
 export function ingestDocs(opts = {}) {
+  const dbPath = opts.dbPath || getDocsDbPath();
+  fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+  const staging = `${dbPath}.${randomUUID()}.building`;
+  const resource = opts.sourceResource || (!opts.roots ? getDocsSourceDir() : null);
+  if (resource) fs.mkdirSync(path.dirname(resource), { recursive: true });
+  const releaseSource = resource && !opts.sourceLeaseHeld ? docsReaderLease(resource) : () => {};
+  try {
+    const result = ingestStagedDocs({ ...opts, dbPath: staging });
+    if (result.errors) throw new Error(`Documentation ingestion failed for ${result.errors} files; existing index retained`);
+    installDatabase(staging, dbPath, { afterInstall: () => fs.rmSync(`${dbPath}.snapshot.json`, { force: true }) });
+    return { ...result, dbPath };
+  } finally { releaseSource(); fs.rmSync(staging, { force: true }); }
+}
+function ingestStagedDocs(opts = {}) {
   const dbPath = opts.dbPath || getDocsDbPath();
   const embed = opts.embed !== false;
   const roots = opts.roots || defaultDocsRoots(opts);
 
-  // Fresh build each run.
-  if (fs.existsSync(dbPath)) fs.rmSync(dbPath);
+  // The caller provides a fresh staging path; never unlink the installed index.
 
   return withDocsDb({ dbPath }, (db) => {
     initDocsSchema(db);

package/src/commands/docs/install.js

@@ -0,0 +1,86 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { docsReaderLease } from './locks.js';
+import { getDocsDbPath, getDocsCacheDir, getDocsSourceDir } from './db.js';
+import { fetchManifest, installSnapshot, snapshotEstimate, validateDatabase, installDatabase, docsSnapshotStatus, DEFAULT_MANIFEST_URL } from './snapshot.js';
+import { canUsePicker } from '../../helpers.js';
+import { errUsageHint } from '../../errors.js';
+
+export async function installDocumentation(source, options = {}) {
+  if (source === 'skip') return { source, skipped: true };
+  if (source === 'snapshot') {
+    const manifestURL = options.manifestURL || DEFAULT_MANIFEST_URL;
+    const manifest = options.manifest || await fetchManifest(manifestURL);
+    process.stderr.write(`Prebuilt searchable database: ${snapshotEstimate(manifest)}.\n`);
+    return installSnapshot({ manifestURL, manifest });
+  }
+  if (source !== 'github') throw errUsageHint('Choose a documentation source.', 'Use jsn docs install --source snapshot|github|skip');
+  process.stderr.write('Raw GitHub source: approximately 51,000 files plus local indexing; estimated 5–25 minutes including semantic indexing (prior runs ~5 minutes; validation full build ~21 minutes; actual time and size vary).\n');
+  fs.mkdirSync(getDocsCacheDir(), { recursive: true });
+  const staging = fs.mkdtempSync(path.join(getDocsCacheDir(), '.github-install-'));
+  try {
+    const { syncDocs } = await import('./sync.js');
+    const { ingestDocs } = await import('./ingest.js');
+    const repoDir = getDocsSourceDir(), dbPath = path.join(staging, 'docs.db');
+    syncDocs({ repoDir, markdownDir: path.join(repoDir, 'markdown'), noIngest: true, embed: false });
+    const releaseSource = docsReaderLease(repoDir);
+    let result;
+    try { result = ingestDocs({ dbPath, roots: [{ dir: path.join(repoDir, 'markdown'), prefix: '' }], embed: true }); }
+    finally { releaseSource(); }
+    if (result.errors) throw new Error('Raw documentation indexing failed; existing index retained');
+    validateDatabase(dbPath);
+    installDatabase(dbPath, getDocsDbPath(), { afterInstall: () => fs.rmSync(`${getDocsDbPath()}.snapshot.json`, { force: true }) });
+    return { source, documents: result.count, dbPath: getDocsDbPath() };
+  } finally { fs.rmSync(staging, { recursive: true, force: true }); }
+}
+export async function chooseDocumentationSource() {
+  const { select } = await import('../../prompts.js');
+  return select({ message: 'Install optional offline documentation?', choices: [
+    { name: 'Skip for now (first search will explain installation)', value: 'skip' },
+    { name: 'Prebuilt searchable database from jsn.jace.pro (size and estimate before approval)', value: 'snapshot' },
+    { name: 'GitHub raw source + local indexing (~51,000 files; estimated 5–25 minutes)', value: 'github' },
+  ] });
+}
+export async function offerDocumentation(_app, _argv = {}) {
+  let source = await chooseDocumentationSource();
+  let approvedManifest;
+  if (source === 'snapshot') {
+    try {
+      const manifest = await fetchManifest(DEFAULT_MANIFEST_URL, { fetchFn: (url, options) => fetch(url, { ...options, signal: AbortSignal.timeout(5000) }) });
+      approvedManifest = manifest;
+      const { confirm } = await import('../../prompts.js');
+      if (!await confirm({ message: `Download prebuilt searchable database: ${snapshotEstimate(manifest)}?`, default: false })) source = 'skip';
+    } catch {
+      throw errUsageHint('Prebuilt documentation is unavailable; nothing downloaded.', 'Choose GitHub raw source with jsn docs install --source github, or retry the snapshot later.');
+    }
+  }
+  return installDocumentation(source, { manifest: approvedManifest });
+}
+export async function ensureDocumentation(app, argv) {
+  if (fs.existsSync(getDocsDbPath())) { scheduleFreshnessCheck(); return; }
+  if (!canUsePicker(app, argv)) throw errUsageHint('No local documentation index. Documentation installation is optional and requires a source choice.',
+    'Run jsn docs install --source snapshot for a verified prebuilt database, or --source github for raw files + local indexing (estimated 5–25 minutes). Use --source skip to defer.');
+  const result = await offerDocumentation(app, argv);
+  if (result.skipped) throw errUsageHint('Documentation installation skipped.', 'Run jsn docs install --source snapshot|github when ready.');
+}
+export function scheduleFreshnessCheck() {
+  if (process.env.JSN_NO_DOCS_CHECK === '1') return;
+  const receipt = docsSnapshotStatus();
+  if (!receipt) return;
+  try {
+    const stamp = `${getDocsDbPath()}.check-stamp`;
+    try {
+      if (Date.now() - fs.statSync(stamp).mtimeMs < 86400000) return;
+      fs.rmSync(stamp);
+    } catch (error) { if (error.code !== 'ENOENT') return; }
+    fs.writeFileSync(stamp, '', { flag: 'wx' });
+    // A separate bounded worker prevents network from delaying local search.
+    const child = spawn(process.execPath, [fileURLToPath(new URL('./snapshot-check.js', import.meta.url)), getDocsDbPath()], {
+      detached: true, stdio: 'ignore', windowsHide: true,
+    });
+    child.on('error', () => {});
+    child.unref();
+  } catch { /* Local search remains available offline. */ }
+}

package/src/commands/docs/locks.js

@@ -0,0 +1,34 @@
+// Coordinate atomic snapshot replacement with short-lived local search readers.
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+function alive(pid) {
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code !== 'ESRCH'; }
+}
+function clearStale(filename) {
+  try {
+    const pid = Number(fs.readFileSync(filename, 'utf8'));
+    if (pid > 0 && alive(pid)) return false;
+    if (!(pid > 0) && Date.now() - fs.statSync(filename).mtimeMs < 120000) return false;
+    fs.rmSync(filename, { force: true });
+    return true;
+  } catch (error) { if (error.code === 'ENOENT') return true; throw error; }
+}
+export function docsReaderLease(dbPath) {
+  const lock = `${dbPath}.install-lock`;
+  if (!clearStale(lock)) throw new Error('Docs snapshot installation is in progress; retry shortly');
+  const lease = `${dbPath}.reader-${process.pid}-${randomUUID()}`;
+  fs.writeFileSync(lease, String(process.pid), { flag: 'wx', mode: 0o600 });
+  if (fs.existsSync(lock)) { fs.rmSync(lease, { force: true }); throw new Error('Docs snapshot installation is in progress; retry shortly'); }
+  return () => fs.rmSync(lease, { force: true });
+}
+export function docsInstallLease(dbPath) {
+  const lock = `${dbPath}.install-lock`;
+  clearStale(lock);
+  fs.writeFileSync(lock, String(process.pid), { flag: 'wx', mode: 0o600 });
+  return () => fs.rmSync(lock, { force: true });
+}
+export function docsHaveReaders(dbPath) {
+  return fs.readdirSync(path.dirname(dbPath)).filter(name => name.startsWith(path.basename(dbPath) + '.reader-'))
+    .some(name => !clearStale(path.join(path.dirname(dbPath), name)));
+}

package/src/commands/docs/refresh.js

@@ -2,20 +2,36 @@
 // after a ServiceNow docs update (e.g. `git pull` in the docs repo).
 
 import fs from 'node:fs';
+import path from 'node:path';
+import { docsReaderLease } from './locks.js';
+import { errUsageHint } from '../../errors.js';
 import { createHash } from 'node:crypto';
 import { parseFrontmatter } from '../../frontmatter.js';
-import { withDocsDb, getDocsDbPath, walkDocs, defaultDocsRoots } from './db.js';
+import { withDocsDb, getDocsDbPath, walkDocs, defaultDocsRoots, getDocsSourceDir } from './db.js';
 import { encodeText, phasesToBytes, docSurface, DEFAULT_DIM } from './hrr.js';
 
 export function refreshDocs(opts = {}) {
+  const resource = opts.sourceResource || (!opts.roots ? getDocsSourceDir() : null);
+  if (resource) fs.mkdirSync(path.dirname(resource), { recursive: true });
+  const release = resource && !opts.sourceLeaseHeld ? docsReaderLease(resource) : () => {};
+  try { return refreshDocsLocked(opts); } finally { release(); }
+}
+function refreshDocsLocked(opts = {}) {
   const dbPath = opts.dbPath || getDocsDbPath();
   const roots = opts.roots || defaultDocsRoots(opts);
 
+  if (roots.some(root => (!root.prefix || opts.roots) && (!fs.existsSync(root.dir) || !fs.statSync(root.dir).isDirectory()))) {
+    throw errUsageHint('Raw documentation source is missing; existing index retained.', 'Use jsn docs install --source snapshot to update a prebuilt index, or --source github to install raw source before refreshing.');
+  }
+
   if (!fs.existsSync(dbPath)) {
     throw new Error(`Database not found: ${dbPath}. Run "jsn docs sync" first for the initial build.`);
   }
 
   return withDocsDb({ dbPath }, (db) => {
+    if (!opts.sourceLeaseHeld && db.prepare("SELECT value FROM meta WHERE key='snapshot_revision'").get()) {
+      throw errUsageHint('A prebuilt snapshot cannot refresh from an unrelated raw clone; existing index retained.', 'Use jsn docs install --source snapshot, or jsn docs sync to explicitly update raw source and rebuild.');
+    }
     db.exec('PRAGMA journal_mode = WAL');
 
     const cols = db.prepare('PRAGMA table_info(docs)').all().map((c) => c.name);
@@ -48,9 +64,11 @@ export function refreshDocs(opts = {}) {
     const seen = new Set();
     const started = Date.now();
 
+    const missingPrefixes = roots.filter(root => root.prefix && !fs.existsSync(root.dir)).map(root => root.prefix);
     const files = [...walkDocs(roots)];
 
     db.exec('BEGIN');
+    db.prepare("DELETE FROM meta WHERE key='snapshot_revision'").run();
     for (const { file, rel } of files) {
       try {
         seen.add(rel);
@@ -105,7 +123,7 @@ export function refreshDocs(opts = {}) {
     }
 
     for (const [rel, row] of existing) {
-      if (!seen.has(rel)) {
+      if (!missingPrefixes.some(prefix => rel.startsWith(prefix)) && !seen.has(rel)) {
         del.run(row.id);
         removed++;
       }
@@ -116,6 +134,8 @@ export function refreshDocs(opts = {}) {
     db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
     db.prepare("INSERT OR REPLACE INTO meta(key, value) VALUES('synced_at', ?)").run(String(Date.now()));
 
+    fs.rmSync(`${dbPath}.snapshot.json`, { force: true });
+    fs.rmSync(`${dbPath}.available.json`, { force: true });
     const secs = ((Date.now() - started) / 1000).toFixed(1);
     return { added, updated, removed, unchanged, errors, secs, dbPath, embeddingsEnabled };
   });

package/src/commands/docs/replace.js

@@ -0,0 +1,30 @@
+import fs from 'node:fs';
+import Database from 'better-sqlite3';
+import { docsInstallLease, docsHaveReaders } from './locks.js';
+import { errUsageHint } from '../../errors.js';
+
+export function installDatabase(staged, dbPath, { afterInstall = () => {} } = {}) {
+  let release;
+  try {
+    release = docsInstallLease(dbPath);
+    // Refuse active databases rather than detach a WAL from its live database.
+    if (docsHaveReaders(dbPath)) throw errUsageHint('Docs index is in use; existing index retained.', 'Close other jsn docs commands and retry installation.');
+    if (['-wal', '-shm'].some(suffix => fs.existsSync(dbPath + suffix))) {
+      // Recover an interrupted reader/writer through SQLite, never by unlinking WAL.
+      const previous = new Database(dbPath, { fileMustExist: true });
+      try {
+        previous.pragma('busy_timeout = 2000');
+        const [checkpoint] = previous.pragma('wal_checkpoint(TRUNCATE)');
+        if (checkpoint.busy || previous.pragma('journal_mode = DELETE', { simple: true }) !== 'delete') {
+          throw errUsageHint('Docs index is in use; existing index retained.', 'Close other jsn docs commands and retry installation.');
+        }
+      } finally { previous.close(); }
+    }
+    if (fs.existsSync(dbPath)) fs.copyFileSync(dbPath, `${dbPath}.previous`);
+    fs.renameSync(staged, dbPath);
+    fs.rmSync(`${dbPath}.available.json`, { force: true });
+    afterInstall();
+  } finally {
+    release?.();
+  }
+}

package/src/commands/docs/snapshot-check.js

@@ -0,0 +1,11 @@
+// Detached read-only freshness worker. Never replaces the installed index.
+import fs from 'node:fs';
+import { fetchManifest } from './snapshot.js';
+const dbPath = process.argv[2];
+try {
+  const receipt = JSON.parse(fs.readFileSync(`${dbPath}.snapshot.json`, 'utf8'));
+  const manifest = await fetchManifest(receipt.manifestURL, { fetchFn: (url, options) => fetch(url, { ...options, signal: AbortSignal.timeout(5000) }) });
+  const filename = `${dbPath}.available.json`;
+  fs.writeFileSync(`${filename}.${process.pid}.tmp`, JSON.stringify({ revision: manifest.revision, installed: receipt.revision, checkedAt: Date.now() }));
+  fs.renameSync(`${filename}.${process.pid}.tmp`, filename);
+} catch { /* Offline and interrupted freshness checks leave the local index intact. */ }

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/setup.js

@@ -14,6 +14,7 @@ const HUB_CHOICES = [
   { name: 'Change settings', value: 'modify', command: 'jsn auth modify --profile <name> --read-only --confirm-deletes --no-include-counts' },
   { name: 'Sign out (keep the profile)', value: 'logout', command: 'jsn auth logout --profile <name> --force (only after explicit approval)' },
   { name: 'Remove a connection', value: 'remove', command: 'jsn auth remove <name>' },
+  { name: 'Install optional offline documentation', value: 'docs', command: 'jsn docs install --source snapshot|github|skip' },
 ];
 
 const setupHelp = () => [
@@ -101,8 +102,13 @@ export function setupCmd(wrap) {
   return {
     command: 'setup',
     describe: 'Set up and manage your ServiceNow instances (interactive)',
-    builder: y => y.epilogue(setupHelp()),
+    builder: y => y.option('docs-source', { type: 'string', choices: ['snapshot', 'github', 'skip'], describe: 'Install optional documentation directly without the authentication wizard' }).epilogue(setupHelp()),
     handler: wrap(async (argv, app) => {
+      if (argv['docs-source']) {
+        const { installDocumentation } = await import('./docs/install.js');
+        app.ok(await installDocumentation(argv['docs-source']));
+        return;
+      }
       const { canUsePicker } = await import('../helpers.js');
       if (!app.isInteractive() || !canUsePicker(app, argv)) {
         throw errUsageHint('"jsn setup" is interactive. Use explicit auth commands instead.', setupHelp());
@@ -111,10 +117,20 @@ export function setupCmd(wrap) {
       if (profileNames.length === 0) {
         const result = await loginWizard(app, argv);
         await showAuthStatus({ ...argv, profile: result.profileName }, app);
+        const { docsDbExists } = await import('./docs/db.js');
+        if (!docsDbExists()) {
+          const { offerDocumentation } = await import('./docs/install.js');
+          app.ok(await offerDocumentation(app, argv));
+        }
         return;
       }
       const action = await authHubMenu();
       if (action === undefined) return;
+      if (action === 'docs') {
+        const { offerDocumentation } = await import('./docs/install.js');
+        app.ok(await offerDocumentation(app, argv));
+        return;
+      }
       const result = await dispatchSetupAction(app, argv, action);
       if (action !== 'status') await showAuthStatus({ ...argv, profile: result?.profile || result?.profileName }, app);
     }),