@north-light/api 0.3.580 → 0.3.587

package/dist/core/command.js

@@ -0,0 +1,848 @@
+// Registration kit for the agent-first crtr CLI.
+// Hand-rolled path walker — no commander. Rationale: the spec requires flags
+// and positional args on input (argv model). Commander's abstraction is more
+// complexity than a plain array walk for this interface contract.
+// A plain array walk + a small flag parser is ~120 lines and has no surprising
+// edge cases.
+import { renderRoot, renderBranch, renderLeafArgv, withAsyncHelpState, collapseWideChildren, rootPromotedChildren } from './help.js';
+import { beginPreview, publishPreviewResult, readStdinRaw, peekStdinRaw, emit, handle, setJsonOutput, isJsonOutput } from './io.js';
+import { renderResult } from './render.js';
+import { CrtrError } from './errors.js';
+import { validateValue } from '../api/command-manifest/result.js';
+import { isManifestStaleError } from './manifest-stale.js';
+import { operationIdContext } from './events/operation-id.js';
+import { ExitCode } from '../types.js';
+import { envNodeId, providerProjectionOverBrokerRelay } from '../shared/env.js';
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { constants as osConstants } from 'node:os';
+import { resolve } from 'node:path';
+// Factory functions
+function freezeCommandMetadata(value) {
+    if (value === null || typeof value !== 'object' || Object.isFrozen(value))
+        return value;
+    for (const child of Object.values(value))
+        freezeCommandMetadata(child);
+    return Object.freeze(value);
+}
+export function defineLeaf(opts) {
+    const help = freezeCommandMetadata(opts.help);
+    const { helpState } = opts;
+    if (helpState !== undefined && opts.effectiveHelp !== undefined)
+        throw new Error(`leaf ${opts.name} declares both helpState and effectiveHelp`);
+    return Object.freeze({
+        kind: 'leaf',
+        name: opts.name,
+        description: opts.description,
+        whenToUse: opts.whenToUse,
+        tier: opts.tier,
+        help,
+        effectiveHelp: opts.effectiveHelp ?? (helpState === undefined ? undefined : (focusedFlag) => withAsyncHelpState(help, helpState, focusedFlag)),
+        slash: opts.slash === undefined ? undefined : freezeCommandMetadata(opts.slash),
+        hookEligible: opts.hookEligible,
+        plugin: opts.plugin,
+        machineSelector: opts.machineSelector,
+        run: opts.run,
+        render: opts.render,
+        preview: opts.preview,
+        stdoutExact: opts.stdoutExact,
+    });
+}
+/** The tier a parent lists a node under: a branch whose children are all hidden is hidden too, though it stays callable by exact path. */
+function effectiveTier(def) {
+    if (def.kind === 'branch' && def.children.length > 0 && visibleSubCount(def) === 0)
+        return 'hidden';
+    return def.tier ?? 'normal';
+}
+/** Number of a node's own non-hidden subcommands (direct children). Leaves and
+ *  childless branches return 0. */
+function visibleSubCount(def) {
+    if (def.kind !== 'branch')
+        return 0;
+    return (def.help.listing ?? []).filter((c) => c.tier !== 'hidden').length;
+}
+export function defineBranch(opts) {
+    // A passthrough branch must be childless: walk() only stops at the deepest
+    // matched node, so a passthrough branch with children would let some
+    // invocations descend into a child (tree dispatch) while others hit the
+    // passthrough interception — silently inconsistent transparency. Fail loudly
+    // at construction instead of letting that split happen at runtime.
+    if (opts.passthrough !== undefined && opts.children.length > 0) {
+        throw new Error(`defineBranch("${opts.name}"): a passthrough branch must declare no children (found ${opts.children.length})`);
+    }
+    // Assemble the parent-level listing straight from the child defs — each node
+    // owns its own description/whenToUse/tier, so the parent copies nothing
+    // (principle 16). Bottom-up construction guarantees a child branch's listing
+    // is already computed, so subCount is available here.
+    opts.help.listing = opts.children.map((c) => {
+        const subCount = visibleSubCount(c);
+        return {
+            name: c.name,
+            description: c.description ?? '',
+            whenToUse: c.whenToUse ?? '',
+            tier: effectiveTier(c),
+            kind: c.kind,
+            ...(c.plugin !== undefined ? { plugin: c.plugin } : {}),
+            ...(subCount > 0 ? { subCount } : {}),
+        };
+    });
+    return {
+        kind: 'branch',
+        name: opts.name,
+        description: opts.description,
+        whenToUse: opts.whenToUse,
+        tier: opts.tier,
+        help: opts.help,
+        effectiveHelp: opts.effectiveHelp,
+        rootEntry: opts.rootEntry,
+        extensible: opts.extensible,
+        plugin: opts.plugin,
+        slash: opts.slash,
+        passthrough: opts.passthrough,
+        refusal: opts.refusal,
+        children: opts.children,
+    };
+}
+/** Walk the whole tree and collect every node's SlashSpec (depth-first). Used
+ *  by the bootstrap to discover which commands opted into slash exposure. */
+export function collectSlashSpecs(root) {
+    const out = [];
+    const visit = (node) => {
+        if (node.slash !== undefined)
+            out.push(node.slash);
+        if (node.kind === 'branch')
+            for (const c of node.children)
+                visit(c);
+    };
+    for (const s of root.subtrees)
+        visit(s);
+    return out;
+}
+/** Assemble root -h from the subtrees themselves. Root owns only the tagline
+ *  and globals; every subtree's concept line, selection rubric, and dynamic
+ *  block come from its own RootEntry. A subtree without a rootEntry does not
+ *  appear in root -h — declaring the parent-level representation is how a
+ *  subtree opts into being listed. */
+export function defineRoot(opts) {
+    // Each listed subtree becomes one <name> block at root, assembled straight
+    // from its RootEntry. Root composes nothing and hardcodes nothing: add a
+    // subtree with a rootEntry and it surfaces; its concept, rubric, state tag,
+    // and dynamic block all travel with it.
+    const commands = opts.subtrees
+        .filter((s) => s.rootEntry !== undefined && effectiveTier(s) !== 'hidden')
+        .map((s) => {
+        // Promote this subtree's common/important children into root, and count
+        // how many other (non-hidden) direct subcommands stay behind `<name> -h`.
+        const visible = (s.help.listing ?? []).filter((c) => c.tier !== 'hidden');
+        const promoted = rootPromotedChildren(visible)
+            .map((c) => ({
+            path: `${s.name} ${c.name}`,
+            // important carries its shortform desc; common shows the bare path.
+            desc: c.tier === 'important' ? c.description : undefined,
+        }));
+        return {
+            name: s.name,
+            concept: s.rootEntry.concept,
+            desc: s.rootEntry.desc,
+            useWhen: s.rootEntry.useWhen,
+            dynamicState: s.rootEntry.dynamicState,
+            subcommands: promoted.length > 0 ? promoted : undefined,
+            otherSubcommandCount: visible.length - promoted.length,
+        };
+    });
+    const help = {
+        tagline: opts.tagline,
+        commands,
+        globals: opts.globals,
+    };
+    return { kind: 'root', help, subtrees: opts.subtrees };
+}
+/** Validate and return child names for an unknown-path error. */
+function childNames(node) {
+    if (node.kind === 'root')
+        return node.subtrees.filter((s) => effectiveTier(s) !== 'hidden').map((s) => s.name);
+    if (node.kind === 'branch') {
+        const { listed, unlisted } = collapseWideChildren(node.children.filter((c) => effectiveTier(c) !== 'hidden'));
+        return [...listed.map((c) => c.name), ...(unlisted > 0 ? [`(and ${unlisted} more)`] : [])];
+    }
+    return [];
+}
+/** Walk argv tokens to the deepest matched node.
+ *  Returns { node, path, remaining } where path is the sequence of matched node
+ *  names from root (excluding root itself) and remaining are unconsumed tokens.
+ *  -h / --help tokens are NOT consumed here — the caller checks for them. */
+export function walk(root, tokens) {
+    let current = root;
+    const path = [];
+    let i = 0;
+    while (i < tokens.length) {
+        const token = tokens[i];
+        // Stop consuming on -h / --help — leave them for caller to detect
+        if (token === '-h' || token === '--help')
+            break;
+        if (current.kind === 'root') {
+            const nextNode = current.subtrees.find((s) => s.name === token);
+            if (nextNode === undefined)
+                break;
+            current = nextNode;
+            path.push(nextNode.name);
+            i++;
+        }
+        else if (current.kind === 'branch') {
+            const nextNode = current.children.find((c) => c.name === token);
+            if (nextNode === undefined)
+                break;
+            current = nextNode;
+            path.push(nextNode.name);
+            i++;
+        }
+        else {
+            // leaf — cannot descend further
+            break;
+        }
+    }
+    return { node: current, path, remaining: tokens.slice(i) };
+}
+export function renderNode(node) {
+    if (node.kind === 'root')
+        return renderRoot(node.help);
+    if (node.kind === 'branch')
+        return renderBranch(node.help);
+    return renderLeafArgv(node.help);
+}
+/** Render effective Effects for a hook-eligible core leaf, then append any
+ *  commands.json helpAddenda beneath the ordinary contract. Focused parameter
+ *  help returns only the leaf-owned parameter view, because the caller already
+ *  read the ordinary contract and addenda before following its road sign. Both
+ *  plugin lookups read stored manifest bytes only. Addenda validation receives
+ *  the install gate's exact reserved core names and full core path set, so a
+ *  manifest rejected at ingress contributes nothing here either. */
+async function renderNodeWithAddenda(node, path, focusedFlag) {
+    if (focusedFlag !== undefined && node.kind === 'leaf') {
+        return renderLeafArgv(node.effectiveHelp !== undefined ? await node.effectiveHelp(focusedFlag) : node.help, focusedFlag);
+    }
+    const body = node.kind === 'leaf' && node.effectiveHelp !== undefined
+        ? renderLeafArgv(await node.effectiveHelp())
+        : node.kind === 'branch' && node.effectiveHelp !== undefined
+            ? renderBranch(await node.effectiveHelp())
+            : renderNode(node);
+    if (path.length === 0)
+        return body;
+    const { hasEffectiveCommandPlugins } = await import('./command-plugins/presence.js');
+    if (!hasEffectiveCommandPlugins())
+        return body;
+    const [{ collectHelpAddenda }, { SUBTREE_NAMES, coreCommandPathsCovering, extensibleCoreBranches }] = await Promise.all([
+        import('./command-plugins/help-addenda.js'),
+        import('../build-root.js'),
+    ]);
+    const addenda = await collectHelpAddenda(path.join(' '), {
+        reservedCoreNames: new Set(SUBTREE_NAMES),
+        coreCommandPaths: coreCommandPathsCovering,
+        extensibleCoreBranches,
+    });
+    return body + addenda.map((a) => `\n\n<plugin-help plugin="${a.plugin}">\n${a.text}\n</plugin-help>`).join('');
+}
+function helpRequested(remaining) {
+    return remaining.some((t) => t === '-h' || t === '--help');
+}
+/** Resolve the canonical focused-help form `crtr <leaf> --<flag> -h`.
+ *  Only flags that explicitly own a focusedHelp contract select that view;
+ *  every other historical help invocation renders ordinary leaf help. */
+function focusedHelpFlag(node, remaining) {
+    if (node.kind !== 'leaf' || remaining.length !== 2)
+        return undefined;
+    const [flagToken, helpToken] = remaining;
+    if ((helpToken !== '-h' && helpToken !== '--help')
+        || !flagToken.startsWith('--')
+        || flagToken.includes('='))
+        return undefined;
+    const name = flagToken.slice(2);
+    const flag = (node.help.params ?? []).find((param) => param.kind === 'flag' && param.name === name);
+    return flag?.focusedHelp !== undefined ? name : undefined;
+}
+/** Recover the RAW argv slice after a matched passthrough branch's path,
+ *  unaffected by the `--json`-stripping done to build `tokens`. `path` is a
+ *  prefix of non-`--json` tokens in order, so walking `rawTokens` while
+ *  skipping `--json` occurrences until `path` is fully matched lands the
+ *  cursor exactly where the branch's own args begin — including a literal
+ *  `--json` the external binary itself accepts. */
+function rawArgsAfterPath(rawTokens, path) {
+    let matched = 0;
+    for (let i = 0; i < rawTokens.length; i++) {
+        if (matched === path.length)
+            return rawTokens.slice(i);
+        if (rawTokens[i] === '--json')
+            continue;
+        if (rawTokens[i] === path[matched])
+            matched++;
+    }
+    return [];
+}
+/** Forward `args` to an external binary verbatim: stdio inherited (streaming
+ *  preserved), and the child's exit code propagated. Never returns — either
+ *  exits with the child's status or throws a structured CrtrError (ENOENT ->
+ *  install hint) for the caller's existing error handler to render. */
+function runPassthrough(passthrough, args) {
+    const result = spawnSync(passthrough.bin, args, { stdio: 'inherit' });
+    if (result.error !== undefined) {
+        // Any launch-time failure (not found, not executable, ...) means this
+        // binary isn't usable from here — surface one structured error with the
+        // install hint rather than branching on a specific errno. (Node/libuv can
+        // report EACCES instead of ENOENT for a genuinely-missing binary when PATH
+        // contains malformed entries — e.g. a literal `~/...` segment — so a
+        // ENOENT-only check would miss real missing-binary cases on such hosts.)
+        const err = result.error;
+        throw new CrtrError('binary_missing', `${passthrough.bin} could not be run (${err.code ?? err.message})`, ExitCode.USAGE, {
+            received: passthrough.bin,
+            next: passthrough.installHint,
+        });
+    }
+    if (result.status !== null) {
+        process.exit(result.status);
+    }
+    if (result.signal !== null) {
+        // Signal-terminated: exit(1) would break the transparent exit-propagation
+        // contract (a direct shell invocation would show 128+signal, e.g. 143 for
+        // SIGTERM). Map to the standard 128+signal-number convention.
+        const signalNumber = osConstants.signals[result.signal];
+        if (signalNumber !== undefined) {
+            process.exit(128 + signalNumber);
+        }
+    }
+    // Truly impossible per Node's spawnSync contract (status and signal are
+    // mutually exclusive and one is always set on a completed run) — fallback only.
+    process.exit(1);
+}
+/** Build a structured unknown-path error. Names valid children of the deepest
+ *  matched node and names the entry command per the spec. The entry command is
+ *  the full path to the matched node (not just its local name), so the recovery
+ *  hint is a command that actually exists. No fuzzy matching. */
+export function unknownPathError(node, path, bad) {
+    const valid = childNames(node);
+    const validStr = valid.length > 0 ? valid.join(', ') : '(none)';
+    const entryCmd = path.length > 0 ? `crtr ${path.join(' ')} -h` : 'crtr -h';
+    const collapsed = valid.some((name) => name.startsWith('(and '));
+    return new CrtrError('unknown_path', `unknown subcommand: ${bad}`, ExitCode.USAGE, {
+        received: bad,
+        next: collapsed
+            ? `Valid children include: ${validStr}. Run \`${entryCmd}\` for how to find the rest.`
+            : `Valid children: ${validStr}. Run \`${entryCmd}\` for the full list.`,
+    });
+}
+/** An unknown top-level command on a computer with no Northlight account (no `runtime/machine.json`, no `runtime.issuer`):
+ *  a command that comes from Northlight needs the account. */
+export function notJoinedError(bad) {
+    const next = 'If it comes from Northlight, it needs a Northlight account: `crtr sys signin`.';
+    return new CrtrError('not_joined', `\`crtr ${bad}\` isn't a command here. ${next}`, ExitCode.USAGE, { received: bad, next });
+}
+/** True when the user settings name no directory issuer. A settings read that
+ *  fails is treated as joined, so the error falls back to `unknown_path`. A fleet
+ *  sandbox reaches the control plane through its broker relay and has no issuer
+ *  to join, so it is never unjoined. */
+async function runtimeUnjoined() {
+    if (providerProjectionOverBrokerRelay())
+        return false;
+    try {
+        const { readConfig } = await import('./config.js');
+        const { readMachineConfig } = await import('../daemon/machine-link/config.js');
+        return readMachineConfig() === undefined && !readConfig('user').runtime?.issuer;
+    }
+    catch {
+        return false;
+    }
+}
+// Argv parser
+function parseArgvError(code, message, received, field, next) {
+    return new CrtrError(code, message, ExitCode.USAGE, {
+        received,
+        field,
+        next: next !== undefined ? next : 'Run the command with -h to see the parameter schema.',
+    });
+}
+/** Convert kebab-case flag name to camelCase key. e.g. context-file → contextFile */
+function flagNameToKey(name) {
+    return name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+/** Parse remaining argv tokens against the leaf's InputParam schema.
+ *  Returns a plain object whose keys are camelCase parameter names.
+ *  Optionally tracks which parameters were explicitly provided via a callback. */
+export async function parseArgv(params, tokens, options) {
+    const result = {};
+    const provided = new Set(); // Track explicitly-provided parameter names
+    const contextFilePaths = new Map();
+    // Index params by kind for quick lookup
+    const positionalParams = params.filter((p) => p.kind === 'positional');
+    const stdinParam = params.find((p) => p.kind === 'stdin');
+    const contextFileParam = params.find((p) => p.kind === 'context-file');
+    const flagParams = params.filter((p) => p.kind === 'flag');
+    const flagsByName = new Map(flagParams.map((f) => [f.name, f]));
+    const withholdValues = flagParams.some((f) => f.sensitive === true);
+    // Apply defaults for bool flags
+    for (const f of flagParams) {
+        if (f.type === 'bool') {
+            result[flagNameToKey(f.name)] = f.default !== undefined ? f.default : false;
+        }
+        else if (f.default !== undefined) {
+            result[flagNameToKey(f.name)] = f.default;
+        }
+    }
+    const positionalValues = [];
+    let positionalIndex = 0;
+    let forcedPositional = false; // true after bare --
+    let i = 0;
+    while (i < tokens.length) {
+        const token = tokens[i];
+        if (token === '--' && !forcedPositional) {
+            forcedPositional = true;
+            i++;
+            continue;
+        }
+        if (!forcedPositional && token.startsWith('--')) {
+            // Flag: --name or --name=value
+            const eqIdx = token.indexOf('=');
+            let flagName;
+            let inlineValue;
+            if (eqIdx !== -1) {
+                flagName = token.slice(2, eqIdx);
+                inlineValue = token.slice(eqIdx + 1);
+            }
+            else {
+                flagName = token.slice(2);
+            }
+            // --context-file is handled specially regardless of declared schema
+            if (flagName === 'context-file') {
+                if (contextFileParam === undefined) {
+                    throw parseArgvError('unknown_flag', `unknown flag: --context-file`, '--context-file', undefined, 'This leaf does not accept --context-file.');
+                }
+                const pathVal = inlineValue !== undefined ? inlineValue : tokens[++i];
+                if (pathVal === undefined) {
+                    throw parseArgvError('missing_parameter', '--context-file requires a PATH argument', '--context-file', 'context-file');
+                }
+                let fileContent;
+                try {
+                    fileContent = readFileSync(pathVal, 'utf8');
+                }
+                catch (err) {
+                    throw parseArgvError('invalid_type', `--context-file: cannot read file: ${pathVal}`, pathVal, 'context-file', 'Provide a readable file path.');
+                }
+                let parsed;
+                try {
+                    parsed = JSON.parse(fileContent);
+                }
+                catch {
+                    throw parseArgvError('invalid_type', `--context-file: file is not valid JSON: ${pathVal}`, pathVal, 'context-file', 'Ensure the file contains a valid JSON object.');
+                }
+                const contextFileKey = flagNameToKey(contextFileParam.name);
+                result[contextFileKey] = parsed;
+                contextFilePaths.set(contextFileKey, resolve(pathVal));
+                provided.add(contextFileKey);
+                i++;
+                continue;
+            }
+            const flagDef = flagsByName.get(flagName);
+            if (flagDef === undefined) {
+                throw parseArgvError('unknown_flag', `unknown flag: --${flagName}`, `--${flagName}`, undefined, 'Use --<flag-name> for declared flags only. Run -h for the schema.');
+            }
+            const key = flagNameToKey(flagName);
+            provided.add(key);
+            if (flagDef.type === 'bool') {
+                if (inlineValue !== undefined) {
+                    throw parseArgvError('invalid_type', `boolean flag --${flagName} takes no value`, `--${flagName}=${inlineValue}`, flagName, `Use --${flagName} (presence = true) with no value.`);
+                }
+                result[key] = true;
+                i++;
+                continue;
+            }
+            const rawVal = inlineValue !== undefined ? inlineValue : tokens[++i];
+            if (rawVal === undefined || (inlineValue === undefined && rawVal.startsWith('--'))) {
+                const focusedNext = flagDef.focusedHelp !== undefined && (options?.leafPath?.length ?? 0) > 0
+                    ? `Run \`crtr ${options.leafPath.join(' ')} --${flagName} -h\` and read the focused value contract before retrying.`
+                    : undefined;
+                throw parseArgvError('missing_parameter', `--${flagName} requires a value`, `--${flagName}`, flagName, focusedNext);
+            }
+            let parsedValue;
+            if (flagDef.type === 'int') {
+                const n = Number(rawVal);
+                if (!Number.isInteger(n)) {
+                    throw parseArgvError('invalid_type', `--${flagName} must be an integer`, rawVal, flagName, `Provide an integer value for --${flagName}.`);
+                }
+                parsedValue = n;
+            }
+            else if (flagDef.type === 'enum') {
+                const choices = flagDef.choices;
+                if (choices !== undefined && !choices.includes(rawVal)) {
+                    throw parseArgvError('invalid_type', `--${flagName} must be one of: ${choices.join(', ')}`, rawVal, flagName, `Retry with one of: ${choices.join(', ')}.`);
+                }
+                parsedValue = rawVal;
+            }
+            else if (flagDef.type === 'json') {
+                let json;
+                try {
+                    json = JSON.parse(rawVal);
+                }
+                catch {
+                    throw parseArgvError('invalid_type', `--${flagName} is not valid JSON`, rawVal, flagName, `Pass one JSON value for --${flagName}; run -h for its shape.`);
+                }
+                const mismatch = flagDef.shape === undefined ? null : validateValue(flagDef.shape, json, `--${flagName}`);
+                if (mismatch !== null) {
+                    throw parseArgvError('invalid_type', `${mismatch.path} must be ${mismatch.expected}, got ${mismatch.receivedType}`, rawVal, mismatch.path, `Fix ${mismatch.path}; run -h for the shape of --${flagName}.`);
+                }
+                parsedValue = json;
+            }
+            else {
+                // string, path or file (a file param is the string typed; only a
+                // path param with an encoding is ever read from disk)
+                parsedValue = rawVal;
+            }
+            if (flagDef.repeatable === true) {
+                const existing = result[key];
+                const arr = Array.isArray(existing) ? existing : [];
+                arr.push(parsedValue);
+                result[key] = arr;
+            }
+            else {
+                result[key] = parsedValue;
+            }
+            i++;
+            continue;
+        }
+        // Positional (or token after --)
+        const positionalParam = positionalParams[positionalIndex];
+        if (positionalParam !== undefined) {
+            const key = flagNameToKey(positionalParam.name);
+            if (positionalParam.repeatable === true) {
+                const values = result[key] ?? [];
+                values.push(token);
+                result[key] = values;
+            }
+            else {
+                result[key] = token;
+                positionalIndex++;
+            }
+            positionalValues.push(token);
+            provided.add(key);
+            i++;
+            continue;
+        }
+        if (positionalValues.length > 0) {
+            // Defer this rejection until flags are parsed: a leaf-specific recovery
+            // may depend on a target flag that follows the positional body.
+            if (stdinParam !== undefined && positionalParams.length === 0) {
+                positionalValues.push(token);
+                i++;
+                continue;
+            }
+            // A leaf that also declares a `stdin` param treats its stdin value as
+            // write-only/sensitive by convention (`profile env set`'s value, etc.).
+            // An unexpected extra positional is the likely secret-as-argv mistake, so
+            // never echo it back in the rejection.
+            if (stdinParam !== undefined) {
+                throw parseArgvError('bad_invocation', `unexpected extra positional argument (value withheld: this leaf reads "${stdinParam.name}" from stdin, never argv)`, undefined, undefined, `Pipe it on stdin instead of passing it as a positional argument.`);
+            }
+            throw parseArgvError('bad_invocation', withholdValues ? 'unexpected extra positional argument (value withheld: this leaf takes a secret)' : `unexpected extra positional argument: ${token}`, withholdValues ? undefined : tokens.join(' '), undefined, 'Use declared flags or positional parameters. Run -h for the schema.');
+        }
+        // A leaf declaring no positional param may still take one bare token as its
+        // stdin body (`crtr node yield "note"`); the resolution below turns it into
+        // the stdin value. `allowPositional: false` opts out.
+        if (positionalParams.length === 0 && (stdinParam === undefined || stdinParam.allowPositional === false)) {
+            throw parseArgvError('bad_invocation', withholdValues ? 'this leaf takes no positional arguments (value withheld: this leaf takes a secret)' : `this leaf takes no positional arguments: ${token}`, withholdValues ? undefined : token, undefined, 'Use --flag for parameters. Run -h for the schema.');
+        }
+        positionalValues.push(token);
+        i++;
+    }
+    // Resolve stdin if declared. Some leaves permit one positional token to
+    // supply the stdin body; `-` then means read stdin. A positional alongside
+    // genuinely piped, non-empty stdin is ambiguous and errors loudly.
+    let stdinWasSupplied = false;
+    if (stdinParam !== undefined) {
+        if (positionalValues.length > 1 && positionalParams.length === 0) {
+            const conflict = stdinParam.positionalStdinConflict?.(result);
+            if (conflict !== undefined) {
+                throw parseArgvError('bad_invocation', conflict.message, undefined, conflict.field, conflict.next);
+            }
+            throw parseArgvError('bad_invocation', `unexpected extra positional argument (value withheld: this leaf reads "${stdinParam.name}" from stdin, never argv)`, undefined, undefined, `Pipe it on stdin instead of passing it as a positional argument.`);
+        }
+        if (positionalValues.length > 0 && positionalParams.length === 0 && stdinParam.allowPositional !== false) {
+            const positionalValue = positionalValues[0];
+            if (positionalValue === '-') {
+                const raw = await readStdinRaw();
+                // Empty required stdin is NOT thrown here: it is left unset so the
+                // completeness check below reports it together with every other
+                // missing required parameter in ONE error.
+                if (raw.trim() !== '' || !stdinParam.required) {
+                    result[flagNameToKey(stdinParam.name)] = raw;
+                }
+                stdinWasSupplied = true;
+            }
+            else {
+                // A bounded peek, not a full drain: a non-TTY stdin that's merely
+                // inherited and held open (e.g. this leaf invoked as a subprocess by
+                // another agent that never closes its own stdin) must not hang the
+                // whole invocation waiting for a close that will never come.
+                const piped = await peekStdinRaw();
+                if (piped.trim() !== '') {
+                    const conflict = stdinParam.positionalStdinConflict?.(result);
+                    throw parseArgvError('bad_invocation', conflict?.message ?? `both a positional argument ("${positionalValue}") and piped stdin were provided for ${stdinParam.name}`, positionalValue, conflict?.field ?? stdinParam.name, conflict?.next ?? `Pass exactly one: either the positional argument or piped stdin, not both.`);
+                }
+                result[flagNameToKey(stdinParam.name)] = positionalValue;
+                stdinWasSupplied = true; // positional supplying stdin counts as supplied
+            }
+        }
+        else {
+            // Unbounded drain to EOF — the standard Unix stdin-body contract. A
+            // heredoc/pipe/redirect/procsub all write and close before this
+            // process finishes reading, so this always resolves for genuine
+            // input; a slow producer's bytes must never be silently discarded.
+            // The non-hang guarantee lives at the spawn boundary instead: every
+            // crtr-owned subprocess (pi bash tool, the bash valve, async
+            // execFile('crtr', …) call sites) gives its child an ignored/closed
+            // stdin, so this only ever blocks on a foreign caller that hands crtr
+            // a held-open pipe — exactly the contract `cat`/`jq`/`wc` honor too.
+            const raw = await readStdinRaw();
+            // Absent (TTY) or empty stdin supplies nothing, for a required param
+            // (the completeness check below reports it with every other missing
+            // parameter) and an optional one alike: an optional body that is not
+            // set is not sent, so a provider can apply its own default for it.
+            if (raw !== '' && (raw.trim() !== '' || !stdinParam.required)) {
+                result[flagNameToKey(stdinParam.name)] = raw;
+                stdinWasSupplied = true;
+            }
+        }
+    }
+    // Track provided stdin param
+    if (stdinWasSupplied && stdinParam !== undefined) {
+        provided.add(flagNameToKey(stdinParam.name));
+    }
+    // Ambient defaults: a param declaring `defaultFromEnv` that the caller did not
+    // supply takes its value from that environment variable when it is set and
+    // non-empty. It is recorded as PROVIDED — the caller's environment is a real
+    // source, not a display default — so it satisfies the required check below and
+    // ships through the HTTP transport's presence rule (a static `default`
+    // deliberately does neither).
+    for (const p of params) {
+        if (p.kind !== 'flag' && p.kind !== 'positional')
+            continue;
+        if (p.defaultFromEnv === undefined)
+            continue;
+        const key = flagNameToKey(p.name);
+        if (provided.has(key))
+            continue;
+        const envValue = process.env[p.defaultFromEnv];
+        if (envValue === undefined || envValue === '')
+            continue;
+        result[key] = p.kind === 'positional' && p.repeatable === true ? [envValue] : envValue;
+        provided.add(key);
+    }
+    // Validate required params — COMPLETE, never first-failure. Drip-feeding one
+    // missing parameter per invocation turns a single correction into a round
+    // trip per field, so collect every violated requirement (flag, positional,
+    // context-file, stdin) and report them in ONE error. A missing parameter is
+    // proof the leaf was invoked without its contract in context, so `Next:`
+    // mandates the schema read rather than offering the one-field patch.
+    const missing = [];
+    for (const p of params) {
+        const key = flagNameToKey(p.name);
+        const missingRequiredBool = p.kind === 'flag' && p.type === 'bool' && !provided.has(key);
+        if (p.required && (missingRequiredBool || result[key] === undefined || result[key] === null)) {
+            const display = p.kind === 'positional'
+                ? `positional ${p.name.toUpperCase()}`
+                : p.kind === 'flag'
+                    ? `--${p.name}`
+                    : p.kind === 'context-file'
+                        ? `--context-file`
+                        : 'stdin';
+            missing.push({ display, name: p.name });
+        }
+    }
+    if (missing.length > 0) {
+        const displays = missing.map((m) => m.display).join(', ');
+        const leafPath = options?.leafPath;
+        const cmd = leafPath !== undefined && leafPath.length > 0
+            ? `\`crtr ${leafPath.join(' ')} -h\``
+            : 'this command with -h';
+        throw parseArgvError('missing_parameter', missing.length === 1
+            ? `required parameter is missing: ${displays}`
+            : `required parameters are missing: ${displays}`, undefined, missing.map((m) => m.name).join(', '), `Run ${cmd} and read the full schema before re-issuing — do not guess parameters one at a time.`);
+    }
+    // Notify caller of which parameters were explicitly provided
+    if (options?.onProvidedParams !== undefined) {
+        options.onProvidedParams(provided);
+    }
+    if (options?.onContextFilePaths !== undefined) {
+        options.onContextFilePaths(contextFilePaths);
+    }
+    return result;
+}
+/**
+ * Tokens handled before dispatch and stripped from what the leaf schema parses
+ * (root `-h` renders them as the Globals footer). They belong to no command, so
+ * anything reasoning about which command an argv names — the plugin
+ * revalidation gate, for one — has to ignore them too. One declaration, so a
+ * new global cannot be added here and missed there.
+ */
+/** Take the `--machine <id>` / `--machine=<id>` selector out of a provider leaf's argv. Nothing after a bare `--` is a flag. */
+export function takeMachineSelector(tokens) {
+    const rest = [];
+    let machine;
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token === '--') {
+            rest.push(...tokens.slice(i));
+            break;
+        }
+        const inline = token.startsWith('--machine=') ? token.slice('--machine='.length) : undefined;
+        if (token !== '--machine' && inline === undefined) {
+            rest.push(token);
+            continue;
+        }
+        const value = inline ?? tokens[i + 1];
+        if (value === undefined || value === '' || (inline === undefined && value.startsWith('-'))) {
+            throw parseArgvError('missing_parameter', '--machine requires a machine id', '--machine', 'machine', 'Pass the machine_id of one of the candidates a `machine_required` answer lists.');
+        }
+        if (inline === undefined)
+            i++;
+        machine = value;
+    }
+    return machine === undefined ? { rest } : { rest, machine };
+}
+export const GLOBAL_TOKENS = new Set(['--json', '--no-autostart']);
+export async function runCli(root, argv) {
+    // argv is process.argv — strip node binary + script path. `--json` is a
+    // global: pull it out anywhere it appears so the rest of argv parses against
+    // the leaf schema unchanged, and switch stdout from rendered prose to the
+    // leaf's declared `outputs` object as raw JSON. Prose stays the contract for
+    // an agent READING output; --json is the documented channel (root -h globals)
+    // for scripts — a cron's bash, external tooling — that must branch on canvas
+    // state and would otherwise scrape markdown.
+    // `--no-autostart` is likewise a global: it suppresses cold-socket daemon
+    // autostart (read from `process.argv` in `cliClient`, spec §7.1) and applies
+    // to every API-backed verb, so strip it here rather than declaring it on each
+    // leaf schema (an undeclared flag would otherwise be rejected as unknown).
+    const rawTokens = argv.slice(2);
+    if (rawTokens.includes('--json'))
+        setJsonOutput(true);
+    const tokens = rawTokens.filter((token) => !GLOBAL_TOKENS.has(token));
+    // Bare root invocation or -h at root
+    if (tokens.length === 0 || (tokens.length === 1 && (tokens[0] === '-h' || tokens[0] === '--help'))) {
+        const help = envNodeId()
+            ? { ...root.help, commands: await Promise.all(root.help.commands.map(async (command) => {
+                    const subtree = root.subtrees.find((entry) => entry.name === command.name);
+                    if (subtree?.effectiveHelp === undefined)
+                        return command;
+                    const listing = (await subtree.effectiveHelp()).listing ?? [];
+                    const visible = listing.filter((entry) => entry.tier !== 'hidden');
+                    const promoted = rootPromotedChildren(visible)
+                        .map((entry) => ({ path: `${subtree.name} ${entry.name}`, desc: entry.tier === 'important' ? entry.description : undefined }));
+                    return { ...command, subcommands: promoted.length ? promoted : undefined, otherSubcommandCount: visible.length - promoted.length };
+                })) }
+            : root.help;
+        process.stdout.write(renderRoot(help) + '\n');
+        process.exitCode = ExitCode.SUCCESS;
+        return;
+    }
+    // `crtr --version` / `crtr -v`. The front door already routes both here, so
+    // without this branch they fall through to the unknown-path error below.
+    // Imported lazily: `sys/shared.js` locates the package root eagerly at module
+    // load, and the cold-start check forbids adding that to cli.js's static
+    // import closure.
+    if (tokens.length === 1 && (tokens[0] === '--version' || tokens[0] === '-v')) {
+        const { readPackageVersion } = await import('../commands/sys/shared.js');
+        process.stdout.write(readPackageVersion() + '\n');
+        process.exitCode = ExitCode.SUCCESS;
+        return;
+    }
+    let { node, path, remaining } = walk(root, tokens);
+    try {
+        // Passthrough branches (e.g. `crtr capture`) opt out of the tree model
+        // entirely: forward every token after the branch verbatim to an external
+        // binary before any of the normal unknown-path / help / dispatch logic
+        // runs, so `crtr capture -h`, `crtr capture <args>`, and bare `crtr capture`
+        // all reach the external CLI untouched.
+        if (node.kind === 'branch' && node.passthrough !== undefined) {
+            runPassthrough(node.passthrough, rawArgsAfterPath(rawTokens, path));
+        }
+        if (node.kind === 'branch' && node.refusal !== undefined && remaining[0] !== '-h' && remaining[0] !== '--help') {
+            throw new CrtrError(node.refusal.code, node.refusal.message, node.refusal.exit, { next: node.refusal.next });
+        }
+        // A root/branch node's `remaining` is only non-empty because walk hit
+        // -h/--help or an unmatched child name (a leaf always consumes the rest
+        // of the path itself). So a non-help leading token here is always the
+        // latter: reject it as an unknown path before rendering any help, even
+        // when a -h/--help token also appears later in `remaining` — otherwise a
+        // removed/misspelled subcommand followed by -h would render the parent's
+        // help and exit 0 instead of failing.
+        if ((node.kind === 'root' || node.kind === 'branch')
+            && remaining.length > 0
+            && remaining[0] !== '-h' && remaining[0] !== '--help') {
+            if (node.kind === 'root' && !remaining[0].startsWith('-') && node.providerCatalogFailure !== undefined)
+                throw node.providerCatalogFailure;
+            if (node.kind === 'root' && !remaining[0].startsWith('-') && await runtimeUnjoined()) {
+                throw notJoinedError(remaining[0]);
+            }
+            throw unknownPathError(node, path, remaining[0]);
+        }
+        // Help anywhere in remaining tokens → print node help and exit. The exact
+        // leaf form `--<flag> -h` selects that flag's focused continuation when one
+        // is declared; no invocation state or acknowledgement token is persisted.
+        if (helpRequested(remaining)) {
+            process.stdout.write(await renderNodeWithAddenda(node, path, focusedHelpFlag(node, remaining)) + '\n');
+            process.exitCode = ExitCode.SUCCESS;
+            return;
+        }
+        // Bare branch or bare root (no -h, remaining fully consumed) → help surface
+        if (node.kind === 'root' || node.kind === 'branch') {
+            process.stdout.write(await renderNodeWithAddenda(node, path) + '\n');
+            process.exitCode = ExitCode.SUCCESS;
+            return;
+        }
+        // Leaf dispatch — argv input model only. Bind the leaf to a const so the
+        // narrowing established by the branch/root guards above survives the awaits
+        // below: `node` is now a reassignable `let` (the §5.1 retry re-walks it),
+        // which TS re-widens to the node union across an `await`.
+        const leaf = node;
+        beginPreview(path.join(' '));
+        const params = leaf.help.params !== undefined ? leaf.help.params : [];
+        let providedParams = new Set();
+        let contextFilePaths = new Map();
+        let leafTokens = remaining;
+        let machine;
+        if (leaf.machineSelector === true && !params.some((param) => param.kind === 'flag' && param.name === 'machine')) {
+            const selected = takeMachineSelector(remaining);
+            leafTokens = selected.rest;
+            machine = selected.machine;
+        }
+        const input = await parseArgv(params, leafTokens, {
+            leafPath: path,
+            onProvidedParams: (provided) => {
+                providedParams = provided;
+            },
+            onContextFilePaths: (paths) => {
+                contextFilePaths = paths;
+            },
+        });
+        const context = { providedParams, contextFilePaths, ...(machine === undefined ? {} : { machine }) };
+        const result = await operationIdContext.fresh(() => leaf.run(input, context));
+        publishPreviewResult(result === undefined || result === null ? result : leaf.preview?.(result) ?? result);
+        if (result !== undefined && result !== null) {
+            if (isJsonOutput()) {
+                emit(result);
+            }
+            else {
+                const text = leaf.render !== undefined ? leaf.render(result) : renderResult(result, leaf.help);
+                process.stdout.write(text + (leaf.stdoutExact?.(result) ? '' : '\n'));
+            }
+        }
+        // JSONL leaves call emitLine themselves and return void
+    }
+    catch (e) {
+        // A backend that answered `manifest_stale` says this dispatch was parsed
+        // from an out-of-date command description. Only the caller above this one
+        // can act on that — refetching the package and re-walking the ORIGINAL argv
+        // against the refreshed tree — so it is the single error class this
+        // dispatcher reports by rethrowing instead of rendering. Whoever declines
+        // to recover renders it with the same `handle`.
+        if (isManifestStaleError(e))
+            throw e;
+        handle(e);
+    }
+}