@jacebenson/jsn 4.3.12 → 4.3.13-dev.100.1

package/src/commands/_ticket.js

@@ -1,12 +1,14 @@
+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
 
-import { getStringField, formatRecordForDisplay, buildQuerySuffix, resolveFieldsParam, confirmDelete, interactiveList, canPrompt } from '../helpers.js';
-import { resolveRecord, resolveSysId } from '../resolve-record.js';
+import { getStringField, formatRecordForDisplay, buildQuerySuffix, resolveFieldsParam, confirmDelete, interactiveList, canPrompt, buildRecordPayload } from '../helpers.js';
+import { getRecord, listRecords, recordListParams, createRecord, updateRecord, deleteRecord, recordOptions } from '../records-engine.js';
+import { resolveSysId } from '../resolve-record.js';
 import { FormatAuto } from '../output.js';
 import { declareCapabilities } from '../capabilities.js';
 
-export function buildTicketCommands(table, displayName, alias, defaultColumns, stateMap, iconFn, wrap) {
+export function buildTicketCommands(table, displayName, alias, defaultColumns, stateMap, iconFn, wrap, opts = {}) {
   // Ticket-style CRUD: list/show are reads; create/update/delete mutate.
   // Root-level command only.
   declareCapabilities(displayName, { mutationSubcommands: ['create', 'update', 'delete'] });
@@ -14,13 +16,14 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
     command: `${displayName} [subcommand]`,
     aliases: [table, alias],
     describe: `Manage ${displayName} (e.g. "${displayName} list --query priority=1")`,
+    discovery: { table, defaultColumns, benefits: ['Configured list columns', 'Ticket-specific create/update flags'] },
     builder: (yargs) => {
       return yargs
         .command({
           command: 'list',
           aliases: ['ls'],
           describe: `List ${table}`,
-          builder: (y) => y
+          builder: (y) => recordOptions(y)
             .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident" or "active=true")' })
             .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description")' })
             .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' })
@@ -73,24 +76,19 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
               app.ok(record, {
                 summary: `${displayName.charAt(0).toUpperCase() + displayName.slice(1)} ${number}`,
                 breadcrumbs: [
-                  { action: 'update', cmd: `jsn ${alias} update ${number} --data '{...}'`, description: `Update this ${displayName}` },
+                  { action: 'update', cmd: `jsn ${alias} update ${number} -f state=2`, description: `Update this ${displayName}` },
                   { action: 'list', cmd: `jsn ${alias} list`, description: `Back to all ${table}` },
                 ],
               });
               return;
             }
 
-            const params = new URLSearchParams();
-            params.set('sysparm_limit', String(limit));
-            params.set('sysparm_offset', String(offset));
-            params.set('sysparm_display_value', 'all');
             const fields = resolveFieldsParam(columns);
-            if (fields) params.set('sysparm_fields', fields);
             const q = query ? query + '^ORDERBYDESCsys_updated_on' : 'ORDERBYDESCsys_updated_on';
-            params.set('sysparm_query', q);
+            const params = recordListParams({ limit, offset, fields, query: q });
 
-            const records = await app.sdk.list(table, params);
-            const displayRecords = fields ? records.map(r => formatRecordForDisplay(r, columns)) : records;
+            const records = await listRecords(app.sdk, { table, params, displayValues: argv.displayValues ?? opts.referenceMode });
+            const displayRecords = fields && !argv.displayValues && opts.listProjection !== 'full' ? records.map(r => formatRecordForDisplay(r, columns)) : records;
 
             const breadcrumbs = [
               { action: 'create', cmd: `jsn ${alias} create --description "..."`, description: `Create a new ${displayName}` },
@@ -129,9 +127,15 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
           command: 'show <number>',
           aliases: ['get'],
           describe: `Show a specific ${displayName}`,
+          builder: 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 resolveRecord(app.sdk, { table, identifier: number, matchField: 'number', resource: displayName });
+            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,
@@ -139,7 +143,7 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
             app.ok(record, {
               summary: `${displayName.charAt(0).toUpperCase() + displayName.slice(1)} ${number}`,
               breadcrumbs: [
-                { action: 'update', cmd: `jsn ${alias} update ${number} --data '{...}'`, description: `Update this ${displayName}` },
+                { action: 'update', cmd: `jsn ${alias} update ${number} -f state=2`, description: `Update this ${displayName}` },
                 { action: 'list', cmd: `jsn ${alias} list`, description: `Back to all ${table}` },
               ],
             });
@@ -148,21 +152,21 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
         .command({
           command: 'create',
           describe: `Create a new ${displayName}`,
-          builder: (y) => y
+          builder: (y) => recordOptions(y, false)
             .option('description', { alias: 'd', type: 'string', describe: 'Short description' })
             .option('priority', { type: 'string', describe: 'Priority (1-5)' })
-            .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.description) recordData.short_description = argv.description;
             if (argv.priority) recordData.priority = argv.priority;
             if (!recordData.short_description) {
-              throw new Error('short_description is required (use --description or --data)');
+              throw new Error('short_description is required (use --description, -f short_description=..., or --data)');
             }
-            const record = await app.sdk.create(table, recordData);
+            const record = await createRecord(app.sdk, { table, data: recordData });
             app.ok(record, {
               summary: `Created ${displayName} ${getStringField(record, 'number')}`,
               breadcrumbs: [
@@ -174,13 +178,16 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
         .command({
           command: 'update <number>',
           describe: `Update a ${displayName}`,
-          builder: (y) => y
-            .option('data', { type: 'string', demandOption: true, describe: 'JSON data to update' }),
+          builder: (y) => recordOptions(y, false)
+            .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 number = argv.number;
-            const recordData = JSON.parse(argv.data);
-            const sysID = await resolveSysId(app.sdk, { table, identifier: number, matchField: 'number', resource: displayName });
-            const updated = await app.sdk.update(table, sysID, recordData);
+            const recordData = buildRecordPayload(argv);
+            const sysID = await resolveSysId(app.sdk, { table, identifier: number, identifierField: argv.identifierField, displayValues: argv.displayValues ?? opts.referenceMode, matchField: opts.identifierField || 'number', resource: displayName });
+            const updated = await updateRecord(app.sdk, { table, record: { sys_id: sysID }, data: recordData });
             app.ok(updated, {
               summary: `Updated ${displayName} ${number}`,
               breadcrumbs: [
@@ -192,12 +199,12 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
         .command({
           command: 'delete <number>',
           describe: `Delete a ${displayName}`,
-          builder: (y) => y.option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
+          builder: (y) => recordOptions(y, false).option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
           handler: wrap(async (argv, app) => {
             const number = argv.number;
             await confirmDelete(app, argv, `Delete ${displayName} ${number}`);
-            const sysID = await resolveSysId(app.sdk, { table, identifier: number, matchField: 'number', resource: displayName });
-            await app.sdk.delete(table, sysID);
+            const sysID = await resolveSysId(app.sdk, { table, identifier: number, identifierField: argv.identifierField, displayValues: argv.displayValues ?? opts.referenceMode, matchField: opts.identifierField || 'number', resource: displayName });
+            await deleteRecord(app.sdk, { table, record: { sys_id: sysID } });
             app.ok({ number, message: `${displayName.charAt(0).toUpperCase() + displayName.slice(1)} deleted` }, {
               summary: `Deleted ${displayName} ${number}`,
             });

package/src/commands/attachments.js

@@ -0,0 +1,88 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { confirmDelete, getStringField } from '../helpers.js';
+import { errUsage } from '../errors.js';
+import { declareCapabilities } from '../capabilities.js';
+
+declareCapabilities('attachments', { mutationSubcommands: ['upload', 'add'] });
+const identifier = value => {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9_-]+$/.test(value)) throw errUsage('Supply a safe record or attachment sys_id.');
+  return value;
+};
+
+// A server-provided filename may never choose directories or platform devices.
+export function attachmentFilename(value, id) {
+  const name = path.posix.basename(String(value || '').replaceAll('\\', '/'))
+    .replace(/[<>:"|?*\p{Cc}]/gu, '_').replace(/[. ]+$/g, '');
+  return !name || /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(name) ? `${id}.bin` : name;
+}
+
+export const attachmentsCmd = wrap => ({
+  command: 'attachments [subcommand]',
+  aliases: ['attachment'],
+  describe: 'List, download and upload files attached to any record',
+  builder: y => y
+    .epilogue([
+      'List files: jsn attachments list --sys-id <record-id>',
+      'Download by attachment ID: jsn attachments download <attachment-id> --out ./file.bin',
+      'Upload: jsn attachments upload ./file.txt --table incident --sys-id <record-id>',
+      'download/get and upload/add are aliases. The former records attachments subtree has moved here.',
+      'Downloads use a safe basename and refuse to overwrite existing local files unless --overwrite is supplied.',
+    ].join('\n'))
+    .command({
+      command: 'list',
+      describe: 'List attachment metadata for a parent record',
+      builder: y => y
+        .option('sys-id', { alias: 's', type: 'string', demandOption: true, describe: 'Parent record sys_id' })
+        .option('table', { type: 'string', describe: 'Parent table (output context only)' }),
+      handler: wrap(async (argv, app) => {
+        const id = identifier(argv['sys-id']);
+        app.requireInstance();
+        const attachments = await app.sdk.listAttachments(id);
+        app.ok({ sys_id: id, table: argv.table || '', count: attachments.length, attachments,
+          context: { instance_url: app.getEffectiveInstance() } }, { summary: `${attachments.length} attachment(s) on record ${id}` });
+      }),
+    })
+    .command({
+      command: 'download <attachment-id>',
+      aliases: ['get'],
+      describe: 'Download file bytes by attachment ID; no parent record ID needed',
+      builder: y => y
+        .positional('attachment-id', { type: 'string', describe: 'Attachment sys_id' })
+        .option('out', { alias: 'o', type: 'string', describe: 'Local output path (default: safe attachment filename in cwd)' })
+        .option('overwrite', { type: 'boolean', default: false, describe: 'Replace an existing local file' }),
+      handler: wrap(async (argv, app) => {
+        const id = identifier(argv.attachmentId ?? argv['attachment-id']);
+        app.requireInstance();
+        let out = argv.out;
+        if (!out) {
+          const metadata = await app.sdk.request(`${app.sdk.baseURL}/api/now/attachment/${id}`, { method: 'GET' });
+          out = attachmentFilename(getStringField(metadata?.result, 'file_name'), id);
+        }
+        const bytes = await app.sdk.getAttachment(id);
+        await fs.writeFile(out, bytes, { flag: argv.overwrite ? 'w' : 'wx' });
+        app.ok({ sys_id: id, out, bytes: bytes.length }, { summary: `Wrote ${bytes.length} bytes to ${out}` });
+      }),
+    })
+    .command({
+      command: 'upload <file>',
+      aliases: ['add'],
+      describe: 'Upload a local file to a record (requires confirmation)',
+      builder: y => y
+        .positional('file', { type: 'string', describe: 'Local file to upload' })
+        .option('sys-id', { alias: 's', type: 'string', demandOption: true, describe: 'Parent record sys_id' })
+        .option('table', { type: 'string', demandOption: true, describe: 'Parent table, for example incident' })
+        .option('name', { type: 'string', describe: 'Attachment filename (default: local basename)' })
+        .option('force', { type: 'boolean', default: false, describe: 'Skip upload confirmation after approval' }),
+      handler: wrap(async (argv, app) => {
+        const id = identifier(argv['sys-id']);
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(argv.table)) throw errUsage('Supply a valid parent table name.');
+        app.requireInstance();
+        await confirmDelete(app, argv, `Upload "${argv.file}" as an attachment on ${argv.table} ${id}?`);
+        const content = await fs.readFile(argv.file);
+        const fileName = argv.name || path.basename(argv.file);
+        const created = await app.sdk.addAttachment(argv.table, id, content, fileName);
+        app.ok({ sys_id: getStringField(created, 'sys_id'), file_name: fileName, table: argv.table, recordsys_id: id }, { summary: `Attached ${fileName}` });
+      }),
+    }),
+});

package/src/commands/auth.js

@@ -1,8 +1,10 @@
+import { detectCommandAudience } from '../command-audience.js';
 import { getEffectiveInstance, normalizeInstanceURL, saveConfig, setActiveProfile } from '../config.js';
-import { errUsage, errUsageHint } from '../errors.js';
+import { errUsage, errUsageHint, errConfirmationRequired } from '../errors.js';
 import { canUsePicker, formatCommandList, quoteShellArg } from '../helpers.js';
 import { declareCapabilities } from '../capabilities.js';
 import process from 'node:process';
+import { readFile } from 'node:fs/promises';
 import { refreshSession } from '../session.js';
 
 function syncSession(app) {
@@ -139,7 +141,7 @@ export function resolveTargetProfile(argv = {}, cfg = {}, instanceURL = '') {
  */
 export function shouldUseBasicAuth(argv = {}, cfg = {}, instanceURL = '', targetProfile = null) {
   if (argv.basic || argv.password) return true;
-  if (argv.oauth || argv.code || argv.printUrl || argv.browser || argv.gck || argv.headers) return false;
+  if (argv.oauth || argv.code || argv.printUrl || argv.browser || argv.gck || argv.headers || argv.headersFile !== undefined) return false;
   if (targetProfile) return targetProfile.auth_method === 'basic';
   return Object.values(cfg.profiles || {}).some(profile =>
     profile.instance_url === instanceURL && profile.auth_method === 'basic'
@@ -147,7 +149,7 @@ export function shouldUseBasicAuth(argv = {}, cfg = {}, instanceURL = '', target
 }
 
 export function shouldUseGckAuth(argv = {}, cfg = {}, instanceURL = '', targetProfile = null) {
-  if (argv.gck || argv.headers || argv.browser) return true;
+  if (argv.gck || argv.headers || argv.browser || argv.headersFile !== undefined) return true;
   if (argv.basic || argv.password || argv.oauth || argv.code || argv.printUrl) return false;
   if (targetProfile) return targetProfile.auth_method === 'gck';
   return Object.values(cfg.profiles || {}).some(profile =>
@@ -157,10 +159,11 @@ export function shouldUseGckAuth(argv = {}, cfg = {}, instanceURL = '', targetPr
 
 export function validateLoginSelectors(argv = {}, targetProfile = null) {
   const basic = argv.basic === true || argv.password === true;
-  const gck = argv.gck === true || argv.headers !== undefined || argv.browser === true;
+  const gck = argv.gck === true || argv.headers !== undefined || argv.headersFile !== undefined || argv.browser === true;
   const oauth = argv.oauth === true || argv.code !== undefined || argv.printUrl === true || argv.waitFile !== undefined;
   if (oauth && (basic || gck)) throw errUsage('Choose only one authentication method: --oauth, --basic, or --browser/--gck.');
   if (argv.waitFile && !argv.printUrl) throw errUsage('--wait-file requires --print-url.');
+  if (argv.headers !== undefined && argv.headersFile !== undefined) throw errUsage('Choose --headers-file or --headers, not both.');
   if (argv.code !== undefined && argv.printUrl) throw errUsage('--code cannot be combined with --print-url.');
   if (argv.browserUrl !== undefined && !argv.browser) {
     throw errUsage('--browser-url requires --browser.');
@@ -168,8 +171,8 @@ export function validateLoginSelectors(argv = {}, targetProfile = null) {
   if (argv.browserName !== undefined && (!argv.browser || argv.browserUrl !== undefined)) {
     throw errUsage('--browser-name requires --browser and cannot be combined with --browser-url.');
   }
-  if (argv.browser && (argv.headers !== undefined || argv.code !== undefined || argv.printUrl || argv.waitFile)) {
-    throw errUsage('--browser cannot be combined with --headers, --code, --print-url, or --wait-file.');
+  if (argv.browser && (argv.headers !== undefined || argv.headersFile !== undefined || argv.code !== undefined || argv.printUrl || argv.waitFile)) {
+    throw errUsage('--browser cannot be combined with --headers-file, --headers, --code, --print-url, or --wait-file.');
   }
   if (basic && gck) {
     throw errUsage('Basic and browser-session selectors are mutually exclusive; choose --basic/--password or --gck/--headers.');
@@ -278,6 +281,22 @@ export async function readBrowserSessionInput() {
   });
 }
 
+/** Read captured session data without putting it in argv or printing a prompt. */
+async function readBrowserSessionFile(file) {
+  let content;
+  if (file === '-') {
+    if (process.stdin.isTTY) throw errUsageHint('--headers-file - requires piped or redirected input.', 'Pipe captured headers into this command, or pass a file path.');
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    content = Buffer.concat(chunks).toString('utf8');
+  } else {
+    try { content = await readFile(file, 'utf8'); }
+    catch { throw errUsageHint('Could not read browser-session input file.', 'Check the --headers-file path and file permissions.'); }
+  }
+  if (!content.trim()) throw errUsage('Browser-session input is empty. Supply captured headers or a cURL request.');
+  return content;
+}
+
 /** Collect human answers, then call the same login operation as auth login. */
 export async function loginWizard(app, argv = {}) {
   const { input, select, confirm, password } = await import('../prompts.js');
@@ -382,13 +401,18 @@ export async function modifyProfile(app, argv = {}) {
   const name = argv.name || argv.profile || await pickProfile(app, 'Modify which profile?', argv);
   const profile = app.config.profiles?.[name];
   if (!profile) throw new Error(`Profile not found: ${name}`);
-  const explicitSettings = ['read-only', 'skip-confirmations', 'include-counts'].some(flag => argv[flag] !== undefined);
+  if (argv.reauth !== undefined && !['auto', 'confirm', 'never'].includes(argv.reauth)) {
+    throw errUsage('--reauth must be auto, confirm, or never.');
+  }
+  const explicitSettings = ['read-only', 'skip-confirmations', 'include-counts', 'reauth'].some(flag => argv[flag] !== undefined);
   if (explicitSettings) {
     if (argv.domain !== undefined) throw errUsage('Set profile preferences and domain separately.');
     const updated = await configureProfileOptions({ ...profile }, argv);
+    if (argv.reauth !== undefined) updated.reauth = argv.reauth;
     app.config.profiles[name] = updated;
     await saveConfig(app.config);
-    app.ok({ profile: name, read_only: updated.read_only === true, confirm_deletes: updated.skip_confirmations !== true, include_counts: updated.include_counts !== false },
+    app.ok({ profile: name, read_only: updated.read_only === true, confirm_deletes: updated.skip_confirmations !== true, include_counts: updated.include_counts !== false,
+      ...(argv.reauth !== undefined ? { reauth: updated.reauth } : {}) },
       { summary: `Settings saved for ${name}` });
     return;
   }
@@ -588,8 +612,9 @@ Find your instance URL in your browser's address bar when logged into ServiceNow
   const useBasic = shouldUseBasicAuth(argv, methodConfig, instanceURL, targetProfile);
   const useGck = shouldUseGckAuth(argv, methodConfig, instanceURL, targetProfile);
   const interactive = canUsePicker(app, argv);
-  if (useGck && !argv.browser && !argv.headers && !interactive) {
-    throw errUsage('Browser sign-in needs a human. Pass --browser to explicitly open a login window, or supply a captured session.');
+  const capturedHeaders = argv.headers !== undefined || argv.headersFile !== undefined;
+  if (useGck && !argv.browser && !capturedHeaders && !interactive) {
+    throw errUsage('Browser sign-in needs a human. Pass --browser to explicitly open a login window, or supply a captured session with --headers-file <path|->.');
   }
   if (!useGck && !useBasic && !argv.printUrl && !argv.code && !interactive) {
     throw errUsage('OAuth login requires --print-url followed by --code <code> when noninteractive.');
@@ -606,9 +631,9 @@ Find your instance URL in your browser's address bar when logged into ServiceNow
   // --basic (with --password as a compatibility alias): authenticate
   // with basic auth from env vars and persist it for this profile.
   if (useGck) {
-    const credentials = (argv.browser || (!argv.gck && !argv.headers))
+    const credentials = (argv.browser || (!argv.gck && !capturedHeaders))
       ? await loginUsingBrowser(app, instanceURL, argv, targetUsername || null)
-      : await app.auth.loginWithGck(instanceURL, argv.headers || await readBrowserSessionInput(), targetUsername || null);
+      : await app.auth.loginWithGck(instanceURL, argv.headersFile !== undefined ? await readBrowserSessionFile(argv.headersFile) : argv.headers || await readBrowserSessionInput(), targetUsername || null);
     targetUsername = credentials?.username || targetUsername;
   } else if (useBasic) {
     let credentials;
@@ -686,6 +711,8 @@ Find your instance URL in your browser's address bar when logged into ServiceNow
   // profile exists; preserve it when verification is unavailable.
   username = username || targetUsername;
 
+  const commandAudience = await detectCommandAudience(app.sdk, username, instanceURL);
+
   // Save to profiles — deduplicate by instance URL
   if (!app.config.profiles) {
     app.config.profiles = {};
@@ -716,7 +743,9 @@ Find your instance URL in your browser's address bar when logged into ServiceNow
     read_only: preferences.read_only,
     skip_confirmations: preferences.skip_confirmations,
     include_counts: preferences.include_counts,
+    ...(commandAudience ? { command_audience: commandAudience } : {}),
   };
+  if (!commandAudience) delete app.config.profiles[profileName].command_audience;
   if (!targetProfile && interactive) {
     try {
       const domains = await import('./domains.js');
@@ -803,10 +832,33 @@ Examples:
   }
   const target = resolveTargetProfile(argv, app.config, instanceURL);
   const username = target.profile?.username ?? null;
-  if (username || canLogoutBareProfile(app, instanceURL, target.profile, !!argv.profile)) {
-    app.auth.logout(instanceURL, username);
+  if (!username && !canLogoutBareProfile(app, instanceURL, target.profile, !!target.name)) {
+    throw errUsageHint('Cannot identify which stored credentials to clear.', 'Choose an unambiguous identity with --profile <name>.');
+  }
+  const selector = target.name ? `--profile ${quoteShellArg(target.name)}` : quoteShellArg(instanceURL);
+  const rerun = `jsn auth logout ${selector}`;
+  const warning = `Clear locally stored credentials for ${target.name ? `profile "${target.name}" at ` : ''}${instanceURL}${username ? ` (user ${username})` : ''}? You will need to authenticate again. The profile is retained; environment credentials and ServiceNow/Chrome sessions are unaffected.`;
+  if (!argv.force) {
+    if (!canUsePicker(app, argv)) throw errConfirmationRequired(warning, rerun);
+    const { confirm } = await import('../prompts.js');
+    if (!await confirm({ message: warning, default: false })) {
+      app.ok({ logged_out: false, credentials_cleared: false, profile: target.name, instance: instanceURL },
+        { summary: 'Logout cancelled; stored credentials were retained.' });
+      return;
+    }
   }
-  app.ok({ logged_out: true, instance: instanceURL }, { summary: `✓ Logged out from ${instanceURL}` });
+  const cleared = app.auth.logout(instanceURL, username) === true;
+  const nextActions = cleared ? [
+    { action: 'Authenticate again', cmd: `jsn auth login ${selector}`, description: 'Restore locally stored authentication' },
+    ...(target.name ? [{ action: 'Remove retained profile', cmd: `jsn auth remove ${quoteShellArg(target.name)}`, description: 'Remove this connection if no longer needed' }] : []),
+  ] : [];
+  app.ok({ logged_out: cleared, credentials_cleared: cleared, profile: target.name, instance: instanceURL,
+    profile_retained: !!target.name, environment_credentials_affected: false, remote_session_terminated: false,
+    next_actions: nextActions }, {
+    summary: cleared ? `✓ Cleared local credentials for ${target.name || instanceURL}. Profile retained; environment credentials and ServiceNow/Chrome sessions are unaffected.`
+      : `No stored credentials were cleared for ${target.name || instanceURL}. Environment credentials and ServiceNow/Chrome sessions are unaffected.`,
+    breadcrumbs: nextActions,
+  });
 }
 
 export async function showAuthStatus(argv, app) {
@@ -966,10 +1018,16 @@ Examples:
 
   const target = resolveTargetProfile(argv, app.config, instanceURL);
   const targetProfile = target.profile;
+  const browser = argv.browser || (targetProfile?.auth_method === 'gck'
+    && argv.headers === undefined && argv.headersFile === undefined && canUsePicker(app, argv));
+  validateLoginSelectors({ ...argv, browser }, targetProfile);
+  if (targetProfile?.auth_method !== 'gck' && (argv.headersFile !== undefined || argv.headers !== undefined || argv.browser)) {
+    throw errUsage('Browser-session input requires a browser-session profile. Select it with --profile, or add a separate connection with auth login --name <name>.');
+  }
   if (targetProfile?.auth_method === 'gck') {
     return loginProfile({
       ...argv, instance: instanceURL, profile: target.name,
-      browser: argv.browser || (!argv.headers && canUsePicker(app, argv)),
+      browser,
     }, app);
   }
   const targetAuthOptions = {
@@ -997,12 +1055,22 @@ Examples:
     const name = target.name || app.config.activeProfile || app.config.defaultProfile;
     if (name && app.config.profiles[name] && app.config.profiles[name].instance_url === instanceURL) {
       app.config.profiles[name].domain_separation = hasDS;
+
       await saveConfig(app.config);
     }
   } catch {
     // Non-fatal — capability probe is best-effort
   }
 
+  const audienceName = target.name || app.config.activeProfile || app.config.defaultProfile;
+  const audienceProfile = app.config.profiles?.[audienceName];
+  if (audienceProfile?.instance_url === instanceURL) {
+    const sdk = app.getSDKForProfile
+      ? app.getSDKForProfile(instanceURL, { ...targetAuthOptions, profile: audienceProfile }) : app.sdk;
+    audienceProfile.command_audience = await detectCommandAudience(sdk, audienceProfile.username, instanceURL);
+    await saveConfig(app.config);
+  }
+
   app.ok({
     refreshed: true,
     instance: instanceURL,
@@ -1055,7 +1123,11 @@ export function authCmd(wrap) {
               type: 'boolean',
             })
             .option('headers', {
-              describe: 'Browser request headers or cURL command for browser-session auth',
+              describe: 'Inline browser headers (compatibility); prefer --headers-file to keep secrets out of arguments',
+              type: 'string',
+            })
+            .option('headers-file', {
+              describe: 'Read browser headers/cURL from a file, or - for stdin; no secrets in arguments',
               type: 'string',
             })
             .option('browser', {
@@ -1094,7 +1166,8 @@ export function authCmd(wrap) {
         })
         .command({
           command: 'logout [instance]',
-          describe: 'Clear stored credentials (keeps the instance entry — use "auth remove" to delete it)',
+          describe: 'Clear local credentials after approval; retains the profile. Unnecessary after ordinary operations; does not sign out of ServiceNow/Chrome or clear environment credentials.',
+          builder: sub => sub.option('force', { type: 'boolean', describe: 'Clear credentials only after explicit approval for this exact logout' }),
           handler: wrap(logoutProfile),
         })
         .command({
@@ -1114,7 +1187,8 @@ export function authCmd(wrap) {
             .option('browser', { type: 'boolean', describe: 'Explicitly open a browser to renew the session' })
             .option('browser-name', { type: 'string', describe: 'Browser to launch: chromium, chrome, or edge' })
             .option('browser-url', { type: 'string', describe: 'Advanced: local browser debugging URL (requires --browser)' })
-            .option('headers', { type: 'string', describe: 'Captured browser request headers or cURL command' }),
+            .option('headers', { type: 'string', describe: 'Inline captured headers (compatibility); prefer --headers-file' })
+            .option('headers-file', { type: 'string', describe: 'Captured headers/cURL file, or - for stdin; keeps secrets out of arguments' }),
           handler: wrap(refreshProfile),
         })
         .command({
@@ -1134,6 +1208,7 @@ export function authCmd(wrap) {
             .option('read-only', { type: 'boolean', describe: 'Set read-only access (use --no-read-only to allow writes)' })
             .option('include-counts', { type: 'boolean', describe: 'Set result counts (use --no-include-counts to disable)' })
             .option('confirm-deletes', { type: 'boolean', describe: 'Set delete confirmations (use --no-confirm-deletes to disable)' })
+            .option('reauth', { type: 'string', choices: ['auto', 'confirm', 'never'], describe: 'Browser recovery policy: auto, confirm (default), or never; interactive only' })
             .option('skip-confirmations', { type: 'boolean', describe: 'Compatibility flag: disable delete confirmations' })
             .positional('name', {
               describe: 'Profile name to modify',

package/src/commands/b4rules.js

@@ -1,5 +1,10 @@
 import { buildDevCmd } from './_generic.js';
 
-// Before-query business rules — applies filters to GlideRecord queries before they execute.
-// These are sys_script records with order < 100.
-export const b4rulesCmd = (wrap) => buildDevCmd('b4rules', 'sys_script', ['b4rule'], ['name', 'collection', 'active', 'order', 'sys_scope'], wrap, { singular: 'before-query business rule', scopeValidation: true, extraQuery: 'when=before' });
+// Query rules are explicitly marked; their order is not a classification rule.
+export const b4rulesCmd = wrap => buildDevCmd('b4rules', 'sys_script', ['b4rule'],
+  ['name', 'collection', 'active', 'order', 'sys_scope'], wrap, {
+    singular: 'before-query business rule', scopeValidation: true,
+    extraQuery: 'when=before^action_query=true',
+    describe: 'Inspect before-query business rules that can filter record reads',
+    help: 'Before-query business rules use when=before and the Boolean action_query=true. Filter collection and active status for the affected table. For field behavior, see jsn columns --help; do not bypass server rules or ACLs.',
+  });

package/src/commands/changes.js

@@ -1,7 +1,5 @@
-import { buildTicketCommands } from './_ticket.js';
-
-const changeDefaultColumns = ['number', 'short_description', 'risk', 'state', 'assigned_to'];
+import { buildProfileCommand } from '../record-profiles.js';
 
 export function changesCmd(wrap) {
-  return buildTicketCommands('change_request', 'changes', 'chg', changeDefaultColumns, {}, null, wrap);
+  return buildProfileCommand('changes', wrap);
 }

package/src/commands/columns.js

@@ -1,9 +1,10 @@
+import { fieldBehaviorHelp } from '../field-behavior.js';
 import { buildDevCmd } from './_generic.js';
 
 export const columnsCmd = (wrap) => {
   const base = buildDevCmd('columns', 'sys_dictionary', ['column', 'col'],
     ['element', 'column_label', 'internal_type', 'mandatory', 'max_length', 'active'],
-    wrap, { singular: 'column', scopeValidation: true });
+    wrap, { singular: 'column', scopeValidation: true, help: fieldBehaviorHelp });
 
   // Add --table filter
   const origBuilder = base.builder;

package/src/commands/customizations.js

@@ -4,6 +4,7 @@ import { canUsePicker } from '../helpers.js';
 import { paginatedSearch } from '../paginated-search.js';
 import { captureReport, listReports, getReport, compareReports, formatReport, formatReportList, formatReportComparison } from '../customizations.js';
 import { buildActionableReport, writeCustomizationHtml } from '../customizations-report.js';
+import { customizationGuidance, formatCustomizationGuidance } from '../customization-guidance.js';
 
 // Only capture needs an instance. Saved reports never need network access.
 declareCapabilities('customizations', { noInstance: true, skipDailyChecks: true, mutationSubcommands: [] });
@@ -25,7 +26,7 @@ async function pickReport(app, argv, exclude = null, message = 'Select a customi
 function show(app, report, options = {}) {
   const actionable = buildActionableReport(report);
   const triage = actionable.artifacts.map(({ category, category_label, identity, triage: classification }) => ({ category, category_label, identity, ...classification }));
-  app.ok({ ...report, triage, _formatted: formatReport(report, options) }, { summary: `Customization capture ${report.run_id}: ${report.status}`, breadcrumbs: [listHint, showHint(report.run_id), compareHint(report.run_id)] });
+  app.ok({ ...report, interpretation: customizationGuidance(), triage, _formatted: formatReport(report, options) }, { summary: `Customization capture ${report.run_id}: ${report.status}`, breadcrumbs: [listHint, showHint(report.run_id), compareHint(report.run_id)] });
 }
 export function customizationsCmd(wrap) {
   return {
@@ -36,7 +37,8 @@ export function customizationsCmd(wrap) {
         builder: b => b.option('label', { type: 'string', describe: 'Label for this capture' })
           .option('customer-scope', { type: 'string', array: true, default: [], describe: 'Declared customer-owned scope value or sys_id, repeatable; ownership is not inferred' })
           .option('page-size', { type: 'number', default: 100, describe: 'Records per table page, 1..1000' })
-          .option('max-pages', { type: 'number', default: 10, describe: 'Maximum pages per source, 1..100' }),
+          .option('max-pages', { type: 'number', default: 10, describe: 'Maximum pages per source, 1..100' })
+          .epilogue(`${customizationGuidance().capture}\n${formatCustomizationGuidance()}\nExample: jsn customizations capture --label review --customer-scope x_acme_app --json`),
         handler: wrap(async (argv, app) => {
           app.requireInstance();
           if (!Number.isInteger(argv.pageSize) || argv.pageSize < 1 || argv.pageSize > 1000 || !Number.isInteger(argv.maxPages) || argv.maxPages < 1 || argv.maxPages > 100) throw errUsage('page-size must be 1..1000 and max-pages 1..100');
@@ -55,18 +57,21 @@ export function customizationsCmd(wrap) {
       })
       .command({ command: 'show [run_id]', describe: 'Review a saved capture offline', builder: b => b
         .option('group-by', { type: 'string', choices: ['type', 'scope', 'updated-by'], default: 'type', describe: 'Group summary by file type, scope or last updater' })
-        .option('filter', { type: 'string', describe: 'Expand a group shown in the summary (friendly or table name for file types)' }), handler: wrap(async (argv, app) => {
+        .option('filter', { type: 'string', describe: 'Expand a group shown in the summary (friendly or table name for file types)' })
+        .epilogue(`Offline review: inspect coverage, interpretation and triage in --json output.\n${formatCustomizationGuidance()}\nExample: jsn customizations show <run_id> --get data.triage`), handler: wrap(async (argv, app) => {
         const report = argv.run_id ? requireReport(argv.run_id) : await pickReport(app, argv);
         if (report) show(app, report, { groupBy: argv.groupBy, filter: argv.filter || '' });
       }) })
       .command({ command: 'html [run_id]', describe: 'Write a searchable, self-contained HTML review of a saved capture', builder: b => b
-        .option('out', { type: 'string', describe: 'Output HTML path (must not already exist)' }), handler: wrap(async (argv, app) => {
+        .option('out', { type: 'string', describe: 'Output HTML path (must not already exist)' })
+        .epilogue('Offline review with the same interpretation and coverage as show; writes a local file without changing instance records.\nExample: jsn customizations html <run_id> --out review.html'), handler: wrap(async (argv, app) => {
         const report = argv.run_id ? requireReport(argv.run_id) : await pickReport(app, argv);
         if (!report) return;
         const file = writeCustomizationHtml(report, { out: argv.out });
-        app.ok({ run_id: report.run_id, file, artifacts: Object.values(report.categories).reduce((total, items) => total + items.length, 0) }, { summary: `Wrote offline customization review: ${file}`, breadcrumbs: [listHint, showHint(report.run_id)] });
+        app.ok({ run_id: report.run_id, file, artifacts: Object.values(report.categories).reduce((total, items) => total + items.length, 0), interpretation: customizationGuidance() }, { summary: `Wrote offline customization review: ${file}`, breadcrumbs: [listHint, showHint(report.run_id)] });
       }) })
-      .command({ command: 'compare [baseline] [new]', describe: 'Compare two saved captures from the same instance', handler: wrap(async (argv, app) => {
+      .command({ command: 'compare [baseline] [new]', describe: 'Compare two saved captures from the same instance',
+        builder: b => b.epilogue(`Offline metadata/evidence comparison; inspect both captures' coverage before interpreting changes.\n${formatCustomizationGuidance()}\nExample: jsn customizations compare <baseline_id> <new_id> --json`), handler: wrap(async (argv, app) => {
         if (!!argv.baseline !== !!argv.new) throw errUsage('Compare requires exactly two report IDs');
         if (argv.baseline && argv.baseline === argv.new) throw errUsage('Compare requires two different report IDs');
         const baseline = argv.baseline ? requireReport(argv.baseline) : await pickReport(app, argv, null, 'Select the baseline capture');
@@ -76,7 +81,8 @@ export function customizationsCmd(wrap) {
         if (baseline.instance !== newer.instance) throw errUsage('Customization reports must describe the same instance');
         const result = compareReports(baseline, newer);
         app.ok({ ...result, _formatted: formatReportComparison(result) }, { summary: `Customization comparison: ${result.status}`, breadcrumbs: [listHint, showHint(baseline.run_id), showHint(newer.run_id)] });
-      }) }),
+      }) })
+      .epilogue(`${customizationGuidance().capture}\n${formatCustomizationGuidance()}\nStart: jsn customizations capture --help\nReview: jsn customizations show --help\nCompare: jsn customizations compare --help`),
     handler: wrap(async (_argv, app) => app.ok({ command: 'customizations', subcommands: ['capture', 'list', 'show', 'html', 'compare'] }, { summary: 'Use `jsn customizations <subcommand> --help` for details.' })),
   };
 }