@jacebenson/jsn 3.0.5 → 3.1.0

package/src/errors.js

@@ -79,7 +79,34 @@ export function errAPI(status, msg) {
   if (status >= 500) {
     hint = 'The ServiceNow instance may be experiencing issues. Try again later.';
   }
-  return new AppError(CodeAPI, `API error (status ${status}): ${msg}`, hint, status);
+
+  // Try to extract structured error detail from JSON API error bodies
+  let displayMsg = msg;
+  if (typeof msg === 'string' && (msg.startsWith('{') || msg.startsWith('['))) {
+    try {
+      const parsed = JSON.parse(msg);
+      const errObj = parsed.error || parsed;
+      const detail = errObj.detail || errObj.message || '';
+      const message = errObj.message || '';
+
+      if (detail && message) {
+        displayMsg = `${message}: ${detail}`;
+      } else if (detail) {
+        displayMsg = detail;
+      } else if (message) {
+        displayMsg = message;
+      }
+
+      // Detect business rule abortion and add a hint
+      if (detail && detail.includes('Business Rule')) {
+        hint = 'A Business Rule rejected this operation. Check for overlapping routes, validation rules, or ACLs on this table.';
+      }
+    } catch {
+      // Not valid JSON, use original message
+    }
+  }
+
+  return new AppError(CodeAPI, `API error (status ${status}): ${displayMsg}`, hint, status);
 }
 
 export function errAmbiguous(resource, matches) {

package/src/help.js

@@ -9,23 +9,63 @@ const COMMAND_GROUPS = {
     { name: 'tasks', alias: 'task', desc: 'Manage catalog tasks' },
     { name: 'tickets', alias: 'ticket', desc: 'Query generic tickets' },
   ],
-  'DATA & ADMIN': [
+  'AUTOMATION': [
+    { name: 'flows', desc: 'Manage Flow Designer flows' },
+    { name: 'actions', alias: 'action', desc: 'Manage flow actions (sys_hub_action_type_definition)' },
+    { name: 'rules', alias: 'br', desc: 'Manage business rules' },
+    { name: 'scrapi', desc: 'Manage Scripted REST APIs' },
+    { name: 'updatesets', desc: 'Manage update sets (set, yolo, export, import)' },
+    { name: 'eval', desc: 'Run server-side JavaScript' },
+    { name: 'rest', desc: 'Make raw REST API calls' },
+  ],
+  'ACCESS': [
+    { name: 'acls', alias: 'acl', desc: 'Manage access controls' },
+    { name: 'roles', alias: 'role', desc: 'Manage roles' },
+    { name: 'scopes', desc: 'Manage application scopes' },
+    { name: 'properties', alias: 'prop', desc: 'Manage system properties' },
+    { name: 'privileges', alias: 'priv', desc: 'Manage scope privileges' },
+    { name: 'securitytypes', alias: 'st', desc: 'Manage security types' },
+    { name: 'aliases', alias: 'als', desc: 'Manage table aliases' },
+  ],
+  'USER EXPERIENCE': [
+    { name: 'forms', desc: 'Manage form layouts' },
+    { name: 'lists', desc: 'Manage list layouts' },
+    { name: 'clientscripts', alias: 'cs', desc: 'Manage client scripts' },
+    { name: 'uipolicies', alias: 'up', desc: 'Manage UI policies' },
+    { name: 'uiactions', alias: 'ua', desc: 'Manage UI actions' },
+    { name: 'sppages', desc: 'Manage Service Portal pages' },
+    { name: 'spwidgets', desc: 'Manage Service Portal widgets' },
+    { name: 'uipages', desc: 'Manage UI pages' },
+    { name: 'appmenu', desc: 'Manage application menus' },
+    { name: 'listcontrols', alias: 'lc', desc: 'Manage list controls' },
+    { name: 'views', alias: 'vw', desc: 'Manage views' },
+    { name: 'uxscripts', alias: 'ux', desc: 'Manage UX source scripts' },
+    { name: 'catalogscripts', desc: 'Manage catalog client scripts' },
+    { name: 'cataloguipolicies', alias: 'cup', desc: 'Manage catalog UI policies' },
+  ],
+  'DATA': [
     { name: 'records', desc: 'Generic Table API for any table' },
+    { name: 'tables', alias: 't', desc: 'Manage table definitions (sys_db_object)' },
+    { name: 'columns', alias: 'col', desc: 'Manage column definitions (sys_dictionary)' },
+    { name: 'includes', alias: 'si', desc: 'Manage script includes' },
+    { name: 'import', desc: 'Manage import sets' },
+    { name: 'logs', desc: 'View system logs' },
     { name: 'users', alias: 'user', desc: 'Manage ServiceNow users' },
     { name: 'groups', alias: 'group', desc: 'Manage groups' },
     { name: 'groupmembers', alias: 'gm', desc: 'Manage group memberships' },
     { name: 'grouproles', alias: 'gr', desc: 'Manage group roles' },
-  ],
-  'DEVELOPMENT': [
-    { name: 'dev', desc: 'Manage development artifacts (flows, includes, rules, ACLs, etc.)' },
-  ],
-  'CONFIGURATION': [
-    { name: 'setup', desc: 'Interactive first-time setup' },
-    { name: 'auth', desc: 'Manage OAuth authentication' },
-    { name: 'profiles', alias: 'profile', desc: 'Manage instance profiles' },
+    { name: 'relationships', alias: 'rel', desc: 'Manage table relationships' },
+    { name: 'appmodules', alias: 'am', desc: 'Manage application modules' },
   ],
 };
 
+const CONFIGURATION_COMMANDS = [
+  { name: 'setup', desc: 'Interactive first-time setup' },
+  { name: 'auth', desc: 'Manage OAuth authentication' },
+  { name: 'profiles', alias: 'profile', desc: 'Manage instance profiles' },
+  { name: 'dev', desc: '[DEPRECATED] All dev subcommands are now top-level — use jsn flows, jsn acls, etc.' },
+];
+
 const UTILITY_COMMANDS = [
   { name: 'skill', desc: 'Manage the jsn AI agent skill file (show, fetch, install)' },
   { name: 'version', desc: 'Show version information (--check for npm updates)' },
@@ -67,6 +107,7 @@ LEARN MORE
 
 export function renderHelp() {
   const sections = Object.entries(COMMAND_GROUPS).map(([name, cmds]) => renderGroup(name, cmds));
+  const configSection = renderGroup('CONFIGURATION', CONFIGURATION_COMMANDS);
   const utilitySection = renderGroup('UTILITY', UTILITY_COMMANDS);
 
   return [
@@ -76,6 +117,8 @@ export function renderHelp() {
     '',
     ...sections,
     '',
+    configSection,
+    '',
     utilitySection,
     '',
     renderFlags(),

package/src/helpers.js

@@ -1,7 +1,7 @@
 // Shared helper utilities
 
 import fs from 'node:fs';
-import search from '@inquirer/search';
+import { paginatedSearch } from './paginated-search.js';
 import { isTTY, FormatAuto } from './output.js';
 
 export function getStringField(record, field) {
@@ -89,71 +89,129 @@ export function resolveFieldsParam(columns) {
  * @param {string} opts.labelField — field used to match selection (default: 'name')
  * @returns {Promise<void>|null} null if no selection made or non-interactive
  */
-export async function interactiveList({ app, table, singular, columns, limit = 20, query = '', formatLabel, labelField = 'name' }) {
+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) || query) {
     return null; // not interactive — caller should fall back to text/table
   }
 
   const pickerColumns = ['sys_id', labelField, ...columns.filter(c => c !== labelField && c !== 'sys_id' && c !== '*')];
-  const params = new URLSearchParams();
-  params.set('sysparm_limit', String(limit));
-  params.set('sysparm_display_value', 'all');
   const pickerFields = pickerColumns.join(',');
-  if (pickerFields) params.set('sysparm_fields', pickerFields);
-  params.set('sysparm_query', 'ORDERBYDESCsys_updated_on');
-
-  const records = await app.sdk.list(table, params);
-  if (records.length === 0) return null;
-
-  const choices = records.map(r => ({
-    name: formatLabel ? formatLabel(r) : (getStringField(r, labelField) || getStringField(r, 'sys_id')),
-    value: r,
-  }));
 
+  // Get total count
+  let totalCount = 0;
   try {
-    const selected = await search({
-      message: `Select ${vowelArticle(singular)} ${singular}:`,
-      source: async (input) => {
-        if (!input) return choices;
-        const term = input.toLowerCase();
-        return choices.filter(c => c.name.toLowerCase().includes(term));
-      },
-    });
-    return selected; // the record object
-  } catch (err) {
-    if (err.name === 'ExitPromptError' || (err.message && err.message.includes('force closed'))) {
-      return null;
+    totalCount = await app.sdk.aggregateCount(table, '');
+  } catch {
+    totalCount = 0;
+  }
+  if (totalCount === 0) return null;
+
+  // Server source adapter for paginatedSearch: (term, offset) => choices[]
+  async function serverSource(term, offset) {
+    const params = new URLSearchParams();
+    params.set('sysparm_limit', String(limit));
+    params.set('sysparm_display_value', 'all');
+    if (pickerFields) params.set('sysparm_fields', pickerFields);
+    if (term) {
+      params.set('sysparm_query', `${labelField}LIKE${term}^ORDERBYDESCsys_updated_on`);
+    } else {
+      params.set('sysparm_query', 'ORDERBYDESCsys_updated_on');
+      params.set('sysparm_offset', String(offset));
     }
-    throw err;
+    const records = await app.sdk.list(table, params);
+    return records.map(r => ({
+      name: formatLabel ? formatLabel(r) : (getStringField(r, labelField) || getStringField(r, 'sys_id')),
+      value: r,
+    }));
   }
+
+  const selected = await paginatedSearch({
+    message: `Select ${singular === 'flow' ? 'a flow' : `a ${singular}`}`,
+    pageSize: 10,
+    totalCount,
+    source: serverSource,
+  });
+  // null = cancelled → undefined so callers skip fallback table
+  if (selected === null) return undefined;
+  return selected?.value; // unwrap {name, value} → raw record
 }
 
-function vowelArticle(word) {
-  const first = word.charAt(0).toLowerCase();
-  return first === 'a' || first === 'e' || first === 'i' || first === 'o' || first === 'u' ? 'an' : 'a';
+/**
+ * Maps table name → array of field names that are computed by the platform.
+ * When a create/update payload contains these, a warning is emitted.
+ */
+export const DERIVED_FIELDS = {
+  sys_ws_operation: ['operation_uri'],
+  sys_ws_definition: ['base_uri'],
+  incident: ['sys_created_on', 'sys_updated_on', 'sys_created_by', 'sys_updated_by', 'sys_mod_count'],
+  change_request: ['sys_created_on', 'sys_updated_on', 'sys_created_by', 'sys_updated_by', 'sys_mod_count'],
+  // Generic — all sys_ fields are system-managed
+};
+
+/**
+ * Check a data payload for fields that appear to be derived/read-only.
+ * Returns an array of warning objects ({field, hint}) for any matches.
+ * @param {string} table - Table name (e.g. 'sys_ws_operation')
+ * @param {object} data - The JSON payload being sent
+ * @returns {Array<{field: string, hint: string}>}
+ */
+export function checkDerivedFields(table, data) {
+  if (!data || typeof data !== 'object') return [];
+  const warnings = [];
+
+  // Check explicitly known derived fields for this table
+  const knownFields = DERIVED_FIELDS[table] || [];
+  for (const field of knownFields) {
+    if (field in data && data[field] != null) {
+      warnings.push({
+        field,
+        hint: `${field} is a derived/read-only field. Setting it directly will be ignored.`,
+      });
+    }
+  }
+
+  // Warn about any sys_* fields that look like system-managed metadata
+  // (but be careful — not all sys_ fields are read-only)
+  if (data.sys_created_on) {
+    warnings.push({
+      field: 'sys_created_on',
+      hint: 'sys_created_on is a system-managed field. Setting it directly will be ignored.',
+    });
+  }
+  if (data.sys_updated_on) {
+    warnings.push({
+      field: 'sys_updated_on',
+      hint: 'sys_updated_on is a system-managed field. Setting it directly will be ignored.',
+    });
+  }
+
+  return warnings;
 }
 
 /**
- * Parse --data or --data-file into a JSON object.
- * If --data-file is given, reads the file. Otherwise parses --data directly.
- * Throws if neither is provided or JSON is invalid.
+ * Parse --data, --data-file, or --data-stdin into a JSON object.
+ * Priority: --data-file > --data-stdin > --data
+ * Throws if none is provided or JSON is invalid.
  */
 export function parseDataArg(argv) {
   let raw;
   if (argv['data-file']) {
     raw = fs.readFileSync(argv['data-file'], 'utf-8');
-    // Strip UTF-8 BOM (\ufeff) which some editors (Windows/PowerShell) add
+    // Strip UTF-8 BOM (\\ufeff) which some editors (Windows/PowerShell) add
     if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1);
+  } else if (argv['data-stdin']) {
+    raw = fs.readFileSync(process.stdin.fd, 'utf-8');
   } else if (argv.data) {
     raw = argv.data;
   } else {
-    throw new Error('--data or --data-file is required');
+    throw new Error('--data, --data-file, or --data-stdin is required');
   }
   try {
     return JSON.parse(raw);
   } catch (e) {
-    throw new Error(`Invalid JSON: ${e.message}\n\nHint: On Windows PowerShell, use --data-file instead of --data to avoid quote mangling.\nRaw value: ${raw.substring(0, 200)}`, { cause: e });
+    throw new Error(`Invalid JSON: ${e.message}\n\nHint: Use --data-file for multiline payloads to avoid shell escaping issues.\nRaw value: ${raw.substring(0, 200)}`, { cause: e });
   }
 }
 

package/src/paginated-search.js

@@ -0,0 +1,178 @@
+/**
+ * Paginated interactive search prompt with server-side pagination.
+ *
+ * Uses raw readline for terminal control — @inquirer/search doesn't support
+ * scroll-based pagination (source only fires on keystrokes, not on scroll).
+ *
+ * Returns the selected choice ({name, value}), or null on cancel.
+ */
+
+import readline from 'node:readline';
+
+export async function paginatedSearch({ message, pageSize, totalCount, pageSize: pgSize, source }) {
+  const PAGE = pageSize || pgSize || 10;
+  let choices = [];
+  let active = 0;
+  let loaded = 0;
+  let cancelled = false;
+  let term = '';
+  let outputLines = 0; // number of lines currently on screen
+
+  // Write + track: returns number of newlines written (cursor advance)
+  function writeLines(lines) {
+    const out = lines.join('\n');
+    process.stdout.write(out);
+    return lines.length - 1; // N elements = N-1 newlines = cursor advances this many
+  }
+
+  function render() {
+    if (outputLines > 0) {
+      process.stdout.moveCursor(0, -outputLines);
+      process.stdout.clearScreenDown();
+    } else {
+      // First render: ensure we start on a fresh line
+      process.stdout.cursorTo(0);
+      process.stdout.clearLine(0);
+    }
+
+    const buf = [];
+
+    // Header: show message + count
+    const countInfo = totalCount > 0 ? ` (${loaded} of ${totalCount} loaded)` : '';
+    buf.push(`${message}${countInfo}`);
+
+    // Visible window: center active item
+    const start = Math.max(0, active - Math.floor(PAGE / 2));
+    const end = Math.min(choices.length, start + PAGE);
+    const visible = choices.slice(start, end);
+
+    for (let i = 0; i < visible.length; i++) {
+      const choice = visible[i];
+      const isActive = (start + i) === active;
+      const prefix = isActive ? '\x1b[7m' : '';
+      const suffix = isActive ? '\x1b[0m' : '';
+      const display = choice.name.length > 70 ? choice.name.slice(0, 67) + '...' : choice.name;
+      buf.push(`  ${prefix}${display}${suffix}`);
+    }
+
+    // Pad to constant height
+    while (buf.length < PAGE + 2) {
+      buf.push('');
+    }
+
+    // Footer
+    const more = loaded < totalCount;
+    const footer = more
+      ? `↑↓ navigate • ⏎ select • esc cancel • type to filter • ↓ at end loads more`
+      : `↑↓ navigate • ⏎ select • esc cancel • type to filter`;
+    buf.push('');
+    buf.push(footer);
+
+    // Search bar
+    buf.push(`> ${term}`);
+
+    outputLines = writeLines(buf);
+  }
+
+  function cleanup() {
+    if (outputLines > 0) {
+      process.stdout.moveCursor(0, -outputLines);
+      process.stdout.clearScreenDown();
+      outputLines = 0;
+    }
+    // Ensure raw mode is off
+    try { process.stdin.setRawMode(false); } catch { /* ok */ }
+  }
+
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: true,
+    });
+    try { process.stdin.setRawMode(true); } catch { /* non-TTY */ }
+
+    let inputBuf = '';
+
+    async function loadPage() {
+      if (loaded >= totalCount) return;
+      const newItems = await source('', loaded);
+      if (newItems.length > 0) {
+        choices = choices.concat(newItems);
+        loaded = Math.min(choices.length, totalCount);
+      }
+    }
+
+    // Initial load
+    (async () => {
+      const initial = await source('', 0);
+      if (cancelled) return;
+      choices = initial;
+      loaded = Math.min(choices.length, totalCount || Infinity);
+      active = 0;
+      render();
+    })();
+
+    rl.input.on('keypress', async (_str, key) => {
+      if (key.name === 'escape' || key.name === 'q' || (key.ctrl && key.name === 'c')) {
+        cancelled = true;
+        rl.close();
+        return;
+      }
+
+      if (key.name === 'return' || key.name === 'enter') {
+        if (choices.length > 0 && active >= 0 && active < choices.length) {
+          rl.close();
+          return;
+        }
+      }
+
+      if (key.name === 'up' && active > 0) {
+        active--;
+        render();
+        return;
+      }
+
+      if (key.name === 'down') {
+        if (active < choices.length - 1) {
+          active++;
+          render();
+        } else if (loaded < totalCount) {
+          await loadPage();
+          if (active < choices.length - 1) active++;
+          render();
+        }
+        return;
+      }
+
+      if (key.name === 'backspace') {
+        if (inputBuf.length > 0) inputBuf = inputBuf.slice(0, -1);
+      } else if (key.sequence && key.sequence.length === 1 && !key.meta && !key.ctrl) {
+        inputBuf += key.sequence;
+      } else {
+        return;
+      }
+
+      // Search
+      term = inputBuf;
+      if (term) {
+        const results = await source(term, 0);
+        choices = results;
+        loaded = results.length;
+      } else {
+        // Reset to browse mode — reload first page
+        const results = await source('', 0);
+        choices = results;
+        loaded = Math.min(results.length, totalCount || Infinity);
+      }
+      active = 0;
+      render();
+    });
+
+    rl.on('close', () => {
+      cleanup();
+      const choice = (!cancelled && active >= 0 && active < choices.length) ? choices[active] : null;
+      resolve(cancelled ? null : choice);
+    });
+  });
+}