@jacebenson/jsn 3.1.5 → 3.2.0

package/package.json

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

package/src/app.js

@@ -3,7 +3,7 @@
 import { AuthManager } from './auth.js';
 import { SDKClient } from './sdk.js';
 import { OutputWriter, FormatAuto, FormatJSON, FormatMarkdown, FormatQuiet, FormatStyled } from './output.js';
-import { getEffectiveInstance } from './config.js';
+import { getEffectiveInstance, normalizeInstanceURL } from './config.js';
 import { extractProfileName } from './helpers.js';
 import { getCurrentUser, getCurrentApplication, getCurrentUpdateSet } from './context.js';
 import { errUsage, errAuth } from './errors.js';
@@ -55,6 +55,8 @@ export class App {
   }
 
   getEffectiveInstance() {
+    // Command-line override (--instance, --profile) takes precedence
+    if (this._overrideInstance) return this._overrideInstance;
     return getEffectiveInstance(this.config);
   }
 
@@ -191,6 +193,18 @@ export class App {
       throw errAuth('Not authenticated');
     }
   }
+
+  /**
+   * Override the effective instance for this command run.
+   * Rebuilds the SDK client for the new instance.
+   */
+  setEffectiveInstance(url) {
+    const normalizedUrl = normalizeInstanceURL(url);
+    if (normalizedUrl) {
+      this._overrideInstance = normalizedUrl;
+      this.sdk = new SDKClient(normalizedUrl, this.auth);
+    }
+  }
 }
 
 function resolveFormat(fmt) {

package/src/auth.js

@@ -58,6 +58,24 @@ function removePKCEState(instance) {
 const DEFAULT_OAUTH_CLIENT_ID = '543e5655f77746a28228c6009a599dfb';
 const REDIRECT_URI = '/sdk-oauth.do';
 
+// ─── WSL detection ───
+
+/**
+ * Detect if running under Windows Subsystem for Linux.
+ * Reads /proc/version which contains "Microsoft" or "WSL" on WSL.
+ */
+let _cachedIsWSL = null;
+async function isWSLEnv() {
+  if (_cachedIsWSL !== null) return _cachedIsWSL;
+  try {
+    const data = fs.readFileSync('/proc/version', 'utf-8');
+    _cachedIsWSL = /microsoft|wsl/i.test(data);
+  } catch {
+    _cachedIsWSL = false;
+  }
+  return _cachedIsWSL;
+}
+
 // ─── Basic auth from environment variables ───
 // SN_USERNAME / SN_PASSWORD — global credentials
 // SN_<INSTANCE>_USERNAME / SN_<INSTANCE>_PASSWORD — instance-specific (e.g. SN_DEV328604_USERNAME)
@@ -386,10 +404,23 @@ export class AuthManager {
       args = [authURL];
     } else if (platform === 'win32') {
       cmd = 'cmd';
-      args = ['/c', 'start', authURL];
+      // Windows: cmd.exe interprets & as a command separator, which truncates
+      // the URL after the first parameter. Passing an empty string as the first
+      // arg to `start` serves as the window title, and spawn auto-quotes the
+      // URL arg, protecting & and other special chars from cmd.exe's parser.
+      args = ['/c', 'start', '', authURL];
     } else {
-      cmd = 'xdg-open';
-      args = [authURL];
+      // WSL detection: check if we're running under Windows Subsystem for Linux
+      // On WSL, xdg-open delegates to cmd.exe /C start <url>, which truncates
+      // on &. We call cmd.exe directly with proper quoting instead.
+      const isWSL = platform === 'linux' && (await isWSLEnv());
+      if (isWSL) {
+        cmd = 'cmd.exe';
+        args = ['/c', 'start', '', authURL];
+      } else {
+        cmd = 'xdg-open';
+        args = [authURL];
+      }
     }
     const child = open(cmd, args, { detached: true, stdio: 'ignore' });
     child.on('error', () => {

package/src/cli.js

@@ -3,7 +3,9 @@
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import process from 'node:process';
-import { loadConfig, getEffectiveInstance } from './config.js';
+import path from 'node:path';
+import fs from 'node:fs';
+import { loadConfig, getEffectiveInstance, globalConfigDir } from './config.js';
 import { App } from './app.js';
 import { renderHelp } from './help.js';
 import { isMutationCommand } from './mutations.js';
@@ -25,7 +27,8 @@ import { groupRolesCmd } from './commands/grouproles.js';
 import { ticketsCmd } from './commands/tickets.js';
 import { versionCmd } from './commands/version.js';
 import { devCmd } from './commands/dev.js';
-import { skillCmd, checkSkill } from './commands/skill.js';
+import { skillCmd } from './commands/skill.js';
+import { getVersion, checkLatest } from './commands/version.js';
 
 // Dev subcommands promoted to root level for progressive disclosure
 import {
@@ -153,8 +156,23 @@ export function buildCLI() {
         if (argv.format) {
           app.output.setFormat(argv.format);
         }
+        // --profile: resolve profile name to its instance URL
+        // --instance wins if both are specified (explicit URL > profile reference)
+        if (argv.profile) {
+          const profile = (cfg.profiles || {})[argv.profile];
+          if (!profile) {
+            process.stderr.write(`Error: Unknown profile "${argv.profile}"\n`);
+            process.exit(1);
+          }
+          const url = profile.instance_url;
+          app._overrideInstance = url;
+          argv._overrideInstance = url;
+          // Temporarily switch active profile so auth picks up the right user
+          cfg.activeProfile = argv.profile;
+        }
         if (argv.instance) {
           app._overrideInstance = argv.instance;
+          argv._overrideInstance = argv.instance;
         }
       },
       // Guard mutation commands when no instance configured
@@ -166,6 +184,7 @@ export function buildCLI() {
         // Check for --instance override
         if (argv.instance) {
           app._overrideInstance = argv.instance;
+          argv._overrideInstance = argv.instance;
         }
         // Determine if this is a mutation
         const subcommand = (argv._[1] || '').toString();
@@ -183,18 +202,40 @@ export function buildCLI() {
 
       const cmd = (argv._[0] || '').toString();
 
-      // Auto-check skill on every command (fire-and-forget, non-blocking)
-      const skipSkillCheck = ['help', 'version', 'completion', 'skill'].includes(cmd)
-        || process.env.JSN_NO_SKILL_CHECK === '1'
-        || argv['no-skill-check']
+      // Daily npm version check (fire-and-forget, non-blocking)
+      // Checks npm for newer jsn releases, at most once per 24 hours.
+      const skipNpmCheck = ['help', 'version', 'completion', 'skill'].includes(cmd)
+        || process.env.JSN_NO_VERSION_CHECK === '1'
         || argv.json
         || argv.quiet;
-      if (!skipSkillCheck) {
-        checkSkill().then(result => {
-          if (result && !result.current && result.error) {
-            process.stderr.write(`\n⚠ ${result.error}\n\n`);
+      if (!skipNpmCheck) {
+        const cacheFile = path.join(globalConfigDir(), '.last-npm-check');
+        let shouldCheck = true;
+        try {
+          const mtime = fs.statSync(cacheFile).mtimeMs;
+          const elapsed = Date.now() - mtime;
+          // Only check if >= 24 hours since last check
+          if (elapsed < 86400000) shouldCheck = false;
+        } catch {
+          // File doesn't exist — check
+        }
+
+        if (shouldCheck) {
+          const version = getVersion();
+          checkLatest().then(latest => {
+            if (latest && version !== latest) {
+              process.stderr.write(`\n⚠ jsn ${latest} available (you have ${version}) — run "npm install -g @jacebenson/jsn" to update\n\n`);
+            }
+          }).catch(() => {});
+
+          // Stamp the cache file (write async, don't block)
+          try {
+            fs.mkdirSync(globalConfigDir(), { recursive: true });
+            fs.writeFileSync(cacheFile, String(Date.now()), 'utf-8');
+          } catch {
+            // Non-fatal
           }
-        }).catch(() => {});
+        }
       }
 
       // Print context header for interactive terminals

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;