@jacebenson/jsn 4.3.7-dev.12 → 4.3.7-dev.14

package/README.md

@@ -72,6 +72,11 @@ jsn records bulk --table incident --query "priority=1" --set '{"state":"3"}'  #
 jsn records get --table incident --sys-id 8a1234abcd5678 --attachments        # record + its files
 jsn records list --table incident --limit 10 --csv                            # output CSV
 
+# Read-only cross-profile record diff
+jsn diff record --table incident --sys-id <sys_id> --profile-a dev --profile-b prod
+jsn diff record --table incident --sys-id <sys_id> --profile-a dev --profile-b prod --ignore state
+jsn diff record --table incident --sys-id <sys_id> --profile-a dev --profile-b prod --no-ignore
+
 # Script execution
 jsn eval "gs.info('Hello World')"
 cat script.js | jsn eval --stdin          # pipe a script in (no shell escaping)
@@ -110,7 +115,7 @@ Run `jsn` for the full grouped list. Commands are organized by ServiceNow domain
 
 **User Experience** — `forms`, `lists`, `clientscripts`, `uipolicies`, `uiactions`
 
-**Data** — `records` (list/get/create/update/delete/count/bulk/attachments), `tables`, `columns`, `includes`, `import`, `logs` (list/show/follow), `snippets` (save/run), `users`, `groups`
+**Data** — `records` (list/get/create/update/delete/count/bulk/attachments), `diff record` (cross-profile read-only comparison), `tables`, `columns`, `includes`, `import`, `logs` (list/show/follow), `snippets` (save/run), `users`, `groups`
 
 Every command supports `--json`, `--query`, and `--help`.
 
@@ -162,6 +167,8 @@ export SERVICENOW_OAUTH_TOKEN="***"
 jsn incidents list
 ```
 
+For the credential identity, auth-method, diagnostics, migration, and concurrency contract, see [`docs/AUTH_LIFECYCLE.md`](docs/AUTH_LIFECYCLE.md).
+
 ## Local data
 
 JSN stores durable local data under `~/.jsn/`. Documentation lives in

package/package.json

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

package/src/auth.js

@@ -41,30 +41,32 @@ function credKey(instance, username) {
 
 // ─── PKCE state persistence (shared with Go version) ───
 
-function pkceStatePath(instance) {
+function pkceStatePath(instance, username) {
   const dir = path.join(globalConfigDir(), 'pkce');
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  const filename = sanitizeKeyPart(instance) + '.json';
+  // A known profile identity gets its own pending-login slot. Keep the bare
+  // instance slot for legacy/no-profile flows, where no identity exists yet.
+  const filename = credKey(instance, username) + '.json';
   return path.join(dir, filename);
 }
 
-function savePKCEState(instance, pkce) {
-  const filePath = pkceStatePath(instance);
+function savePKCEState(instance, pkce, username) {
+  const filePath = pkceStatePath(instance, username);
   fs.writeFileSync(filePath, JSON.stringify(pkce, null, 2), { mode: 0o600 });
 }
 
-function loadPKCEState(instance) {
+function loadPKCEState(instance, username) {
   try {
-    const data = fs.readFileSync(pkceStatePath(instance), 'utf-8');
+    const data = fs.readFileSync(pkceStatePath(instance, username), 'utf-8');
     return JSON.parse(data);
   } catch {
     return null;
   }
 }
 
-function removePKCEState(instance) {
+function removePKCEState(instance, username) {
   try {
-    fs.unlinkSync(pkceStatePath(instance));
+    fs.unlinkSync(pkceStatePath(instance, username));
   } catch {
     // ignore
   }
@@ -746,7 +748,7 @@ export class AuthManager {
     instanceURL = normalizeInstanceURL(instanceURL);
     const clientID = getOAuthClientID();
     const pkce = generatePKCE();
-    savePKCEState(instanceURL, pkce);
+    savePKCEState(instanceURL, pkce, username);
     const url = buildAuthURL(instanceURL, clientID, pkce);
     if (waitFile) {
       console.log(url);
@@ -766,7 +768,7 @@ export class AuthManager {
         const code = fs.readFileSync(filePath, 'utf-8').trim();
         if (code) {
           console.log(`\nAuthorization code found in ${filePath}`);
-          removePKCEState(instanceURL);
+          removePKCEState(instanceURL, username);
           const newCreds = await this.exchangeCode(instanceURL, clientID, code, pkce);
           this.saveCredentials(instanceURL, newCreds, username || newCreds.username);
           console.log('Token exchange successful!\n');
@@ -838,7 +840,7 @@ export class AuthManager {
   async loginWithCode(instanceURL, code, username = this._activeUsername()) {
     instanceURL = normalizeInstanceURL(instanceURL);
     const clientID = getOAuthClientID();
-    const pkce = loadPKCEState(instanceURL);
+    const pkce = loadPKCEState(instanceURL, username);
     if (!pkce) {
       throw errAuth(
         `No pending login session for ${instanceURL}.\n\n` +
@@ -848,7 +850,7 @@ export class AuthManager {
         `  jsn auth login ${instanceURL} --code CODE`
       );
     }
-    removePKCEState(instanceURL);
+    removePKCEState(instanceURL, username);
 
     const newCreds = await this.exchangeCode(instanceURL, clientID, code, pkce);
     this.saveCredentials(instanceURL, newCreds, username || newCreds.username);

package/src/cli.js

@@ -69,6 +69,7 @@ import { b4rulesCmd } from './commands/b4rules.js';
 import { atfCmd } from './commands/atf.js';
 import { approvalsCmd } from './commands/approvals.js';
 import { perfCmd } from './commands/perf.js';
+import { diffCmd } from './commands/diff.js';
 
 function wrap(handler) {
   return async (argv) => {
@@ -371,6 +372,7 @@ export function buildCLI() {
     .command(atfCmd(wrap))
     .command(approvalsCmd(wrap))
     .command(perfCmd(wrap))
+    .command(diffCmd(wrap))
     .command(evalCmd(wrap))
     .command(restCmd(wrap))
     .command(skillCmd(wrap))

package/src/commands/diff.js

@@ -0,0 +1,205 @@
+import { declareCapabilities } from '../capabilities.js';
+import { errUsage, errUsageHint } from '../errors.js';
+import { resolveSession } from '../session.js';
+import { resolveRecord } from '../resolve-record.js';
+
+declareCapabilities('diff', {});
+
+const DEFAULT_IGNORED_FIELDS = [
+  'sys_created_by',
+  'sys_created_on',
+  'sys_mod_count',
+  'sys_updated_by',
+  'sys_updated_on',
+];
+
+function profileTarget(app, name, label) {
+  const session = resolveSession({ profile: name }, app.config);
+  if (session.unknownProfile || !session.profileName) {
+    throw errUsageHint(`Unknown ${label} profile "${name}"`, 'Run "jsn auth status" to list configured profiles.');
+  }
+  if (!session.instance || !session.profile) {
+    throw errUsage(`Profile "${name}" has no configured instance URL`);
+  }
+  return {
+    name: session.profileName,
+    instance: session.instance,
+    profile: session.profile,
+    username: session.username || '',
+    domain: session.domain || '',
+  };
+}
+
+function sdkForProfile(app, target) {
+  return app.getSDKForProfile(target.instance, {
+    profile: target.profile,
+    profileName: target.name,
+    username: target.username,
+    authMethod: target.profile.auth_method,
+    domain: target.domain,
+  });
+}
+
+async function fetchRecord(app, target, table, identifier) {
+  try {
+    const record = await resolveRecord(sdkForProfile(app, target), {
+      table,
+      identifier,
+      matchField: 'sys_id',
+      resource: 'Record',
+    });
+    return { status: 'found', record };
+  } catch (error) {
+    if (error?.code === 'not_found') return { status: 'missing', record: null };
+    if (error?.code === 'forbidden') return { status: 'forbidden', record: null, error: error.code };
+    if (error?.code === 'auth_error') return { status: 'auth_error', record: null, error: error.code };
+    return { status: 'error', record: null, error: error?.code || 'error' };
+  }
+}
+
+function stableValue(value) {
+  if (value && typeof value === 'object' && Object.hasOwn(value, 'value')) return value.value;
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.keys(value).sort().map(key => [key, stableValue(value[key])]));
+  }
+  return value;
+}
+
+function equalValue(a, b) {
+  return JSON.stringify(stableValue(a)) === JSON.stringify(stableValue(b));
+}
+
+function displayValue(value) {
+  if (value && typeof value === 'object' && value.display_value != null) return String(value.display_value);
+  if (value == null) return 'null';
+  if (typeof value === 'object') return JSON.stringify(value);
+  return String(value);
+}
+
+function fieldDifference(field, status, a, b) {
+  return {
+    field,
+    status,
+    ...(a !== undefined ? { a } : {}),
+    ...(b !== undefined ? { b } : {}),
+  };
+}
+
+export function compareRecords(recordA, recordB, ignoredFields = DEFAULT_IGNORED_FIELDS) {
+  const ignored = new Set(ignoredFields);
+  const fields = [...new Set([
+    ...Object.keys(recordA || {}),
+    ...Object.keys(recordB || {}),
+  ])].filter(field => !ignored.has(field)).sort();
+  const differences = [];
+  for (const field of fields) {
+    const hasA = Object.hasOwn(recordA || {}, field);
+    const hasB = Object.hasOwn(recordB || {}, field);
+    if (!hasA && hasB) differences.push(fieldDifference(field, 'added', undefined, recordB[field]));
+    else if (hasA && !hasB) differences.push(fieldDifference(field, 'missing', recordA[field], undefined));
+    else if (!equalValue(recordA[field], recordB[field])) differences.push(fieldDifference(field, 'changed', recordA[field], recordB[field]));
+  }
+  return differences;
+}
+
+export function formatRecordDiff(data) {
+  const lines = [
+    `Record diff: ${data.table} ${data.identifiers.a}`,
+    `A: ${data.profiles.a.name} (${data.existence.a})`,
+    `B: ${data.profiles.b.name} (${data.existence.b})`,
+    `Status: ${data.status}`,
+  ];
+  if (data.status === 'error' || data.status === 'forbidden' || data.status === 'auth_error' || data.status === 'missing' || data.status === 'both_missing') return `${lines.join('\n')}\n`;
+  lines.push(`Ignored: ${data.ignored_fields.join(', ') || '(none)'}`);
+  if (data.differences.length === 0) lines.push('No field differences');
+  for (const difference of data.differences) {
+    const left = difference.a === undefined ? '(missing)' : displayValue(difference.a);
+    const right = difference.b === undefined ? '(missing)' : displayValue(difference.b);
+    lines.push(`${difference.status.toUpperCase()} ${difference.field}: ${left} -> ${right}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function ignoredFields(argv) {
+  if (argv['no-ignore']) return [];
+  return [...new Set([...DEFAULT_IGNORED_FIELDS, ...(argv.ignore || [])])].sort();
+}
+
+export function diffCmd(wrap) {
+  return {
+    command: 'diff [subcommand]',
+    describe: 'Compare records across configured profiles (read-only)',
+    builder: (y) => y.command({
+      command: 'record',
+      describe: 'Compare one record across two profiles',
+      builder: (b) => b
+        .option('table', { type: 'string', demandOption: true, describe: 'ServiceNow table' })
+        .option('sys-id', { type: 'string', demandOption: true, describe: 'Record sys_id or exact identifier' })
+        .option('profile-a', { type: 'string', demandOption: true, describe: 'Profile for side A' })
+        .option('profile-b', { type: 'string', demandOption: true, describe: 'Profile for side B' })
+        .option('ignore', { type: 'string', array: true, default: [], describe: 'Additional field to ignore (repeatable)' })
+        .option('no-ignore', { type: 'boolean', default: false, describe: 'Do not ignore system noise fields' }),
+      handler: wrap(async (argv, app) => {
+        const table = String(argv.table || '').trim();
+        const identifier = String(argv['sys-id'] || '').trim();
+        if (!table || !identifier) throw errUsage('diff record requires --table and --sys-id');
+        if (argv['profile-a'] === argv['profile-b']) throw errUsage('Profile A and profile B must be different');
+        const targetA = profileTarget(app, argv['profile-a'], 'profile-a');
+        const targetB = profileTarget(app, argv['profile-b'], 'profile-b');
+        const [sideA, sideB] = await Promise.all([
+          fetchRecord(app, targetA, table, identifier),
+          fetchRecord(app, targetB, table, identifier),
+        ]);
+        const ignored = ignoredFields(argv);
+        let status = 'error';
+        let differences = [];
+        if (sideA.status === 'found' && sideB.status === 'found') {
+          differences = compareRecords(sideA.record, sideB.record, ignored);
+          status = differences.length ? 'different' : 'equal';
+        } else if (sideA.status === 'missing' && sideB.status === 'missing') {
+          status = 'both_missing';
+        } else if (sideA.status === 'missing' || sideB.status === 'missing') {
+          status = 'missing';
+        } else if (sideA.status === 'forbidden' || sideB.status === 'forbidden') {
+          status = 'forbidden';
+        } else if (sideA.status === 'auth_error' || sideB.status === 'auth_error') {
+          status = 'auth_error';
+        }
+        const data = {
+          table,
+          identifiers: { a: identifier, b: identifier },
+          profiles: {
+            a: { name: targetA.name, instance: targetA.instance },
+            b: { name: targetB.name, instance: targetB.instance },
+          },
+          existence: { a: sideA.status, b: sideB.status },
+          errors: { a: sideA.error || null, b: sideB.error || null },
+          ignored_fields: ignored,
+          status,
+          differences,
+          _formatted: formatRecordDiff({
+            table,
+            identifiers: { a: identifier },
+            profiles: dataProfiles(targetA, targetB),
+            existence: { a: sideA.status, b: sideB.status },
+            ignored_fields: ignored,
+            status,
+            differences,
+          }),
+        };
+        app.ok(data, { summary: `Record diff ${status}: ${table} ${identifier}` });
+      }),
+    }),
+    handler: wrap(async (_argv, app) => {
+      app.ok({ command: 'diff', subcommands: ['record'] }, { summary: 'Use `jsn diff record --help` for details.' });
+    }),
+  };
+}
+
+function dataProfiles(targetA, targetB) {
+  return {
+    a: { name: targetA.name, instance: targetA.instance },
+    b: { name: targetB.name, instance: targetB.instance },
+  };
+}