@jacebenson/jsn 4.3.7 → 4.3.8

package/src/cli.js

@@ -10,7 +10,8 @@ import { resolveSession, applySession } from './session.js';
 import { renderHelp } from './help.js';
 import { isMutationCommand, refreshMutationCommands } from './mutations.js';
 import { noInstanceCommands, dailyCheckSkipCommands } from './capabilities.js';
-import { guardExit, exitWithError } from './errors.js';
+import { guardExit, exitWithError, AppError, CodeUsage } from './errors.js';
+import { formatCommandList } from './helpers.js';
 
 // Command modules
 import { setupCmd } from './commands/setup.js';
@@ -69,6 +70,41 @@ import { b4rulesCmd } from './commands/b4rules.js';
 import { atfCmd } from './commands/atf.js';
 import { approvalsCmd } from './commands/approvals.js';
 import { perfCmd } from './commands/perf.js';
+import { midserversCmd } from './commands/midservers.js';
+import { diffCmd } from './commands/diff.js';
+import { graphqlCmd } from './commands/graphql.js';
+
+/**
+ * The output format the caller asked for, resolved from PARSED argv.
+ *
+ * One policy, two callers: the format middleware applies it once a command
+ * parses, and the parse-time failure handler applies it when parsing fails.
+ * They used to disagree — the failure path re-scanned the raw tokens (any
+ * `--json` anywhere, first `--format` match, no option termination, no values
+ * consumed by string options, no `--no-` negation), so the stream and the shape
+ * of a failure depended on which layer rejected the command instead of on the
+ * command line the caller typed.
+ *
+ * Precedence is the middleware's, unchanged: the shortcut flags beat `--format`,
+ * and among the shortcuts the one applied last wins
+ * (csv > markdown > styled > quiet > json).
+ */
+export function resolveRequestedFormat(argv) {
+  if (!argv) return '';
+  if (argv.csv) return 'csv';
+  if (argv.markdown) return 'markdown';
+  if (argv.styled) return 'styled';
+  if (argv.quiet) return 'quiet';
+  if (argv.json) return 'json';
+  return typeof argv.format === 'string' ? argv.format : '';
+}
+
+/**
+ * Parent commands owned by another change. The adapter's discovery fallback
+ * (which gives a handler-less parent its child list instead of a silent exit 0)
+ * is skipped for these families so their own fix owns the behavior.
+ */
+const DISCOVERY_OWNED_ELSEWHERE = new Set(['auth', 'perf', 'skill', 'groupmembers', 'grouproles']);
 
 function wrap(handler) {
   return async (argv) => {
@@ -148,15 +184,14 @@ export function buildCLI() {
       },
     })
     .middleware([
-      // Apply format option overrides
+      // Apply format option overrides. The resolution lives in
+      // resolveRequestedFormat so the parse-time failure path applies the
+      // identical policy instead of approximating it from raw tokens.
       (argv) => {
-        if (argv.json) argv.format = 'json';
-        if (argv.quiet) argv.format = 'quiet';
-        if (argv.styled) argv.format = 'styled';
-        if (argv.markdown) argv.format = 'markdown';
-        if (argv.csv) argv.format = 'csv';
-        if (argv.format) {
-          app.output.setFormat(argv.format);
+        const requested = resolveRequestedFormat(argv);
+        if (requested) {
+          argv.format = requested;
+          app.output.setFormat(requested);
         }
         if (argv.get) {
           app.output.setJqFilter(argv.get);
@@ -371,6 +406,9 @@ export function buildCLI() {
     .command(atfCmd(wrap))
     .command(approvalsCmd(wrap))
     .command(perfCmd(wrap))
+    .command(midserversCmd(wrap))
+    .command(diffCmd(wrap))
+    .command(graphqlCmd(wrap))
     .command(evalCmd(wrap))
     .command(restCmd(wrap))
     .command(skillCmd(wrap))
@@ -429,14 +467,48 @@ export function buildCLI() {
         cliInstance.showCompletionScript();
       },
     })
+    .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) —
+      // 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.
+      if (DISCOVERY_OWNED_ELSEWHERE.has(path[0])) return;
+      const canonical = path.join(' ');
+      const summary = `jsn ${canonical} — available subcommands.`;
+      // Same error boundary as every registered handler (AGENTS.md: handlers go
+      // through wrap()). Discovery runs outside any command handler, and the
+      // shared extractor throws on a `--get` path that does not resolve — an
+      // unwrapped callback rejected parse() into an entry point with no
+      // rejection handler, so a missing path printed a Node stack instead of the
+      // extraction_not_found envelope.
+      return wrap(async () => {
+        (argv.app || app).ok({
+          command: canonical,
+          subcommands,
+          _formatted: formatCommandList({
+            title: `jsn ${canonical}`,
+            commands: subcommands,
+            footer: `Run "jsn ${canonical} <command> --help" for details.`,
+          }),
+        }, { summary });
+      })(argv);
+    })
     .help('help', 'Show help')
     .version(false)
     .strictCommands()
     .strictOptions(false)
     .fail((msg, err) => {
       if (err) throw err;
+      const raw = process.argv.slice(2);
+      // A parse-time failure never reaches the format middleware, so resolve the
+      // requested format with the adapter's OWN tokenizer (same option specs,
+      // option termination, consumed values, repeated options, `--no-`
+      // negation) instead of re-scanning raw argv — one policy, one answer for
+      // this command line no matter which layer rejects it.
+      const formatArgv = cliInstance.parseGlobalOptions(raw);
+      const requestedFormat = resolveRequestedFormat(formatArgv);
       if (msg === 'You must specify a command') {
-        const raw = process.argv.slice(2);
         const hasLoneProfile = raw.some((a, i, arr) => {
           if (a !== '--profile' && a !== '-p') return false;
           const next = arr[i + 1];
@@ -452,11 +524,47 @@ export function buildCLI() {
           }
           process.exit(0);
         }
-        process.stdout.write(renderHelp(loadConfig()) + '\n');
+        // No command is a discovery request, not a failure: the human view
+        // stays exactly as it was (exit 0 + grouped help), and an explicit
+        // --json gets the same surface as machine-readable data instead of
+        // prose that a parser cannot read.
+        if (requestedFormat === 'json') {
+          app.output.setFormat('json');
+          // `--get` is jsn's jq substitute for every JSON shape (AGENTS.md), so
+          // the root discovery envelope honours it too: extract when the path
+          // resolves, and fail with the structured envelope when it does not,
+          // instead of always dumping the whole envelope.
+          if (typeof formatArgv?.get === 'string' && formatArgv.get) {
+            app.output.setJqFilter(formatArgv.get);
+          }
+          const { commands } = cliInstance.commandRegistry();
+          try {
+            app.ok({ commands }, {
+              summary: `${commands.length} registered commands — run "jsn <command> --json" for a command's subcommands.`,
+            });
+          } catch (discoveryError) {
+            exitWithError(discoveryError, { app });
+          }
+          process.exit(0);
+        }
+        process.stdout.write(renderHelp(loadConfig(), cliInstance.commandRegistry()) + '\n');
         process.exit(0);
       }
-      process.stderr.write(msg + '\n');
-      process.exit(1);
+      // Every other failure here (unknown command, missing required argument,
+      // invalid choice/number) is a usage failure. Route it through the same
+      // renderer as handler and guard failures: exit 2, and the documented
+      // error envelope on stdout when the caller is in JSON mode. Previously
+      // this wrote raw prose to stderr and exited 1, so the exit code and the
+      // output shape depended on which layer rejected the command.
+      if (requestedFormat) app.output.setFormat(requestedFormat);
+      let hint;
+      try {
+        const path = cliInstance._findPath(raw).path.map((n) => n.name).join(' ');
+        hint = `Run "jsn ${path ? `${path} ` : ''}--help" for usage.`;
+      } catch {
+        hint = 'Run "jsn --help" for the command list.';
+      }
+      exitWithError(new AppError(CodeUsage, msg, hint), { app });
     });
 
   // Snapshot the root command names (plus aliases) for the completion

package/src/commands/_generic.js

@@ -181,11 +181,12 @@ export function buildDevCmd(name, table, aliases, defaultColumns, wrap, opts = {
         }),
       })
       .command({
-        command: 'show <identifier>',
+        command: opts.resolveIdentifier ? 'show [identifier]' : 'show <identifier>',
         aliases: ['get'],
         describe: `Show ${vowelArticle(singular)} ${singular} by name or sys_id`,
         handler: wrap(async (argv, app) => {
-          const id = argv.identifier;
+          const id = opts.resolveIdentifier ? await opts.resolveIdentifier(argv, app) : argv.identifier;
+          if (id === undefined) return;
           // Only restrict sysparm_fields if showFields is explicitly set.
           // Go version fetches all fields for show unless explicitly restricted.
           const fields = (showFields && showFields.length > 0)

package/src/commands/_simple.js

@@ -45,7 +45,7 @@ async function fetchExtensionChain(sdk, record) {
   return chain;
 }
 
-export const actionsCmd = (wrap) => buildDevCmd('actions', 'sys_hub_action_type_definition', ['action'], ['name', 'active', 'sys_scope', 'sys_updated_on'], wrap, { singular: 'action', scopeValidation: true });
+export { actionsCmd } from './actions.js';
 
 export const includesCmd = (wrap) => buildDevCmd('includes', 'sys_script_include', ['include', 'si'], ['name', 'api_name', 'active', 'sys_scope'], wrap, { singular: 'script include', scopeValidation: true });
 

package/src/commands/actions.js

@@ -0,0 +1,156 @@
+import { buildDevCmd } from './_generic.js';
+import { formatCommandList, parseDataArg } from '../helpers.js';
+import { resolveRecord, unwrapSysId } from '../resolve-record.js';
+import { declareCapabilities } from '../capabilities.js';
+import { ACTION_TABLE, actionScope } from '../processflow-actions.js';
+import { errUsage } from '../errors.js';
+import { cancelled, pickDesignerRecord, designerScope, guidedActionCreate, guidedActionEdit, guidedActionTestInputs, interactiveDesigner, hasDefinitionData, confirmDesignerMutation } from '../flow-designer-interactive.js';
+
+const ACTION_COMMANDS = [
+  { name: 'list', description: 'List actions' },
+  { name: 'show [identifier]', description: 'Show an action by name or sys_id' },
+  { name: 'definition [identifier]', description: 'Read the full JSON definition including executable step_instances' },
+  { name: 'step-types', description: 'Read step schema templates for a target scope' },
+  { name: 'create', description: 'Create an action: guided in a terminal, full JSON definition in scripts' },
+  { name: 'update [identifier]', description: 'Save a full definition through Process Flow (alias: edit)' },
+  { name: 'test [identifier]', description: 'Execute an action and optionally wait for actual outputs' },
+  { name: 'delete [identifier]', description: 'Delete an action parent explicitly' },
+];
+
+const scopeOption = y => y.option('scope', { type: 'string', describe: 'Exact transaction scope sys_id; inferred from existing action when omitted' });
+const dataOptions = y => y
+  .option('data-file', { type: 'string', describe: 'Full action definition JSON file, not table fields' })
+  .option('data', { type: 'string', describe: 'Full action definition as JSON' });
+async function actionID(argv, app) {
+  const identifier = await pickDesignerRecord(argv, app, ACTION_TABLE, 'action');
+  if (identifier === undefined) return undefined;
+  argv = { ...argv, identifier };
+  return unwrapSysId(await resolveRecord(app.sdk, { table: ACTION_TABLE, identifier: argv.identifier, matchField: 'name', resource: 'action' }));
+}
+
+export const actionsCmd = wrap => {
+  // Reuse the existing list/show picker and output contract only.
+  const base = buildDevCmd('actions', ACTION_TABLE, ['action'], ['name', 'active', 'sys_scope', 'sys_updated_on'], wrap, {
+    singular: 'action', readOnly: true,
+    resolveIdentifier: (argv, app) => cancelled(() => pickDesignerRecord(argv, app, ACTION_TABLE, 'action')),
+    showBreadcrumbs: (_record, id) => [
+      { action: 'definition', cmd: `jsn actions definition ${id}`, description: 'Read complete executable definition' },
+      { action: 'list', cmd: 'jsn actions list', description: 'Back to actions' },
+    ],
+  });
+  declareCapabilities('actions', { mutationSubcommands: ['create', 'update', 'edit', 'delete', 'test'] });
+  // Retain the common wrap and output controller; domain failures get a
+  // structured error envelope and nonzero exit, never a success-shaped dispatch.
+  const run = handler => wrap(async (argv, app) => {
+    try { await cancelled(() => handler(argv, app)); }
+    catch (error) {
+      if (!error.code?.startsWith('action_')) throw error;
+      if (error.details) error.hint = JSON.stringify(error.details);
+      app.err(error);
+      process.exitCode = 1;
+    }
+  });
+  return {
+    ...base,
+    describe: 'Flow Designer actions: create, edit full definitions, and test with outputs',
+    builder: y => base.builder(y)
+      .command({
+        command: 'create', describe: 'Create parent and executable Process Flow action; verify persistence',
+        builder: yy => dataOptions(yy).option('scope', { type: 'string', describe: 'Exact target scope sys_id, or global' }),
+        handler: run(async (argv, app) => {
+          const guided = !hasDefinitionData(argv) ? await guidedActionCreate(argv, app) : undefined;
+          const definition = guided?.definition ?? parseDataArg(argv);
+          const scope = guided?.scope ?? await designerScope(argv, app);
+          const result = await app.sdk.createProcessFlowAction(scope, definition);
+          app.ok(result, { summary: `Created and verified action ${result.sys_id}` });
+        }),
+      })
+      .command({
+        command: 'definition [identifier]', describe: 'Read full JSON definition including executable step_instances',
+        builder: scopeOption,
+        handler: run(async (argv, app) => {
+          const id = await actionID(argv, app);
+          if (id === undefined) return;
+          const scope = await actionScope(app.sdk, id, argv.scope);
+          app.ok(await app.sdk.getProcessFlowAction(id, scope), { summary: `Read action definition ${id}` });
+        }),
+      })
+      .command({
+        command: 'update [identifier]', aliases: ['edit'], describe: 'Save a full definition through Process Flow PUT and verify readback',
+        builder: yy => dataOptions(scopeOption(yy)),
+        handler: run(async (argv, app) => {
+          if (!hasDefinitionData(argv) && !interactiveDesigner(argv, app)) throw errUsage('Provide --data-file or --data for the full action definition in noninteractive mode');
+          const id = await actionID(argv, app);
+          if (id === undefined) return;
+          const definition = hasDefinitionData(argv) ? parseDataArg(argv)
+            : await guidedActionEdit(argv, app, await app.sdk.getProcessFlowAction(id, await actionScope(app.sdk, id, argv.scope)));
+          const result = await app.sdk.updateProcessFlowAction(id, argv.scope, definition);
+          app.ok(result, { summary: `Saved and verified action ${id}` });
+        }),
+      })
+      .command({
+        command: 'test [identifier]', describe: 'Execute saved or supplied definition; optionally wait for actual outputs',
+        builder: yy => dataOptions(scopeOption(yy))
+          .option('force', { type: 'boolean', default: false, describe: 'Confirm execution of action scripts, which may have side effects' })
+          .option('output-map', { type: 'string', describe: 'JSON action input names to values; sent as outputMap' })
+          .option('run-on-thread', { type: 'boolean', default: true, describe: 'Run test on a worker thread' })
+          .option('tracing-enabled', { type: 'boolean', default: false, describe: 'Enable Flow Designer tracing' })
+          .option('wait', { type: 'boolean', default: false, describe: 'Wait for COMPLETE context and actual runtime outputs' })
+          .option('timeout', { type: 'number', default: 60, describe: 'Maximum wait seconds after dispatch, greater than 0, at most 3600' }),
+        handler: run(async (argv, app) => {
+          let outputMap;
+          try { outputMap = JSON.parse(argv['output-map'] ?? '{}'); }
+          catch { throw errUsage('--output-map must be valid JSON'); }
+          let definition = hasDefinitionData(argv) ? parseDataArg(argv) : undefined;
+          const id = await actionID(argv, app);
+          if (id === undefined) return;
+          if (argv['output-map'] === undefined && interactiveDesigner(argv, app)) {
+            definition = await app.sdk.getProcessFlowAction(id, await actionScope(app.sdk, id, argv.scope));
+            outputMap = await guidedActionTestInputs(argv, app, definition);
+          }
+          await confirmDesignerMutation(argv, app, `Execute action '${id}' scripts, which may have side effects`);
+          const result = await app.sdk.testProcessFlowAction(id, argv.scope, definition, outputMap, {
+            wait: argv.wait, timeout: argv.timeout, runOnThread: argv['run-on-thread'], tracingEnabled: argv['tracing-enabled'],
+          });
+          app.ok(result, { summary: result.status === 'complete' ? `Test completed ${result.context}` : `Test dispatched ${result.context}; outputs not yet verified` });
+        }),
+      })
+      .command({
+        command: 'step-types', describe: 'Read step schema templates for a target scope',
+        builder: yy => yy.option('scope', { type: 'string', describe: 'Exact transaction scope sys_id, or global' }),
+        handler: run(async (argv, app) => {
+          const scope = await designerScope(argv, app);
+          app.ok(await app.sdk.getProcessFlowStepTypes(scope), { summary: 'Process Flow step schemas' });
+        }),
+      })
+      .command({
+        command: 'delete [identifier]', describe: 'Delete action parent explicitly',
+        builder: yy => scopeOption(yy).option('force', { type: 'boolean', default: false, describe: 'Skip confirmation' }),
+        handler: run(async (argv, app) => {
+          const id = await actionID(argv, app);
+          if (id === undefined) return;
+          await actionScope(app.sdk, id, argv.scope);
+          await confirmDesignerMutation(argv, app, `Delete action '${id}'`);
+          await app.sdk.delete(ACTION_TABLE, id);
+          // Verify the exact target is absent. Do not interpret a 403 as deletion.
+          const query = new URLSearchParams({ sysparm_query: `sys_id=${id}`, sysparm_limit: '1', sysparm_fields: 'sys_id', sysparm_display_value: 'false' });
+          const response = await app.sdk.request(`${app.sdk.baseURL}/api/now/table/${ACTION_TABLE}?${query}`, { method: 'GET' });
+          if (!response || response.error || !Array.isArray(response.result) || response.result.length) {
+            throw new Error(`Delete is unverified; action ${id} absence was not explicitly confirmed`);
+          }
+          app.ok({ name: argv.identifier, sys_id: id, deleted: true }, { summary: `Deleted action ${id}` });
+        }),
+      }),
+    handler: wrap(async (_argv, app) => {
+      const summary = 'Manage Flow Designer actions from the sys_hub_action_type_definition table. Create and update guide terminal users; automation passes full JSON definitions, not table fields.';
+      app.ok({
+        commands: ACTION_COMMANDS.map(command => command.name),
+        _formatted: formatCommandList({
+          title: summary,
+          commands: ACTION_COMMANDS,
+          footer: 'Run "jsn actions <command> --help" for details. In a terminal you can omit the target and pick one.',
+        }),
+      }, { summary });
+    }),
+  };
+};

package/src/commands/auth.js

@@ -1,5 +1,6 @@
 import { getEffectiveInstance, normalizeInstanceURL, saveConfig, setActiveProfile, setProfile } from '../config.js';
-import { errUsage } from '../errors.js';
+import { errUsage, errUsageHint } from '../errors.js';
+import { canUsePicker } from '../helpers.js';
 import { declareCapabilities } from '../capabilities.js';
 import process from 'node:process';
 
@@ -128,14 +129,16 @@ export function validateLoginSelectors(argv = {}, targetProfile = null) {
 }
 
 /**
- * Pick a profile by name — interactive search picker when ambiguous,
- * auto-selects when there's exactly one, throws when none configured.
+ * Pick a profile by name — interactive search picker when ambiguous and a
+ * human is available, auto-selects when there's exactly one, throws when
+ * none configured. A non-interactive caller (agent, pipe, --json/--get)
+ * never opens a picker; it falls back to the single/default profile.
  */
 export async function pickProfile(app, message) {
   const { search } = await import('@inquirer/prompts');
   const profileNames = Object.keys(app.config.profiles || {});
   if (profileNames.length === 0) throw errUsage('No profiles configured. Run "jsn setup" first.');
-  if (profileNames.length === 1 || !app.isInteractive()) return profileNames[0];
+  if (profileNames.length === 1 || !canUsePicker(app, {})) return profileNames[0];
   const choices = profileNames.map(name => ({
     name: `${name} — ${app.config.profiles[name].instance_url}`,
     value: name,
@@ -281,10 +284,9 @@ export async function loginWizard(app, argv = {}) {
   app.config.activeProfile = profileName;
   app.config.defaultProfile = profileName;
 
-  // Present all connection-level options during setup. Gated on interactivity
-  // so a piped/scripted call never blocks on prompts.
-  const { canPrompt } = await import('../helpers.js');
-  if (canPrompt()) {
+  // Present all connection-level options during setup. Gated on
+  // interactivity so a piped/scripted call never blocks on prompts.
+  if (canUsePicker(app, argv)) {
     // @inquirer/prompts owns stdin while these confirmations run. Close the
     // older readline interface before handing stdin to Inquirer. This matters
     // on Windows Git Bash: leaving both readers attached can make the later
@@ -604,7 +606,7 @@ export function authCmd(wrap) {
               instanceURL = normalizeInstanceURL(namedProfile.instance_url);
             } else if (argv.instance) {
               instanceURL = resolveInstanceArg(argv.instance, app.config);
-            } else if (app.isInteractive()) {
+            } else if (canUsePicker(app, argv)) {
               // gh-faithful: interactive terminals always get a picker —
               // existing profiles plus "＋ Add a new instance". Zero profiles
               // goes straight to the setup wizard.
@@ -987,7 +989,9 @@ Examples:
               if (profileNames.length === 0) {
                 throw errUsage('No profiles configured. Run "jsn auth login" first.');
               }
-              if (profileNames.length > 1 && app.isInteractive()) {
+              if (profileNames.length === 1) {
+                name = profileNames[0];
+              } else if (canUsePicker(app, argv)) {
                 const { search } = await import('@inquirer/prompts');
                 const choices = profileNames.map(profileName => ({
                   name: `${profileName} — ${app.config.profiles[profileName].instance_url}`,
@@ -1002,7 +1006,13 @@ Examples:
                 });
                 name = selected;
               } else {
-                name = profileNames[0];
+                // Never silently switch the active profile for a
+                // non-interactive caller: picking one for them is a
+                // config write they did not ask for.
+                throw errUsageHint(
+                  `Which profile? ${profileNames.length} profiles are configured: ${profileNames.join(', ')}`,
+                  'Pass the profile name: jsn auth switch <name>'
+                );
               }
             }
             await setActiveProfile(app.config, name);

package/src/commands/cmdb.js

@@ -8,6 +8,7 @@
 import {
   assertSafeExactMatch,
   buildQuerySuffix,
+  formatCommandList,
   formatRecordForDisplay,
   getStringField,
   interactiveList,
@@ -351,6 +352,23 @@ export function cmdbCmd(wrap) {
   return {
     command: 'cmdb [subcommand]',
     describe: 'Query the Configuration Management Database (CMDB) — CIs and relationship traversal (read-only)',
+    // Parent discovery. Without a handler `jsn cmdb` exited 0 having printed
+    // nothing: a script reads that as success and a human as a hang. The child
+    // list comes from the registry (argv.subcommands), so it cannot drift from
+    // what is registered; the styled view is a side channel that JSON ignores.
+    handler: wrap(async (argv, app) => {
+      const subcommands = argv.subcommands || [];
+      const summary = 'Query the Configuration Management Database (CMDB): CI lookup and relationship traversal. Read-only.';
+      app.ok({
+        command: 'cmdb',
+        subcommands,
+        _formatted: formatCommandList({
+          title: summary,
+          commands: subcommands,
+          footer: 'Run "jsn cmdb <command> --help" for details.',
+        }),
+      }, { summary });
+    }),
     builder: (yargs) => {
       return yargs
         .command({