@jacebenson/jsn 4.3.13-dev.72.1 → 4.3.13-dev.73.1

package/package.json

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

package/skills/servicenow/SKILL.md

@@ -14,7 +14,7 @@ compatibility: |
   Works with Claude Code, OpenCode, Cursor, and agentskills-compatible tools.
 metadata:
   author: jacebenson
-  version: "4.3.6"
+  version: "4.3.9"
   repository: https://github.com/jacebenson/jsn
 ---
 
@@ -43,10 +43,9 @@ All `list` subcommands use a paginated interactive picker in TTY mode:
 1. **Output modes** — `--json` when parsing data; text when presenting to humans
 2. **Use sys_id for updates** — All update/delete operations require sys_id
 3. **Check auth first** — Run `jsn auth status` before operations
-4. **NEVER logout** — Only run `jsn auth logout` if the user explicitly asks
-5. **Use `--profile <name>`** to target a specific instance, or `jsn auth switch <name>` to change the default
-6. **Before using `eval` or `rest`** — Ask: *"Is there a more specific jsn command?"* Prefer specific over generic over escape hatch over eval.
-7. **CONFIRM before destructive operations** — Show what will be created/updated/deleted and ask for approval.
+4. **Verify the intended instance** — Use `--profile <name>` for explicit targeting; never assume the default is right. `jsn auth switch <name>` changes the default.
+5. **Eval safety** — Prefer purpose-built or `records` commands. Never use `eval` to bypass a blocked business rule, ACL, or other ServiceNow protection. If eval is genuinely needed, explain why and obtain explicit user approval.
+6. **CONFIRM before destructive operations** — Show what will be created/updated/deleted and ask for approval.
 
 ## Command Hierarchy
 
@@ -113,6 +112,12 @@ excludes that history row. Use raw values, not display labels or other skip reas
 
 ### Complete an update set
 
+Before development changes, identify the intended application scope and update
+set. Keep related changes together, use the appropriate update-set or application
+deployment mechanism, and report where changes were captured. Not all changes
+are update-set tracked. Only complete a set when the human explicitly asks,
+including sets you created; completing the current set returns selection to Default.
+
 ```bash
 jsn updatesets complete "My Feature" --notes "Fixed validation" --force --json
 ```
@@ -127,18 +132,10 @@ child sets when the parent completes; their descriptions are not replaced.
 Both selected-set Description and state are read back before success. On
 verification failure, inspect the set before retrying.
 
-### Table and raw REST examples
-
-```bash
-# Query a table with the normal records command
-jsn records list --table incident --query "active=true" --limit 5 --json
+### Table and raw REST discovery
 
-# Get a single record
-jsn records get --table incident --sys-id abc123... --json
-
-# Raw endpoint access when no specific command fits
-jsn rest "/api/now/table/incident?sysparm_limit=3" --json
-```
+Use `jsn records list --help`, `jsn records get --help`, and `jsn rest --help`
+for syntax and examples. REST is blocked on read-only connections, including GET.
 
 ### `jsn docs` — offline documentation search
 

package/src/auth.js

@@ -612,7 +612,9 @@ export class AuthManager {
     if (!instance) {
       throw errAuth('No instance specified');
     }
+    const existed = !!this.credentialStore.load(instance, username);
     this.credentialStore.delete(instance, username);
+    return existed && !this.credentialStore.load(instance, username);
   }
 
   /**

package/src/commands/auth.js

@@ -1,5 +1,5 @@
 import { getEffectiveInstance, normalizeInstanceURL, saveConfig, setActiveProfile } from '../config.js';
-import { errUsage, errUsageHint } from '../errors.js';
+import { errUsage, errUsageHint, errConfirmationRequired } from '../errors.js';
 import { canUsePicker, formatCommandList, quoteShellArg } from '../helpers.js';
 import { declareCapabilities } from '../capabilities.js';
 import process from 'node:process';
@@ -808,10 +808,33 @@ Examples:
   }
   const target = resolveTargetProfile(argv, app.config, instanceURL);
   const username = target.profile?.username ?? null;
-  if (username || canLogoutBareProfile(app, instanceURL, target.profile, !!argv.profile)) {
-    app.auth.logout(instanceURL, username);
+  if (!username && !canLogoutBareProfile(app, instanceURL, target.profile, !!target.name)) {
+    throw errUsageHint('Cannot identify which stored credentials to clear.', 'Choose an unambiguous identity with --profile <name>.');
   }
-  app.ok({ logged_out: true, instance: instanceURL }, { summary: `✓ Logged out from ${instanceURL}` });
+  const selector = target.name ? `--profile ${quoteShellArg(target.name)}` : quoteShellArg(instanceURL);
+  const rerun = `jsn auth logout ${selector}`;
+  const warning = `Clear locally stored credentials for ${target.name ? `profile "${target.name}" at ` : ''}${instanceURL}${username ? ` (user ${username})` : ''}? You will need to authenticate again. The profile is retained; environment credentials and ServiceNow/Chrome sessions are unaffected.`;
+  if (!argv.force) {
+    if (!canUsePicker(app, argv)) throw errConfirmationRequired(warning, rerun);
+    const { confirm } = await import('../prompts.js');
+    if (!await confirm({ message: warning, default: false })) {
+      app.ok({ logged_out: false, credentials_cleared: false, profile: target.name, instance: instanceURL },
+        { summary: 'Logout cancelled; stored credentials were retained.' });
+      return;
+    }
+  }
+  const cleared = app.auth.logout(instanceURL, username) === true;
+  const nextActions = cleared ? [
+    { action: 'Authenticate again', cmd: `jsn auth login ${selector}`, description: 'Restore locally stored authentication' },
+    ...(target.name ? [{ action: 'Remove retained profile', cmd: `jsn auth remove ${quoteShellArg(target.name)}`, description: 'Remove this connection if no longer needed' }] : []),
+  ] : [];
+  app.ok({ logged_out: cleared, credentials_cleared: cleared, profile: target.name, instance: instanceURL,
+    profile_retained: !!target.name, environment_credentials_affected: false, remote_session_terminated: false,
+    next_actions: nextActions }, {
+    summary: cleared ? `✓ Cleared local credentials for ${target.name || instanceURL}. Profile retained; environment credentials and ServiceNow/Chrome sessions are unaffected.`
+      : `No stored credentials were cleared for ${target.name || instanceURL}. Environment credentials and ServiceNow/Chrome sessions are unaffected.`,
+    breadcrumbs: nextActions,
+  });
 }
 
 export async function showAuthStatus(argv, app) {
@@ -1099,7 +1122,8 @@ export function authCmd(wrap) {
         })
         .command({
           command: 'logout [instance]',
-          describe: 'Clear stored credentials (keeps the instance entry — use "auth remove" to delete it)',
+          describe: 'Clear local credentials after approval; retains the profile. Unnecessary after ordinary operations; does not sign out of ServiceNow/Chrome or clear environment credentials.',
+          builder: sub => sub.option('force', { type: 'boolean', describe: 'Clear credentials only after explicit approval for this exact logout' }),
           handler: wrap(logoutProfile),
         })
         .command({

package/src/commands/records.js

@@ -83,7 +83,15 @@ export function recordsCmd(wrap) {
             .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' })
             .option('limit', { type: 'number', default: 20, describe: 'Max records' })
             .option('offset', { type: 'number', default: 0, describe: 'Offset' })
-            .option('count', { type: 'boolean', default: true, describe: 'Include the total-matching count (use --no-count to opt out)' }),
+            .option('count', { type: 'boolean', default: true, describe: 'Include the total-matching count (use --no-count to opt out)' })
+            .epilogue([
+              'In an interactive terminal with automatic output, browse a picker (10 visible items).',
+              'Use arrow keys to browse, type to search sys_id on the server, scroll to load more,',
+              'and press Enter to select or Esc to cancel. --sys-id skips the picker.',
+              'Use --json for noninteractive structured output; pipes and explicit formats also skip the picker.',
+              'Example: jsn records list --table incident --query "active=true" --limit 5 --json',
+              'Discover fields with: jsn columns --table incident',
+            ].join('\n')),
           handler: wrap(async (argv, app) => {
             const table = argv.table;
             const columns = argv.columns ? argv.columns.split(',') : getDefaultColumns(table);
@@ -187,7 +195,8 @@ 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('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' })
-            .option('attachments', { type: 'boolean', default: false, describe: 'Also list the record\'s attachments' }),
+            .option('attachments', { type: 'boolean', default: false, describe: 'Also list the record\'s attachments' })
+            .epilogue('Example: jsn records get --table incident --sys-id <sys_id> --json'),
           handler: wrap(async (argv, app) => {
             assertSafeExactMatch(argv['sys-id']);
             const params = new URLSearchParams();

package/src/commands/rest.js

@@ -10,6 +10,10 @@ export function restCmd(wrap) {
     describe: 'Make raw REST API calls',
     builder: (yargs) => {
       return yargs
+        .positional('endpoint', {
+          type: 'string',
+          describe: 'API path, optionally including query parameters; with --table, a record sys_id',
+        })
         .option('method', {
           alias: 'X',
           type: 'string',
@@ -34,7 +38,16 @@ export function restCmd(wrap) {
         .option('query', {
           type: 'string',
           describe: 'Query parameters string',
-        });
+        })
+        .epilogue([
+          'Prefer a specific jsn command or records for normal table operations.',
+          'Raw REST is blocked on read-only profiles for every method, including GET.',
+          'Examples:',
+          '  jsn rest "/api/now/table/incident?sysparm_limit=3" --json',
+          '  jsn rest --table incident --query "sysparm_limit=3" --json',
+          '  jsn rest /stats.do --raw',
+          'Use either query parameters in the endpoint or --query, rather than both.',
+        ].join('\n'));
     },
     handler: wrap(async (argv, app) => {
       const validMethods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];

package/src/commands/skill.js

@@ -119,9 +119,8 @@ function saveSkillConfig(updates) {
   fs.writeFileSync(globalConfigPath(), JSON.stringify(cfg, null, 2), { mode: 0o600 });
 }
 
-function recordSkillInstall(targetPath) {
-  const bundled = readBundledSkill();
-  const version = extractVersion(bundled) || 'unknown';
+function recordSkillInstall(targetPath, content) {
+  const version = extractVersion(content) || 'unknown';
   saveSkillConfig({
     skillLocation: targetPath,
     skillVersion: version,
@@ -260,7 +259,7 @@ export function skillCmd(wrap) {
         })
         .command({
           command: 'install [dir]',
-          describe: 'Download and save the latest skill file',
+          describe: 'Install the bundled skill matched to this CLI version',
           builder: (y) => y
             .positional('dir', {
               type: 'string',
@@ -271,9 +270,10 @@ export function skillCmd(wrap) {
               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);
-            if (!res.ok) throw new Error(`Failed to fetch skill: ${res.status} ${res.statusText}`);
-            const content = await res.text();
+            const content = readBundledSkill();
+            if (!content) {
+              throw new Error('Skill file not found in package (expected at skills/servicenow/SKILL.md). Reinstall jsn to restore it.');
+            }
 
             // Resolve target directories
             let targets = [];
@@ -389,7 +389,7 @@ export function skillCmd(wrap) {
             }
 
             // Record install location so checkSkill knows where to look
-            recordSkillInstall(targets[0].path);
+            recordSkillInstall(targets[0].path, content);
 
             const installed = targets.reduce((acc, t) => { acc[t.name] = t.path; return acc; }, {});
             const summary = targets.length === 1
@@ -399,7 +399,7 @@ export function skillCmd(wrap) {
             const okOpts = {
               summary,
               breadcrumbs: [
-                { action: 'reinstall', cmd: 'jsn skill install', description: 'Re-download and reinstall to default target' },
+                { action: 'reinstall', cmd: 'jsn skill install', description: 'Reinstall the bundled skill to default target' },
               ],
             };
 
@@ -407,7 +407,7 @@ export function skillCmd(wrap) {
               okOpts.notice = 'Installed to multiple agents. Restart or reload your agent to pick up the skill.';
             }
 
-            app.ok({ installed, from: SKILL_RAW_URL }, okOpts);
+            app.ok({ installed, from: SKILL_REPO_PATH }, okOpts);
           }),
         });
     },