@jacebenson/jsn 4.3.13-dev.93.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.93.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';
@@ -148,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: {
@@ -432,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)
@@ -452,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)]);
       });
     })
@@ -557,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.`,
@@ -567,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,
@@ -587,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/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/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