@jacebenson/jsn 3.3.2 → 3.4.0

package/package.json

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

package/src/commands/docs/docs.js

@@ -114,7 +114,84 @@ export function docsCmd(wrap) {
               docType: argv['doc-type'],
               mode: argv.mode,
             });
-            app.ok(result, { summary: `${result.count} result(s) for "${result.query}" (${result.mode})` });
+
+            // Build a readable text blob for styled TTY output.
+            const lines = [];
+            for (const r of result.results) {
+              const title = r.title || r.path || '(untitled)';
+              const snippet = (r.snippet || r.body || '')
+                .replace(/\\n/g, ' ')
+                .replace(/\s+/g, ' ')
+                .trim()
+                .substring(0, 200);
+              lines.push(`[${r.id}] ${title}`);
+              if (snippet) lines.push(`  ${snippet}`);
+              lines.push('');
+            }
+
+            const hasMore = result.total > result.count;
+            if (hasMore) {
+              const nextOffset = (result.count + (argv.offset || 0));
+              lines.push(`… ${result.total - result.count} more results (use --offset ${nextOffset} for next page)`);
+            }
+
+            app.ok({
+              _formatted: lines.join('\n'),
+              query: result.query,
+              mode: result.mode,
+              total: result.total,
+              count: result.count,
+              results: result.results,
+            }, { summary: `${result.count} of ${result.total} result(s) for "${result.query}" (${result.mode})` });
+          }),
+        })
+        .command({
+          command: 'show <id-or-path>',
+          describe: 'Show a documentation page by id or path',
+          builder: (y) => y
+            .positional('id-or-path', { type: 'string', describe: 'Document id (number) or file path' })
+            .option('lines', { type: 'number', default: 80, describe: 'Lines of body to show in terminal (use --json for full content)' }),
+          handler: wrap(async (argv, app) => {
+            const 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);
+
+            if (!row) {
+              throw Object.assign(new Error(`No doc found for "${idOrPath}"`), { code: 'not_found' });
+            }
+
+            let fm = {};
+            try { fm = JSON.parse(row.frontmatter || '{}'); } catch { /* ignore */ }
+
+            const title = row.title || fm.title || row.path || '(untitled)';
+            const header = `${title}\n${'─'.repeat(Math.min(title.length, 80))}`;
+            const body = row.body || '';
+            const bodyLines = body.split('\n');
+            const truncated = bodyLines.length > argv.lines;
+            const preview = bodyLines.slice(0, argv.lines).join('\n');
+            const hint = truncated ? `\n\n… ${bodyLines.length - argv.lines} more lines (use --lines ${bodyLines.length} or --json for full content)` : '';
+
+            app.ok({
+              id: row.id,
+              path: row.path,
+              title: row.title,
+              bundle: row.bundle,
+              release: row.release,
+              canonical_url: fm.canonical_url || null,
+              body,
+              _formatted: `${header}\n\n${preview}${hint}`,
+            }, { summary: `Doc ${row.id}: ${title}` });
           }),
         })
         .command({
@@ -157,9 +234,13 @@ export function docsCmd(wrap) {
       process.stdout.write('  sync      Download docs and build a searchable index (handles updates too)\n');
       process.stdout.write('  status    Show whether docs are downloaded, indexed, embedded, or served\n');
       process.stdout.write('  search    Full-text + semantic search across the local docs index\n');
+      process.stdout.write('  show      Display a full documentation page by id or path\n');
       process.stdout.write('  serve     Start a local web UI for browsing and searching docs\n');
       process.stdout.write('\n');
       process.stdout.write('Tip: use "jsn docs serve --expose" to bind to 0.0.0.0 and share on your network.\n');
+      process.stdout.write('\n');
+      const dbPath = getDocsDbPath();
+      process.stdout.write(`Docs DB: ${dbPath} (run "jsn docs status" for details, or query directly with sqlite3)\n`);
       process.stdout.write('\nRun "jsn docs <command> --help" for details.\n');
     },
   };

package/src/commands/docs/search.js

@@ -25,7 +25,7 @@ export function searchDocs(opts = {}) {
   }
 
   const db = new DatabaseSync(dbPath, { readOnly: true });
-  const limit = Math.min(parseInt(opts.limit, 10) || 20, 100);
+  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;
   const docType = opts.docType ? String(opts.docType) : null;
@@ -44,6 +44,11 @@ export function searchDocs(opts = {}) {
   }
   const where = filters.length ? ' AND ' + filters.join(' AND ') : '';
 
+  // Total matching docs (for pagination)
+  const total = db
+    .prepare(`SELECT COUNT(*) AS n FROM docs_fts WHERE docs_fts MATCH @q${where}`)
+    .get({ q, ...(bundle && { bundle }), ...(docType && { docType }) }).n;
+
   let rows;
   if (!useHybrid) {
     rows = db
@@ -133,6 +138,7 @@ export function searchDocs(opts = {}) {
   return {
     query: q,
     mode: useHybrid ? 'hybrid' : 'keyword',
+    total,
     count: rows.length,
     results: rows,
   };

package/src/commands/docs/sync.js

@@ -12,6 +12,9 @@ const BRANCH = 'australia';
 
 function git(args, cwd, stdio = 'inherit') {
   const r = spawnSync('git', args, { cwd, stdio });
+  if (r.error && r.error.code === 'ENOENT') {
+    throw new Error('git is not installed. Install git to sync docs, or download the docs repo manually.');
+  }
   if (r.status !== 0) {
     throw new Error(`git ${args[0]} failed (exit ${r.status}).`);
   }