@jacebenson/jsn 4.3.12 → 4.3.13-dev.101.1

package/src/commands/updatesets.js

@@ -1,16 +1,20 @@
 import fs from 'node:fs';
+import path from 'node:path';
+import { inspectUpdateSetXML, updateSetFilename, MAX_UPDATE_SET_BYTES } from '../update-set-xml.js';
 import { editor, confirm } from '../prompts.js';
-import { formatRecordForDisplay, getStringField, interactiveList, assertSafeExactMatch, canPrompt, buildRerunCommand, verifyWriteBack } from '../helpers.js';
+import { formatRecordForDisplay, getStringField, interactiveList, assertSafeExactMatch, canPrompt, buildRerunCommand, verifyWriteBack, quoteShellArg } from '../helpers.js';
 import { getActiveProfile } from '../config.js';
 import { FormatAuto } from '../output.js';
 import { getCurrentApplication, getCurrentUpdateSet, requireCurrentUserSysId, setCurrentApplication, setCurrentUpdateSet } from '../context.js';
-import { errAPI, errUsage, errConfirmationRequired } from '../errors.js';
+import { AppError, CodeConfirmationRequired, errAPI, errUsage, errConfirmationRequired } from '../errors.js';
 import { declareCapabilities } from '../capabilities.js';
 import { resolveScope } from './scopes.js';
 import { unwrapSysId } from '../resolve-record.js';
 
 declareCapabilities('updatesets', {
-  mutationSubcommands: ['create', 'set', 'complete', 'ignore', 'parent'],
+  mutationSubcommands: ['create', 'set', 'complete', 'ignore', 'parent', 'import', 'reopen'],
+  mutationContextExemptSubcommands: ['create', 'set', 'import', 'reopen'],
+  localPreviewSubcommands: ['import'],
 });
 
 /**
@@ -27,7 +31,7 @@ export function scopeMismatchWarning(updateSetApp, currentApp) {
   const updateSetAppId = updateSetApp?.value || (typeof updateSetApp === 'string' ? updateSetApp : '');
   if (!updateSetAppId || !currentApp.appSysId || updateSetAppId === currentApp.appSysId) return '';
   const name = updateSetApp?.display_value || updateSetApp;
-  return ` ⚠️ update set is in app "${name}", but current app is "${currentApp.scope}" — changes won't land here. Run: jsn scopes set ${name}`;
+  return ` ⚠️ update set is in app "${name}", but current app is "${currentApp.scope}" — changes may not be captured in this set. Run: jsn scopes set ${quoteShellArg(updateSetAppId)}`;
 }
 
 /** Format a picker label for an update set: "Name [State] (app/scope)". */
@@ -361,6 +365,7 @@ export async function formatUpdateSetDetail(app, record) {
   const stateRaw = String(full.state?.value ?? full.state ?? '').toLowerCase();
   const isClosed = ['complete', 'committed'].includes(stateRaw);
   const hints = [];
+  hints.push({ action: 'scan', cmd: `jsn scan run --update-set ${sysID}${app.session?.profileName ? ` --profile ${quoteShellArg(app.session.profileName)}` : ''}`, description: 'Offer an explicit scan of current records before completing or promoting this set' });
   if (isClosed) {
     hints.push({
       action: 'set',
@@ -381,7 +386,7 @@ export async function formatUpdateSetDetail(app, record) {
   });
   hints.push({
     action: 'export',
-    cmd: `jsn updatesets export "${name}" --out ${name.replace(/[^a-z0-9]+/gi, '-').toLowerCase()}.xml`,
+    cmd: `jsn updatesets export "${name}" --out ${quoteShellArg(updateSetFilename(name))}`,
     description: 'Export this update set to XML',
   });
   if (!isClosed) {
@@ -424,7 +429,7 @@ export function updateSetsCmd(wrap) {
   return {
     command: 'updatesets [subcommand]',
     aliases: ['updateset', 'us'],
-    describe: 'Manage update sets',
+    describe: 'Manage update sets. Global + Default mutations require approval (--force only after user approval); create/set remain available to select a dedicated capture set. Scope mismatches warn; completed capture sets block writes.',
     builder: (yargs) => {
       return yargs
         .command({
@@ -477,11 +482,14 @@ export function updateSetsCmd(wrap) {
         })
         .command({
           command: 'export <name>',
-          describe: 'Export an update set to XML (raw XML to stdout, or --out file)',
+          describe: 'Export XML without changing state; auto-name a file in a terminal, preserve piped stdout',
           builder: (y) => y
             .positional('name', { describe: 'Update set name', type: 'string' })
-            .option('out', { alias: 'o', type: 'string', describe: 'Write XML to this file instead of stdout' }),
+            .option('out', { alias: 'o', type: 'string', describe: 'Write XML to this file instead of stdout' })
+            .option('out-dir', { type: 'string', describe: 'Write an automatically named XML file in this directory' })
+            .option('stdout', { type: 'boolean', describe: 'Write raw XML to stdout, including in a terminal' }),
           handler: wrap(async (argv, app) => {
+            if ([Boolean(argv.out), Boolean(argv.outDir), Boolean(argv.stdout)].filter(Boolean).length > 1) throw errUsage('Choose one of --out, --out-dir, or --stdout');
             app.requireInstance();
             const record = await resolveUpdateSetByName(app, argv.name);
             const sysID = getStringField(record, 'sys_id');
@@ -503,14 +511,16 @@ export function updateSetsCmd(wrap) {
             }
 
             const bytes = Buffer.byteLength(xml, 'utf-8');
-            if (argv.out) {
-              await fs.promises.writeFile(argv.out, xml);
+            const out = argv.out || (argv.outDir || (process.stdout.isTTY && !argv.stdout && !argv.json && argv.format !== 'json')
+              ? path.join(argv.outDir || '.', updateSetFilename(getStringField(record, 'name'))) : null);
+            if (out) {
+              await fs.promises.writeFile(out, xml, { flag: 'wx' });
               app.ok({
                 update_set: getStringField(record, 'name'),
                 sys_id: sysID,
-                out: argv.out,
+                out,
                 bytes,
-              }, { summary: `Exported update set "${getStringField(record, 'name')}" (${bytes} bytes) to ${argv.out}` });
+              }, { summary: `Exported update set "${getStringField(record, 'name')}" (${bytes} bytes) to ${out}` });
               return;
             }
 
@@ -518,7 +528,7 @@ export function updateSetsCmd(wrap) {
             // (`jsn updatesets export "X" > set.xml`). Only wrap in the JSON
             // envelope when the user explicitly asks for it — auto format
             // detection must NOT hijack the payload for piped consumers.
-            if (argv.json || argv.format === 'json') {
+            if (!argv.stdout && (argv.json || argv.format === 'json')) {
               app.ok({
                 update_set: getStringField(record, 'name'),
                 sys_id: sysID,
@@ -530,6 +540,47 @@ export function updateSetsCmd(wrap) {
             process.stdout.write(xml + (xml.endsWith('\n') ? '' : '\n'));
           }),
         })
+        .command({
+          command: 'import <file>',
+          describe: 'Load XML as a retrieved update set; never preview, commit, or select it automatically',
+          builder: y => y
+            .positional('file', { type: 'string', describe: 'Update set XML export' })
+            .option('dry-run', { type: 'boolean', describe: 'Inspect locally without any instance requests' })
+            .option('yes', { type: 'boolean', describe: 'Confirm loading the displayed XML into the selected target' }),
+          handler: wrap(async (argv, app) => {
+            const stat = await fs.promises.stat(argv.file);
+            if (!stat.isFile() || stat.size > MAX_UPDATE_SET_BYTES) throw errUsage('Expected an XML file no larger than 50 MiB');
+            const xml = await fs.promises.readFile(argv.file, 'utf8');
+            const inspection = inspectUpdateSetXML(xml);
+            const { members, ...summary } = inspection;
+            if (argv.dryRun) return app.ok({ ...summary, members, dry_run: true }, { summary: `XML: ${inspection.name}; ${inspection.count} updates (local inspection only)` });
+            app.requireInstance();
+            const question = `Load "${inspection.name}" (${inspection.count} updates) into ${app.getEffectiveInstance()} as a retrieved update set? This does not commit its changes.`;
+            if (!argv.yes) {
+              if (!canPrompt() || argv.json || argv.get || (argv.format && argv.format !== FormatAuto)) {
+                throw new AppError(CodeConfirmationRequired, `${question} — confirmation required. Pass --yes after approving this target.`,
+                  `Rerun: ${buildRerunCommand(argv, { rerun: ['updatesets', 'import', argv.file, '--yes'] })}`);
+              }
+              if (!await confirm({ message: question, default: false })) return;
+            }
+            const result = await app.sdk.importUpdateSet(xml, inspection, path.basename(argv.file));
+            app.ok({ ...summary, ...result, committed: false }, { summary: `Loaded retrieved update set "${inspection.name}" (${result.count} updates); not committed` });
+          }),
+        })
+        .command({
+          command: 'reopen <name>',
+          describe: 'Explicitly return a complete or ignored local update set to in progress; does not select it',
+          handler: wrap(async (argv, app) => {
+            const target = await resolveCompletionTarget(app, argv.name);
+            const record = await fetchUpdateSetById(app, target.sys_id);
+            const state = String(record?.state?.value ?? record?.state ?? '').toLowerCase();
+            if (!['complete', 'ignore'].includes(state)) throw errUsage(`Cannot reopen an update set in state "${state}"; expected complete or ignore`);
+            await app.sdk.update('sys_update_set', target.sys_id, { state: 'in progress' });
+            const mismatches = await verifyWriteBack(app, 'sys_update_set', target.sys_id, { state: 'in progress' });
+            if (mismatches.length) throw errAPI(200, 'Reopen could not be verified; inspect the update set before retrying');
+            app.ok({ update_set: target.name, sys_id: target.sys_id, state: 'in progress' }, { summary: `Reopened update set: ${target.name}` });
+          }),
+        })
         .command({
           command: 'set [name]',
           describe: 'Set the current update set (interactive picker with scope when run bare)',
@@ -737,6 +788,8 @@ export function updateSetsCmd(wrap) {
         console.log('  list           List update sets (shows scope)');
         console.log('  show <name>    Show an update set (type counts + risky items)');
         console.log('  export <name>  Export an update set to XML (stdout or --out)');
+        console.log('  import <file>  Load retrieved XML (--dry-run inspects locally; --yes confirms)');
+        console.log('  reopen <name>  Explicitly return a closed set to in progress');
         console.log('  set  [name]    Set the current update set (picker when run bare)');
         console.log('  create         Create a new update set (auto-sets as current)');
         console.log('  complete [name] Complete a named or current set with --notes (editor when omitted)');

package/src/commands/users.js

@@ -1,4 +1,4 @@
-import { formatRecordForDisplay, getStringField, interactiveList, resolveFieldsParam } from '../helpers.js';
+import { formatRecordForDisplay, getStringField, interactiveList, resolveFieldsParam, buildRecordPayload } from '../helpers.js';
 import { resolveRecord, resolveSysId } from '../resolve-record.js';
 import { declareCapabilities } from '../capabilities.js';
 
@@ -72,12 +72,12 @@ export function usersCmd(wrap) {
             .option('username', { alias: 'u', type: 'string', describe: 'Username (e.g. john.doe)' })
             .option('name', { alias: 'n', type: 'string', describe: 'Full name (e.g. John Doe)' })
             .option('email', { alias: 'e', type: 'string', describe: 'Email address' })
-            .option('data', { type: 'string', describe: 'JSON data for additional fields' }),
+            .option('data', { type: 'string', describe: 'JSON data for additional 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 = {};
-            if (argv.data) {
-              Object.assign(recordData, JSON.parse(argv.data));
-            }
+            const recordData = buildRecordPayload(argv, { required: false });
             if (argv.username) recordData.user_name = argv.username;
             if (argv.name) recordData.name = argv.name;
             if (argv.email) recordData.email = argv.email;
@@ -97,10 +97,13 @@ export function usersCmd(wrap) {
           command: 'update <identifier>',
           describe: 'Update a user by user_name or sys_id',
           builder: (y) => y
-            .option('data', { type: 'string', demandOption: true, describe: 'JSON data to update' }),
+            .option('data', { type: 'string', describe: 'JSON data to update' })
+            .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 id = argv.identifier;
-            const recordData = JSON.parse(argv.data);
+            const recordData = buildRecordPayload(argv);
             const sysID = await resolveSysId(app.sdk, { table: 'sys_user', identifier: id, matchField: 'user_name', resource: 'User' });
             const updated = await app.sdk.update('sys_user', sysID, recordData);
             app.ok(updated, {

package/src/commands/version.js

@@ -6,7 +6,13 @@ import { declareCapabilities } from '../capabilities.js';
 declareCapabilities('version', { noInstance: true, skipDailyChecks: true });
 
 const NPM_PKG = '@jacebenson/jsn';
-const NPM_REGISTRY = `https://registry.npmjs.org/${NPM_PKG}/latest`;
+export function getReleaseChannel(version = getVersion()) {
+  return /^\d+\.\d+\.\d+-dev\./.test(version) ? 'dev' : 'latest';
+}
+
+export function getInstallCommand(version = getVersion()) {
+  return `npm install -g ${NPM_PKG}${getReleaseChannel(version) === 'dev' ? '@dev' : ''}`;
+}
 
 export function getVersion() {
   try {
@@ -26,16 +32,16 @@ export function cancelBackgroundChecks() {
   backgroundChecks.clear();
 }
 
-export async function checkLatest({ timeout = 1500, background = false } = {}) {
+export async function checkLatest({ timeout = 1500, background = false, version = getVersion() } = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeout);
   timer.unref();
   if (background) backgroundChecks.add(controller);
   try {
-    const res = await fetch(NPM_REGISTRY, { signal: controller.signal });
+    const res = await fetch(`https://registry.npmjs.org/${NPM_PKG}/${getReleaseChannel(version)}`, { signal: controller.signal });
     if (!res.ok) return null;
     const data = await res.json();
-    return data.version;
+    return typeof data.version === 'string' ? data.version : null;
   } catch {
     return null;
   } finally {
@@ -58,11 +64,11 @@ export function versionCmd(wrap) {
       const version = getVersion();
 
       if (argv.check) {
-        const latest = await checkLatest();
+        const latest = await checkLatest({ version });
         if (!latest) {
           app.ok({ version }, {
             summary: `jsn ${version} (could not reach npm registry to check for updates)`,
-            notice: `Run \`npm view ${NPM_PKG}\` directly to check manually`,
+            notice: `Run \`npm view ${NPM_PKG}@${getReleaseChannel(version)} version\` directly to check manually`,
           });
           return;
         }
@@ -82,11 +88,11 @@ export function versionCmd(wrap) {
             version,
             latest,
             upToDate: false,
-            installCmd: `npm install -g ${NPM_PKG}`,
+            installCmd: getInstallCommand(version),
           }, {
             summary: `jsn ${version} — newer version ${latest} available`,
             breadcrumbs: [
-              { action: 'update', cmd: `npm install -g ${NPM_PKG}`, description: `Update jsn from ${version} to ${latest}` },
+              { action: 'update', cmd: getInstallCommand(version), description: `Update jsn from ${version} to ${latest}` },
             ],
           });
         }

package/src/constrained-query.js

@@ -0,0 +1,20 @@
+import { errUsageHint } from './errors.js';
+
+/** Constrained table views accept literal AND filters. Encoded queries have no
+ * portable parenthesization; OR/NQ/dynamic clauses must not escape fixed filters. */
+export function constrainQuery(query = '', constraint = '') {
+  if (!constraint) return query;
+  const clauses = String(query).split('^').filter((clause, index, values) => clause !== 'EQ' || index !== values.length - 1);
+  if (!query) return constraint;
+  const literal = /^[a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)*(?:(?:!=|>=|<=|=|>|<|NOT LIKE|STARTSWITH|ENDSWITH|LIKE|NOT IN|IN)[^^]*|ISEMPTY|ISNOTEMPTY)$/;
+  const ordering = /^ORDERBY(?:DESC)?[a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)*$/;
+  const allowed = clause => ordering.test(clause) || (literal.test(clause)
+    && (!/^(?:NQ|OR)/i.test(clause) || /^order(?:!=|>=|<=|=|>|<|NOT LIKE|STARTSWITH|ENDSWITH|LIKE|NOT IN|IN|ISEMPTY|ISNOTEMPTY)/.test(clause)));
+  if (/javascript\s*:/i.test(query) || clauses.some(clause => !allowed(clause))) {
+    throw errUsageHint('This constrained command accepts literal AND filters and ORDERBY only; OR, NQ and dynamic query clauses are unsupported.',
+      `The fixed filter is ${constraint}. Use literal AND clauses, or explicitly use records list for advanced queries and retain the intended constraints in every branch.`);
+  }
+  return clauses.length ? `${constraint}^${clauses.join('^')}` : constraint;
+}
+
+export const constrainedQueryHelp = constraint => `Always includes: ${constraint}. Additional --query filters use literal AND clauses (plus ORDERBY). OR, NQ and dynamic query clauses are rejected before requests so they cannot bypass this view's fixed filter.`;

package/src/context.js

@@ -18,26 +18,26 @@ export async function getCurrentUser(sdk) {
   };
 }
 
-export async function getCurrentApplication(sdk, userSysID) {
+export async function getCurrentApplication(sdk, userSysID, { unknownWhenMissing = false } = {}) {
   const params = new URLSearchParams();
   params.set('sysparm_query', `user=${userSysID}^name=apps.current_app`);
   params.set('sysparm_limit', '1');
   params.set('sysparm_fields', 'value');
   const records = await sdk.list('sys_user_preference', params);
-  if (records.length === 0) return { scope: 'global', appSysId: '' };
+  if (records.length === 0) return { scope: unknownWhenMissing ? '' : 'global', appSysId: '' };
   const val = records[0].value?.value || records[0].value;
-  if (!val) return { scope: 'global', appSysId: '' };
+  if (!val) return { scope: unknownWhenMissing ? '' : 'global', appSysId: '' };
 
   // Try to resolve sys_id to scope name
   try {
     const app = await sdk.get('sys_scope', val);
-    if (app) return { scope: app.scope || 'global', appSysId: val };
+    if (app) return { scope: getStringField(app, 'scope') || (unknownWhenMissing ? '' : 'global'), appSysId: val };
   } catch {
     // fallback
   }
   try {
     const app2 = await sdk.get('sys_app', val);
-    if (app2) return { scope: app2.scope || 'global', appSysId: val };
+    if (app2) return { scope: getStringField(app2, 'scope') || (unknownWhenMissing ? '' : 'global'), appSysId: val };
   } catch {
     // fallback
   }
@@ -56,7 +56,7 @@ export async function getCurrentUpdateSet(sdk, userSysID) {
 
   try {
     const us = await sdk.get('sys_update_set', val);
-    if (us) return { name: us.name || val, sys_id: val };
+    if (us) return { name: getStringField(us, 'name') || val, sys_id: val, application: us.application, state: getStringField(us, 'state') };
   } catch {
     // fallback
   }

package/src/customization-guidance.js

@@ -0,0 +1,31 @@
+// Shared interpretation for CLI help, saved-report views and comparisons.
+// Keep this independent of capture/storage so older captures remain readable.
+export function customizationGuidance() {
+  return {
+    capture: 'Capture uses bounded GET-only table reads and saves reports locally. Authentication may refresh OAuth credentials locally or bootstrap a session/GCK with authentication POSTs. Saved list/show/compare/html operations are offline.',
+    evidence: {
+      upgrade_skips: 'Raw upgrade dispositions 4 and 104 are historical skipped-customization evidence; reviewed_reverted rows are excluded. Display labels and other skip reasons are not equivalent. A skip does not prove a current OOTB baseline deviation.',
+      ownership: 'Customer scopes must be declared explicitly. Matching a scope verifies its identity, not customer or publisher ownership. Non-global scope and updater names do not establish ownership.',
+      metadata: 'The broad sys_metadata read is an arbitrary sys_id-ordered bounded sample, not an inventory. Declared-customer and unclassified categories are not complete inventories; they can include sampled artifacts and artifacts found by skipped-history lookups.',
+      resolution: 'Every observed skipped file_name is resolved by chunked sys_metadata.sys_update_name lookups. Unresolved names and failed lookup chunks remain coverage gaps. A resolved artifact may lack a scope name when its scope was outside the bounded sys_scope read.',
+    },
+    limitations: [
+      'All captures are incomplete. No findings is not proof of no customizations; ACLs, pagination limits, unmatched evidence and concurrent changes can hide artifacts.',
+      'Current baseline, full source payloads, runtime reversion impact and dependencies are not established. An empty dependency list does not prove none exist.',
+    ],
+    comparison: 'Comparisons cover captured metadata and evidence only. Added/removed means newly observed/no longer observed, not proven creation/deletion. Changed declarations or coverage can change categories without an artifact change.',
+    next_steps: [
+      'Review coverage, evidence and per-artifact confidence before drawing conclusions.',
+      'Verify ownership and compare with a trusted baseline for the exact release; investigate dependencies and test in non-production before changing records. Never recommend automatic reversion.',
+    ],
+    automated_remediation: false,
+  };
+}
+
+export function formatCustomizationGuidance() {
+  const guidance = customizationGuidance();
+  return [
+    ...Object.values(guidance.evidence), ...guidance.limitations,
+    guidance.comparison, ...guidance.next_steps.map(step => `Next: ${step}`),
+  ].join('\n');
+}

package/src/customizations-report.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { customizationGuidance, formatCustomizationGuidance } from './customization-guidance.js';
 
 const CLASSIFICATIONS = {
   ootb_modifications: {
@@ -94,6 +95,7 @@ export function buildActionableReport(report) {
     start_time: report.start_time,
     artifacts,
     coverage: report.coverage,
+    interpretation: customizationGuidance(),
   };
 }
 
@@ -119,6 +121,7 @@ export function renderCustomizationHtml(report) {
 <section class="toolbar" aria-label="Report filters"><label class="control grow">Search artifacts<input id="search" type="search" placeholder="Name, table, scope, updater, evidence"></label><label class="control">Classification<select id="category"><option value="">All classifications</option>${categoryOptions}</select></label><label class="control">Group by<select id="group-by"><option value="type">File type</option><option value="scope">Scope</option><option value="updated_by">Updated by</option></select></label></section>
 <section id="results" aria-live="polite"></section>
 <details class="coverage"><summary>Capture coverage and limitations</summary><div id="coverage-content"></div></details>
+<details class="coverage"><summary>How to interpret this evidence</summary>${formatCustomizationGuidance().split('\n').map(line => `<p>${escapeHtml(line)}</p>`).join('')}</details>
 <script id="report-data" type="application/json">${data}</script>
 <script>
 'use strict';
@@ -146,6 +149,9 @@ function render(){
 for(const [categoryName,items] of Object.entries(report.artifacts.reduce((groups,item)=>{groups[item.category]=(groups[item.category]||0)+1;return groups;},{})))document.getElementById('stats').append(el('span',categoryName.replaceAll('_',' ')+': '+items,'stat'));
 search.addEventListener('input',render);category.addEventListener('change',render);groupBy.addEventListener('change',render);render();
 const coverage=document.getElementById('coverage-content');const ul=el('ul');for(const [source,details] of Object.entries(report.coverage.sources||{})){ul.append(el('li',source+': '+details.status+', '+details.fetched+'/'+(details.available??'unknown')+' rows. '+details.reason));}coverage.append(ul);for(const note of report.coverage.limitations||[])coverage.append(el('p',note));
+coverage.append(el('p','Unmatched upgrade history records: '+(report.coverage.unmatched_upgrade_records??'unknown')));
+if(report.coverage.unmatched_customer_scopes?.length)coverage.append(el('p','Unmatched customer declarations: '+report.coverage.unmatched_customer_scopes.join(', ')));
+const upgrade=report.coverage.upgrade_evidence;if(upgrade){coverage.append(el('p','Observed skipped rows: '+upgrade.skipped_rows_observed+'; update names: '+upgrade.update_names_observed+'; resolved by lookup: '+upgrade.resolved_by_lookup+'; failed lookup chunks: '+upgrade.lookup_failures));if(upgrade.unresolved_update_names?.length)coverage.append(el('p','Unresolved skipped update names: '+upgrade.unresolved_update_names.join(', ')));}
 </script>
 </main></body></html>\n`;
 }

package/src/customizations.js

@@ -6,6 +6,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { getVersion } from './commands/version.js';
 import { classifyCustomization } from './customizations-report.js';
+import { customizationGuidance, formatCustomizationGuidance } from './customization-guidance.js';
 
 // Raw provider choices: 4 = Skipped, 104 = Skipped (second pass). Other skip
 // dispositions do not establish a preserved customization, so the upgrade
@@ -290,22 +291,28 @@ export function compareReports(baseline, newer) {
   const unknowns = ['Additions/removals mean newly observed/no longer observed, not proven creation/deletion. ACLs, limits and concurrent changes can affect visibility.', 'Only captured metadata and evidence are compared, not full artifact content or OOTB baselines.', 'Ownership declarations, scope visibility and evidence coverage can cause category changes without an artifact change.'];
   if (unreliable) unknowns.push(`Unavailable or empty sources make observed additions/removals unreliable: baseline [${impaired.baseline.join(', ') || 'none'}], new [${impaired.new.join(', ') || 'none'}]. They may reflect missing coverage rather than a real change and must not be read as mass creation or deletion.`);
   return { baseline_run_id: baseline.run_id, new_run_id: newer.run_id, instance: baseline.instance, status: unreliable ? 'unreliable' : 'incomplete', additions, removals, changes,
-    impaired_sources: impaired,
+    impaired_sources: impaired, interpretation: customizationGuidance(),
     coverage: { baseline: baseline.coverage, new: newer.coverage },
     unknowns };
 }
 
-function formatReportDetailed(report) {
-  const lines = [`Customization capture ${report.run_id}${report.label ? ` (${report.label})` : ''}`, `Instance: ${report.instance}`, `Status: ${report.status}`, '', 'COVERAGE'];
-  for (const [source, coverage] of Object.entries(report.coverage.sources)) lines.push(`${source}${coverage.kind ? ` [${coverage.kind}]` : ''}: ${coverage.status}, ${coverage.fetched} fetched of ${coverage.available === null || coverage.available === undefined ? 'unknown' : coverage.available} available. ${coverage.reason}`);
-  for (const limitation of report.coverage.limitations) lines.push(`Unknown: ${limitation}`);
-  if (report.coverage.unmatched_customer_scopes.length) lines.push(`Unmatched customer declarations: ${report.coverage.unmatched_customer_scopes.join(', ')}`);
+function coverageLines(report) {
+  const lines = [];
+  for (const [source, coverage] of Object.entries(report.coverage.sources || {})) lines.push(`${source}${coverage.kind ? ` [${coverage.kind}]` : ''}: ${coverage.status}, ${coverage.fetched} fetched of ${coverage.available === null || coverage.available === undefined ? 'unknown' : coverage.available} available. ${coverage.reason}`);
+  for (const limitation of report.coverage.limitations || []) lines.push(`Unknown: ${limitation}`);
+  if (report.coverage.unmatched_customer_scopes?.length) lines.push(`Unmatched customer declarations: ${report.coverage.unmatched_customer_scopes.join(', ')}`);
   const upgrade = report.coverage.upgrade_evidence;
   if (upgrade) {
-    lines.push(`Observed skipped upgrade rows: ${upgrade.skipped_rows_observed}; distinct update names: ${upgrade.update_names_observed}; resolved by direct name lookup: ${upgrade.resolved_by_lookup}; unresolved: ${upgrade.unresolved_update_names.length}${upgrade.lookup_failures ? `; failed lookup chunks: ${upgrade.lookup_failures}` : ''}`);
-    if (upgrade.unresolved_update_names.length) lines.push(`Unresolved skipped update names (not visible in sys_metadata): ${upgrade.unresolved_update_names.slice(0, 20).join(', ')}${upgrade.unresolved_update_names.length > 20 ? `, ... and ${upgrade.unresolved_update_names.length - 20} more` : ''}`);
+    const unresolved = upgrade.unresolved_update_names;
+    lines.push(`Observed skipped upgrade rows: ${upgrade.skipped_rows_observed}; distinct update names: ${upgrade.update_names_observed}; resolved by direct name lookup: ${upgrade.resolved_by_lookup}; unresolved: ${unresolved?.length ?? 'unknown'}${upgrade.lookup_failures ? `; failed lookup chunks: ${upgrade.lookup_failures}` : ''}`);
+    if (unresolved?.length) lines.push(`Unresolved skipped update names (not visible in sys_metadata): ${unresolved.slice(0, 20).join(', ')}${unresolved.length > 20 ? `, ... and ${unresolved.length - 20} more` : ''}`);
   }
-  lines.push(`Unmatched upgrade history records: ${report.coverage.unmatched_upgrade_records}`);
+  lines.push(`Unmatched upgrade history records: ${report.coverage.unmatched_upgrade_records ?? 'unknown'}`);
+  return lines;
+}
+
+function formatReportDetailed(report) {
+  const lines = [`Customization capture ${report.run_id}${report.label ? ` (${report.label})` : ''}`, `Instance: ${report.instance}`, `Status: ${report.status}`, '', 'COVERAGE', ...coverageLines(report), '', 'INTERPRETATION', formatCustomizationGuidance()];
   for (const [category, items] of Object.entries(report.categories)) {
     lines.push('', `${category.toUpperCase()} (${items.length})`);
     for (const item of items) {
@@ -357,8 +364,13 @@ export function formatReport(report, { groupBy = 'type', filter = '' } = {}) {
   }
   lines.push('', 'Expand a group with --filter <group-name>. File-type filters accept the friendly label or table name. Regroup with --group-by scope or --group-by updated-by.', 'Examples:', `  jsn customizations show ${report.run_id} --filter "Script Include"`, `  jsn customizations show ${report.run_id} --group-by scope`, `  jsn customizations show ${report.run_id} --group-by updated-by`);
   lines.push('', 'Coverage and limitations are shared across these artifacts.');
-  for (const [source, coverage] of Object.entries(report.coverage.sources)) lines.push(`${source}: ${coverage.status}, ${coverage.fetched}/${coverage.available ?? 'unknown'} rows${coverage.kind ? ` (${coverage.kind})` : ''}`);
-  lines.push('Limits: metadata is a bounded sample; skipped-upgrade evidence is historical, not proof of a current OOTB difference. Scope and updater are clues, not proof of ownership.');
+  lines.push(...coverageLines(report), '', 'INTERPRETATION', formatCustomizationGuidance());
+  for (const [category, records] of Object.entries(report.categories)) {
+    if (!records.length) continue;
+    const triage = classifyCustomization(category);
+    lines.push(`${triage.label}: ${triage.confidence}. ${triage.summary}`);
+    for (const step of triage.next_steps) lines.push(`Next: ${step}`);
+  }
   return lines.join('\n') + '\n';
 }
 
@@ -395,18 +407,21 @@ function fieldChanges(before, after) {
 function describeComparedItem(item) {
   const identity = item?.identity || {};
   const scope = item?.scope || {};
+  const triage = classifyCustomization(item?.category);
   return [
     `Artifact: ${identity.table || 'unknown'}:${identity.sys_id || 'unknown'} "${identity.name || identity.update_name || 'unnamed'}"`,
     `Category: ${item?.category || 'unknown'}`,
     `Scope: ${scope.scope || scope.sys_id || 'unknown'}${scope.name ? ` (${scope.name})` : ''}`,
     `Evidence: ${(item?.evidence || []).map(evidence => `${evidence.source}:${evidence.sys_id}`).join(', ') || 'none captured'}`,
     `Risk: ${item?.risk?.rating || 'unknown'}`,
+    `Triage: ${triage.label} (${triage.confidence}). ${triage.summary}`,
+    ...triage.next_steps.map(step => `Next: ${step}`),
     `Recommendation: ${item?.recommendation || 'not recorded'}`,
   ];
 }
 
 export function formatReportComparison(result) {
-  const lines = [`Customization comparison: ${result.status}`, `Baseline: ${result.baseline_run_id}`, `New: ${result.new_run_id}`, ...result.unknowns];
+  const lines = [`Customization comparison: ${result.status}`, `Baseline: ${result.baseline_run_id}`, `New: ${result.new_run_id}`, ...result.unknowns, '', 'INTERPRETATION', formatCustomizationGuidance()];
   const impaired = result.impaired_sources || { baseline: [], new: [] };
   if (impaired.baseline.length) lines.push(`Unreliable baseline sources: ${impaired.baseline.join(', ')}`);
   if (impaired.new.length) lines.push(`Unreliable new sources: ${impaired.new.join(', ')}`);
@@ -511,7 +526,7 @@ export async function captureCustomizations({ sdk, customerScopes = [], pageSize
       },
       unmatched_upgrade_records: data.sys_upgrade_history_log.filter(row => !visibleNames.has(text(row.file_name))).length,
       unmatched_customer_scopes: customerScopes.filter(id => !data.sys_scope.some(row => text(row.sys_id) === id || text(row.scope) === id)),
-      limitations: ['Inventory covers visible sys_metadata and upgrade history only, not every customization mechanism.', `Upgrade history is read server-side for raw dispositions ${SKIP_DISPOSITIONS.join(' and ')} only; unmatched upgrade counts describe that filtered population, not all upgrade history.`, 'Coverage compares rows fetched with the Stats API count for the same query; a short page never implies exhaustion and an unavailable count leaves completeness unknown.', `The broad sys_metadata source is a bounded sample of an arbitrary sys_id-ordered slice, not an inventory, so unclassified and declared-customer categories only describe sampled artifacts. Skipped-upgrade artifacts are separate: they are resolved by the update names the filtered history read observed (${RESOLUTION_SOURCE}).`, 'Name resolution only looks up artifacts with skipped-upgrade evidence, so customizations with no upgrade-skip history are not discovered by it.', 'A resolved artifact can show a scope sys_id without a scope name when that scope record was outside the bounded sys_scope read.', 'Row/field ACL filtering and concurrent changes cannot be ruled out.', 'No current baseline, source payloads or dependency graph captured. Comparisons detect captured metadata/evidence changes only.', 'OOTB category means historical skipped-upgrade evidence, not a verified current deviation. Customer scopes are caller declarations.'],
+      limitations: ['Inventory covers visible sys_metadata and upgrade history only, not every customization mechanism.', `Upgrade history is read server-side for raw dispositions ${SKIP_DISPOSITIONS.join(' and ')} only; unmatched upgrade counts describe that filtered population, not all upgrade history.`, 'Coverage compares rows fetched with the Stats API count for the same query; a short page never implies exhaustion and an unavailable count leaves completeness unknown.', `The broad sys_metadata source is a bounded sample of an arbitrary sys_id-ordered slice, not an inventory, so unclassified and declared-customer categories are not complete inventories; they can include sampled artifacts and artifacts resolved by skipped-history lookups. Skipped-upgrade artifacts are separate: they are resolved by the update names the filtered history read observed (${RESOLUTION_SOURCE}).`, 'Name resolution only looks up artifacts with skipped-upgrade evidence, so customizations with no upgrade-skip history are not discovered by it.', 'A resolved artifact can show a scope sys_id without a scope name when that scope record was outside the bounded sys_scope read.', 'Row/field ACL filtering and concurrent changes cannot be ruled out.', 'No current baseline, source payloads or dependency graph captured. Comparisons detect captured metadata/evidence changes only.', 'OOTB category means historical skipped-upgrade evidence, not a verified current deviation. Customer scopes are caller declarations.'],
     },
   };
 }

package/src/errors.js

@@ -77,6 +77,16 @@ export function errNetwork(cause) {
 }
 
 export function errAPI(status, msg) {
+  // Authentication/authorization bodies can echo credentials. Never render them.
+  if (status === 401) {
+    const error = new AppError(CodeAuth, 'Authentication rejected for the active profile (HTTP 401).', 'Run: jsn auth login', 401);
+    error.recovery = 'jsn auth login';
+    return error;
+  }
+  if (status === 403) {
+    return new AppError(CodeForbidden, 'Access forbidden (HTTP 403).',
+      'This is an authorization/ACL/role problem, not a login problem. Check access to this endpoint.', 403);
+  }
   let hint = 'Check the API documentation for this endpoint.';
   if (status >= 500) {
     hint = 'The ServiceNow instance may be experiencing issues. Try again later.';
@@ -203,7 +213,7 @@ export function isErrorCode(err, code) {
  * back to argv.format for callers without an App (unit tests).
  */
 function resolveJsonMode(app, argv) {
-  if (app?.output) return app.output.effectiveFormat() === 'json';
+  if (app?.output) return ['json', 'quiet'].includes(app.output.effectiveFormat());
   return argv?.format === 'json';
 }
 
@@ -229,6 +239,11 @@ export function renderAppError(err, { app = null, argv = null, identifier = '' }
     return { stream: 'stderr', text, exitCode: 1 };
   }
 
+  if (code === CodeForbidden) {
+    if (resolveJsonMode(app, argv) && app) return { stream: 'stdout', text: null, exitCode: 1, appErr: true };
+    return { stream: 'stderr', text: `Error (forbidden): ${err.message}\n\nHint: ${err.hint}\n`, exitCode: 1 };
+  }
+
   if (code === CodeConfirmationRequired) {
     // Structured error for AI agents / piped consumers: the JSON envelope
     // goes to stdout (where tooling reads) so the agent can surface the
@@ -241,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/field-behavior.js

@@ -0,0 +1,15 @@
+// Schema-backed investigation paths; no universal priority order is assumed.
+export const fieldBehaviorHelp = [
+  'Investigate the observed symptom; there is no fixed priority order for every field problem.',
+  'Query filtering: jsn b4rules list --query "collection=incident^active=true" --json',
+  'Before-query rules use sys_script.when=before and the Boolean action_query=true.',
+  'Dictionary entry: jsn records list --table sys_dictionary --query "name=incident^element=caller_id" --json',
+  'Inherited dictionary overrides: jsn records list --table sys_dictionary_override --query "name=incident^element=caller_id" --json',
+  'Inspect base_table and inherited tables as needed; the dictionary entry is separate from its overrides.',
+  'Access controls: jsn acls list --query "nameINincident,incident.*,incident.caller_id,*.caller_id,*,*.*" --json',
+  'Also inspect inherited-table and wildcard ACLs. Exact name=incident alone omits field/wildcard rules.',
+  'ACL rows are evidence, not proof of effective access: operation, roles, conditions and scripts matter.',
+  'Form behavior: jsn clientscripts list --query "table=incident^active=true" --json',
+  'Form policies: jsn uipolicies list --query "table=incident^active=true" --json',
+  'Use the command help and show output to inspect the relevant records. Never bypass a business rule, ACL or other protection to make a symptom disappear.',
+].join('\n');