@jacebenson/jsn 4.0.4 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.0.4",
+  "version": "4.1.0",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {
@@ -29,8 +29,6 @@
     "@inquirer/core": "^10.1.0",
     "@inquirer/prompts": "^7.5.1",
     "better-sqlite3": "^13.0.3",
-    "chalk": "^5.4.1",
-    "cli-table3": "^0.6.5",
     "gray-matter": "^4.0.3",
     "turndown": "^7.2.4",
     "yargs": "^17.7.2"

package/src/cli.js

@@ -10,6 +10,7 @@ import { App } from './app.js';
 import { renderHelp } from './help.js';
 import { isMutationCommand } from './mutations.js';
 import { guardExit } from './errors.js';
+import { FormatJSON } from './output.js';
 
 // Command modules
 import { setupCmd } from './commands/setup.js';
@@ -86,6 +87,19 @@ function wrap(handler) {
         process.stderr.write(`Error (system): ${err.message}\n`);
         process.exit(3);
       }
+      if (err.code === 'confirmation_required') {
+        // Structured error for AI agents / piped consumers: emit the
+        // JSON envelope on stdout (where tooling reads) so the agent can
+        // surface the decision to its user or re-run with --force.
+        const app = argv.app;
+        if (app && app.output.effectiveFormat() === FormatJSON) {
+          app.err(err);
+        } else {
+          process.stderr.write(`Error: ${err.message}\n`);
+          if (err.hint) process.stderr.write(`\n${err.hint}\n`);
+        }
+        process.exit(1);
+      }
       process.stderr.write(`Error: ${err.message}\n`);
       process.exit(1);
     }

package/src/commands/_ticket.js

@@ -1,9 +1,9 @@
 // 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, assertSafeExactMatch } from '../helpers.js';
+import { getStringField, formatRecordForDisplay, buildQuerySuffix, resolveFieldsParam, confirmDelete, assertSafeExactMatch, canPrompt } from '../helpers.js';
 import { search } from '@inquirer/prompts';
-import { isTTY, FormatAuto } from '../output.js';
+import { FormatAuto } from '../output.js';
 
 export function buildTicketCommands(table, displayName, alias, defaultColumns, stateMap, iconFn, wrap) {
   return {
@@ -28,7 +28,7 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
             const offset = argv.offset;
 
             // Interactive picker in TTY with auto format and no explicit query/offset
-            const isInteractive = isTTY(process.stdout) && isTTY(process.stdin);
+            const isInteractive = canPrompt();
             if (isInteractive && app.output.getFormat() === FormatAuto && !query && offset === 0) {
               const pickerColumns = ['sys_id', 'number', 'short_description', 'state', 'assigned_to'];
               const pickerParams = new URLSearchParams();

package/src/commands/catalog.js

@@ -175,7 +175,15 @@ export function catalogCmd(wrap) {
 }
 
 async function showItem(app, sysID) {
-  const item = await app.sdk.get('sc_cat_item', sysID);
+  // Use list + display_value=all so reference fields (category, flow) resolve
+  // to readable display values instead of raw sys_ids.
+  const p = new URLSearchParams();
+  p.set('sysparm_query', `sys_id=${sysID}`);
+  p.set('sysparm_limit', '1');
+  p.set('sysparm_display_value', 'all');
+  const items = await app.sdk.list('sc_cat_item', p);
+  const item = items[0] || null;
+  if (!item) throw new Error(`Not found: ${sysID}`);
 
   const vp = new URLSearchParams();
   vp.set('sysparm_query', `cat_item=${sysID}^active=true`);
@@ -216,7 +224,8 @@ async function showItem(app, sysID) {
   const wfName = getStringField(item, 'workflow') || '';
   const wfID = item.workflow?.value || '';
   const planName = getStringField(item, 'delivery_plan') || getStringField(item, 'execution_plan') || '';
-  app.ok({
+
+  const data = {
     name: getStringField(item, 'name'),
     short_description: getStringField(item, 'short_description'),
     category: getStringField(item, 'category'),
@@ -232,7 +241,60 @@ async function showItem(app, sysID) {
       standalone: standalone.map(v => ({ label: v.question_text || v.name, type: v.type, mandatory: String(v.mandatory) === 'true' })),
       sets: Array.from(setVars.values()).map(s => ({ name: s.name, variables: s.variables.map(v => ({ label: v.question_text || v.name, type: v.type, mandatory: String(v.mandatory) === 'true' })) })),
     } : undefined,
-  }, {
-    summary: `${getStringField(item, 'name')} — ${totalVars} variable(s)`,
+  };
+
+  // Styled-mode rendering (non-enumerable so JSON output stays clean)
+  Object.defineProperty(data, '_formatted', {
+    value: buildCatalogFormatted(data, standalone, Array.from(setVars.values()), totalVars),
+    enumerable: false,
+    configurable: true,
   });
+
+  app.ok(data, {
+    summary: `${data.name} — ${totalVars} variable(s)`,
+    breadcrumbs: [
+      { action: 'list', cmd: 'jsn catalogitems list', description: 'Back to all catalog items' },
+    ],
+  });
+}
+
+function buildCatalogFormatted(data, standalone, setVars, totalVars) {
+  const lines = [];
+  lines.push(`${data.name} (sc_cat_item)`);
+  lines.push('');
+  lines.push('─ Details ─');
+  if (data.short_description) lines.push(`  short_description:  ${data.short_description}`);
+  if (data.category) lines.push(`  category:  ${data.category}`);
+  lines.push(`  active:  ${data.active}`);
+  if (data.url) lines.push(`  url:  ${data.url}`);
+  if (data.execution_plan) lines.push(`  execution_plan:  ${data.execution_plan}`);
+  lines.push('');
+  if (data.flow) {
+    lines.push('─ Flow ─');
+    lines.push(`  ${data.flow}`);
+    if (data.flow_cmd) lines.push(`  → ${data.flow_cmd}`);
+    lines.push('');
+  }
+  if (data.workflow) {
+    lines.push('─ Workflow ─');
+    lines.push(`  ${data.workflow}`);
+    if (data.workflow_cmd) lines.push(`  → ${data.workflow_cmd}`);
+    lines.push('');
+  }
+  if (totalVars > 0) {
+    lines.push('─ Catalog Variables ─');
+    for (const v of standalone) {
+      const label = v.question_text || v.name;
+      lines.push(`  ${label}:  ${v.type}${String(v.mandatory) === 'true' ? ' (mandatory)' : ''}`);
+    }
+    for (const s of setVars) {
+      lines.push(`  [${s.name}]`);
+      for (const v of s.variables) {
+        const label = v.question_text || v.name;
+        lines.push(`    ${label}:  ${v.type}${String(v.mandatory) === 'true' ? ' (mandatory)' : ''}`);
+      }
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
 }

package/src/commands/dev/_generic.js

@@ -1,9 +1,9 @@
 // Generic dev subcommand builder for table-based CRUD
 
-import { formatRecordForDisplay, getStringField, isHexString, parseDataArg, confirmDelete, assertSafeExactMatch } from '../../helpers.js';
+import { formatRecordForDisplay, getStringField, isHexString, parseDataArg, confirmDelete, assertSafeExactMatch, canPrompt } from '../../helpers.js';
 import { getCurrentUser, getCurrentApplication } from '../../context.js';
 import { paginatedSearch } from '../../paginated-search.js';
-import { isTTY, FormatAuto } from '../../output.js';
+import { FormatAuto } from '../../output.js';
 
 function vowelArticle(word) {
   const first = word.charAt(0).toLowerCase();
@@ -111,7 +111,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
           const limit = argv.limit;
 
           // Interactive picker with pagination
-          const interactive = isTTY(process.stdout) && isTTY(process.stdin);
+          const interactive = canPrompt();
           if (interactive && app.output.getFormat() === FormatAuto && !query) {
             // Get total count
             let totalCount = 0;

package/src/commands/dev/eval.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import { getCurrentUser, getCurrentApplication } from '../../context.js';
 
 export function evalCmd(wrap) {
   return {
@@ -8,16 +9,34 @@ export function evalCmd(wrap) {
       return yargs
         .option('script', { alias: 's', type: 'string', describe: "JavaScript code to execute (single-quote the script, double quotes inside: --script 'gs.log(\"Hello\")')" })
         .option('file', { alias: 'f', type: 'string', describe: 'Read script from file (avoids shell quoting issues)' })
-        .option('scope', { alias: null, type: 'string', describe: 'Scope name or sys_id to run the script under (default: global)' });
+        .option('scope', { alias: null, type: 'string', describe: 'Scope name or sys_id to run the script under (default: active scope from banner)' });
     },
     handler: wrap(async (argv, app) => {
       let script;
       let scopeSysId = null;
 
-      if (argv.scope) {
-        scopeSysId = await app.sdk.resolveScope(argv.scope);
+      // Resolve execution scope: explicit --scope wins; otherwise use the
+      // active scope from apps.current_app (same source as the banner);
+      // fall back to global only when no active scope exists.
+      let scope = argv.scope || '';
+      if (!scope) {
+        try {
+          const user = await getCurrentUser(app.sdk);
+          if (user && user.sys_id) {
+            const currentApp = await getCurrentApplication(app.sdk, user.sys_id);
+            if (currentApp && currentApp.scope && currentApp.scope !== 'global') {
+              scope = currentApp.scope;
+            }
+          }
+        } catch {
+          // ignore — fall back to global
+        }
+      }
+
+      if (scope) {
+        scopeSysId = await app.sdk.resolveScope(scope);
         if (!scopeSysId) {
-          throw new Error(`Scope not found: ${argv.scope}`);
+          throw new Error(`Scope not found: ${scope}`);
         }
       }
 
@@ -36,10 +55,13 @@ export function evalCmd(wrap) {
       const warning = scopeSysId
         ? ` ⚠️ Records without explicit sys_scope will land in global. Use $scopeSysId variable.`
         : '';
-      const output = await app.sdk.executeScript(script, argv.scope);
+      // Pass the resolved sys_id (not the name) — sys.scripts.do only
+      // honors selectable scope values, which are sys_ids.
+      const output = await app.sdk.executeScript(script, scopeSysId || '');
       app.ok({
         script,
         output,
+        scope: scope || 'global',
         instance: app.getEffectiveInstance(),
       }, {
         summary: 'Script executed' + warning,

package/src/commands/records.js

@@ -1,4 +1,4 @@
-import { formatRecordForDisplay, buildQuerySuffix, parseDataArg, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, assertSafeExactMatch } from '../helpers.js';
+import { formatRecordForDisplay, buildQuerySuffix, parseDataArg, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, assertSafeExactMatch, verifyWriteBack } from '../helpers.js';
 
 const tableDefaultColumns = {
   incident: ['number', 'short_description', 'priority', 'state', 'assigned_to'],
@@ -135,7 +135,8 @@ export function recordsCmd(wrap) {
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
             .option('data', { type: 'string', describe: 'JSON fields (e.g. \'{"state":"2"}\')' })
             .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('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin (pipe-friendly)' })
+            .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 warnings = checkDerivedFields(argv.table, recordData);
@@ -143,6 +144,14 @@ export function recordsCmd(wrap) {
               process.stderr.write(`⚠ ${w.hint}\n`);
             }
             const record = await app.sdk.create(argv.table, recordData);
+            const sysID = getStringField(record, 'sys_id');
+            const mismatches = await verifyWriteBack(app, argv.table, sysID, recordData);
+            for (const m of mismatches) {
+              process.stderr.write(`⚠ field "${m.field}" was not persisted (sent: "${m.sent}", got: "${m.got}")\n`);
+            }
+            if (mismatches.length > 0 && argv.strict) {
+              throw new Error(`Strict mode: ${mismatches.length} field(s) not persisted after create`);
+            }
             app.ok(record, { summary: `Created record in ${argv.table}` });
           }),
         })
@@ -154,7 +163,8 @@ export function recordsCmd(wrap) {
             .option('sys-id', { type: 'string', demandOption: true, describe: 'Record sys_id' })
             .option('data', { type: 'string', describe: 'JSON fields (e.g. \'{"state":"2"}\')' })
             .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('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin (pipe-friendly)' })
+            .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 warnings = checkDerivedFields(argv.table, recordData);
@@ -162,6 +172,13 @@ export function recordsCmd(wrap) {
               process.stderr.write(`⚠ ${w.hint}\n`);
             }
             const record = await app.sdk.update(argv.table, argv['sys-id'], recordData);
+            const mismatches = await verifyWriteBack(app, argv.table, argv['sys-id'], recordData);
+            for (const m of mismatches) {
+              process.stderr.write(`⚠ field "${m.field}" was not persisted (sent: "${m.sent}", got: "${m.got}")\n`);
+            }
+            if (mismatches.length > 0 && argv.strict) {
+              throw new Error(`Strict mode: ${mismatches.length} field(s) not persisted after update`);
+            }
             app.ok(record, { summary: `Updated record in ${argv.table}` });
           }),
         })

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/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/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');
         }