@jacebenson/jsn 3.1.5 → 3.3.0

package/src/commands/docs/sync.js

@@ -0,0 +1,75 @@
+// Clone or update the ServiceNow docs repo locally.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { getDocsSourceDir, getDocsSourceMarkdownDir, getDocsDbPath, docsDbExists } from './db.js';
+import { ingestDocs } from './ingest.js';
+import { refreshDocs } from './refresh.js';
+
+const REPO_URL = 'https://github.com/ServiceNow/ServiceNowDocs';
+const BRANCH = 'australia';
+
+function git(args, cwd, stdio = 'inherit') {
+  const r = spawnSync('git', args, { cwd, stdio });
+  if (r.status !== 0) {
+    throw new Error(`git ${args[0]} failed (exit ${r.status}).`);
+  }
+}
+
+export function syncDocs(opts = {}) {
+  const repoDir = opts.repoDir || getDocsSourceDir();
+  const markdownDir = opts.markdownDir || getDocsSourceMarkdownDir();
+  const dbPath = opts.dbPath || getDocsDbPath();
+  const embed = opts.embed !== false;
+  const noIngest = opts.noIngest === true;
+
+  const initialStatus = {
+    clone: !fs.existsSync(path.join(repoDir, '.git')),
+    docsApprox: 45000,
+    willEmbed: embed && noIngest === false,
+    minutesHint: embed ? 3 : 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`);
+  if (initialStatus.willEmbed) {
+    process.stderr.write('Pass --no-embed to skip semantic embeddings and finish faster.\n');
+  }
+  process.stderr.write('\n');
+
+  if (!initialStatus.clone) {
+    process.stderr.write(`Updating existing clone at ${repoDir} ...\n`);
+    git(['-C', repoDir, 'pull', '--ff-only'], repoDir, 'inherit');
+  } else {
+    fs.mkdirSync(path.dirname(repoDir), { recursive: true });
+    process.stderr.write(`Cloning ${REPO_URL} (branch ${BRANCH}) into ${repoDir} ...\n`);
+    git([
+      'clone',
+      '--depth', '1',
+      '--branch', BRANCH,
+      '--config', 'core.longpaths=true',
+      REPO_URL,
+      repoDir,
+    ], undefined, 'inherit');
+  }
+
+  if (!fs.existsSync(markdownDir)) {
+    throw new Error(`Expected markdown folder not found at ${markdownDir}.`);
+  }
+
+  if (noIngest) {
+    return { repoDir, markdownDir, dbPath, ingested: false, note: 'Run without --no-ingest to build the index.' };
+  }
+
+  // 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 });
+    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 });
+  return { repoDir, markdownDir, dbPath, ingested: true, incremental: false, ...result };
+}

package/src/commands/skill.js

@@ -4,32 +4,86 @@ import os from 'node:os';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
+import { execSync } from 'node:child_process';
+
 const SKILL_NAME = 'servicenow';
 const SKILL_REPO_PATH = path.join(
   path.dirname(fileURLToPath(import.meta.url)),
   '..', '..', 'skills', SKILL_NAME, 'SKILL.md'
 );
 
-const HERMES_SKILL_PATH = path.join(os.homedir(), '.hermes', 'skills', SKILL_NAME, 'SKILL.md');
-
 const SKILL_RAW_URL = 'https://raw.githubusercontent.com/jacebenson/jsn/nodejs/skills/servicenow/SKILL.md';
 
+/**
+ * Resolve the user's real home directory, even when Hermes overrides $HOME.
+ */
+function realHomeDir() {
+  try {
+    const result = execSync('getent passwd ' + process.env.USER + ' 2>/dev/null', { encoding: 'utf-8', timeout: 3000 });
+    const home = result.trim().split(':')[5];
+    if (home) return home;
+  } catch {
+    // fall through
+  }
+  return os.homedir();
+}
+
+/**
+ * Resolve the Hermes profile skill directory.
+ * Checks HERMES_PROFILE env var, then scans ~/.hermes/profiles/ for the first
+ * profile directory, falling back to ~/.hermes/skills/ (legacy symlink path).
+ */
+function hermesSkillDir() {
+  const base = path.join(realHomeDir(), '.hermes');
+  const profileEnv = process.env.HERMES_PROFILE;
+  let profileName = profileEnv;
+
+  if (!profileName) {
+    try {
+      const profiles = fs.readdirSync(path.join(base, 'profiles'));
+      // Pick the first real profile directory (skip . and ..)
+      profileName = profiles.find(d => d !== '.' && d !== '..') || null;
+    } catch {
+      profileName = null;
+    }
+  }
+
+  if (profileName) {
+    return path.join(base, 'profiles', profileName, 'skills', SKILL_NAME);
+  }
+  return path.join(base, 'skills', SKILL_NAME);
+}
+
+/** Resolve the installed SKILL.md path for Hermes. */
+function hermesSkillPath() {
+  return path.join(hermesSkillDir(), 'SKILL.md');
+}
+
 // Known agent skill directories (personal/user-level)
 // Keyed by agent name for the --target flag
+// Each value is the directory for the <name>/SKILL.md file
 const AGENT_SKILL_DIRS = {
-  hermes: path.join(os.homedir(), '.hermes', 'skills', SKILL_NAME),
-  copilot: path.join(os.homedir(), '.copilot', 'skills', SKILL_NAME),
-  claude: path.join(os.homedir(), '.claude', 'skills', SKILL_NAME),
-  cursor: path.join(os.homedir(), '.cursor', 'rules'),
-  agents: path.join(os.homedir(), '.agents', 'skills', SKILL_NAME),
+  hermes: hermesSkillDir(),
+  copilot: path.join(realHomeDir(), '.copilot', 'skills', SKILL_NAME),
+  vscode: path.join(realHomeDir(), '.copilot', 'instructions', SKILL_NAME),
+  claude: path.join(realHomeDir(), '.claude', 'skills', SKILL_NAME),
+  cursor: path.join(realHomeDir(), '.cursor', 'rules'),
+  agents: path.join(realHomeDir(), '.agents', 'skills', SKILL_NAME),
+  opencode: path.join(realHomeDir(), '.config', 'opencode', 'skills', SKILL_NAME),
+  openclaw: path.join(realHomeDir(), '.openclaw', 'skills', SKILL_NAME),
+  codex: path.join(realHomeDir(), '.codex', 'skills', SKILL_NAME),
 };
 
 const TARGET_NAMES = {
   hermes: 'Hermes Agent',
   copilot: 'GitHub Copilot',
+  vscode: 'VS Code (Copilot Instructions)',
   claude: 'Claude Code',
   cursor: 'Cursor',
   agents: 'Agents (open standard)',
+  opencode: 'OpenCode',
+  openclaw: 'OpenClaw',
+  codex: 'Codex CLI',
 };
 
 function readBundledSkill() {
@@ -40,21 +94,32 @@ function readBundledSkill() {
   }
 }
 
-function readInstalledSkill() {
-  try {
-    return fs.readFileSync(HERMES_SKILL_PATH, 'utf-8');
-  } catch {
-    return null;
+export async function checkSkill() {
+  // Compare all installed skill copies against GitHub.
+  // Uses a single HTTP fetch and reads all harness paths that exist.
+  // Returns the first installed version found for comparison, plus a list
+  // of harnesses where the skill is current vs outdated (or missing).
+  const SKILL_NAME = 'servicenow';
+
+  // Collect all installed copies that actually exist on disk
+  const installedCopies = [];
+  for (const [key, dir] of Object.entries(AGENT_SKILL_DIRS)) {
+    const skillPath = key === 'cursor'
+      ? path.join(dir, `${SKILL_NAME}.mdc`)
+      : path.join(dir, 'SKILL.md');
+    try {
+      const content = fs.readFileSync(skillPath, 'utf-8');
+      installedCopies.push({ harness: key, label: TARGET_NAMES[key], content, path: skillPath });
+    } catch {
+      // Not installed to this harness — skip
+    }
   }
-}
 
-export async function checkSkill() {
-  // Compare the Hermes-installed copy's version against GitHub (not the npm-bundled copy).
-  // Uses the YAML frontmatter "version" field so publishing jsn doesn't flag it.
-  const installed = readInstalledSkill() || readBundledSkill();
-  if (!installed) return { current: false, error: 'Skill file not found' };
+  // Fall back to bundled skill if nothing installed yet
+  const primary = installedCopies[0] || { content: readBundledSkill() };
+  if (!primary.content) return { current: false, error: 'Skill file not found' };
 
-  const installedVersion = extractVersion(installed);
+  const installedVersion = extractVersion(primary.content);
   if (!installedVersion) return { current: false, error: 'No version field in installed skill' };
 
   try {
@@ -68,11 +133,30 @@ export async function checkSkill() {
     if (!upstreamVersion) return { current: false, error: 'No version field in upstream skill' };
 
     const current = installedVersion === upstreamVersion;
+
+    // Check each installed copy for version match
+    const outdated = [];
+    for (const copy of installedCopies) {
+      const v = extractVersion(copy.content);
+      if (v && v !== upstreamVersion) {
+        outdated.push(copy.label);
+      }
+    }
+
+    const outdatedMsg = outdated.length > 0
+      ? ` Skill outdated for ${outdated.join(', ')} (v${installedVersion} vs GitHub v${upstreamVersion}) — run "jsn skill install" to update`
+      : null;
+
     return {
       current,
       installed_version: installedVersion,
       upstream_version: upstreamVersion,
-      error: current ? null : `Skill version ${installedVersion} vs GitHub ${upstreamVersion} — run "jsn skill install" to update`,
+      checked: installedCopies.length,
+      harnesses: {
+        installed: installedCopies.map(c => c.label),
+        outdated,
+      },
+      error: current ? null : outdatedMsg,
     };
   } catch {
     return { current: false, error: 'Could not check — GitHub unreachable' };
@@ -85,6 +169,9 @@ function extractVersion(content) {
   return m ? m[1] : null;
 }
 
+// Exported for testing
+export { realHomeDir, hermesSkillDir, extractVersion, AGENT_SKILL_DIRS, TARGET_NAMES };
+
 export function skillCmd(wrap) {
   return {
     command: 'skill',
@@ -112,13 +199,28 @@ export function skillCmd(wrap) {
           describe: 'Check if the bundled skill file is up to date with GitHub',
           handler: wrap(async (_argv, app) => {
             const result = await checkSkill();
+            const h = result.harnesses || {};
+
+            // Build a summary that shows which harnesses are installed and current
+            let summary;
             if (result.error && !result.current) {
-              app.ok(result, { summary: result.error });
+              summary = result.error;
             } else if (result.current) {
-              app.ok(result, { summary: `✓ Skill is current (v${result.installed_version})` });
+              const parts = [`✓ Skill is current (v${result.installed_version})`];
+              if (h.installed && h.installed.length > 0) {
+                parts.push(` — installed for ${h.installed.join(', ')}`);
+              }
+              summary = parts.join('');
             } else {
-              app.ok(result, { summary: `⚠ Skill outdated: installed v${result.installed_version} vs GitHub v${result.upstream_version} — run "jsn skill install" to update` });
+              const parts = [`⚠ Skill outdated: installed v${result.installed_version} vs GitHub v${result.upstream_version}`];
+              if (h.outdated && h.outdated.length > 0) {
+                parts.push(` — outdated for ${h.outdated.join(', ')}`);
+              }
+              parts.push(` — run "jsn skill install" to update`);
+              summary = parts.join('');
             }
+
+            app.ok(result, { summary });
           }),
         })
         .command({
@@ -148,7 +250,7 @@ export function skillCmd(wrap) {
             }, {
               summary: 'Skill file locations and install targets',
               breadcrumbs: [
-                { action: 'install', cmd: 'jsn skill install', description: 'Install to Hermes (default)' },
+                { action: 'install', cmd: 'jsn skill install', description: 'Interactive picker for install targets' },
                 { action: 'install-all', cmd: 'jsn skill install --target all', description: 'Install to all supported agents' },
                 { action: 'install-copilot', cmd: 'jsn skill install --target copilot', description: 'Install for GitHub Copilot' },
                 { action: 'install-claude', cmd: 'jsn skill install --target claude', description: 'Install for Claude Code' },
@@ -166,8 +268,7 @@ export function skillCmd(wrap) {
             })
             .option('target', {
               type: 'string',
-              describe: 'Target agent(s): hermes, copilot, claude, cursor, agents, or "all" (comma-separated)',
-              default: 'hermes',
+              describe: 'Target agent(s): hermes, copilot, vscode, claude, cursor, agents, opencode, openclaw, codex, or "all" (comma-separated). Omit for interactive picker.',
             }),
           handler: wrap(async (argv, app) => {
             const res = await fetch(SKILL_RAW_URL);
@@ -184,7 +285,8 @@ export function skillCmd(wrap) {
               const targetPath = path.join(p, 'SKILL.md');
               fs.writeFileSync(targetPath, content, 'utf-8');
               targets.push({ name: path.basename(argv.dir), path: targetPath });
-            } else {
+            } else if (argv.target) {
+              // Explicit --target: install to specified agents
               const rawTargets = argv.target.split(',').map(t => t.trim().toLowerCase());
               const all = rawTargets.includes('all');
 
@@ -204,6 +306,80 @@ export function skillCmd(wrap) {
                   }
                 }
               }
+            } else if (process.stdin.isTTY) {
+              // Interactive: show multi-select picker
+              const fetchedVersion = extractVersion(content);
+              // Check if any existing installed copies are outdated
+              const outdated = [];
+              if (fetchedVersion) {
+                for (const [key, dir] of Object.entries(AGENT_SKILL_DIRS)) {
+                  const skillPath = key === 'cursor'
+                    ? path.join(dir, `${SKILL_NAME}.mdc`)
+                    : path.join(dir, 'SKILL.md');
+                  try {
+                    const existing = fs.readFileSync(skillPath, 'utf-8');
+                    const existingVersion = extractVersion(existing);
+                    if (existingVersion && existingVersion !== fetchedVersion) {
+                      outdated.push(TARGET_NAMES[key]);
+                    }
+                  } catch {
+                    // Not installed — skip
+                  }
+                }
+              }
+              const promptMsg = outdated.length > 0
+                ? `Where should the jsn skill be installed? (${outdated.length} outdated)`
+                : 'Where should the jsn skill be installed?';
+
+              const { default: checkbox } = await import('@inquirer/checkbox');
+              const choices = Object.entries(TARGET_NAMES).map(([key, label]) => {
+                const dir = AGENT_SKILL_DIRS[key];
+                const targetPath = key === 'cursor'
+                  ? path.join(dir, `${SKILL_NAME}.mdc`)
+                  : path.join(dir, 'SKILL.md');
+                // Show tildified path for readability
+                const home = realHomeDir();
+                const displayPath = targetPath.replace(home, '~');
+                return {
+                  name: label,
+                  value: key,
+                  description: displayPath,
+                  // Pre-check agents whose skill dirs already exist
+                  checked: fs.existsSync(AGENT_SKILL_DIRS[key]),
+                };
+              });
+              const selected = await checkbox({
+                message: promptMsg,
+                choices,
+                instructions: '(space to toggle, enter to confirm)',
+              });
+
+              if (selected.length === 0) {
+                // Fall back to Hermes if nothing selected
+                selected.push('hermes');
+              }
+
+              for (const key of selected) {
+                const dir = AGENT_SKILL_DIRS[key];
+                if (key === 'cursor') {
+                  fs.mkdirSync(dir, { recursive: true });
+                  const targetPath = path.join(dir, `${SKILL_NAME}.mdc`);
+                  fs.writeFileSync(targetPath, content, 'utf-8');
+                  targets.push({ name: TARGET_NAMES[key], path: targetPath });
+                } else {
+                  fs.mkdirSync(dir, { recursive: true });
+                  const targetPath = path.join(dir, 'SKILL.md');
+                  fs.writeFileSync(targetPath, content, 'utf-8');
+                  targets.push({ name: TARGET_NAMES[key], path: targetPath });
+                }
+              }
+            } else {
+              // Non-interactive, no --target: install to Hermes only (backward compat)
+              const dir = AGENT_SKILL_DIRS.hermes;
+              fs.mkdirSync(dir, { recursive: true });
+              const targetPath = path.join(dir, 'SKILL.md');
+              fs.writeFileSync(targetPath, content, 'utf-8');
+              targets.push({ name: TARGET_NAMES.hermes, path: targetPath });
             }
 
             if (targets.length === 0) {

package/src/commands/version.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url';
 const NPM_PKG = '@jacebenson/jsn';
 const NPM_REGISTRY = `https://registry.npmjs.org/${NPM_PKG}/latest`;
 
-function getVersion() {
+export function getVersion() {
   try {
     const __dirname = path.dirname(fileURLToPath(import.meta.url));
     const pkgPath = path.join(__dirname, '..', '..', 'package.json');
@@ -16,7 +16,7 @@ function getVersion() {
   }
 }
 
-async function checkLatest() {
+export async function checkLatest() {
   try {
     const res = await fetch(NPM_REGISTRY);
     if (!res.ok) return null;

package/suppress-warnings.cjs

@@ -0,0 +1,13 @@
+// Suppresses the node:sqlite ExperimentalWarning on Node 22.x.
+// Loaded via NODE_OPTIONS=--require before the main ESM entry point.
+
+const original = process.emitWarning;
+process.emitWarning = function emitWarning(warning, ...args) {
+  const message = typeof warning === 'string'
+    ? warning
+    : (warning?.message || '');
+  if (message.includes('SQLite')) {
+    return;
+  }
+  return original.apply(this, [warning, ...args]);
+};