@jacebenson/jsn 4.3.13 → 4.4.0-dev.113.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, buildRecordPayload } from '../helpers.js';
-import { resolveRecord, resolveSysId } from '../resolve-record.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' })
@@ -80,17 +83,12 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
               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,
@@ -148,7 +152,7 @@ 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' })
@@ -162,7 +166,7 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
             if (!recordData.short_description) {
               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,7 +178,7 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
         .command({
           command: 'update <number>',
           describe: `Update a ${displayName}`,
-          builder: (y) => y
+          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' })
@@ -182,8 +186,8 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
           handler: wrap(async (argv, app) => {
             const number = argv.number;
             const recordData = buildRecordPayload(argv);
-            const sysID = await resolveSysId(app.sdk, { table, identifier: number, matchField: 'number', resource: displayName });
-            const updated = await app.sdk.update(table, sysID, recordData);
+            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: [
@@ -195,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/catalog-order.js

@@ -0,0 +1,93 @@
+import { parseDataArg, confirmDelete, quoteShellArg } from '../helpers.js';
+import { errAPI, errUsage } from '../errors.js';
+
+const ID = /^[a-f0-9]{32}$/i;
+const API = '/api/sn_sc/servicecatalog/items';
+const object = v => v && typeof v === 'object' && !Array.isArray(v);
+
+function emit(app, argv, data, summary, breadcrumbs = []) {
+  const connection = argv.profile ? ` --profile ${quoteShellArg(argv.profile)}` : argv.instance ? ` --instance ${quoteShellArg(argv.instance)}` : '';
+  app.ok(data, { summary, breadcrumbs: breadcrumbs.map(h => ({ ...h, cmd: h.cmd + connection })) });
+}
+function requireId(id) { if (!ID.test(id || '')) throw errUsage('Use the full catalog item sys_id; find it with catalogitems search.'); }
+async function describe(app, id) {
+  requireId(id);
+  const response = await app.sdk.request(`${app.sdk.baseURL}${API}/${id}`, { method: 'GET' });
+  if (!object(response?.result) || response.result.sys_id !== id) throw errAPI(200, 'Catalog API returned no readable item with the requested identity.');
+  return response.result;
+}
+function itemHints(id) {
+  return [{ action: 'describe', cmd: `jsn catalogitems describe ${id}`, description: 'Inspect catalog inputs and pricing' },
+    { action: 'preview', cmd: `jsn catalogitems order ${id} --dry-run --variables-file variables.json`, description: 'Preview an order without submitting' }];
+}
+
+export function catalogOrderCommands(wrap) {
+  return [
+    { command: 'search <text>', describe: 'Find requestable items through the Service Catalog API',
+      builder: y => y.positional('text', { type: 'string' }).option('limit', { type: 'number', default: 20, describe: 'Maximum items (1–100)' }),
+      handler: wrap(async (argv, app) => {
+        if (typeof argv.text !== 'string' || !argv.text.trim()) throw errUsage('Provide nonempty catalog search text.');
+        if (!Number.isInteger(argv.limit) || argv.limit < 1 || argv.limit > 100) throw errUsage('--limit must be from 1 to 100.');
+        const params = new URLSearchParams({ sysparm_text: argv.text.trim(), sysparm_limit: String(argv.limit) });
+        const response = await app.sdk.request(`${app.sdk.baseURL}${API}?${params}`, { method: 'GET' });
+        if (!Array.isArray(response?.result) || response.result.some(i => !object(i) || !ID.test(i.sys_id || ''))) throw errAPI(200, 'Catalog API returned no valid item list.');
+        emit(app, argv, { items: response.result, count: response.result.length, limit: argv.limit,
+          possibly_truncated: response.result.length === argv.limit }, `${response.result.length} catalog item(s)`,
+        response.result.flatMap(i => itemHints(i.sys_id).slice(0, 1)));
+      }) },
+    { command: 'describe <id>', aliases: ['inputs'], describe: 'Read requestable item details, pricing and variable definitions',
+      builder: y => y.positional('id', { type: 'string' }),
+      handler: wrap(async (argv, app) => {
+        const item = await describe(app, argv.id);
+        emit(app, argv, item, item.name || item.short_description || argv.id, itemHints(argv.id));
+      }) },
+    { command: 'order <id>', describe: 'Submit a catalog order with explicit confirmation',
+      builder: y => y.positional('id', { type: 'string' })
+        .option('variables', { type: 'string', describe: 'JSON object of catalog variable names/values' })
+        .option('variables-file', { type: 'string', describe: 'Read the variables object from a JSON file' })
+        .option('quantity', { type: 'number', default: 1, describe: 'Positive integer quantity (max 1000)' })
+        .option('requested-for', { type: 'string', describe: 'User sys_id; instance delegation rules still apply' })
+        .option('dry-run', { type: 'boolean', default: false, describe: 'Read item details and preview variable names; no order is submitted' })
+        .epilogue('Use describe to inspect variables first. Server-side rules validate the order; a preview does not prove submission will succeed. Existing create/list/show commands manage definitions. Orders require a write-enabled profile, including dry runs. No application/update-set selection is needed.'),
+      handler: wrap(async (argv, app) => {
+        requireId(argv.id);
+        if (!Number.isInteger(argv.quantity) || argv.quantity < 1 || argv.quantity > 1000) throw errUsage('--quantity must be an integer from 1 to 1000.');
+        const requestedFor = argv.requestedFor ?? argv['requested-for'];
+        if (requestedFor !== undefined && !ID.test(requestedFor)) throw errUsage('--requested-for requires a user sys_id.');
+        const file = argv.variablesFile ?? argv['variables-file'];
+        if (argv.variables !== undefined && file !== undefined) throw errUsage('Choose --variables or --variables-file, not both.');
+        const variables = argv.variables !== undefined || file !== undefined
+          ? parseDataArg({ data: argv.variables, 'data-file': file }) : {};
+        if (!object(variables)) throw errUsage('Catalog variables must be a JSON object.');
+        const item = await describe(app, argv.id);
+        if (item.sys_class_name && item.sys_class_name !== 'sc_cat_item') throw errUsage('order supports standard catalog items; record producers and order guides need their own submission workflows.');
+        if (item.active === false || item.active === 'false' || item.can_order === false) throw errUsage('This item is not currently orderable.');
+        const plan = { item_id: argv.id, name: item.name || item.short_description, quantity: argv.quantity,
+          requested_for: requestedFor || null, variable_names: Object.keys(variables) };
+        if (argv.dryRun ?? argv['dry-run']) return emit(app, argv, { ...plan, submitted: false, server_validation: 'not performed' }, 'Catalog order preview; nothing submitted', itemHints(argv.id));
+        const rerun = ['catalogitems', 'order', argv.id, '--quantity', String(argv.quantity),
+          ...(requestedFor ? ['--requested-for', requestedFor] : []),
+          ...(file ? ['--variables-file', file] : Object.keys(variables).length ? ['--variables-file', '<variables.json>'] : [])];
+        try {
+          await confirmDelete(app, argv, `Order ${argv.quantity} × ${plan.name || argv.id}${requestedFor ? ` for ${requestedFor}` : ''}?`, { rerun });
+        } catch (error) {
+          if (error.message === 'Deletion cancelled') throw errUsage('Catalog order cancelled.');
+          throw error;
+        }
+        const body = { sysparm_quantity: argv.quantity, variables, ...(requestedFor ? { sysparm_requested_for: requestedFor } : {}) };
+        let response;
+        try {
+          response = await app.sdk.request(`${app.sdk.baseURL}${API}/${argv.id}/order_now`, { method: 'POST', body: JSON.stringify(body) });
+        } catch (error) {
+          if (error.status >= 400 && error.status < 500 && error.status !== 408) throw errAPI(error.status, 'Catalog order was rejected. Check item access, required variables and requested-for eligibility.');
+          throw errAPI(error.status || 0, 'Catalog submission did not return a confirmed order. Inspect your requests before retrying; the order may have been placed.');
+        }
+        const result = response?.result;
+        const requestId = result?.request_id || result?.sys_id, number = result?.request_number || result?.number;
+        if (!object(result) || result.error || !ID.test(requestId || '') || typeof number !== 'string' || !number.trim()) throw errAPI(200, 'Catalog response did not confirm an order identity. Inspect your requests before retrying; do not resubmit automatically.');
+        emit(app, argv, { item_id: argv.id, quantity: argv.quantity, request_id: requestId, request_number: number, submitted: true },
+          `Ordered: ${number}`, [{ action: 'request', cmd: `jsn records get --table sc_request --sys-id ${requestId}`, description: 'Read the request header' },
+            { action: 'items', cmd: `jsn requests list --query ${quoteShellArg(`request=${requestId}`)}`, description: 'Track the requested items' }]);
+      }) },
+  ];
+}

package/src/commands/catalog.js

@@ -1,9 +1,10 @@
-import { getStringField, interactiveList, resolveItemOptionType } from '../helpers.js';
+import { getStringField, interactiveList, resolveItemOptionType, formatCommandList, quoteShellArg } from '../helpers.js';
+import { catalogOrderCommands } from './catalog-order.js';
 import { resolveSysId } from '../resolve-record.js';
 import { declareCapabilities } from '../capabilities.js';
 import { enrichCatalogItem, buildCatalogFormatted } from './catalog/enrich.js';
 
-declareCapabilities('catalogitems', { mutationSubcommands: ['create'] });
+declareCapabilities('catalogitems', { mutationSubcommands: ['create', 'order'], mutationContextExemptSubcommands: ['order'], localPreviewSubcommands: ['order'] });
 
 export function catalogCmd(wrap) {
   return {
@@ -11,6 +12,7 @@ export function catalogCmd(wrap) {
     aliases: ['ci'],
     describe: 'Manage Service Catalog items',
     builder: (yargs) => {
+      for (const command of catalogOrderCommands(wrap)) yargs.command(command);
       return yargs
         .command({
           command: 'create',
@@ -148,14 +150,10 @@ export function catalogCmd(wrap) {
           }),
         });
     },
-    handler: () => {
-      console.log('Service Catalog management.');
-      console.log('');
-      console.log('Commands:');
-      console.log('  create     Create a catalog item');
-      console.log('  list       Browse catalog items');
-      console.log('  show <id>  Show catalog item');
-    },
+    handler: wrap(async (argv, app) => app.ok({ subcommands: argv.subcommands || [],
+      _formatted: formatCommandList({ title: 'Service Catalog', commands: argv.subcommands || [] }) },
+    { summary: 'Service Catalog: search, describe and order items; manage definitions with create/list/show',
+      breadcrumbs: [{ action: 'search', cmd: 'jsn catalogitems search <text>' + (argv.profile ? ` --profile ${quoteShellArg(argv.profile)}` : argv.instance ? ` --instance ${quoteShellArg(argv.instance)}` : ''), description: 'Find requestable items' }] })),
   };
 }
 

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