@jacebenson/jsn 4.3.7-dev.43 → 4.3.7-dev.45

package/package.json

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

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();
@@ -37,16 +41,34 @@ class CommandNode {
    * 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;
     }
-    child.aliases = [...new Set([...child.aliases, ...this.children[index].aliases])];
+    // 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;
   }
@@ -157,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;
     }
@@ -176,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] = {
@@ -199,11 +229,40 @@ 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);

package/src/cli.js

@@ -75,43 +75,28 @@ import { diffCmd } from './commands/diff.js';
 import { graphqlCmd } from './commands/graphql.js';
 
 /**
- * Did the caller explicitly ask for machine output?
+ * The output format the caller asked for, resolved from PARSED argv.
  *
- * Read from the raw argv because parse-time failures happen BEFORE the format
- * middleware can run, so `--json`/`--format=json` had not reached the output
- * controller yet — which is exactly why the structured failure envelope was
- * unreachable for the mistakes scripts and agents hit most (a missing required
- * flag, a bad choice, an unknown command).
- */
-function explicitJsonRequest(args) {
-  return args.some((arg, i) => {
-    if (arg === '--json') return true;
-    if (arg.startsWith('--json=')) return arg !== '--json=false';
-    if (arg === '--format=json') return true;
-    return arg === '--format' && args[i + 1] === 'json';
-  });
-}
-
-/**
- * The output format the caller explicitly asked for, read from the raw 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.
  *
- * Same reason as explicitJsonRequest: the format middleware never runs for a
- * parse-time failure, so an explicit `--format=styled` (human) or
- * `--format=json` (machine) was silently ignored and the failure was rendered
- * by the pipe/TTY default instead of what was asked for.
+ * 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).
  */
-function explicitFormat(args) {
-  for (let i = 0; i < args.length; i += 1) {
-    const arg = args[i];
-    if (arg === '--json') return 'json';
-    if (arg === '--quiet' || arg === '-q') return 'quiet';
-    if (arg === '--styled') return 'styled';
-    if (arg === '--markdown') return 'markdown';
-    if (arg === '--csv') return 'csv';
-    if (arg.startsWith('--format=')) return arg.slice('--format='.length);
-    if (arg === '--format' && args[i + 1]) return args[i + 1];
-  }
-  return '';
+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 : '';
 }
 
 /**
@@ -199,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);
@@ -485,22 +469,30 @@ export function buildCLI() {
     })
     .onParentDiscovery((argv, { path, subcommands }) => {
       // Reached only for a parent command that declares no default handler of
-      // its own (cmdb, platform, 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.
+      // 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.`;
-      (argv.app || app).ok({
-        command: canonical,
-        subcommands,
-        _formatted: formatCommandList({
-          title: `jsn ${canonical}`,
-          commands: subcommands,
-          footer: `Run "jsn ${canonical} <command> --help" for details.`,
-        }),
-      }, { summary });
+      // 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)
@@ -509,6 +501,13 @@ export function buildCLI() {
     .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 hasLoneProfile = raw.some((a, i, arr) => {
           if (a !== '--profile' && a !== '-p') return false;
@@ -529,12 +528,23 @@ export function buildCLI() {
         // 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 (explicitJsonRequest(raw)) {
+        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();
-          app.ok({ commands }, {
-            summary: `${commands.length} registered commands — run "jsn <command> --json" for a command's subcommands.`,
-          });
+          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');
@@ -546,11 +556,7 @@ export function buildCLI() {
       // 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 (explicitJsonRequest(raw)) app.output.setFormat('json');
-      else {
-        const requestedFormat = explicitFormat(raw);
-        if (requestedFormat) app.output.setFormat(requestedFormat);
-      }
+      if (requestedFormat) app.output.setFormat(requestedFormat);
       let hint;
       try {
         const path = cliInstance._findPath(raw).path.map((n) => n.name).join(' ');