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

package/package.json

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

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';
@@ -146,6 +147,8 @@ 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',
@@ -416,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/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/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++) {