@jacebenson/jsn 3.3.1 → 3.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "3.3.1",
+  "version": "3.4.0",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {
@@ -10,7 +10,6 @@
   "scripts": {
     "test": "NODE_OPTIONS=--require=./suppress-warnings.cjs node --test $(find test -name '*.test.js')",
     "lint": "npx eslint src/ bin/ test/",
-    "postinstall": "node scripts/postinstall.mjs",
     "start": "NODE_OPTIONS=--require=./suppress-warnings.cjs node bin/jsn.js",
     "tag-reminder": "node scripts/tag-reminder.js",
     "release": "node scripts/release.js"

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}).`);
   }

package/src/commands/skill.js

@@ -20,6 +20,9 @@ const SKILL_RAW_URL = 'https://raw.githubusercontent.com/jacebenson/jsn/nodejs/s
  * Resolve the user's real home directory, even when Hermes overrides $HOME.
  */
 function realHomeDir() {
+  // getent doesn't exist on Windows; os.homedir() is reliable there.
+  if (process.platform === 'win32') return os.homedir();
+
   try {
     const result = execSync('getent passwd ' + process.env.USER + ' 2>/dev/null', { encoding: 'utf-8', timeout: 3000 });
     const home = result.trim().split(':')[5];

package/scripts/postinstall.mjs

@@ -1,84 +0,0 @@
-#!/usr/bin/env node
-/**
- * postinstall.mjs — Copies the bundled ServiceNow SKILL.md to agent skill directories
- * on npm global install. Mirrors what `basecamp`'s installer does for their skill.
- *
- * Only runs when `npm install -g @jacebenson/jsn`.
- * On `npm install` (local dependency), it's a no-op.
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
-import { fileURLToPath } from 'node:url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const SKILL_SOURCE = path.resolve(__dirname, '..', 'skills', 'servicenow', 'SKILL.md');
-const AGENTS_DIR = path.join(os.homedir(), '.agents', 'skills', 'servicenow');
-const AGENTS_SKILL = path.join(AGENTS_DIR, 'SKILL.md');
-const CLAUDE_SKILL_DIR = path.join(os.homedir(), '.claude', 'skills');
-const CLAUDE_SYMLINK = path.join(CLAUDE_SKILL_DIR, 'servicenow');
-
-function isGlobalInstall() {
-  return (
-    process.env.npm_config_global === 'true' ||
-    process.env.npm_lifecycle_event === 'postinstall'
-  );
-}
-
-function installSkill() {
-  // Check if running in a non-interactive/CI environment where .agents
-  // doesn't make sense. Skip silently.
-  if (!AGENTS_DIR.startsWith(os.homedir())) {
-    return;
-  }
-
-  if (!fs.existsSync(SKILL_SOURCE)) {
-    console.warn('  ⚠ jsn: ServiceNow SKILL.md not found at', SKILL_SOURCE);
-    return;
-  }
-
-  // Create ~/.agents/skills/servicenow/
-  try {
-    fs.mkdirSync(AGENTS_DIR, { recursive: true });
-  } catch {
-    // user's home might not be writable in container/CI
-    return;
-  }
-
-  // Copy the bundled skill file
-  try {
-    fs.copyFileSync(SKILL_SOURCE, AGENTS_SKILL);
-    console.log('  ✓ jsn: ServiceNow skill installed to ' + AGENTS_SKILL);
-  } catch (err) {
-    console.warn('  ⚠ jsn: Could not copy skill to ' + AGENTS_SKILL, err.message);
-    return;
-  }
-
-  // Symlinks require admin on Windows and are pointless outside Unix/Mac.
-  // Skip on win32 to avoid "system cannot find the path" errors.
-  if (process.platform === 'win32') return;
-
-  // Create symlink at ~/.claude/skills/servicenow → ../../.agents/skills/servicenow
-  // This is the same pattern basecamp's installer uses: ~/.claude/skills/basecamp → ../../.agents/skills/basecamp
-  try {
-    fs.mkdirSync(CLAUDE_SKILL_DIR, { recursive: true });
-
-    // Remove stale symlink or directory if it exists
-    try {
-      fs.unlinkSync(CLAUDE_SYMLINK);
-    } catch {
-      // doesn't exist — fine
-    }
-
-    // Relative symlink so it survives user home dir moves
-    const relativeTarget = path.relative(CLAUDE_SKILL_DIR, AGENTS_DIR);
-    fs.symlinkSync(relativeTarget, CLAUDE_SYMLINK, 'dir');
-    console.log('  ✓ jsn: Claude Code skill link at ' + CLAUDE_SYMLINK);
-  } catch (err) {
-    // Claude Code skill dir might not be expected — non-fatal
-    console.warn('  ⚠ jsn: Could not create Claude Code symlink:', err.message);
-  }
-}
-
-installSkill();