@jacebenson/jsn 3.0.3 → 3.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "3.0.3",
+  "version": "3.0.6",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {
@@ -43,4 +43,4 @@
     "README.md",
     "LICENSE"
   ]
-}
+}

package/skills/servicenow/SKILL.md

@@ -10,12 +10,12 @@ description: |
 license: MIT
 compatibility: |
   Requires jsn CLI (github.com/jacebenson/jsn). Install via:
-  curl -fsSL https://jsn.jace.pro/install | bash
+  npm install -g @jacebenson/jsn
   Works with Claude Code, OpenCode, Cursor, and agentskills-compatible tools.
   
-  Windows users: Download from GitHub releases. If jsn is not in your PATH, the setup
-  command will automatically detect its location and show the correct command path
-  (e.g., `.\jsn.exe tables list` instead of `jsn tables list`).
+  Windows users: Install Node.js first, then the npm command above. If jsn is not
+  in your PATH, the setup command will automatically detect its location and show
+  the correct command path.
 metadata:
   author: jacebenson
   version: "1.0.0"

package/src/cli.js

@@ -142,9 +142,12 @@ export const cli = yargs(hideBin(process.argv))
     }
 
     // Auto-check skill on every command (fire-and-forget, non-blocking)
+    // Skipped under --json, --quiet, --no-skill-check, or env var
     const skipSkillCheck = ['help', 'version', 'completion', 'skill'].includes(cmd)
       || process.env.JSN_NO_SKILL_CHECK === '1'
-      || argv['no-skill-check'];
+      || argv['no-skill-check']
+      || argv.json
+      || argv.quiet;
     if (!skipSkillCheck) {
       // Fire check but don't await — it runs in background
       checkSkill().then(result => {

package/src/commands/dev/_simple.js

@@ -81,7 +81,6 @@ export const spPagesCmd = (wrap) => buildDevCmd('sppages', 'sp_page', ['sp-pages
 export const spWidgetsCmd = (wrap) => buildDevCmd('spwidgets', 'sp_widget', ['sp-widget', 'widgets'], ['id', 'name', 'sys_scope'], wrap, { singular: 'Service Portal widget', readOnly: true });
 export const uiPagesCmd = (wrap) => buildDevCmd('uipages', 'sys_ui_page', ['ui-page', 'pages'], ['name', 'sys_scope'], wrap, { singular: 'UI page', scopeValidation: true });
 export const appMenuCmd = (wrap) => buildDevCmd('appmenu', 'sys_app_application', ['app-menu', 'menu'], ['name', 'active', 'sys_scope'], wrap, { singular: 'application menu', scopeValidation: true });
-export const scRAPICmd = (wrap) => buildDevCmd('scrapi', 'sys_ws_operation', ['scripted-rest', 'rest-api'], ['name', 'sys_ws_definition', 'sys_scope'], wrap, { singular: 'scripted REST API', readOnly: true });
 
 // Commands with full CRUD
 export const aclsCmd = (wrap) => buildDevCmd('acls', 'sys_security_acl', ['acl'], ['name', 'operation', 'type', 'active', 'sys_scope'], wrap, { singular: 'ACL', scopeValidation: true });

package/src/commands/dev/eval.js

@@ -7,10 +7,19 @@ export function evalCmd(wrap) {
     builder: (yargs) => {
       return yargs
         .option('script', { alias: 's', type: 'string', describe: "JavaScript code to execute (single-quote the script, double quotes inside: --script 'gs.log(\"Hello\")')" })
-        .option('file', { alias: 'f', type: 'string', describe: 'Read script from file (avoids shell quoting issues)' });
+        .option('file', { alias: 'f', type: 'string', describe: 'Read script from file (avoids shell quoting issues)' })
+        .option('scope', { alias: null, type: 'string', describe: 'Scope name or sys_id to run the script under (default: global)' });
     },
     handler: wrap(async (argv, app) => {
       let script;
+      let scopeSysId = null;
+
+      if (argv.scope) {
+        scopeSysId = await app.sdk.resolveScope(argv.scope);
+        if (!scopeSysId) {
+          throw new Error(`Scope not found: ${argv.scope}`);
+        }
+      }
 
       if (argv.file) {
         script = fs.readFileSync(argv.file, 'utf-8');
@@ -20,13 +29,20 @@ export function evalCmd(wrap) {
         throw new Error('--script or --file is required');
       }
 
-      const output = await app.sdk.executeScript(script);
+      if (scopeSysId) {
+        script = `var $scopeSysId = '${scopeSysId}';\n${script}`;
+      }
+
+      const warning = scopeSysId
+        ? ` ⚠️ Records without explicit sys_scope will land in global. Use $scopeSysId variable.`
+        : '';
+      const output = await app.sdk.executeScript(script, argv.scope);
       app.ok({
         script,
         output,
         instance: app.getEffectiveInstance(),
       }, {
-        summary: 'Script executed',
+        summary: 'Script executed' + warning,
         breadcrumbs: [{
           action: 'eval',
           cmd: 'jsn dev eval --script \'...\'',

package/src/commands/dev/scrapi.js

@@ -0,0 +1,344 @@
+// Custom scraPI command: list/show individual operations + one-shot API definition creation
+//
+// The 'create' subcommand lets you build a full Scripted REST API in one call:
+//   jsn dev scrapi create \
+//     --name "SL Managed Services" --service-id managed_services --namespace slapi \
+//     --resource create=POST:/create:./create.js \
+//     --resource comment=POST:/comment:./comment.js
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { formatRecordForDisplay, getStringField, isHexString } from '../../helpers.js';
+import { errUsageHint } from '../../errors.js';
+
+/**
+ * Parse a --resource flag value of the form:
+ *   name=METHOD:/path:./script.js
+ * Returns { name, method, relativePath, scriptFile } or null.
+ */
+function parseResourceArg(raw) {
+  if (!raw || typeof raw !== 'string') return null;
+
+  // Split on first '=' to get name and the rest
+  const eqIdx = raw.indexOf('=');
+  if (eqIdx === -1) return null;
+  const name = raw.slice(0, eqIdx).trim();
+  const rest = raw.slice(eqIdx + 1).trim();
+
+  // Rest should be METHOD:/path:./script.js
+  // Split on first ':' to separate METHOD from the path:file part
+  const colonIdx = rest.indexOf(':');
+  if (colonIdx === -1) return null;
+  const method = rest.slice(0, colonIdx).trim().toUpperCase();
+  const pathFile = rest.slice(colonIdx + 1).trim();
+
+  // Split pathAndFile on last ':' to separate relative_path from script file
+  const lastColon = pathFile.lastIndexOf(':');
+  if (lastColon === -1) return null;
+  const relativePath = pathFile.slice(0, lastColon).trim();
+  const scriptFile = pathFile.slice(lastColon + 1).trim();
+
+  if (!relativePath.startsWith('/')) {
+    return null; // relative_path must start with /
+  }
+
+  return { name, method, relativePath, scriptFile };
+}
+
+/**
+ * Read script content from a file path (relative to cwd or absolute).
+ */
+function readScriptFile(filePath) {
+  const resolved = path.resolve(filePath);
+  if (!fs.existsSync(resolved)) {
+    throw errUsageHint(
+      `Script file not found: ${filePath}`,
+      `Checked: ${resolved}`
+    );
+  }
+  return fs.readFileSync(resolved, 'utf-8');
+}
+
+export function scrapiCmd(wrap) {
+  return {
+    command: 'scrapi [subcommand]',
+    aliases: ['scripted-rest', 'rest-api'],
+    describe: 'Manage Scripted REST APIs (list/show operations, create full APIs with resources)',
+    builder: (yargs) => {
+      return yargs
+        // ── list ──
+        .command({
+          command: 'list',
+          aliases: ['ls'],
+          describe: 'List API operations',
+          builder: (y) => y
+            .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident")' })
+            .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns' })
+            .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' }),
+          handler: wrap(async (argv, app) => {
+            const columns = argv.columns ? argv.columns.split(',') : ['name', 'sys_ws_definition', 'http_method', 'relative_path', 'sys_scope'];
+            const query = argv.query || '';
+            const limit = argv.limit;
+
+            const params = new URLSearchParams();
+            params.set('sysparm_limit', String(limit));
+            params.set('sysparm_display_value', 'all');
+            params.set('sysparm_fields', ['sys_id', ...columns].join(','));
+            const q = query ? query + '^ORDERBYDESCsys_updated_on' : 'ORDERBYDESCsys_updated_on';
+            params.set('sysparm_query', q);
+            const records = await app.sdk.list('sys_ws_operation', params);
+
+            app.ok({
+              table: 'sys_ws_operation',
+              count: records.length,
+              columns,
+              records: records.map(r => formatRecordForDisplay(r, columns)),
+              context: { instance_url: app.getEffectiveInstance() },
+            }, {
+              summary: `${records.length} operation(s)`,
+              breadcrumbs: [
+                { action: 'create', cmd: 'jsn dev scrapi create --name "My API" --service-id my-api --namespace myapp --resource get=GET:/items:./script.js', description: 'Create a new REST API' },
+                { action: 'show', cmd: 'jsn dev scrapi show <name>', description: 'Show operation details' },
+              ],
+            });
+          }),
+        })
+        // ── show ──
+        .command({
+          command: 'show <identifier>',
+          aliases: ['get'],
+          describe: 'Show an API definition or operation by service_id, name, or sys_id — includes child resources',
+          handler: wrap(async (argv, app) => {
+            const id = argv.identifier;
+            const isSysId = isHexString(id) && id.length === 32;
+
+            // 1. Try to find a sys_ws_operation by name or sys_id
+            const opParams = new URLSearchParams();
+            opParams.set('sysparm_query', `${isSysId ? 'sys_id' : 'name'}=${id}`);
+            opParams.set('sysparm_limit', '1');
+            opParams.set('sysparm_display_value', 'all');
+            let records = await app.sdk.list('sys_ws_operation', opParams);
+
+            if (records.length > 0) {
+              // Found an operation — show it directly
+              records[0]._context = {
+                instance_url: app.getEffectiveInstance(),
+                table: 'sys_ws_operation',
+              };
+              return app.ok(records[0], {
+                summary: `Operation: ${getStringField(records[0], 'name') || id}`,
+                breadcrumbs: [
+                  { action: 'list', cmd: 'jsn dev scrapi list', description: 'Back to all operations' },
+                ],
+              });
+            }
+
+            // 2. Try to find a sys_ws_definition by service_id, name, or sys_id
+            const defQuery = isSysId
+              ? `sys_id=${id}`
+              : `service_id=${id}^ORname=${id}`;
+            const defParams = new URLSearchParams();
+            defParams.set('sysparm_query', defQuery);
+            defParams.set('sysparm_limit', '1');
+            defParams.set('sysparm_display_value', 'all');
+            const defRecords = await app.sdk.list('sys_ws_definition', defParams);
+
+            if (defRecords.length === 0) {
+              throw new Error(`No API or operation found matching: ${id}`);
+            }
+
+            const definition = defRecords[0];
+            const defName = getStringField(definition, 'name');
+            const defSysId = definition.sys_id?.value || definition.sys_id;
+
+            // 3. Fetch child operations for this definition
+            const childParams = new URLSearchParams();
+            childParams.set('sysparm_query', `web_service_definition=${defSysId}`);
+            childParams.set('sysparm_limit', '50');
+            childParams.set('sysparm_display_value', 'all');
+            childParams.set('sysparm_fields', 'sys_id,name,http_method,relative_path,active');
+            const childOps = await app.sdk.list('sys_ws_operation', childParams);
+
+            // Build a formatted display
+            const instanceURL = app.getEffectiveInstance();
+            const defLink = `${instanceURL}/sys_ws_definition.do?sys_id=${defSysId}`;
+
+            let formatted = `\n${defName} (Scripted REST API)\n`;
+            formatted += `${'─'.repeat(defName.length + 22)}\n\n`;
+            formatted += `  service_id:     ${getStringField(definition, 'service_id')}\n`;
+            formatted += `  namespace:      ${getStringField(definition, 'namespace')}\n`;
+            formatted += `  scope:          ${getStringField(definition, 'sys_scope')}\n`;
+            formatted += `  base_uri:       ${getStringField(definition, 'base_uri')}\n`;
+            formatted += `  description:    ${(getStringField(definition, 'description') || '(none)').slice(0, 60)}\n`;
+            formatted += `\n  Link: ${defLink}\n`;
+
+            if (childOps.length > 0) {
+              formatted += `\n  ── Resources (${childOps.length}) ──\n\n`;
+              for (const op of childOps) {
+                const opName = getStringField(op, 'name');
+                const method = getStringField(op, 'http_method');
+                const relPath = getStringField(op, 'relative_path');
+                const active = getStringField(op, 'active');
+                formatted += `    ${(method + '  ').slice(0, 7)} ${relPath.padEnd(30)} ${opName}${active !== 'true' ? ' (inactive)' : ''}\n`;
+              }
+            } else {
+              formatted += `\n  (no resources — run jsn dev scrapi create --resource ... to add some)\n`;
+            }
+
+            app.ok({
+              _formatted: formatted,
+              definition: {
+                sys_id: defSysId,
+                name: defName,
+                service_id: getStringField(definition, 'service_id'),
+                namespace: getStringField(definition, 'namespace'),
+                base_uri: getStringField(definition, 'base_uri'),
+                scope: getStringField(definition, 'sys_scope'),
+                description: getStringField(definition, 'description'),
+                link: defLink,
+              },
+              resources: childOps.map(op => ({
+                name: getStringField(op, 'name'),
+                method: getStringField(op, 'http_method'),
+                relative_path: getStringField(op, 'relative_path'),
+                active: getStringField(op, 'active'),
+              })),
+              _context: { instance_url: instanceURL, table: 'sys_ws_definition' },
+            }, {
+              summary: `API: ${defName} — ${childOps.length} resource(s)`,
+              breadcrumbs: [
+                { action: 'create', cmd: 'jsn dev scrapi create --name "..." --service-id ... --namespace ... --resource ...', description: 'Create a new API' },
+                { action: 'list', cmd: 'jsn dev scrapi list', description: 'Back to all operations' },
+              ],
+            });
+          }),
+        })
+        // ── create (one-shot API + operations) ──
+        .command({
+          command: 'create',
+          describe: 'Create a new Scripted REST API with operations in one command',
+          builder: (y) => y
+            .option('name', { type: 'string', demandOption: true, describe: 'API name (e.g. "SL Managed Services")' })
+            .option('service-id', { type: 'string', demandOption: true, describe: 'Service ID (e.g. "managed_services")' })
+            .option('namespace', { type: 'string', demandOption: true, describe: 'API namespace (e.g. "slapi")' })
+            .option('resource', {
+              type: 'string',
+              array: true,
+              demandOption: true,
+              describe: 'Resource definition: name=METHOD:/path:./script.js (can be repeated)',
+            })
+            .option('description', { type: 'string', describe: 'API description' })
+            .option('scope', { type: 'string', describe: 'Scope name or sys_id (default: current scope)' }),
+          handler: wrap(async (argv, app) => {
+            if (!app.sdk) throw new Error('Not connected to a ServiceNow instance');
+
+            // 1. Parse and validate all resources first
+            const resources = [];
+            for (const raw of argv.resource) {
+              const parsed = parseResourceArg(raw);
+              if (!parsed) {
+                throw errUsageHint(
+                  `Invalid --resource format: ${raw}`,
+                  'Expected: name=METHOD:/path:./script.js  e.g. create=POST:/create:./create.js'
+                );
+              }
+              const script = readScriptFile(parsed.scriptFile);
+              resources.push({ ...parsed, script });
+            }
+
+            const apiName = argv.name;
+            const serviceId = argv['service-id'];
+            const namespace = argv.namespace;
+            const description = argv.description || '';
+
+            // 2. Resolve scope if provided
+            let scopeSysId = null;
+            if (argv.scope) {
+              scopeSysId = await app.sdk.resolveScope(argv.scope);
+              if (!scopeSysId) {
+                throw new Error(`Scope not found: ${argv.scope}`);
+              }
+            }
+
+            // 3. Create the API definition (sys_ws_definition)
+            const definitionData = {
+              name: apiName,
+              service_id: serviceId,
+              namespace,
+              description,
+            };
+            if (scopeSysId) {
+              definitionData.sys_scope = scopeSysId;
+            }
+
+            const definition = await app.sdk.create('sys_ws_definition', definitionData);
+            const defSysId = definition?.sys_id?.value || definition?.sys_id;
+            if (!defSysId) {
+              throw new Error('API definition creation returned no sys_id — check for validation errors');
+            }
+
+            // 4. Create each operation (sys_ws_operation)
+            const operations = [];
+            for (const res of resources) {
+              const opData = {
+                name: res.name,
+                http_method: res.method,
+                relative_path: res.relativePath,
+                operation_script: res.script,
+                web_service_definition: defSysId,
+              };
+              // Set the scope so the operation inherits the API's scope
+              if (scopeSysId) {
+                opData.sys_scope = scopeSysId;
+              }
+              const operation = await app.sdk.create('sys_ws_operation', opData);
+              operations.push(operation?.result || operation);
+            }
+
+            // 5. Report
+            const instanceURL = app.getEffectiveInstance();
+            const apiURL = `${instanceURL}/sys_ws_definition.do?sys_id=${defSysId}`;
+
+            app.ok({
+              api_definition: {
+                sys_id: defSysId,
+                name: apiName,
+                service_id: serviceId,
+                namespace,
+                link: apiURL,
+              },
+              operations: operations.map((op, i) => ({
+                name: resources[i].name,
+                method: resources[i].method,
+                relative_path: resources[i].relativePath,
+              })),
+            }, {
+              summary: `Created API "${apiName}" with ${operations.length} operation(s)`,
+              notice: `View API: ${apiURL}`,
+              breadcrumbs: [
+                { action: 'show', cmd: `jsn dev scrapi list --query "web_service_definition=${defSysId}"`, description: 'List operations for this API' },
+                { action: 'add', cmd: `jsn dev scrapi add-resource --api "${serviceId}" --name <name>=METHOD:/path:./script.js`, description: 'Add another resource' },
+              ],
+            });
+          }),
+        });
+    },
+    // Default handler when no subcommand matches
+    handler: () => {
+      console.log('Manage Scripted REST APIs.');
+      console.log('');
+      console.log('Available subcommands:');
+      console.log('  list        List API operations');
+      console.log('  show        Show an operation by name or sys_id');
+      console.log('  create      Create a new API with operations (one-shot)');
+      console.log('');
+      console.log('Examples:');
+      console.log('  jsn dev scrapi list');
+      console.log('  jsn dev scrapi show my_operation');
+      console.log('  jsn dev scrapi create \\');
+      console.log('    --name "My API" --service-id my-api --namespace myapp \\');
+      console.log('    --resource "create=POST:/create:./create.js" \\');
+      console.log('    --resource "list=GET:/list:./list.js"');
+    },
+  };
+}

package/src/commands/dev.js

@@ -4,7 +4,7 @@ import {
   actionsCmd, includesCmd, rulesCmd,
   clientScriptsCmd, uiActionsCmd, uiPoliciesCmd,
   tablesCmd, columnsCmd, importCmd,
-  spPagesCmd, spWidgetsCmd, uiPagesCmd, appMenuCmd, scRAPICmd,
+  spPagesCmd, spWidgetsCmd, uiPagesCmd, appMenuCmd,
   aclsCmd, rolesCmd, propertiesCmd,
   relationshipsCmd, appmodulesCmd, listcontrolsCmd, viewsCmd,
   privilegesCmd, securitytypesCmd, uxscriptsCmd, aliasesCmd,
@@ -18,6 +18,7 @@ import { scopesCmd } from './dev/scopes.js';
 import { evalCmd } from './dev/eval.js';
 import { restCmd } from './dev/rest.js';
 import { logsCmd } from './dev/logs.js';
+import { scrapiCmd } from './dev/scrapi.js';
 
 export function devCmd(wrap) {
   return {
@@ -41,7 +42,7 @@ export function devCmd(wrap) {
         .command(spWidgetsCmd(wrap))
         .command(uiPagesCmd(wrap))
         .command(appMenuCmd(wrap))
-        .command(scRAPICmd(wrap))
+        .command(scrapiCmd(wrap))
         .command(aclsCmd(wrap))
         .command(rolesCmd(wrap))
         .command(updateSetsCmd(wrap))

package/src/commands/records.js

@@ -1,4 +1,4 @@
-import { formatRecordForDisplay, buildQuerySuffix, parseDataArg, getStringField, interactiveList, resolveFieldsParam } from '../helpers.js';
+import { formatRecordForDisplay, buildQuerySuffix, parseDataArg, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields } from '../helpers.js';
 
 const tableDefaultColumns = {
   incident: ['number', 'short_description', 'priority', 'state', 'assigned_to'],
@@ -133,9 +133,14 @@ export function recordsCmd(wrap) {
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
             .option('data', { type: 'string', describe: 'JSON fields (e.g. \'{"state":"2"}\')' })
-            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' }),
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin (pipe-friendly)' }),
           handler: wrap(async (argv, app) => {
             const recordData = parseDataArg(argv);
+            const warnings = checkDerivedFields(argv.table, recordData);
+            for (const w of warnings) {
+              process.stderr.write(`⚠ ${w.hint}\n`);
+            }
             const record = await app.sdk.create(argv.table, recordData);
             app.ok(record, { summary: `Created record in ${argv.table}` });
           }),
@@ -147,9 +152,14 @@ export function recordsCmd(wrap) {
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
             .option('sys-id', { type: 'string', demandOption: true, describe: 'Record sys_id' })
             .option('data', { type: 'string', describe: 'JSON fields (e.g. \'{"state":"2"}\')' })
-            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' }),
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin (pipe-friendly)' }),
           handler: wrap(async (argv, app) => {
             const recordData = parseDataArg(argv);
+            const warnings = checkDerivedFields(argv.table, recordData);
+            for (const w of warnings) {
+              process.stderr.write(`⚠ ${w.hint}\n`);
+            }
             const record = await app.sdk.update(argv.table, argv['sys-id'], recordData);
             app.ok(record, { summary: `Updated record in ${argv.table}` });
           }),

package/src/commands/skill.js

@@ -1,15 +1,37 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
+const SKILL_NAME = 'servicenow';
 const SKILL_REPO_PATH = path.join(
   path.dirname(fileURLToPath(import.meta.url)),
-  '..', '..', 'skills', 'servicenow', 'SKILL.md'
+  '..', '..', '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';
 
+// Known agent skill directories (personal/user-level)
+// Keyed by agent name for the --target flag
+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),
+};
+
+const TARGET_NAMES = {
+  hermes: 'Hermes Agent',
+  copilot: 'GitHub Copilot',
+  claude: 'Claude Code',
+  cursor: 'Cursor',
+  agents: 'Agents (open standard)',
+};
+
 function readBundledSkill() {
   try {
     return fs.readFileSync(SKILL_REPO_PATH, 'utf-8');
@@ -18,9 +40,23 @@ function readBundledSkill() {
   }
 }
 
+function readInstalledSkill() {
+  try {
+    return fs.readFileSync(HERMES_SKILL_PATH, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
 export async function checkSkill() {
-  const bundled = readBundledSkill();
-  if (!bundled) return { current: false, error: 'Skill file not found in package' };
+  // 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' };
+
+  const installedVersion = extractVersion(installed);
+  if (!installedVersion) return { current: false, error: 'No version field in installed skill' };
+
   try {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), 10000);
@@ -28,18 +64,27 @@ export async function checkSkill() {
     clearTimeout(timer);
     if (!res.ok) return { current: false, error: `GitHub returned ${res.status}` };
     const upstream = await res.text();
-    const current = bundled === upstream;
+    const upstreamVersion = extractVersion(upstream);
+    if (!upstreamVersion) return { current: false, error: 'No version field in upstream skill' };
+
+    const current = installedVersion === upstreamVersion;
     return {
       current,
-      bundled_lines: bundled.split('\n').length,
-      upstream_lines: upstream.split('\n').length,
-      error: current ? null : 'Bundled skill is outdated — run "jsn skill install" to update',
+      installed_version: installedVersion,
+      upstream_version: upstreamVersion,
+      error: current ? null : `Skill version ${installedVersion} vs GitHub ${upstreamVersion} — run "jsn skill install" to update`,
     };
   } catch {
     return { current: false, error: 'Could not check — GitHub unreachable' };
   }
 }
 
+function extractVersion(content) {
+  // Matches version in YAML frontmatter (top-level or nested under metadata:)
+  const m = content.match(/^\s*version:\s*["']?(.+?)["']?\s*$/m);
+  return m ? m[1] : null;
+}
+
 export function skillCmd(wrap) {
   return {
     command: 'skill',
@@ -70,9 +115,9 @@ export function skillCmd(wrap) {
             if (result.error && !result.current) {
               app.ok(result, { summary: result.error });
             } else if (result.current) {
-              app.ok(result, { summary: `✓ Skill is current (${result.bundled_lines} lines)` });
+              app.ok(result, { summary: `✓ Skill is current (v${result.installed_version})` });
             } else {
-              app.ok(result, { summary: `⚠ Skill is outdated (bundled ${result.bundled_lines} lines vs upstream ${result.upstream_lines} lines) — run "jsn skill install" to update` });
+              app.ok(result, { summary: `⚠ Skill outdated: installed v${result.installed_version} vs GitHub v${result.upstream_version} — run "jsn skill install" to update` });
             }
           }),
         })
@@ -90,18 +135,23 @@ export function skillCmd(wrap) {
           command: 'path',
           describe: 'Show skill file locations and install targets',
           handler: wrap(async (_argv, app) => {
-            const hermesDir = path.join(os.homedir(), '.hermes', 'skills', 'servicenow');
-            const hermesPath = path.join(hermesDir, 'SKILL.md');
+            const allPaths = {};
+            for (const [key, dir] of Object.entries(AGENT_SKILL_DIRS)) {
+              const file = key === 'cursor' ? path.join(dir, `${SKILL_NAME}.mdc`) : path.join(dir, 'SKILL.md');
+              allPaths[TARGET_NAMES[key]] = file;
+            }
+
             app.ok({
               bundled: SKILL_REPO_PATH,
-              hermes: hermesPath,
+              targets: allPaths,
               raw_url: SKILL_RAW_URL,
             }, {
-              summary: 'Skill file locations',
+              summary: 'Skill file locations and install targets',
               breadcrumbs: [
-                { action: 'view', cmd: 'jsn skill show', description: 'Show bundled skill content' },
-                { action: 'fetch', cmd: 'jsn skill fetch', description: 'Download latest from GitHub' },
-                { action: 'install', cmd: 'jsn skill install', description: 'Download + save to Hermes' },
+                { action: 'install', cmd: 'jsn skill install', description: 'Install to Hermes (default)' },
+                { 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' },
               ],
             });
           }),
@@ -112,30 +162,71 @@ export function skillCmd(wrap) {
           builder: (y) => y
             .positional('dir', {
               type: 'string',
-              describe: 'Target directory (default: ~/.hermes/skills/servicenow/)',
+              describe: 'Target directory (overrides --target; installs only to this dir)',
+            })
+            .option('target', {
+              type: 'string',
+              describe: 'Target agent(s): hermes, copilot, claude, cursor, agents, or "all" (comma-separated)',
+              default: 'hermes',
             }),
           handler: wrap(async (argv, app) => {
-            const targetDir = argv.dir || path.join(os.homedir(), '.hermes', 'skills', 'servicenow');
-            const targetPath = path.join(targetDir, 'SKILL.md');
-
-            fs.mkdirSync(targetDir, { recursive: true });
-
             const res = await fetch(SKILL_RAW_URL);
             if (!res.ok) throw new Error(`Failed to fetch skill: ${res.status} ${res.statusText}`);
             const content = await res.text();
 
-            fs.writeFileSync(targetPath, content, 'utf-8');
+            // Resolve target directories
+            let targets = [];
 
-            app.ok({
-              installed: targetPath,
-              from: SKILL_RAW_URL,
-            }, {
-              summary: `Skill installed to ${targetPath}`,
+            if (argv.dir) {
+              // Explicit --dir overrides targets — single install
+              const p = path.resolve(argv.dir);
+              fs.mkdirSync(p, { recursive: true });
+              const targetPath = path.join(p, 'SKILL.md');
+              fs.writeFileSync(targetPath, content, 'utf-8');
+              targets.push({ name: path.basename(argv.dir), path: targetPath });
+            } else {
+              const rawTargets = argv.target.split(',').map(t => t.trim().toLowerCase());
+              const all = rawTargets.includes('all');
+
+              for (const [key, dir] of Object.entries(AGENT_SKILL_DIRS)) {
+                if (all || rawTargets.includes(key)) {
+                  // For cursor, the skill goes in a .mdc file, not a subfolder
+                  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 });
+                  }
+                }
+              }
+            }
+
+            if (targets.length === 0) {
+              throw new Error(`No targets matched. Valid targets: ${Object.keys(AGENT_SKILL_DIRS).join(', ')}, or "all"`);
+            }
+
+            const installed = targets.reduce((acc, t) => { acc[t.name] = t.path; return acc; }, {});
+            const summary = targets.length === 1
+              ? `Skill installed to ${targets[0].path}`
+              : `Skill installed to ${targets.length} target(s)`;
+
+            const okOpts = {
+              summary,
               breadcrumbs: [
-                { action: 'verify', cmd: `head -30 ${targetPath}`, description: 'Verify the installed skill' },
-                { action: 'reinstall', cmd: 'jsn skill install', description: 'Re-download and reinstall' },
+                { action: 'reinstall', cmd: 'jsn skill install', description: 'Re-download and reinstall to default target' },
               ],
-            });
+            };
+
+            if (targets.length > 1) {
+              okOpts.notice = 'Installed to multiple agents. Restart or reload your agent to pick up the skill.';
+            }
+
+            app.ok({ installed, from: SKILL_RAW_URL }, okOpts);
           }),
         });
     },

package/src/errors.js

@@ -79,7 +79,34 @@ export function errAPI(status, msg) {
   if (status >= 500) {
     hint = 'The ServiceNow instance may be experiencing issues. Try again later.';
   }
-  return new AppError(CodeAPI, `API error (status ${status}): ${msg}`, hint, status);
+
+  // Try to extract structured error detail from JSON API error bodies
+  let displayMsg = msg;
+  if (typeof msg === 'string' && (msg.startsWith('{') || msg.startsWith('['))) {
+    try {
+      const parsed = JSON.parse(msg);
+      const errObj = parsed.error || parsed;
+      const detail = errObj.detail || errObj.message || '';
+      const message = errObj.message || '';
+
+      if (detail && message) {
+        displayMsg = `${message}: ${detail}`;
+      } else if (detail) {
+        displayMsg = detail;
+      } else if (message) {
+        displayMsg = message;
+      }
+
+      // Detect business rule abortion and add a hint
+      if (detail && detail.includes('Business Rule')) {
+        hint = 'A Business Rule rejected this operation. Check for overlapping routes, validation rules, or ACLs on this table.';
+      }
+    } catch {
+      // Not valid JSON, use original message
+    }
+  }
+
+  return new AppError(CodeAPI, `API error (status ${status}): ${displayMsg}`, hint, status);
 }
 
 export function errAmbiguous(resource, matches) {

package/src/helpers.js

@@ -135,25 +135,80 @@ function vowelArticle(word) {
 }
 
 /**
- * Parse --data or --data-file into a JSON object.
- * If --data-file is given, reads the file. Otherwise parses --data directly.
- * Throws if neither is provided or JSON is invalid.
+ * Known derived (read-only) ServiceNow fields that should not be set directly.
+ * Maps table name → array of field names that are computed by the platform.
+ * When a create/update payload contains these, a warning is emitted.
+ */
+export const DERIVED_FIELDS = {
+  sys_ws_operation: ['operation_uri'],
+  sys_ws_definition: ['base_uri'],
+  incident: ['sys_created_on', 'sys_updated_on', 'sys_created_by', 'sys_updated_by', 'sys_mod_count'],
+  change_request: ['sys_created_on', 'sys_updated_on', 'sys_created_by', 'sys_updated_by', 'sys_mod_count'],
+  // Generic — all sys_ fields are system-managed
+};
+
+/**
+ * Check a data payload for fields that appear to be derived/read-only.
+ * Returns an array of warning objects ({field, hint}) for any matches.
+ * @param {string} table - Table name (e.g. 'sys_ws_operation')
+ * @param {object} data - The JSON payload being sent
+ * @returns {Array<{field: string, hint: string}>}
+ */
+export function checkDerivedFields(table, data) {
+  if (!data || typeof data !== 'object') return [];
+  const warnings = [];
+
+  // Check explicitly known derived fields for this table
+  const knownFields = DERIVED_FIELDS[table] || [];
+  for (const field of knownFields) {
+    if (field in data && data[field] != null) {
+      warnings.push({
+        field,
+        hint: `${field} is a derived/read-only field. Setting it directly will be ignored.`,
+      });
+    }
+  }
+
+  // Warn about any sys_* fields that look like system-managed metadata
+  // (but be careful — not all sys_ fields are read-only)
+  if (data.sys_created_on) {
+    warnings.push({
+      field: 'sys_created_on',
+      hint: 'sys_created_on is a system-managed field. Setting it directly will be ignored.',
+    });
+  }
+  if (data.sys_updated_on) {
+    warnings.push({
+      field: 'sys_updated_on',
+      hint: 'sys_updated_on is a system-managed field. Setting it directly will be ignored.',
+    });
+  }
+
+  return warnings;
+}
+
+/**
+ * Parse --data, --data-file, or --data-stdin into a JSON object.
+ * Priority: --data-file > --data-stdin > --data
+ * Throws if none is provided or JSON is invalid.
  */
 export function parseDataArg(argv) {
   let raw;
   if (argv['data-file']) {
     raw = fs.readFileSync(argv['data-file'], 'utf-8');
-    // Strip UTF-8 BOM (\ufeff) which some editors (Windows/PowerShell) add
+    // Strip UTF-8 BOM (\\ufeff) which some editors (Windows/PowerShell) add
     if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1);
+  } else if (argv['data-stdin']) {
+    raw = fs.readFileSync(process.stdin.fd, 'utf-8');
   } else if (argv.data) {
     raw = argv.data;
   } else {
-    throw new Error('--data or --data-file is required');
+    throw new Error('--data, --data-file, or --data-stdin is required');
   }
   try {
     return JSON.parse(raw);
   } catch (e) {
-    throw new Error(`Invalid JSON: ${e.message}\n\nHint: On Windows PowerShell, use --data-file instead of --data to avoid quote mangling.\nRaw value: ${raw.substring(0, 200)}`, { cause: e });
+    throw new Error(`Invalid JSON: ${e.message}\n\nHint: Use --data-file for multiline payloads to avoid shell escaping issues.\nRaw value: ${raw.substring(0, 200)}`, { cause: e });
   }
 }
 

package/src/sdk.js

@@ -188,6 +188,25 @@ export class SDKClient {
     };
   }
 
+  /**
+   * Resolve a scope name or sys_id to a sys_id.
+   * @param {string} scope - Scope name (e.g. "sn_notif_dashboard") or sys_id
+   * @returns {Promise<string|null>} The scope sys_id, or null if not found
+   */
+  async resolveScope(scope) {
+    if (!scope) return null;
+    // If it looks like a sys_id (32 hex chars), try it directly
+    if (/^[0-9a-fA-F]{32}$/.test(scope)) return scope;
+
+    const params = new URLSearchParams();
+    params.set('sysparm_query', `scope=${scope}`);
+    params.set('sysparm_limit', '1');
+    params.set('sysparm_fields', 'sys_id,name');
+    const records = await this.list('sys_scope', params);
+    if (records.length === 0) return null;
+    return records[0].sys_id?.value || records[0].sys_id;
+  }
+
   async inspectFlow(identifier) {
     const isSysID = identifier.length === 32 && /^[0-9a-fA-F]+$/.test(identifier);
 
@@ -372,7 +391,7 @@ export class SDKClient {
    * @param {string} script - JavaScript code to execute
    * @returns {Promise<string>} The script's output text
    */
-  async executeScript(script) {
+  async executeScript(script, scope) {
     // Step 1: Warm up the session by hitting any REST API — this makes
     // ServiceNow issue session cookies for subsequent UI page requests.
     // We capture cookies to forward them (Node.js fetch() has no built-in cookie jar).
@@ -387,7 +406,7 @@ export class SDKClient {
     formBody.set('script', script);
     formBody.set('sysparm_ck', csrfToken);
     formBody.set('runscript', 'Run script');
-    formBody.set('sys_scope', 'global');
+    formBody.set('sys_scope', scope || 'global');
     formBody.set('record_for_rollback', 'on');
     formBody.set('quota_managed_transaction', 'on');