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

package/package.json

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