@jacebenson/jsn 4.0.4 → 4.2.0

package/src/commands/users.js

@@ -1,4 +1,8 @@
-import { formatRecordForDisplay, getStringField, interactiveList, resolveFieldsParam, assertSafeExactMatch } from '../helpers.js';
+import { formatRecordForDisplay, getStringField, interactiveList, resolveFieldsParam } from '../helpers.js';
+import { resolveRecord, resolveSysId } from '../resolve-record.js';
+import { declareCapabilities } from '../capabilities.js';
+
+declareCapabilities('users', { mutationSubcommands: ['create', 'update', 'delete'] });
 
 export function usersCmd(wrap) {
   return {
@@ -57,17 +61,8 @@ export function usersCmd(wrap) {
           describe: 'Show a user by user_name or sys_id',
           handler: wrap(async (argv, app) => {
             const id = argv.identifier;
-            assertSafeExactMatch(id);
-            const isSysID = id.length === 32 && /^[0-9a-fA-F]+$/.test(id);
-            const params = new URLSearchParams();
-            params.set('sysparm_query', isSysID ? `sys_id=${id}` : `user_name=${id}`);
-            params.set('sysparm_limit', '1');
-            params.set('sysparm_display_value', 'all');
-            const records = await app.sdk.list('sys_user', params);
-            if (records.length === 0) {
-              throw new Error(`User not found: ${id}`);
-            }
-            app.ok(records[0], { summary: `User ${id}` });
+            const record = await resolveRecord(app.sdk, { table: 'sys_user', identifier: id, matchField: 'user_name', resource: 'User' });
+            app.ok(record, { summary: `User ${id}` });
           }),
         })
         .command({
@@ -105,19 +100,8 @@ export function usersCmd(wrap) {
             .option('data', { type: 'string', demandOption: true, describe: 'JSON data to update' }),
           handler: wrap(async (argv, app) => {
             const id = argv.identifier;
-            assertSafeExactMatch(id);
             const recordData = JSON.parse(argv.data);
-            const isSysID = id.length === 32 && /^[0-9a-fA-F]+$/.test(id);
-            const params = new URLSearchParams();
-            params.set('sysparm_query', isSysID ? `sys_id=${id}` : `user_name=${id}`);
-            params.set('sysparm_limit', '1');
-            params.set('sysparm_display_value', 'all');
-            params.set('sysparm_fields', 'sys_id');
-            const records = await app.sdk.list('sys_user', params);
-            if (records.length === 0) {
-              throw new Error(`User not found: ${id}`);
-            }
-            const sysID = getStringField(records[0], 'sys_id');
+            const sysID = await resolveSysId(app.sdk, { table: 'sys_user', identifier: id, matchField: 'user_name', resource: 'User' });
             const updated = await app.sdk.update('sys_user', sysID, recordData);
             app.ok(updated, {
               summary: `Updated user ${id}`,
@@ -132,17 +116,7 @@ export function usersCmd(wrap) {
           describe: 'Delete a user by user_name or sys_id',
           handler: wrap(async (argv, app) => {
             const id = argv.identifier;
-            assertSafeExactMatch(id);
-            const isSysID = id.length === 32 && /^[0-9a-fA-F]+$/.test(id);
-            const params = new URLSearchParams();
-            params.set('sysparm_query', isSysID ? `sys_id=${id}` : `user_name=${id}`);
-            params.set('sysparm_limit', '1');
-            params.set('sysparm_fields', 'sys_id');
-            const records = await app.sdk.list('sys_user', params);
-            if (records.length === 0) {
-              throw new Error(`User not found: ${id}`);
-            }
-            const sysID = getStringField(records[0], 'sys_id');
+            const sysID = await resolveSysId(app.sdk, { table: 'sys_user', identifier: id, matchField: 'user_name', resource: 'User' });
             await app.sdk.delete('sys_user', sysID);
             app.ok({ identifier: id, message: 'User deleted' }, {
               summary: `Deleted user ${id}`,

package/src/commands/version.js

@@ -1,6 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { declareCapabilities } from '../capabilities.js';
+
+declareCapabilities('version', { noInstance: true, skipDailyChecks: true });
 
 const NPM_PKG = '@jacebenson/jsn';
 const NPM_REGISTRY = `https://registry.npmjs.org/${NPM_PKG}/latest`;

package/src/errors.js

@@ -9,6 +9,7 @@ export const CodeNetwork = 'network_error';
 export const CodeAPI = 'api_error';
 export const CodeAmbiguous = 'ambiguous';
 export const CodeEmptyResult = 'empty_result';
+export const CodeConfirmationRequired = 'confirmation_required';
 
 export class AppError extends Error {
   constructor(code, message, hint = '', status = 0, cause = null) {
@@ -117,6 +118,20 @@ export function errAmbiguous(resource, matches) {
   );
 }
 
+/**
+ * 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.
+ */
+export function errConfirmationRequired(question, rerunCmd) {
+  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`
+  );
+}
+
 export function asError(err) {
   if (!err) return null;
   if (err instanceof AppError) return err;
@@ -127,15 +142,106 @@ export function isErrorCode(err, code) {
   return err instanceof AppError && err.code === code;
 }
 
+/**
+ * ── Unified error renderer ─────────────────────────────────────────────
+ * ONE place owns AppError → (stream, text, exit code). wrap()'s catch
+ * block, the middleware guard (guardError/guardExit), and any future
+ * entry point all route through renderAppError so the rendering can't
+ * diverge again (it had: wrap checked app.output.effectiveFormat() while
+ * guardError checked argv.format; 'usage' vs 'usage_error' disagreed).
+ *
+ * Exit-code contract (observable behavior, pinned by tests):
+ *   not_found              → 1   stderr, "Error (not_found): …" + identifier hint
+ *   usage / usage_error    → 2   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: …"
+ *
+ * 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).
+ */
+function resolveJsonMode(app, argv) {
+  if (app?.output) return app.output.effectiveFormat() === 'json';
+  return argv?.format === 'json';
+}
+
+/**
+ * Render an error for the terminal/pipe.
+ *
+ * @param {object} err — Error with optional .code and .hint
+ * @param {object} [opts]
+ * @param {object} [opts.app] — App instance (format resolution, JSON envelope)
+ * @param {object} [opts.argv] — yargs argv (fallback format resolution)
+ * @param {string} [opts.identifier] — for not_found: the id that missed
+ * @returns {{ stream: 'stdout'|'stderr', text: string|null, exitCode: number, appErr?: boolean }}
+ *   text is null when the error was rendered through app.err (envelope).
+ */
+export function renderAppError(err, { app = null, argv = null, identifier = '' } = {}) {
+  const code = err.code || 'unknown';
+
+  if (code === CodeConfirmationRequired) {
+    // Structured error for AI agents / piped consumers: the JSON envelope
+    // goes to stdout (where tooling reads) so the agent can surface the
+    // decision to its user or re-run with --force.
+    if (resolveJsonMode(app, argv) && app) {
+      return { stream: 'stdout', text: null, exitCode: 1, appErr: true };
+    }
+    let text = `Error: ${err.message}\n`;
+    if (err.hint) text += `\n${err.hint}\n`;
+    return { stream: 'stderr', text, exitCode: 1 };
+  }
+
+  if (code === CodeNotFound) {
+    let text = `Error (${code}): ${err.message}\n`;
+    if (identifier) {
+      text += `\nHint: The identifier "${identifier}" was not found. Check the name or sys_id.\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 };
+  }
+
+  if (code === 'system_error') {
+    return { stream: 'stderr', text: `Error (system): ${err.message}\n`, exitCode: 3 };
+  }
+
+  return { stream: 'stderr', text: `Error: ${err.message}\n`, exitCode: 1 };
+}
+
+/**
+ * Write + exit for a rendered error. Shared by wrap() and guardExit().
+ */
+export function exitWithError(err, opts = {}) {
+  const { app = null } = opts;
+  const r = renderAppError(err, opts);
+  if (r.appErr && app) {
+    app.err(err);
+  } else if (r.stream === 'stdout') {
+    process.stdout.write(r.text);
+  } else {
+    process.stderr.write(r.text);
+  }
+  process.exit(r.exitCode);
+}
+
 /**
  * Format a safety-guard failure (mutation guard middleware in cli.js).
  * In JSON mode writes the documented error envelope to stdout so piped
  * consumers (`jsn ... --json | jq`) get a structured error instead of a
  * raw stderr message. Otherwise writes human text to stderr.
  * Always exits non-zero via guardExit.
+ *
+ * Routes through the same JSON-mode resolution as renderAppError
+ * (app.output.effectiveFormat() when an App is on argv, else argv.format).
  */
 export function guardError(argv, { code, message, hint = '' }) {
-  if (argv?.format === 'json') {
+  if (resolveJsonMode(argv?.app, argv)) {
     return {
       stream: 'stdout',
       text: JSON.stringify({ ok: false, error: message, code, hint }) + '\n',

package/src/help.js

@@ -115,6 +115,7 @@ const CONFIG_COMMANDS = [
 ];
 
 const DEVELOPER_COMMANDS = [
+  { name: 'atf', desc: 'Automated Test Framework (list, suites, run, results)' },
   { name: 'eval', desc: 'Run server-side JavaScript' },
   { name: 'rest', desc: 'Raw REST API calls' },
   { name: 'skill', desc: 'AI agent skill file (show, fetch, install)' },

package/src/helpers.js

@@ -5,6 +5,32 @@ import readline from 'node:readline';
 import { paginatedSearch } from './paginated-search.js';
 import { isTTY, FormatAuto } from './output.js';
 import { getActiveProfile } from './config.js';
+import { errConfirmationRequired } from './errors.js';
+
+/**
+ * Detect whether a human is actually available to answer interactive
+ * prompts. Agent tooling (VSCode Copilot, Claude Code, Cursor, etc.)
+ * allocates a PTY for subprocesses, so isTTY() returns true even though
+ * no one will ever type a response. Those environments set signals that
+ * let us fall back to non-interactive behavior instead of hanging:
+ *
+ *   - JSN_NO_PROMPTS=1        (explicit opt-out, documented for agents)
+ *   - CI / NONINTERACTIVE / GITHUB_ACTIONS
+ *   - CLAUDE_CODE / COPILOT_* / CURSOR_* agent markers
+ *   - TERM=dumb
+ *
+ * @returns {boolean} true when a human can answer a prompt
+ */
+export function canPrompt() {
+  if (process.env.JSN_NO_PROMPTS === '1') return false;
+  if (process.env.CI === 'true' || process.env.CI === '1') return false;
+  if (process.env.NONINTERACTIVE === 'true' || process.env.NONINTERACTIVE === '1') return false;
+  if (process.env.GITHUB_ACTIONS === 'true') return false;
+  if (process.env.TERM === 'dumb') return false;
+  const agentMarkers = ['CLAUDE_CODE', 'COPILOT_AGENT', 'VSCODE_AGENT', 'CURSOR_AGENT', 'CODEX_AGENT', 'GITHUB_COPILOT_AGENT'];
+  if (agentMarkers.some((m) => process.env[m] === 'true' || process.env[m] === '1')) return false;
+  return isTTY(process.stdout) && isTTY(process.stdin);
+}
 
 /**
  * Confirm a destructive action before executing.
@@ -25,7 +51,7 @@ export async function confirmDelete(app, argv, question) {
   const profile = getActiveProfile(app.config);
   if (profile?.skip_confirmations === true) return true;
   if (argv.force) return true;
-  if (isTTY(process.stdout) && isTTY(process.stdin)) {
+  if (canPrompt()) {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     const answer = await new Promise((resolve) => {
       rl.question(`${question} (y/N): `, resolve);
@@ -37,9 +63,10 @@ export async function confirmDelete(app, argv, question) {
     }
     return true;
   }
-  throw new Error(
-    `${question} — confirmation required. Pass --force to skip, or set skip_confirmations on the profile to disable prompts.`
-  );
+  // 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);
 }
 
 
@@ -55,6 +82,84 @@ export function getStringField(record, field) {
   return String(val);
 }
 
+/**
+ * Extract the raw value from a field that may be a string or a
+ * {display_value, value} object returned by the Table API.
+ * Prefers .value (the raw stored value) over .display_value.
+ */
+function getRawValue(val) {
+  if (val == null) return '';
+  if (typeof val === 'object') {
+    if (val.value != null) return String(val.value);
+    if (val.display_value != null) return String(val.display_value);
+    return '';
+  }
+  return String(val);
+}
+
+/**
+ * Normalize a value the user supplied in --data for comparison against
+ * what the API persisted. Objects like {"value": "<sys_id>"} are unwrapped.
+ */
+function normalizeSupplied(val) {
+  if (val == null) return '';
+  if (typeof val === 'object') {
+    if (val.value != null) return String(val.value);
+    return '';
+  }
+  return String(val);
+}
+
+/**
+ * Write-back verification for records create/update.
+ *
+ * After a mutation, re-GET the record and compare each field supplied in
+ * --data against what actually persisted. Surfaces silent server-side
+ * drops (inherited references, ACL-restricted fields, IO: prefixed strings,
+ * platform quirks) that ServiceNow ignores without erroring.
+ *
+ * Skips sys_* fields (system-managed, already warned by checkDerivedFields).
+ *
+ * @returns {Promise<Array<{field: string, sent: string, got: string}>>}
+ */
+export async function verifyWriteBack(app, table, sysID, sentData) {
+  const mismatches = [];
+  if (!sysID || !sentData || typeof sentData !== 'object') return mismatches;
+
+  const fields = Object.keys(sentData).filter(f => f !== 'sys_id' && !f.startsWith('sys_'));
+  if (fields.length === 0) return mismatches;
+
+  let persisted;
+  try {
+    const params = new URLSearchParams();
+    params.set('sysparm_query', `sys_id=${sysID}`);
+    params.set('sysparm_limit', '1');
+    params.set('sysparm_display_value', 'all');
+    params.set('sysparm_fields', ['sys_id', ...fields].join(','));
+    const records = await app.sdk.list(table, params);
+    persisted = records[0] || null;
+  } catch {
+    // Verification GET failed — don't fail the mutation, just report it.
+    mismatches.push({ field: '(verify)', sent: '', got: 'write-back check failed (GET error)' });
+    return mismatches;
+  }
+
+  if (!persisted) {
+    mismatches.push({ field: '(verify)', sent: '', got: 'record not found after write' });
+    return mismatches;
+  }
+
+  for (const field of fields) {
+    const sent = normalizeSupplied(sentData[field]);
+    const got = getRawValue(persisted[field]);
+    if (sent !== got) {
+      mismatches.push({ field, sent, got });
+    }
+  }
+
+  return mismatches;
+}
+
 export function formatRecordForDisplay(record, columns) {
   const result = {};
 
@@ -146,25 +251,36 @@ export function assertSafeExactMatch(value) {
  * @param {string} opts.singular — e.g. "script include", "log entry"
  * @param {string[]} opts.columns — default display columns
  * @param {number} opts.limit — max records (default 20)
- * @param {string} opts.query — optional encoded query
+ * @param {string} opts.query — optional encoded query, folded into every
+ *   request (browse pages, search-as-you-type, and the aggregate count)
  * @param {Function} opts.formatLabel — (record) => string for the picker display
  * @param {string} opts.labelField — field used to match selection (default: 'name')
- * @returns {Promise<void>|null} null if no selection made or non-interactive
+ * @param {string} [opts.message] — picker prompt message
+ *   (default: "Select a <singular>")
+ * @param {Function} [opts.formatValue] — (record) => value for the choice;
+ *   defaults to returning the full record on selection
+ * @param {Function} [opts.promptFn] — test seam: replaces paginatedSearch;
+ *   injecting it also bypasses the TTY/canPrompt gate (the test drives the
+ *   interactive path explicitly)
+ * @returns {Promise<*|null|undefined>} the selected record (or formatValue
+ *   result), undefined when the user cancelled, null when non-interactive
  */
-export async function interactiveList({ app, table, singular, columns, limit = 50, _query = '', formatLabel, labelField = 'name' }) {
+export async function interactiveList({ app, table, singular, columns, limit = 50, query = '', formatLabel, labelField = 'name', message, formatValue, promptFn }) {
+  const prompt = promptFn || paginatedSearch;
   app.requireInstance();
   const effectiveFormat = app.output.getFormat() === FormatAuto ? (isTTY(process.stdout) ? FormatAuto : FormatAuto) : app.output.getFormat();
-  if (effectiveFormat !== FormatAuto || !isTTY(process.stdout) || !isTTY(process.stdin)) {
+  if (!promptFn && (effectiveFormat !== FormatAuto || !canPrompt())) {
     return null; // not interactive — caller should fall back to text/table
   }
 
   const pickerColumns = ['sys_id', labelField, ...columns.filter(c => c !== labelField && c !== 'sys_id' && c !== '*')];
   const pickerFields = pickerColumns.join(',');
+  const baseQuery = query ? query + '^' : '';
 
   // Get total count
   let totalCount;
   try {
-    totalCount = await app.sdk.aggregateCount(table, '');
+    totalCount = await app.sdk.aggregateCount(table, query || '');
   } catch {
     totalCount = 0;
   }
@@ -178,9 +294,9 @@ export async function interactiveList({ app, table, singular, columns, limit = 5
       params.set('sysparm_display_value', 'all');
       if (pickerFields) params.set('sysparm_fields', pickerFields);
       if (term) {
-        params.set('sysparm_query', `${labelField}LIKE${term}^ORDERBYDESCsys_updated_on`);
+        params.set('sysparm_query', `${baseQuery}${labelField}LIKE${term}^ORDERBYDESCsys_updated_on`);
       } else {
-        params.set('sysparm_query', 'ORDERBYDESCsys_updated_on');
+        params.set('sysparm_query', baseQuery + 'ORDERBYDESCsys_updated_on');
         params.set('sysparm_offset', String(offset));
       }
       const records = await app.sdk.list(table, params);
@@ -190,7 +306,7 @@ export async function interactiveList({ app, table, singular, columns, limit = 5
       }
       return records.map(r => ({
         name: formatLabel ? formatLabel(r) : (getStringField(r, labelField) || getStringField(r, 'sys_id')),
-        value: r,
+        value: formatValue ? formatValue(r) : r,
       }));
     } catch (err) {
       console.error('serverSource error:', err.message || err);
@@ -198,14 +314,14 @@ export async function interactiveList({ app, table, singular, columns, limit = 5
     }
   }
 
-  const selected = await paginatedSearch({
-    message: `Select ${singular === 'flow' ? 'a flow' : `a ${singular}`}`,
+  const selected = await prompt({
+    message: message || `Select ${singular === 'flow' ? 'a flow' : `a ${singular}`}`,
     pageSize: 10,
     totalCount,
     source: serverSource,
   });
 
-  return selected?.value; // unwrap {name, value} → raw record, undefined on cancel
+  return selected?.value; // unwrap {name, value}, undefined on cancel
 }
 
 /**

package/src/mutations.js

@@ -1,105 +1,50 @@
-// Centralized mutation command registry
-// Used by the read-only profile middleware to block mutation commands.
-// Each entry is a command path array matching argv._ tokens.
+// Mutation guard — the public face is isMutationCommand(argv), used by the
+// read-only-profile middleware in cli.js. The command-path data is DERIVED
+// from the capability registry (src/capabilities.js) at call time — command
+// modules declare their mutating subcommands once, at the definition site.
+//
+// The registry used to be a hand-maintained list here, and it rotted: it
+// gated `catalog create-item` while the real command is `catalogitems
+// create` (read-only bypass), and listed `restmethods`, a command that was
+// never registered. Derived data can't drift that way.
 
-// Dev commands that expose create/update/delete via buildDevCmd.
-// Each generates the root form (`jsn <name> create`) and the legacy dev form
-// (`jsn dev <name> create`), so read-only profiles block both spellings.
-const DEV_CRUD_COMMANDS = [
-  'actions', 'includes', 'rules', 'clientscripts', 'uiactions', 'uipolicies',
-  'tables', 'uipages', 'appmenu', 'acls', 'roles', 'properties', 'relationships',
-  'appmodules', 'listcontrols', 'views', 'privileges', 'uxscripts',
-  'catalogscripts', 'scriptactions', 'scheduledjobs', 'asyncrules', 'triggers',
-  'email', 'restmethods', 'restmessage', 'soapmessages', 'uimacros',
-  'cataloguipolicies', 'aliases', 'columns', 'flows', 'scrapi',
-];
+import { mutationPaths } from './capabilities.js';
 
-function devCrudPaths(name) {
-  return [
-    [name, 'create'],
-    [name, 'update'],
-    [name, 'delete'],
-    ['dev', name, 'create'],
-    ['dev', name, 'update'],
-    ['dev', name, 'delete'],
-  ];
+/**
+ * Back-compat export: the derived mutation path list, refreshed by
+ * refreshMutationCommands() — cli.js calls it at the end of buildCLI(),
+ * so the data is generated at CLI build time, not hand-maintained.
+ * Prefer isMutationCommand().
+ */
+export const MUTATION_COMMANDS = [];
+
+export function refreshMutationCommands() {
+  MUTATION_COMMANDS.length = 0;
+  MUTATION_COMMANDS.push(...mutationPaths());
+  return MUTATION_COMMANDS;
 }
 
-export const MUTATION_COMMANDS = [
-  // Incidents
-  ['incidents', 'create'],
-  ['incidents', 'update'],
-  ['incidents', 'delete'],
-  // Changes
-  ['changes', 'create'],
-  ['changes', 'update'],
-  ['changes', 'delete'],
-  // Records
-  ['records', 'create'],
-  ['records', 'update'],
-  ['records', 'delete'],
-  // Requests
-  ['requests', 'create'],
-  ['requests', 'update'],
-  ['requests', 'delete'],
-  // Tasks
-  ['tasks', 'create'],
-  ['tasks', 'update'],
-  ['tasks', 'delete'],
-  // Tickets
-  ['tickets', 'create'],
-  ['tickets', 'update'],
-  ['tickets', 'delete'],
-  // Users
-  ['users', 'create'],
-  ['users', 'update'],
-  ['users', 'delete'],
-  // Groups
-  ['groups', 'create'],
-  ['groups', 'update'],
-  ['groups', 'delete'],
-  // Catalog
-  ['catalog', 'create-item'],
-  // Dev CRUD commands (root + `jsn dev` forms)
-  ...DEV_CRUD_COMMANDS.flatMap(devCrudPaths),
-  // Dev eval (no sub-action) — both spellings must be gated:
-  // `jsn eval` (root) and legacy `jsn dev eval`
-  ['eval'],
-  ['dev', 'eval'],
-  // Raw REST passthrough — can hit any endpoint with any method,
-  // so the whole command is a mutation surface on read-only profiles
-  ['rest'],
-  ['dev', 'rest'],
-  // Scopes: create + set (root + dev forms)
-  ['scopes', 'create'],
-  ['scopes', 'set'],
-  ['dev', 'scopes', 'create'],
-  ['dev', 'scopes', 'set'],
-  // Domains: set writes the profile config (root + dev forms)
-  ['domains', 'set'],
-  ['dev', 'domains', 'set'],
-  // Update sets: create, set, complete, ignore, parent (root + dev forms)
-  ['updatesets', 'create'],
-  ['updatesets', 'set'],
-  ['updatesets', 'complete'],
-  ['updatesets', 'ignore'],
-  ['updatesets', 'parent'],
-  ['dev', 'updatesets', 'create'],
-  ['dev', 'updatesets', 'set'],
-  ['dev', 'updatesets', 'complete'],
-  ['dev', 'updatesets', 'ignore'],
-  ['dev', 'updatesets', 'parent'],
-];
+function currentPaths(paths) {
+  return paths || refreshMutationCommands();
+}
 
 /**
  * Check if the parsed argv matches any mutation command pattern.
+ * Prefix match: a command whose argv._ path begins with a mutation pattern
+ * IS that mutation (trailing positionals like a sys_id or file path don't
+ * change the intent). This lets positional mutation subcommands (e.g.
+ * `records attachments <id> add <file>`) be gated on read-only profiles.
+ *
  * @param {object} argv — yargs parsed argv with `_` array
+ * @param {Array<string[]>} [paths] — mutation path patterns; defaults to
+ *   the paths derived from the capability registry. (Tests pass explicit
+ *   paths; production callers should let it derive.)
  * @returns {boolean}
  */
-export function isMutationCommand(argv) {
+export function isMutationCommand(argv, paths) {
   const cmd = argv._ || [];
-  for (const pattern of MUTATION_COMMANDS) {
-    if (pattern.length !== cmd.length) continue;
+  for (const pattern of currentPaths(paths)) {
+    if (pattern.length > cmd.length) continue;
     let match = true;
     for (let i = 0; i < pattern.length; i++) {
       if (pattern[i] !== cmd[i]) {