@jacebenson/jsn 4.3.13 → 4.4.0-dev.113.1

package/src/commands/upgrade.js

@@ -0,0 +1,69 @@
+import { spawnSync } from 'node:child_process';
+import { declareCapabilities } from '../capabilities.js';
+import { AppError, CodeAPI, CodeNetwork } from '../errors.js';
+import { checkLatest, getReleaseChannel, getVersion } from './version.js';
+
+for (const name of ['upgrade', 'update']) {
+  declareCapabilities(name, { noInstance: true, skipDailyChecks: true });
+}
+
+function installPackage(args, { structured }) {
+  const result = spawnSync('npm', args, { stdio: structured ? 'pipe' : 'inherit', encoding: 'utf8' });
+  if (result.error || result.status !== 0) {
+    throw new AppError(CodeAPI, 'npm could not upgrade jsn.', 'Check npm installation permissions and connectivity, then retry.');
+  }
+}
+
+function isNewer(candidate, installed) {
+  const parse = (value) => {
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(value);
+    if (!match) throw new AppError(CodeAPI, 'The registry returned an invalid package version.');
+    return { core: match.slice(1, 4).map(Number), pre: match[4]?.split('.') };
+  };
+  const a = parse(candidate), b = parse(installed);
+  for (let i = 0; i < 3; i++) {
+    if (a.core[i] !== b.core[i]) return a.core[i] > b.core[i];
+  }
+  if (!a.pre || !b.pre) return !a.pre && Boolean(b.pre);
+  for (let i = 0; i < Math.max(a.pre.length, b.pre.length); i++) {
+    if (a.pre[i] === b.pre[i]) continue;
+    if (a.pre[i] === undefined) return false;
+    if (b.pre[i] === undefined) return true;
+    const an = /^\d+$/.test(a.pre[i]), bn = /^\d+$/.test(b.pre[i]);
+    if (an && bn) return Number(a.pre[i]) > Number(b.pre[i]);
+    if (an !== bn) return !an;
+    return a.pre[i] > b.pre[i];
+  }
+  return false;
+}
+
+export function upgradeCmd(wrap, { version = getVersion, check = checkLatest, install = installPackage } = {}) {
+  return {
+    command: 'upgrade',
+    aliases: ['update'],
+    describe: 'Upgrade jsn through npm (preserves the installed release channel)',
+    builder: (y) => y
+      .option('channel', { type: 'string', choices: ['dev', 'latest'], describe: 'Choose the npm release channel' })
+      .option('dry-run', { type: 'boolean', describe: 'Show the install command without installing' })
+      .option('force', { type: 'boolean', describe: 'Reinstall even when the selected version is not newer' }),
+    handler: wrap(async (argv, app) => {
+      const current = version();
+      const channel = argv.channel || getReleaseChannel(current);
+      const args = ['install', '-g', `@jacebenson/jsn@${channel}`];
+      const command = `npm ${args.join(' ')}`;
+      if (argv.dryRun || argv['dry-run']) {
+        app.ok({ version: current, channel, dryRun: true, installCmd: command }, { summary: command });
+        return;
+      }
+      const latest = await check({ version: current, channel });
+      if (!latest) throw new AppError(CodeNetwork, 'Could not check the npm release channel.', 'Check connectivity and retry; use --dry-run to inspect the command.');
+      const switching = argv.channel && channel !== getReleaseChannel(current);
+      if (!argv.force && !switching && !isNewer(latest, current)) {
+        app.ok({ version: current, latest, channel, upToDate: true }, { summary: `jsn ${current} — no newer version available` });
+        return;
+      }
+      await install(args, { structured: Boolean(!process.stdout.isTTY || argv.json || argv.get || argv.format === 'json') });
+      app.ok({ previousVersion: current, version: latest, channel, upgraded: true }, { summary: `Installed jsn from the ${channel} channel (registry version ${latest})` });
+    }),
+  };
+}

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(), channel = getReleaseChannel(version) } = {}) {
   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}/${channel}`, { 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');

package/src/help.js

@@ -28,6 +28,7 @@ function renderGroup(name, commands) {
 }
 
 const CORE_COMMANDS = [
+  { name: 'knowledge', alias: 'kb', desc: 'Search and read knowledge articles' },
   { name: 'incidents', alias: 'inc', desc: 'Manage incidents' },
   { name: 'changes', alias: 'chg', desc: 'Manage change requests' },
   { name: 'requests', alias: 'req', desc: 'Manage service catalog requests' },
@@ -132,6 +133,7 @@ const CONFIG_COMMANDS = [
 ];
 
 const DEVELOPER_COMMANDS = [
+  { name: 'scan', desc: 'Instance Scan checks, suites, explicit targets, progress and findings' },
   { name: 'atf', desc: 'Automated Test Framework (list, suites, run, results)' },
   { name: 'eval', desc: 'Run server-side JavaScript' },
   { name: 'rest', desc: 'Raw REST API calls' },
@@ -200,14 +202,22 @@ function renderFlags(options) {
   return `\nFLAGS\n${lines.join('\n')}`;
 }
 
-function renderTips() {
+export function renderTips() {
   return `
 TIPS
-  --query is available on every list command (e.g. "incidents list --query priority=1")
+  Show every command, including admin and developer tools: "jsn --all-commands --help"
+  Command visibility follows the selected profile at authentication; explicit commands still use ServiceNow ACLs.
+  Find commands by task words: "jsn discover catalog"; by configured table: "jsn discover --table incident"
+  Cross-table task searches and custom tables: "jsn records list --help"
+  Specialized commands offer configured columns, lookup, and table-specific views; inspect discovery results for details
+  Raw endpoints when needed: "jsn rest --help"; examples and intent guidance: "jsn discover --help"
   Use "jsn <command> --help" for details, or "jsn <command> list --help" for list options
   "jsn --json" prints the registered command surface as JSON for scripts and agents
 
 LEARN MORE
+  Some list commands offer a picker in an interactive terminal with automatic output.
+  Arrow keys browse (10 visible items); type to search; scroll to load more; Enter selects; Esc cancels.
+  Picker eligibility and search fields vary by command. Explicit output formats (including --json) skip pickers.
   Use "jsn <command> --help" for more information about a command.`;
 }