@jacebenson/jsn 4.3.7 → 4.3.8

package/src/commands/perf.js

@@ -1,14 +1,22 @@
 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,
@@ -77,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) }, {
@@ -99,22 +107,41 @@ 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)],
           });
         }),
       })
+      .command({
+        command: 'transactions [subcommand]',
+        describe: 'Inspect Client Transaction Timings',
+        builder: (b) => b.command(topTransactionsCmd(wrap)),
+      })
       .command({
         command: 'compare [baseline] [new]',
         describe: 'Compare exactly two saved captures',
         handler: wrap(async (argv, app) => {
           if (!argv.baseline && !argv.new) {
-            const baseline = await pickRun(app, { message: 'Select the baseline capture' });
+            if (!pickerEnabled(app, argv)) {
+              throw errUsageHint(
+                'Compare requires exactly two run IDs when prompts are unavailable.',
+                'Run `jsn perf compare <baseline> <new>` with two run IDs from `jsn perf list`.'
+              );
+            }
+            const baseline = await pickRun(app, { message: 'Select the baseline capture', argv });
             if (!baseline) return;
-            const newer = await pickRun(app, { exclude: new Set([baseline.run_id]), message: 'Select the new capture' });
+            const newer = await pickRun(app, { exclude: new Set([baseline.run_id]), message: 'Select the new capture', argv });
             if (!newer) return;
             const baselineRun = getRun(baseline.run_id);
             const newerRun = getRun(newer.run_id);

package/src/commands/platform.js

@@ -1,3 +1,6 @@
+import { declareCapabilities } from '../capabilities.js';
+import { formatCommandList } from '../helpers.js';
+
 function numberOrString(value) {
   const n = Number(value);
   return value !== '' && Number.isFinite(n) ? n : value;
@@ -24,6 +27,179 @@ function statsForWindow(xml, parent, window) {
   return tagAttributes(parentMatch[1], window);
 }
 
+export const XMLSTATS_MAX_BYTES = 4 * 1024 * 1024;
+
+function metric(value) {
+  if (value === undefined || value === null || String(value).trim() === '') {
+    return { value: null, availability: 'unavailable' };
+  }
+  return { value: numberOrString(String(value).trim()), availability: 'available' };
+}
+
+function firstNestedText(xml, parent, child) {
+  const parentMatch = xml.match(new RegExp(`<${parent}\\b[^>]*>([\\s\\S]*?)</${parent}>`));
+  return parentMatch ? tagText(parentMatch[1], child) : undefined;
+}
+
+function allowlistedStats(xml) {
+  const unavailable = [];
+  const add = (path, value) => {
+    const result = metric(value);
+    if (result.availability === 'unavailable') unavailable.push(path);
+    return result;
+  };
+
+  const cluster = xml.match(/<cluster\.status\b[^>]*>([\s\S]*?)<\/cluster\.status>/);
+  const nodeXml = cluster?.[1]?.match(/<node\b[^>]*>([\s\S]*?)<\/node>/)?.[1] || '';
+  const daily = statsForWindow(xml, 'all_transactions', 'daily') || {};
+  const semaphores = [];
+  for (const match of xml.matchAll(/<semaphores([^>]*)\/>/g)) {
+    const attrs = {};
+    for (const [, key, value] of match[1].matchAll(/([\w.-]+)="([^"]*)"/g)) attrs[key] = value;
+    if (!attrs.name && !attrs.available && !attrs.borrowed && !attrs.maximum_concurrency && !attrs.queue_depth) continue;
+    semaphores.push({
+      name: attrs.name || 'unnamed',
+      available: add(`semaphores[${attrs.name || 'unnamed'}].available`, attrs.available),
+      borrowed: add(`semaphores[${attrs.name || 'unnamed'}].borrowed`, attrs.borrowed),
+      maximum: add(`semaphores[${attrs.name || 'unnamed'}].maximum`, attrs.maximum_concurrency),
+      queue_depth: add(`semaphores[${attrs.name || 'unnamed'}].queue_depth`, attrs.queue_depth),
+    });
+  }
+  if (semaphores.length === 0) unavailable.push('semaphores');
+
+  return {
+    node: {
+      status: add('node.status', tagText(nodeXml, 'status')),
+      type: add('node.type', firstNestedText(nodeXml, 'node_type', 'name')),
+    },
+    queue: {
+      length: add('queue.length', tagText(xml, 'queue.length')),
+      age: add('queue.age', tagText(xml, 'queue.age')),
+    },
+    active_sessions: add('active_sessions', tagText(xml, 'servlet.active.sessions')),
+    memory_pressure: add('memory_pressure', tagText(xml, 'memory_pressure')),
+    semaphores,
+    transactions: {
+      daily: {
+        count: add('transactions.daily.count', daily.count),
+        mean: add('transactions.daily.mean', daily.mean),
+        median: add('transactions.daily.median', daily.median),
+        ninetypercent: add('transactions.daily.ninetypercent', daily.ninetypercent),
+        max: add('transactions.daily.max', daily.max),
+      },
+    },
+    unavailable,
+  };
+}
+
+export function parsePlatformStatsXml(xml) {
+  const source = String(xml || '');
+  if (Buffer.byteLength(source) > XMLSTATS_MAX_BYTES) throw new Error('xmlstats response exceeds the bounded size limit');
+  if (!/^\s*(?:<\?xml[\s\S]*?\?>\s*)?<xmlstats\b[^>]*>/i.test(source)
+    || !/<\/xmlstats>\s*$/i.test(source)) {
+    throw new Error('Malformed XML: expected an xmlstats document');
+  }
+  const stack = [];
+  for (const match of source.matchAll(/<\/?([A-Za-z][\w.:-]*)(?:\s[^>]*)?>/g)) {
+    const token = match[0];
+    const name = match[1];
+    if (/^<\//.test(token)) {
+      if (stack.pop() !== name) throw new Error('Malformed XML: mismatched tags');
+    } else if (!/\/\s*>$/.test(token)) {
+      stack.push(name);
+    }
+  }
+  if (stack.length !== 0) throw new Error('Malformed XML: unclosed tags');
+  return allowlistedStats(source);
+}
+
+async function readBoundedResponse(response, maxBytes = XMLSTATS_MAX_BYTES) {
+  if (!response.body?.getReader) {
+    const text = await response.text();
+    return Buffer.byteLength(text) > maxBytes ? { tooLarge: true, bytes: Buffer.byteLength(text) } : { text, bytes: Buffer.byteLength(text) };
+  }
+  const reader = response.body.getReader();
+  const chunks = [];
+  let bytes = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    bytes += value.byteLength;
+    if (bytes > maxBytes) {
+      await reader.cancel();
+      return { tooLarge: true, bytes };
+    }
+    chunks.push(value);
+  }
+  const body = new Uint8Array(bytes);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return { text: new TextDecoder().decode(body), bytes };
+}
+
+function looksLikeLoginHtml(response, body) {
+  const contentType = response.headers?.get?.('content-type') || '';
+  return /text\/html/i.test(contentType) || /^\s*<(?:!doctype\s+html|html\b)/i.test(body);
+}
+
+export async function collectPlatformStats(sdk, instance) {
+  let response;
+  try {
+    response = await sdk.fetchResponse(`${instance}/xmlstats.do`, {
+      method: 'GET',
+      headers: { Accept: 'application/xml,text/xml' },
+    });
+  } catch (error) {
+    const message = String(error?.message || '').toLowerCase();
+    return { status: /timeout|timed out/.test(message) ? 'timeout' : 'unavailable', reason: /timeout|timed out/.test(message) ? 'request timed out' : 'request failed' };
+  }
+
+  if (response.status === 401 || response.status === 403) return { status: 'permission_denied', reason: `HTTP ${response.status}` };
+  if (response.status === 404 || response.status === 405) return { status: 'unsupported', reason: `HTTP ${response.status}` };
+  if (!response.ok) return { status: 'unavailable', reason: `HTTP ${response.status}` };
+
+  const body = await readBoundedResponse(response);
+  if (body.tooLarge) return { status: 'too_large', reason: `response exceeded ${XMLSTATS_MAX_BYTES} bytes`, bytes: body.bytes };
+  if (looksLikeLoginHtml(response, body.text)) return { status: 'login_redirect', reason: 'received HTML instead of xmlstats XML', bytes: body.bytes };
+
+  try {
+    const metrics = parsePlatformStatsXml(body.text);
+    const status = metrics.unavailable.length > 0 ? 'partial' : 'success';
+    return {
+      status,
+      reason: status === 'partial' ? 'some allowlisted metrics were unavailable' : null,
+      bytes: body.bytes,
+      metrics,
+    };
+  } catch {
+    return { status: 'malformed_xml', reason: 'response was not a valid xmlstats document', bytes: body.bytes };
+  }
+}
+
+function metricText(item) {
+  return item?.availability === 'available' ? String(item.value) : 'unavailable';
+}
+
+export function formatPlatformStats(result) {
+  const lines = [`STATUS: ${result.status}`];
+  if (result.reason) lines.push(`REASON: ${result.reason}`);
+  const m = result.metrics;
+  if (!m) return `${lines.join('\\n')}\\n`;
+  lines.push(`NODE: ${metricText(m.node.status)} / ${metricText(m.node.type)}`);
+  lines.push(`QUEUE: ${metricText(m.queue.length)} length, ${metricText(m.queue.age)} age`);
+  lines.push(`SESSIONS: ${metricText(m.active_sessions)}`);
+  lines.push(`MEMORY PRESSURE: ${metricText(m.memory_pressure)}`);
+  lines.push(`TRANSACTIONS DAILY: ${metricText(m.transactions.daily.count)} count, ${metricText(m.transactions.daily.mean)} mean, ${metricText(m.transactions.daily.ninetypercent)} p90, ${metricText(m.transactions.daily.max)} max`);
+  if (m.semaphores.length === 0) lines.push('SEMAPHORES: unavailable');
+  else for (const semaphore of m.semaphores) {
+    lines.push(`SEMAPHORE ${semaphore.name}: ${metricText(semaphore.available)} available, ${metricText(semaphore.borrowed)} borrowed, ${metricText(semaphore.maximum)} maximum, ${metricText(semaphore.queue_depth)} queue`);
+  }
+  return `${lines.join('\\n')}\\n`;
+}
+
 export function parseNodeStatsXml(xml) {
   const source = String(xml || '');
   const result = {};
@@ -91,9 +267,26 @@ function formatHealth(nodes) {
 }
 
 export function platformCmd(wrap) {
+  declareCapabilities('platform', { mutationSubcommands: [] });
   return {
     command: 'platform',
     describe: 'Inspect read-only platform health and node statistics',
+    // Parent discovery. This parent had no handler, so `jsn platform` and
+    // `jsn platform --json` exited 0 with no output at all — silent success.
+    // Children come from the registry, not a second hand-written list.
+    handler: wrap(async (argv, app) => {
+      const subcommands = argv.subcommands || [];
+      const summary = 'Inspect read-only platform health and node statistics.';
+      app.ok({
+        command: 'platform',
+        subcommands,
+        _formatted: formatCommandList({
+          title: summary,
+          commands: subcommands,
+          footer: 'Run "jsn platform <command> --help" for details.',
+        }),
+      }, { summary });
+    }),
     builder: (y) => y.command({
       command: 'health',
       describe: 'Show cluster, queue, semaphore, and node health',
@@ -122,6 +315,15 @@ export function platformCmd(wrap) {
         }
         app.ok({ table: 'sys_cluster_state', node_count: nodes.length, nodes, _formatted: formatHealth(nodes), security: { raw_xml: 'excluded', sensitive_fields: 'excluded' }, context: { instance_url: app.getEffectiveInstance() } }, { summary: `Platform health: ${nodes.length} node(s)` });
       }),
+    }).command({
+      command: 'stats',
+      describe: 'Show bounded, read-only platform statistics from xmlstats.do',
+      handler: wrap(async (argv, app) => {
+        app.requireInstance();
+        const result = await collectPlatformStats(app.sdk, app.getEffectiveInstance());
+        result._formatted = formatPlatformStats(result);
+        app.ok(result, { summary: `Platform stats: ${result.status}` });
+      }),
     }),
   };
 }

package/src/commands/records.js

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

package/src/commands/skill.js

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

package/src/commands/transactions.js

@@ -39,6 +39,7 @@ export function classifyTransactionType(type, url = '') {
 }
 
 function numericValue(value) {
+  if (value == null || String(value).trim() === '') return null;
   const n = Number(String(value ?? '').replaceAll(',', ''));
   return Number.isFinite(n) ? n : null;
 }
@@ -65,6 +66,83 @@ function summarizeGroup(group) {
   };
 }
 
+function topQuery(argv = {}) {
+  const parts = [];
+  if (argv.query) parts.push(String(argv.query));
+  for (const field of ['type', 'table', 'view']) if (argv[field]) parts.push(`${field}=${argv[field]}`);
+  if (argv.window != null && String(argv.window) !== '') {
+    const days = Math.max(1, Math.min(30, Number(argv.window) || 1));
+    parts.push(`sys_created_on>=javascript:gs.daysAgoStart(${days})`);
+  }
+  if (argv.since) parts.push(`sys_created_on>=${argv.since}`);
+  if (argv.until) parts.push(`sys_created_on<=${argv.until}`);
+  return normalizeTransactionQuery(parts.join('^'));
+}
+
+function topGroup(group) {
+  const stats = group?.stats || {};
+  return {
+    type: groupValue(group, 'type') || 'unavailable',
+    table: groupValue(group, 'table') || 'unavailable',
+    view: groupValue(group, 'view') || 'unavailable',
+    count: numericValue(stats.count) ?? 0,
+    avg_response_time_ms: metricValue(stats, 'avg', 'response_time'),
+    min_response_time_ms: metricValue(stats, 'min', 'response_time'),
+    max_response_time_ms: metricValue(stats, 'max', 'response_time'),
+  };
+}
+
+function formatTopTransactions(groups) {
+  const value = metric => metric == null ? 'unavailable' : `${Math.round(metric * 100) / 100} ms`;
+  const lines = [
+    'TYPE         TABLE              VIEW             COUNT  AVG          MIN          MAX',
+    '-----------  -----------------  ---------------  -----  -----------  -----------  -----------',
+  ];
+  for (const row of groups) lines.push(`${String(row.type).slice(0, 11).padEnd(11)}  ${String(row.table).slice(0, 17).padEnd(17)}  ${String(row.view).slice(0, 15).padEnd(15)}  ${String(row.count).padStart(5)}  ${value(row.avg_response_time_ms).padEnd(11)}  ${value(row.min_response_time_ms).padEnd(11)}  ${value(row.max_response_time_ms)}`);
+  if (groups.length === 0) lines.push('(no transaction groups)');
+  return `${lines.join('\\n')}\\n`;
+}
+
+export function topTransactionsCmd(wrap) {
+  return {
+    command: 'top',
+    describe: 'Rank Client Transaction Timings by type, table, and view',
+    builder: (y) => y
+      .option('type', { type: 'string', describe: 'Filter transaction type' })
+      .option('table', { type: 'string', describe: 'Filter transaction table' })
+      .option('view', { type: 'string', describe: 'Filter transaction view' })
+      .option('query', { type: 'string', describe: 'Additional encoded query' })
+      .option('window', { type: 'number', default: 1, describe: 'Look back this many days (max 30)' })
+      .option('since', { type: 'string', describe: 'Only records on or after this timestamp' })
+      .option('until', { type: 'string', describe: 'Only records on or before this timestamp' })
+      .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Maximum groups to return' }),
+    handler: wrap(async (argv, app) => {
+      app.requireInstance();
+      const query = topQuery(argv);
+      const limit = Math.max(1, Math.min(100, Number(argv.limit) || 20));
+      const result = await app.sdk.aggregate('syslog_transaction', {
+        query,
+        groupBy: ['type', 'table', 'view'],
+        count: true,
+        averageFields: ['response_time'],
+        minimumFields: ['response_time'],
+        maximumFields: ['response_time'],
+        orderBy: 'countDESC',
+      });
+      const groups = (Array.isArray(result.groups) ? result.groups : []).map(topGroup).slice(0, limit);
+      app.ok({
+        table: 'syslog_transaction',
+        query,
+        group_by: ['type', 'table', 'view'],
+        response_time_unit: 'ms',
+        groups,
+        _formatted: formatTopTransactions(groups),
+        context: { instance_url: app.getEffectiveInstance() },
+      }, { summary: `Top transaction groups: ${groups.length}` });
+    }),
+  };
+}
+
 export function transactionsCmd(wrap) {
   return {
     command: 'transactions',

package/src/errors.js

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