@jacebenson/jsn 4.0.4 → 4.2.0

package/src/output.js

@@ -1,13 +1,42 @@
 // Output formatting: JSON, Markdown, Styled, Quiet
 
 import process from 'node:process';
-import chalk from 'chalk';
 
 export const FormatAuto = 'auto';
 export const FormatJSON = 'json';
 export const FormatMarkdown = 'markdown';
 export const FormatStyled = 'styled';
 export const FormatQuiet = 'quiet';
+export const FormatCSV = 'csv';
+
+/**
+ * Resolve a dotpath (`.data[0].number`, `data.records.0.sys_id`) against an
+ * object. Supports dotted keys and `[N]` array indexes. Returns undefined
+ * when the path doesn't resolve. Dependency-free — not a jq replacement.
+ */
+export function resolvePath(obj, path) {
+  const s = String(path || '').trim().replace(/^\./, '');
+  if (!s) return undefined;
+  // Tokenize on dots, '[' and ']'. Pure-integer segments become array indexes.
+  const tokens = [];
+  let i = 0;
+  while (i < s.length) {
+    const ch = s[i];
+    if (ch === '.' || ch === '[' || ch === ']') { i += 1; continue; }
+    let j = i;
+    while (j < s.length && s[j] !== '.' && s[j] !== '[' && s[j] !== ']') j += 1;
+    const part = s.slice(i, j);
+    const n = Number(part);
+    tokens.push(Number.isInteger(n) && String(n) === part ? n : part);
+    i = j;
+  }
+  let cur = obj;
+  for (const tok of tokens) {
+    if (cur == null) return undefined;
+    cur = cur[tok];
+  }
+  return cur;
+}
 
 export function hyperlink(text, url) {
   if (!url) return text;
@@ -28,6 +57,37 @@ export function isTTY(writer) {
   return writer.isTTY === true;
 }
 
+// Default styled-table column widths for well-known ServiceNow fields.
+// Pure presentation defaults — commands can override per envelope via
+// `data.columnWidths` (see writeRecordsTable).
+const DEFAULT_COLUMN_WIDTHS = {
+  number: 14,
+  short_description: 48,
+  priority: 14,
+  state: 10,
+  assigned_to: 15,
+  risk: 10,
+  name: 30,
+  user_name: 15,
+  email: 30,
+  sys_id: 32,
+  sys_updated_on: 22,
+  sys_created_on: 22,
+  opened_at: 22,
+  closed_at: 22,
+  sys_updated_by: 20,
+  sys_created_by: 20,
+  opened_by: 20,
+  u_category: 20,
+  u_subcategory: 20,
+};
+
+// 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;
@@ -44,6 +104,16 @@ export class OutputWriter {
     return this;
   }
 
+  /**
+   * Set a dotpath extractor. When set, successful output is reduced to the
+   * value at the path (resolved against the JSON envelope) and printed as-is.
+   * Gives pipelines a dependency-free `--get` without needing jq.
+   */
+  setJqFilter(path) {
+    this.jqFilter = path || '';
+    return this;
+  }
+
   effectiveFormat() {
     if (this.format === FormatAuto) {
       return isTTY(this.writer) ? FormatStyled : FormatJSON;
@@ -52,6 +122,16 @@ export class OutputWriter {
   }
 
   ok(data, opts = {}) {
+    // --get extractor: resolve against the JSON envelope and print just that
+    // value as JSON. Takes precedence over styling/table formats — a path
+    // extract is inherently scriptable, not presentational.
+    if (this.jqFilter) {
+      const envelope = { ok: true, data, summary: opts.summary || '', breadcrumbs: opts.breadcrumbs || [] };
+      const value = resolvePath(envelope, this.jqFilter);
+      this.writer.write(JSON.stringify(value, null, 2) + '\n');
+      return;
+    }
+
     const format = this.effectiveFormat();
     switch (format) {
       case FormatJSON:
@@ -60,6 +140,8 @@ export class OutputWriter {
         return this.writeMarkdown(data, opts);
       case FormatQuiet:
         return this.writeQuiet(data);
+      case FormatCSV:
+        return this.writeCSV(data, opts);
       case FormatStyled:
         return this.writeStyled(data, opts);
       default:
@@ -82,8 +164,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');
         }
@@ -155,7 +237,58 @@ export class OutputWriter {
     }
   }
 
+  writeCSV(data, opts) {
+    if (opts.summary && isTTY(this.writer)) {
+      this.writer.write(opts.summary + '\n\n');
+    }
+    if (Array.isArray(data)) {
+      this.writeCSVTable(data);
+    } else if (data && typeof data === 'object' && Array.isArray(data.records)) {
+      this.writeCSVTable(data.records);
+    } else {
+      this.writeCSVTable([data]);
+    }
+  }
+
+  writeCSVTable(rows) {
+    if (!Array.isArray(rows) || rows.length === 0) {
+      this.writer.write('');
+      return;
+    }
+    const columns = Object.keys(rows[0]);
+    this.writer.write(columns.map(csvEscape).join(',') + '\n');
+    for (const row of rows) {
+      const cells = columns.map((col) => {
+        const val = row[col];
+        if (val == null) return '';
+        if (typeof val === 'object') {
+          if (val.display_value != null) return csvEscape(val.display_value);
+          if (val.value != null) return csvEscape(val.value);
+          return csvEscape(JSON.stringify(val));
+        }
+        return csvEscape(val);
+      });
+      this.writer.write(cells.join(',') + '\n');
+    }
+  }
+
   writeStyled(data, opts) {
+    // ── The `_formatted` interface ──────────────────────────────────────
+    // Commands may ship a pre-rendered styled view as `data._formatted`
+    // (a plain string). The writer prints it verbatim and suppresses both
+    // opts.summary and the records table / field-dump renderers — the
+    // curated visual IS the output. JSON/quiet/markdown/csv formats ignore
+    // `_formatted` entirely and serialize the full envelope as usual, so
+    // scripting (`--json`, `--get`) is unaffected.
+    //
+    // This is the documented escape hatch for command-curated visuals
+    // (auth status, cmdb show cards/trees, docs search results, …). View
+    // logic belongs in the command that owns the domain — output.js stays
+    // generic. Other underscore-prefixed side-channel keys commands may
+    // attach: `_context` ({instance_url, table} consumed by the record
+    // renderer), `_attachments`, `_variables` (record card sections), plus
+    // `records`/`columns`/`table`/`relationships` for the generic table and
+    // record views below.
     const hasFormatted = data && typeof data === 'object' && data._formatted;
 
     if (opts.summary && !hasFormatted) {
@@ -173,48 +306,18 @@ export class OutputWriter {
       }
 
       const { isRecord, tableName } = detectRecord(data);
-      if (isRecord) {
+      if (isRecord && !data._formatted) {
+        // _formatted (e.g. cmdb show card) replaces the raw field dump —
+        // the visual is the curated view; JSON/quiet keep full data.
         this.writeFormattedRecord(data, tableName);
       }
 
-      if (Array.isArray(data.profiles) && data.profiles.length > 0) {
-        this.writer.write('\n');
-        for (const p of data.profiles) {
-          const prefix = p.default ? '* ' : '  ';
-          const authIcon = p.authenticated ? '✓' : '✗';
-
-          // Show verified status if we got one
-          let verifiedStr = '';
-          if (p.verified === true) {
-            verifiedStr = ' ✅';
-          } else if (p.verified === false) {
-            verifiedStr = ' ⚠️';
-          }
-
-          // Show stale hint if >7 days since last seen
-          let staleStr = '';
-          if (p.stale && p.days_since_last_seen) {
-            staleStr = ` (${p.days_since_last_seen}d ago — may have been released)`;
-          }
-
-          // Show lock icon for read-only profiles
-          const lockIcon = p.read_only ? ' 🔒' : '';
-
-          // Show confirmations-off badge for skip_confirmations profiles
-          const confirmBadge = p.skip_confirmations ? ' ⚡' : '';
-
-          if (p.name) {
-            this.writer.write(`${prefix}${authIcon} ${p.name} — ${p.instance}${lockIcon}${confirmBadge}${verifiedStr}${staleStr}\n`);
-          } else if (p.username) {
-            this.writer.write(`${prefix}${authIcon} ${p.instance} (as ${p.username})${lockIcon}${confirmBadge}${verifiedStr}${staleStr}\n`);
-          } else {
-            this.writer.write(`${prefix}${authIcon} ${p.instance}${lockIcon}${confirmBadge}${verifiedStr}${staleStr}\n`);
-          }
-        }
-      }
-
       if (Array.isArray(data.records) && data.records.length > 0) {
-        this.writeRecordsTable(data);
+        // A _formatted visual (e.g. cmdb relationship tree) replaces the
+        // flat table in styled mode — showing both is noise.
+        if (!data._formatted) {
+          this.writeRecordsTable(data);
+        }
       }
     } else {
       if (!opts.summary) {
@@ -236,27 +339,10 @@ export class OutputWriter {
     const table = data.table || '';
     const instanceURL = data.context?.instance_url || '';
 
-    const colWidths = {
-      number: 14,
-      short_description: 48,
-      priority: 14,
-      state: 10,
-      assigned_to: 15,
-      risk: 10,
-      name: 30,
-      user_name: 15,
-      email: 30,
-      sys_id: 32,
-      sys_updated_on: 22,
-      sys_created_on: 22,
-      opened_at: 22,
-      closed_at: 22,
-      sys_updated_by: 20,
-      sys_created_by: 20,
-      opened_by: 20,
-      u_category: 20,
-      u_subcategory: 20,
-    };
+    // Default per-column widths for known ServiceNow fields; unknown columns
+    // fall back to 20. Commands may override/extend per call by attaching
+    // `data.columnWidths = { <col>: <width> }` — hints win over defaults.
+    const colWidths = { ...DEFAULT_COLUMN_WIDTHS, ...(data.columnWidths || {}) };
 
     this.writer.write('\n');
 
@@ -280,7 +366,9 @@ export class OutputWriter {
       const row = records[i];
       for (let j = 0; j < columns.length; j++) {
         const col = columns[j];
-        let val = row[col] || '';
+        // Coerce to string — rows can carry ServiceNow reference objects
+        // ({display_value, value}) and numeric cells (e.g. cmdb depth)
+        let val = getDisplayValue(row[col]);
         const width = colWidths[col] || 20;
 
         if (j === 0 && instanceURL && table && row.sys_id) {
@@ -369,7 +457,7 @@ export class OutputWriter {
       }
     }
 
-    const otherFields = Object.keys(data).filter(f => !displayed.has(f) && !f.startsWith('_')).sort();
+    const otherFields = Object.keys(data).filter(f => !displayed.has(f) && !f.startsWith('_') && f !== 'relationships').sort();
     if (otherFields.length > 0) {
       this.writer.write('─ Other ─\n');
       for (const field of otherFields) {
@@ -386,6 +474,33 @@ export class OutputWriter {
       this.writer.write('\n');
     }
 
+    // Inline relationships (e.g. cmdb show). Grouped shape:
+    // { parents: [], siblings: [], children: [], counts: {} } renders as
+    // sections; a flat array renders as one compact list.
+    if (data.relationships && typeof data.relationships === 'object' && !Array.isArray(data.relationships)) {
+      const renderGroup = (label, rows, total, arrow, viaKey) => {
+        if ((!rows || rows.length === 0) && !total) return;
+        const capNote = total && total > (rows?.length || 0) ? ` (showing ${rows.length} of ${total})` : '';
+        this.writer.write(`─ ${label}${capNote} ─\n`);
+        for (const rel of rows || []) {
+          const via = viaKey && rel[viaKey] ? ` (via ${rel[viaKey]})` : '';
+          this.writer.write(`  ${arrow} ${rel.name} (${rel.class}) — ${rel.type}${via}\n`);
+        }
+        this.writer.write('\n');
+      };
+      const counts = data.relationships.counts || {};
+      renderGroup('Parents', data.relationships.parents, counts.parents, '↑');
+      renderGroup('Siblings', data.relationships.siblings, counts.siblings, '↔', 'via');
+      renderGroup('Children', data.relationships.children, counts.children, '↓');
+    } else if (Array.isArray(data.relationships) && data.relationships.length > 0) {
+      this.writer.write('─ Relationships ─\n');
+      for (const rel of data.relationships) {
+        const arrow = rel.direction === 'upstream' ? '↑' : '↓';
+        this.writer.write(`  ${arrow} ${rel.name} (${rel.class}) — ${rel.type}\n`);
+      }
+      this.writer.write('\n');
+    }
+
     // ── Attachments ──
     if (data._attachments && Array.isArray(data._attachments) && data._attachments.length > 0) {
       this.writer.write('─ Attachments ─\n');
@@ -453,6 +568,12 @@ function detectRecord(data) {
     }
   }
 
+  // Explicit table stamp set by command handlers (e.g. _context.table on
+  // cmdb_rel_ci rows, which have neither sys_class_name nor number).
+  if (!tableName && data._context && typeof data._context === 'object' && data._context.table) {
+    tableName = data._context.table;
+  }
+
   return { isRecord: hasSysID && (hasSysClass || tableName), tableName };
 }
 
@@ -481,3 +602,13 @@ export function getDisplayValue(val) {
   }
   return String(val);
 }
+
+/** Escape a single CSV field: quote when it contains a delimiter, quote, or newline. */
+export function csvEscape(val) {
+  if (val == null) return '';
+  const s = String(val);
+  if (/[",\n\r]/.test(s)) {
+    return '"' + s.replace(/"/g, '""') + '"';
+  }
+  return s;
+}

package/src/resolve-record.js

@@ -0,0 +1,71 @@
+// Shared resolver for "find one record by a human identifier".
+//
+// Every command that accepts a number / name / user_name / sys_id used to
+// hand-roll the same five steps (classify the identifier, guard the query,
+// build params, fetch, unwrap sys_id) — and they drifted: hex detection
+// differed per file and some lookups forgot sysparm_display_value=all, so a
+// wrapped {value, display_value} sys_id leaked into update/delete calls.
+// This module is the single deep seam; commands shrink to
+// resolve → mutate → report.
+
+import { assertSafeExactMatch, isHexString } from './helpers.js';
+import { errNotFound } from './errors.js';
+
+/**
+ * True when the identifier looks like a ServiceNow sys_id (32 hex chars).
+ * Exported so call sites that only need classification share one definition.
+ */
+export function isSysId(identifier) {
+  return typeof identifier === 'string' && identifier.length === 32 && isHexString(identifier);
+}
+
+/**
+ * Unwrap a record's sys_id, which may be a plain string or a
+ * {value, display_value} object when display values were requested.
+ */
+export function unwrapSysId(record) {
+  const sysId = record?.sys_id;
+  if (sysId && typeof sysId === 'object') return sysId.value || sysId.display_value || '';
+  return sysId || '';
+}
+
+/**
+ * Resolve a single record by human identifier.
+ *
+ * @param {object} sdk — SDK handle (uses sdk.list)
+ * @param {object} opts
+ * @param {string} opts.table — ServiceNow table
+ * @param {string} opts.identifier — sys_id (32 hex) or value of matchField
+ * @param {string} opts.matchField — field to match non-sys_id identifiers on
+ *   (e.g. 'number', 'name', 'user_name')
+ * @param {string} [opts.resource] — label for the not-found error
+ *   (e.g. 'User' → "User not found: <id>"); defaults to matchField
+ * @param {string[]} [opts.fields] — restrict sysparm_fields when set
+ * @returns {Promise<object>} the record (display values requested)
+ * @throws {AppError} code not_found when no record matches
+ */
+export async function resolveRecord(sdk, { table, identifier, matchField, resource, fields }) {
+  assertSafeExactMatch(identifier);
+  const queryField = isSysId(identifier) ? 'sys_id' : matchField;
+  const params = new URLSearchParams();
+  params.set('sysparm_query', `${queryField}=${identifier}`);
+  params.set('sysparm_limit', '1');
+  params.set('sysparm_display_value', 'all');
+  if (fields && fields.length > 0) {
+    params.set('sysparm_fields', fields.join(','));
+  }
+  const records = await sdk.list(table, params);
+  if (records.length === 0) {
+    throw errNotFound(resource || matchField, identifier);
+  }
+  return records[0];
+}
+
+/**
+ * Resolve a record and return just its raw sys_id.
+ * Same options as resolveRecord; defaults to fetching only sys_id.
+ */
+export async function resolveSysId(sdk, opts) {
+  const record = await resolveRecord(sdk, { fields: ['sys_id'], ...opts });
+  return unwrapSysId(record);
+}

package/src/sdk.js

@@ -6,6 +6,23 @@ import { getStringField } from './helpers.js';
 
 const DEFAULT_TIMEOUT = 30000;
 
+// Build the sys.scripts.do POST body for background script execution.
+// Extracted for testability (issue #177): maps script-mode options to the
+// form fields on ServiceNow's Script Background form. Defaults preserve the
+// historical behavior (rollback recording on, quota-managed transaction on).
+export function buildScriptFormBody({ script, csrf, scope, rollback = true, quotaManagedTransaction = true, sandbox = false, scriptlet = false }) {
+  const formBody = new URLSearchParams();
+  formBody.set('script', script);
+  formBody.set('sysparm_ck', csrf);
+  formBody.set('runscript', 'Run script');
+  formBody.set('sys_scope', scope || 'global');
+  if (rollback) formBody.set('record_for_rollback', 'on');
+  if (quotaManagedTransaction) formBody.set('quota_managed_transaction', 'on');
+  if (sandbox) formBody.set('sandbox', 'on');
+  if (scriptlet) formBody.set('scriptlet', 'on');
+  return formBody;
+}
+
 export class SDKClient {
   constructor(baseURL, authProvider, opts = {}) {
     this.baseURL = baseURL.replace(/\/$/, '');
@@ -177,6 +194,55 @@ export class SDKClient {
     await this.request(endpoint, { method: 'DELETE' });
   }
 
+  // ─── Attachments ───
+
+  /**
+   * List attachments on a record.
+   * @param {string} sysID - record sys_id
+   * @returns {Promise<Array>} attachment metadata rows
+   */
+  async listAttachments(sysID) {
+    const params = new URLSearchParams();
+    params.set('sysparm_query', `table_sys_id=${sysID}`);
+    params.set('sysparm_display_value', 'all');
+    params.set('sysparm_fields', 'sys_id,file_name,size_bytes,content_type,sys_created_by,sys_created_on');
+    const endpoint = `${this.baseURL}/api/now/attachment?${params.toString()}`;
+    const result = await this.request(endpoint, { method: 'GET' });
+    return result?.result || [];
+  }
+
+  /**
+   * Download an attachment's file contents as a Buffer.
+   * @param {string} sysID - attachment sys_id
+   * @returns {Promise<Buffer>}
+   */
+  async getAttachment(sysID) {
+    const endpoint = `${this.baseURL}/api/now/attachment/${sysID}/file`;
+    const resp = await this._fetchWithAuth(endpoint, { method: 'GET', headers: { Accept: 'application/octet-stream' } });
+    if (!resp.ok) {
+      throw errAPI(resp.status, String(resp.statusText));
+    }
+    const buf = Buffer.from(await resp.arrayBuffer());
+    return buf;
+  }
+
+  /**
+   * Upload a file as a new attachment on a record.
+   * @param {string} table - parent table name (e.g. 'incident')
+   * @param {string} sysID - parent record sys_id
+   * @param {Buffer|string} content - file bytes or path
+   * @param {string} fileName - display file name
+   * @returns {Promise<object>} created attachment row
+   */
+  async addAttachment(table, sysID, content, fileName) {
+    const form = new FormData();
+    const blob = Buffer.isBuffer(content) ? new Blob([content]) : new Blob([String(content)]);
+    form.append('file', blob, fileName);
+    const endpoint = `${this.baseURL}/api/now/attachment?table_name=${encodeURIComponent(table)}&table_sys_id=${encodeURIComponent(sysID)}`;
+    const result = await this.request(endpoint, { method: 'POST', body: form });
+    return result?.result || null;
+  }
+
   async getCurrentUser() {
     const params = new URLSearchParams();
     params.set('sysparm_query', 'user_name=javascript:gs.getUserName()');
@@ -433,6 +499,31 @@ export class SDKClient {
 
   // ─── Background Script Execution (3-step OAuth session flow) ───
 
+  /**
+   * Export an update set to XML via the fluent export endpoint.
+   * Same session dance as executeScript: warm the session for cookies,
+   * grab the CSRF token from sys.scripts.do, then GET the export endpoint.
+   *
+   * @param {string} updateSetSysId - sys_id of the sys_update_set record
+   * @param {string} appSysId - sys_scope sys_id (scope of the update set)
+   * @returns {Promise<string>} The update set XML document
+   */
+  async exportUpdateSet(updateSetSysId, appSysId = '') {
+    const cookies = await this._warmSession();
+    const csrfToken = await this._getScriptsPageCSRF(cookies);
+
+    const params = new URLSearchParams();
+    params.set('sysparm_ck', csrfToken);
+    params.set('sysparm_sys_id', updateSetSysId);
+    params.set('sysparm_app_sys_id', appSysId);
+
+    const endpoint = `${this.baseURL}/fluent_update_set_export.do?${params.toString()}`;
+    return this.rawRequest(endpoint, {
+      method: 'GET',
+      headers: cookies ? { Cookie: cookies } : {},
+    });
+  }
+
   /**
    * Execute a background script on the ServiceNow instance via sys.scripts.do.
    * Uses a 3-step session-establishment flow compatible with OAuth tokens:
@@ -441,9 +532,16 @@ export class SDKClient {
    *  3. POST /sys.scripts.do with the script, CSRF token, and cookies
    *
    * @param {string} script - JavaScript code to execute
+   * @param {string} scope - Scope sys_id to run under ('' = global)
+   * @param {object} [opts] - Script-mode flags (issue #177), mapping to the
+   *   Script Background form checkboxes:
+   *   - rollback (default true) → record_for_rollback
+   *   - quotaManagedTransaction (default true) → quota_managed_transaction
+   *   - sandbox (default false) → sandbox (KittyScript, single expression)
+   *   - scriptlet (default false) → scriptlet
    * @returns {Promise<string>} The script's output text
    */
-  async executeScript(script, scope) {
+  async executeScript(script, scope, opts = {}) {
     // Step 1: Warm up the session by hitting any REST API — this makes
     // ServiceNow issue session cookies for subsequent UI page requests.
     // We capture cookies to forward them (Node.js fetch() has no built-in cookie jar).
@@ -454,13 +552,15 @@ export class SDKClient {
 
     // Step 3: POST the script with form data including the CSRF token.
     const endpoint = `${this.baseURL}/sys.scripts.do`;
-    const formBody = new URLSearchParams();
-    formBody.set('script', script);
-    formBody.set('sysparm_ck', csrfToken);
-    formBody.set('runscript', 'Run script');
-    formBody.set('sys_scope', scope || 'global');
-    formBody.set('record_for_rollback', 'on');
-    formBody.set('quota_managed_transaction', 'on');
+    const formBody = buildScriptFormBody({
+      script,
+      csrf: csrfToken,
+      scope,
+      rollback: opts.rollback,
+      quotaManagedTransaction: opts.quotaManagedTransaction,
+      sandbox: opts.sandbox,
+      scriptlet: opts.scriptlet,
+    });
 
     const html = await this.rawRequest(endpoint, {
       method: 'POST',