@jacebenson/jsn 4.3.7-dev.40 → 4.3.7-dev.42

package/package.json

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

package/src/app.js

@@ -14,6 +14,7 @@ import { saveConfig } from './config.js';
 import { resolveSession, applySession, contextFromSession, requireSessionInstance } from './session.js';
 import { getCurrentUser, getCurrentApplication, getCurrentUpdateSet } from './context.js';
 import { errUsage, errAuth } from './errors.js';
+import { canPrompt } from './helpers.js';
 import { isMutationCommand } from './mutations.js';
 import process from 'node:process';
 
@@ -190,8 +191,14 @@ export class App {
     this.output.err(error);
   }
 
+  /**
+   * True only when a human can actually answer a prompt. Delegates to
+   * canPrompt() so the check is "both stdio descriptors are TTYs AND no
+   * agent/CI/opt-out marker is set" — a PTY allocated for an agent
+   * (stdout.isTTY true, JSN_NO_PROMPTS/CI set) is NOT interactive.
+   */
   isInteractive() {
-    return process.stdout.isTTY === true;
+    return canPrompt();
   }
 
   requireInstance() {

package/src/cli-adapter.js

@@ -24,11 +24,38 @@ class CommandNode {
     if (typeof this.definition.builder === 'function') this.definition.builder(this.api());
   }
 
+  /**
+   * Register a child, replacing any existing registration that claims the same
+   * canonical name (or that the new child claims as an alias).
+   *
+   * yargs semantics are last-registration-wins: a command module re-registers a
+   * subcommand to layer a specialized handler over the base one (see
+   * `requests show`). Appending instead of replacing left the base registration
+   * first in the list and reachable by dispatch/help while the duplicate was
+   * invisible to the registry (child counts, inventory, completion).
+   *
+   * Registration order is preserved (the slot is replaced in place) and the
+   * replaced node's aliases are carried over so layered commands keep resolving
+   * through the alias that the base registration published.
+   */
+  register(child) {
+    const index = this.children.findIndex((existing) => existing.name === child.name
+      || existing.aliases.includes(child.name)
+      || child.aliases.includes(existing.name));
+    if (index === -1) {
+      this.children.push(child);
+      return child;
+    }
+    child.aliases = [...new Set([...child.aliases, ...this.children[index].aliases])];
+    this.children[index] = child;
+    return child;
+  }
+
   api() {
     const node = this;
     return {
       command(definition, builder, handler) {
-        node.children.push(new CommandNode(typeof definition === 'string' ? { command: definition, builder, handler } : definition));
+        node.register(new CommandNode(typeof definition === 'string' ? { command: definition, builder, handler } : definition));
         return this;
       },
       option(name, config = {}) { node.options.set(name, { ...config, name }); return this; },
@@ -63,10 +90,16 @@ export class LocalCLI {
   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; }
   command(definition, builder, handler) {
-    const node = new CommandNode(typeof definition === 'string' ? { command: definition, builder, handler } : definition);
-    this.root.children.push(node);
+    this.root.register(new CommandNode(typeof definition === 'string' ? { command: definition, builder, handler } : definition));
     return this;
   }
+  /**
+   * Register the fallback used when a parent command (a node with children) is
+   * invoked with no subcommand and declares no handler of its own. Without it
+   * those parents exited 0 having printed nothing, which reads as success to a
+   * script and as a hang to a human.
+   */
+  onParentDiscovery(fn) { this.parentDiscovery = fn; return this; }
   demandCommand(count, message) { this.root.demand = { count, message }; return this; }
   completion(name, _description, handler) { this.completionCommand = name; this.completionHandler = handler; return this; }
   help() { this.helpEnabled = true; return this; }
@@ -175,6 +208,54 @@ export class LocalCLI {
     if (this.failHandler) return this.failHandler(message, error);
     throw error || new Error(message);
   }
+  /**
+   * Describe the registered command surface: root commands (canonical name,
+   * aliases, describe, child names) and the global option declarations.
+   *
+   * This is the single source both the grouped root help and the machine
+   * discovery output are generated from, so neither can drift away from the
+   * commands that actually exist. Builders run here (idempotently) because a
+   * parent's children are only registered when its builder is invoked.
+   */
+  commandRegistry() {
+    const visible = (node) => node.name !== this.completionCommand;
+    const serialize = (node) => {
+      node.build();
+      return {
+        name: node.name,
+        command: node.definition.command || node.name,
+        aliases: [...node.aliases],
+        description: node.definition.describe || '',
+        subcommands: node.children.filter(visible).map((child) => child.name),
+      };
+    };
+    return {
+      commands: this.root.children.filter(visible).map(serialize),
+      options: [...this.root.options.values()].map((spec) => ({
+        name: spec.name,
+        alias: names(spec.alias),
+        description: spec.description || spec.describe || '',
+        choices: spec.choices || [],
+        type: spec.type || 'boolean',
+      })),
+    };
+  }
+
+  /** Structured child signatures for a parent node, built on demand. */
+  subcommandsOf(node) {
+    return node.children
+      .filter((child) => child.name !== this.completionCommand)
+      .map((child) => {
+        child.build();
+        return {
+          name: child.name,
+          command: child.definition.command || child.name,
+          aliases: [...child.aliases],
+          description: child.definition.describe || '',
+        };
+      });
+  }
+
   _help(node, path = []) {
     const lines = [node.usageText || `Usage: ${this.script} ${path.join(' ') || '<command>'}`];
     if (node.definition.describe) lines.push(`\n${node.definition.describe}`);
@@ -232,6 +313,11 @@ export class LocalCLI {
     const parsed = this._parseOptions(commandArgs, path);
     if (!parsed) return;
     const argv = parsed.values;
+    // A parent command's own children are registry-derived, so a default
+    // handler can list exactly what is registered instead of repeating a
+    // hand-written list that drifts (see the records parent, which advertised
+    // an `inspect` description the registration disagreed with).
+    if (node.children.length) argv.subcommands = this.subcommandsOf(node);
     const specs = [...this._optionConfig(path).values()];
     const positions = positionSpec(node.definition.command || '').map((position) => ({
       ...position, ...node.positionals.get(position.name), name: position.name,
@@ -242,7 +328,13 @@ export class LocalCLI {
     for (const middleware of this.middlewares) await middleware(argv);
     for (const commandNode of path) for (const middleware of commandNode.middlewares) await middleware(argv);
     if (node.definition.handler) await node.definition.handler(argv);
-    else if (node.demand?.count && !path.length) return this._fail(node.demand.message);
+    // A parent with no handler of its own used to fall through and exit 0
+    // with no output — indistinguishable from a command that ran and found
+    // nothing. The registered discovery hook (cli.js) prints the child
+    // surface instead: a JSON envelope in machine mode, a list for humans.
+    else if (path.length && argv.subcommands?.length && this.parentDiscovery) {
+      await this.parentDiscovery(argv, { path: path.map((n) => n.name), subcommands: argv.subcommands });
+    } else if (node.demand?.count && !path.length) return this._fail(node.demand.message);
   }
 }
 

package/src/cli.js

@@ -10,7 +10,8 @@ import { resolveSession, applySession } from './session.js';
 import { renderHelp } from './help.js';
 import { isMutationCommand, refreshMutationCommands } from './mutations.js';
 import { noInstanceCommands, dailyCheckSkipCommands } from './capabilities.js';
-import { guardExit, exitWithError } from './errors.js';
+import { guardExit, exitWithError, AppError, CodeUsage } from './errors.js';
+import { formatCommandList } from './helpers.js';
 
 // Command modules
 import { setupCmd } from './commands/setup.js';
@@ -73,6 +74,53 @@ import { midserversCmd } from './commands/midservers.js';
 import { diffCmd } from './commands/diff.js';
 import { graphqlCmd } from './commands/graphql.js';
 
+/**
+ * Did the caller explicitly ask for machine output?
+ *
+ * Read from the raw argv because parse-time failures happen BEFORE the format
+ * middleware can run, so `--json`/`--format=json` had not reached the output
+ * controller yet — which is exactly why the structured failure envelope was
+ * unreachable for the mistakes scripts and agents hit most (a missing required
+ * flag, a bad choice, an unknown command).
+ */
+function explicitJsonRequest(args) {
+  return args.some((arg, i) => {
+    if (arg === '--json') return true;
+    if (arg.startsWith('--json=')) return arg !== '--json=false';
+    if (arg === '--format=json') return true;
+    return arg === '--format' && args[i + 1] === 'json';
+  });
+}
+
+/**
+ * The output format the caller explicitly asked for, read from the raw argv.
+ *
+ * Same reason as explicitJsonRequest: the format middleware never runs for a
+ * parse-time failure, so an explicit `--format=styled` (human) or
+ * `--format=json` (machine) was silently ignored and the failure was rendered
+ * by the pipe/TTY default instead of what was asked for.
+ */
+function explicitFormat(args) {
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--json') return 'json';
+    if (arg === '--quiet' || arg === '-q') return 'quiet';
+    if (arg === '--styled') return 'styled';
+    if (arg === '--markdown') return 'markdown';
+    if (arg === '--csv') return 'csv';
+    if (arg.startsWith('--format=')) return arg.slice('--format='.length);
+    if (arg === '--format' && args[i + 1]) return args[i + 1];
+  }
+  return '';
+}
+
+/**
+ * Parent commands owned by another change. The adapter's discovery fallback
+ * (which gives a handler-less parent its child list instead of a silent exit 0)
+ * is skipped for these families so their own fix owns the behavior.
+ */
+const DISCOVERY_OWNED_ELSEWHERE = new Set(['auth', 'perf', 'skill', 'groupmembers', 'grouproles']);
+
 function wrap(handler) {
   return async (argv) => {
     try {
@@ -435,14 +483,33 @@ export function buildCLI() {
         cliInstance.showCompletionScript();
       },
     })
+    .onParentDiscovery((argv, { path, subcommands }) => {
+      // Reached only for a parent command that declares no default handler of
+      // its own (cmdb, platform, and any future parent) — the adapter used to
+      // fall through and exit 0 having printed nothing. Children come from the
+      // registry, description included, so this list cannot drift from the
+      // registrations the way a hand-written one did.
+      if (DISCOVERY_OWNED_ELSEWHERE.has(path[0])) return;
+      const canonical = path.join(' ');
+      const summary = `jsn ${canonical} — available subcommands.`;
+      (argv.app || app).ok({
+        command: canonical,
+        subcommands,
+        _formatted: formatCommandList({
+          title: `jsn ${canonical}`,
+          commands: subcommands,
+          footer: `Run "jsn ${canonical} <command> --help" for details.`,
+        }),
+      }, { summary });
+    })
     .help('help', 'Show help')
     .version(false)
     .strictCommands()
     .strictOptions(false)
     .fail((msg, err) => {
       if (err) throw err;
+      const raw = process.argv.slice(2);
       if (msg === 'You must specify a command') {
-        const raw = process.argv.slice(2);
         const hasLoneProfile = raw.some((a, i, arr) => {
           if (a !== '--profile' && a !== '-p') return false;
           const next = arr[i + 1];
@@ -458,11 +525,40 @@ export function buildCLI() {
           }
           process.exit(0);
         }
-        process.stdout.write(renderHelp(loadConfig()) + '\n');
+        // No command is a discovery request, not a failure: the human view
+        // stays exactly as it was (exit 0 + grouped help), and an explicit
+        // --json gets the same surface as machine-readable data instead of
+        // prose that a parser cannot read.
+        if (explicitJsonRequest(raw)) {
+          app.output.setFormat('json');
+          const { commands } = cliInstance.commandRegistry();
+          app.ok({ commands }, {
+            summary: `${commands.length} registered commands — run "jsn <command> --json" for a command's subcommands.`,
+          });
+          process.exit(0);
+        }
+        process.stdout.write(renderHelp(loadConfig(), cliInstance.commandRegistry()) + '\n');
         process.exit(0);
       }
-      process.stderr.write(msg + '\n');
-      process.exit(1);
+      // Every other failure here (unknown command, missing required argument,
+      // invalid choice/number) is a usage failure. Route it through the same
+      // renderer as handler and guard failures: exit 2, and the documented
+      // error envelope on stdout when the caller is in JSON mode. Previously
+      // this wrote raw prose to stderr and exited 1, so the exit code and the
+      // output shape depended on which layer rejected the command.
+      if (explicitJsonRequest(raw)) app.output.setFormat('json');
+      else {
+        const requestedFormat = explicitFormat(raw);
+        if (requestedFormat) app.output.setFormat(requestedFormat);
+      }
+      let hint;
+      try {
+        const path = cliInstance._findPath(raw).path.map((n) => n.name).join(' ');
+        hint = `Run "jsn ${path ? `${path} ` : ''}--help" for usage.`;
+      } catch {
+        hint = 'Run "jsn --help" for the command list.';
+      }
+      exitWithError(new AppError(CodeUsage, msg, hint), { app });
     });
 
   // Snapshot the root command names (plus aliases) for the completion

package/src/commands/auth.js

@@ -1,5 +1,6 @@
 import { getEffectiveInstance, normalizeInstanceURL, saveConfig, setActiveProfile, setProfile } from '../config.js';
-import { errUsage } from '../errors.js';
+import { errUsage, errUsageHint } from '../errors.js';
+import { canUsePicker } from '../helpers.js';
 import { declareCapabilities } from '../capabilities.js';
 import process from 'node:process';
 
@@ -128,14 +129,16 @@ export function validateLoginSelectors(argv = {}, targetProfile = null) {
 }
 
 /**
- * Pick a profile by name — interactive search picker when ambiguous,
- * auto-selects when there's exactly one, throws when none configured.
+ * Pick a profile by name — interactive search picker when ambiguous and a
+ * human is available, auto-selects when there's exactly one, throws when
+ * none configured. A non-interactive caller (agent, pipe, --json/--get)
+ * never opens a picker; it falls back to the single/default profile.
  */
 export async function pickProfile(app, message) {
   const { search } = await import('@inquirer/prompts');
   const profileNames = Object.keys(app.config.profiles || {});
   if (profileNames.length === 0) throw errUsage('No profiles configured. Run "jsn setup" first.');
-  if (profileNames.length === 1 || !app.isInteractive()) return profileNames[0];
+  if (profileNames.length === 1 || !canUsePicker(app, {})) return profileNames[0];
   const choices = profileNames.map(name => ({
     name: `${name} — ${app.config.profiles[name].instance_url}`,
     value: name,
@@ -281,10 +284,9 @@ export async function loginWizard(app, argv = {}) {
   app.config.activeProfile = profileName;
   app.config.defaultProfile = profileName;
 
-  // Present all connection-level options during setup. Gated on interactivity
-  // so a piped/scripted call never blocks on prompts.
-  const { canPrompt } = await import('../helpers.js');
-  if (canPrompt()) {
+  // Present all connection-level options during setup. Gated on
+  // interactivity so a piped/scripted call never blocks on prompts.
+  if (canUsePicker(app, argv)) {
     // @inquirer/prompts owns stdin while these confirmations run. Close the
     // older readline interface before handing stdin to Inquirer. This matters
     // on Windows Git Bash: leaving both readers attached can make the later
@@ -604,7 +606,7 @@ export function authCmd(wrap) {
               instanceURL = normalizeInstanceURL(namedProfile.instance_url);
             } else if (argv.instance) {
               instanceURL = resolveInstanceArg(argv.instance, app.config);
-            } else if (app.isInteractive()) {
+            } else if (canUsePicker(app, argv)) {
               // gh-faithful: interactive terminals always get a picker —
               // existing profiles plus "＋ Add a new instance". Zero profiles
               // goes straight to the setup wizard.
@@ -987,7 +989,9 @@ Examples:
               if (profileNames.length === 0) {
                 throw errUsage('No profiles configured. Run "jsn auth login" first.');
               }
-              if (profileNames.length > 1 && app.isInteractive()) {
+              if (profileNames.length === 1) {
+                name = profileNames[0];
+              } else if (canUsePicker(app, argv)) {
                 const { search } = await import('@inquirer/prompts');
                 const choices = profileNames.map(profileName => ({
                   name: `${profileName} — ${app.config.profiles[profileName].instance_url}`,
@@ -1002,7 +1006,13 @@ Examples:
                 });
                 name = selected;
               } else {
-                name = profileNames[0];
+                // Never silently switch the active profile for a
+                // non-interactive caller: picking one for them is a
+                // config write they did not ask for.
+                throw errUsageHint(
+                  `Which profile? ${profileNames.length} profiles are configured: ${profileNames.join(', ')}`,
+                  'Pass the profile name: jsn auth switch <name>'
+                );
               }
             }
             await setActiveProfile(app.config, name);

package/src/commands/cmdb.js

@@ -8,6 +8,7 @@
 import {
   assertSafeExactMatch,
   buildQuerySuffix,
+  formatCommandList,
   formatRecordForDisplay,
   getStringField,
   interactiveList,
@@ -351,6 +352,23 @@ export function cmdbCmd(wrap) {
   return {
     command: 'cmdb [subcommand]',
     describe: 'Query the Configuration Management Database (CMDB) — CIs and relationship traversal (read-only)',
+    // Parent discovery. Without a handler `jsn cmdb` exited 0 having printed
+    // nothing: a script reads that as success and a human as a hang. The child
+    // list comes from the registry (argv.subcommands), so it cannot drift from
+    // what is registered; the styled view is a side channel that JSON ignores.
+    handler: wrap(async (argv, app) => {
+      const subcommands = argv.subcommands || [];
+      const summary = 'Query the Configuration Management Database (CMDB): CI lookup and relationship traversal. Read-only.';
+      app.ok({
+        command: 'cmdb',
+        subcommands,
+        _formatted: formatCommandList({
+          title: summary,
+          commands: subcommands,
+          footer: 'Run "jsn cmdb <command> --help" for details.',
+        }),
+      }, { summary });
+    }),
     builder: (yargs) => {
       return yargs
         .command({

package/src/commands/docs/docs.js

@@ -15,6 +15,7 @@ import { searchDocs, getDocByIdOrPath } from './search.js';
 import { serveDocs } from './serve.js';
 import { syncCommunity, listCommunityDocs } from './community.js';
 import { declareCapabilities } from '../../capabilities.js';
+import { formatCommandList } from '../../helpers.js';
 
 declareCapabilities('docs', { noInstance: true, skipDailyChecks: true });
 
@@ -256,21 +257,22 @@ export function docsCmd(wrap) {
             .demandCommand(1, 'Specify an action: sync or list'),
         });
     },
-    handler: () => {
-      process.stdout.write('jsn docs — ServiceNow documentation search\n\n');
-      process.stdout.write('Available subcommands:\n');
-      process.stdout.write('  sync      Download docs and build a searchable index (handles updates too)\n');
-      process.stdout.write('  status    Show whether docs are downloaded, indexed, embedded, or served\n');
-      process.stdout.write('  search    Full-text + semantic search across the local docs index\n');
-      process.stdout.write('  show      Display a full documentation page by id or path\n');
-      process.stdout.write('  serve     Start a local web UI for browsing and searching docs\n');
-      process.stdout.write('  community Sync ServiceNow Community articles (hubs + linked posts) into the index\n');
-      process.stdout.write('\n');
-      process.stdout.write('Tip: use "jsn docs serve --expose" to bind to 0.0.0.0 and share on your network.\n');
-      process.stdout.write('\n');
-      const dbPath = getDocsDbPath();
-      process.stdout.write(`Docs DB: ${dbPath} (run "jsn docs status" for details, or query directly with sqlite3)\n`);
-      process.stdout.write('\nRun "jsn docs <command> --help" for details.\n');
-    },
+    handler: wrap(async (argv, app) => {
+      const subcommands = argv.subcommands || [];
+      const summary = 'jsn docs — ServiceNow documentation search (sync, status, search, show, serve).';
+      app.ok({
+        command: 'docs',
+        subcommands,
+        _formatted: formatCommandList({
+          title: summary,
+          commands: subcommands,
+          footer: [
+            'Tip: use "jsn docs serve --expose" to bind to 0.0.0.0 and share on your network.',
+            `Docs DB: ${getDocsDbPath()} (run "jsn docs status" for details, or query directly with sqlite3)`,
+            'Run "jsn docs <command> --help" for details.',
+          ].join('\n'),
+        }),
+      }, { summary });
+    }),
   };
 }

package/src/commands/groupmembers.js

@@ -1,4 +1,9 @@
-import { formatRecordForDisplay, getStringField, resolveFieldsParam } from '../helpers.js';
+import { formatRecordForDisplay, getStringField, resolveFieldsParam, assertSafeExactMatch, confirmDelete, quoteShellArg } from '../helpers.js';
+import { declareCapabilities } from '../capabilities.js';
+
+// add/remove write sys_user_grmember; the mutation guard (instance +
+// read-only profile) and the delete confirmation both key off this.
+declareCapabilities('groupmembers', { mutationSubcommands: ['add', 'remove'] });
 
 export function groupMembersCmd(wrap) {
   return {
@@ -42,6 +47,8 @@ export function groupMembersCmd(wrap) {
           handler: wrap(async (argv, app) => {
             const groupName = argv.group;
             const userName = argv.user;
+            assertSafeExactMatch(groupName);
+            assertSafeExactMatch(userName);
 
             // Resolve group sys_id
             const isGroupSysID = groupName.length === 32 && /^[0-9a-fA-F]+$/.test(groupName);
@@ -86,7 +93,7 @@ export function groupMembersCmd(wrap) {
               summary: `Added ${userName} to ${groupName}`,
               breadcrumbs: [
                 { action: 'list', cmd: `jsn groupmembers list --query "group.name=${groupName}"`, description: 'List group members' },
-                { action: 'remove', cmd: `jsn groupmembers remove --group "${groupName}" --user "${userName}"`, description: 'Remove this member' },
+                { action: 'remove', cmd: `jsn groupmembers remove --group ${quoteShellArg(groupName)} --user ${quoteShellArg(userName)}`, description: 'Remove this member' },
               ],
             });
           }),
@@ -96,10 +103,18 @@ export function groupMembersCmd(wrap) {
           describe: 'Remove a user from a group',
           builder: (y) => y
             .option('group', { alias: 'g', type: 'string', demandOption: true, describe: 'Group name or sys_id (required)' })
-            .option('user', { alias: 'u', type: 'string', demandOption: true, describe: 'Username or sys_id (required)' }),
+            .option('user', { alias: 'u', type: 'string', demandOption: true, describe: 'Username or sys_id (required)' })
+            .option('force', { type: 'boolean', describe: 'Skip the confirmation prompt (removal)' }),
           handler: wrap(async (argv, app) => {
             const groupName = argv.group;
             const userName = argv.user;
+            assertSafeExactMatch(groupName);
+            assertSafeExactMatch(userName);
+            // Confirm before any lookup: a refused confirmation must not
+            // touch the instance at all.
+            await confirmDelete(app, argv, `Remove ${userName} from group ${groupName}`, {
+              rerun: ['groupmembers', 'remove', '--group', groupName, '--user', userName],
+            });
 
             // Resolve group sys_id
             const isGroupSysID = groupName.length === 32 && /^[0-9a-fA-F]+$/.test(groupName);
@@ -142,7 +157,7 @@ export function groupMembersCmd(wrap) {
               summary: `Removed ${userName} from ${groupName}`,
               breadcrumbs: [
                 { action: 'list', cmd: `jsn groupmembers list --query "group.name=${groupName}"`, description: 'List group members' },
-                { action: 'add', cmd: `jsn groupmembers add --group "${groupName}" --user "${userName}"`, description: 'Add user back to group' },
+                { action: 'add', cmd: `jsn groupmembers add --group ${quoteShellArg(groupName)} --user ${quoteShellArg(userName)}`, description: 'Add user back to group' },
               ],
             });
           }),

package/src/commands/grouproles.js

@@ -1,4 +1,9 @@
-import { formatRecordForDisplay, getStringField, resolveFieldsParam, assertSafeExactMatch } from '../helpers.js';
+import { formatRecordForDisplay, getStringField, resolveFieldsParam, assertSafeExactMatch, confirmDelete, quoteShellArg } from '../helpers.js';
+import { declareCapabilities } from '../capabilities.js';
+
+// add/remove write sys_group_has_role; the mutation guard (instance +
+// read-only profile) and the delete confirmation both key off this.
+declareCapabilities('grouproles', { mutationSubcommands: ['add', 'remove'] });
 
 export function groupRolesCmd(wrap) {
   return {
@@ -88,7 +93,7 @@ export function groupRolesCmd(wrap) {
               summary: `Added role ${roleName} to ${groupName}`,
               breadcrumbs: [
                 { action: 'list', cmd: `jsn grouproles list --query "group.name=${groupName}"`, description: 'List group roles' },
-                { action: 'remove', cmd: `jsn grouproles remove --group "${groupName}" --role "${roleName}"`, description: 'Remove this role' },
+                { action: 'remove', cmd: `jsn grouproles remove --group ${quoteShellArg(groupName)} --role ${quoteShellArg(roleName)}`, description: 'Remove this role' },
               ],
             });
           }),
@@ -98,12 +103,18 @@ export function groupRolesCmd(wrap) {
           describe: 'Remove a role from a group',
           builder: (y) => y
             .option('group', { alias: 'g', type: 'string', demandOption: true, describe: 'Group name or sys_id (required)' })
-            .option('role', { alias: 'r', type: 'string', demandOption: true, describe: 'Role name or sys_id (required)' }),
+            .option('role', { alias: 'r', type: 'string', demandOption: true, describe: 'Role name or sys_id (required)' })
+            .option('force', { type: 'boolean', describe: 'Skip the confirmation prompt (removal)' }),
           handler: wrap(async (argv, app) => {
             const groupName = argv.group;
             const roleName = argv.role;
             assertSafeExactMatch(groupName);
             assertSafeExactMatch(roleName);
+            // Confirm before any lookup: a refused confirmation must not
+            // touch the instance at all.
+            await confirmDelete(app, argv, `Remove role ${roleName} from group ${groupName}`, {
+              rerun: ['grouproles', 'remove', '--group', groupName, '--role', roleName],
+            });
 
             // Resolve group sys_id
             const isGroupSysID = groupName.length === 32 && /^[0-9a-fA-F]+$/.test(groupName);
@@ -146,7 +157,7 @@ export function groupRolesCmd(wrap) {
               summary: `Removed role ${roleName} from ${groupName}`,
               breadcrumbs: [
                 { action: 'list', cmd: `jsn grouproles list --query "group.name=${groupName}"`, description: 'List group roles' },
-                { action: 'add', cmd: `jsn grouproles add --group "${groupName}" --role "${roleName}"`, description: 'Add role back to group' },
+                { action: 'add', cmd: `jsn grouproles add --group ${quoteShellArg(groupName)} --role ${quoteShellArg(roleName)}`, description: 'Add role back to group' },
               ],
             });
           }),

package/src/commands/perf.js

@@ -2,14 +2,21 @@ import { errUsageHint, errUsage } from '../errors.js';
 import { captureRun, listRuns, getRun, compareRuns, formatRunDetailed, formatRunList, formatComparisonDetailed } from '../perf.js';
 import { topTransactionsCmd } from './transactions.js';
 import { paginatedSearch } from '../paginated-search.js';
+import { canUsePicker } from '../helpers.js';
 
-function pickerEnabled(app) {
-  return Boolean(process.stdin.isTTY && process.stdout.isTTY && app.output?.effectiveFormat?.() !== 'json' && app.output?.effectiveFormat?.() !== 'quiet');
+/**
+ * A picker is only safe when a human is reachable AND the invocation did
+ * not ask for machine output (`--json`/`--quiet`) or a one-shot extraction
+ * (`--get`). canUsePicker() owns that rule so CI/agent markers and
+ * JSN_NO_PROMPTS are honored too.
+ */
+function pickerEnabled(app, argv = {}) {
+  return canUsePicker(app, argv);
 }
 
-async function pickRun(app, { exclude = new Set(), message = 'Select a performance capture' } = {}) {
+async function pickRun(app, { exclude = new Set(), message = 'Select a performance capture', argv = {} } = {}) {
   const runs = listRuns({ limit: 1000 }).filter(run => !exclude.has(run.run_id));
-  if (!pickerEnabled(app) || runs.length === 0) return null;
+  if (!pickerEnabled(app, argv) || runs.length === 0) return null;
   const selected = await paginatedSearch({
     message,
     totalCount: runs.length,
@@ -78,7 +85,7 @@ export function perfCmd(wrap) {
         builder: (b) => b.option('limit', { alias: 'l', type: 'number', default: 50, describe: 'Maximum runs to show' }),
         handler: wrap(async (argv, app) => {
           const runs = listRuns({ limit: argv.limit });
-          const picked = await pickRun(app, { message: 'Select a performance capture' });
+          const picked = await pickRun(app, { message: 'Select a performance capture', argv });
           if (picked) {
             const run = getRun(picked.run_id);
             app.ok({ ...run, _formatted: formatRunDetailed(run) }, {
@@ -100,8 +107,16 @@ export function perfCmd(wrap) {
         command: 'show [run_id]',
         describe: 'Show one saved performance capture',
         handler: wrap(async (argv, app) => {
-          const run = argv.run_id ? requireRun(argv.run_id, 'target') : await pickRun(app);
-          if (!run) return;
+          // No run ID and no human to pick one: fail with a usable error
+          // instead of exiting 0 with no output at all.
+          if (!argv.run_id && !pickerEnabled(app, argv)) {
+            throw errUsageHint(
+              'Missing run ID: `jsn perf show` needs a run ID when prompts are unavailable.',
+              'Find a capture with `jsn perf list`, then run `jsn perf show <run_id>`.'
+            );
+          }
+          const run = argv.run_id ? requireRun(argv.run_id, 'target') : await pickRun(app, { argv });
+          if (!run) return; // cancelled at the picker
           app.ok({ ...run, _formatted: formatRunDetailed(run) }, {
             summary: `Performance capture ${run.run_id}`,
             breadcrumbs: [listHint(), compareHint(run.run_id)],
@@ -118,9 +133,15 @@ export function perfCmd(wrap) {
         describe: 'Compare exactly two saved captures',
         handler: wrap(async (argv, app) => {
           if (!argv.baseline && !argv.new) {
-            const baseline = await pickRun(app, { message: 'Select the baseline capture' });
+            if (!pickerEnabled(app, argv)) {
+              throw errUsageHint(
+                'Compare requires exactly two run IDs when prompts are unavailable.',
+                'Run `jsn perf compare <baseline> <new>` with two run IDs from `jsn perf list`.'
+              );
+            }
+            const baseline = await pickRun(app, { message: 'Select the baseline capture', argv });
             if (!baseline) return;
-            const newer = await pickRun(app, { exclude: new Set([baseline.run_id]), message: 'Select the new capture' });
+            const newer = await pickRun(app, { exclude: new Set([baseline.run_id]), message: 'Select the new capture', argv });
             if (!newer) return;
             const baselineRun = getRun(baseline.run_id);
             const newerRun = getRun(newer.run_id);

package/src/commands/platform.js

@@ -1,4 +1,5 @@
 import { declareCapabilities } from '../capabilities.js';
+import { formatCommandList } from '../helpers.js';
 
 function numberOrString(value) {
   const n = Number(value);
@@ -270,6 +271,22 @@ export function platformCmd(wrap) {
   return {
     command: 'platform',
     describe: 'Inspect read-only platform health and node statistics',
+    // Parent discovery. This parent had no handler, so `jsn platform` and
+    // `jsn platform --json` exited 0 with no output at all — silent success.
+    // Children come from the registry, not a second hand-written list.
+    handler: wrap(async (argv, app) => {
+      const subcommands = argv.subcommands || [];
+      const summary = 'Inspect read-only platform health and node statistics.';
+      app.ok({
+        command: 'platform',
+        subcommands,
+        _formatted: formatCommandList({
+          title: summary,
+          commands: subcommands,
+          footer: 'Run "jsn platform <command> --help" for details.',
+        }),
+      }, { summary });
+    }),
     builder: (y) => y.command({
       command: 'health',
       describe: 'Show cluster, queue, semaphore, and node health',

package/src/commands/records.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { formatRecordForDisplay, buildQuerySuffix, parseDataArg, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, assertSafeExactMatch, verifyWriteBack } from '../helpers.js';
+import { formatCommandList, formatRecordForDisplay, buildQuerySuffix, parseDataArg, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, assertSafeExactMatch, verifyWriteBack } from '../helpers.js';
 import { declareCapabilities } from '../capabilities.js';
 
 declareCapabilities('records', {
@@ -514,20 +514,24 @@ export function recordsCmd(wrap) {
         })
 
     },
-    handler: (argv) => {
+    // Parent discovery through the output controller: the subcommand list is
+    // registry-derived (argv.subcommands), so `jsn records --json` returns a
+    // structured envelope instead of prose, and the descriptions can no longer
+    // describe a different surface than the registrations (the previous
+    // hand-written list advertised `inspect` as table schema/statistics).
+    handler: wrap(async (argv, app) => {
       if (argv._[1]) return; // a subcommand ran — its own handler handled it
-      console.log('Query and manage records in any ServiceNow table.');
-      console.log('');
-      console.log('Available subcommands:');
-      console.log('  list                  List records from a table (includes total by default)');
-      console.log('  get                   Get a single record by sys_id (--attachments to include files)');
-      console.log('  create                Create a record');
-      console.log('  update                Update a record');
-      console.log('  delete                Delete a record');
-      console.log('  aggregate              Run Stats API aggregation with optional grouping');
-      console.log('  inspect                Inspect table schema and statistics');
-      console.log('');
-      console.log('Run "jsn records <command> --help" for details.');
-    },
+      const subcommands = argv.subcommands || [];
+      const summary = 'Query and manage records in any ServiceNow table.';
+      app.ok({
+        command: 'records',
+        subcommands,
+        _formatted: formatCommandList({
+          title: summary,
+          commands: subcommands,
+          footer: 'Run "jsn records <command> --help" for details.',
+        }),
+      }, { summary });
+    }),
   };
 }

package/src/commands/skill.js

@@ -8,6 +8,7 @@ import { execSync } from 'node:child_process';
 
 import { globalConfigPath } from '../config.js';
 import { declareCapabilities } from '../capabilities.js';
+import { canUsePicker } from '../helpers.js';
 
 declareCapabilities('skill', { noInstance: true, skipDailyChecks: true });
 
@@ -305,8 +306,10 @@ export function skillCmd(wrap) {
                   }
                 }
               }
-            } else if (process.stdin.isTTY) {
-              // Interactive: show multi-select picker
+            } else if (canUsePicker(app, argv)) {
+              // Interactive: show multi-select picker. canUsePicker() (not a
+              // bare stdin TTY check) keeps a PTY allocated for an agent,
+              // CI, JSN_NO_PROMPTS, --json/--quiet or --get out of a prompt.
               const fetchedVersion = extractVersion(content);
               // Check if any existing installed copies are outdated
               const outdated = [];

package/src/errors.js

@@ -10,6 +10,7 @@ export const CodeAPI = 'api_error';
 export const CodeAmbiguous = 'ambiguous';
 export const CodeEmptyResult = 'empty_result';
 export const CodeConfirmationRequired = 'confirmation_required';
+export const CodeExtractionNotFound = 'extraction_not_found';
 
 export class AppError extends Error {
   constructor(code, message, hint = '', status = 0, cause = null) {
@@ -118,17 +119,48 @@ export function errAmbiguous(resource, matches) {
   );
 }
 
+/**
+ * Structured error for `--get <path>` resolving to nothing.
+ *
+ * An unresolvable path (typo, wrong envelope shape, out-of-range index) is a
+ * failure, not a value: printing `undefined` and exiting 0 made a misspelled
+ * extract look like a successful empty result until the next tool in the pipe
+ * tried to parse it. A path that resolves to a present null, false, 0, or ""
+ * is a real value and is returned unchanged — only an unresolved path errors.
+ */
+export function errExtractionNotFound(path) {
+  return new AppError(
+    CodeExtractionNotFound,
+    `No value at --get path "${path}".`,
+    'Check the path against the envelope (run the same command without --get, or with --json, to see its shape). '
+    + 'Present null, false, 0, and "" values are returned as-is; only an unresolvable path fails.'
+  );
+}
+
 /**
  * Structured error for a destructive action that requires confirmation
  * but no human is available to answer (non-TTY, pipes, or AI agents).
+ *
  * The hint is written to be machine-parseable: an agent can read the
- * re-run command and either present it to its user or execute it.
+ * exact re-run command — target, table, pinned profile/instance — and
+ * present it to its user for approval before executing. It deliberately
+ * does NOT recommend permanently disabling confirmations: an approval for
+ * one destructive action is not consent to disarm the guard for every
+ * future action.
+ *
+ * @param {string} question — e.g. `Delete incident INC0010001?`
+ * @param {string} [rerunCmd] — complete re-run command WITHOUT --force,
+ *   already shell-quoted. Empty when the caller cannot reconstruct it.
  */
-export function errConfirmationRequired(question, rerunCmd) {
+export function errConfirmationRequired(question, rerunCmd = '') {
+  const cmd = String(rerunCmd || '').trim();
+  const hint = cmd
+    ? `This is a destructive action. Ask your user to approve this exact command, then re-run:\n  ${cmd} --force`
+    : 'This is a destructive action. Ask your user to approve it, then re-run the same command with --force.';
   return new AppError(
     CodeConfirmationRequired,
-    `${question} — confirmation required. Pass --force to skip, or set skip_confirmations on the profile to disable prompts.`,
-    `This is a destructive action. Ask your user to confirm, then re-run:\n  ${rerunCmd} --force\nOr set skip_confirmations on the profile to disable prompts:\n  jsn auth login <instance> --skip-confirmations`
+    `${question} — confirmation required. Pass --force only after your user approves this operation.`,
+    hint
   );
 }
 
@@ -152,12 +184,20 @@ export function isErrorCode(err, code) {
  *
  * Exit-code contract (observable behavior, pinned by tests):
  *   not_found              → 1   stderr, "Error (not_found): …" + identifier hint
- *   usage / usage_error    → 2   stderr, "Error (usage): …"
+ *   extraction_not_found   → 1   JSON envelope on stdout in JSON mode, else stderr
+ *   usage / usage_error    → 2   JSON envelope on stdout in JSON mode
+ *                                (machine consumers), else stderr "Error (usage): …"
  *   system_error           → 3   stderr, "Error (system): …"
  *   confirmation_required  → 1   JSON envelope on stdout in JSON mode
  *                                (machine consumers), else stderr + hint
  *   anything else          → 1   stderr, "Error: …"
  *
+ * The JSON envelope is the SAME shape for every failure that a machine
+ * consumer can hit — guardError(), the mutation middleware, parse-time
+ * failures routed by cli.js, and handler-thrown AppErrors all end up here, so
+ * `--json` never yields human prose on stdout and never yields a
+ * success-shaped payload for a failed command.
+ *
  * jsonMode resolution: prefer app.output.effectiveFormat() (respects
  * --json/--quiet/etc. shortcuts AND piped-stdout auto-detection); fall
  * back to argv.format for callers without an App (unit tests).
@@ -201,15 +241,35 @@ export function renderAppError(err, { app = null, argv = null, identifier = '' }
     return { stream: 'stderr', text, exitCode: 1 };
   }
 
+  if (code === CodeExtractionNotFound) {
+    // Same contract as every other machine-consumable failure: a parseable
+    // envelope on stdout when the caller is in JSON mode, human text on
+    // stderr otherwise. Exit 1 — the command ran, the value was absent.
+    if (resolveJsonMode(app, argv) && app) {
+      return { stream: 'stdout', text: null, exitCode: 1, appErr: true };
+    }
+    let text = `Error (${code}): ${err.message}\n`;
+    if (err.hint) text += `\nHint: ${err.hint}\n`;
+    return { stream: 'stderr', text, exitCode: 1 };
+  }
+
   // 'usage' is the legacy literal; CodeUsage ('usage_error') is the
   // exported constant. Both render as the usage class.
   if (code === CodeUsage || code === 'usage') {
-    // Interactive command families can opt into machine-readable fail-fast errors
-    // without changing the legacy stderr contract for other usage errors.
-    if (err.jsonEnvelope === true && resolveJsonMode(app, argv) && app) {
+    // Usage failures were the last split-brain case: a parse-time failure
+    // exited 1 with raw prose, a middleware guard exited 2 with a JSON
+    // envelope, and a handler-thrown usage error exited 2 with prose — all
+    // for the same class of mistake. One renderer, one exit code (2), and a
+    // structured envelope whenever the caller is in JSON mode.
+    if (resolveJsonMode(app, argv) && app) {
       return { stream: 'stdout', text: null, exitCode: 2, appErr: true };
     }
-    return { stream: 'stderr', text: `Error (usage): ${err.message}\n`, exitCode: 2 };
+    // Keep the actionable hint (the failing command's --help) in the human view
+    // too — it used to be dropped on this path while every other error class
+    // printed one.
+    let text = `Error (usage): ${err.message}\n`;
+    if (err.hint) text += `\nHint: ${err.hint}\n`;
+    return { stream: 'stderr', text, exitCode: 2 };
   }
 
   if (code === 'system_error') {

package/src/help.js

@@ -1,5 +1,14 @@
 // Custom grouped help renderer
 // Organized by ServiceNow domain model with subgroup dividers
+//
+// The command rows are generated from the LIVE command registry
+// (`cli.commandRegistry()`): every registered root command appears, with the
+// description its own registration declares. The tables below are placement
+// hints only — group order, dividers, and a fallback description for a command
+// that declares none. A command that is registered but not hinted lands in the
+// trailing "MORE" group, so help can never silently drop a command again
+// (`approvals`, `cmdb`, `docs`, `perf`, `platform`, … were missing from the
+// hand-written list while being fully registered).
 
 function renderGroup(name, commands) {
   const lines = [`\n${name}`];
@@ -23,6 +32,8 @@ const CORE_COMMANDS = [
   { name: 'changes', alias: 'chg', desc: 'Manage change requests' },
   { name: 'requests', alias: 'req', desc: 'Manage service catalog requests' },
   { name: 'tasks', alias: 'task', desc: 'Manage catalog tasks' },
+  { name: 'tickets', desc: 'Query generic tickets' },
+  { name: 'approvals', desc: 'Approval requests (list, approve, reject, submit, history)' },
 ];
 
 const AUTOMATION_COMMANDS = [
@@ -96,6 +107,7 @@ const DATA_COMMANDS = [
   { name: 'tables', alias: 't', desc: 'Table definitions' },
   { name: 'columns', alias: 'col', desc: 'Column definitions' },
   { name: 'relationships', alias: 'rel', desc: 'Table relationships' },
+  { name: 'cmdb', desc: 'CMDB: CI lookup and relationship traversal (read-only)' },
 
   { divider: '── Shared Code, Transforms, Logs ──' },
   { name: 'includes', alias: 'si', desc: 'Script includes' },
@@ -104,6 +116,8 @@ const DATA_COMMANDS = [
   { name: 'properties', alias: 'prop', desc: 'System properties' },
 
   { name: 'records', desc: 'Generic Table API (any table)' },
+  { name: 'transactions', desc: 'Client transaction timings' },
+  { name: 'snippets', desc: 'Saved query snippets' },
 ];
 
 const CONFIG_COMMANDS = [
@@ -112,12 +126,20 @@ const CONFIG_COMMANDS = [
   { name: 'updatesets', desc: 'Update sets (set, create, export)' },
   { name: 'scopes', desc: 'Application scopes' },
   { name: 'domains', desc: 'Domains (domain separation)' },
+  { name: 'midservers', desc: 'MID Servers and MID-run commands' },
+  { name: 'platform', desc: 'Platform health and node statistics (read-only)' },
+  { name: 'completion', desc: 'Shell completion script' },
 ];
 
 const DEVELOPER_COMMANDS = [
   { name: 'atf', desc: 'Automated Test Framework (list, suites, run, results)' },
   { name: 'eval', desc: 'Run server-side JavaScript' },
   { name: 'rest', desc: 'Raw REST API calls' },
+  { name: 'graphql', desc: 'GraphQL queries' },
+  { name: 'codesearch', desc: 'Search code across ServiceNow artifacts' },
+  { name: 'docs', desc: 'Local ServiceNow documentation search' },
+  { name: 'diff', desc: 'Compare records across configured profiles' },
+  { name: 'perf', desc: 'Read-only performance capture and comparison' },
   { name: 'skill', desc: 'AI agent skill file (show, fetch, install)' },
   { name: 'version', desc: 'Version info (--check for npm updates)' },
 ];
@@ -132,17 +154,50 @@ const COMMAND_GROUPS = {
   'DEVELOPER': DEVELOPER_COMMANDS,
 };
 
-function renderFlags() {
-  return `
-FLAGS
-  --instance    ServiceNow instance URL (e.g., https://dev12345.service-now.com)  [string]
-  -p, --profile Configuration profile to use                                      [string]
-  --format      Output format: auto, json, markdown, styled, quiet                [string]
-  --json        Output in JSON format                                            [boolean]
-  -q, --quiet   Output only data, no envelope                                    [boolean]
-  --styled      Force styled output                                              [boolean]
-  --markdown    Output in Markdown format                                        [boolean]
-  --help        Show help                                                        [boolean]`;
+/**
+ * Domain separation is an optional plugin — only advertise `domains` when the
+ * active profile's capability probe found it installed.
+ */
+function isCapabilityHidden(name, config) {
+  if (name !== 'domains') return false;
+  const activeName = config?.activeProfile || config?.defaultProfile;
+  return !(activeName && config?.profiles?.[activeName]?.domain_separation);
+}
+
+/**
+ * Group rows for one domain: registry first (alias/description from the
+ * command's own registration), hint text only as a fallback description.
+ */
+function rowsFor(hint, byName, used, config) {
+  const rows = [];
+  for (const entry of hint) {
+    if (entry.divider) { rows.push(entry); continue; }
+    const node = byName.get(entry.name);
+    if (!node || isCapabilityHidden(node.name, config)) continue;
+    used.add(node.name);
+    rows.push({
+      name: node.name,
+      alias: node.aliases[0] || entry.alias || '',
+      desc: node.description || entry.desc || '',
+    });
+  }
+  return rows;
+}
+
+function renderFlags(options) {
+  // Derived from the registered global options, so a new global flag cannot be
+  // missing from help (--get and --csv were, along with the csv format choice).
+  const lines = [];
+  for (const spec of options) {
+    if (spec.name === 'help') continue;
+    const alias = spec.alias.length ? `-${spec.alias.join(', -')}, ` : '';
+    const suffix = spec.name === 'format' && spec.choices.length
+      ? ` [string: ${spec.choices.join(', ')}]`
+      : ` [${spec.type}]`;
+    lines.push(`  ${`${alias}--${spec.name}`.padEnd(24)}${spec.description}${suffix}`);
+  }
+  lines.push(`  ${'--help'.padEnd(24)}Show help${' [boolean]'}`);
+  return `\nFLAGS\n${lines.join('\n')}`;
 }
 
 function renderTips() {
@@ -150,35 +205,45 @@ function renderTips() {
 TIPS
   --query is available on every list command (e.g. "incidents list --query priority=1")
   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
   Use "jsn <command> --help" for more information about a command.`;
 }
 
-export function renderHelp(config) {
-  // Domain separation is an optional plugin — only advertise `domains`
-  // when the active profile's capability probe found it installed.
-  const activeName = config?.activeProfile || config?.defaultProfile;
-  const hasDS = !!(activeName && config?.profiles?.[activeName]?.domain_separation);
-  const configCmds = hasDS
-    ? CONFIG_COMMANDS
-    : CONFIG_COMMANDS.filter((c) => !c.name || c.name !== 'domains');
-
-  const COMMAND_GROUPS_LOCAL = {
-    ...COMMAND_GROUPS,
-    'CONFIGURATION': configCmds,
-  };
-
-  const sections = Object.entries(COMMAND_GROUPS_LOCAL).map(([name, cmds]) => renderGroup(name, cmds));
+/**
+ * Render the grouped root help.
+ *
+ * @param {object} config — profile config (capability-conditioned hiding)
+ * @param {{commands: Array, options: Array}} [registry] — from
+ *   `cli.commandRegistry()`. Without it only the hint tables render, which is
+ *   the fallback for callers that have no registry (unit tests).
+ */
+export function renderHelp(config, registry = null) {
+  const commands = Array.isArray(registry?.commands) ? registry.commands : [];
+  const byName = new Map(commands.map((command) => [command.name, command]));
+  const used = new Set();
+
+  const sections = Object.entries(COMMAND_GROUPS)
+    .map(([name, hint]) => [name, rowsFor(hint, byName, used, config)])
+    .filter(([, rows]) => rows.some((row) => !row.divider))
+    .map(([name, rows]) => renderGroup(name, rows));
+
+  // Anything registered that the hint tables don't place. This is the safety
+  // net that keeps help complete as commands are added at the root.
+  const unplaced = commands
+    .filter((command) => !used.has(command.name) && !isCapabilityHidden(command.name, config))
+    .map((command) => ({ name: command.name, alias: command.aliases[0] || '', desc: command.description || '' }));
+  if (unplaced.length) sections.push(renderGroup('MORE', unplaced));
 
   return [
     'Usage: jsn <command> [options]',
     '',
-    `Command-line interface for ServiceNow`,
+    'Command-line interface for ServiceNow',
     '',
     ...sections,
     '',
-    renderFlags(),
+    renderFlags(Array.isArray(registry?.options) ? registry.options : []),
     renderTips(),
     '',
   ].join('\n');

package/src/helpers.js

@@ -32,6 +32,29 @@ export function canPrompt() {
   return isTTY(process.stdout) && isTTY(process.stdin);
 }
 
+/**
+ * True when an interactive picker may be opened for THIS invocation.
+ *
+ * canPrompt() alone answers "is a human reachable" — it does not know that
+ * the caller asked for machine output (`--json`, `--quiet`, `--csv`, …) or
+ * a one-shot extraction (`--get`). Opening a picker in either case blocks a
+ * script and corrupts the requested output shape, so every picker gate
+ * routes through here.
+ *
+ * @param {object} app — app instance (uses app.output when present)
+ * @param {object} [argv] — parsed args (checks argv.get)
+ * @returns {boolean} true when a picker may be shown
+ */
+export function canUsePicker(app, argv = {}) {
+  if (argv && argv.get) return false;
+  if (!canPrompt()) return false;
+  const writer = app?.output;
+  if (!writer) return true; // no output controller (unit-test app) — canPrompt decided
+  const format = typeof writer.getFormat === 'function' ? writer.getFormat() : undefined;
+  if (!format) return true;
+  return format === FormatAuto;
+}
+
 /**
  * Render a parent command's subcommand list for its default handler.
  *
@@ -47,6 +70,55 @@ export function formatCommandList({ title, commands, footer }) {
   return `${lines.join('\n')}\n`;
 }
 
+/**
+ * Quote one argv token so the emitted confirmation hint is copy-pasteable
+ * in a POSIX shell. Boring tokens stay bare; anything containing spaces,
+ * quotes, `$`, `;`, `&`, `*` … gets single-quoted with embedded quotes
+ * escaped. `^ = < > ~ ! ,` are ServiceNow query characters — common in
+ * encoded queries — and are shell-safe bare, so they stay bare.
+ *
+ * @param {*} value — token
+ * @returns {string} shell-safe token
+ */
+export function quoteShellArg(value) {
+  const s = value == null ? '' : String(value);
+  if (s === '') return "''";
+  if (/^[A-Za-z0-9_@%+=:,./^-]+$/.test(s)) return s;
+  return `'${s.split("'").join("'\\''")}'`;
+}
+
+/**
+ * Build the exact, safely-quoted rerun command for a confirmation hint.
+ *
+ * `argv._` holds command PATH NAMES only — the local adapter stores
+ * positionals and flags in named fields — so a hint built from `argv._`
+ * alone loses the target (`jsn incidents delete` with no number). Callers
+ * therefore pass the complete target tokens.
+ *
+ * @param {object} argv — parsed args (reads `_`, `profile`, `instance`)
+ * @param {object} [opts]
+ * @param {string|string[]} [opts.rerun] — complete rerun command: a token
+ *   array (quoted here) or a full command string (used verbatim)
+ * @returns {string} command without `--force`, or '' when unknowable
+ */
+export function buildRerunCommand(argv = {}, { rerun = null } = {}) {
+  let parts;
+  if (Array.isArray(rerun) && rerun.length > 0) {
+    parts = ['jsn', ...rerun].map(quoteShellArg);
+  } else if (typeof rerun === 'string' && rerun.trim()) {
+    parts = [rerun.trim()];
+  } else {
+    parts = ['jsn', ...(argv?._ || [])].map(quoteShellArg);
+  }
+  if (parts.length === 1) return ''; // no path known — nothing worth repeating
+  const joined = parts.join(' ');
+  // Re-pin the profile/instance the caller was operating on, so following
+  // the hint cannot silently retarget a different instance or profile.
+  if (argv?.profile && !joined.includes('--profile')) parts.push('--profile', quoteShellArg(argv.profile));
+  if (argv?.instance && !joined.includes('--instance')) parts.push('--instance', quoteShellArg(argv.instance));
+  return parts.join(' ');
+}
+
 /**
  * Confirm a destructive action before executing.
  *
@@ -59,10 +131,12 @@ export function formatCommandList({ title, commands, footer }) {
  * @param {object} app — app instance (reads active profile from app.config)
  * @param {object} argv — parsed args (checks argv.force)
  * @param {string} question — e.g. `Delete incident INC0010001?`
+ * @param {object} [options] — { rerun } complete rerun command or token
+ *   array for the hint (see buildRerunCommand)
  * @returns {Promise<boolean>} true when the action may proceed
  * @throws when confirmation is required but denied/unavailable
  */
-export async function confirmDelete(app, argv, question) {
+export async function confirmDelete(app, argv, question, options = {}) {
   const profile = getActiveProfile(app.config);
   if (profile?.skip_confirmations === true) return true;
   if (argv.force) return true;
@@ -80,8 +154,7 @@ export async function confirmDelete(app, argv, question) {
   }
   // No human available (pipes, scripts, AI agents). Fail fast with a
   // structured error an agent can act on — never hang waiting for stdin.
-  const cmd = ['jsn', ...(argv._ || [])].join(' ');
-  throw errConfirmationRequired(question, cmd);
+  throw errConfirmationRequired(question, buildRerunCommand(argv, options));
 }
 
 
@@ -298,14 +371,39 @@ export async function interactiveList({ app, table, singular, columns, limit = 5
   const pickerFields = pickerColumns.join(',');
   const baseQuery = query ? query + '^' : '';
 
-  // Get total count
-  let totalCount;
+  // Get total count. A FAILED count is unknown — never zero. Mapping the
+  // failure to 0 used to make callers report an invented "empty table"
+  // success (or silently return) when the real cause was a 403/network
+  // error. Only a measured 0 means empty; otherwise confirm emptiness with
+  // one bounded list request before showing the picker.
+  let totalCount = null;
+  let countError = null;
   try {
     totalCount = await app.sdk.aggregateCount(table, query || '');
-  } catch {
-    totalCount = 0;
+  } catch (err) {
+    countError = err;
+  }
+  if (totalCount === 0) return null; // measured empty
+
+  if (countError) {
+    try {
+      const probeParams = new URLSearchParams();
+      probeParams.set('sysparm_limit', '1');
+      probeParams.set('sysparm_display_value', 'all');
+      probeParams.set('sysparm_fields', 'sys_id');
+      if (query) probeParams.set('sysparm_query', query);
+      const probe = await app.sdk.list(table, probeParams);
+      if (!Array.isArray(probe)) throw new Error('list returned a non-array result');
+      if (probe.length === 0) return null; // the list itself confirms empty
+    } catch (err) {
+      // Both the count and the list failed — surface the failure instead of
+      // reporting an empty result nobody measured.
+      throw new Error(
+        `Could not list ${table}: ${err.message || err} (aggregate count also failed: ${countError.message || countError})`,
+        { cause: err }
+      );
+    }
   }
-  if (totalCount === 0) return null;
 
   // Paginated source adapter: (term, offset, { signal }) => choices[]
   async function serverSource(term, offset, { signal: _signal } = {}) {
@@ -418,7 +516,9 @@ export function parseDataArg(argv) {
   try {
     return JSON.parse(raw);
   } catch (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 });
+    // Never echo the raw payload: real --data bodies carry personal data and
+    // secrets, and the parse position from e.message is enough to debug.
+    throw new Error(`Invalid JSON: ${e.message}\n\nHint: Use --data-file for multiline payloads to avoid shell escaping issues.`, { cause: e });
   }
 }
 

package/src/output.js

@@ -1,6 +1,7 @@
 // Output formatting: JSON, Markdown, Styled, Quiet
 
 import process from 'node:process';
+import { errExtractionNotFound } from './errors.js';
 
 export const FormatAuto = 'auto';
 export const FormatJSON = 'json';
@@ -125,9 +126,15 @@ export class OutputWriter {
     // --get extractor: resolve against the JSON envelope and print just that
     // value as JSON. Takes precedence over styling/table formats — a path
     // extract is inherently scriptable, not presentational.
+    //
+    // A path that does not resolve is an error, not a value. Stringifying
+    // `undefined` printed the literal token `undefined` and exited 0, so a
+    // typo looked like a successful empty result until the next tool in the
+    // pipeline failed to parse it. Present null/false/0/"" still print as-is.
     if (this.jqFilter) {
       const envelope = { ok: true, data, summary: opts.summary || '', breadcrumbs: opts.breadcrumbs || [] };
       const value = resolvePath(envelope, this.jqFilter);
+      if (value === undefined) throw errExtractionNotFound(this.jqFilter);
       this.writer.write(JSON.stringify(value, null, 2) + '\n');
       return;
     }