@jacebenson/jsn 4.0.3 → 4.1.0

package/src/context.js

@@ -1,5 +1,7 @@
 // ServiceNow runtime context: current user, scope, update set
 
+import { getStringField } from './helpers.js';
+
 export async function getCurrentUser(sdk) {
   const params = new URLSearchParams();
   params.set('sysparm_query', 'user_name=javascript:gs.getUserName()');
@@ -22,24 +24,24 @@ export async function getCurrentApplication(sdk, userSysID) {
   params.set('sysparm_limit', '1');
   params.set('sysparm_fields', 'value');
   const records = await sdk.list('sys_user_preference', params);
-  if (records.length === 0) return { scope: 'global' };
+  if (records.length === 0) return { scope: 'global', appSysId: '' };
   const val = records[0].value?.value || records[0].value;
-  if (!val) return { scope: 'global' };
+  if (!val) return { scope: 'global', appSysId: '' };
 
   // Try to resolve sys_id to scope name
   try {
     const app = await sdk.get('sys_scope', val);
-    if (app) return { scope: app.scope || 'global' };
+    if (app) return { scope: app.scope || 'global', appSysId: val };
   } catch {
     // fallback
   }
   try {
     const app2 = await sdk.get('sys_app', val);
-    if (app2) return { scope: app2.scope || 'global' };
+    if (app2) return { scope: app2.scope || 'global', appSysId: val };
   } catch {
     // fallback
   }
-  return { scope: val };
+  return { scope: val, appSysId: val };
 }
 
 export async function getCurrentUpdateSet(sdk, userSysID) {
@@ -60,3 +62,48 @@ export async function getCurrentUpdateSet(sdk, userSysID) {
   }
   return { name: val, sys_id: val };
 }
+
+/**
+ * Find-or-create a sys_user_preference and set its value. Shared by the
+ * scope/update-set "set" commands and create auto-set (was copy-pasted 3x).
+ */
+async function setUserPreference(sdk, userSysID, name, value) {
+  const params = new URLSearchParams();
+  params.set('sysparm_query', `user=${userSysID}^name=${name}`);
+  params.set('sysparm_limit', '1');
+  params.set('sysparm_fields', 'sys_id');
+  const prefs = await sdk.list('sys_user_preference', params);
+  if (prefs.length > 0) {
+    await sdk.update('sys_user_preference', getStringField(prefs[0], 'sys_id'), { value });
+  } else {
+    await sdk.create('sys_user_preference', {
+      user: userSysID,
+      name,
+      value,
+      type: 'string',
+    });
+  }
+}
+
+/** Resolve the current user's sys_id (throws if it can't be determined). */
+export async function requireCurrentUserSysId(sdk) {
+  const user = await sdk.list('sys_user', new URLSearchParams({
+    sysparm_query: 'user_name=javascript:gs.getUserName()',
+    sysparm_limit: '1',
+    sysparm_fields: 'sys_id',
+  }));
+  if (user.length === 0) {
+    throw new Error('Could not determine current user');
+  }
+  return getStringField(user[0], 'sys_id');
+}
+
+/** Set the current application scope via the apps.current_app preference. */
+export async function setCurrentApplication(sdk, userSysID, scopeSysID) {
+  await setUserPreference(sdk, userSysID, 'apps.current_app', scopeSysID);
+}
+
+/** Set the current update set via the sys_update_set preference. */
+export async function setCurrentUpdateSet(sdk, userSysID, updateSetSysID) {
+  await setUserPreference(sdk, userSysID, 'sys_update_set', updateSetSysID);
+}

package/src/errors.js

@@ -9,6 +9,7 @@ export const CodeNetwork = 'network_error';
 export const CodeAPI = 'api_error';
 export const CodeAmbiguous = 'ambiguous';
 export const CodeEmptyResult = 'empty_result';
+export const CodeConfirmationRequired = 'confirmation_required';
 
 export class AppError extends Error {
   constructor(code, message, hint = '', status = 0, cause = null) {
@@ -117,6 +118,20 @@ export function errAmbiguous(resource, matches) {
   );
 }
 
+/**
+ * Structured error for a destructive action that requires confirmation
+ * but no human is available to answer (non-TTY, pipes, or AI agents).
+ * The hint is written to be machine-parseable: an agent can read the
+ * re-run command and either present it to its user or execute it.
+ */
+export function errConfirmationRequired(question, rerunCmd) {
+  return new AppError(
+    CodeConfirmationRequired,
+    `${question} — confirmation required. Pass --force to skip, or set skip_confirmations on the profile to disable prompts.`,
+    `This is a destructive action. Ask your user to confirm, then re-run:\n  ${rerunCmd} --force\nOr set skip_confirmations on the profile to disable prompts:\n  jsn auth login <instance> --skip-confirmations`
+  );
+}
+
 export function asError(err) {
   if (!err) return null;
   if (err instanceof AppError) return err;

package/src/help.js

@@ -111,6 +111,7 @@ const CONFIG_COMMANDS = [
   { name: 'auth', desc: 'Authentication (login, refresh, status)' },
   { name: 'updatesets', desc: 'Update sets (set, create, export)' },
   { name: 'scopes', desc: 'Application scopes' },
+  { name: 'domains', desc: 'Domains (domain separation)' },
 ];
 
 const DEVELOPER_COMMANDS = [
@@ -153,8 +154,21 @@ LEARN MORE
   Use "jsn <command> --help" for more information about a command.`;
 }
 
-export function renderHelp() {
-  const sections = Object.entries(COMMAND_GROUPS).map(([name, cmds]) => renderGroup(name, cmds));
+export function renderHelp(config) {
+  // Domain separation is an optional plugin — only advertise `domains`
+  // when the active profile's capability probe found it installed.
+  const activeName = config?.activeProfile || config?.defaultProfile;
+  const hasDS = !!(activeName && config?.profiles?.[activeName]?.domain_separation);
+  const configCmds = hasDS
+    ? CONFIG_COMMANDS
+    : CONFIG_COMMANDS.filter((c) => !c.name || c.name !== 'domains');
+
+  const COMMAND_GROUPS_LOCAL = {
+    ...COMMAND_GROUPS,
+    'CONFIGURATION': configCmds,
+  };
+
+  const sections = Object.entries(COMMAND_GROUPS_LOCAL).map(([name, cmds]) => renderGroup(name, cmds));
 
   return [
     'Usage: jsn <command> [options]',

package/src/helpers.js

@@ -5,6 +5,32 @@ import readline from 'node:readline';
 import { paginatedSearch } from './paginated-search.js';
 import { isTTY, FormatAuto } from './output.js';
 import { getActiveProfile } from './config.js';
+import { errConfirmationRequired } from './errors.js';
+
+/**
+ * Detect whether a human is actually available to answer interactive
+ * prompts. Agent tooling (VSCode Copilot, Claude Code, Cursor, etc.)
+ * allocates a PTY for subprocesses, so isTTY() returns true even though
+ * no one will ever type a response. Those environments set signals that
+ * let us fall back to non-interactive behavior instead of hanging:
+ *
+ *   - JSN_NO_PROMPTS=1        (explicit opt-out, documented for agents)
+ *   - CI / NONINTERACTIVE / GITHUB_ACTIONS
+ *   - CLAUDE_CODE / COPILOT_* / CURSOR_* agent markers
+ *   - TERM=dumb
+ *
+ * @returns {boolean} true when a human can answer a prompt
+ */
+export function canPrompt() {
+  if (process.env.JSN_NO_PROMPTS === '1') return false;
+  if (process.env.CI === 'true' || process.env.CI === '1') return false;
+  if (process.env.NONINTERACTIVE === 'true' || process.env.NONINTERACTIVE === '1') return false;
+  if (process.env.GITHUB_ACTIONS === 'true') return false;
+  if (process.env.TERM === 'dumb') return false;
+  const agentMarkers = ['CLAUDE_CODE', 'COPILOT_AGENT', 'VSCODE_AGENT', 'CURSOR_AGENT', 'CODEX_AGENT', 'GITHUB_COPILOT_AGENT'];
+  if (agentMarkers.some((m) => process.env[m] === 'true' || process.env[m] === '1')) return false;
+  return isTTY(process.stdout) && isTTY(process.stdin);
+}
 
 /**
  * Confirm a destructive action before executing.
@@ -25,7 +51,7 @@ export async function confirmDelete(app, argv, question) {
   const profile = getActiveProfile(app.config);
   if (profile?.skip_confirmations === true) return true;
   if (argv.force) return true;
-  if (isTTY(process.stdout) && isTTY(process.stdin)) {
+  if (canPrompt()) {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     const answer = await new Promise((resolve) => {
       rl.question(`${question} (y/N): `, resolve);
@@ -37,9 +63,10 @@ export async function confirmDelete(app, argv, question) {
     }
     return true;
   }
-  throw new Error(
-    `${question} — confirmation required. Pass --force to skip, or set skip_confirmations on the profile to disable prompts.`
-  );
+  // No human available (pipes, scripts, AI agents). Fail fast with a
+  // structured error an agent can act on — never hang waiting for stdin.
+  const cmd = ['jsn', ...(argv._ || [])].join(' ');
+  throw errConfirmationRequired(question, cmd);
 }
 
 
@@ -55,6 +82,84 @@ export function getStringField(record, field) {
   return String(val);
 }
 
+/**
+ * Extract the raw value from a field that may be a string or a
+ * {display_value, value} object returned by the Table API.
+ * Prefers .value (the raw stored value) over .display_value.
+ */
+function getRawValue(val) {
+  if (val == null) return '';
+  if (typeof val === 'object') {
+    if (val.value != null) return String(val.value);
+    if (val.display_value != null) return String(val.display_value);
+    return '';
+  }
+  return String(val);
+}
+
+/**
+ * Normalize a value the user supplied in --data for comparison against
+ * what the API persisted. Objects like {"value": "<sys_id>"} are unwrapped.
+ */
+function normalizeSupplied(val) {
+  if (val == null) return '';
+  if (typeof val === 'object') {
+    if (val.value != null) return String(val.value);
+    return '';
+  }
+  return String(val);
+}
+
+/**
+ * Write-back verification for records create/update.
+ *
+ * After a mutation, re-GET the record and compare each field supplied in
+ * --data against what actually persisted. Surfaces silent server-side
+ * drops (inherited references, ACL-restricted fields, IO: prefixed strings,
+ * platform quirks) that ServiceNow ignores without erroring.
+ *
+ * Skips sys_* fields (system-managed, already warned by checkDerivedFields).
+ *
+ * @returns {Promise<Array<{field: string, sent: string, got: string}>>}
+ */
+export async function verifyWriteBack(app, table, sysID, sentData) {
+  const mismatches = [];
+  if (!sysID || !sentData || typeof sentData !== 'object') return mismatches;
+
+  const fields = Object.keys(sentData).filter(f => f !== 'sys_id' && !f.startsWith('sys_'));
+  if (fields.length === 0) return mismatches;
+
+  let persisted;
+  try {
+    const params = new URLSearchParams();
+    params.set('sysparm_query', `sys_id=${sysID}`);
+    params.set('sysparm_limit', '1');
+    params.set('sysparm_display_value', 'all');
+    params.set('sysparm_fields', ['sys_id', ...fields].join(','));
+    const records = await app.sdk.list(table, params);
+    persisted = records[0] || null;
+  } catch {
+    // Verification GET failed — don't fail the mutation, just report it.
+    mismatches.push({ field: '(verify)', sent: '', got: 'write-back check failed (GET error)' });
+    return mismatches;
+  }
+
+  if (!persisted) {
+    mismatches.push({ field: '(verify)', sent: '', got: 'record not found after write' });
+    return mismatches;
+  }
+
+  for (const field of fields) {
+    const sent = normalizeSupplied(sentData[field]);
+    const got = getRawValue(persisted[field]);
+    if (sent !== got) {
+      mismatches.push({ field, sent, got });
+    }
+  }
+
+  return mismatches;
+}
+
 export function formatRecordForDisplay(record, columns) {
   const result = {};
 
@@ -154,7 +259,7 @@ export function assertSafeExactMatch(value) {
 export async function interactiveList({ app, table, singular, columns, limit = 50, _query = '', formatLabel, labelField = 'name' }) {
   app.requireInstance();
   const effectiveFormat = app.output.getFormat() === FormatAuto ? (isTTY(process.stdout) ? FormatAuto : FormatAuto) : app.output.getFormat();
-  if (effectiveFormat !== FormatAuto || !isTTY(process.stdout) || !isTTY(process.stdin)) {
+  if (effectiveFormat !== FormatAuto || !canPrompt()) {
     return null; // not interactive — caller should fall back to text/table
   }
 

package/src/mutations.js

@@ -75,11 +75,20 @@ export const MUTATION_COMMANDS = [
   ['scopes', 'set'],
   ['dev', 'scopes', 'create'],
   ['dev', 'scopes', 'set'],
-  // Update sets: create + set (root + dev forms)
+  // Domains: set writes the profile config (root + dev forms)
+  ['domains', 'set'],
+  ['dev', 'domains', 'set'],
+  // Update sets: create, set, complete, ignore, parent (root + dev forms)
   ['updatesets', 'create'],
   ['updatesets', 'set'],
+  ['updatesets', 'complete'],
+  ['updatesets', 'ignore'],
+  ['updatesets', 'parent'],
   ['dev', 'updatesets', 'create'],
   ['dev', 'updatesets', 'set'],
+  ['dev', 'updatesets', 'complete'],
+  ['dev', 'updatesets', 'ignore'],
+  ['dev', 'updatesets', 'parent'],
 ];
 
 /**

package/src/output.js

@@ -1,7 +1,6 @@
 // Output formatting: JSON, Markdown, Styled, Quiet
 
 import process from 'node:process';
-import chalk from 'chalk';
 
 export const FormatAuto = 'auto';
 export const FormatJSON = 'json';
@@ -28,6 +27,12 @@ export function isTTY(writer) {
   return writer.isTTY === true;
 }
 
+// Minimal ANSI colors — replaces chalk (only used for error/hint styling,
+// which is already TTY-gated by callers).
+const ansi = (code) => (text) => `\x1b[${code}m${text}\x1b[0m`;
+const colorRed = ansi('31');
+const colorYellow = ansi('33');
+
 export class OutputWriter {
   constructor(opts = {}) {
     this.format = opts.format || FormatAuto;
@@ -82,8 +87,8 @@ export class OutputWriter {
         break;
       default:
         if (isTTY(this.writer)) {
-          this.writer.write(chalk.red(`Error (${e.code}): ${e.message}\n`));
-          if (e.hint) this.writer.write(chalk.yellow(`Hint: ${e.hint}\n`));
+          this.writer.write(colorRed(`Error (${e.code}): ${e.message}\n`));
+          if (e.hint) this.writer.write(colorYellow(`Hint: ${e.hint}\n`));
         } else {
           this.writer.write(JSON.stringify(resp, null, 2) + '\n');
         }

package/src/sdk.js

@@ -11,6 +11,7 @@ export class SDKClient {
     this.baseURL = baseURL.replace(/\/$/, '');
     this.authProvider = authProvider;
     this.timeout = opts.timeout || DEFAULT_TIMEOUT;
+    this.domain = opts.domain || '';
   }
 
   async _setAuth(req) {
@@ -53,6 +54,9 @@ export class SDKClient {
       if (opts.body && typeof opts.body === 'string') {
         req.headers.set('Content-Type', 'application/json');
       }
+      if (this.domain) {
+        req.headers.set('X-Now-Domain', this.domain);
+      }
       await this._setAuth(req);
 
       const resp = await fetch(req);