@jacebenson/jsn 4.3.13-dev.75.1 → 4.3.13-dev.77.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.13-dev.75.1",
+  "version": "4.3.13-dev.77.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.11"
+  version: "4.3.12"
   repository: https://github.com/jacebenson/jsn
 ---
 
@@ -150,8 +150,5 @@ Check order (priority):
 
 ## Configuration
 
-```
-~/.config/servicenow/
-├── config.json               # Profiles and settings
-└── credentials/              # Auth tokens (fallback, one file per key)
-```
+Use `jsn setup` for interactive configuration. `jsn setup --help` lists the
+scriptable `jsn auth` equivalents and secure authentication input options.

package/src/cli-adapter.js

@@ -116,6 +116,7 @@ export class LocalCLI {
 
   scriptName(value) { this.script = value; return this; }
   usage(value) { this.root.usageText = value; return this; }
+  epilogue(value) { this.root.epilogueText = value; return this; }
   middleware(fn) { this.middlewares.push(...(Array.isArray(fn) ? fn : [fn])); return this; }
   option(name, config) { this.root.options.set(name, { ...config, name }); return this; }
   options(config) { for (const [name, value] of Object.entries(config)) this.option(name, value); return this; }
@@ -294,6 +295,13 @@ export class LocalCLI {
         aliases: [...node.aliases],
         description: node.definition.describe || '',
         subcommands: node.children.filter(visible).map((child) => child.name),
+        discovery: node.definition.discovery || null,
+        help: `jsn ${node.name} --help`,
+        actions: node.children.filter(visible).map((child) => ({
+          name: child.name,
+          description: child.definition.describe || '',
+          help: `jsn ${node.name} ${child.name} --help`,
+        })),
       };
     };
     return {

package/src/cli.js

@@ -7,7 +7,7 @@ import fs from 'node:fs';
 import { loadConfig, globalConfigDir } from './config.js';
 import { App } from './app.js';
 import { resolveSession, applySession } from './session.js';
-import { renderHelp } from './help.js';
+import { renderHelp, renderTips } from './help.js';
 import { isMutationCommand, refreshMutationCommands } from './mutations.js';
 import { skippedUpdatesCmd } from './commands/skipped-updates.js';
 import { noInstanceCommands, dailyCheckSkipCommands, contextHeaderSkipCommands } from './capabilities.js';
@@ -15,6 +15,7 @@ import { guardExit, exitWithError, AppError, CodeUsage } from './errors.js';
 import { formatCommandList } from './helpers.js';
 
 // Command modules
+import { discoverCmd } from './commands/discover.js';
 import { setupCmd } from './commands/setup.js';
 import { authCmd } from './commands/auth.js';
 import { recordsCmd } from './commands/records.js';
@@ -419,6 +420,7 @@ export function buildCLI() {
     .command(skillCmd(wrap))
     .command(docsCmd(wrap))
     .command(versionCmd(wrap))
+    .command(discoverCmd(wrap, () => cliInstance.commandRegistry()))
     .demandCommand(1, 'You must specify a command')
     // Completion plumbing under a hidden command name, so the explicit
     // 'completion' command below owns the UX. (#176)
@@ -499,6 +501,7 @@ export function buildCLI() {
         }, { summary });
       })(argv);
     })
+    .epilogue(renderTips())
     .help('help', 'Show help')
     .version(false)
     .strictCommands()

package/src/commands/_generic.js

@@ -280,6 +280,13 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
     command: `${name} [subcommand]`,
     aliases: aliases || [],
     describe: `Manage ${name} (e.g. "${name} list --query nameLIKEincident")`,
+    discovery: {
+      table,
+      defaultColumns,
+      benefits: ['Configured list columns', 'Lookup by name or sys_id',
+        ...(showFields ? ['Configured show fields'] : []),
+        ...(opts.onShow ? ['Additional table-specific show processing'] : [])],
+    },
     builder,
     handler: (_argv) => {
       // This handler only runs when no subcommand is matched (the default case).

package/src/commands/_ticket.js

@@ -14,6 +14,7 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
     command: `${displayName} [subcommand]`,
     aliases: [table, alias],
     describe: `Manage ${displayName} (e.g. "${displayName} list --query priority=1")`,
+    discovery: { table, defaultColumns, benefits: ['Configured list columns', 'Ticket-specific create/update flags'] },
     builder: (yargs) => {
       return yargs
         .command({

package/src/commands/auth.js

@@ -3,6 +3,7 @@ import { errUsage, errUsageHint, errConfirmationRequired } from '../errors.js';
 import { canUsePicker, formatCommandList, quoteShellArg } from '../helpers.js';
 import { declareCapabilities } from '../capabilities.js';
 import process from 'node:process';
+import { readFile } from 'node:fs/promises';
 import { refreshSession } from '../session.js';
 
 function syncSession(app) {
@@ -139,7 +140,7 @@ export function resolveTargetProfile(argv = {}, cfg = {}, instanceURL = '') {
  */
 export function shouldUseBasicAuth(argv = {}, cfg = {}, instanceURL = '', targetProfile = null) {
   if (argv.basic || argv.password) return true;
-  if (argv.oauth || argv.code || argv.printUrl || argv.browser || argv.gck || argv.headers) return false;
+  if (argv.oauth || argv.code || argv.printUrl || argv.browser || argv.gck || argv.headers || argv.headersFile !== undefined) return false;
   if (targetProfile) return targetProfile.auth_method === 'basic';
   return Object.values(cfg.profiles || {}).some(profile =>
     profile.instance_url === instanceURL && profile.auth_method === 'basic'
@@ -147,7 +148,7 @@ export function shouldUseBasicAuth(argv = {}, cfg = {}, instanceURL = '', target
 }
 
 export function shouldUseGckAuth(argv = {}, cfg = {}, instanceURL = '', targetProfile = null) {
-  if (argv.gck || argv.headers || argv.browser) return true;
+  if (argv.gck || argv.headers || argv.browser || argv.headersFile !== undefined) return true;
   if (argv.basic || argv.password || argv.oauth || argv.code || argv.printUrl) return false;
   if (targetProfile) return targetProfile.auth_method === 'gck';
   return Object.values(cfg.profiles || {}).some(profile =>
@@ -157,10 +158,11 @@ export function shouldUseGckAuth(argv = {}, cfg = {}, instanceURL = '', targetPr
 
 export function validateLoginSelectors(argv = {}, targetProfile = null) {
   const basic = argv.basic === true || argv.password === true;
-  const gck = argv.gck === true || argv.headers !== undefined || argv.browser === true;
+  const gck = argv.gck === true || argv.headers !== undefined || argv.headersFile !== undefined || argv.browser === true;
   const oauth = argv.oauth === true || argv.code !== undefined || argv.printUrl === true || argv.waitFile !== undefined;
   if (oauth && (basic || gck)) throw errUsage('Choose only one authentication method: --oauth, --basic, or --browser/--gck.');
   if (argv.waitFile && !argv.printUrl) throw errUsage('--wait-file requires --print-url.');
+  if (argv.headers !== undefined && argv.headersFile !== undefined) throw errUsage('Choose --headers-file or --headers, not both.');
   if (argv.code !== undefined && argv.printUrl) throw errUsage('--code cannot be combined with --print-url.');
   if (argv.browserUrl !== undefined && !argv.browser) {
     throw errUsage('--browser-url requires --browser.');
@@ -168,8 +170,8 @@ export function validateLoginSelectors(argv = {}, targetProfile = null) {
   if (argv.browserName !== undefined && (!argv.browser || argv.browserUrl !== undefined)) {
     throw errUsage('--browser-name requires --browser and cannot be combined with --browser-url.');
   }
-  if (argv.browser && (argv.headers !== undefined || argv.code !== undefined || argv.printUrl || argv.waitFile)) {
-    throw errUsage('--browser cannot be combined with --headers, --code, --print-url, or --wait-file.');
+  if (argv.browser && (argv.headers !== undefined || argv.headersFile !== undefined || argv.code !== undefined || argv.printUrl || argv.waitFile)) {
+    throw errUsage('--browser cannot be combined with --headers-file, --headers, --code, --print-url, or --wait-file.');
   }
   if (basic && gck) {
     throw errUsage('Basic and browser-session selectors are mutually exclusive; choose --basic/--password or --gck/--headers.');
@@ -278,6 +280,22 @@ export async function readBrowserSessionInput() {
   });
 }
 
+/** Read captured session data without putting it in argv or printing a prompt. */
+async function readBrowserSessionFile(file) {
+  let content;
+  if (file === '-') {
+    if (process.stdin.isTTY) throw errUsageHint('--headers-file - requires piped or redirected input.', 'Pipe captured headers into this command, or pass a file path.');
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    content = Buffer.concat(chunks).toString('utf8');
+  } else {
+    try { content = await readFile(file, 'utf8'); }
+    catch { throw errUsageHint('Could not read browser-session input file.', 'Check the --headers-file path and file permissions.'); }
+  }
+  if (!content.trim()) throw errUsage('Browser-session input is empty. Supply captured headers or a cURL request.');
+  return content;
+}
+
 /** Collect human answers, then call the same login operation as auth login. */
 export async function loginWizard(app, argv = {}) {
   const { input, select, confirm, password } = await import('../prompts.js');
@@ -593,8 +611,9 @@ Find your instance URL in your browser's address bar when logged into ServiceNow
   const useBasic = shouldUseBasicAuth(argv, methodConfig, instanceURL, targetProfile);
   const useGck = shouldUseGckAuth(argv, methodConfig, instanceURL, targetProfile);
   const interactive = canUsePicker(app, argv);
-  if (useGck && !argv.browser && !argv.headers && !interactive) {
-    throw errUsage('Browser sign-in needs a human. Pass --browser to explicitly open a login window, or supply a captured session.');
+  const capturedHeaders = argv.headers !== undefined || argv.headersFile !== undefined;
+  if (useGck && !argv.browser && !capturedHeaders && !interactive) {
+    throw errUsage('Browser sign-in needs a human. Pass --browser to explicitly open a login window, or supply a captured session with --headers-file <path|->.');
   }
   if (!useGck && !useBasic && !argv.printUrl && !argv.code && !interactive) {
     throw errUsage('OAuth login requires --print-url followed by --code <code> when noninteractive.');
@@ -611,9 +630,9 @@ Find your instance URL in your browser's address bar when logged into ServiceNow
   // --basic (with --password as a compatibility alias): authenticate
   // with basic auth from env vars and persist it for this profile.
   if (useGck) {
-    const credentials = (argv.browser || (!argv.gck && !argv.headers))
+    const credentials = (argv.browser || (!argv.gck && !capturedHeaders))
       ? await loginUsingBrowser(app, instanceURL, argv, targetUsername || null)
-      : await app.auth.loginWithGck(instanceURL, argv.headers || await readBrowserSessionInput(), targetUsername || null);
+      : await app.auth.loginWithGck(instanceURL, argv.headersFile !== undefined ? await readBrowserSessionFile(argv.headersFile) : argv.headers || await readBrowserSessionInput(), targetUsername || null);
     targetUsername = credentials?.username || targetUsername;
   } else if (useBasic) {
     let credentials;
@@ -994,10 +1013,16 @@ Examples:
 
   const target = resolveTargetProfile(argv, app.config, instanceURL);
   const targetProfile = target.profile;
+  const browser = argv.browser || (targetProfile?.auth_method === 'gck'
+    && argv.headers === undefined && argv.headersFile === undefined && canUsePicker(app, argv));
+  validateLoginSelectors({ ...argv, browser }, targetProfile);
+  if (targetProfile?.auth_method !== 'gck' && (argv.headersFile !== undefined || argv.headers !== undefined || argv.browser)) {
+    throw errUsage('Browser-session input requires a browser-session profile. Select it with --profile, or add a separate connection with auth login --name <name>.');
+  }
   if (targetProfile?.auth_method === 'gck') {
     return loginProfile({
       ...argv, instance: instanceURL, profile: target.name,
-      browser: argv.browser || (!argv.headers && canUsePicker(app, argv)),
+      browser,
     }, app);
   }
   const targetAuthOptions = {
@@ -1083,7 +1108,11 @@ export function authCmd(wrap) {
               type: 'boolean',
             })
             .option('headers', {
-              describe: 'Browser request headers or cURL command for browser-session auth',
+              describe: 'Inline browser headers (compatibility); prefer --headers-file to keep secrets out of arguments',
+              type: 'string',
+            })
+            .option('headers-file', {
+              describe: 'Read browser headers/cURL from a file, or - for stdin; no secrets in arguments',
               type: 'string',
             })
             .option('browser', {
@@ -1143,7 +1172,8 @@ export function authCmd(wrap) {
             .option('browser', { type: 'boolean', describe: 'Explicitly open a browser to renew the session' })
             .option('browser-name', { type: 'string', describe: 'Browser to launch: chromium, chrome, or edge' })
             .option('browser-url', { type: 'string', describe: 'Advanced: local browser debugging URL (requires --browser)' })
-            .option('headers', { type: 'string', describe: 'Captured browser request headers or cURL command' }),
+            .option('headers', { type: 'string', describe: 'Inline captured headers (compatibility); prefer --headers-file' })
+            .option('headers-file', { type: 'string', describe: 'Captured headers/cURL file, or - for stdin; keeps secrets out of arguments' }),
           handler: wrap(refreshProfile),
         })
         .command({

package/src/commands/discover.js

@@ -0,0 +1,54 @@
+import { declareCapabilities } from '../capabilities.js';
+
+declareCapabilities('discover', { noInstance: true, skipDailyChecks: true });
+
+// The live registrations supply names, descriptions, aliases, actions, and
+// factory configuration. No separate inventory of table commands lives here.
+export function discoverCommands(registry, { query = '', table = '' } = {}) {
+  const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+  return registry.commands.filter(command => {
+    const metadata = command.discovery;
+    if (table && metadata?.table !== table) return false;
+    const haystack = [command.name, ...command.aliases, command.description,
+      metadata?.table, ...(metadata?.benefits || []),
+      ...(command.actions || []).map(action => `${action.name} ${action.description}`)].join(' ').toLowerCase();
+    return words.every(word => haystack.includes(word));
+  });
+}
+
+export function discoverCmd(wrap, getRegistry) {
+  return {
+    command: 'discover [query]',
+    describe: 'Find commands by words in their names, aliases, descriptions, or configured table',
+    builder: y => y
+      .positional('query', { type: 'string', describe: 'Search words (quote multiple words)' })
+      .option('table', { type: 'string', describe: 'Find specialized commands configured for this exact table' })
+      .epilogue([
+        'Choose by intent:',
+        '  Cross-table tasks: jsn records list --table task --query "active=true" --json',
+        '  Custom tables: jsn records list --table x_example_record --limit 5 --json',
+        '  Table-specific defaults and views: jsn discover --table incident',
+        '  Rich request views (attachments and variables): jsn requests show --help',
+        '  Raw endpoints when needed: jsn rest --help',
+        'Generic records supports any accessible table; specialized commands provide configured defaults and table-specific behavior.',
+        'Discovery matches registered text; try fewer words if there are no matches.',
+        'Use --json for structured results or --json --get data.commands for only matches.',
+      ].join('\n')),
+    handler: wrap(async (argv, app) => {
+      const commands = discoverCommands(getRegistry(), { query: argv.query, table: argv.table });
+      const lines = commands.flatMap(command => [
+        `${command.name}: ${command.description}`,
+        ...(command.discovery ? [
+          `  Table: ${command.discovery.table}; default columns: ${command.discovery.defaultColumns.join(', ')}`,
+          ...command.discovery.benefits.map(benefit => `  ${benefit}`),
+        ] : []),
+        `  ${command.help}`,
+        ...(command.actions || []).map(action => `  ${action.help} — ${action.description}`),
+      ]);
+      if (!commands.length) lines.push('No registered matches. Try fewer words or use generic records for any accessible table: jsn records list --help');
+      app.ok({ commands, _formatted: lines.join('\n') }, {
+        summary: `${commands.length} matching command(s). Use jsn discover --help for guidance by intent.`,
+      });
+    }),
+  };
+}

package/src/commands/setup.js

@@ -1,5 +1,5 @@
 import { loginWizard, loginProfile, showAuthStatus, switchProfile, modifyProfile, logoutProfile, removeConnection } from './auth.js';
-import { errUsage } from '../errors.js';
+import { errUsageHint } from '../errors.js';
 import { declareCapabilities } from '../capabilities.js';
 
 // Setup manages local profile config — runs without a configured instance.
@@ -7,15 +7,35 @@ import { declareCapabilities } from '../capabilities.js';
 declareCapabilities('setup', { noInstance: true, skipContextHeader: true });
 
 const HUB_CHOICES = [
-  { name: 'Add a connection', value: 'add' },
-  { name: 'Sign in again', value: 'login' },
-  { name: 'Check connections', value: 'status' },
-  { name: 'Choose the default profile', value: 'switch' },
-  { name: 'Change settings', value: 'modify' },
-  { name: 'Sign out (keep the profile)', value: 'logout' },
-  { name: 'Remove a connection', value: 'remove' },
+  { name: 'Add a connection', value: 'add', command: 'jsn auth login <instance> --name <name> --basic' },
+  { name: 'Sign in again', value: 'login', command: 'jsn auth login --profile <name> (with the authentication options below)' },
+  { name: 'Check connections', value: 'status', command: 'jsn auth status --details --json (use --local to skip instance probes)' },
+  { name: 'Choose the default profile', value: 'switch', command: 'jsn auth switch <name>' },
+  { name: 'Change settings', value: 'modify', command: 'jsn auth modify --profile <name> --read-only --confirm-deletes --no-include-counts' },
+  { name: 'Sign out (keep the profile)', value: 'logout', command: 'jsn auth logout --profile <name> --force (only after explicit approval)' },
+  { name: 'Remove a connection', value: 'remove', command: 'jsn auth remove <name>' },
 ];
 
+const setupHelp = () => [
+  'With no profiles, setup opens the add-connection wizard; otherwise it opens the management menu.',
+  'The wizard and these scriptable commands share the same authentication and configuration operations:',
+  ...HUB_CHOICES.map(choice => `  ${choice.name}: ${choice.command}`),
+  '',
+  'Authentication input without secrets in command arguments:',
+  '  Basic: set SN_USERNAME and SN_PASSWORD through your environment, then use --basic.',
+  '  OAuth: jsn auth login <instance> --name <name> --oauth --print-url --wait-file <code-file> --json',
+  '  Browser session: jsn auth login <instance> --name <name> --headers-file <session-file> --json',
+  '  Piped browser session: jsn auth login <instance> --name <name> --headers-file - --json',
+  '  A browser window can also be requested explicitly with --browser; it requires a human to sign in.',
+  '  Refresh OAuth: jsn auth refresh --profile <name>',
+  '  Renew captured browser headers: jsn auth refresh --profile <name> --headers-file <session-file>',
+  '',
+  'New-profile preferences: --read-only, --confirm-deletes, --include-counts and --make-default.',
+  'Use --no-read-only, --no-confirm-deletes, --no-include-counts or --no-make-default for the opposite value.',
+  'Use --json for structured output. Explicit flags avoid implicit pickers; ambiguous targets return an error.',
+  'Discover all options with jsn auth <command> --help.',
+].join('\n');
+
 /** The setup hub prompt; q and Escape resolve with no selected action. */
 export const authHubPrompt = async (...args) => {
   const { createPrompt, useKeypress, usePagination, useState, isDownKey, isEnterKey, isUpKey } = await import('@inquirer/core');
@@ -81,10 +101,11 @@ export function setupCmd(wrap) {
   return {
     command: 'setup',
     describe: 'Set up and manage your ServiceNow instances (interactive)',
+    builder: y => y.epilogue(setupHelp()),
     handler: wrap(async (argv, app) => {
       const { canUsePicker } = await import('../helpers.js');
       if (!app.isInteractive() || !canUsePicker(app, argv)) {
-        throw errUsage('"jsn setup" is interactive. Use the specific commands:\n  jsn auth login <instance>\n  jsn auth refresh\n  jsn auth status');
+        throw errUsageHint('"jsn setup" is interactive. Use explicit auth commands instead.', setupHelp());
       }
       const profileNames = Object.keys(app.config.profiles || {});
       if (profileNames.length === 0) {

package/src/help.js

@@ -200,14 +200,20 @@ function renderFlags(options) {
   return `\nFLAGS\n${lines.join('\n')}`;
 }
 
-function renderTips() {
+export function renderTips() {
   return `
 TIPS
-  --query is available on every list command (e.g. "incidents list --query priority=1")
+  Find commands by task words: "jsn discover catalog"; by configured table: "jsn discover --table incident"
+  Cross-table task searches and custom tables: "jsn records list --help"
+  Specialized commands offer configured columns, lookup, and table-specific views; inspect discovery results for details
+  Raw endpoints when needed: "jsn rest --help"; examples and intent guidance: "jsn discover --help"
   Use "jsn <command> --help" for details, or "jsn <command> list --help" for list options
   "jsn --json" prints the registered command surface as JSON for scripts and agents
 
 LEARN MORE
+  Some list commands offer a picker in an interactive terminal with automatic output.
+  Arrow keys browse (10 visible items); type to search; scroll to load more; Enter selects; Esc cancels.
+  Picker eligibility and search fields vary by command. Explicit output formats (including --json) skip pickers.
   Use "jsn <command> --help" for more information about a command.`;
 }