@jacebenson/jsn 4.3.13-dev.82.1 → 4.3.13-dev.84.1

package/src/commands/tickets.js

@@ -1,5 +1,6 @@
-import { formatRecordForDisplay, getStringField, buildQuerySuffix, resolveFieldsParam, buildRecordPayload } from '../helpers.js';
-import { resolveRecord, resolveSysId } from '../resolve-record.js';
+import { formatRecordForDisplay, getStringField, buildQuerySuffix, resolveFieldsParam, buildRecordPayload, confirmDelete } from '../helpers.js';
+import { getRecord, listRecords, recordListParams, createRecord, updateRecord, deleteRecord, recordOptions } from '../records-engine.js';
+import { resolveSysId } from '../resolve-record.js';
 import { declareCapabilities } from '../capabilities.js';
 
 declareCapabilities('tickets', { mutationSubcommands: ['create', 'update', 'delete'] });
@@ -15,23 +16,18 @@ export function ticketsCmd(wrap) {
           command: 'list',
           aliases: ['ls'],
           describe: 'List tickets',
-          builder: (y) => y
+          builder: (y) => recordOptions(y)
             .option('query', { type: 'string', describe: 'Encoded query (e.g. "active=true^priority=1")' })
             .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description,priority")' })
             .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' })
             .option('offset', { alias: 'o', type: 'number', default: 0, describe: 'Offset' }),
           handler: wrap(async (argv, app) => {
             const columns = argv.columns ? argv.columns.split(',') : ['number', 'short_description', 'state', 'assigned_to'];
-            const params = new URLSearchParams();
-            params.set('sysparm_limit', String(argv.limit));
-            params.set('sysparm_offset', String(argv.offset));
-            params.set('sysparm_display_value', 'all');
             const fields = resolveFieldsParam(columns);
-            if (fields) params.set('sysparm_fields', fields);
             const q = argv.query ? argv.query + '^ORDERBYDESCsys_updated_on' : 'ORDERBYDESCsys_updated_on';
-            params.set('sysparm_query', q);
-            const records = await app.sdk.list('task', params);
-            const displayRecords = fields ? records.map(r => formatRecordForDisplay(r, columns)) : records;
+            const params = recordListParams({ limit: argv.limit, offset: argv.offset, fields, query: q });
+            const records = await listRecords(app.sdk, { table: 'task', params, displayValues: argv.displayValues });
+            const displayRecords = fields && !argv.displayValues ? records.map(r => formatRecordForDisplay(r, columns)) : records;
             const breadcrumbs = [
               { action: 'create', cmd: 'jsn tickets create -f short_description=New ticket', description: 'Create a new ticket' },
             ];
@@ -63,46 +59,49 @@ export function ticketsCmd(wrap) {
           command: 'show <number>',
           aliases: ['get'],
           describe: 'Show a ticket',
+          builder: y => recordOptions(y),
           handler: wrap(async (argv, app) => {
-            const record = await resolveRecord(app.sdk, { table: 'task', identifier: argv.number, matchField: 'number', resource: 'Ticket' });
+            const record = await getRecord(app.sdk, { table: 'task', identifier: argv.number, identifierField: argv.identifierField, displayValues: argv.displayValues, matchField: 'number', resource: 'Ticket' });
             app.ok(record, { summary: `Ticket ${argv.number}` });
           }),
         })
         .command({
           command: 'create',
           describe: 'Create a new ticket',
-          builder: (y) => y
+          builder: (y) => recordOptions(y, false)
             .option('data', { type: 'string', describe: 'JSON fields' })
             .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
             .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
             .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
             const recordData = buildRecordPayload(argv);
-            const record = await app.sdk.create('task', recordData);
+            const record = await createRecord(app.sdk, { table: 'task', data: recordData });
             app.ok(record, { summary: `Created ticket ${getStringField(record, 'number')}` });
           }),
         })
         .command({
           command: 'update <number>',
           describe: 'Update a ticket',
-          builder: (y) => y
+          builder: (y) => recordOptions(y, false)
             .option('data', { type: 'string', describe: 'JSON fields' })
             .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
             .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
             .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
             const recordData = buildRecordPayload(argv);
-            const sysID = await resolveSysId(app.sdk, { table: 'task', identifier: argv.number, matchField: 'number', resource: 'Ticket' });
-            const updated = await app.sdk.update('task', sysID, recordData);
+            const sysID = await resolveSysId(app.sdk, { table: 'task', identifier: argv.number, identifierField: argv.identifierField, displayValues: argv.displayValues, matchField: 'number', resource: 'Ticket' });
+            const updated = await updateRecord(app.sdk, { table: 'task', record: { sys_id: sysID }, data: recordData });
             app.ok(updated, { summary: `Updated ticket ${argv.number}` });
           }),
         })
         .command({
           command: 'delete <number>',
           describe: 'Delete a ticket',
+          builder: y => recordOptions(y, false).option('force', { type: 'boolean', default: false, describe: 'Skip confirmation after approval' }),
           handler: wrap(async (argv, app) => {
-            const sysID = await resolveSysId(app.sdk, { table: 'task', identifier: argv.number, matchField: 'number', resource: 'Ticket' });
-            await app.sdk.delete('task', sysID);
+            await confirmDelete(app, argv, `Delete ticket ${argv.number}`);
+            const sysID = await resolveSysId(app.sdk, { table: 'task', identifier: argv.number, identifierField: argv.identifierField, displayValues: argv.displayValues, matchField: 'number', resource: 'Ticket' });
+            await deleteRecord(app.sdk, { table: 'task', record: { sys_id: sysID } });
             app.ok({ number: argv.number, message: 'Ticket deleted' }, { summary: `Deleted ticket ${argv.number}` });
           }),
         })

package/src/commands/uipolicies.js

@@ -1,28 +1,3 @@
-import { buildDevCmd } from './_generic.js';
-import { getStringField } from '../helpers.js';
+import { buildProfileCommand } from '../record-profiles.js';
 
-export const uipoliciesCmd = (wrap) => buildDevCmd('uipolicies', 'sys_ui_policy', ['uipolicy', 'up'],
-  ['short_description', 'table', 'sys_class_name', 'active'], wrap, {
-    singular: 'UI policy',
-    scopeValidation: true,
-    onShow: async (record, app) => {
-      const sysID = getStringField(record, 'sys_id') || '';
-      if (!sysID) return;
-      const mp = new URLSearchParams();
-      mp.set('sysparm_query', `ui_policy=${sysID}^ORDERBYorder`);
-      mp.set('sysparm_limit', '100'); mp.set('sysparm_display_value', 'all');
-      mp.set('sysparm_fields', 'name,table,field_name,read_only,mandatory,visible,sys_id');
-      const actions = await app.sdk.list('sys_ui_policy_action', mp);
-      if (actions.length > 0) {
-        console.log(`  Actions (${actions.length}):`);
-        for (const a of actions) {
-          const f = getStringField(a, 'field_name') || '(all fields)';
-          const flags = [];
-          if (getStringField(a, 'mandatory') === 'true') flags.push('mandatory');
-          if (getStringField(a, 'read_only') === 'true') flags.push('read-only');
-          if (getStringField(a, 'visible') === 'false') flags.push('hidden');
-          console.log(`    ${f}  ${flags.length ? `[${flags.join(', ')}]` : ''}`);
-        }
-      }
-    },
-  });
+export const uipoliciesCmd = wrap => buildProfileCommand('uipolicies', wrap);

package/src/errors.js

@@ -256,6 +256,13 @@ export function renderAppError(err, { app = null, argv = null, identifier = '' }
     return { stream: 'stderr', text, exitCode: 1 };
   }
 
+  if (err.resolution) {
+    if (resolveJsonMode(app, argv) && app) return { stream: 'stdout', text: null, exitCode: 1, appErr: true };
+    const lookup = err.resolution;
+    const text = `Error (${code}): ${err.message}\nLookup: ${lookup.mode} ${lookup.table}.${lookup.field}; ${lookup.at_least ? 'at least ' : ''}${lookup.matches} matches.\n${err.hint ? `\nHint: ${err.hint}\n` : ''}`;
+    return { stream: 'stderr', text, exitCode: 1 };
+  }
+
   if (code === CodeNotFound) {
     let text = `Error (${code}): ${err.message}\n`;
     if (identifier) {

package/src/essential-records.js

@@ -0,0 +1,40 @@
+// Essential relationships are a declarative opt-in of specialized profiles.
+// Supplementary metadata/counts live separately; this never fetches them.
+import { assertSafeExactMatch, quoteShellArg } from './helpers.js';
+import { listRecords, displayValue, recordListParams } from './records-engine.js';
+
+export async function enrichEssentialRecords(record, { sdk, relationships, displayValues = 'both', profileName, instance }) {
+  if (!relationships?.length) return record;
+  const id = typeof record.sys_id === 'object' ? record.sys_id?.value : record.sys_id;
+  const entries = await Promise.all(relationships.map(async relationship => {
+    const limit = relationship.limit ?? 100;
+    const query = `${relationship.foreignKey}=${id}`;
+    const result = { table: relationship.table, query, limit, records: [], loaded: 0,
+      coverage: 'visible_rows_only', visibility: 'Subject to field/row ACLs; empty results do not prove no related records.' };
+    try {
+      if (!id) throw new Error('No readable raw parent sys_id');
+      assertSafeExactMatch(id);
+      const ordered = query + (relationship.orderBy ? `^ORDERBY${relationship.orderBy}` : '');
+      const params = recordListParams({ limit: limit + 1, query: ordered,
+        fields: relationship.columns ? ['sys_id', ...relationship.columns] : undefined,
+        displayValue: displayValue(displayValues),
+      });
+      const rows = await listRecords(sdk, { table: relationship.table, params });
+      if (!Array.isArray(rows)) throw new Error('Invalid related record response');
+      result.records = rows.slice(0, limit);
+      result.loaded = result.records.length;
+      result.has_more = rows.length > limit;
+      result.status = 'loaded';
+      const selector = profileName ? ` --profile ${quoteShellArg(profileName)}` : instance ? ` --instance ${quoteShellArg(instance)}` : '';
+      result.command = `jsn${selector} records list --table ${quoteShellArg(relationship.table)} --query ${quoteShellArg(ordered)} --limit ${limit} --json`;
+    } catch (error) {
+      // Provider bodies can contain private data. Preserve uncertainty, not raw errors.
+      result.status = 'unavailable';
+      result.error = { code: error.code === 'forbidden' || error.status === 403 ? 'forbidden' : 'unavailable',
+        message: 'Essential related records could not be read. Check parent identity, table/field permissions and connection.' };
+    }
+    return [relationship.name, result];
+  }));
+  record._essential = Object.fromEntries(entries);
+  return record;
+}

package/src/output.js

@@ -160,6 +160,7 @@ 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) {
@@ -514,6 +515,20 @@ 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');
+      }
+    }
+
     // ── 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 } },
+  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,88 @@
+// 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;
+  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,147 @@
+// 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;
+}