@jacebenson/jsn 4.1.0 → 4.2.1

package/src/errors.js

@@ -142,15 +142,106 @@ export function isErrorCode(err, code) {
   return err instanceof AppError && err.code === code;
 }
 
+/**
+ * ── Unified error renderer ─────────────────────────────────────────────
+ * ONE place owns AppError → (stream, text, exit code). wrap()'s catch
+ * block, the middleware guard (guardError/guardExit), and any future
+ * entry point all route through renderAppError so the rendering can't
+ * diverge again (it had: wrap checked app.output.effectiveFormat() while
+ * guardError checked argv.format; 'usage' vs 'usage_error' disagreed).
+ *
+ * Exit-code contract (observable behavior, pinned by tests):
+ *   not_found              → 1   stderr, "Error (not_found): …" + identifier hint
+ *   usage / usage_error    → 2   stderr, "Error (usage): …"
+ *   system_error           → 3   stderr, "Error (system): …"
+ *   confirmation_required  → 1   JSON envelope on stdout in JSON mode
+ *                                (machine consumers), else stderr + hint
+ *   anything else          → 1   stderr, "Error: …"
+ *
+ * jsonMode resolution: prefer app.output.effectiveFormat() (respects
+ * --json/--quiet/etc. shortcuts AND piped-stdout auto-detection); fall
+ * back to argv.format for callers without an App (unit tests).
+ */
+function resolveJsonMode(app, argv) {
+  if (app?.output) return app.output.effectiveFormat() === 'json';
+  return argv?.format === 'json';
+}
+
+/**
+ * Render an error for the terminal/pipe.
+ *
+ * @param {object} err — Error with optional .code and .hint
+ * @param {object} [opts]
+ * @param {object} [opts.app] — App instance (format resolution, JSON envelope)
+ * @param {object} [opts.argv] — yargs argv (fallback format resolution)
+ * @param {string} [opts.identifier] — for not_found: the id that missed
+ * @returns {{ stream: 'stdout'|'stderr', text: string|null, exitCode: number, appErr?: boolean }}
+ *   text is null when the error was rendered through app.err (envelope).
+ */
+export function renderAppError(err, { app = null, argv = null, identifier = '' } = {}) {
+  const code = err.code || 'unknown';
+
+  if (code === CodeConfirmationRequired) {
+    // Structured error for AI agents / piped consumers: the JSON envelope
+    // goes to stdout (where tooling reads) so the agent can surface the
+    // decision to its user or re-run with --force.
+    if (resolveJsonMode(app, argv) && app) {
+      return { stream: 'stdout', text: null, exitCode: 1, appErr: true };
+    }
+    let text = `Error: ${err.message}\n`;
+    if (err.hint) text += `\n${err.hint}\n`;
+    return { stream: 'stderr', text, exitCode: 1 };
+  }
+
+  if (code === CodeNotFound) {
+    let text = `Error (${code}): ${err.message}\n`;
+    if (identifier) {
+      text += `\nHint: The identifier "${identifier}" was not found. Check the name or sys_id.\n`;
+    }
+    return { stream: 'stderr', text, exitCode: 1 };
+  }
+
+  // 'usage' is the legacy literal; CodeUsage ('usage_error') is the
+  // exported constant. Both render as the usage class.
+  if (code === CodeUsage || code === 'usage') {
+    return { stream: 'stderr', text: `Error (usage): ${err.message}\n`, exitCode: 2 };
+  }
+
+  if (code === 'system_error') {
+    return { stream: 'stderr', text: `Error (system): ${err.message}\n`, exitCode: 3 };
+  }
+
+  return { stream: 'stderr', text: `Error: ${err.message}\n`, exitCode: 1 };
+}
+
+/**
+ * Write + exit for a rendered error. Shared by wrap() and guardExit().
+ */
+export function exitWithError(err, opts = {}) {
+  const { app = null } = opts;
+  const r = renderAppError(err, opts);
+  if (r.appErr && app) {
+    app.err(err);
+  } else if (r.stream === 'stdout') {
+    process.stdout.write(r.text);
+  } else {
+    process.stderr.write(r.text);
+  }
+  process.exit(r.exitCode);
+}
+
 /**
  * Format a safety-guard failure (mutation guard middleware in cli.js).
  * In JSON mode writes the documented error envelope to stdout so piped
  * consumers (`jsn ... --json | jq`) get a structured error instead of a
  * raw stderr message. Otherwise writes human text to stderr.
  * Always exits non-zero via guardExit.
+ *
+ * Routes through the same JSON-mode resolution as renderAppError
+ * (app.output.effectiveFormat() when an App is on argv, else argv.format).
  */
 export function guardError(argv, { code, message, hint = '' }) {
-  if (argv?.format === 'json') {
+  if (resolveJsonMode(argv?.app, argv)) {
     return {
       stream: 'stdout',
       text: JSON.stringify({ ok: false, error: message, code, hint }) + '\n',

package/src/help.js

@@ -115,6 +115,7 @@ const CONFIG_COMMANDS = [
 ];
 
 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: 'skill', desc: 'AI agent skill file (show, fetch, install)' },

package/src/helpers.js

@@ -251,25 +251,36 @@ export function assertSafeExactMatch(value) {
  * @param {string} opts.singular — e.g. "script include", "log entry"
  * @param {string[]} opts.columns — default display columns
  * @param {number} opts.limit — max records (default 20)
- * @param {string} opts.query — optional encoded query
+ * @param {string} opts.query — optional encoded query, folded into every
+ *   request (browse pages, search-as-you-type, and the aggregate count)
  * @param {Function} opts.formatLabel — (record) => string for the picker display
  * @param {string} opts.labelField — field used to match selection (default: 'name')
- * @returns {Promise<void>|null} null if no selection made or non-interactive
+ * @param {string} [opts.message] — picker prompt message
+ *   (default: "Select a <singular>")
+ * @param {Function} [opts.formatValue] — (record) => value for the choice;
+ *   defaults to returning the full record on selection
+ * @param {Function} [opts.promptFn] — test seam: replaces paginatedSearch;
+ *   injecting it also bypasses the TTY/canPrompt gate (the test drives the
+ *   interactive path explicitly)
+ * @returns {Promise<*|null|undefined>} the selected record (or formatValue
+ *   result), undefined when the user cancelled, null when non-interactive
  */
-export async function interactiveList({ app, table, singular, columns, limit = 50, _query = '', formatLabel, labelField = 'name' }) {
+export async function interactiveList({ app, table, singular, columns, limit = 50, query = '', formatLabel, labelField = 'name', message, formatValue, promptFn }) {
+  const prompt = promptFn || paginatedSearch;
   app.requireInstance();
   const effectiveFormat = app.output.getFormat() === FormatAuto ? (isTTY(process.stdout) ? FormatAuto : FormatAuto) : app.output.getFormat();
-  if (effectiveFormat !== FormatAuto || !canPrompt()) {
+  if (!promptFn && (effectiveFormat !== FormatAuto || !canPrompt())) {
     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 pickerFields = pickerColumns.join(',');
+  const baseQuery = query ? query + '^' : '';
 
   // Get total count
   let totalCount;
   try {
-    totalCount = await app.sdk.aggregateCount(table, '');
+    totalCount = await app.sdk.aggregateCount(table, query || '');
   } catch {
     totalCount = 0;
   }
@@ -283,9 +294,9 @@ export async function interactiveList({ app, table, singular, columns, limit = 5
       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`);
+        params.set('sysparm_query', `${baseQuery}${labelField}LIKE${term}^ORDERBYDESCsys_updated_on`);
       } else {
-        params.set('sysparm_query', 'ORDERBYDESCsys_updated_on');
+        params.set('sysparm_query', baseQuery + 'ORDERBYDESCsys_updated_on');
         params.set('sysparm_offset', String(offset));
       }
       const records = await app.sdk.list(table, params);
@@ -295,7 +306,7 @@ export async function interactiveList({ app, table, singular, columns, limit = 5
       }
       return records.map(r => ({
         name: formatLabel ? formatLabel(r) : (getStringField(r, labelField) || getStringField(r, 'sys_id')),
-        value: r,
+        value: formatValue ? formatValue(r) : r,
       }));
     } catch (err) {
       console.error('serverSource error:', err.message || err);
@@ -303,14 +314,14 @@ export async function interactiveList({ app, table, singular, columns, limit = 5
     }
   }
 
-  const selected = await paginatedSearch({
-    message: `Select ${singular === 'flow' ? 'a flow' : `a ${singular}`}`,
+  const selected = await prompt({
+    message: message || `Select ${singular === 'flow' ? 'a flow' : `a ${singular}`}`,
     pageSize: 10,
     totalCount,
     source: serverSource,
   });
 
-  return selected?.value; // unwrap {name, value} → raw record, undefined on cancel
+  return selected?.value; // unwrap {name, value}, undefined on cancel
 }
 
 /**

package/src/mutations.js

@@ -1,105 +1,50 @@
-// Centralized mutation command registry
-// Used by the read-only profile middleware to block mutation commands.
-// Each entry is a command path array matching argv._ tokens.
+// Mutation guard — the public face is isMutationCommand(argv), used by the
+// read-only-profile middleware in cli.js. The command-path data is DERIVED
+// from the capability registry (src/capabilities.js) at call time — command
+// modules declare their mutating subcommands once, at the definition site.
+//
+// The registry used to be a hand-maintained list here, and it rotted: it
+// gated `catalog create-item` while the real command is `catalogitems
+// create` (read-only bypass), and listed `restmethods`, a command that was
+// never registered. Derived data can't drift that way.
 
-// Dev commands that expose create/update/delete via buildDevCmd.
-// Each generates the root form (`jsn <name> create`) and the legacy dev form
-// (`jsn dev <name> create`), so read-only profiles block both spellings.
-const DEV_CRUD_COMMANDS = [
-  'actions', 'includes', 'rules', 'clientscripts', 'uiactions', 'uipolicies',
-  'tables', 'uipages', 'appmenu', 'acls', 'roles', 'properties', 'relationships',
-  'appmodules', 'listcontrols', 'views', 'privileges', 'uxscripts',
-  'catalogscripts', 'scriptactions', 'scheduledjobs', 'asyncrules', 'triggers',
-  'email', 'restmethods', 'restmessage', 'soapmessages', 'uimacros',
-  'cataloguipolicies', 'aliases', 'columns', 'flows', 'scrapi',
-];
+import { mutationPaths } from './capabilities.js';
 
-function devCrudPaths(name) {
-  return [
-    [name, 'create'],
-    [name, 'update'],
-    [name, 'delete'],
-    ['dev', name, 'create'],
-    ['dev', name, 'update'],
-    ['dev', name, 'delete'],
-  ];
+/**
+ * Back-compat export: the derived mutation path list, refreshed by
+ * refreshMutationCommands() — cli.js calls it at the end of buildCLI(),
+ * so the data is generated at CLI build time, not hand-maintained.
+ * Prefer isMutationCommand().
+ */
+export const MUTATION_COMMANDS = [];
+
+export function refreshMutationCommands() {
+  MUTATION_COMMANDS.length = 0;
+  MUTATION_COMMANDS.push(...mutationPaths());
+  return MUTATION_COMMANDS;
 }
 
-export const MUTATION_COMMANDS = [
-  // Incidents
-  ['incidents', 'create'],
-  ['incidents', 'update'],
-  ['incidents', 'delete'],
-  // Changes
-  ['changes', 'create'],
-  ['changes', 'update'],
-  ['changes', 'delete'],
-  // Records
-  ['records', 'create'],
-  ['records', 'update'],
-  ['records', 'delete'],
-  // Requests
-  ['requests', 'create'],
-  ['requests', 'update'],
-  ['requests', 'delete'],
-  // Tasks
-  ['tasks', 'create'],
-  ['tasks', 'update'],
-  ['tasks', 'delete'],
-  // Tickets
-  ['tickets', 'create'],
-  ['tickets', 'update'],
-  ['tickets', 'delete'],
-  // Users
-  ['users', 'create'],
-  ['users', 'update'],
-  ['users', 'delete'],
-  // Groups
-  ['groups', 'create'],
-  ['groups', 'update'],
-  ['groups', 'delete'],
-  // Catalog
-  ['catalog', 'create-item'],
-  // Dev CRUD commands (root + `jsn dev` forms)
-  ...DEV_CRUD_COMMANDS.flatMap(devCrudPaths),
-  // Dev eval (no sub-action) — both spellings must be gated:
-  // `jsn eval` (root) and legacy `jsn dev eval`
-  ['eval'],
-  ['dev', 'eval'],
-  // Raw REST passthrough — can hit any endpoint with any method,
-  // so the whole command is a mutation surface on read-only profiles
-  ['rest'],
-  ['dev', 'rest'],
-  // Scopes: create + set (root + dev forms)
-  ['scopes', 'create'],
-  ['scopes', 'set'],
-  ['dev', 'scopes', 'create'],
-  ['dev', 'scopes', 'set'],
-  // 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'],
-];
+function currentPaths(paths) {
+  return paths || refreshMutationCommands();
+}
 
 /**
  * Check if the parsed argv matches any mutation command pattern.
+ * Prefix match: a command whose argv._ path begins with a mutation pattern
+ * IS that mutation (trailing positionals like a sys_id or file path don't
+ * change the intent). This lets positional mutation subcommands (e.g.
+ * `records attachments <id> add <file>`) be gated on read-only profiles.
+ *
  * @param {object} argv — yargs parsed argv with `_` array
+ * @param {Array<string[]>} [paths] — mutation path patterns; defaults to
+ *   the paths derived from the capability registry. (Tests pass explicit
+ *   paths; production callers should let it derive.)
  * @returns {boolean}
  */
-export function isMutationCommand(argv) {
+export function isMutationCommand(argv, paths) {
   const cmd = argv._ || [];
-  for (const pattern of MUTATION_COMMANDS) {
-    if (pattern.length !== cmd.length) continue;
+  for (const pattern of currentPaths(paths)) {
+    if (pattern.length > cmd.length) continue;
     let match = true;
     for (let i = 0; i < pattern.length; i++) {
       if (pattern[i] !== cmd[i]) {

package/src/output.js

@@ -7,6 +7,36 @@ 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;
@@ -27,6 +57,31 @@ 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`;
@@ -49,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;
@@ -57,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:
@@ -65,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:
@@ -160,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) {
@@ -178,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) {
@@ -241,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');
 
@@ -285,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) {
@@ -374,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) {
@@ -391,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');
@@ -458,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 };
 }
 
@@ -486,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;
+}