@jacebenson/jsn 4.3.7 → 4.3.8-dev.47

package/src/cli-adapter.js

@@ -10,7 +10,11 @@ class CommandNode {
   constructor(definition) {
     this.definition = typeof definition === 'string' ? { command: definition } : definition;
     this.name = commandName(this.definition.command || '');
-    this.aliases = names(this.definition.aliases || this.definition.alias);
+    // A command that lists its canonical name as its own alias publishes one
+    // token twice: the registry then has two entries for it and dispatch can
+    // resolve it through the alias table instead of the command table. An alias
+    // is an ALTERNATE name, so a self-alias is dropped at the source.
+    this.aliases = names(this.definition.aliases || this.definition.alias).filter((alias) => alias !== this.name);
     this.children = [];
     this.options = new Map();
     this.positionals = new Map();
@@ -24,11 +28,56 @@ class CommandNode {
     if (typeof this.definition.builder === 'function') this.definition.builder(this.api());
   }
 
+  /**
+   * Register a child, replacing any existing registration that claims the same
+   * canonical name (or that the new child claims as an alias).
+   *
+   * yargs semantics are last-registration-wins: a command module re-registers a
+   * subcommand to layer a specialized handler over the base one (see
+   * `requests show`). Appending instead of replacing left the base registration
+   * first in the list and reachable by dispatch/help while the duplicate was
+   * invisible to the registry (child counts, inventory, completion).
+   *
+   * Registration order is preserved (the slot is replaced in place) and the
+   * replaced node's aliases are carried over so layered commands keep resolving
+   * through the alias that the base registration published.
+   *
+   * A token must resolve to exactly ONE command. Two registrations can also
+   * collide without sharing a canonical name: an alias that another command
+   * already published (or already claims as its alias) is the same kind of
+   * claim, and registration order decides it — the later registration owns the
+   * token and the earlier one stops advertising it. The earlier command keeps
+   * its canonical name, so nothing becomes unreachable.
+   */
+  register(child) {
+    const index = this.children.findIndex((existing) => existing.name === child.name
+      || existing.aliases.includes(child.name)
+      || child.aliases.includes(existing.name));
+    if (index === -1) {
+      for (const sibling of this.children) {
+        sibling.aliases = sibling.aliases.filter((alias) => !child.aliases.includes(alias));
+      }
+      this.children.push(child);
+      return child;
+    }
+    // Carry the replaced node's aliases over — minus any alias that is now the
+    // replacement's own canonical name, which would advertise the command as
+    // its own alias.
+    child.aliases = [...new Set([...child.aliases, ...this.children[index].aliases])]
+      .filter((alias) => alias !== child.name);
+    for (const sibling of this.children) {
+      if (sibling === this.children[index]) continue;
+      sibling.aliases = sibling.aliases.filter((alias) => !child.aliases.includes(alias));
+    }
+    this.children[index] = child;
+    return child;
+  }
+
   api() {
     const node = this;
     return {
       command(definition, builder, handler) {
-        node.children.push(new CommandNode(typeof definition === 'string' ? { command: definition, builder, handler } : definition));
+        node.register(new CommandNode(typeof definition === 'string' ? { command: definition, builder, handler } : definition));
         return this;
       },
       option(name, config = {}) { node.options.set(name, { ...config, name }); return this; },
@@ -63,10 +112,16 @@ export class LocalCLI {
   option(name, config) { this.root.options.set(name, { ...config, name }); return this; }
   options(config) { for (const [name, value] of Object.entries(config)) this.option(name, value); return this; }
   command(definition, builder, handler) {
-    const node = new CommandNode(typeof definition === 'string' ? { command: definition, builder, handler } : definition);
-    this.root.children.push(node);
+    this.root.register(new CommandNode(typeof definition === 'string' ? { command: definition, builder, handler } : definition));
     return this;
   }
+  /**
+   * Register the fallback used when a parent command (a node with children) is
+   * invoked with no subcommand and declares no handler of its own. Without it
+   * those parents exited 0 having printed nothing, which reads as success to a
+   * script and as a hang to a human.
+   */
+  onParentDiscovery(fn) { this.parentDiscovery = fn; return this; }
   demandCommand(count, message) { this.root.demand = { count, message }; return this; }
   completion(name, _description, handler) { this.completionCommand = name; this.completionHandler = handler; return this; }
   help() { this.helpEnabled = true; return this; }
@@ -124,14 +179,22 @@ export class LocalCLI {
     return options.get(key) || [...options.values()].find((spec) => spec.name === key || names(spec.alias).includes(key))
       || { name: key, type: typeof value === 'boolean' ? 'boolean' : 'string' };
   }
-  _assign(argv, key, value, spec) {
+  /**
+   * Assign one parsed value to argv.
+   *
+   * `validate: false` (tolerant mode, used by parseGlobalOptions) skips the
+   * choice/number checks so a value that will be thrown away anyway cannot
+   * abort a parse whose only purpose is reading the global output flags.
+   */
+  _assign(argv, key, value, spec, opts = {}) {
+    const validate = opts.validate !== false;
     const actual = spec?.name || key;
     const values = spec?.type === 'array' ? (Array.isArray(value) ? value : [value]) : [value];
-    if (spec?.choices && values.some((item) => !spec.choices.includes(item))) {
+    if (validate && spec?.choices && values.some((item) => !spec.choices.includes(item))) {
       this._fail(`Invalid value for --${actual}: ${value}. Choose from: ${spec.choices.join(', ')}`);
       return false;
     }
-    if (spec?.type === 'number' && values.some((item) => item === '' || !Number.isFinite(Number(item)))) {
+    if (validate && spec?.type === 'number' && values.some((item) => item === '' || !Number.isFinite(Number(item)))) {
       this._fail(`Invalid number for --${actual}: ${value}`);
       return false;
     }
@@ -143,7 +206,7 @@ export class LocalCLI {
     argv[camel(actual)] = argv[actual];
     for (const alias of names(spec?.alias)) argv[alias] = argv[actual];
   }
-  _parseOptions(args, path) {
+  _parseOptions(args, path, opts = {}) {
     const options = this._optionConfig(path);
     const defs = {};
     for (const [key, spec] of options) defs[key] = {
@@ -166,15 +229,92 @@ export class LocalCLI {
     const argv = { _: path.map((n) => n.name) };
     for (const [key, value] of Object.entries(parsed.values)) {
       const spec = this._specFor(options, key, value);
-      if (this._assign(argv, key, value, spec) === false) return null;
+      if (this._assign(argv, key, value, spec, opts) === false) return null;
     }
-    for (const [key, spec] of options) if (argv[spec.name] === undefined && spec.default !== undefined) this._assign(argv, key, spec.default, spec);
+    for (const [key, spec] of options) if (argv[spec.name] === undefined && spec.default !== undefined) this._assign(argv, key, spec.default, spec, opts);
     return { values: argv, positionals: parsed.positionals };
   }
+
+  /**
+   * Resolve the global options from raw tokens WITHOUT dispatching a command and
+   * without failing.
+   *
+   * The format middleware never runs when parsing fails, so the parse-time
+   * failure renderer has to know the format the caller asked for. Rather than
+   * re-scanning argv with a second, approximate tokenizer (any `--json`
+   * anywhere, first `--format` wins, no option termination, no value
+   * consumption, no `--no-` negation), it asks the SAME parser the successful
+   * path uses. Tolerant mode keeps a value error (`--format xml`, the very
+   * failure being rendered) from aborting the resolution.
+   *
+   * Returns null when the tokens cannot be parsed at all — the caller then
+   * falls back to the pipe/TTY default, exactly as it did before.
+   */
+  parseGlobalOptions(args) {
+    const saved = this.failHandler;
+    this.failHandler = null; // errors here are not the failure being reported
+    try {
+      const { path, commandArgs } = this._findPath(args);
+      const parsed = this._parseOptions(commandArgs, path, { validate: false });
+      return parsed ? parsed.values : null;
+    } catch {
+      return null;
+    } finally {
+      this.failHandler = saved;
+    }
+  }
   _fail(message, error) {
     if (this.failHandler) return this.failHandler(message, error);
     throw error || new Error(message);
   }
+  /**
+   * Describe the registered command surface: root commands (canonical name,
+   * aliases, describe, child names) and the global option declarations.
+   *
+   * This is the single source both the grouped root help and the machine
+   * discovery output are generated from, so neither can drift away from the
+   * commands that actually exist. Builders run here (idempotently) because a
+   * parent's children are only registered when its builder is invoked.
+   */
+  commandRegistry() {
+    const visible = (node) => node.name !== this.completionCommand;
+    const serialize = (node) => {
+      node.build();
+      return {
+        name: node.name,
+        command: node.definition.command || node.name,
+        aliases: [...node.aliases],
+        description: node.definition.describe || '',
+        subcommands: node.children.filter(visible).map((child) => child.name),
+      };
+    };
+    return {
+      commands: this.root.children.filter(visible).map(serialize),
+      options: [...this.root.options.values()].map((spec) => ({
+        name: spec.name,
+        alias: names(spec.alias),
+        description: spec.description || spec.describe || '',
+        choices: spec.choices || [],
+        type: spec.type || 'boolean',
+      })),
+    };
+  }
+
+  /** Structured child signatures for a parent node, built on demand. */
+  subcommandsOf(node) {
+    return node.children
+      .filter((child) => child.name !== this.completionCommand)
+      .map((child) => {
+        child.build();
+        return {
+          name: child.name,
+          command: child.definition.command || child.name,
+          aliases: [...child.aliases],
+          description: child.definition.describe || '',
+        };
+      });
+  }
+
   _help(node, path = []) {
     const lines = [node.usageText || `Usage: ${this.script} ${path.join(' ') || '<command>'}`];
     if (node.definition.describe) lines.push(`\n${node.definition.describe}`);
@@ -232,6 +372,11 @@ export class LocalCLI {
     const parsed = this._parseOptions(commandArgs, path);
     if (!parsed) return;
     const argv = parsed.values;
+    // A parent command's own children are registry-derived, so a default
+    // handler can list exactly what is registered instead of repeating a
+    // hand-written list that drifts (see the records parent, which advertised
+    // an `inspect` description the registration disagreed with).
+    if (node.children.length) argv.subcommands = this.subcommandsOf(node);
     const specs = [...this._optionConfig(path).values()];
     const positions = positionSpec(node.definition.command || '').map((position) => ({
       ...position, ...node.positionals.get(position.name), name: position.name,
@@ -242,7 +387,13 @@ export class LocalCLI {
     for (const middleware of this.middlewares) await middleware(argv);
     for (const commandNode of path) for (const middleware of commandNode.middlewares) await middleware(argv);
     if (node.definition.handler) await node.definition.handler(argv);
-    else if (node.demand?.count && !path.length) return this._fail(node.demand.message);
+    // A parent with no handler of its own used to fall through and exit 0
+    // with no output — indistinguishable from a command that ran and found
+    // nothing. The registered discovery hook (cli.js) prints the child
+    // surface instead: a JSON envelope in machine mode, a list for humans.
+    else if (path.length && argv.subcommands?.length && this.parentDiscovery) {
+      await this.parentDiscovery(argv, { path: path.map((n) => n.name), subcommands: argv.subcommands });
+    } else if (node.demand?.count && !path.length) return this._fail(node.demand.message);
   }
 }
 

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