@jacebenson/jsn 4.3.7 → 4.3.8

package/README.md

@@ -31,6 +31,19 @@ npm install -g @jacebenson/jsn
 
 **Note:** git installs build `better-sqlite3` (docs search) from source, so the machine needs build tools (Python, make, a C++ compiler).
 
+## Direct MID installation
+
+```sh
+jsn midservers add --install-method direct --name worker1
+```
+
+Official x86-64 ZIPs for Linux and Windows, selected from the instance's
+`mid.version`. Credentials are prompted and validated before installation.
+Linux supports a user-owned background runtime. Windows currently prepares
+private files and offers a foreground console, not native service registration.
+See [direct MID installation](docs/mid-direct-install.md) for security boundaries,
+lifecycle commands and the untested Windows host phases. Docker remains available.
+
 ## Quick Start
 
 ```bash
@@ -59,6 +72,7 @@ jsn flows executions --since "2026-08-25 00:00:00" --until "2026-08-26 00:00:00"
 jsn flows executions --summary                 # Server totals + sampled duration metrics by flow
 jsn flows executions --limit 100               # Inspect more rows from the matching population
 jsn flows executions --record <sys_id>        # Executions for one source record
+jsn flows create --data-file flow.manifest.json # Create a draft record-triggered flow
 jsn rules list --query "collection=incident"
 jsn updatesets set "My Feature"
 
@@ -72,10 +86,19 @@ jsn records bulk --table incident --query "priority=1" --set '{"state":"3"}'  #
 jsn records get --table incident --sys-id 8a1234abcd5678 --attachments        # record + its files
 jsn records list --table incident --limit 10 --csv                            # output CSV
 
+# Read-only cross-profile record diff
+jsn diff record --table incident --sys-id <sys_id> --profile-a dev --profile-b prod
+jsn diff record --table incident --sys-id <sys_id> --profile-a dev --profile-b prod --ignore state
+jsn diff record --table incident --sys-id <sys_id> --profile-a dev --profile-b prod --no-ignore
+
 # Script execution
 jsn eval "gs.info('Hello World')"
 cat script.js | jsn eval --stdin          # pipe a script in (no shell escaping)
 
+# Now GraphQL (documents may contain mutations; read-only profiles are blocked)
+jsn graphql --query '{ GlideRecord_Query { incident(pagination: {limit: 2}) { _results { number { value } } } } }'
+cat incident.graphql | jsn graphql --stdin --variables '{"limit":2}'
+
 # Saved query snippets (stored locally, run against the active profile)
 jsn snippets save open-inc --table incident --query "active=true"
 jsn snippets run open-inc
@@ -84,8 +107,203 @@ jsn snippets run open-inc
 jsn logs follow --level error --tail 10
 ```
 
+### Flow Designer actions
+
+`actions` and `action` are the same command. `list`, `show`, and explicit
+`delete` remain available. In a human terminal, omit the target to open a
+searchable picker. Create and edit guide you through provider schemas and save
+full Process Flow definitions, not ordinary table-field updates.
+
+```bash
+jsn actions create                 # Guided scope, name, schemas, inputs and script
+jsn actions edit                   # Pick an action, edit its saved definition
+jsn actions definition             # Pick and inspect a complete definition
+jsn actions test --wait            # Pick an action, supply saved-schema inputs, confirm
+jsn actions step-types             # Pick the exact transaction scope
+```
+
+Script inputs offer a file path or your `$VISUAL`/`$EDITOR`. New script steps can
+declare outputs and map them to action outputs. Variable declarations reuse
+provider schema templates and receive fresh UI identities. Unknown nested
+schema fields are retained. Unsupported input types stop with instructions to
+use `--data-file`; JSN does not silently omit them or invent schema defaults.
+Creation waits for an explicit final confirmation before allocating a parent.
+It saves a draft only and never publishes or runs it automatically.
+
+For automation, keep using explicit identifiers and full JSON:
+
+```bash
+jsn actions step-types --scope <scope_sys_id> --get data > step-types.json
+jsn actions create --scope <scope_sys_id> --data-file new-action.json --json
+jsn actions definition <action_sys_id> --get data > action.json
+# Edit action.json, retaining its ID, scope, lifecycle fields and all arrays.
+jsn actions update <action_sys_id> --data-file action.json --json
+jsn action edit <action_sys_id> --data-file action.json --json  # same operation
+jsn actions test <action_sys_id> --force --output-map '{"response":"hello"}' --wait --timeout 60 --json
+jsn actions test <action_sys_id> --force --data-file action.json --output-map '{"response":"hello"}' --wait --get data.outputs.response.value
+jsn actions delete <action_sys_id> --force  # explicit cleanup, never automatic
+```
+
+Existing targets infer their exact transaction scope from the action record.
+An explicit `--scope` must match that record byte-for-byte and exist in
+`sys_scope`. For Global, use the literal sys_id `global`.
+
+This **illustrative create document** shows an input/script/output mapping.
+Replace `<SCRIPT_STEP_TYPE_SYS_ID>` with the target's `step-types` result.
+Start from that step type's full input/output schemas, preserving runtime
+settings, status outputs and any other required fields. The shortened example
+is not a captured or instance-verified template. New steps/variables need their
+own identifiers; do not clone another action's record IDs. Leave new steps'
+`step_id` and `action` blank or omitted. Create binds their `action` to the newly
+allocated parent; persisted step IDs or parent bindings are rejected before creation.
+
+```json
+{
+  "name": "Echo response",
+  "description": "Return the supplied response",
+  "internal_name": "echo_response",
+  "inputs": [{"name": "response", "label": "Response", "type": "string", "mandatory": true}],
+  "outputs": [{"name": "response", "label": "Response", "type": "string", "value": "{{step[11111111-2222-4333-8444-555555555555].response}}"}],
+  "steps": [{
+    "cid": "11111111-2222-4333-8444-555555555555",
+    "step_type": "SCRIPT",
+    "step_type_id": "<SCRIPT_STEP_TYPE_SYS_ID>",
+    "label": "Echo script",
+    "order": 1,
+    "inputs": [
+      {"name": "required_run_time", "type": "choice", "value": "instance"},
+      {"name": "script", "type": "script", "value": "(function execute(inputs, outputs) { outputs.response = inputs.response; })(inputs, outputs);"}
+    ],
+    "outputs": [],
+    "extended_inputs": [{"name": "response", "type": "string", "value": "{{inputs.response}}", "extended": true}],
+    "extended_outputs": [{"name": "response", "type": "string", "extended": true}]
+  }]
+}
+```
+
+Create first inserts the parent in `sys_hub_action_type_definition`, reads that
+parent's own Process Flow defaults, then saves the inputs, outputs and nonempty
+steps with the internal `/api/now/processflow/action/action_types/{id}` PUT.
+It retains fresh lifecycle/status metadata instead of copying source snapshot
+or status IDs. A subsequent definition GET plus `/step_instances` GET verifies
+scripts, mappings and schemas. Update requires a complete document from
+`definition`, including target-owned lifecycle fields. Omitted fields are
+rejected before mutation. A PUT timeout triggers readback, not another PUT;
+`persisted_after_timeout` means persistence was verified, not that HTTP success
+was received. Failed creation reports the parent ID and leaves cleanup to you.
+
+Test sends `action`, `outputMap`, `runOnThread` and `tracingEnabled` to `/test`.
+Despite its wire name, `--output-map` supplies **action inputs**. Without
+`--wait`, success means dispatch only, with `status: dispatched` and no outputs.
+With `--wait`, JSN requires a `COMPLETE` context, blank `error_message`, and each
+declared user output's actual value from `sys_flow_runtime_value`. Output entries
+have `value`, `displayValue` and `hasValue`; false, zero and empty strings count.
+Failures, denied/missing outputs and timeouts exit nonzero. The wait budget
+starts after dispatch, defaults to 60 seconds, and is capped at 3600 seconds.
+Timeout does not cancel the server execution. Draft actions can be tested without
+publication. Testing runs their scripts and can have side effects. It requires
+interactive confirmation or `--force`, unless the profile explicitly skips
+confirmations. Read-only profiles block create/update/delete/test. No publish
+or snapshot command is added.
+These internal endpoints and runtime-table permissions can vary by instance.
+
 ### Flow execution fields
 
+### Flow Designer terminal workflows
+
+```bash
+jsn flows create         # Guided record trigger and published action inputs
+jsn flows edit           # Pick an inactive Draft, edit condition or existing inputs
+jsn flows show           # Pick a flow to inspect
+jsn flows status         # Pick a flow to diagnose
+jsn flows test           # Pick flow and a record from its actual trigger table, confirm
+jsn flows publish        # Pick a flow, explicitly confirm activation
+# Automation must explicitly confirm publication too:
+jsn flows publish <flow_sys_id> --force --json
+```
+
+Wizards and omitted-target pickers require both a prompt-capable terminal and
+`auto` output. `--json`, explicit formats, `--get`, `--data`, `--data-file`,
+`--output-map`, pipes, `CI`, `NONINTERACTIVE` and `JSN_NO_PROMPTS=1` never open a
+wizard. In those modes provide identifiers and required scope/record/data
+explicitly. Tests, publish and deletion require `--force` or the profile's
+existing explicit skip-confirmations setting when prompting is unavailable.
+Read-only profiles still block mutations before authentication or prompting.
+Press Escape in record pickers or Ctrl+C in any wizard to cancel. Refusing a
+final confirmation leaves the instance untouched.
+
+Existing action/flow scopes come from saved raw identifiers. New scopes offer
+the active application preference if available, then a searchable scope picker.
+No scope name is guessed. Input pills are passed through unchanged.
+
+Flow edits are limited to the existing manifest contract. They do not rename
+flows, add/remove steps, implement Flow Logic, subflows, variables or error
+handling. Flow deletion remains unsupported. Action deletion retains its
+existing explicit parent-record cleanup and absence readback, not a new native
+builder deletion lifecycle. See [command coverage and local proof](docs/flow-designer-interactive.md).
+
+### Flow creation manifest
+
+`jsn flows create` accepts `--data-file` or inline `--data`, or guides human
+terminal users without those options. The supported slice
+supports one `record_create_or_update` trigger and published Action types whose
+input schemas are available from the instance. JSN resolves action metadata,
+defaults, and typed inputs from ServiceNow; callers do not provide GraphQL or
+editor-generated identifiers.
+
+```json
+{
+  "name": "JSN-STUDY-ticket-log",
+  "description": "Log JSN study tickets",
+  "scope": "<SCOPE_SYS_ID>",
+  "trigger": {
+    "type": "record_create_or_update",
+    "table": "ticket",
+    "condition": "short_descriptionSTARTSWITHJSN-STUDY-"
+  },
+  "actions": [
+    { "type": "Log", "inputs": { "log_level": "info", "log_message": "Ticket received" } }
+  ]
+}
+```
+
+`scope` is required; JSN never defaults it to a tenant-specific or captured
+scope. The record-trigger condition currently accepts one simple encoded-query
+predicate (`fieldSTARTSWITHvalue`, `field=value`, `fieldLIKEvalue`, and the
+equivalent single-predicate operators). Compound `^`/`^OR` expressions are
+rejected until their predicate AST mapping is proven against the instance.
+
+Creation leaves the flow in Draft and inactive, then creates and reads back an
+Autosave version. `flows publish` remains a separate lifecycle operation: it
+reads the saved ProcessFlow definition, POSTs `/snapshot`, creates an
+`Activate/Publish` version, reads version history, and verifies `active=true`.
+Do not use it in a dry-run: publishing activates the flow.
+
+`jsn flows test <identifier> --record <sys_id>` is also a mutating operation.
+It requires confirmation (or `--force`), reads the saved definition, verifies
+that the supplied record exists in the record-trigger table, and POSTs the full
+definition to the ProcessFlow test endpoint. A response with only a context ID
+is reported as accepted, not completed. Test runs execute actions and can have
+side effects; this slice does not execute test flows during development.
+
+Flow Logic, subflows, flow-variable lifecycle, and error handling are deferred
+and rejected by this slice rather than silently ignored.
+
+`jsn flows update <identifier> --data-file update.json` updates supported fields
+of existing inactive Draft flows. The manifest may contain only `trigger` (with
+`table` and/or `condition`) and `actions`. Each action selects one saved instance
+by its one-based `order` and reusable action `type` (name or sys_id). Its `inputs`
+object may change only inputs already present in that saved Action. The CLI reads
+the saved component identities itself; manifests never carry UI UUIDs. Omitted
+trigger fields, Action inputs, metadata, and other flow components are preserved.
+Names must resolve to exactly one flow, and the protected `jace-test-flow` is
+rejected. Update sends the captured GraphQL `triggerInstances.update` and/or
+`actions.update` shapes, reads the full ProcessFlow definition back, creates an
+Autosave version, and reports update-set captures. It never publishes or
+activates the flow. Unsupported Flow Logic, subflows, variables, error handling,
+new Action inputs, ambiguous selectors, active flows, and non-Draft flows are
+rejected before mutation.
+
 `jsn flows executions` reads `sys_flow_context` and returns both the raw row and a normalized `execution` object. JSN discovers the runtime columns from `sys_dictionary` first, then uses these mappings:
 
 - `started`: `started`, `start_time`, `started_at`, then `sys_created_on`
@@ -110,10 +328,31 @@ Run `jsn` for the full grouped list. Commands are organized by ServiceNow domain
 
 **User Experience** — `forms`, `lists`, `clientscripts`, `uipolicies`, `uiactions`
 
-**Data** — `records` (list/get/create/update/delete/count/bulk/attachments), `tables`, `columns`, `includes`, `import`, `logs` (list/show/follow), `snippets` (save/run), `users`, `groups`
+**Data** — `records` (list/get/create/update/delete/count/bulk/attachments), `diff record` (cross-profile read-only comparison), `tables`, `columns`, `includes`, `import`, `logs` (list/show/follow), `snippets` (save/run), `users`, `groups`
+
+**Platform** — `platform health` (cluster records) and `platform stats` (bounded, read-only `/xmlstats.do` summary; allowlisted metrics only)
 
 Every command supports `--json`, `--query`, and `--help`.
 
+For multiline script fields, `--data-file` parses the file as UTF-8 JSON and
+passes the resulting values through unchanged. On Windows PowerShell, generate
+the payload as JSON text and inspect it before invoking JSN, for example:
+
+```powershell
+$script = [string](Get-Content -Path .\Example.script.js -Raw)
+$payload = @{ script = $script; description = 'Example' } |
+  ConvertTo-Json -Depth 5 -Compress
+Set-Content -Path .\Example.update.json -Value $payload -Encoding UTF8
+Get-Content .\Example.update.json -Raw | ConvertFrom-Json | Select-Object -ExpandProperty script
+jsn includes update Example --data-file .\Example.update.json --json
+```
+
+`JSON.parse` preserves a JSON string as a JavaScript string, and the SDK
+serializes update payloads with `JSON.stringify`. If the file already contains
+a `{value=...}` or FileSystem-provider representation, that text is external
+to JSN and must be corrected before the update. Use a read-back command or
+`records update --strict` where applicable to verify persisted fields.
+
 ## Instances
 
 Switch between instances without re-authenticating.
@@ -162,6 +401,12 @@ export SERVICENOW_OAUTH_TOKEN="***"
 jsn incidents list
 ```
 
+For the credential identity, auth-method, diagnostics, migration, and concurrency contract, see [`docs/AUTH_LIFECYCLE.md`](docs/AUTH_LIFECYCLE.md).
+
+GraphQL uses ServiceNow's `/api/now/graphql` endpoint and sends `{query, variables}` through the authenticated SDK transport. The command preserves GraphQL `data` and `errors`; introspection and available namespaces depend on the target instance.
+
+`jsn platform stats` uses a fixed `GET /xmlstats.do` request. It never accepts a processor path, query parameters, or request body, and it does not emit raw XML, cookies, credentials, or full node identifiers. Oversized, HTML/login, permission, unsupported, timeout, and malformed responses are reported with bounded collector statuses; missing metrics remain unavailable rather than being reported as zero.
+
 ## Local data
 
 JSN stores durable local data under `~/.jsn/`. Documentation lives in

package/package.json

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

package/src/app.js

@@ -14,6 +14,7 @@ import { saveConfig } from './config.js';
 import { resolveSession, applySession, contextFromSession, requireSessionInstance } from './session.js';
 import { getCurrentUser, getCurrentApplication, getCurrentUpdateSet } from './context.js';
 import { errUsage, errAuth } from './errors.js';
+import { canPrompt } from './helpers.js';
 import { isMutationCommand } from './mutations.js';
 import process from 'node:process';
 
@@ -190,8 +191,14 @@ export class App {
     this.output.err(error);
   }
 
+  /**
+   * True only when a human can actually answer a prompt. Delegates to
+   * canPrompt() so the check is "both stdio descriptors are TTYs AND no
+   * agent/CI/opt-out marker is set" — a PTY allocated for an agent
+   * (stdout.isTTY true, JSN_NO_PROMPTS/CI set) is NOT interactive.
+   */
   isInteractive() {
-    return process.stdout.isTTY === true;
+    return canPrompt();
   }
 
   requireInstance() {

package/src/auth.js

@@ -41,30 +41,32 @@ function credKey(instance, username) {
 
 // ─── PKCE state persistence (shared with Go version) ───
 
-function pkceStatePath(instance) {
+function pkceStatePath(instance, username) {
   const dir = path.join(globalConfigDir(), 'pkce');
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  const filename = sanitizeKeyPart(instance) + '.json';
+  // A known profile identity gets its own pending-login slot. Keep the bare
+  // instance slot for legacy/no-profile flows, where no identity exists yet.
+  const filename = credKey(instance, username) + '.json';
   return path.join(dir, filename);
 }
 
-function savePKCEState(instance, pkce) {
-  const filePath = pkceStatePath(instance);
+function savePKCEState(instance, pkce, username) {
+  const filePath = pkceStatePath(instance, username);
   fs.writeFileSync(filePath, JSON.stringify(pkce, null, 2), { mode: 0o600 });
 }
 
-function loadPKCEState(instance) {
+function loadPKCEState(instance, username) {
   try {
-    const data = fs.readFileSync(pkceStatePath(instance), 'utf-8');
+    const data = fs.readFileSync(pkceStatePath(instance, username), 'utf-8');
     return JSON.parse(data);
   } catch {
     return null;
   }
 }
 
-function removePKCEState(instance) {
+function removePKCEState(instance, username) {
   try {
-    fs.unlinkSync(pkceStatePath(instance));
+    fs.unlinkSync(pkceStatePath(instance, username));
   } catch {
     // ignore
   }
@@ -746,7 +748,7 @@ export class AuthManager {
     instanceURL = normalizeInstanceURL(instanceURL);
     const clientID = getOAuthClientID();
     const pkce = generatePKCE();
-    savePKCEState(instanceURL, pkce);
+    savePKCEState(instanceURL, pkce, username);
     const url = buildAuthURL(instanceURL, clientID, pkce);
     if (waitFile) {
       console.log(url);
@@ -766,7 +768,7 @@ export class AuthManager {
         const code = fs.readFileSync(filePath, 'utf-8').trim();
         if (code) {
           console.log(`\nAuthorization code found in ${filePath}`);
-          removePKCEState(instanceURL);
+          removePKCEState(instanceURL, username);
           const newCreds = await this.exchangeCode(instanceURL, clientID, code, pkce);
           this.saveCredentials(instanceURL, newCreds, username || newCreds.username);
           console.log('Token exchange successful!\n');
@@ -838,7 +840,7 @@ export class AuthManager {
   async loginWithCode(instanceURL, code, username = this._activeUsername()) {
     instanceURL = normalizeInstanceURL(instanceURL);
     const clientID = getOAuthClientID();
-    const pkce = loadPKCEState(instanceURL);
+    const pkce = loadPKCEState(instanceURL, username);
     if (!pkce) {
       throw errAuth(
         `No pending login session for ${instanceURL}.\n\n` +
@@ -848,7 +850,7 @@ export class AuthManager {
         `  jsn auth login ${instanceURL} --code CODE`
       );
     }
-    removePKCEState(instanceURL);
+    removePKCEState(instanceURL, username);
 
     const newCreds = await this.exchangeCode(instanceURL, clientID, code, pkce);
     this.saveCredentials(instanceURL, newCreds, username || newCreds.username);

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