@jacebenson/jsn 4.3.13-dev.78.1 → 4.3.13-dev.80.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.13-dev.78.1",
+  "version": "4.3.13-dev.80.1",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {

package/src/app.js

@@ -7,6 +7,7 @@
 // setEffectiveInstance() are thin session-backed shims kept for the many
 // command handlers that already call them.
 
+import { appendMutation } from './mutation-history.js';
 import { AuthManager } from './auth.js';
 import { createAuthRecovery } from './auth-recovery.js';
 import { SDKClient } from './sdk.js';
@@ -16,7 +17,7 @@ import { resolveSession, applySession, contextFromSession, requireSessionInstanc
 import { getCurrentUser, getCurrentApplication, getCurrentUpdateSet } from './context.js';
 import { errUsage, errAuth } from './errors.js';
 import { canPrompt } from './helpers.js';
-import { isMutationCommand } from './mutations.js';
+import { guardMutationContext } from './mutation-context.js';
 import process from 'node:process';
 
 
@@ -59,6 +60,7 @@ export class App {
     }), {
       domain: session?.domain || '',
       recovery: createAuthRecovery({ app: this, session }),
+      onMutation: event => this.recordMutation(instance, session?.profileName, event),
     });
   }
 
@@ -67,9 +69,21 @@ export class App {
     const profile = options.profile || {};
     return new SDKClient(instance, this.auth.createProfileProvider(instance, options), {
       domain: options.domain ?? profile.domain ?? '',
+      onMutation: event => this.recordMutation(instance, options.profileName || null, event),
     });
   }
 
+  recordMutation(instance, profile, event) {
+    if (!this._authArgv) return;
+    try { appendMutation({ ...event, instance, profile, reason: this._authArgv.reason }); }
+    catch {
+      if (!this._historyWarningShown) {
+        process.stderr.write('Warning: local mutation history could not be saved. The remote result is unchanged.\n');
+        this._historyWarningShown = true;
+      }
+    }
+  }
+
   loadContext() {
     this.context = contextFromSession(this.session, this.config);
   }
@@ -78,7 +92,7 @@ export class App {
     return this.session?.instance || '';
   }
 
-  async printContextHeader(argv = {}) {
+  async printContextHeader(_argv = {}) {
     if (!this.getEffectiveInstance() || !this.sdk) return;
     if (process.env.JSN_NO_HEADER) return;
     if (this.output.getFormat() === FormatJSON || this.output.getFormat() === FormatQuiet) return;
@@ -104,12 +118,12 @@ export class App {
 
     // Both lookups depend on the user, but not on one another.
     const [application, selectedUpdateSet] = userSysID ? await Promise.all([
-      getCurrentApplication(this.sdk, userSysID).catch(() => null),
+      getCurrentApplication(this.sdk, userSysID, { unknownWhenMissing: true }).catch(() => null),
       getCurrentUpdateSet(this.sdk, userSysID).catch(() => null),
     ]) : [null, null];
-    const scope = application?.scope || 'global';
+    const scope = application?.scope || 'unknown';
     const updateSet = selectedUpdateSet?.name && selectedUpdateSet.name !== '-'
-      ? selectedUpdateSet.name : 'Default';
+      ? selectedUpdateSet.name : 'unknown';
     const updateSetSysID = selectedUpdateSet?.name && selectedUpdateSet.name !== '-'
       ? selectedUpdateSet.sys_id : '';
     this.context.scope = scope;
@@ -139,43 +153,14 @@ export class App {
 
     process.stderr.write(`${profileStr} ${userStr} ${scopeStr} ${updateSetStr}\n\n`);
 
-    // ⚠️  Warning if in the Default update set (mutation commands only)
-    if (isMutationCommand(argv) && updateSet && updateSet.toLowerCase().includes('default')) {
-      const isGlobal = scope === 'global';
-      if (isGlobal) {
-        // 🔴 HARD WARNING — Global + Default
-        process.stderr.write(
-          '\x1b[31m' + // red
-          '┏━ GLOBAL + DEFAULT ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓\n' +
-          '┃  You are in Global scope with the Default update set.  ┃\n' +
-          '┃  Changes ARE captured — in the Default update set.     ┃\n' +
-          '┃  Moving them to a named update set later requires      ┃\n' +
-          '┃  manual surgery, one change at a time. Avoid the mess. ┃\n' +
-          '┃                                                        ┃\n' +
-          '┃  Create a named update set now:                        ┃\n' +
-          '┃    jsn updatesets create --name "My Feature"       ┃\n' +
-          '┃                                                        ┃\n' +
-          '┃  Or switch to a scoped scope first:                    ┃\n' +
-          '┃    jsn scopes list                                 ┃\n' +
-          '┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛\x1b[0m\n'
-        );
-      } else {
-        // 🟡 SOFT WARNING — Scope + Default
-        process.stderr.write(
-          '\x1b[33m' + // yellow
-          '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n' +
-          '  ⚠  Default update set in scope [' + scope + ']\n' +
-          '  Changes are contained to this scope, but a named\n' +
-          '  update set is still recommended for tracking.\n' +
-          '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n' +
-          '\x1b[0m' // reset
-        );
-      }
-    }
+  }
+
+  async guardMutationContext(argv) {
+    this.mutationContext = await guardMutationContext(this, argv);
   }
 
   ok(data, opts = {}) {
-    this.output.ok(data, opts);
+    this.output.ok(data, this.mutationContext ? { ...opts, context: { ...opts.context, mutation: this.mutationContext } } : opts);
   }
 
   err(error) {

package/src/capabilities.js

@@ -16,6 +16,10 @@
 //     skipDailyChecks: true,
 //     // Suppress the current instance header for profile management commands.
 //     skipContextHeader: true,
+//     // Remediation commands bypass mutation capture-context approval only.
+//     mutationContextExemptSubcommands: ['create', 'set'],
+//     // REST methods that are reads (read-only profile policy is separate).
+//     mutationContextReadMethods: ['GET', 'HEAD', 'OPTIONS'],
 //   }
 //
 // cli.js derives every skip-list and the mutation guard's path list from

package/src/cli.js

@@ -71,6 +71,7 @@ import { scrapiCmd } from './commands/scrapi.js';
 import { b4rulesCmd } from './commands/b4rules.js';
 import { atfCmd } from './commands/atf.js';
 import { approvalsCmd } from './commands/approvals.js';
+import { historyCmd } from './commands/history.js';
 import { perfCmd } from './commands/perf.js';
 import { customizationsCmd } from './commands/customizations.js';
 import { midserversCmd } from './commands/midservers.js';
@@ -117,6 +118,7 @@ function wrap(handler) {
         process.stderr.write('Error: App context not initialized.\n');
         process.exit(1);
       }
+      await app.guardMutationContext(argv);
       await handler(argv, app);
     } catch (err) {
       // All error rendering goes through the unified renderer in
@@ -145,6 +147,12 @@ export function buildCLI() {
       },
     ])
     .options({
+      reason: { type: 'string', describe: 'Optional non-sensitive reason saved in local mutation history' },
+
+      force: {
+        type: 'boolean',
+        description: 'Approve Global + Default mutation context only after user approval; delete commands also use this for their separate confirmation',
+      },
       instance: {
         type: 'string',
         description: 'ServiceNow instance URL',
@@ -411,6 +419,7 @@ export function buildCLI() {
     .command(approvalsCmd(wrap))
     .command(skippedUpdatesCmd(wrap))
     .command(perfCmd(wrap))
+    .command(historyCmd(wrap))
     .command(customizationsCmd(wrap))
     .command(midserversCmd(wrap))
     .command(diffCmd(wrap))

package/src/commands/history.js

@@ -0,0 +1,26 @@
+import { declareCapabilities } from '../capabilities.js';
+import { listHistory, pruneHistory } from '../mutation-history.js';
+
+export function historyCmd(wrap) {
+  declareCapabilities('history', { noInstance: true, skipDailyChecks: true });
+  const list = wrap(async (argv, app) => {
+    const entries = listHistory({ ...argv, instance: argv['instance-url'], profile: argv['profile-name'] });
+    app.ok({ entries, retentionDays: 7, _formatted: entries.length
+      ? entries.map(e => `${e.timestamp} ${e.operation} ${e.table}/${e.sys_id || '(unknown ID)'} ${e.outcome} ${e.instance}${e.reason ? ` — ${e.reason}` : ''}`).join('\n')
+      : 'No local mutations in the last seven days.' });
+  });
+  const filters = b => b
+    .option('since', { type: 'string', describe: 'Earliest ISO timestamp' })
+    .option('until', { type: 'string', describe: 'Latest ISO timestamp' })
+    .option('instance-url', { type: 'string', describe: 'Filter by instance origin' })
+    .option('profile-name', { type: 'string', describe: 'Filter by recorded profile name (including removed profiles)' })
+    .option('table', { type: 'string', describe: 'Filter by table' })
+    .option('operation', { choices: ['create', 'update', 'delete'], type: 'string' })
+    .option('record', { type: 'string', describe: 'Filter by full resolved sys_id' })
+    .option('limit', { type: 'number', default: 50, describe: 'Maximum entries (1–10000)' });
+  return { command: 'history [subcommand]', describe: 'Local seven-day mutation history (not a durable ServiceNow audit)',
+    builder: y => filters(y).command({ command: 'list', describe: 'List local mutations', builder: filters, handler: list })
+      .command({ command: 'prune', describe: 'Remove expired entries only', handler: wrap(async (_argv, app) => {
+        app.ok({ ...pruneHistory(), _formatted: 'Expired local history removed; seven days retained.' });
+      }) }), handler: list };
+}

package/src/commands/rest.js

@@ -2,7 +2,7 @@ import { declareCapabilities } from '../capabilities.js';
 
 // Raw REST passthrough — can hit any endpoint with any method, so the whole
 // command is a mutation surface on read-only profiles.
-declareCapabilities('rest', { mutationSubcommands: [''] });
+declareCapabilities('rest', { mutationSubcommands: [''], mutationContextReadMethods: ['GET', 'HEAD', 'OPTIONS'] });
 
 export function restCmd(wrap) {
   return {

package/src/commands/scopes.js

@@ -3,7 +3,7 @@ import { requireCurrentUserSysId, setCurrentApplication } from '../context.js';
 import { declareCapabilities } from '../capabilities.js';
 import { unwrapSysId } from '../resolve-record.js';
 
-declareCapabilities('scopes', { mutationSubcommands: ['create', 'set'] });
+declareCapabilities('scopes', { mutationSubcommands: ['create', 'set'], mutationContextExemptSubcommands: ['create', 'set'] });
 
 /**
  * Resolve a scope identifier to a single sys_scope record.

package/src/commands/updatesets.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import { editor, confirm } from '../prompts.js';
-import { formatRecordForDisplay, getStringField, interactiveList, assertSafeExactMatch, canPrompt, buildRerunCommand, verifyWriteBack } from '../helpers.js';
+import { formatRecordForDisplay, getStringField, interactiveList, assertSafeExactMatch, canPrompt, buildRerunCommand, verifyWriteBack, quoteShellArg } from '../helpers.js';
 import { getActiveProfile } from '../config.js';
 import { FormatAuto } from '../output.js';
 import { getCurrentApplication, getCurrentUpdateSet, requireCurrentUserSysId, setCurrentApplication, setCurrentUpdateSet } from '../context.js';
@@ -11,6 +11,7 @@ import { unwrapSysId } from '../resolve-record.js';
 
 declareCapabilities('updatesets', {
   mutationSubcommands: ['create', 'set', 'complete', 'ignore', 'parent'],
+  mutationContextExemptSubcommands: ['create', 'set'],
 });
 
 /**
@@ -27,7 +28,7 @@ export function scopeMismatchWarning(updateSetApp, currentApp) {
   const updateSetAppId = updateSetApp?.value || (typeof updateSetApp === 'string' ? updateSetApp : '');
   if (!updateSetAppId || !currentApp.appSysId || updateSetAppId === currentApp.appSysId) return '';
   const name = updateSetApp?.display_value || updateSetApp;
-  return ` ⚠️ update set is in app "${name}", but current app is "${currentApp.scope}" — changes won't land here. Run: jsn scopes set ${name}`;
+  return ` ⚠️ update set is in app "${name}", but current app is "${currentApp.scope}" — changes may not be captured in this set. Run: jsn scopes set ${quoteShellArg(updateSetAppId)}`;
 }
 
 /** Format a picker label for an update set: "Name [State] (app/scope)". */
@@ -424,7 +425,7 @@ export function updateSetsCmd(wrap) {
   return {
     command: 'updatesets [subcommand]',
     aliases: ['updateset', 'us'],
-    describe: 'Manage update sets',
+    describe: 'Manage update sets. Global + Default mutations require approval (--force only after user approval); create/set remain available to select a dedicated capture set. Scope mismatches warn; completed capture sets block writes.',
     builder: (yargs) => {
       return yargs
         .command({

package/src/context.js

@@ -18,26 +18,26 @@ export async function getCurrentUser(sdk) {
   };
 }
 
-export async function getCurrentApplication(sdk, userSysID) {
+export async function getCurrentApplication(sdk, userSysID, { unknownWhenMissing = false } = {}) {
   const params = new URLSearchParams();
   params.set('sysparm_query', `user=${userSysID}^name=apps.current_app`);
   params.set('sysparm_limit', '1');
   params.set('sysparm_fields', 'value');
   const records = await sdk.list('sys_user_preference', params);
-  if (records.length === 0) return { scope: 'global', appSysId: '' };
+  if (records.length === 0) return { scope: unknownWhenMissing ? '' : 'global', appSysId: '' };
   const val = records[0].value?.value || records[0].value;
-  if (!val) return { scope: 'global', appSysId: '' };
+  if (!val) return { scope: unknownWhenMissing ? '' : 'global', appSysId: '' };
 
   // Try to resolve sys_id to scope name
   try {
     const app = await sdk.get('sys_scope', val);
-    if (app) return { scope: app.scope || 'global', appSysId: val };
+    if (app) return { scope: getStringField(app, 'scope') || (unknownWhenMissing ? '' : 'global'), appSysId: val };
   } catch {
     // fallback
   }
   try {
     const app2 = await sdk.get('sys_app', val);
-    if (app2) return { scope: app2.scope || 'global', appSysId: val };
+    if (app2) return { scope: getStringField(app2, 'scope') || (unknownWhenMissing ? '' : 'global'), appSysId: val };
   } catch {
     // fallback
   }
@@ -56,7 +56,7 @@ export async function getCurrentUpdateSet(sdk, userSysID) {
 
   try {
     const us = await sdk.get('sys_update_set', val);
-    if (us) return { name: us.name || val, sys_id: val };
+    if (us) return { name: getStringField(us, 'name') || val, sys_id: val, application: us.application, state: getStringField(us, 'state') };
   } catch {
     // fallback
   }

package/src/errors.js

@@ -213,7 +213,7 @@ export function isErrorCode(err, code) {
  * back to argv.format for callers without an App (unit tests).
  */
 function resolveJsonMode(app, argv) {
-  if (app?.output) return app.output.effectiveFormat() === 'json';
+  if (app?.output) return ['json', 'quiet'].includes(app.output.effectiveFormat());
   return argv?.format === 'json';
 }
 

package/src/mutation-context.js

@@ -0,0 +1,74 @@
+// Capture-context approval is independent of delete confirmation preferences.
+import process from 'node:process';
+import { collectCapabilities } from './capabilities.js';
+import { isMutationCommand } from './mutations.js';
+import { getCurrentUser, getCurrentApplication, getCurrentUpdateSet } from './context.js';
+import { canUsePicker, getStringField, quoteShellArg } from './helpers.js';
+import { confirm } from './prompts.js';
+import { AppError, CodeConfirmationRequired, errUsageHint } from './errors.js';
+
+export function needsMutationContext(argv) {
+  if (!isMutationCommand(argv)) return false;
+  const caps = collectCapabilities().get(argv._?.[0]) || {};
+  if (caps.mutationContextReadMethods?.includes(String(argv.method || 'GET').toUpperCase())) return false;
+  return !caps.mutationContextExemptSubcommands?.some(sub =>
+    sub.split(' ').every((part, index) => argv._?.[index + 1] === part));
+}
+
+function diagnostic(code, message, command, severity = 'warning') {
+  return { code, severity, message, remediation: { command } };
+}
+
+export async function guardMutationContext(app, argv, { ask = confirm, rawArgs = process.argv.slice(2) } = {}) {
+  if (!needsMutationContext(argv) || !app.sdk) return null;
+  let application, updateSet;
+  try {
+    const user = await getCurrentUser(app.sdk);
+    if (user?.sys_id) [application, updateSet] = await Promise.all([
+      getCurrentApplication(app.sdk, user.sys_id, { unknownWhenMissing: true }),
+      getCurrentUpdateSet(app.sdk, user.sys_id),
+    ]);
+  } catch {
+    // Failed reads are unknown context, never evidence of Global + Default.
+  }
+  const context = { scope: application?.scope || null, application_id: application?.appSysId || null,
+    update_set: updateSet ? { name: updateSet.name, sys_id: updateSet.sys_id, state: updateSet.state || null } : null,
+    diagnostics: [], approval_required: false, approved: false };
+  if (!context.scope || !updateSet) context.diagnostics.push(diagnostic('capture_context_unknown',
+    'Capture context could not be determined. Identify the intended scope and update set before development changes.', 'jsn updatesets list'));
+  const appId = getStringField(updateSet || {}, 'application');
+  const rawAppId = updateSet?.application?.value || appId;
+  if (application?.appSysId && rawAppId && application.appSysId !== rawAppId) {
+    context.diagnostics.push(diagnostic('update_set_scope_mismatch',
+      `Selected scope ${context.scope} and update set ${updateSet.name} belong to different applications; changes may not be captured in this set.`,
+      `jsn scopes set ${quoteShellArg(rawAppId)}`));
+  }
+  if (updateSet?.state && !['in progress', 'in_progress'].includes(updateSet.state.toLowerCase())) {
+    context.diagnostics.push(diagnostic('update_set_not_in_progress', `Selected update set ${updateSet.name} is ${updateSet.state}; select an in-progress capture set.`, 'jsn updatesets set', 'error'));
+    const error = errUsageHint('Selected capture update set is not in progress.', 'Run: jsn updatesets set');
+    error.context = context; throw error;
+  }
+  const globalDefault = context.scope?.toLowerCase() === 'global' && updateSet?.name?.toLowerCase() === 'default';
+  if (globalDefault) {
+    context.approval_required = true;
+    context.diagnostics.push(diagnostic('global_default_update_set',
+      'Global scope + Default update set can capture customization in the wrong place or leave changes untracked. Select or create a dedicated update set; not all record changes are update-set tracked.',
+      'jsn updatesets create --name "My Feature"'));
+    if (argv.force) context.approved = true;
+    else if (canUsePicker(app, argv)) {
+      context.approved = await ask({ message: `Scope: Global; update set: Default. ${context.diagnostics.at(-1).message} Approve this exact mutation: ${['jsn', ...rawArgs].map(quoteShellArg).join(' ')}?`, default: false });
+    }
+    if (!context.approved) {
+      const target = app.session?.profileName ? ` --profile ${quoteShellArg(app.session.profileName)}` : '';
+      const rerun = ['jsn', ...rawArgs.filter(arg => arg !== '--force')].map(quoteShellArg).join(' ') + (rawArgs.includes('--profile') ? '' : target);
+      const error = new AppError(CodeConfirmationRequired, 'Mutation in Global scope + Default update set requires explicit approval.',
+        `Select a dedicated set: jsn updatesets set; or jsn updatesets create --name "My Feature". Ask the user to approve this exact operation, then rerun: ${rerun} --force`);
+      error.context = context; throw error;
+    }
+  }
+  if (canUsePicker(app, argv)) {
+    process.stderr.write(`Mutation context: scope ${context.scope || 'unknown'}; update set ${updateSet?.name || 'unknown'}${updateSet?.sys_id ? ` (${updateSet.sys_id})` : ''}.\n`);
+    for (const item of context.diagnostics) process.stderr.write(`Warning (${item.code}): ${item.message} Run: ${item.remediation.command}\n`);
+  }
+  return context;
+}

package/src/mutation-history.js

@@ -0,0 +1,75 @@
+// Local convenience history, independent of documentation indexes and sync.
+import Database from 'better-sqlite3';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { errUsage } from './errors.js';
+
+export const RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+const operations = ['create', 'update', 'delete'];
+const outcomes = ['succeeded', 'failed', 'unknown'];
+export function historyPath() {
+  return path.join(process.env.JSN_DATA_HOME || path.join(os.homedir(), '.jsn'), 'history.db');
+}
+function openHistory(filename, now) {
+  fs.mkdirSync(path.dirname(filename), { recursive: true, mode: 0o700 });
+  const db = new Database(filename);
+  try {
+    if (process.platform !== 'win32') fs.chmodSync(filename, 0o600);
+    db.pragma('busy_timeout = 3000');
+    db.exec(`CREATE TABLE IF NOT EXISTS mutation_history (
+      id INTEGER PRIMARY KEY, timestamp INTEGER NOT NULL, instance TEXT NOT NULL,
+      profile TEXT, table_name TEXT NOT NULL, sys_id TEXT, operation TEXT NOT NULL,
+      outcome TEXT NOT NULL, reason TEXT, http_status INTEGER
+    ); CREATE INDEX IF NOT EXISTS mutation_history_time ON mutation_history(timestamp)`);
+    db.prepare('DELETE FROM mutation_history WHERE timestamp < ?').run(now - RETENTION_MS);
+    return db;
+  } catch (error) { db.close(); throw error; }
+}
+export function sanitizeReason(value) {
+  if (!value) return null;
+  // eslint-disable-next-line no-control-regex -- strip controls from user-supplied prose
+  return String(value).replace(/[\u0000-\u001f\u007f]/g, ' ')
+    .replace(/\b(?:Bearer|Basic)\s+\S+/gi, '[redacted]')
+    .replace(/\b(password|token|cookie|secret|authorization|access_token|sysparm_ck)\s*[:=]\s*(?:"[^"]*"|'[^']*'|\S+)/gi, '$1=[redacted]')
+    .slice(0, 1000);
+}
+export function appendMutation(event, { filename = historyPath(), now = Date.now() } = {}) {
+  if (!operations.includes(event.operation) || !outcomes.includes(event.outcome)) throw errUsage('Invalid history event');
+  const instance = new URL(event.instance).origin;
+  // Deliberate whitelist: never serialize SDK options, response bodies, or payloads.
+  const row = { timestamp: now, instance, profile: event.profile || null,
+    table_name: event.table, sys_id: event.sys_id || null, operation: event.operation,
+    outcome: event.outcome, reason: sanitizeReason(event.reason), http_status: event.http_status || null };
+  const db = openHistory(filename, now);
+  try {
+    db.prepare(`INSERT INTO mutation_history
+      (timestamp,instance,profile,table_name,sys_id,operation,outcome,reason,http_status)
+      VALUES (@timestamp,@instance,@profile,@table_name,@sys_id,@operation,@outcome,@reason,@http_status)`).run(row);
+  } finally { db.close(); }
+}
+export function pruneHistory({ filename = historyPath(), now = Date.now() } = {}) {
+  const db = openHistory(filename, now);
+  try { return { retentionDays: 7 }; } finally { db.close(); }
+}
+export function listHistory(filters = {}, { filename = historyPath(), now = Date.now() } = {}) {
+  const where = [], values = [];
+  for (const [key, column] of Object.entries({ instance: 'instance', profile: 'profile', table: 'table_name', operation: 'operation', record: 'sys_id' })) {
+    if (filters[key]) { where.push(`${column} = ?`); values.push(key === 'instance' ? new URL(filters[key]).origin : filters[key]); }
+  }
+  for (const [key, operator] of [['since', '>='], ['until', '<=']]) {
+    if (filters[key]) {
+      const time = Date.parse(filters[key]);
+      if (!Number.isFinite(time)) throw errUsage(`Invalid --${key} timestamp; use an ISO date`);
+      where.push(`timestamp ${operator} ?`); values.push(time);
+    }
+  }
+  const limit = filters.limit ?? 50;
+  if (!Number.isInteger(limit) || limit < 1 || limit > 10000) throw errUsage('--limit must be an integer from 1 to 10000');
+  const db = openHistory(filename, now);
+  try {
+    return db.prepare(`SELECT id,timestamp,instance,profile,table_name AS "table",sys_id,operation,outcome,reason,http_status
+      FROM mutation_history ${where.length ? `WHERE ${where.join(' AND ')}` : ''} ORDER BY timestamp DESC,id DESC LIMIT ?`)
+      .all(...values, limit).map(row => ({ ...row, timestamp: new Date(row.timestamp).toISOString() }));
+  } finally { db.close(); }
+}

package/src/output.js

@@ -160,6 +160,7 @@ export class OutputWriter {
     const format = this.effectiveFormat();
     const e = error.code ? error : { code: 'unknown', message: String(error), hint: '' };
     const resp = { ok: false, error: e.message, code: e.code, hint: e.hint || '' };
+    if (e.context) resp.context = e.context;
     if (e.status === 401 || e.status === 403) resp.status = e.status;
     if (e.recovery) {
       resp.recovery = e.recovery;

package/src/sdk.js

@@ -48,6 +48,7 @@ export class SDKClient {
     this.baseURL = baseURL.replace(/\/$/, '');
     this.authProvider = authProvider;
     this.recovery = opts.recovery;
+    this.onMutation = opts.onMutation;
     this.timeout = opts.timeout || DEFAULT_TIMEOUT;
     this.domain = opts.domain || '';
     this.oauthCookies = null;
@@ -104,7 +105,47 @@ export class SDKClient {
 
   // Keep the timeout alive through body consumption for text/JSON requests.
   // Raw-response callers retain their existing timeout boundary at headers.
-  async _withAuthenticatedRequest(endpoint, opts, {
+  async _withAuthenticatedRequest(endpoint, opts, settings, consume = (response) => response) {
+    const url = new URL(endpoint);
+    const match = url.pathname.match(/^\/api\/now\/table\/([^/]+)(?:\/([^/]+))?\/?$/);
+    const operation = { POST: 'create', PUT: 'update', PATCH: 'update', DELETE: 'delete' }[(opts.method || 'GET').toUpperCase()];
+    const event = match && operation && this.onMutation ? {
+      table: decodeURIComponent(match[1]), sys_id: match[2] ? decodeURIComponent(match[2]) : null, operation,
+    } : null;
+    let result;
+    try {
+      result = await this._performAuthenticatedRequest(endpoint, opts, settings, async response => {
+        if (event) event.http_status = response.status;
+        const value = await consume(response);
+        if (event && value instanceof Response && response.ok && operation === 'create') {
+          try { event.sys_id = (await response.clone().json())?.result?.sys_id || null; } catch { /* ID remains unknown. */ }
+        }
+        return value;
+      });
+    } catch (error) {
+      if (event) await this._reportMutation({ ...event, outcome: error.status >= 400 && error.status < 500 && error.status !== 408
+        ? 'failed' : 'unknown', http_status: error.status || null });
+      throw error;
+    }
+    if (event) {
+      let body = result;
+      if (typeof body === 'string') { try { body = JSON.parse(body); } catch { body = null; } }
+      const id = body?.result?.sys_id;
+      if (typeof id === 'string') event.sys_id = id;
+      else if (typeof id?.value === 'string') event.sys_id = id.value;
+      await this._reportMutation({ ...event, outcome: event.http_status >= 400
+        ? (event.http_status < 500 && event.http_status !== 408 ? 'failed' : 'unknown')
+        : (event.sys_id ? 'succeeded' : 'unknown') });
+    }
+    return result;
+  }
+
+  async _reportMutation(event) {
+    // History failures must never change the outcome of a completed remote write.
+    try { await this.onMutation(event); } catch { /* App callback reports local storage failures. */ }
+  }
+
+  async _performAuthenticatedRequest(endpoint, opts, {
     timeout = this.timeout, prepare, skipOAuthSession = false, normalizeErrors = false,
   }, consume = (response) => response) {
     for (let attempt = 0; attempt < 2; attempt++) {