@jacebenson/jsn 4.3.13-dev.92.1 → 4.3.13-dev.94.1

package/README.md

@@ -78,3 +78,17 @@ npm test
 ## License
 
 MIT
+
+
+### Commands for the connected account
+
+Login and OAuth refresh check for the current account's `admin` role. Profiles
+without that role show a compact command list focused on tickets, generic
+records, people/groups, documentation, and connection management. If the role
+check is unavailable, the profile also uses compact help; this does not assert
+that the account lacks admin. Existing profiles keep full help until renewed.
+
+This applies to root help, root JSON, `discover`, and root shell completion.
+Use `jsn --all-commands --help` or `jsn discover --all-commands --json` to inspect
+every registered command. Explicit command paths remain available and ServiceNow
+ACLs decide access. Reauthenticate (or refresh OAuth) after roles change.

package/package.json

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

package/src/cli-adapter.js

@@ -332,6 +332,10 @@ export class LocalCLI {
   }
 
   _help(node, path = []) {
+    if (!path.length && this.rootHelpRenderer) {
+      process.stdout.write(this.rootHelpRenderer() + "\n");
+      return;
+    }
     const lines = [node.usageText || `Usage: ${this.script} ${path.join(' ') || '<command>'}`];
     if (node.definition.describe) lines.push(`\n${node.definition.describe}`);
     if (node.children.length) lines.push('\nCommands:\n' + node.children.filter((n) => n.name !== this.completionCommand).map((n) => `  ${n.definition.command}  ${n.definition.describe || ''}`).join('\n'));

package/src/cli.js

@@ -1,3 +1,4 @@
+import { visibleCommandRegistry } from './command-audience.js';
 // Root CLI using the local yargs-compatible adapter
 
 import yargs, { hideBin } from './cli-adapter.js';
@@ -19,6 +20,7 @@ import { discoverCmd } from './commands/discover.js';
 import { setupCmd } from './commands/setup.js';
 import { authCmd } from './commands/auth.js';
 import { recordsCmd } from './commands/records.js';
+import { attachmentsCmd } from './commands/attachments.js';
 import { cmdbCmd } from './commands/cmdb.js';
 import { snippetsCmd } from './commands/snippets.js';
 import { catalogCmd } from './commands/catalog.js';
@@ -147,6 +149,7 @@ export function buildCLI() {
       },
     ])
     .options({
+      'all-commands': { type: 'boolean', describe: 'Show the full command list, including admin and developer tools' },
       reason: { type: 'string', describe: 'Optional non-sensitive reason saved in local mutation history' },
 
       force: {
@@ -409,6 +412,7 @@ export function buildCLI() {
     // DATA
     .command(cmdbCmd(wrap))
     .command(recordsCmd(wrap))
+    .command(attachmentsCmd(wrap))
     .command(transactionsCmd(wrap))
 
     .command(platformCmd(wrap))
@@ -430,7 +434,7 @@ export function buildCLI() {
     .command(skillCmd(wrap))
     .command(docsCmd(wrap))
     .command(versionCmd(wrap))
-    .command(discoverCmd(wrap, () => cliInstance.commandRegistry()))
+    .command(discoverCmd(wrap, (argv) => visibleCommandRegistry(cliInstance.commandRegistry(), app.config, argv)))
     .demandCommand(1, 'You must specify a command')
     // Completion plumbing under a hidden command name, so the explicit
     // 'completion' command below owns the UX. (#176)
@@ -450,6 +454,12 @@ export function buildCLI() {
         if (current && !current.startsWith('-') && depth === 0) {
           out = [...new Set([...out, ...rootCommands])];
         }
+        const options = cliInstance.parseGlobalOptions(process.argv.slice(2));
+        const visible = visibleCommandRegistry(cliInstance.commandRegistry(), loadConfig(options), options);
+        if (!depth) {
+          const names = new Set(visible.commands.flatMap(command => [command.name, ...command.aliases]));
+          out = out.filter(value => value.startsWith('-') || names.has(value));
+        }
         done([...new Set(out)]);
       });
     })
@@ -486,7 +496,7 @@ export function buildCLI() {
     })
     .onParentDiscovery((argv, { path, subcommands }) => {
       // Reached only for a parent command that declares no default handler of
-      // its own (records attachments, docs community, and any future parent) —
+      // its own (attachments, docs community, and any future parent) —
       // the adapter used to fall through and exit 0 having printed nothing.
       // Children come from the registry, description included, so this list
       // cannot drift from the registrations the way a hand-written one did.
@@ -555,7 +565,7 @@ export function buildCLI() {
           if (typeof formatArgv?.get === 'string' && formatArgv.get) {
             app.output.setJqFilter(formatArgv.get);
           }
-          const { commands } = cliInstance.commandRegistry();
+          const { commands } = visibleCommandRegistry(cliInstance.commandRegistry(), loadConfig(formatArgv), formatArgv);
           try {
             app.ok({ commands }, {
               summary: `${commands.length} registered commands — run "jsn <command> --json" for a command's subcommands.`,
@@ -565,7 +575,7 @@ export function buildCLI() {
           }
           process.exit(0);
         }
-        process.stdout.write(renderHelp(loadConfig(), cliInstance.commandRegistry()) + '\n');
+        process.stdout.write(renderHelp(loadConfig(formatArgv), visibleCommandRegistry(cliInstance.commandRegistry(), loadConfig(formatArgv), formatArgv)) + '\n');
         process.exit(0);
       }
       // Every other failure here (unknown command, missing required argument,
@@ -585,6 +595,12 @@ export function buildCLI() {
       exitWithError(new AppError(CodeUsage, msg, hint), { app });
     });
 
+  cliInstance.rootHelpRenderer = () => {
+    const options = cliInstance.parseGlobalOptions(process.argv.slice(2));
+    const config = loadConfig(options);
+    return renderHelp(config, visibleCommandRegistry(cliInstance.commandRegistry(), config, options));
+  };
+
   // Snapshot the root command names (plus aliases) for the completion
   // filter. Done before any parse — command builders mutate the registry.
   rootCommands = cliInstance.getInternalMethods().getCommandInstance().getCommands();

package/src/command-audience.js

@@ -0,0 +1,35 @@
+// Presentation policy only. ServiceNow ACLs still authorize every request.
+// Explicit command paths and --all-commands remain available to every account.
+const BASIC_COMMANDS = new Set([
+  'incidents', 'changes', 'requests', 'tasks', 'tickets', 'approvals', 'records',
+  'groups', 'groupmembers', 'grouproles', 'users', 'setup', 'auth', 'skill',
+  'version', 'docs', 'history', 'discover', 'completion',
+]);
+
+export async function detectCommandAudience(sdk, username, instanceURL = sdk?.baseURL) {
+  if (!username || typeof sdk?.listStrict !== 'function') return undefined;
+  try {
+    const roles = await sdk.listStrict('sys_user_has_role', {
+      sysparm_query: 'user=javascript:gs.getUserID()^role.name=admin',
+      sysparm_fields: 'sys_id', sysparm_limit: '1',
+    }, { touchLastSeen: false });
+    return { username, instance_url: instanceURL, mode: roles.length ? 'admin' : 'basic', role_check: 'verified' };
+  } catch {
+    // Missing role access must not expand help. This is a presentation fallback,
+    // not a claim that the role query succeeded or an authorization boundary.
+    return { username, instance_url: instanceURL, mode: 'basic', role_check: 'unavailable' };
+  }
+}
+
+export function commandAudience(config, { instance, allCommands = false } = {}) {
+  if (allCommands || instance) return 'all';
+  const name = config?.activeProfile || config?.defaultProfile;
+  const profile = config?.profiles?.[name];
+  const cached = profile?.command_audience;
+  return cached?.username === profile?.username && cached?.instance_url === profile?.instance_url && cached?.mode === 'basic' ? 'basic' : 'all';
+}
+
+export function visibleCommandRegistry(registry, config, options = {}) {
+  if (commandAudience(config, options) !== 'basic') return registry;
+  return { ...registry, commands: registry.commands.filter(command => BASIC_COMMANDS.has(command.name)) };
+}

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,3 +1,4 @@
+import { detectCommandAudience } from '../command-audience.js';
 import { getEffectiveInstance, normalizeInstanceURL, saveConfig, setActiveProfile } from '../config.js';
 import { errUsage, errUsageHint, errConfirmationRequired } from '../errors.js';
 import { canUsePicker, formatCommandList, quoteShellArg } from '../helpers.js';
@@ -710,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 = {};
@@ -740,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');
@@ -1050,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,

package/src/commands/discover.js

@@ -35,7 +35,7 @@ export function discoverCmd(wrap, getRegistry) {
         'Use --json for structured results or --json --get data.commands for only matches.',
       ].join('\n')),
     handler: wrap(async (argv, app) => {
-      const commands = discoverCommands(getRegistry(), { query: argv.query, table: argv.table });
+      const commands = discoverCommands(getRegistry(argv), { query: argv.query, table: argv.table });
       const lines = commands.flatMap(command => [
         `${command.name}: ${command.description}`,
         ...(command.discovery ? [

package/src/commands/records.js

@@ -1,5 +1,3 @@
-import fs from 'node:fs';
-import path from 'node:path';
 import { formatCommandList, formatRecordForDisplay, buildQuerySuffix, buildRecordPayload, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, verifyWriteBack } from '../helpers.js';
 import { listRecords, recordListParams, getRecord, createRecord, updateRecord, deleteRecord } from '../records-engine.js';
 import { unwrapSysId } from '../resolve-record.js';
@@ -7,7 +5,7 @@ import { errUsage } from '../errors.js';
 import { declareCapabilities } from '../capabilities.js';
 
 declareCapabilities('records', {
-  mutationSubcommands: ['create', 'update', 'delete', 'bulk', 'attachments add'],
+  mutationSubcommands: ['create', 'update', 'delete', 'bulk'],
 });
 
 const tableDefaultColumns = {
@@ -304,74 +302,6 @@ export function recordsCmd(wrap) {
             app.ok({ message: 'Record deleted', table: argv.table, sys_id: sysID }, { summary: `Deleted record from ${argv.table}` });
           }),
         })
-        .command({
-          command: 'attachments',
-          describe: 'Work with attachments on a record',
-          builder: (y) => y
-            .command({
-              command: 'list',
-              describe: 'List attachments on a record',
-              builder: (yy) => yy
-                .option('sys-id', { alias: 's', type: 'string', demandOption: true, describe: 'Parent record sys_id' })
-                .option('table', { type: 'string', describe: 'Parent table name (context only)' }),
-              handler: wrap(async (argv, app) => {
-                app.requireInstance();
-                const attachments = await app.sdk.listAttachments(argv['sys-id']);
-                app.ok({
-                  sys_id: argv['sys-id'],
-                  table: argv.table || '',
-                  count: attachments.length,
-                  attachments,
-                  context: { instance_url: app.getEffectiveInstance() },
-                }, { summary: `${attachments.length} attachment(s) on record ${argv['sys-id']}` });
-              }),
-            })
-            .command({
-              command: 'get <attachment-id>',
-              describe: 'Download an attachment to a local file',
-              builder: (yy) => yy
-                .positional('attachment-id', { describe: 'Attachment sys_id', type: 'string' })
-                .option('sys-id', { alias: 's', type: 'string', demandOption: true, describe: 'Parent record sys_id (used to resolve the file name)' })
-                .option('out', { alias: 'o', type: 'string', describe: 'Output file path (default: attachment file name in cwd)' }),
-              handler: wrap(async (argv, app) => {
-                app.requireInstance();
-                const buf = await app.sdk.getAttachment(argv['attachment-id']);
-                let name = argv.out;
-                if (!name) {
-                  // Best-effort: derive the file name from the attachment row.
-                  let fileName = `${argv['attachment-id']}.bin`;
-                  try {
-                    const rows = await app.sdk.listAttachments(argv['sys-id']);
-                    const hit = (rows || []).find((a) => getStringField(a, 'sys_id') === argv['attachment-id']);
-                    const fn = getStringField(hit, 'file_name');
-                    if (fn) fileName = fn;
-                  } catch { /* keep default */ }
-                  name = fileName;
-                }
-                await fs.promises.writeFile(name, buf);
-                app.ok({ sys_id: argv['attachment-id'], out: name, bytes: buf.length }, { summary: `Wrote ${buf.length} bytes to ${name}` });
-              }),
-            })
-            .command({
-              command: 'add <file>',
-              describe: 'Upload a file as a new attachment on a record (mutation)',
-              builder: (yy) => yy
-                .positional('file', { describe: 'Local file path to upload', type: 'string' })
-                .option('sys-id', { alias: 's', type: 'string', demandOption: true, describe: 'Parent record sys_id' })
-                .option('table', { type: 'string', demandOption: true, describe: 'Parent table for the record (e.g. incident)' })
-                .option('name', { type: 'string', describe: 'Display file name (default: basename of --file)' })
-                .option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
-              handler: wrap(async (argv, app) => {
-                app.requireInstance();
-                await confirmDelete(app, argv, `Upload "${argv.file}" as an attachment on ${argv.table} ${argv['sys-id']}?`);
-                const content = await fs.promises.readFile(argv.file);
-                const fileName = argv.name || path.basename(argv.file);
-                const created = await app.sdk.addAttachment(argv.table, argv['sys-id'], content, fileName);
-                app.ok({ sys_id: created?.sys_id, file_name: fileName, table: argv.table, recordsys_id: argv['sys-id'] }, { summary: `Attached ${fileName}` });
-              }),
-            })
-            .demandCommand(1, 'Specify an attachment action: list, get, or add'),
-        })
         .command({
           command: 'aggregate',
           describe: 'Run ServiceNow Stats API aggregation with optional grouping',

package/src/help.js

@@ -203,6 +203,8 @@ function renderFlags(options) {
 export function renderTips() {
   return `
 TIPS
+  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

package/src/mutations.js

@@ -33,7 +33,7 @@ function currentPaths(paths) {
  * Prefix match: a command whose argv._ path begins with a mutation pattern
  * IS that mutation (trailing positionals like a sys_id or file path don't
  * change the intent). This lets positional mutation subcommands (e.g.
- * `records attachments <id> add <file>`) be gated on read-only profiles.
+ * `attachments upload <file>`) be gated on read-only profiles.
  *
  * @param {object} argv — yargs parsed argv with `_` array
  * @param {Array<string[]>} [paths] — mutation path patterns; defaults to