@jacebenson/jsn 4.3.12-dev.70 → 4.3.13-dev.100.1

package/src/mutation-history.js

@@ -0,0 +1,75 @@
+// Local convenience history, independent of documentation indexes and sync.
+import Database from 'better-sqlite3';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { errUsage } from './errors.js';
+
+export const RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+const operations = ['create', 'update', 'delete'];
+const outcomes = ['succeeded', 'failed', 'unknown'];
+export function historyPath() {
+  return path.join(process.env.JSN_DATA_HOME || path.join(os.homedir(), '.jsn'), 'history.db');
+}
+function openHistory(filename, now) {
+  fs.mkdirSync(path.dirname(filename), { recursive: true, mode: 0o700 });
+  const db = new Database(filename);
+  try {
+    if (process.platform !== 'win32') fs.chmodSync(filename, 0o600);
+    db.pragma('busy_timeout = 3000');
+    db.exec(`CREATE TABLE IF NOT EXISTS mutation_history (
+      id INTEGER PRIMARY KEY, timestamp INTEGER NOT NULL, instance TEXT NOT NULL,
+      profile TEXT, table_name TEXT NOT NULL, sys_id TEXT, operation TEXT NOT NULL,
+      outcome TEXT NOT NULL, reason TEXT, http_status INTEGER
+    ); CREATE INDEX IF NOT EXISTS mutation_history_time ON mutation_history(timestamp)`);
+    db.prepare('DELETE FROM mutation_history WHERE timestamp < ?').run(now - RETENTION_MS);
+    return db;
+  } catch (error) { db.close(); throw error; }
+}
+export function sanitizeReason(value) {
+  if (!value) return null;
+  // eslint-disable-next-line no-control-regex -- strip controls from user-supplied prose
+  return String(value).replace(/[\u0000-\u001f\u007f]/g, ' ')
+    .replace(/\b(?:Bearer|Basic)\s+\S+/gi, '[redacted]')
+    .replace(/\b(password|token|cookie|secret|authorization|access_token|sysparm_ck)\s*[:=]\s*(?:"[^"]*"|'[^']*'|\S+)/gi, '$1=[redacted]')
+    .slice(0, 1000);
+}
+export function appendMutation(event, { filename = historyPath(), now = Date.now() } = {}) {
+  if (!operations.includes(event.operation) || !outcomes.includes(event.outcome)) throw errUsage('Invalid history event');
+  const instance = new URL(event.instance).origin;
+  // Deliberate whitelist: never serialize SDK options, response bodies, or payloads.
+  const row = { timestamp: now, instance, profile: event.profile || null,
+    table_name: event.table, sys_id: event.sys_id || null, operation: event.operation,
+    outcome: event.outcome, reason: sanitizeReason(event.reason), http_status: event.http_status || null };
+  const db = openHistory(filename, now);
+  try {
+    db.prepare(`INSERT INTO mutation_history
+      (timestamp,instance,profile,table_name,sys_id,operation,outcome,reason,http_status)
+      VALUES (@timestamp,@instance,@profile,@table_name,@sys_id,@operation,@outcome,@reason,@http_status)`).run(row);
+  } finally { db.close(); }
+}
+export function pruneHistory({ filename = historyPath(), now = Date.now() } = {}) {
+  const db = openHistory(filename, now);
+  try { return { retentionDays: 7 }; } finally { db.close(); }
+}
+export function listHistory(filters = {}, { filename = historyPath(), now = Date.now() } = {}) {
+  const where = [], values = [];
+  for (const [key, column] of Object.entries({ instance: 'instance', profile: 'profile', table: 'table_name', operation: 'operation', record: 'sys_id' })) {
+    if (filters[key]) { where.push(`${column} = ?`); values.push(key === 'instance' ? new URL(filters[key]).origin : filters[key]); }
+  }
+  for (const [key, operator] of [['since', '>='], ['until', '<=']]) {
+    if (filters[key]) {
+      const time = Date.parse(filters[key]);
+      if (!Number.isFinite(time)) throw errUsage(`Invalid --${key} timestamp; use an ISO date`);
+      where.push(`timestamp ${operator} ?`); values.push(time);
+    }
+  }
+  const limit = filters.limit ?? 50;
+  if (!Number.isInteger(limit) || limit < 1 || limit > 10000) throw errUsage('--limit must be an integer from 1 to 10000');
+  const db = openHistory(filename, now);
+  try {
+    return db.prepare(`SELECT id,timestamp,instance,profile,table_name AS "table",sys_id,operation,outcome,reason,http_status
+      FROM mutation_history ${where.length ? `WHERE ${where.join(' AND ')}` : ''} ORDER BY timestamp DESC,id DESC LIMIT ?`)
+      .all(...values, limit).map(row => ({ ...row, timestamp: new Date(row.timestamp).toISOString() }));
+  } finally { db.close(); }
+}

package/src/mutations.js

@@ -8,7 +8,7 @@
 // create` (read-only bypass), and listed `restmethods`, a command that was
 // never registered. Derived data can't drift that way.
 
-import { mutationPaths } from './capabilities.js';
+import { mutationPaths, isLocalPreview } from './capabilities.js';
 
 /**
  * Back-compat export: the derived mutation path list, refreshed by
@@ -33,7 +33,7 @@ function currentPaths(paths) {
  * 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.
+ * `attachments upload <file>`) be gated on read-only profiles.
  *
  * @param {object} argv — yargs parsed argv with `_` array
  * @param {Array<string[]>} [paths] — mutation path patterns; defaults to
@@ -42,6 +42,7 @@ function currentPaths(paths) {
  * @returns {boolean}
  */
 export function isMutationCommand(argv, paths) {
+  if (isLocalPreview(argv)) return false;
   const cmd = argv._ || [];
   for (const pattern of currentPaths(paths)) {
     if (pattern.length > cmd.length) continue;

package/src/output.js

@@ -160,6 +160,13 @@ export class OutputWriter {
     const format = this.effectiveFormat();
     const e = error.code ? error : { code: 'unknown', message: String(error), hint: '' };
     const resp = { ok: false, error: e.message, code: e.code, hint: e.hint || '' };
+    if (e.resolution) resp.resolution = e.resolution;
+    if (e.context) resp.context = e.context;
+    if (e.status === 401 || e.status === 403) resp.status = e.status;
+    if (e.recovery) {
+      resp.recovery = e.recovery;
+      if (Object.hasOwn(e, 'profile')) resp.profile = e.profile;
+    }
     switch (format) {
       case FormatJSON:
       case FormatQuiet:
@@ -282,7 +289,7 @@ export class OutputWriter {
   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
+    // (a plain string). The writer ensures a trailing newline 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
@@ -309,7 +316,7 @@ export class OutputWriter {
       }
     } else if (data && typeof data === 'object') {
       if (data._formatted) {
-        this.writer.write(data._formatted);
+        this.writer.write(data._formatted.endsWith('\n') ? data._formatted : data._formatted + '\n');
       }
 
       const { isRecord, tableName } = detectRecord(data);
@@ -508,6 +515,31 @@ export class OutputWriter {
       this.writer.write('\n');
     }
 
+    if (data._essential && typeof data._essential === 'object') {
+      for (const [name, related] of Object.entries(data._essential)) {
+        this.writer.write(`─ Essential: ${name} (${related.loaded} loaded${related.has_more ? ', more available' : ''}) ─\n`);
+        if (related.status !== 'loaded') this.writer.write(`  Unavailable: ${related.error?.message || 'Read could not be completed.'}\n`);
+        for (const row of related.records || []) {
+          const fields = Object.entries(row).filter(([field]) => field !== 'sys_id').map(([field, value]) => `${field}: ${getDisplayValue(value)}`);
+          this.writer.write(`  ${fields.join(' | ')}\n`);
+        }
+        this.writer.write(`  ${related.visibility}\n`);
+        if (related.command) this.writer.write(`  Retrieve: ${related.command}\n`);
+        this.writer.write('\n');
+      }
+    }
+
+    if (data._related && typeof data._related === 'object') {
+      this.writer.write('─ Related lists ─\n');
+      for (const list of data._related.nonempty || []) {
+        this.writer.write(`  ${list.label}: ${list.count}\n`);
+        if (list.command) this.writer.write(`  Retrieve: ${list.command}\n`);
+      }
+      this.writer.write(`  Coverage: ${data._related.coverage?.state || 'unknown'}; counts reflect aggregate API access and visible metadata.\n`);
+      for (const warning of data._related.coverage?.warnings || []) this.writer.write(`  Unknown (${warning.source}): ${warning.reason}\n`);
+      this.writer.write('\n');
+    }
+
     // ── Attachments ──
     if (data._attachments && Array.isArray(data._attachments) && data._attachments.length > 0) {
       this.writer.write('─ Attachments ─\n');

package/src/record-command-profiles.js

@@ -0,0 +1,70 @@
+// Edit table/ticket command defaults here. The key is the CLI command name.
+// Identifier/output defaults and empty relationship policies live in record-profiles.js.
+export default {
+  includes: { table: 'sys_script_include', aliases: ['include', 'si'], columns: ['name', 'api_name', 'active', 'sys_scope'],
+    options: { singular: 'script include', scopeValidation: true } },
+  rules: { table: 'sys_script', aliases: ['rule', 'br'], columns: ['name', 'collection', 'active', 'order', 'sys_scope'],
+    options: { singular: 'business rule', scopeValidation: true } },
+  clientscripts: { table: 'sys_script_client', aliases: ['clientscript', 'cs'], columns: ['name', 'table', 'active', 'type', 'sys_scope'],
+    options: { singular: 'client script', scopeValidation: true } },
+  uiactions: { table: 'sys_ui_action', aliases: ['uiaction', 'ua'], columns: ['name', 'table', 'active', 'order', 'sys_scope'],
+    options: { singular: 'UI action', scopeValidation: true } },
+  sppages: { table: 'sp_page', aliases: ['sp-pages'], columns: ['id', 'title', 'sys_scope'],
+    options: { singular: 'Service Portal page', readOnly: true } },
+  spwidgets: { table: 'sp_widget', aliases: ['sp-widget', 'widgets'], columns: ['id', 'name', 'sys_scope'],
+    options: { singular: 'Service Portal widget', readOnly: true } },
+  uipages: { table: 'sys_ui_page', aliases: ['ui-page', 'pages'], columns: ['name', 'sys_scope'],
+    options: { singular: 'UI page', scopeValidation: true } },
+  appmenu: { table: 'sys_app_application', aliases: ['app-menu', 'menu'], columns: ['name', 'active', 'sys_scope'],
+    options: { singular: 'application menu', scopeValidation: true } },
+  acls: { table: 'sys_security_acl', aliases: ['acl'], columns: ['name', 'operation', 'type', 'active', 'sys_scope'],
+    options: { singular: 'ACL', scopeValidation: true, help: 'Investigate table, field, wildcard and inherited ACL names for the relevant operation. Exact name=incident alone does not cover incident.caller_id, incident.*, *.caller_id or inherited-table ACLs. Roles, conditions and scripts affect effective access; rows alone do not prove access. See jsn columns --help for field investigation paths.' } },
+  roles: { table: 'sys_user_role', aliases: ['role', 'r'], columns: ['name', 'description', 'elevated_privilege', 'sys_scope'],
+    options: { singular: 'role', scopeValidation: true } },
+  properties: { table: 'sys_properties', aliases: ['property', 'prop'], columns: ['name', 'value', 'description', 'sys_scope'],
+    options: { singular: 'property', scopeValidation: true } },
+  relationships: { table: 'sys_relationship', aliases: ['relationship', 'rel'], columns: ['name', 'sys_scope'],
+    options: { singular: 'relationship', scopeValidation: true } },
+  appmodules: { table: 'sys_app_module', aliases: ['appmodule', 'am'], columns: ['name', 'active', 'sys_scope'],
+    options: { singular: 'application module', scopeValidation: true } },
+  listcontrols: { table: 'sys_ui_list_control', aliases: ['listcontrol', 'lc'], columns: ['name', 'active', 'sys_scope'],
+    options: { singular: 'list control', scopeValidation: true } },
+  views: { table: 'sys_ui_view', aliases: ['view', 'vw'], columns: ['name', 'title', 'sys_scope'],
+    options: { singular: 'view', scopeValidation: true } },
+  privileges: { table: 'sys_scope_privilege', aliases: ['privilege', 'priv'], columns: ['source_scope', 'target_scope', 'target_name', 'operation', 'status'],
+    options: { singular: 'privilege', scopeValidation: true } },
+  uxscripts: { table: 'sys_ux_lib_source_script', aliases: ['uxscript', 'ux'], columns: ['name', 'active', 'sys_scope'],
+    options: { singular: 'UX script', scopeValidation: true } },
+  catalogscripts: { table: 'catalog_script_client', aliases: ['catalogscript'], columns: ['name', 'table', 'active', 'sys_scope'],
+    options: { singular: 'catalog script', scopeValidation: true } },
+  scriptactions: { table: 'sysevent_script_action', aliases: ['scriptaction'], columns: ['name', 'active', 'sys_scope'],
+    options: { singular: 'script action', scopeValidation: true } },
+  scheduledjobs: { table: 'sysauto_script', aliases: ['scheduledjob'], columns: ['name', 'active', 'run_type', 'sys_scope'],
+    options: { singular: 'scheduled job', scopeValidation: true } },
+  asyncrules: { table: 'sys_script', aliases: ['asyncrule'], columns: ['name', 'collection', 'active', 'order', 'sys_scope'],
+    options: { singular: 'async business rule', scopeValidation: true, extraQuery: 'when=async' } },
+  triggers: { table: 'sysevent_register', aliases: ['trigger'], columns: ['name', 'event_name', 'active', 'sys_scope'],
+    options: { singular: 'event trigger', scopeValidation: true } },
+  assignments: { table: 'sysrule_assignment', aliases: ['assignment'], columns: ['name', 'active', 'sys_scope'],
+    options: { singular: 'assignment rule', scopeValidation: true, readOnly: true } },
+  email: { table: 'sysevent_in_email_action', aliases: ['emails'], columns: ['name', 'active', 'type', 'sys_scope'],
+    options: { singular: 'inbound email action', scopeValidation: true } },
+  uimacros: { table: 'sys_ui_macro', aliases: ['uimacro'], columns: ['name', 'active', 'sys_scope'],
+    options: { singular: 'UI macro', scopeValidation: true } },
+  uxlists: { table: 'sys_ux_list', aliases: ['uxlist'], columns: ['name', 'active', 'sys_scope'],
+    options: { singular: 'workspace list', scopeValidation: true, readOnly: true } },
+  uxapplicability: { table: 'sys_ux_applicability_m2m', aliases: ['uxapp'], columns: ['name', 'active', 'sys_scope'],
+    options: { singular: 'workspace applicability', scopeValidation: true, readOnly: true } },
+  cataloguipolicies: { table: 'catalog_ui_policy', aliases: ['cataloguipolicy', 'cup'], columns: ['short_description', 'catalog_item', 'variable_set', 'active', 'sys_scope'],
+    options: { singular: 'catalog UI policy', scopeValidation: true } },
+  tables: { table: 'sys_db_object', aliases: ['table', 't'], columns: ['name', 'label', 'super_class', 'create_access_controls'],
+    options: { singular: 'table', scopeValidation: true, showFields: ['name', 'label', 'super_class', 'create_access_controls', 'sys_scope', 'sys_created_on', 'sys_updated_on', 'sys_created_by', 'sys_updated_by', 'is_extendable'] } },
+  incidents: { table: 'incident', aliases: ['incident', 'inc'], columns: ['number', 'short_description', 'priority', 'state', 'assigned_to'], kind: 'ticket' },
+  changes: { table: 'change_request', aliases: ['change_request', 'chg'], columns: ['number', 'short_description', 'risk', 'state', 'assigned_to'], kind: 'ticket' },
+  requests: { table: 'sc_req_item', aliases: ['sc_req_item', 'req'], columns: ['number', 'short_description', 'stage', 'assigned_to'], kind: 'ticket' },
+  tasks: { table: 'sc_task', aliases: ['sc_task', 'task'], columns: ['number', 'short_description', 'state', 'assigned_to'], kind: 'ticket' },
+  uipolicies: { table: 'sys_ui_policy', aliases: ['uipolicy', 'up'], columns: ['short_description', 'table', 'sys_class_name', 'active'],
+    identifierField: 'short_description', options: { singular: 'UI policy', scopeValidation: true },
+    relationships: { essential: [{ name: 'actions', table: 'sys_ui_policy_action', foreignKey: 'ui_policy', limit: 100, orderBy: 'order',
+      columns: ['name', 'table', 'field_name', 'read_only', 'mandatory', 'visible'] }] } },
+};

package/src/record-profiles.js

@@ -0,0 +1,93 @@
+// Declarative command metadata is consumed by the actual command factories.
+// Hooks stay executable code; the compact registry owns aliases/table/defaults/relationship policy.
+import definitions from './record-command-profiles.js';
+import { enrichEssentialRecords } from './essential-records.js';
+import { buildDevCmd } from './commands/_generic.js';
+import { buildTicketCommands } from './commands/_ticket.js';
+
+const namePattern = /^[a-z][a-z0-9_-]*$/i;
+const fieldPattern = /^[a-z_][a-z0-9_]*$/i;
+function freeze(value) {
+  if (value && typeof value === 'object') {
+    for (const entry of Object.values(value)) freeze(entry);
+    Object.freeze(value);
+  }
+  return value;
+}
+export function validateRecordProfiles(profiles) {
+  if (!Array.isArray(profiles)) throw new Error('Record profiles must be an array.');
+  const names = new Set();
+  return profiles.map(definition => {
+    for (const key of ['options', 'output', 'relationships']) {
+      if (definition[key] !== undefined && (!definition[key] || typeof definition[key] !== 'object' || Array.isArray(definition[key]))) throw new Error(`Invalid ${key} for ${definition.name}.`);
+    }
+    const profile = { ...definition,
+      identifierField: definition.identifierField ?? (definition.kind === 'ticket' ? 'number' : 'name'),
+      options: { ...definition.options },
+      output: { references: 'both', listProjection: 'display', ...definition.output },
+      relationships: { essential: [], supplementary: [], ...definition.relationships },
+    };
+    if (!namePattern.test(profile.name || '') || names.has(profile.name)) throw new Error('Invalid or duplicate record profile name.');
+    names.add(profile.name);
+    if (!fieldPattern.test(profile.table || '') || !fieldPattern.test(profile.identifierField || '')) throw new Error(`Invalid table/identifier field for ${profile.name}.`);
+    if (!Array.isArray(profile.aliases) || !profile.aliases.every(alias => namePattern.test(alias))) throw new Error(`Invalid aliases for ${profile.name}.`);
+    if (!Array.isArray(profile.columns) || !profile.columns.length || !profile.columns.every(field => fieldPattern.test(field))) throw new Error(`Invalid columns for ${profile.name}.`);
+    if (!['dev', 'ticket'].includes(profile.kind || 'dev')) throw new Error(`Invalid factory kind for ${profile.name}.`);
+    if (!['raw', 'display', 'both'].includes(profile.output?.references) || !['display', 'full'].includes(profile.output?.listProjection)) throw new Error(`Invalid output preferences for ${profile.name}.`);
+    if (!profile.options || typeof profile.options !== 'object' || Array.isArray(profile.options)) throw new Error(`Invalid factory options for ${profile.name}.`);
+    for (const key of ['readOnly', 'scopeValidation']) {
+      if (profile.options[key] !== undefined && typeof profile.options[key] !== 'boolean') throw new Error(`Invalid ${key} option for ${profile.name}.`);
+    }
+    for (const kind of ['essential', 'supplementary']) {
+      if (!Array.isArray(profile.relationships?.[kind])) throw new Error(`Missing ${kind} relationship policy for ${profile.name}.`);
+      const relationshipNames = new Set();
+      for (const relationship of profile.relationships[kind]) {
+        if (relationshipNames.has(relationship.name)) throw new Error(`Duplicate relationship for ${profile.name}.`);
+        relationshipNames.add(relationship.name);
+        if (relationship.limit !== undefined && (!Number.isInteger(relationship.limit) || relationship.limit < 1 || relationship.limit > 1000)) throw new Error(`Invalid relationship limit for ${profile.name}.`);
+        if (relationship.orderBy !== undefined && !fieldPattern.test(relationship.orderBy)) throw new Error(`Invalid relationship ordering for ${profile.name}.`);
+        if (relationship.columns !== undefined && (!Array.isArray(relationship.columns) || !relationship.columns.every(field => fieldPattern.test(field)))) throw new Error(`Invalid relationship columns for ${profile.name}.`);
+        if (!namePattern.test(relationship.name || '') || !fieldPattern.test(relationship.table || '') || !fieldPattern.test(relationship.foreignKey || '')) throw new Error(`Invalid relationship for ${profile.name}.`);
+      }
+    }
+    return freeze(structuredClone(profile));
+  });
+}
+const profiles = freeze(validateRecordProfiles(Object.entries(definitions).map(([name, profile]) => ({ name, ...profile }))));
+const index = new Map(profiles.map(profile => [profile.name, profile]));
+export const recordProfiles = () => profiles;
+export function getRecordProfile(name) {
+  const profile = index.get(name);
+  if (!profile) throw new Error(`Unknown record command profile: ${name}`);
+  return profile;
+}
+export function buildProfileCommand(name, wrap, hooks = {}) {
+  return buildRecordProfile(getRecordProfile(name), wrap, hooks);
+}
+
+export function buildRecordProfile(definition, wrap, hooks = {}) {
+  const [profile] = validateRecordProfiles([definition]);
+  const options = { ...profile.options, identifierField: profile.identifierField,
+    referenceMode: profile.output.references, listProjection: profile.output.listProjection,
+    relationships: profile.relationships, ...hooks };
+  if (profile.relationships.essential.length) {
+    const hook = options.onShow;
+    options.onShow = async (record, app, argv = {}) => {
+      if (hook) await hook(record, app, argv);
+      if (argv.essential !== false) await enrichEssentialRecords(record, { sdk: app.sdk,
+        relationships: profile.relationships.essential, displayValues: argv.displayValues ?? profile.output.references,
+        profileName: app.session?.profileName, instance: app.getEffectiveInstance?.() });
+    };
+  }
+  const command = profile.kind === 'ticket'
+    ? buildTicketCommands(profile.table, profile.name, profile.aliases.find(alias => alias !== profile.table), profile.columns, {}, null, wrap, options)
+    : buildDevCmd(profile.name, profile.table, profile.aliases, profile.columns, wrap, options);
+  command.aliases = [...profile.aliases];
+  command.recordProfile = profile;
+  command.discovery.benefits.push(
+    `Reference output: ${profile.output.references}; list projection: ${profile.output.listProjection}`,
+    ...profile.relationships.essential.map(relationship =>
+      `Essential ${relationship.name} records from ${relationship.table} on show (disable with --no-essential)`),
+  );
+  return command;
+}

package/src/records-engine.js

@@ -0,0 +1,57 @@
+// In-process CRUD transport shared by generic and specialized commands.
+// Policy (confirmation, scope, payload and output shape) stays with callers.
+import { resolveRecord, unwrapSysId } from './resolve-record.js';
+import { errUsage } from './errors.js';
+
+export function displayValue(mode, fallback = 'all') {
+  if (mode === undefined) return fallback;
+  const values = { raw: 'false', display: 'true', both: 'all' };
+  if (!Object.hasOwn(values, mode)) throw errUsage('display-values must be raw, display or both');
+  return values[mode];
+}
+
+export function recordListParams({ limit, offset, query, fields, displayValue: representation = 'all' } = {}) {
+  const params = new URLSearchParams({ sysparm_display_value: representation });
+  if (limit !== undefined) params.set('sysparm_limit', String(limit));
+  if (offset !== undefined) params.set('sysparm_offset', String(offset));
+  if (query) params.set('sysparm_query', query);
+  if (fields) params.set('sysparm_fields', Array.isArray(fields) ? fields.join(',') : fields);
+  return params;
+}
+
+export function listRecords(sdk, { table, params, displayValues, ...options }) {
+  const query = params ? new URLSearchParams(params) : recordListParams(options);
+  if (displayValues !== undefined) query.set('sysparm_display_value', displayValue(displayValues));
+  return sdk.list(table, query);
+}
+
+export function getRecord(sdk, options) {
+  return resolveRecord(sdk, { ...options, displayValue: displayValue(options.displayValues, options.displayValue || 'all') });
+}
+
+export function createRecord(sdk, { table, data }) {
+  return sdk.create(table, data);
+}
+
+function mutationId(record) {
+  const id = unwrapSysId(record);
+  if (!id) throw errUsage('The matched record has no readable sys_id; check field ACLs before retrying.');
+  return id;
+}
+
+export async function updateRecord(sdk, { table, data, record, ...lookup }) {
+  const resolved = record || await getRecord(sdk, { table, ...lookup });
+  return sdk.update(table, mutationId(resolved), data);
+}
+
+export async function deleteRecord(sdk, { table, record, ...lookup }) {
+  const resolved = record || await getRecord(sdk, { table, ...lookup });
+  const id = mutationId(resolved);
+  await sdk.delete(table, id);
+  return id;
+}
+
+export function recordOptions(y, display = true) {
+  const command = y.option('identifier-field', { type: 'string', describe: 'Exact field for disambiguation (sys_id, number, name, etc); no human-field partial matches' });
+  return display ? command.option('display-values', { type: 'string', choices: ['raw', 'display', 'both'], describe: 'Reference values: raw, display or both; omitted preserves existing output' }) : command;
+}

package/src/related-lists.js

@@ -0,0 +1,153 @@
+// Opt-in related-list counts. Counts never fetch supplementary records; hints
+// leave opening the list to an explicit subsequent command.
+import { assertSafeExactMatch, quoteShellArg } from './helpers.js';
+import { errUsage } from './errors.js';
+const namePattern = /^[A-Za-z0-9_]+$/;
+const isName = value => typeof value === 'string' && namePattern.test(value);
+const raw = value => String(value && typeof value === 'object' ? value.value ?? '' : value ?? '');
+
+/** Only a conservative, AND-only literal encoded-query subset can be combined
+ * with a record reference. Unknown platform/dynamic logic stays unavailable. */
+export function safeRelatedFilter(value = '') {
+  if (typeof value !== 'string' || /javascript\s*:|\r|\n/i.test(value)) return null;
+  if (!value) return '';
+  const clauses = value.split('^');
+  if (clauses.at(-1) === 'EQ') clauses.pop();
+  if (!clauses.length) return '';
+  for (const clause of clauses) {
+    if (!clause || /^(?:OR|NQ|ORDERBY)/i.test(clause)) return null;
+    if (!/^[A-Za-z0-9_]+(?:\.[A-Za-z0-9_]+)*(?:(?:!=|>=|<=|=|>|<|NOT LIKE|STARTSWITH|ENDSWITH|LIKE|NOT IN|IN)[^^]*|ISEMPTY|ISNOTEMPTY)$/.test(clause)) return null;
+  }
+  return clauses.join('^');
+}
+function parseCount(body) {
+  const result = body?.result;
+  const entry = Array.isArray(result) && result.length === 1 && !result[0]?.groupby_fields?.length
+    ? result[0] : result;
+  let stats = entry?.stats;
+  if (typeof stats === 'string') { try { stats = JSON.parse(stats); } catch { return null; } }
+  const count = stats?.count;
+  if (typeof count !== 'number' && (typeof count !== 'string' || !/^\d+$/.test(count))) return null;
+  const number = Number(count);
+  return Number.isSafeInteger(number) && number >= 0 ? number : null;
+}
+function hint(table, query, { profile, instance }) {
+  const tokens = ['jsn', 'records', 'list', '--table', table, '--query', query];
+  if (profile) tokens.push('--profile', profile);
+  if (instance) tokens.push('--instance', instance);
+  return tokens.map(quoteShellArg).join(' ');
+}
+
+/** Invocation-bound reader. Metadata/aggregate failures are coverage gaps, not
+ * zero counts. Optional batch owns endpoint fallback; items never replay. */
+export function createRelatedListReader(sdk, { metadataReader, maxLists = 50 } = {}) {
+  if (!Number.isInteger(maxLists) || maxLists < 1 || maxLists > 1000) throw errUsage('Related-list limit must be an integer from 1 to 1000.');
+  const cache = new Map();
+  let reader = metadataReader;
+  async function read({ table, recordId, view = 'Default view', profile = '', instance = '' }) {
+    if (!isName(table)) throw errUsage('Related-list table must be a valid table name.');
+    const id = raw(recordId);
+    if (!id || !/^[A-Za-z0-9_-]+$/.test(id)) throw errUsage('Related-list counts require a safe, resolved record sys_id.');
+    assertSafeExactMatch(id);
+    if (!reader) {
+      const { createRecordMetadataReader } = await import('./metadata/records.js');
+      reader = createRecordMetadataReader(sdk);
+    }
+    const metadata = await reader.read({ table, view });
+    const warnings = [...(metadata.coverage?.warnings || [])];
+    const descriptors = metadata.related_lists || [];
+    const prepared = descriptors.map((list, index) => {
+      const result = { id: list.id, label: list.label || list.id, table: list.table || null,
+        reference_field: list.reference_field || null, configured: !!list.configured,
+        status: 'unavailable', count: null };
+      let reason;
+      const filter = safeRelatedFilter(list.filter || '');
+      if (list.query_status !== 'reference' || !isName(list.table) || !isName(list.reference_field)) reason = list.reason || 'Related list requires platform relationship logic or unavailable metadata.';
+      else if (list.configured && list.filter_available === false) reason = 'Configured related-list filter is not visible; count was not requested.';
+      else if (filter === null) reason = 'Related-list filter uses unsupported dynamic or disjunctive query logic; count was not requested.';
+      if (reason) {
+        result.reason = reason; warnings.push({ source: list.id, reason }); return { result };
+      }
+      const query = `${list.reference_field}=${id}${filter ? `^${filter}` : ''}`;
+      if (index >= maxLists) {
+        const reason = `Related-list limit ${maxLists} reached; count was not requested. Open this specific list explicitly or raise --related-limit.`;
+        warnings.push({ source: list.id, reason });
+        return { result: { ...result, reason, query, command: hint(list.table, query, { profile, instance }) } };
+      }
+      const params = new URLSearchParams({ sysparm_count: 'true', sysparm_query: query });
+      const url = `/api/now/stats/${list.table}?${params}`;
+      return { result, query, url };
+    });
+    const unique = [...new Set(prepared.filter(item => item.url && !cache.has(item.url)).map(item => item.url))];
+    if (unique.length) {
+      const pending = (async () => {
+        if (typeof sdk.batch === 'function' && unique.length > 1) {
+          try {
+            const batch = await sdk.batch(unique.map((url, index) => ({ id: `related-${index}`, method: 'GET', url })), { fallback: true });
+            return unique.map((_, index) => {
+              const item = batch.results?.find(value => value.id === `related-${index}`);
+              if (!item?.ok) return { count: null, status: item?.status || null,
+                reason: item?.error?.message || 'Aggregate subrequest was unavailable or unserviced.' };
+              const count = parseCount(item.data);
+              return { count, status: item.status, ...(count === null ? { reason: 'Aggregate response did not contain a valid count.' } : {}) };
+            });
+          } catch (error) {
+            return unique.map(() => ({ count: null, status: error.status || null, reason: error.message || 'Aggregate batch failed.' }));
+          }
+        }
+        const individual = async url => {
+          try {
+            const body = await sdk.request(`${sdk.baseURL}${url}`, { method: 'GET', readOnly: true });
+            const count = parseCount(body);
+            return { count, ...(count === null ? { reason: 'Aggregate response did not contain a valid count.' } : {}) };
+          } catch (error) { return { count: null, status: error.status || null, reason: error.message || 'Aggregate request failed.' }; }
+        };
+        const results = new Array(unique.length);
+        let next = 0;
+        await Promise.all(Array.from({ length: Math.min(4, unique.length) }, async () => {
+          while (next < unique.length) {
+            const index = next++;
+            results[index] = await individual(unique[index]);
+          }
+        }));
+        return results;
+      })();
+      unique.forEach((url, index) => cache.set(url, pending.then(items => items[index])));
+    }
+    const lists = await Promise.all(prepared.map(async item => {
+      if (!item.url) return item.result;
+      const observed = await cache.get(item.url);
+      if (observed.count === null) {
+        warnings.push({ source: item.result.id, reason: observed.reason, ...(observed.status ? { status: observed.status } : {}) });
+        return { ...item.result, reason: observed.reason, ...(observed.status ? { http_status: observed.status } : {}) };
+      }
+      return { ...item.result, status: 'available', count: observed.count, query: item.query,
+        ...(observed.count > 0 ? { command: hint(item.result.table, item.query, { profile, instance }) } : {}) };
+    }));
+    return { table, record_id: id, view, lists, nonempty: lists.filter(list => list.count > 0),
+      coverage: { state: metadata.coverage?.state === 'partial' || warnings.length ? 'partial' : 'observed',
+        scope: 'aggregate_api_access', warnings } };
+  }
+  return { read, clear() { cache.clear(); reader?.clear?.(); } };
+}
+
+/** Specialized show hook; ordinary shows and generic records get do no work. */
+export async function enrichRelatedLists(record, { table, argv = {}, app }) {
+  if (!argv.related) return record;
+  const limit = argv['related-limit'] ?? 50;
+  if (!app.relatedListReader || app._relatedListReaderSDK !== app.sdk || (app._relatedListReaderLimit !== undefined && app._relatedListReaderLimit !== limit)) {
+    app.relatedListReader = createRelatedListReader(app.sdk, { maxLists: limit });
+    app._relatedListReaderSDK = app.sdk;
+    app._relatedListReaderLimit = limit;
+  }
+  record._related = await app.relatedListReader.read({ table, recordId: record.sys_id,
+    view: argv.view || 'Default view', profile: app.session?.profileName || argv.profile || '',
+    instance: app.getEffectiveInstance?.() || '' });
+  return record;
+}
+
+export function relatedListOptions(y) {
+  return y.option('related', { type: 'boolean', default: false, describe: 'Count related lists under Aggregate API access; suggest commands without loading supplementary records' })
+    .option('view', { type: 'string', describe: 'Form view for --related metadata (default: Default view)' })
+    .option('related-limit', { type: 'number', describe: 'Max related-list descriptors to count with --related (default 50)' });
+}