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

package/package.json

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

package/src/commands/_generic.js

@@ -1,3 +1,4 @@
+import { enrichRelatedLists, relatedListOptions } from '../related-lists.js';
 // Generic table-based CRUD command builder
 
 import { formatRecordForDisplay, getStringField, buildRecordPayload, confirmDelete, interactiveList, canPrompt } from '../helpers.js';
@@ -182,7 +183,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
         aliases: ['get'],
         describe: `Show ${vowelArticle(singular)} ${singular} by name or sys_id`,
         builder: y => {
-          const command = recordOptions(y);
+          const command = relatedListOptions(recordOptions(y));
           return opts.relationships?.essential?.length ? command.option('essential', { type: 'boolean', default: true,
             describe: 'Fetch profile-declared essential children; --no-essential skips them. Supplementary lists remain lazy.' }) : command;
         },
@@ -204,6 +205,7 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
             await opts.onShow(record, app, argv);
           }
 
+          await enrichRelatedLists(record, { table, argv, app });
           const summary = typeof showSummary === 'function' ? showSummary(record, id) : showSummary;
           const breadcrumbs = typeof showBreadcrumbs === 'function' ? showBreadcrumbs(record, id) : showBreadcrumbs;
 

package/src/commands/_ticket.js

@@ -1,3 +1,4 @@
+import { enrichRelatedLists, relatedListOptions } from '../related-lists.js';
 // Generic command builder for CRUD operations on a ServiceNow table
 // Used by incidents, changes, requests, tasks, and most dev subcommands
 
@@ -127,13 +128,14 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
           aliases: ['get'],
           describe: `Show a specific ${displayName}`,
           builder: y => {
-            const command = recordOptions(y);
+            const command = relatedListOptions(recordOptions(y));
             return opts.relationships?.essential?.length ? command.option('essential', { type: 'boolean', default: true, describe: 'Fetch declared essential children; use --no-essential to skip' }) : command;
           },
           handler: wrap(async (argv, app) => {
             const number = argv.number;
             const record = await getRecord(app.sdk, { table, identifier: number, identifierField: argv.identifierField, displayValues: argv.displayValues ?? opts.referenceMode, matchField: opts.identifierField || 'number', resource: displayName });
             if (opts.onShow) await opts.onShow(record, app, argv);
+            await enrichRelatedLists(record, { table, argv, app });
             record._context = {
               instance_url: app.getEffectiveInstance(),
               table,

package/src/commands/requests.js

@@ -1,3 +1,4 @@
+import { enrichRelatedLists, relatedListOptions } from '../related-lists.js';
 import { getRecord, recordOptions } from '../records-engine.js';
 import { unwrapSysId } from '../resolve-record.js';
 import { buildProfileCommand } from '../record-profiles.js';
@@ -16,7 +17,7 @@ export function requestsCmd(wrap) {
       command: 'show <number>',
       aliases: ['get'],
       describe: 'Show a specific request with attachments and catalog variables',
-      builder: y => recordOptions(y),
+      builder: y => relatedListOptions(recordOptions(y)),
       handler: wrap(enrichedShowHandler),
     });
   };
@@ -42,6 +43,7 @@ async function enrichedShowHandler(argv, app) {
     table: 'sc_req_item',
   };
 
+  await enrichRelatedLists(record, { table: 'sc_req_item', argv, app });
   app.ok(record, {
     summary: `Request ${number}`,
     breadcrumbs: [

package/src/commands/tickets.js

@@ -1,3 +1,4 @@
+import { enrichRelatedLists, relatedListOptions } from '../related-lists.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';
@@ -59,9 +60,10 @@ export function ticketsCmd(wrap) {
           command: 'show <number>',
           aliases: ['get'],
           describe: 'Show a ticket',
-          builder: y => recordOptions(y),
+          builder: y => relatedListOptions(recordOptions(y)),
           handler: wrap(async (argv, app) => {
             const record = await getRecord(app.sdk, { table: 'task', identifier: argv.number, identifierField: argv.identifierField, displayValues: argv.displayValues, matchField: 'number', resource: 'Ticket' });
+            await enrichRelatedLists(record, { table: 'task', argv, app });
             app.ok(record, { summary: `Ticket ${argv.number}` });
           }),
         })

package/src/metadata/records.js

@@ -237,7 +237,11 @@ function buildRelationships({ entries, dictionary, relationships, sourceTable, n
     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),
+    const filter = entry.filter;
+    const filterAvailable = Boolean(Object.hasOwn(entry, 'filter') && (filter === null || typeof filter === 'string'
+      || (filter && typeof filter === 'object' && Object.hasOwn(filter, 'value') && (filter.value === null || typeof filter.value === 'string'))));
+    if (!filterAvailable) warnings.push({ source: 'sys_ui_related_list_entry', reason: 'A configured filter is absent or not visible; do not assume an unfiltered list' });
+    result.set(id, { ...descriptor, configured: true, filter_available: filterAvailable, 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 });
   }

package/src/output.js

@@ -529,6 +529,17 @@ export class OutputWriter {
       }
     }
 
+    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/related-lists.js

@@ -145,3 +145,9 @@ export async function enrichRelatedLists(record, { table, argv = {}, app }) {
     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)' });
+}