@jacebenson/jsn 4.3.12 → 4.3.13-dev.72.1

package/README.md

@@ -13,6 +13,47 @@ jsn setup
 
 See the [setup guide](docs/docs-setup.md) to connect an instance safely.
 
+### Dev channel
+
+For the newest changes from `main`, including changes that may be unstable:
+
+```bash
+npm install -g @jacebenson/jsn@dev
+```
+
+Dev builds check the dev channel for updates during normal use, at most once
+per day. Run `jsn version --check` to check immediately. To install the newest
+dev build, run `npm install -g @jacebenson/jsn@dev` again. Updates are manual.
+Return to stable with `npm install -g @jacebenson/jsn@latest`.
+
+Pushes to `main` promote the commit to `dev` and publish a tested prerelease
+under npm's `dev` tag. Versions include the workflow run number and attempt
+(for example, `4.3.9-dev.123.1`); they do not move npm's stable `latest` tag.
+The npm trusted publisher for `publish-dev.yml` must authorize the repository's
+`dev` GitHub environment, alongside the production publishing configuration.
+
+### Supported versions
+
+Only the current release and the two preceding releases in each channel are
+supported (three stable releases and three dev builds). For example, with
+stable `4.3.11`, versions `4.3.11`, `4.3.10`, and `4.3.9` are supported.
+Update to the newest version in your channel before reporting an issue.
+
+After each successful npm publish, deployment deprecates older versions in that
+channel. Deprecated versions remain installable and appear in history, but npm
+prints an update warning on installation. Existing deprecation messages are
+preserved. No versions are unpublished.
+
+The deprecation step uses the repository's `NPM_TOKEN` secret with permission to
+modify `@jacebenson/jsn` and noninteractive authentication (including bypass 2FA
+where required). Publishing continues to use OIDC. A deprecation failure fails
+the workflow after publishing; it does not roll back the published package.
+To retry only deprecation after fixing authentication, use the matching release
+checkout and run `node scripts/deprecate-old-versions.mjs latest --apply` (or
+`dev --apply`) with npm authentication configured and `NODE_AUTH_TOKEN` set.
+Omit `--apply` to preview the affected versions without changing npm. The script
+requires the checkout's package version to match the channel's current npm tag.
+
 ## Try it
 
 ```bash

package/package.json

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

package/src/app.js

@@ -8,6 +8,7 @@
 // command handlers that already call them.
 
 import { AuthManager } from './auth.js';
+import { createAuthRecovery } from './auth-recovery.js';
 import { SDKClient } from './sdk.js';
 import { OutputWriter, FormatAuto, FormatJSON, FormatMarkdown, FormatQuiet, FormatStyled, hyperlink } from './output.js';
 import { saveConfig } from './config.js';
@@ -53,8 +54,11 @@ export class App {
 
   /** Build (or rebuild) the SDK client for an instance + session. */
   _buildSdk(instance, session = this.session) {
-    this.sdk = new SDKClient(instance, this.auth, {
+    this.sdk = new SDKClient(instance, this.auth.createProfileProvider(instance, {
+      username: session?.username, authMethod: session?.profile?.auth_method,
+    }), {
       domain: session?.domain || '',
+      recovery: createAuthRecovery({ app: this, session }),
     });
   }
 

package/src/auth-recovery.js

@@ -0,0 +1,74 @@
+import { errAPI } from './errors.js';
+import { canUsePicker, quoteShellArg } from './helpers.js';
+import { confirm } from './prompts.js';
+
+// Recovery is scoped to the SDK's resolved identity, never the mutable default.
+// error supplies the same safe guidance if the single retry is also rejected.
+export function createAuthRecovery({ app, session, argv = () => app._authArgv || {},
+  canInteract = canUsePicker, prompt = confirm,
+  renewBrowser = async (request, targetApp) => {
+    const { refreshProfile } = await import('./commands/auth.js');
+    return refreshProfile(request, targetApp);
+  },
+}) {
+  const { instance, profileName, username, profile } = session;
+  const target = profileName ? `--profile ${quoteShellArg(profileName)}` : quoteShellArg(instance);
+  const label = profileName ? `profile ${quoteShellArg(profileName)}` : 'the active profile';
+  function failure(method = profile?.auth_method) {
+    const error = errAPI(401, '');
+    const login = `jsn auth login ${target}`;
+    error.message = `Authentication rejected for ${label} (HTTP 401).`;
+    error.profile = profileName || null;
+    error.recovery = method === 'basic'
+      ? `jsn auth login --basic ${quoteShellArg(instance)}${profileName ? ` --profile ${quoteShellArg(profileName)}` : ''}`
+      : method === 'gck' ? `jsn auth refresh ${target} --browser`
+      : method === 'oauth' ? `jsn auth refresh ${target}` : login;
+    error.hint = method === 'basic'
+      ? `Set SN_USERNAME/SN_PASSWORD to the correct credentials, then run: ${error.recovery}`
+      : method === 'oauth'
+        ? `Run interactively: ${error.recovery}. If refresh fails, run: ${login}`
+        : `Run: ${error.recovery}`;
+    return error;
+  }
+  // Keep the settled promise too: this provider gets only one recovery attempt.
+  let recoveryAttempt;
+  const provider = {
+    error: failure(),
+    async recover({ status }) {
+      if (status !== 401) return false;
+      return recoveryAttempt ??= recoverOnce();
+    },
+  };
+  async function recoverOnce() {
+    let creds;
+    try {
+      creds = await app.auth.getCredentialsFor(instance, username, {
+        username, authMethod: profile?.auth_method, refresh: false,
+      });
+    } catch { throw provider.error; }
+    const method = profile?.auth_method || creds.auth_method;
+    provider.error = failure(method);
+    if (method === 'oauth' && creds.refresh_token) {
+      try {
+        await app.auth.refreshToken(instance, creds, username ?? null);
+        return true;
+      } catch { throw provider.error; }
+    }
+    if (method === 'gck' && profileName && ['auto', 'confirm'].includes(profile?.reauth ?? 'confirm')
+      && canInteract(app, argv())) {
+      try {
+        if ((profile?.reauth ?? 'confirm') === 'confirm'
+          && !await prompt({ message: `Sign in again in a browser for ${label}?`, default: false })) throw provider.error;
+        // Reuse the canonical GCK refresh/login operation without emitting a
+        // second success envelope or replacing the in-flight command's SDK.
+        const targetApp = Object.create(app);
+        targetApp.ok = () => {};
+        targetApp.sdk = app.getSDKForProfile(instance, { profile, authMethod: 'gck', username });
+        await renewBrowser({ profile: profileName, browser: true }, targetApp);
+        return true;
+      } catch { throw provider.error; }
+    }
+    throw provider.error;
+  }
+  return provider;
+}

package/src/cli-adapter.js

@@ -3,6 +3,14 @@ import process from 'node:process';
 
 const camel = (name) => name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 const names = (x) => typeof x === 'string' ? [x] : (x || []);
+
+/**
+ * A repeatable option may be declared either way: `type: 'array'` (this
+ * adapter's historic spelling) or `array: true` (the yargs spelling most
+ * contributors reach for). Both must accumulate; honoring only the first
+ * silently kept the LAST value of `-f a=1 -f b=2` and dropped the rest.
+ */
+const isArrayOption = (spec) => spec?.type === 'array' || spec?.array === true;
 const commandName = (command) => command.trim().split(/\s+/)[0];
 const positionSpec = (command) => [...command.matchAll(/([<[])([^>\]]+)[>\]]/g)].map((m) => ({ name: m[2], required: m[1] === '<' }));
 
@@ -189,7 +197,7 @@ export class LocalCLI {
   _assign(argv, key, value, spec, opts = {}) {
     const validate = opts.validate !== false;
     const actual = spec?.name || key;
-    const values = spec?.type === 'array' ? (Array.isArray(value) ? value : [value]) : [value];
+    const values = isArrayOption(spec) ? (Array.isArray(value) ? value : [value]) : [value];
     if (validate && spec?.choices && values.some((item) => !spec.choices.includes(item))) {
       this._fail(`Invalid value for --${actual}: ${value}. Choose from: ${spec.choices.join(', ')}`);
       return false;
@@ -201,7 +209,7 @@ export class LocalCLI {
     const converted = spec?.type === 'boolean'
       ? (value === 'true' ? true : value === 'false' ? false : value)
       : spec?.type === 'number' ? Number(value) : value;
-    if (spec?.type === 'array') argv[actual] = [...(argv[actual] || []), ...values];
+    if (isArrayOption(spec)) argv[actual] = [...(argv[actual] || []), ...values];
     else argv[actual] = converted;
     argv[camel(actual)] = argv[actual];
     for (const alias of names(spec?.alias)) argv[alias] = argv[actual];
@@ -210,8 +218,8 @@ export class LocalCLI {
     const options = this._optionConfig(path);
     const defs = {};
     for (const [key, spec] of options) defs[key] = {
-      type: spec.type === 'number' || spec.type === 'array' ? 'string' : (spec.type || 'boolean'),
-      multiple: spec.type === 'array',
+      type: spec.type === 'number' || isArrayOption(spec) ? 'string' : (spec.type || 'boolean'),
+      multiple: isArrayOption(spec),
     };
     args = args.map((arg) => {
       if (/^-[^-]=/.test(arg)) return `--${arg.slice(1)}`;

package/src/cli.js

@@ -36,7 +36,7 @@ import { platformCmd } from './commands/platform.js';
 import { codesearchCmd } from './commands/codesearch.js';
 import { versionCmd } from './commands/version.js';
 import { skillCmd, checkSkill } from './commands/skill.js';
-import { getVersion, checkLatest } from './commands/version.js';
+import { getVersion, checkLatest, getReleaseChannel, getInstallCommand } from './commands/version.js';
 import { docsCmd } from './commands/docs/docs.js';
 
 // Table and platform commands registered at root level for progressive disclosure
@@ -213,6 +213,7 @@ export function buildCLI() {
               hint: 'Run "jsn auth status" to list profiles.',
             });
           }
+          app._authArgv = argv;
           applySession(app, session);
         } catch (err) {
           guardExit(argv, { code: err.code || 'usage', message: err.message, hint: err.hint });
@@ -290,7 +291,7 @@ export function buildCLI() {
         }
       }
       if (!skipNpmCheck) {
-        const cacheFile = path.join(globalConfigDir(), '.last-npm-check');
+        const cacheFile = path.join(globalConfigDir(), `.last-npm-check-${getReleaseChannel()}`);
         let shouldCheck = true;
         try {
           const mtime = fs.statSync(cacheFile).mtimeMs;
@@ -303,9 +304,9 @@ export function buildCLI() {
 
         if (shouldCheck) {
           const version = getVersion();
-          checkLatest({ background: true }).then(latest => {
+          checkLatest({ background: true, version }).then(latest => {
             if (latest && version !== latest) {
-              process.stderr.write(`\n⚠ jsn ${latest} available (you have ${version}) — run "npm install -g @jacebenson/jsn" to update\n\n`);
+              process.stderr.write(`\n⚠ jsn ${latest} available (you have ${version}) — run "${getInstallCommand(version)}" to update\n\n`);
             }
           }).catch(() => {});
 

package/src/commands/_generic.js

@@ -1,6 +1,6 @@
 // Generic table-based CRUD command builder
 
-import { formatRecordForDisplay, getStringField, parseDataArg, confirmDelete, interactiveList, canPrompt } from '../helpers.js';
+import { formatRecordForDisplay, getStringField, buildRecordPayload, confirmDelete, interactiveList, canPrompt } from '../helpers.js';
 import { resolveRecord, unwrapSysId } from '../resolve-record.js';
 import { getCurrentUser, getCurrentApplication } from '../context.js';
 import { FormatAuto } from '../output.js';
@@ -108,7 +108,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
     if (!readOnly) {
       crumbs.unshift(
         { action: 'delete', cmd: `jsn ${name} delete ${id}`, description: `Delete this ${singular}` },
-        { action: 'update', cmd: `jsn ${name} update ${id} --data '{...}'`, description: `Update this ${singular}` }
+        { action: 'update', cmd: `jsn ${name} update ${id} -f name=value`, description: `Update this ${singular}` }
       );
     }
     return crumbs;
@@ -152,7 +152,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
             app.ok(record, {
               summary: `${singular.charAt(0).toUpperCase() + singular.slice(1)}: ${recordName}`,
               breadcrumbs: [
-                ...(readOnly ? [] : [{ action: 'update', cmd: `jsn ${name} update ${recordName} --data '{...}'`, description: `Update this ${singular}` }]),
+                ...(readOnly ? [] : [{ action: 'update', cmd: `jsn ${name} update ${recordName} -f name=value`, description: `Update this ${singular}` }]),
                 { action: 'list', cmd: `jsn ${name} list`, description: `Back to all ${name}` },
               ],
             });
@@ -215,10 +215,12 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
           command: 'create',
           describe: `Create a new ${singular}`,
           builder: (y) => y
-            .option('data', { type: 'string', describe: 'JSON fields (e.g. \'{"state":"2"}\')' })
-            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' }),
+            .option('data', { type: 'string', describe: 'JSON fields' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
-            const recordData = parseDataArg(argv);
+            const recordData = buildRecordPayload(argv);
             const record = await app.sdk.create(table, recordData);
             app.ok(record, {
               summary: `Created ${singular}`,
@@ -232,8 +234,10 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
           command: 'update <identifier>',
           describe: `Update ${vowelArticle(singular)} ${singular}`,
           builder: (y) => y
-            .option('data', { type: 'string', describe: 'JSON fields (e.g. \'{"state":"2"}\')' })
-            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' }),
+            .option('data', { type: 'string', describe: 'JSON fields' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
             const id = argv.identifier;
             const record = await resolveRecord(app.sdk, { table, identifier: id, matchField: 'name', resource: singular });
@@ -242,7 +246,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
             }
 
             const sysID = unwrapSysId(record);
-            const recordData = parseDataArg(argv);
+            const recordData = buildRecordPayload(argv);
             const updated = await app.sdk.update(table, sysID, recordData);
             app.ok(updated, { summary: `Updated ${singular} ${id}` });
           }),

package/src/commands/_ticket.js

@@ -1,7 +1,7 @@
 // Generic command builder for CRUD operations on a ServiceNow table
 // Used by incidents, changes, requests, tasks, and most dev subcommands
 
-import { getStringField, formatRecordForDisplay, buildQuerySuffix, resolveFieldsParam, confirmDelete, interactiveList, canPrompt } from '../helpers.js';
+import { getStringField, formatRecordForDisplay, buildQuerySuffix, resolveFieldsParam, confirmDelete, interactiveList, canPrompt, buildRecordPayload } from '../helpers.js';
 import { resolveRecord, resolveSysId } from '../resolve-record.js';
 import { FormatAuto } from '../output.js';
 import { declareCapabilities } from '../capabilities.js';
@@ -73,7 +73,7 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
               app.ok(record, {
                 summary: `${displayName.charAt(0).toUpperCase() + displayName.slice(1)} ${number}`,
                 breadcrumbs: [
-                  { action: 'update', cmd: `jsn ${alias} update ${number} --data '{...}'`, description: `Update this ${displayName}` },
+                  { action: 'update', cmd: `jsn ${alias} update ${number} -f state=2`, description: `Update this ${displayName}` },
                   { action: 'list', cmd: `jsn ${alias} list`, description: `Back to all ${table}` },
                 ],
               });
@@ -139,7 +139,7 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
             app.ok(record, {
               summary: `${displayName.charAt(0).toUpperCase() + displayName.slice(1)} ${number}`,
               breadcrumbs: [
-                { action: 'update', cmd: `jsn ${alias} update ${number} --data '{...}'`, description: `Update this ${displayName}` },
+                { action: 'update', cmd: `jsn ${alias} update ${number} -f state=2`, description: `Update this ${displayName}` },
                 { action: 'list', cmd: `jsn ${alias} list`, description: `Back to all ${table}` },
               ],
             });
@@ -151,16 +151,16 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
           builder: (y) => y
             .option('description', { alias: 'd', type: 'string', describe: 'Short description' })
             .option('priority', { type: 'string', describe: 'Priority (1-5)' })
-            .option('data', { type: 'string', describe: 'JSON data for additional fields' }),
+            .option('data', { type: 'string', describe: 'JSON data for additional fields' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
-            const recordData = {};
-            if (argv.data) {
-              Object.assign(recordData, JSON.parse(argv.data));
-            }
+            const recordData = buildRecordPayload(argv, { required: false });
             if (argv.description) recordData.short_description = argv.description;
             if (argv.priority) recordData.priority = argv.priority;
             if (!recordData.short_description) {
-              throw new Error('short_description is required (use --description or --data)');
+              throw new Error('short_description is required (use --description, -f short_description=..., or --data)');
             }
             const record = await app.sdk.create(table, recordData);
             app.ok(record, {
@@ -175,10 +175,13 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
           command: 'update <number>',
           describe: `Update a ${displayName}`,
           builder: (y) => y
-            .option('data', { type: 'string', demandOption: true, describe: 'JSON data to update' }),
+            .option('data', { type: 'string', describe: 'JSON data to update' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
             const number = argv.number;
-            const recordData = JSON.parse(argv.data);
+            const recordData = buildRecordPayload(argv);
             const sysID = await resolveSysId(app.sdk, { table, identifier: number, matchField: 'number', resource: displayName });
             const updated = await app.sdk.update(table, sysID, recordData);
             app.ok(updated, {

package/src/commands/auth.js

@@ -382,13 +382,18 @@ export async function modifyProfile(app, argv = {}) {
   const name = argv.name || argv.profile || await pickProfile(app, 'Modify which profile?', argv);
   const profile = app.config.profiles?.[name];
   if (!profile) throw new Error(`Profile not found: ${name}`);
-  const explicitSettings = ['read-only', 'skip-confirmations', 'include-counts'].some(flag => argv[flag] !== undefined);
+  if (argv.reauth !== undefined && !['auto', 'confirm', 'never'].includes(argv.reauth)) {
+    throw errUsage('--reauth must be auto, confirm, or never.');
+  }
+  const explicitSettings = ['read-only', 'skip-confirmations', 'include-counts', 'reauth'].some(flag => argv[flag] !== undefined);
   if (explicitSettings) {
     if (argv.domain !== undefined) throw errUsage('Set profile preferences and domain separately.');
     const updated = await configureProfileOptions({ ...profile }, argv);
+    if (argv.reauth !== undefined) updated.reauth = argv.reauth;
     app.config.profiles[name] = updated;
     await saveConfig(app.config);
-    app.ok({ profile: name, read_only: updated.read_only === true, confirm_deletes: updated.skip_confirmations !== true, include_counts: updated.include_counts !== false },
+    app.ok({ profile: name, read_only: updated.read_only === true, confirm_deletes: updated.skip_confirmations !== true, include_counts: updated.include_counts !== false,
+      ...(argv.reauth !== undefined ? { reauth: updated.reauth } : {}) },
       { summary: `Settings saved for ${name}` });
     return;
   }
@@ -1134,6 +1139,7 @@ export function authCmd(wrap) {
             .option('read-only', { type: 'boolean', describe: 'Set read-only access (use --no-read-only to allow writes)' })
             .option('include-counts', { type: 'boolean', describe: 'Set result counts (use --no-include-counts to disable)' })
             .option('confirm-deletes', { type: 'boolean', describe: 'Set delete confirmations (use --no-confirm-deletes to disable)' })
+            .option('reauth', { type: 'string', choices: ['auto', 'confirm', 'never'], describe: 'Browser recovery policy: auto, confirm (default), or never; interactive only' })
             .option('skip-confirmations', { type: 'boolean', describe: 'Compatibility flag: disable delete confirmations' })
             .positional('name', {
               describe: 'Profile name to modify',

package/src/commands/groups.js

@@ -1,4 +1,4 @@
-import { formatRecordForDisplay, getStringField, interactiveList, resolveFieldsParam, assertSafeExactMatch } from '../helpers.js';
+import { formatRecordForDisplay, getStringField, interactiveList, resolveFieldsParam, assertSafeExactMatch, buildRecordPayload } from '../helpers.js';
 import { declareCapabilities } from '../capabilities.js';
 
 declareCapabilities('groups', { mutationSubcommands: ['create', 'update', 'delete'] });
@@ -94,12 +94,12 @@ export function groupsCmd(wrap) {
           builder: (y) => y
             .option('name', { alias: 'n', type: 'string', describe: 'Group name' })
             .option('manager', { type: 'string', describe: 'Manager name or sys_id' })
-            .option('data', { type: 'string', describe: 'JSON data for additional fields' }),
+            .option('data', { type: 'string', describe: 'JSON data for additional fields' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
-            const recordData = {};
-            if (argv.data) {
-              Object.assign(recordData, JSON.parse(argv.data));
-            }
+            const recordData = buildRecordPayload(argv, { required: false });
             if (argv.name) recordData.name = argv.name;
             if (argv.manager) recordData.manager = argv.manager;
             if (!recordData.name) {
@@ -118,11 +118,14 @@ export function groupsCmd(wrap) {
           command: 'update <name>',
           describe: 'Update a group by name or sys_id',
           builder: (y) => y
-            .option('data', { type: 'string', demandOption: true, describe: 'JSON data to update' }),
+            .option('data', { type: 'string', describe: 'JSON data to update' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
             const id = argv.name;
             assertSafeExactMatch(id);
-            const recordData = JSON.parse(argv.data);
+            const recordData = buildRecordPayload(argv);
             const isSysID = id.length === 32 && /^[0-9a-fA-F]+$/.test(id);
             const params = new URLSearchParams();
             params.set('sysparm_query', isSysID ? `sys_id=${id}` : `name=${id}`);

package/src/commands/records.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { formatCommandList, formatRecordForDisplay, buildQuerySuffix, parseDataArg, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, assertSafeExactMatch, verifyWriteBack } from '../helpers.js';
+import { formatCommandList, formatRecordForDisplay, buildQuerySuffix, buildRecordPayload, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, assertSafeExactMatch, verifyWriteBack } from '../helpers.js';
 import { declareCapabilities } from '../capabilities.js';
 
 declareCapabilities('records', {
@@ -142,7 +142,7 @@ export function recordsCmd(wrap) {
             }
 
             const breadcrumbs = [
-              { action: 'create', cmd: `jsn records create --table ${table} --data '{...}'`, description: 'Create a new record' },
+              { action: 'create', cmd: `jsn records create --table ${table} -f name=value`, description: 'Create a new record' },
               { action: 'filter', cmd: `jsn records list --table ${table} --query "priority=1"`, description: 'Filter: priority 1 only' },
               { action: 'columns', cmd: `jsn columns --table ${table}`, description: 'View available columns' },
             ];
@@ -221,12 +221,13 @@ export function recordsCmd(wrap) {
           describe: 'Create a new record',
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
-            .option('data', { type: 'string', describe: 'JSON fields (e.g. \'{"state":"2"}\')' })
+            .option('data', { type: 'string', describe: 'JSON fields' })
             .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
             .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin (pipe-friendly)' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' })
             .option('strict', { type: 'boolean', default: false, describe: 'Exit non-zero if any supplied field was not persisted (write-back check)' }),
           handler: wrap(async (argv, app) => {
-            const recordData = parseDataArg(argv);
+            const recordData = buildRecordPayload(argv);
             const warnings = checkDerivedFields(argv.table, recordData);
             for (const w of warnings) {
               process.stderr.write(`⚠ ${w.hint}\n`);
@@ -249,12 +250,13 @@ export function recordsCmd(wrap) {
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
             .option('sys-id', { type: 'string', demandOption: true, describe: 'Record sys_id' })
-            .option('data', { type: 'string', describe: 'JSON fields (e.g. \'{"state":"2"}\')' })
+            .option('data', { type: 'string', describe: 'JSON fields' })
             .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
             .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin (pipe-friendly)' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' })
             .option('strict', { type: 'boolean', default: false, describe: 'Exit non-zero if any supplied field was not persisted (write-back check)' }),
           handler: wrap(async (argv, app) => {
-            const recordData = parseDataArg(argv);
+            const recordData = buildRecordPayload(argv);
             const warnings = checkDerivedFields(argv.table, recordData);
             for (const w of warnings) {
               process.stderr.write(`⚠ ${w.hint}\n`);
@@ -401,22 +403,15 @@ export function recordsCmd(wrap) {
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
             .option('query', { type: 'string', demandOption: true, describe: 'Encoded query selecting the records to update (e.g. "priority=1^state=1")' })
-            .option('set', { type: 'string', demandOption: true, describe: 'JSON object of fields to set (e.g. \'{"state":"3"}\')' })
+            .option('set', { type: 'string', describe: 'JSON object of fields to set' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' })
             .option('dry-run', { type: 'boolean', default: true, describe: 'Preview the count + a sample without mutating (default)' })
             .option('execute', { type: 'boolean', default: false, describe: 'Perform the update after confirmation' })
             .option('limit', { type: 'number', default: 200, describe: 'Max records to update when executing' })
             .option('force', { type: 'boolean', default: false, describe: 'Skip confirmation (with --execute)' }),
           handler: wrap(async (argv, app) => {
             app.requireInstance();
-            let set;
-            try {
-              set = JSON.parse(argv.set);
-            } catch (e) {
-              throw new Error(`Invalid --set JSON: ${e.message}`, { cause: e });
-            }
-            if (!set || typeof set !== 'object' || Array.isArray(set)) {
-              throw new Error('--set must be a JSON object of field=value pairs');
-            }
+            const set = buildRecordPayload({ ...argv, data: argv.set }, { required: true });
             if (!argv['dry-run'] && !argv.execute) {
               argv.execute = true; // explicit --no-dry-run implies execute intent
             }

package/src/commands/requests.js

@@ -53,7 +53,7 @@ async function enrichedShowHandler(argv, app) {
   app.ok(record, {
     summary: `Request ${number}`,
     breadcrumbs: [
-      { action: 'update', cmd: `jsn req update ${number} --data '{...}'`, description: 'Update this request' },
+      { action: 'update', cmd: `jsn req update ${number} -f state=2`, description: 'Update this request' },
       { action: 'list', cmd: `jsn req list`, description: 'Back to all requests' },
     ],
   });

package/src/commands/tickets.js

@@ -1,4 +1,4 @@
-import { formatRecordForDisplay, getStringField, buildQuerySuffix, resolveFieldsParam } from '../helpers.js';
+import { formatRecordForDisplay, getStringField, buildQuerySuffix, resolveFieldsParam, buildRecordPayload } from '../helpers.js';
 import { resolveRecord, resolveSysId } from '../resolve-record.js';
 import { declareCapabilities } from '../capabilities.js';
 
@@ -33,7 +33,7 @@ export function ticketsCmd(wrap) {
             const records = await app.sdk.list('task', params);
             const displayRecords = fields ? records.map(r => formatRecordForDisplay(r, columns)) : records;
             const breadcrumbs = [
-              { action: 'create', cmd: 'jsn tickets create --data \'{...}\'', description: 'Create a new ticket' },
+              { action: 'create', cmd: 'jsn tickets create -f short_description=New ticket', description: 'Create a new ticket' },
             ];
             if (records.length === argv.limit) {
               breadcrumbs.push({
@@ -71,9 +71,13 @@ export function ticketsCmd(wrap) {
         .command({
           command: 'create',
           describe: 'Create a new ticket',
-          builder: (y) => y.option('data', { type: 'string', demandOption: true, describe: 'JSON fields (e.g. \'{"state":"2","priority":"1"}\')' }),
+          builder: (y) => y
+            .option('data', { type: 'string', describe: 'JSON fields' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
-            const recordData = JSON.parse(argv.data);
+            const recordData = buildRecordPayload(argv);
             const record = await app.sdk.create('task', recordData);
             app.ok(record, { summary: `Created ticket ${getStringField(record, 'number')}` });
           }),
@@ -81,9 +85,13 @@ export function ticketsCmd(wrap) {
         .command({
           command: 'update <number>',
           describe: 'Update a ticket',
-          builder: (y) => y.option('data', { type: 'string', demandOption: true, describe: 'JSON fields (e.g. \'{"state":"2","priority":"1"}\')' }),
+          builder: (y) => y
+            .option('data', { type: 'string', describe: 'JSON fields' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
-            const recordData = JSON.parse(argv.data);
+            const recordData = buildRecordPayload(argv);
             const sysID = await resolveSysId(app.sdk, { table: 'task', identifier: argv.number, matchField: 'number', resource: 'Ticket' });
             const updated = await app.sdk.update('task', sysID, recordData);
             app.ok(updated, { summary: `Updated ticket ${argv.number}` });

package/src/commands/users.js

@@ -1,4 +1,4 @@
-import { formatRecordForDisplay, getStringField, interactiveList, resolveFieldsParam } from '../helpers.js';
+import { formatRecordForDisplay, getStringField, interactiveList, resolveFieldsParam, buildRecordPayload } from '../helpers.js';
 import { resolveRecord, resolveSysId } from '../resolve-record.js';
 import { declareCapabilities } from '../capabilities.js';
 
@@ -72,12 +72,12 @@ export function usersCmd(wrap) {
             .option('username', { alias: 'u', type: 'string', describe: 'Username (e.g. john.doe)' })
             .option('name', { alias: 'n', type: 'string', describe: 'Full name (e.g. John Doe)' })
             .option('email', { alias: 'e', type: 'string', describe: 'Email address' })
-            .option('data', { type: 'string', describe: 'JSON data for additional fields' }),
+            .option('data', { type: 'string', describe: 'JSON data for additional fields' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
-            const recordData = {};
-            if (argv.data) {
-              Object.assign(recordData, JSON.parse(argv.data));
-            }
+            const recordData = buildRecordPayload(argv, { required: false });
             if (argv.username) recordData.user_name = argv.username;
             if (argv.name) recordData.name = argv.name;
             if (argv.email) recordData.email = argv.email;
@@ -97,10 +97,13 @@ export function usersCmd(wrap) {
           command: 'update <identifier>',
           describe: 'Update a user by user_name or sys_id',
           builder: (y) => y
-            .option('data', { type: 'string', demandOption: true, describe: 'JSON data to update' }),
+            .option('data', { type: 'string', describe: 'JSON data to update' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
             const id = argv.identifier;
-            const recordData = JSON.parse(argv.data);
+            const recordData = buildRecordPayload(argv);
             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, {

package/src/commands/version.js

@@ -6,7 +6,13 @@ 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`;
+export function getReleaseChannel(version = getVersion()) {
+  return /^\d+\.\d+\.\d+-dev\./.test(version) ? 'dev' : 'latest';
+}
+
+export function getInstallCommand(version = getVersion()) {
+  return `npm install -g ${NPM_PKG}${getReleaseChannel(version) === 'dev' ? '@dev' : ''}`;
+}
 
 export function getVersion() {
   try {
@@ -26,16 +32,16 @@ export function cancelBackgroundChecks() {
   backgroundChecks.clear();
 }
 
-export async function checkLatest({ timeout = 1500, background = false } = {}) {
+export async function checkLatest({ timeout = 1500, background = false, version = getVersion() } = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeout);
   timer.unref();
   if (background) backgroundChecks.add(controller);
   try {
-    const res = await fetch(NPM_REGISTRY, { signal: controller.signal });
+    const res = await fetch(`https://registry.npmjs.org/${NPM_PKG}/${getReleaseChannel(version)}`, { signal: controller.signal });
     if (!res.ok) return null;
     const data = await res.json();
-    return data.version;
+    return typeof data.version === 'string' ? data.version : null;
   } catch {
     return null;
   } finally {
@@ -58,11 +64,11 @@ export function versionCmd(wrap) {
       const version = getVersion();
 
       if (argv.check) {
-        const latest = await checkLatest();
+        const latest = await checkLatest({ version });
         if (!latest) {
           app.ok({ version }, {
             summary: `jsn ${version} (could not reach npm registry to check for updates)`,
-            notice: `Run \`npm view ${NPM_PKG}\` directly to check manually`,
+            notice: `Run \`npm view ${NPM_PKG}@${getReleaseChannel(version)} version\` directly to check manually`,
           });
           return;
         }
@@ -82,11 +88,11 @@ export function versionCmd(wrap) {
             version,
             latest,
             upToDate: false,
-            installCmd: `npm install -g ${NPM_PKG}`,
+            installCmd: getInstallCommand(version),
           }, {
             summary: `jsn ${version} — newer version ${latest} available`,
             breadcrumbs: [
-              { action: 'update', cmd: `npm install -g ${NPM_PKG}`, description: `Update jsn from ${version} to ${latest}` },
+              { action: 'update', cmd: getInstallCommand(version), description: `Update jsn from ${version} to ${latest}` },
             ],
           });
         }

package/src/errors.js

@@ -77,6 +77,16 @@ export function errNetwork(cause) {
 }
 
 export function errAPI(status, msg) {
+  // Authentication/authorization bodies can echo credentials. Never render them.
+  if (status === 401) {
+    const error = new AppError(CodeAuth, 'Authentication rejected for the active profile (HTTP 401).', 'Run: jsn auth login', 401);
+    error.recovery = 'jsn auth login';
+    return error;
+  }
+  if (status === 403) {
+    return new AppError(CodeForbidden, 'Access forbidden (HTTP 403).',
+      'This is an authorization/ACL/role problem, not a login problem. Check access to this endpoint.', 403);
+  }
   let hint = 'Check the API documentation for this endpoint.';
   if (status >= 500) {
     hint = 'The ServiceNow instance may be experiencing issues. Try again later.';
@@ -229,6 +239,11 @@ export function renderAppError(err, { app = null, argv = null, identifier = '' }
     return { stream: 'stderr', text, exitCode: 1 };
   }
 
+  if (code === CodeForbidden) {
+    if (resolveJsonMode(app, argv) && app) return { stream: 'stdout', text: null, exitCode: 1, appErr: true };
+    return { stream: 'stderr', text: `Error (forbidden): ${err.message}\n\nHint: ${err.hint}\n`, exitCode: 1 };
+  }
+
   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

package/src/helpers.js

@@ -522,6 +522,50 @@ export function parseDataArg(argv) {
   }
 }
 
+/**
+ * Parse repeatable -f/--field name=value options.
+ * Values remain strings, including empty values and values containing '='.
+ */
+export function parseFieldPairs(argv = {}) {
+  const raw = argv.field == null ? [] : (Array.isArray(argv.field) ? argv.field : [argv.field]);
+  const result = {};
+  for (const token of raw) {
+    const text = String(token);
+    const equals = text.indexOf('=');
+    if (equals < 0) throw new Error(`-f expects field=value, got "${text}"`);
+    const name = text.slice(0, equals);
+    let value = text.slice(equals + 1);
+    if (!name || /\\s/.test(name) || !/^[A-Za-z0-9_.]+$/.test(name)) {
+      throw new Error(`-f expects a valid field name, got "${name}"`);
+    }
+    if (value.startsWith('@@')) {
+      value = value.slice(1);
+    } else if (value.startsWith('@')) {
+      value = fs.readFileSync(value.slice(1), 'utf-8');
+      if (value.charCodeAt(0) === 0xFEFF) value = value.slice(1);
+    }
+    result[name] = value;
+  }
+  return result;
+}
+
+/**
+ * Build a record mutation payload from JSON input and/or field pairs.
+ */
+export function buildRecordPayload(argv = {}, { required = true } = {}) {
+  const hasData = Boolean(argv.data || argv['data-file'] || argv['data-stdin']);
+  const hasFields = argv.field != null && (Array.isArray(argv.field) ? argv.field.length > 0 : true);
+  if (!hasData && !hasFields) {
+    if (required) throw new Error('Provide fields with -f name=value, or a JSON payload with --data/--data-file/--data-stdin');
+    return {};
+  }
+  const payload = hasData ? parseDataArg(argv) : {};
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new Error('Record payload must be a JSON object');
+  }
+  return { ...payload, ...parseFieldPairs(argv) };
+}
+
 /**
  * Translate human-readable type names to ServiceNow item_option_new type IDs.
  * Maps common names like "date", "select", "multilinetext" to their integer IDs.

package/src/output.js

@@ -160,6 +160,11 @@ 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.status === 401 || e.status === 403) resp.status = e.status;
+    if (e.recovery) {
+      resp.recovery = e.recovery;
+      if (Object.hasOwn(e, 'profile')) resp.profile = e.profile;
+    }
     switch (format) {
       case FormatJSON:
       case FormatQuiet:

package/src/sdk.js

@@ -47,6 +47,7 @@ export class SDKClient {
   constructor(baseURL, authProvider, opts = {}) {
     this.baseURL = baseURL.replace(/\/$/, '');
     this.authProvider = authProvider;
+    this.recovery = opts.recovery;
     this.timeout = opts.timeout || DEFAULT_TIMEOUT;
     this.domain = opts.domain || '';
     this.oauthCookies = null;
@@ -100,23 +101,42 @@ export class SDKClient {
   async _withAuthenticatedRequest(endpoint, opts, {
     timeout = this.timeout, prepare, skipOAuthSession = false, normalizeErrors = false,
   }, consume = (response) => response) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeout);
-    try {
-      const req = new Request(endpoint, { ...opts, signal: controller.signal });
-      if (prepare) prepare(req);
-      await this._setAuth(req, { skipOAuthSession });
-      return await consume(await fetch(req));
-    } catch (err) {
-      if (normalizeErrors) {
-        if (err.name === 'AbortError') throw errNetwork(new Error('Request timed out'));
-        if (err.code === 'ECONNREFUSED' || err.code === 'ENOTFOUND' || err.code === 'ETIMEDOUT') {
-          throw errNetwork(err);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeout);
+      let rejection;
+      try {
+        const req = new Request(endpoint, { ...opts, signal: controller.signal });
+        if (prepare) prepare(req);
+        await this._setAuth(req, { skipOAuthSession });
+        const response = await fetch(req);
+        if (!skipOAuthSession && response.status === 401 && this.recovery) {
+          // Only a definitive HTTP rejection permits replay, including POST.
+          // Do not consume/echo the provider's potentially sensitive body.
+          rejection = { status: response.status, method: req.method, url: req.url };
+          await response.body?.cancel();
+        } else {
+          return await consume(response);
         }
+      } catch (err) {
+        if (normalizeErrors) {
+          if (err.name === 'AbortError') throw errNetwork(new Error('Request timed out'));
+          if (err.code === 'ECONNREFUSED' || err.code === 'ENOTFOUND' || err.code === 'ETIMEDOUT') {
+            throw errNetwork(err);
+          }
+        }
+        throw err;
+      } finally {
+        clearTimeout(timer);
       }
-      throw err;
-    } finally {
-      clearTimeout(timer);
+      // Browser renewal has its own existing hard timeout. Never leave a
+      // request timeout running while waiting for the human to authenticate.
+      if (attempt === 0 && await this.recovery.recover(rejection)) {
+        this.oauthCookies = null;
+        this.sessionUserToken = '';
+        continue;
+      }
+      throw this.recovery.error || errAPI(401, '');
     }
   }