@jacebenson/jsn 4.3.7 → 4.3.8-dev.46

package/src/help.js

@@ -1,5 +1,14 @@
 // Custom grouped help renderer
 // Organized by ServiceNow domain model with subgroup dividers
+//
+// The command rows are generated from the LIVE command registry
+// (`cli.commandRegistry()`): every registered root command appears, with the
+// description its own registration declares. The tables below are placement
+// hints only — group order, dividers, and a fallback description for a command
+// that declares none. A command that is registered but not hinted lands in the
+// trailing "MORE" group, so help can never silently drop a command again
+// (`approvals`, `cmdb`, `docs`, `perf`, `platform`, … were missing from the
+// hand-written list while being fully registered).
 
 function renderGroup(name, commands) {
   const lines = [`\n${name}`];
@@ -23,6 +32,8 @@ const CORE_COMMANDS = [
   { name: 'changes', alias: 'chg', desc: 'Manage change requests' },
   { name: 'requests', alias: 'req', desc: 'Manage service catalog requests' },
   { name: 'tasks', alias: 'task', desc: 'Manage catalog tasks' },
+  { name: 'tickets', desc: 'Query generic tickets' },
+  { name: 'approvals', desc: 'Approval requests (list, approve, reject, submit, history)' },
 ];
 
 const AUTOMATION_COMMANDS = [
@@ -96,6 +107,7 @@ const DATA_COMMANDS = [
   { name: 'tables', alias: 't', desc: 'Table definitions' },
   { name: 'columns', alias: 'col', desc: 'Column definitions' },
   { name: 'relationships', alias: 'rel', desc: 'Table relationships' },
+  { name: 'cmdb', desc: 'CMDB: CI lookup and relationship traversal (read-only)' },
 
   { divider: '── Shared Code, Transforms, Logs ──' },
   { name: 'includes', alias: 'si', desc: 'Script includes' },
@@ -104,6 +116,8 @@ const DATA_COMMANDS = [
   { name: 'properties', alias: 'prop', desc: 'System properties' },
 
   { name: 'records', desc: 'Generic Table API (any table)' },
+  { name: 'transactions', desc: 'Client transaction timings' },
+  { name: 'snippets', desc: 'Saved query snippets' },
 ];
 
 const CONFIG_COMMANDS = [
@@ -112,12 +126,20 @@ const CONFIG_COMMANDS = [
   { name: 'updatesets', desc: 'Update sets (set, create, export)' },
   { name: 'scopes', desc: 'Application scopes' },
   { name: 'domains', desc: 'Domains (domain separation)' },
+  { name: 'midservers', desc: 'MID Servers and MID-run commands' },
+  { name: 'platform', desc: 'Platform health and node statistics (read-only)' },
+  { name: 'completion', desc: 'Shell completion script' },
 ];
 
 const DEVELOPER_COMMANDS = [
   { name: 'atf', desc: 'Automated Test Framework (list, suites, run, results)' },
   { name: 'eval', desc: 'Run server-side JavaScript' },
   { name: 'rest', desc: 'Raw REST API calls' },
+  { name: 'graphql', desc: 'GraphQL queries' },
+  { name: 'codesearch', desc: 'Search code across ServiceNow artifacts' },
+  { name: 'docs', desc: 'Local ServiceNow documentation search' },
+  { name: 'diff', desc: 'Compare records across configured profiles' },
+  { name: 'perf', desc: 'Read-only performance capture and comparison' },
   { name: 'skill', desc: 'AI agent skill file (show, fetch, install)' },
   { name: 'version', desc: 'Version info (--check for npm updates)' },
 ];
@@ -132,17 +154,50 @@ const COMMAND_GROUPS = {
   'DEVELOPER': DEVELOPER_COMMANDS,
 };
 
-function renderFlags() {
-  return `
-FLAGS
-  --instance    ServiceNow instance URL (e.g., https://dev12345.service-now.com)  [string]
-  -p, --profile Configuration profile to use                                      [string]
-  --format      Output format: auto, json, markdown, styled, quiet                [string]
-  --json        Output in JSON format                                            [boolean]
-  -q, --quiet   Output only data, no envelope                                    [boolean]
-  --styled      Force styled output                                              [boolean]
-  --markdown    Output in Markdown format                                        [boolean]
-  --help        Show help                                                        [boolean]`;
+/**
+ * Domain separation is an optional plugin — only advertise `domains` when the
+ * active profile's capability probe found it installed.
+ */
+function isCapabilityHidden(name, config) {
+  if (name !== 'domains') return false;
+  const activeName = config?.activeProfile || config?.defaultProfile;
+  return !(activeName && config?.profiles?.[activeName]?.domain_separation);
+}
+
+/**
+ * Group rows for one domain: registry first (alias/description from the
+ * command's own registration), hint text only as a fallback description.
+ */
+function rowsFor(hint, byName, used, config) {
+  const rows = [];
+  for (const entry of hint) {
+    if (entry.divider) { rows.push(entry); continue; }
+    const node = byName.get(entry.name);
+    if (!node || isCapabilityHidden(node.name, config)) continue;
+    used.add(node.name);
+    rows.push({
+      name: node.name,
+      alias: node.aliases[0] || entry.alias || '',
+      desc: node.description || entry.desc || '',
+    });
+  }
+  return rows;
+}
+
+function renderFlags(options) {
+  // Derived from the registered global options, so a new global flag cannot be
+  // missing from help (--get and --csv were, along with the csv format choice).
+  const lines = [];
+  for (const spec of options) {
+    if (spec.name === 'help') continue;
+    const alias = spec.alias.length ? `-${spec.alias.join(', -')}, ` : '';
+    const suffix = spec.name === 'format' && spec.choices.length
+      ? ` [string: ${spec.choices.join(', ')}]`
+      : ` [${spec.type}]`;
+    lines.push(`  ${`${alias}--${spec.name}`.padEnd(24)}${spec.description}${suffix}`);
+  }
+  lines.push(`  ${'--help'.padEnd(24)}Show help${' [boolean]'}`);
+  return `\nFLAGS\n${lines.join('\n')}`;
 }
 
 function renderTips() {
@@ -150,35 +205,45 @@ function renderTips() {
 TIPS
   --query is available on every list command (e.g. "incidents list --query priority=1")
   Use "jsn <command> --help" for details, or "jsn <command> list --help" for list options
+  "jsn --json" prints the registered command surface as JSON for scripts and agents
 
 LEARN MORE
   Use "jsn <command> --help" for more information about a command.`;
 }
 
-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));
+/**
+ * Render the grouped root help.
+ *
+ * @param {object} config — profile config (capability-conditioned hiding)
+ * @param {{commands: Array, options: Array}} [registry] — from
+ *   `cli.commandRegistry()`. Without it only the hint tables render, which is
+ *   the fallback for callers that have no registry (unit tests).
+ */
+export function renderHelp(config, registry = null) {
+  const commands = Array.isArray(registry?.commands) ? registry.commands : [];
+  const byName = new Map(commands.map((command) => [command.name, command]));
+  const used = new Set();
+
+  const sections = Object.entries(COMMAND_GROUPS)
+    .map(([name, hint]) => [name, rowsFor(hint, byName, used, config)])
+    .filter(([, rows]) => rows.some((row) => !row.divider))
+    .map(([name, rows]) => renderGroup(name, rows));
+
+  // Anything registered that the hint tables don't place. This is the safety
+  // net that keeps help complete as commands are added at the root.
+  const unplaced = commands
+    .filter((command) => !used.has(command.name) && !isCapabilityHidden(command.name, config))
+    .map((command) => ({ name: command.name, alias: command.aliases[0] || '', desc: command.description || '' }));
+  if (unplaced.length) sections.push(renderGroup('MORE', unplaced));
 
   return [
     'Usage: jsn <command> [options]',
     '',
-    `Command-line interface for ServiceNow`,
+    'Command-line interface for ServiceNow',
     '',
     ...sections,
     '',
-    renderFlags(),
+    renderFlags(Array.isArray(registry?.options) ? registry.options : []),
     renderTips(),
     '',
   ].join('\n');

package/src/helpers.js

@@ -32,6 +32,93 @@ export function canPrompt() {
   return isTTY(process.stdout) && isTTY(process.stdin);
 }
 
+/**
+ * True when an interactive picker may be opened for THIS invocation.
+ *
+ * canPrompt() alone answers "is a human reachable" — it does not know that
+ * the caller asked for machine output (`--json`, `--quiet`, `--csv`, …) or
+ * a one-shot extraction (`--get`). Opening a picker in either case blocks a
+ * script and corrupts the requested output shape, so every picker gate
+ * routes through here.
+ *
+ * @param {object} app — app instance (uses app.output when present)
+ * @param {object} [argv] — parsed args (checks argv.get)
+ * @returns {boolean} true when a picker may be shown
+ */
+export function canUsePicker(app, argv = {}) {
+  if (argv && argv.get) return false;
+  if (!canPrompt()) return false;
+  const writer = app?.output;
+  if (!writer) return true; // no output controller (unit-test app) — canPrompt decided
+  const format = typeof writer.getFormat === 'function' ? writer.getFormat() : undefined;
+  if (!format) return true;
+  return format === FormatAuto;
+}
+
+/**
+ * Render a parent command's subcommand list for its default handler.
+ *
+ * Returned through the `_formatted` side channel so a terminal prints the list
+ * while `--json`/`--quiet` keep the structured envelope. A parent command that
+ * only sets a summary leaves terminal users with no way to discover children.
+ */
+export function formatCommandList({ title, commands, footer }) {
+  const width = Math.max(...commands.map(command => command.name.length));
+  const lines = [title, '', 'Available subcommands:'];
+  for (const command of commands) lines.push(`  ${command.name.padEnd(width)}  ${command.description}`);
+  if (footer) lines.push('', footer);
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Quote one argv token so the emitted confirmation hint is copy-pasteable
+ * in a POSIX shell. Boring tokens stay bare; anything containing spaces,
+ * quotes, `$`, `;`, `&`, `*` … gets single-quoted with embedded quotes
+ * escaped. `^ = < > ~ ! ,` are ServiceNow query characters — common in
+ * encoded queries — and are shell-safe bare, so they stay bare.
+ *
+ * @param {*} value — token
+ * @returns {string} shell-safe token
+ */
+export function quoteShellArg(value) {
+  const s = value == null ? '' : String(value);
+  if (s === '') return "''";
+  if (/^[A-Za-z0-9_@%+=:,./^-]+$/.test(s)) return s;
+  return `'${s.split("'").join("'\\''")}'`;
+}
+
+/**
+ * Build the exact, safely-quoted rerun command for a confirmation hint.
+ *
+ * `argv._` holds command PATH NAMES only — the local adapter stores
+ * positionals and flags in named fields — so a hint built from `argv._`
+ * alone loses the target (`jsn incidents delete` with no number). Callers
+ * therefore pass the complete target tokens.
+ *
+ * @param {object} argv — parsed args (reads `_`, `profile`, `instance`)
+ * @param {object} [opts]
+ * @param {string|string[]} [opts.rerun] — complete rerun command: a token
+ *   array (quoted here) or a full command string (used verbatim)
+ * @returns {string} command without `--force`, or '' when unknowable
+ */
+export function buildRerunCommand(argv = {}, { rerun = null } = {}) {
+  let parts;
+  if (Array.isArray(rerun) && rerun.length > 0) {
+    parts = ['jsn', ...rerun].map(quoteShellArg);
+  } else if (typeof rerun === 'string' && rerun.trim()) {
+    parts = [rerun.trim()];
+  } else {
+    parts = ['jsn', ...(argv?._ || [])].map(quoteShellArg);
+  }
+  if (parts.length === 1) return ''; // no path known — nothing worth repeating
+  const joined = parts.join(' ');
+  // Re-pin the profile/instance the caller was operating on, so following
+  // the hint cannot silently retarget a different instance or profile.
+  if (argv?.profile && !joined.includes('--profile')) parts.push('--profile', quoteShellArg(argv.profile));
+  if (argv?.instance && !joined.includes('--instance')) parts.push('--instance', quoteShellArg(argv.instance));
+  return parts.join(' ');
+}
+
 /**
  * Confirm a destructive action before executing.
  *
@@ -44,10 +131,12 @@ export function canPrompt() {
  * @param {object} app — app instance (reads active profile from app.config)
  * @param {object} argv — parsed args (checks argv.force)
  * @param {string} question — e.g. `Delete incident INC0010001?`
+ * @param {object} [options] — { rerun } complete rerun command or token
+ *   array for the hint (see buildRerunCommand)
  * @returns {Promise<boolean>} true when the action may proceed
  * @throws when confirmation is required but denied/unavailable
  */
-export async function confirmDelete(app, argv, question) {
+export async function confirmDelete(app, argv, question, options = {}) {
   const profile = getActiveProfile(app.config);
   if (profile?.skip_confirmations === true) return true;
   if (argv.force) return true;
@@ -65,8 +154,7 @@ export async function confirmDelete(app, argv, question) {
   }
   // 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);
+  throw errConfirmationRequired(question, buildRerunCommand(argv, options));
 }
 
 
@@ -283,14 +371,39 @@ export async function interactiveList({ app, table, singular, columns, limit = 5
   const pickerFields = pickerColumns.join(',');
   const baseQuery = query ? query + '^' : '';
 
-  // Get total count
-  let totalCount;
+  // Get total count. A FAILED count is unknown — never zero. Mapping the
+  // failure to 0 used to make callers report an invented "empty table"
+  // success (or silently return) when the real cause was a 403/network
+  // error. Only a measured 0 means empty; otherwise confirm emptiness with
+  // one bounded list request before showing the picker.
+  let totalCount = null;
+  let countError = null;
   try {
     totalCount = await app.sdk.aggregateCount(table, query || '');
-  } catch {
-    totalCount = 0;
+  } catch (err) {
+    countError = err;
+  }
+  if (totalCount === 0) return null; // measured empty
+
+  if (countError) {
+    try {
+      const probeParams = new URLSearchParams();
+      probeParams.set('sysparm_limit', '1');
+      probeParams.set('sysparm_display_value', 'all');
+      probeParams.set('sysparm_fields', 'sys_id');
+      if (query) probeParams.set('sysparm_query', query);
+      const probe = await app.sdk.list(table, probeParams);
+      if (!Array.isArray(probe)) throw new Error('list returned a non-array result');
+      if (probe.length === 0) return null; // the list itself confirms empty
+    } catch (err) {
+      // Both the count and the list failed — surface the failure instead of
+      // reporting an empty result nobody measured.
+      throw new Error(
+        `Could not list ${table}: ${err.message || err} (aggregate count also failed: ${countError.message || countError})`,
+        { cause: err }
+      );
+    }
   }
-  if (totalCount === 0) return null;
 
   // Paginated source adapter: (term, offset, { signal }) => choices[]
   async function serverSource(term, offset, { signal: _signal } = {}) {
@@ -403,7 +516,9 @@ export function parseDataArg(argv) {
   try {
     return JSON.parse(raw);
   } catch (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 });
+    // Never echo the raw payload: real --data bodies carry personal data and
+    // secrets, and the parse position from e.message is enough to debug.
+    throw new Error(`Invalid JSON: ${e.message}\n\nHint: Use --data-file for multiline payloads to avoid shell escaping issues.`, { cause: e });
   }
 }