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

package/package.json

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