@jacebenson/jsn 4.3.11 → 4.3.12-dev.70

package/src/auth.js

@@ -5,76 +5,20 @@
 // same instance have separate credential slots.
 
 import fs from 'node:fs';
-import path from 'node:path';
-import crypto from 'node:crypto';
-import { execFileSync } from 'node:child_process';
 import { password as passwordPrompt } from './prompts.js';
-import { globalConfigDir, normalizeInstanceURL } from './config.js';
+import { normalizeInstanceURL } from './config.js';
 import { errAuth } from './errors.js';
 import { pendingBrowserLogin } from './browser-auth.js';
+import { defaultCredentialStore } from './auth/credential-store.js';
+import { savePKCEState, loadPKCEState, removePKCEState, getOAuthClientID, generatePKCE, buildAuthURL, REDIRECT_URI } from './auth/oauth.js';
+import { parseBrowserSessionInput } from './auth/browser-session.js';
+import { normalizeAuthMethod, normalizeAuthSource, sourceMethod, probeFailure, classifyProbeError, classifyCredentialState } from './auth/credential-state.js';
 
-// ─── Credential key helpers ───
-
-/**
- * Sanitize an instance URL into a filesystem/arg-safe key part.
- *
- * Whitelist approach (issue #143 findings #2/#3): first map the `://`
- * protocol separator to `_` exactly as the Go version's encoding does
- * (so existing keyring keys like `https_dev437538.service-now.com` keep
- * matching), then drop everything outside [a-zA-Z0-9._-]. Blacklist
- * stripping of just `/` and `:` left quotes, `$()`, backticks, `;`,
- * spaces, and backslashes — which broke out of double-quoted shell args
- * in keyring calls and, on Windows, out of path.join() credential dirs.
- */
-export function sanitizeKeyPart(instance) {
-  return instance.replace(/:\/\//g, '_').replace(/[^a-zA-Z0-9._-]/g, '_');
-}
-
-/**
- * Build a compound key for credential storage: <username>@<instance>
- * When username is omitted (legacy), just the normalized instance URL is used.
- */
-function credKey(instance, username) {
-  const normalized = sanitizeKeyPart(instance);
-  if (!username) return normalized;
-  return `${username.replace(/[^a-zA-Z0-9._@-]/g, '_')}@${normalized}`;
-}
-
-// ─── PKCE state persistence (shared with Go version) ───
-
-function pkceStatePath(instance, username) {
-  const dir = path.join(globalConfigDir(), 'pkce');
-  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  // 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, username) {
-  const filePath = pkceStatePath(instance, username);
-  fs.writeFileSync(filePath, JSON.stringify(pkce, null, 2), { mode: 0o600 });
-}
-
-function loadPKCEState(instance, username) {
-  try {
-    const data = fs.readFileSync(pkceStatePath(instance, username), 'utf-8');
-    return JSON.parse(data);
-  } catch {
-    return null;
-  }
-}
-
-function removePKCEState(instance, username) {
-  try {
-    fs.unlinkSync(pkceStatePath(instance, username));
-  } catch {
-    // ignore
-  }
-}
+// Preserve the public auth module API while implementation stays separated.
+export { sanitizeKeyPart } from './auth/credential-store.js';
+export { parseBrowserSessionInput } from './auth/browser-session.js';
+export { classifyCredentialState } from './auth/credential-state.js';
 
-const DEFAULT_OAUTH_CLIENT_ID = '543e5655f77746a28228c6009a599dfb';
-const REDIRECT_URI = '/sdk-oauth.do';
 
 // ─── Basic auth from environment variables ───
 // SN_USERNAME / SN_PASSWORD — global credentials
@@ -110,322 +54,10 @@ function getBasicAuthFromEnv(instance) {
   return null;
 }
 
-// Keychain constants — same as Go version (internal/auth/store.go)
-const KEYRING_SERVICE = 'servicenow-cli';
-const KEYRING_ATTR_SERVICE = 'service';
-const KEYRING_ATTR_USERNAME = 'username';
-
-function credentialsFilePath(key) {
-  const dir = path.join(globalConfigDir(), 'credentials');
-  // Match Go's filename encoding: replace :// and / and : with _
-  const filename = key + '.json';
-  return path.join(dir, filename);
-}
-
-function credentialsPath(key) {
-  const filePath = credentialsFilePath(key);
-  fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
-  return filePath;
-}
-
-function getOAuthClientID() {
-  return process.env.SERVICENOW_OAUTH_CLIENT_ID || DEFAULT_OAUTH_CLIENT_ID;
-}
-
-function generatePKCE() {
-  const verifier = crypto.randomBytes(32).toString('base64url');
-  const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
-  const state = crypto.randomBytes(16).toString('base64url');
-  return { code_verifier: verifier, code_challenge: challenge, state };
-}
-
-function buildAuthURL(instanceURL, clientID, pkce) {
-  const u = new URL('/oauth_auth.do', instanceURL);
-  u.searchParams.set('response_type', 'code');
-  u.searchParams.set('client_id', clientID);
-  u.searchParams.set('redirect_uri', REDIRECT_URI);
-  u.searchParams.set('state', pkce.state);
-  u.searchParams.set('code_challenge', pkce.code_challenge);
-  u.searchParams.set('code_challenge_method', 'S256');
-  u.searchParams.set('scope', 'openid');
-  u.searchParams.set('approval_prompt', 'force');
-  return u.toString();
-}
-
-// ─── Keyring via secret-tool (libsecret, same backend as Go's go-keyring) ───
-
-function keyringLookup(key) {
-  try {
-    // execFileSync with an arg array — no shell, so `key` can never
-    // break out into command injection (issue #143 finding #2).
-    const result = execFileSync(
-      'secret-tool',
-      ['lookup', KEYRING_ATTR_SERVICE, KEYRING_SERVICE, KEYRING_ATTR_USERNAME, key],
-      { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' }
-    );
-    const trimmed = result.trim();
-    if (!trimmed) return null;
-    const parsed = JSON.parse(trimmed);
-    // Spread all fields from keyring first, then normalize known fields
-    // so username, password, and other extras are preserved.
-    return {
-      ...parsed,
-      auth_method: parsed.auth_method || 'oauth',
-      access_token: parsed.access_token || parsed.AccessToken || '',
-      refresh_token: parsed.refresh_token || parsed.RefreshToken || '',
-      expires_at: parsed.expires_at || parsed.ExpiresAt || 0,
-      created_at: parsed.created_at || parsed.CreatedAt || 0,
-      auth_source: ['oauth', 'env_token', 'env_basic', undefined].includes(parsed.auth_source)
-        ? (parsed.auth_method === 'gck' ? 'gck' : 'keyring')
-        : parsed.auth_source,
-    };
-  } catch {
-    return null;
-  }
-}
-
-function keyringStore(key, creds) {
-  try {
-    execFileSync(
-      'secret-tool',
-      ['store', `--label=Password for '${key}' on '${KEYRING_SERVICE}'`,
-        KEYRING_ATTR_SERVICE, KEYRING_SERVICE, KEYRING_ATTR_USERNAME, key],
-      { stdio: ['pipe', 'ignore', 'ignore'], input: JSON.stringify(creds) }
-    );
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function keyringDelete(key) {
-  try {
-    execFileSync(
-      'secret-tool',
-      ['clear', KEYRING_ATTR_SERVICE, KEYRING_SERVICE, KEYRING_ATTR_USERNAME, key],
-      { stdio: 'ignore' }
-    );
-  } catch {
-    // ignore
-  }
-}
-
-// ─── File-based storage (fallback) ───
-
-/**
- * Load credentials for an instance keyed by <username>@<instance>.
- * When username is omitted (legacy configs without profile user), uses
- * bare instance key for lookup.
- */
-function loadCredentials(instance, username, injectedStore) {
-  if (injectedStore) return injectedStore.load(instance, username);
-  const key = username ? credKey(instance, username) : credKey(instance);
-  const keyringCreds = keyringLookup(key);
-  if (keyringCreds) {
-    return {
-      ...keyringCreds,
-      auth_source: keyringCreds.auth_source || (keyringCreds.auth_method === 'gck' ? 'gck' : 'keyring'),
-    };
-  }
-  try {
-    const data = fs.readFileSync(credentialsFilePath(key), 'utf-8');
-    const creds = JSON.parse(data);
-    return {
-      ...creds,
-      auth_source: ['oauth', 'env_token', 'env_basic', undefined].includes(creds.auth_source)
-        ? (creds.auth_method === 'gck' ? 'gck' : 'file')
-        : creds.auth_source,
-    };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Save credentials for an instance.
- * Uses <username>@<instance> key when username is available.
- */
-function saveCredentials(instance, creds, username, injectedStore) {
-  if (injectedStore) {
-    creds.last_seen = creds.last_seen || Math.floor(Date.now() / 1000);
-    return injectedStore.save(instance, creds, username);
-  }
-  const key = username ? credKey(instance, username) : credKey(instance);
-  // Stamp last_seen on every credential save
-  creds.last_seen = creds.last_seen || Math.floor(Date.now() / 1000);
-  // Try keyring first, fall back to file
-  if (!keyringStore(key, creds)) {
-    fs.writeFileSync(credentialsPath(key), JSON.stringify(creds, null, 2), { mode: 0o600 });
-  }
-}
-
-/**
- * Delete credentials for an instance keyed by <username>@<instance>.
- */
-function deleteCredentials(instance, username, injectedStore) {
-  if (injectedStore) return injectedStore.delete(instance, username);
-  const key = username ? credKey(instance, username) : credKey(instance);
-  keyringDelete(key);
-  try {
-    fs.unlinkSync(credentialsPath(key));
-  } catch {
-    // ignore
-  }
-}
-
-const defaultCredentialStore = {
-  load: loadCredentials,
-  save: saveCredentials,
-  delete: deleteCredentials,
-};
-
 function askHidden(promptText) {
   return passwordPrompt({ message: promptText });
 }
 
-/**
- * Extract the browser session token and cookies from pasted DevTools headers
- * or a "Copy as cURL" command. Only these two values are retained.
- */
-export function parseBrowserSessionInput(input) {
-  const text = String(input || '');
-  const tokenMatch = text.match(/(?:x-usertoken|x-user-token)\s*:\s*([^\s'";,]+)/i);
-  const cookieArgMatch = text.match(/(?:^|\s)(?:-b|--cookie)\s+(['"])(.*?)\1/s);
-  const quotedCookieMatch = text.match(/cookie\s*:\s*(['"])(.*?)\1/i);
-  const plainCookieMatch = text.match(/cookie\s*:\s*([^\r\n]+)/i);
-  const token = tokenMatch?.[1]?.trim() || '';
-  const cookies = (cookieArgMatch?.[2] || quotedCookieMatch?.[2] || plainCookieMatch?.[1] || '')
-    .trim()
-    .replace(/['"`]\s*(?:\\\s*)?$/, '');
-  if (!token) throw errAuth('No X-UserToken header found');
-  if (!cookies) throw errAuth('No Cookie header found. Paste the complete request headers or cURL command.');
-  return { auth_method: 'gck', access_token: token, cookies, auth_source: 'gck' };
-}
-
-const AUTH_METHODS = new Set(['oauth', 'basic', 'gck']);
-const AUTH_SOURCES = new Set(['env_token', 'env_basic', 'gck', 'keyring', 'file', 'unavailable']);
-
-function normalizeAuthMethod(value, fallback = 'unconfigured') {
-  return AUTH_METHODS.has(value) ? value : fallback;
-}
-
-function normalizeAuthSource(value, fallback = 'unavailable') {
-  return AUTH_SOURCES.has(value) ? value : fallback;
-}
-
-function sourceMethod(source) {
-  return { env_token: 'oauth', env_basic: 'basic', gck: 'gck' }[source] || null;
-}
-
-const PROBE_FAILURES = {
-  missing_credentials: {
-    message: 'Credentials are not available for this profile.',
-    hint: 'Run: jsn auth login',
-  },
-  credentials_expired: {
-    message: 'Credentials have expired and cannot be refreshed.',
-    hint: 'Run: jsn auth login',
-  },
-  refresh_required: {
-    message: 'Credentials require refresh before probing.',
-    hint: 'Run: jsn auth refresh',
-  },
-  refresh_failed: {
-    message: 'Credential refresh failed before the authenticated probe.',
-    hint: 'Run: jsn auth login',
-  },
-  invalid_browser_session: {
-    message: 'Browser session credentials are incomplete or invalid.',
-    hint: 'Capture a fresh ServiceNow browser request and run: jsn auth login --gck',
-  },
-  malformed_credentials: {
-    message: 'Credentials are malformed for the selected authentication method.',
-    hint: 'Run: jsn auth login',
-  },
-  permission_denied: {
-    message: 'The authenticated user lacks permission for the current-user probe.',
-    hint: 'Ask an administrator to grant access to the sys_user table/API.',
-  },
-  unauthorized: {
-    message: 'The instance rejected the selected credentials.',
-    hint: 'Run: jsn auth login',
-  },
-  network: {
-    message: 'The authenticated probe could not reach the instance.',
-    hint: 'Check your internet connection and instance URL.',
-  },
-  unknown: {
-    message: 'The authenticated probe failed for an unknown reason.',
-    hint: 'Retry the probe; if it persists, check the instance logs.',
-  },
-  missing_instance: {
-    message: 'No instance is configured for this profile.',
-    hint: 'Set an instance URL and run: jsn auth login',
-  },
-  sdk_construction_failed: {
-    message: 'The authenticated probe could not be initialized for this profile.',
-    hint: 'Check the profile configuration and run: jsn auth status again',
-  },
-};
-
-const PROBE_CLASSIFICATIONS = {
-  missing_credentials: 'unavailable', credentials_expired: 'expired', refresh_required: 'refresh_required',
-  refresh_failed: 'refresh_failed', invalid_browser_session: 'browser_session_invalid',
-  malformed_credentials: 'malformed', permission_denied: 'permission_denied', unauthorized: 'unauthorized',
-  network: 'network_error', unknown: 'unknown',
-  missing_instance: 'unavailable', sdk_construction_failed: 'configuration_error',
-};
-
-function probeFailure(code, status = 'failed') {
-  return { status, code, classification: PROBE_CLASSIFICATIONS[code] || 'unknown', ...PROBE_FAILURES[code] };
-}
-
-function classifyProbeError(error, method) {
-  if (error?.status === 401 || error?.status === 403) {
-    return error.status === 403 ? 'permission_denied' : 'unauthorized';
-  }
-  if (error?.code === 'network_error' || ['ECONNREFUSED', 'ENOTFOUND', 'ETIMEDOUT'].includes(error?.code)) {
-    return 'network';
-  }
-  const text = String(error?.message || '').toLowerCase();
-  if (error?.code === 'auth_error' && text.includes('refresh')) return 'refresh_failed';
-  if (method === 'gck' && error?.code === 'auth_error') return 'invalid_browser_session';
-  return 'unknown';
-}
-
-/**
- * Classify credentials without returning or logging any credential material.
- * This is deliberately pure so diagnostics cannot refresh, persist, or probe.
- */
-export function classifyCredentialState(credentials, method, now = Date.now()) {
-  if (!credentials) return 'missing';
-  if (!AUTH_METHODS.has(method)) return 'malformed';
-
-  if (method === 'basic') {
-    const hasUser = typeof credentials.username === 'string' && credentials.username.length > 0;
-    const hasPassword = typeof credentials.password === 'string' && credentials.password.length > 0;
-    return hasUser && hasPassword ? 'available' : 'malformed';
-  }
-
-  if (method === 'gck') {
-    const hasToken = typeof credentials.access_token === 'string' && credentials.access_token.length > 0;
-    const hasCookies = typeof credentials.cookies === 'string' && credentials.cookies.length > 0;
-    return hasToken && hasCookies ? 'available' : 'malformed';
-  }
-
-  if (credentials.access_token !== undefined && typeof credentials.access_token !== 'string') return 'malformed';
-  if (credentials.refresh_token !== undefined && typeof credentials.refresh_token !== 'string') return 'malformed';
-
-  const hasToken = typeof credentials.access_token === 'string' && credentials.access_token.length > 0;
-  if (!hasToken) return credentials.refresh_token ? 'refreshable' : 'missing';
-  if (credentials.expires_at !== undefined && credentials.expires_at !== null && credentials.expires_at !== 0) {
-    const expiresAt = Number(credentials.expires_at);
-    if (!Number.isFinite(expiresAt)) return 'malformed';
-    if (now >= (expiresAt - 300) * 1000) return credentials.refresh_token ? 'refreshable' : 'expired';
-  }
-  return 'available';
-}
-
 export class AuthManager {
   /**
    * @param {object} identity — the resolved-identity provider. Production
@@ -1002,4 +634,5 @@ export class AuthManager {
   }
 }
 
-export { saveCredentials, loadCredentials, deleteCredentials, askHidden };
+export { saveCredentials, loadCredentials, deleteCredentials } from './auth/credential-store.js';
+export { askHidden };

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

@@ -303,7 +303,7 @@ export function buildCLI() {
 
         if (shouldCheck) {
           const version = getVersion();
-          checkLatest().then(latest => {
+          checkLatest({ background: true }).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`);
             }
@@ -584,3 +584,5 @@ export function buildCLI() {
 
 // Run if invoked directly (bin/jsn.js calls cli.parse())
 export const cli = buildCLI();
+
+export { cancelBackgroundChecks } from './commands/version.js';

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/docs/db.js

@@ -132,8 +132,13 @@ export function openDocsDb(opts = {}) {
   const dbPath = opts.dbPath || getDocsDbPath();
   ensureDocsCacheDir();
   const db = new Database(dbPath);
-  db.exec('PRAGMA journal_mode = WAL');
-  return db;
+  try {
+    db.exec('PRAGMA journal_mode = WAL');
+    return db;
+  } catch (error) {
+    closeDocsDb(db);
+    throw error;
+  }
 }
 
 export function closeDocsDb(db) {
@@ -246,3 +251,18 @@ export function getDocsIndexStats(db) {
 export function setMeta(db, key, value) {
   db.prepare('INSERT OR REPLACE INTO meta(key, value) VALUES(?, ?)').run(key, value);
 }
+
+/** Own a synchronous docs connection and roll back unfinished work on failure. */
+export function withDocsDb(opts, operation) {
+  const db = openDocsDb(opts);
+  try {
+    return operation(db);
+  } catch (error) {
+    if (db.inTransaction) {
+      try { db.exec('ROLLBACK'); } catch { /* Preserve the original error. */ }
+    }
+    throw error;
+  } finally {
+    closeDocsDb(db);
+  }
+}