@jacebenson/jsn 4.3.7-dev.41 → 4.3.7-dev.44

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.7-dev.41",
+  "version": "4.3.7-dev.44",
   "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

@@ -10,7 +10,11 @@ class CommandNode {
   constructor(definition) {
     this.definition = typeof definition === 'string' ? { command: definition } : definition;
     this.name = commandName(this.definition.command || '');
-    this.aliases = names(this.definition.aliases || this.definition.alias);
+    // A command that lists its canonical name as its own alias publishes one
+    // token twice: the registry then has two entries for it and dispatch can
+    // resolve it through the alias table instead of the command table. An alias
+    // is an ALTERNATE name, so a self-alias is dropped at the source.
+    this.aliases = names(this.definition.aliases || this.definition.alias).filter((alias) => alias !== this.name);
     this.children = [];
     this.options = new Map();
     this.positionals = new Map();
@@ -37,16 +41,34 @@ class CommandNode {
    * 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.
+   *
+   * A token must resolve to exactly ONE command. Two registrations can also
+   * collide without sharing a canonical name: an alias that another command
+   * already published (or already claims as its alias) is the same kind of
+   * claim, and registration order decides it — the later registration owns the
+   * token and the earlier one stops advertising it. The earlier command keeps
+   * its canonical name, so nothing becomes unreachable.
    */
   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) {
+      for (const sibling of this.children) {
+        sibling.aliases = sibling.aliases.filter((alias) => !child.aliases.includes(alias));
+      }
       this.children.push(child);
       return child;
     }
-    child.aliases = [...new Set([...child.aliases, ...this.children[index].aliases])];
+    // Carry the replaced node's aliases over — minus any alias that is now the
+    // replacement's own canonical name, which would advertise the command as
+    // its own alias.
+    child.aliases = [...new Set([...child.aliases, ...this.children[index].aliases])]
+      .filter((alias) => alias !== child.name);
+    for (const sibling of this.children) {
+      if (sibling === this.children[index]) continue;
+      sibling.aliases = sibling.aliases.filter((alias) => !child.aliases.includes(alias));
+    }
     this.children[index] = child;
     return child;
   }
@@ -157,14 +179,22 @@ export class LocalCLI {
     return options.get(key) || [...options.values()].find((spec) => spec.name === key || names(spec.alias).includes(key))
       || { name: key, type: typeof value === 'boolean' ? 'boolean' : 'string' };
   }
-  _assign(argv, key, value, spec) {
+  /**
+   * Assign one parsed value to argv.
+   *
+   * `validate: false` (tolerant mode, used by parseGlobalOptions) skips the
+   * choice/number checks so a value that will be thrown away anyway cannot
+   * abort a parse whose only purpose is reading the global output flags.
+   */
+  _assign(argv, key, value, spec, opts = {}) {
+    const validate = opts.validate !== false;
     const actual = spec?.name || key;
     const values = spec?.type === 'array' ? (Array.isArray(value) ? value : [value]) : [value];
-    if (spec?.choices && values.some((item) => !spec.choices.includes(item))) {
+    if (validate && spec?.choices && values.some((item) => !spec.choices.includes(item))) {
       this._fail(`Invalid value for --${actual}: ${value}. Choose from: ${spec.choices.join(', ')}`);
       return false;
     }
-    if (spec?.type === 'number' && values.some((item) => item === '' || !Number.isFinite(Number(item)))) {
+    if (validate && spec?.type === 'number' && values.some((item) => item === '' || !Number.isFinite(Number(item)))) {
       this._fail(`Invalid number for --${actual}: ${value}`);
       return false;
     }
@@ -176,7 +206,7 @@ export class LocalCLI {
     argv[camel(actual)] = argv[actual];
     for (const alias of names(spec?.alias)) argv[alias] = argv[actual];
   }
-  _parseOptions(args, path) {
+  _parseOptions(args, path, opts = {}) {
     const options = this._optionConfig(path);
     const defs = {};
     for (const [key, spec] of options) defs[key] = {
@@ -199,11 +229,40 @@ export class LocalCLI {
     const argv = { _: path.map((n) => n.name) };
     for (const [key, value] of Object.entries(parsed.values)) {
       const spec = this._specFor(options, key, value);
-      if (this._assign(argv, key, value, spec) === false) return null;
+      if (this._assign(argv, key, value, spec, opts) === false) return null;
     }
-    for (const [key, spec] of options) if (argv[spec.name] === undefined && spec.default !== undefined) this._assign(argv, key, spec.default, spec);
+    for (const [key, spec] of options) if (argv[spec.name] === undefined && spec.default !== undefined) this._assign(argv, key, spec.default, spec, opts);
     return { values: argv, positionals: parsed.positionals };
   }
+
+  /**
+   * Resolve the global options from raw tokens WITHOUT dispatching a command and
+   * without failing.
+   *
+   * The format middleware never runs when parsing fails, so the parse-time
+   * failure renderer has to know the format the caller asked for. Rather than
+   * re-scanning argv with a second, approximate tokenizer (any `--json`
+   * anywhere, first `--format` wins, no option termination, no value
+   * consumption, no `--no-` negation), it asks the SAME parser the successful
+   * path uses. Tolerant mode keeps a value error (`--format xml`, the very
+   * failure being rendered) from aborting the resolution.
+   *
+   * Returns null when the tokens cannot be parsed at all — the caller then
+   * falls back to the pipe/TTY default, exactly as it did before.
+   */
+  parseGlobalOptions(args) {
+    const saved = this.failHandler;
+    this.failHandler = null; // errors here are not the failure being reported
+    try {
+      const { path, commandArgs } = this._findPath(args);
+      const parsed = this._parseOptions(commandArgs, path, { validate: false });
+      return parsed ? parsed.values : null;
+    } catch {
+      return null;
+    } finally {
+      this.failHandler = saved;
+    }
+  }
   _fail(message, error) {
     if (this.failHandler) return this.failHandler(message, error);
     throw error || new Error(message);

package/src/cli.js

@@ -75,43 +75,28 @@ import { diffCmd } from './commands/diff.js';
 import { graphqlCmd } from './commands/graphql.js';
 
 /**
- * Did the caller explicitly ask for machine output?
+ * The output format the caller asked for, resolved from PARSED argv.
  *
- * 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.
+ * One policy, two callers: the format middleware applies it once a command
+ * parses, and the parse-time failure handler applies it when parsing fails.
+ * They used to disagree — the failure path re-scanned the raw tokens (any
+ * `--json` anywhere, first `--format` match, no option termination, no values
+ * consumed by string options, no `--no-` negation), so the stream and the shape
+ * of a failure depended on which layer rejected the command instead of on the
+ * command line the caller typed.
  *
- * 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.
+ * Precedence is the middleware's, unchanged: the shortcut flags beat `--format`,
+ * and among the shortcuts the one applied last wins
+ * (csv > markdown > styled > quiet > json).
  */
-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 '';
+export function resolveRequestedFormat(argv) {
+  if (!argv) return '';
+  if (argv.csv) return 'csv';
+  if (argv.markdown) return 'markdown';
+  if (argv.styled) return 'styled';
+  if (argv.quiet) return 'quiet';
+  if (argv.json) return 'json';
+  return typeof argv.format === 'string' ? argv.format : '';
 }
 
 /**
@@ -199,15 +184,14 @@ export function buildCLI() {
       },
     })
     .middleware([
-      // Apply format option overrides
+      // Apply format option overrides. The resolution lives in
+      // resolveRequestedFormat so the parse-time failure path applies the
+      // identical policy instead of approximating it from raw tokens.
       (argv) => {
-        if (argv.json) argv.format = 'json';
-        if (argv.quiet) argv.format = 'quiet';
-        if (argv.styled) argv.format = 'styled';
-        if (argv.markdown) argv.format = 'markdown';
-        if (argv.csv) argv.format = 'csv';
-        if (argv.format) {
-          app.output.setFormat(argv.format);
+        const requested = resolveRequestedFormat(argv);
+        if (requested) {
+          argv.format = requested;
+          app.output.setFormat(requested);
         }
         if (argv.get) {
           app.output.setJqFilter(argv.get);
@@ -485,22 +469,30 @@ export function buildCLI() {
     })
     .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.
+      // its own (records attachments, docs community, 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 });
+      // Same error boundary as every registered handler (AGENTS.md: handlers go
+      // through wrap()). Discovery runs outside any command handler, and the
+      // shared extractor throws on a `--get` path that does not resolve — an
+      // unwrapped callback rejected parse() into an entry point with no
+      // rejection handler, so a missing path printed a Node stack instead of the
+      // extraction_not_found envelope.
+      return wrap(async () => {
+        (argv.app || app).ok({
+          command: canonical,
+          subcommands,
+          _formatted: formatCommandList({
+            title: `jsn ${canonical}`,
+            commands: subcommands,
+            footer: `Run "jsn ${canonical} <command> --help" for details.`,
+          }),
+        }, { summary });
+      })(argv);
     })
     .help('help', 'Show help')
     .version(false)
@@ -509,6 +501,13 @@ export function buildCLI() {
     .fail((msg, err) => {
       if (err) throw err;
       const raw = process.argv.slice(2);
+      // A parse-time failure never reaches the format middleware, so resolve the
+      // requested format with the adapter's OWN tokenizer (same option specs,
+      // option termination, consumed values, repeated options, `--no-`
+      // negation) instead of re-scanning raw argv — one policy, one answer for
+      // this command line no matter which layer rejects it.
+      const formatArgv = cliInstance.parseGlobalOptions(raw);
+      const requestedFormat = resolveRequestedFormat(formatArgv);
       if (msg === 'You must specify a command') {
         const hasLoneProfile = raw.some((a, i, arr) => {
           if (a !== '--profile' && a !== '-p') return false;
@@ -529,12 +528,23 @@ export function buildCLI() {
         // 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)) {
+        if (requestedFormat === 'json') {
           app.output.setFormat('json');
+          // `--get` is jsn's jq substitute for every JSON shape (AGENTS.md), so
+          // the root discovery envelope honours it too: extract when the path
+          // resolves, and fail with the structured envelope when it does not,
+          // instead of always dumping the whole envelope.
+          if (typeof formatArgv?.get === 'string' && formatArgv.get) {
+            app.output.setJqFilter(formatArgv.get);
+          }
           const { commands } = cliInstance.commandRegistry();
-          app.ok({ commands }, {
-            summary: `${commands.length} registered commands — run "jsn <command> --json" for a command's subcommands.`,
-          });
+          try {
+            app.ok({ commands }, {
+              summary: `${commands.length} registered commands — run "jsn <command> --json" for a command's subcommands.`,
+            });
+          } catch (discoveryError) {
+            exitWithError(discoveryError, { app });
+          }
           process.exit(0);
         }
         process.stdout.write(renderHelp(loadConfig(), cliInstance.commandRegistry()) + '\n');
@@ -546,11 +556,7 @@ export function buildCLI() {
       // 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);
-      }
+      if (requestedFormat) app.output.setFormat(requestedFormat);
       let hint;
       try {
         const path = cliInstance._findPath(raw).path.map((n) => n.name).join(' ');

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/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/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

@@ -140,14 +140,27 @@ export function errExtractionNotFound(path) {
 /**
  * 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
   );
 }
 

package/src/flow-create.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { assertSafeExactMatch } from './helpers.js';
 import { createVerifiedFlowVersion } from './flow-versioning.js';
 import {
+  RECORD_TRIGGER_FAMILY,
   SUPPORTED_TRIGGER_TYPES,
   TRIGGER_DEFINITION_TABLE,
   buildTriggerInputs,
@@ -11,6 +12,7 @@ import {
   readTriggerInputDefinitions,
   tableInputFor,
   flowDesignParameter,
+  triggerFamily,
 } from './flow-triggers.js';
 
 const FLOW_ENDPOINT = '/api/now/processflow/flow';
@@ -264,7 +266,11 @@ export function buildTypedInputs(action, schema) {
       throw new Error(`Action ${action.type} input "${field.name}" has a malformed parameter block; refusing to change it`);
     }
     const suppliedValue = Object.prototype.hasOwnProperty.call(supplied, field.name) ? supplied[field.name] : field.default;
-    if ((suppliedValue === undefined || suppliedValue === null) && (field.mandatory === true || field.required === true)) throw new Error(`Missing required input "${field.name}" for action ${action.type}`);
+    const parameter = field.parameter || {};
+    if ((suppliedValue === undefined || suppliedValue === null)
+      && (field.mandatory === true || field.required === true || parameter.mandatory === true || parameter.required === true)) {
+      throw new Error(`Missing required input "${field.name}" for action ${action.type}`);
+    }
     const value = suppliedValue ?? null;
     const displayValue = field.displayValue ?? field.display_value ?? value;
     // global_snFlowDesigner_ActionInstanceValue accepts ONLY these keys. The
@@ -277,13 +283,29 @@ export function buildTypedInputs(action, schema) {
       children: Array.isArray(field.children) ? field.children : [],
       displayField: stringValue(field.displayField || field.display_field || ''),
       scriptActive: false,
-      parameter: flowDesignParameter(field),
+      parameter: actionInputParameter(field),
       value: { schemaless: false, schemalessValue: '', value },
       displayValue: { schemaless: false, schemalessValue: '', value: displayValue },
     };
   });
 }
 
+// Providers hand back the input metadata in one of two shapes: nested inside a
+// `parameter` block (the earlier contract) or FLAT on the input object (the real
+// published Log action's action_types route). The nested block wins when it
+// exists, flat keys fill in only what it leaves empty, and the result is always
+// narrowed to the fields global_snFlowDesigner_FlowDesignParameter accepts.
+export function actionInputParameter(field) {
+  if (field?.parameter === undefined) return flowDesignParameter(field);
+  const parameter = flowDesignParameter(field.parameter);
+  const flat = flowDesignParameter(field);
+  for (const key of Object.keys(flat)) {
+    if (flat[key] === undefined || flat[key] === '') continue;
+    if (parameter[key] === undefined || parameter[key] === '') parameter[key] = flat[key];
+  }
+  return parameter;
+}
+
 function parseSimpleCondition(condition) {
   if (!condition) return null;
   const match = condition.match(/^([A-Za-z_][A-Za-z0-9_.]*)(STARTSWITH|ENDSWITH|LIKE|NOT LIKE|=|!=|IN|ISEMPTY|ISNOTEMPTY)([^,^]*)$/);
@@ -552,8 +574,8 @@ function updatedTrigger(flow, manifest, descriptor) {
   if (!existing) throw new Error('Saved flow has no trigger instance');
   const existingMetadata = parseMaybeJson(existing.metadata, null);
   if (existing.metadata && (!existingMetadata || typeof existingMetadata !== 'object' || Array.isArray(existingMetadata))) throw new Error('Saved record trigger metadata is unreadable; refusing to replace it');
-  const existingType = stringValue(existing.triggerType || existing.trigger_type || existingMetadata?.triggerType || existingMetadata?.trigger_type);
-  if (existingType && existingType !== 'record_create_or_update') throw new Error(`Only record_create_or_update trigger updates are supported; found ${existingType}`);
+  const existingFamily = triggerFamily(existing);
+  if (existingFamily && existingFamily !== RECORD_TRIGGER_FAMILY) throw new Error(`Only ${RECORD_TRIGGER_FAMILY} trigger updates are supported; found ${existingFamily}`);
   const inputs = clone(inputList(existing));
   const tableInput = inputs.find(input => input.name === 'table');
   const conditionInput = inputs.find(input => input.name === 'condition');

package/src/flow-inspection.js

@@ -298,11 +298,7 @@ function buildLabelCache(payload) {
   if (!payload || typeof payload !== 'object') return cache;
   let entries = payload.label_cache;
   if (!Array.isArray(entries)) {
-    try {
-      entries = JSON.parse(payload.labelCacheAsJsonString || '[]');
-    } catch {
-      entries = [];
-    }
+    entries = parseLabelCacheJson(payload.labelCacheAsJsonString);
   }
   for (const e of entries) {
     if (!e || typeof e !== 'object') continue;
@@ -313,6 +309,20 @@ function buildLabelCache(payload) {
   return cache;
 }
 
+// labelCacheAsJsonString is a JSON document, and JSON `null` or `{}` parses
+// successfully into something that is not iterable — that threw
+// "entries is not iterable" and broke `flows show` on real drafts whose cache is
+// empty. An empty cache simply has no labels.
+function parseLabelCacheJson(value) {
+  if (typeof value !== 'string' || !value.trim()) return [];
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
 const GUID_PILL_RE = /\{\{([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.([^}]+)\}\}/g;
 
 /**

package/src/flow-test.js

@@ -1,4 +1,5 @@
 import { assertSafeExactMatch } from './helpers.js';
+import { RECORD_TRIGGER_FAMILY, triggerFamily } from './flow-triggers.js';
 
 const FLOW_ENDPOINT = '/api/now/processflow/flow';
 
@@ -30,15 +31,14 @@ function inputValue(trigger, name) {
   return valueOf(input?.value ?? input?.displayValue);
 }
 
-function triggerType(trigger) {
-  return valueOf(trigger?.triggerType || trigger?.trigger_type || trigger?.type);
-}
-
 export function deriveRecordTrigger(definition) {
   const trigger = findTrigger(definition);
   if (!trigger) throw new Error('Flow definition has no trigger instance');
-  const type = triggerType(trigger);
-  if (type !== 'record_create_or_update') throw new Error(`Flow test supports only record_create_or_update triggers; found ${type || 'unknown'}`);
+  // `type` is the family; `triggerType` is only the picker category ("Record").
+  // triggerFamily keeps a deliberate legacy fallback for saved instances that
+  // predate the split.
+  const type = triggerFamily(trigger);
+  if (type !== RECORD_TRIGGER_FAMILY) throw new Error(`Flow test supports only ${RECORD_TRIGGER_FAMILY} triggers; found ${type || 'unknown'}`);
   const table = inputValue(trigger, 'table');
   if (!table) throw new Error('Flow definition record trigger has no table');
   return { trigger, type, table };

package/src/flow-triggers.js

@@ -358,6 +358,59 @@ export function buildTriggerInstance({ flowId, definition, triggerType = '', inp
   };
 }
 
+export const RECORD_TRIGGER_FAMILY = 'record_create_or_update';
+
+// A trigger instance carries the FAMILY and the picker CATEGORY in two different
+// fields: `type` is the family Flow Designer executes ("record_create_or_update",
+// "daily", …) and `triggerType` is the category display name ("Record",
+// "Scheduled", …). Creation writes the family to `type` (resolveTriggerDefinition
+// reads it from sys_hub_trigger_definition), and the live ProcessFlow read-back
+// returns exactly that shape, so `type` is authoritative.
+//
+// Instances and fixtures that predate that split stored the family in
+// `triggerType` (and sometimes inside the raw metadata block), so those stay as
+// deliberate fallbacks — otherwise a real saved trigger reads as the category
+// "Record" and every consumer rejects it.
+export function triggerFamily(source) {
+  const metadata = parsedObject(source?.metadata);
+  const candidates = [
+    source?.type,
+    source?.trigger_type,
+    metadata?.type,
+    metadata?.trigger_type,
+    source?.triggerType,
+    metadata?.triggerType,
+  ];
+  for (const candidate of candidates) {
+    const family = familyValue(candidate);
+    if (family) return family;
+  }
+  return '';
+}
+
+function parsedObject(value) {
+  if (value && typeof value === 'object' && !Array.isArray(value)) return value;
+  if (typeof value !== 'string' || !value.trim()) return null;
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function familyValue(value) {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'object') {
+    for (const key of ['value', 'display_value', 'sys_id']) {
+      const nested = familyValue(value[key]);
+      if (nested) return nested;
+    }
+    return '';
+  }
+  return String(value).trim();
+}
+
 // The snFlowDesigner GraphQL input types take `attributes` as a String
 // ("key=value,key=value") even though the ProcessFlow read path renders it as an
 // object. Sending the object fails validation: "not a valid 'String'".

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 });
   }
 }