@jacebenson/jsn 4.3.13-dev.81.1 → 4.3.13-dev.83.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.13-dev.81.1",
+  "version": "4.3.13-dev.83.1",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {

package/src/commands/forms.js

@@ -1,105 +1,29 @@
 import { getStringField, interactiveList } from '../helpers.js';
 
-function getDisplayValue(record, key) {
-  if (!record || typeof record !== 'object') return '';
-  const val = record[key];
-  if (val == null) return '';
-  if (typeof val === 'string') return val;
-  if (typeof val === 'object') {
-    if (val.display_value != null && val.display_value !== '') return String(val.display_value);
-    if (val.value != null) return String(val.value);
-  }
-  return String(val);
-}
-
-function getIntValue(record, key) {
-  if (!record || typeof record !== 'object') return 0;
-  const val = record[key];
-  if (val == null) return 0;
-  if (typeof val === 'number') return Math.floor(val);
-  if (typeof val === 'string') { const n = parseInt(val, 10); return isNaN(n) ? 0 : n; }
-  if (typeof val === 'object' && val.value != null) { const n = parseInt(val.value, 10); return isNaN(n) ? 0 : n; }
-  return 0;
-}
-
-async function showForm(app, table, viewName) {
-  // 1) Look up the view
-  const viewParams = new URLSearchParams();
-  viewParams.set('sysparm_limit', '1');
-  viewParams.set('sysparm_fields', 'sys_id');
-  viewParams.set('sysparm_display_value', 'all');
-  viewParams.set('sysparm_query', `name=${viewName}`);
-  let viewSysID = '';
-  try { const vr = await app.sdk.list('sys_ui_view', viewParams); if (vr.length > 0) viewSysID = getStringField(vr[0], 'sys_id'); } catch { /* ignore */ }
-  if (!viewSysID) {
-    viewParams.set('sysparm_query', `title=${viewName}`);
-    try { const vr = await app.sdk.list('sys_ui_view', viewParams); if (vr.length > 0) viewSysID = getStringField(vr[0], 'sys_id'); } catch { /* ignore */ }
-  }
-
-  // 2) Get sections for this table + view
-  const secParams = new URLSearchParams();
-  secParams.set('sysparm_limit', '200');
-  secParams.set('sysparm_fields', 'sys_id,caption');
-  secParams.set('sysparm_display_value', 'all');
-  secParams.set('sysparm_query', `name=${table}^view=${viewName}^ORDERBYposition`);
-  if (viewSysID) {
-    secParams.set('sysparm_query', `name=${table}^view=${viewSysID}^ORDERBYposition`);
-  }
-  const sections = await app.sdk.list('sys_ui_section', secParams);
-
-  // 3) Get elements for each section
-  const sectionsOut = [];
-  for (const sec of sections) {
-    const secSysID = getStringField(sec, 'sys_id');
-    const sectionCaption = getDisplayValue(sec, 'caption') || '(unnamed)';
+import { createRecordMetadataReader } from '../metadata/records.js';
 
-    let elements = [];
-    if (secSysID) {
-      const elemParams = new URLSearchParams();
-      elemParams.set('sysparm_limit', '500');
-      elemParams.set('sysparm_fields', 'element,type,label,position');
-      elemParams.set('sysparm_display_value', 'all');
-      elemParams.set('sysparm_query', `sys_ui_section=${secSysID}^ORDERBYposition`);
-      try { elements = await app.sdk.list('sys_ui_element', elemParams); } catch { /* ignore */ }
-    }
-
-    sectionsOut.push({
-      caption: sectionCaption,
-      position: getIntValue(sec, 'position'),
-      elements: elements
-        .map(e => ({
-          type: getDisplayValue(e, 'type'),
-          label: getDisplayValue(e, 'label'),
-          element: getDisplayValue(e, 'element'),
-          position: getIntValue(e, 'position'),
-        }))
-        .sort((a, b) => a.position - b.position),
-    });
+export function formatFormMetadata(metadata) {
+  const lines = [`Form: ${metadata.table} → ${metadata.requested_view}`];
+  if (metadata.form?.inherited) lines.push(`  Inherited layout: ${metadata.form.table}`);
+  if (!metadata.form) lines.push('  No unambiguous shared form layout is visible.');
+  for (const section of metadata.form?.sections || []) {
+    lines.push('', `── ${section.caption || '(unnamed)'} ──`);
+    for (const element of section.elements) lines.push(`  ${element.label || element.element || '(unnamed)'}${element.type ? ` (${element.type})` : ''}`);
+    if (!section.elements.length) lines.push('  (no visible elements)');
   }
-
-  sectionsOut.sort((a, b) => a.position - b.position);
-
-  // Build formatted output
-  const lines = [];
-  lines.push(`Form: ${table} → ${viewName}`);
-  if (viewSysID) lines.push(`  View: ${app.getEffectiveInstance()}/nav_to.do?uri=sys_ui_view.do?sys_id=${viewSysID}`);
-  lines.push('');
-
-  for (const sec of sectionsOut) {
-    const secLabel = sec.caption || '(unnamed)';
-    lines.push(`── ${secLabel} ──`);
-    if (sec.elements.length === 0) {
-      lines.push('  (no elements)');
-    }
-    for (const el of sec.elements) {
-      const elLabel = el.label || el.element || '(unnamed)';
-      const typeStr = el.type ? ` (${el.type})` : '';
-      lines.push(`  ${elLabel}${typeStr}`);
-    }
-    lines.push('');
+  const configured = metadata.related_lists.filter(item => item.configured);
+  if (configured.length) {
+    lines.push('', 'Configured related lists:');
+    for (const list of configured) lines.push(`  ${list.label || list.id} (${list.query_status})`);
   }
+  lines.push('', metadata.coverage.scope);
+  for (const warning of metadata.coverage.warnings) lines.push(`  ${warning.source}: ${warning.reason}`);
+  return lines.join('\n');
+}
 
-  process.stdout.write(lines.join('\n') + '\n');
+async function showForm(app, table, view) {
+  const metadata = await createRecordMetadataReader(app.sdk).read({ table, view });
+  app.ok({ ...metadata, _formatted: formatFormMetadata(metadata) }, { summary: `Form metadata for ${table}` });
 }
 
 export function formsCmd(wrap) {
@@ -164,7 +88,8 @@ export function formsCmd(wrap) {
           aliases: ['get'],
           describe: 'Show form layout',
           builder: (y) => y
-            .option('view', { type: 'string', default: 'Default view', describe: 'View name' }),
+            .option('view', { type: 'string', default: 'Default view', describe: 'Shared view name, title or sys_id' })
+            .epilogue('Discovers shared layouts, inherited forms and related-list metadata. JSON includes coverage limits; custom relationship scripts are never executed. Generic records get presentation is unchanged.'),
           handler: wrap(async (argv, app) => {
             app.requireInstance();
             await showForm(app, argv.table, argv.view);

package/src/metadata/records.js

@@ -0,0 +1,245 @@
+import { assertSafeExactMatch } from '../helpers.js';
+import { errUsage, errAuth } from '../errors.js';
+
+const namePattern = /^[a-zA-Z0-9_]+$/;
+const raw = value => String(value && typeof value === 'object' ? value.value ?? '' : value ?? '');
+const field = (record, name) => raw(record?.[name]);
+const position = row => Number(field(row, 'position')) || 0;
+const ordered = rows => [...rows].sort((a, b) => position(a) - position(b));
+const reference = value => {
+  const text = raw(value);
+  assertSafeExactMatch(text);
+  return text;
+};
+const isName = value => typeof value === 'string' && namePattern.test(value);
+const chunks = values => Array.from({ length: Math.ceil(values.length / 100) }, (_, index) => values.slice(index * 100, (index + 1) * 100));
+
+function request(table, query, fields, limit = 1000) {
+  return { table, params: new URLSearchParams({
+    sysparm_query: query, sysparm_fields: fields, sysparm_limit: String(limit),
+    sysparm_display_value: 'all', sysparm_exclude_reference_link: 'true',
+  }) };
+}
+
+/** Invocation-scoped, SDK-bound metadata reader. No persistence across users. */
+export function createRecordMetadataReader(sdk, { limit = 1000, maxDepth = 32 } = {}) {
+  if (!Number.isInteger(limit) || limit < 1 || limit > 10000) throw errUsage('Metadata limit must be an integer from 1 to 10000');
+  if (!Number.isInteger(maxDepth) || maxDepth < 1 || maxDepth > 100) throw errUsage('Metadata inheritance depth must be an integer from 1 to 100');
+  const cache = new Map();
+  const reports = new Map();
+
+  async function reads(specs, warnings) {
+    const missing = specs.filter(spec => !cache.has(`${spec.table}?${spec.params}`));
+    // Reserve promises before transport so concurrent metadata requests share
+    // both successful reads and observed failures within this reader only.
+    const unique = [...new Map(missing.map(spec => [`${spec.table}?${spec.params}`, spec])).values()];
+    if (unique.length) {
+      const pending = (async () => {
+        if (unique.length > 1 && typeof sdk.batch === 'function') {
+          try {
+            const batch = await sdk.batch(unique.map((spec, index) => ({
+              id: `metadata-${index}`, method: 'GET', url: `/api/now/table/${spec.table}?${spec.params}`,
+            })), { fallback: true });
+            return unique.map((spec, index) => {
+              const item = batch.results?.find(result => result.id === `metadata-${index}`);
+              if (item?.status === 401) throw errAuth('Authentication failed while reading metadata');
+              if (!item?.ok) return { rows: [], error: item?.error?.message || `Metadata read failed (${item?.status || 'unknown status'})` };
+              return normalize(item.data?.result, spec);
+            });
+          } catch (error) {
+            if (error.code === 'auth_error' || error.status === 401) throw error;
+            // The batch provider owns unsupported-endpoint fallback. Never
+            // replay authentication/ACL/server failures through another path.
+            return unique.map(() => ({ rows: [], error: error.message || 'Metadata batch failed' }));
+          }
+        }
+        return Promise.all(unique.map(async spec => {
+          try { return normalize(await sdk.list(spec.table, spec.params), spec); }
+          catch (error) {
+            if (error.code === 'auth_error' || error.status === 401) throw error;
+            return { rows: [], error: error.message || 'Metadata read failed' };
+          }
+        }));
+      })();
+      unique.forEach((spec, index) => cache.set(`${spec.table}?${spec.params}`, pending.then(results => results[index])));
+    }
+    return Promise.all(specs.map(async spec => {
+      const result = await cache.get(`${spec.table}?${spec.params}`);
+      if (result.error) warnings.push({ source: spec.table, reason: result.error });
+      if (result.truncated) warnings.push({ source: spec.table, reason: `Metadata limit ${spec.params.get('sysparm_limit')} reached; results may be incomplete` });
+      return result.rows;
+    }));
+  }
+
+  function normalize(rows, spec) {
+    if (!Array.isArray(rows)) return { rows: [], error: 'Metadata response was not an array' };
+    return { rows, truncated: rows.length >= Number(spec.params.get('sysparm_limit')) };
+  }
+
+  async function read({ table, view = 'Default view' }) {
+    if (!isName(table)) throw errUsage('Metadata table must be a table name containing letters, numbers or underscores');
+    if (typeof view !== 'string' || !view) throw errUsage('Metadata view must be a nonempty name, title or sys_id');
+    assertSafeExactMatch(view);
+    const key = `${table}\0${view}`;
+    if (!reports.has(key)) reports.set(key, load(table, view));
+    // Protect cached objects from a consumer attaching record-specific hints.
+    return structuredClone(await reports.get(key));
+  }
+
+  async function load(table, view) {
+    const warnings = [];
+    const hierarchy = [];
+    const visited = new Set();
+    let next = request('sys_db_object', `name=${table}`, 'sys_id,name,super_class', 2);
+    for (let depth = 0; next && depth < maxDepth; depth++) {
+      const [rows] = await reads([next], warnings);
+      if (rows.length !== 1) {
+        warnings.push({ source: 'sys_db_object', reason: `Expected one visible table definition, found ${rows.length}; inheritance coverage is incomplete` });
+        break;
+      }
+      const row = rows[0];
+      const name = field(row, 'name');
+      const id = field(row, 'sys_id');
+      if (!isName(name) || visited.has(name)) {
+        warnings.push({ source: 'sys_db_object', reason: 'Invalid or cyclic table inheritance metadata' });
+        break;
+      }
+      visited.add(name);
+      hierarchy.push({ name, sys_id: id });
+      if (!Object.hasOwn(row, 'super_class')) warnings.push({ source: 'sys_db_object', reason: 'Parent metadata is not visible; inheritance coverage is incomplete' });
+      const parent = reference(row.super_class);
+      next = parent ? request('sys_db_object', `sys_id=${parent}`, 'sys_id,name,super_class', 2) : null;
+    }
+    if (next && hierarchy.length === maxDepth) warnings.push({ source: 'sys_db_object', reason: `Inheritance depth limit ${maxDepth} reached` });
+    if (!hierarchy.length) hierarchy.push({ name: table, sys_id: '' });
+    const names = hierarchy.map(item => item.name);
+    const defaultView = view === 'Default view' || view === 'default';
+    const viewQuery = defaultView ? 'name=^ORname=default^ORtitle=Default view' : `name=${view}^ORtitle=${view}^ORsys_id=${view}`;
+    const [views] = await reads([request('sys_ui_view', `${viewQuery}^userISEMPTY`, 'sys_id,name,title', limit)], warnings);
+    const byId = views.filter(row => field(row, 'sys_id') === view);
+    const byName = views.filter(row => field(row, 'name') === (defaultView ? '' : view));
+    const byTitle = views.filter(row => field(row, 'title') === view);
+    const byAlias = defaultView ? views.filter(row => field(row, 'name') === 'default') : [];
+    const candidates = byId.length ? byId : byName.length ? byName : byTitle.length ? byTitle : byAlias;
+    let viewId = '';
+    const viewCapped = views.length >= limit;
+    if (candidates.length === 1 && !viewCapped) {
+      viewId = reference(candidates[0].sys_id);
+      if (!viewId) warnings.push({ source: 'sys_ui_view', reason: 'View id is absent or not visible' });
+    } else if (candidates.length > 1 || viewCapped) warnings.push({ source: 'sys_ui_view', reason: 'View lookup is ambiguous or capped; no layout was selected' });
+    else if (!defaultView) warnings.push({ source: 'sys_ui_view', reason: 'Requested view is absent or not visible; no layout was selected' });
+    const canReadLayout = !viewCapped && candidates.length <= 1 && (defaultView || !!viewId);
+    const viewFilter = viewId ? `view=${viewId}${defaultView ? '^ORviewISEMPTY' : ''}` : 'viewISEMPTY';
+    const specs = [
+      request('sys_dictionary', `referenceIN${names.join(',')}^elementISNOTEMPTY`, 'sys_id,name,element,reference,column_label', limit),
+      request('sys_relationship', `basic_apply_toIN${names.join(',')}`, 'sys_id,name,basic_apply_to,basic_query_from,reference_field,simple_reference,advanced,query_with', limit),
+      ...(canReadLayout ? [
+        request('sys_ui_form', `nameIN${names.join(',')}^${viewFilter}^sys_userISEMPTY`, 'sys_id,name,view', limit),
+        request('sys_ui_related_list', `nameIN${names.join(',')}^${viewFilter}^sys_userISEMPTY`, 'sys_id,name,view', limit),
+      ] : []),
+    ];
+    const [dictionary, relationships, forms = [], containers = []] = await reads(specs, warnings);
+    const nearest = rows => {
+      for (const name of names) {
+        const candidates = rows.filter(row => field(row, 'name') === name);
+        const exact = viewId ? candidates.filter(row => field(row, 'view') === viewId) : [];
+        const preferred = exact.length ? exact : candidates;
+        if (preferred.length > 1) warnings.push({ source: 'layout', reason: `Ambiguous layout for ${name}; no layout was selected` });
+        if (preferred.length) {
+          if (!field(preferred[0], 'sys_id')) {
+            warnings.push({ source: 'layout', reason: `Layout id is absent or not visible for ${name}` });
+            return null;
+          }
+          return preferred.length === 1 ? preferred[0] : null;
+        }
+      }
+      return null;
+    };
+    const form = nearest(forms);
+    const container = nearest(containers);
+    const detailSpecs = [
+      ...(form ? [request('sys_ui_form_section', `sys_ui_form=${reference(form.sys_id)}^ORDERBYposition`, 'sys_id,sys_ui_form,sys_ui_section,position', limit)] : []),
+      ...(container ? [request('sys_ui_related_list_entry', `list_id=${reference(container.sys_id)}^ORDERBYposition`, 'sys_id,related_list,position,filter,order_by', limit)] : []),
+    ];
+    const details = await reads(detailSpecs, warnings);
+    const links = form ? details.shift() : [];
+    const entries = container ? details.shift() : [];
+    const sectionIds = [...new Set(links.map(link => reference(link.sys_ui_section)).filter(Boolean))];
+    const relationshipIds = entries.map(entry => field(entry, 'related_list')).filter(value => /^REL:[a-f0-9]{32}$/i.test(value)).map(value => value.slice(4));
+    const missingRelationships = relationshipIds.filter(id => !relationships.some(row => field(row, 'sys_id') === id));
+    const tailSpecs = [
+      ...chunks(sectionIds).flatMap(ids => [
+        { ...request('sys_ui_section', `sys_idIN${ids.join(',')}^sys_userISEMPTY`, 'sys_id,name,caption,header,title,view', limit), group: 'sections' },
+        { ...request('sys_ui_element', `sys_ui_sectionIN${ids.join(',')}^sys_userISEMPTY^ORDERBYposition`, 'sys_id,sys_ui_section,element,type,position', limit), group: 'elements' },
+      ]),
+      ...chunks([...new Set(missingRelationships)]).map(ids => ({
+        ...request('sys_relationship', `sys_idIN${ids.join(',')}`, 'sys_id,name,basic_apply_to,basic_query_from,reference_field,simple_reference,advanced,query_with', limit), group: 'relationships',
+      })),
+    ];
+    const tail = await reads(tailSpecs, warnings);
+    const group = name => tail.flatMap((rows, index) => tailSpecs[index].group === name ? rows : []);
+    const sections = group('sections');
+    const elements = group('elements');
+    relationships.push(...group('relationships'));
+    const sectionsOut = ordered(links).map(link => {
+      const id = field(link, 'sys_ui_section');
+      const section = sections.find(row => field(row, 'sys_id') === id);
+      if (!section) warnings.push({ source: 'sys_ui_section', reason: `A linked section is absent or not visible` });
+      return { sys_id: id, caption: field(section, 'caption'), position: position(link),
+        elements: ordered(elements.filter(row => field(row, 'sys_ui_section') === id)).map(row => ({
+          element: field(row, 'element'), type: field(row, 'type'), label: field(row, 'label'), position: position(row),
+        })) };
+    });
+    const relatedLists = buildRelationships({ entries, dictionary, relationships, sourceTable: container ? field(container, 'name') : '', names, warnings });
+    return {
+      table, requested_view: view, view_sys_id: viewId, hierarchy,
+      form: form ? { sys_id: field(form, 'sys_id'), table: field(form, 'name'), inherited: field(form, 'name') !== table, sections: sectionsOut } : null,
+      related_lists: relatedLists,
+      coverage: { state: warnings.length ? 'partial' : 'observed', scope: 'Visible shared layout metadata only; ACLs, personalization and advanced relationships may hide or change runtime results', warnings },
+    };
+  }
+
+  return { read, clear() { cache.clear(); reports.clear(); } };
+}
+
+function buildRelationships({ entries, dictionary, relationships, sourceTable, names, warnings }) {
+  const result = new Map();
+  for (const row of dictionary) {
+    const table = field(row, 'name');
+    const referenceField = field(row, 'element');
+    if (!isName(table) || !isName(referenceField)) {
+      warnings.push({ source: 'sys_dictionary', reason: 'Ignored an invalid reference definition' });
+      continue;
+    }
+    if (!names.includes(field(row, 'reference'))) warnings.push({ source: 'sys_dictionary', reason: 'A reference target is absent, unrelated, or not visible' });
+    const id = `${table}.${referenceField}`;
+    result.set(id, { id, kind: 'reference', table, reference_field: referenceField,
+      references: field(row, 'reference'), label: field(row, 'column_label'), configured: false,
+      query_status: names.includes(field(row, 'reference')) ? 'reference' : 'unavailable' });
+  }
+  for (const row of relationships) {
+    const id = `REL:${field(row, 'sys_id')}`;
+    if (!/^REL:[a-f0-9]{32}$/i.test(id)) continue;
+    const table = field(row, 'basic_query_from');
+    const referenceField = field(row, 'reference_field');
+    const queryable = field(row, 'advanced') !== 'true' && field(row, 'advanced') !== '1'
+      && names.includes(field(row, 'basic_apply_to'))
+      && ['true', '1'].includes(field(row, 'simple_reference')) && !field(row, 'query_with').trim()
+      && isName(table) && isName(referenceField);
+    result.set(id, { id, kind: 'relationship', relationship_sys_id: field(row, 'sys_id'),
+      table: isName(table) ? table : '', reference_field: queryable ? referenceField : '',
+      label: field(row, 'name'), configured: false, query_status: queryable ? 'reference' : 'platform_required',
+      ...(queryable ? {} : { reason: 'Custom/advanced relationship requires platform query logic; scripts are never executed by metadata discovery' }),
+    });
+  }
+  for (const entry of ordered(entries)) {
+    const id = field(entry, 'related_list');
+    const existing = result.get(id);
+    const descriptor = existing || { id, kind: 'unresolved', table: '', reference_field: '', query_status: 'unavailable',
+      reason: 'Configured related list metadata is absent, unsupported, or not visible' };
+    result.set(id, { ...descriptor, configured: true, source_table: sourceTable, position: position(entry),
+      filter: field(entry, 'filter'), order_by: field(entry, 'order_by') });
+    if (!existing) warnings.push({ source: 'sys_ui_related_list_entry', reason: descriptor.reason });
+  }
+  return [...result.values()].sort((a, b) => Number(b.configured) - Number(a.configured) || (a.position || 0) - (b.position || 0));
+}

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;
+}