@north-light/crouter 0.3.318 → 0.3.320

package/dist/core/command.js

@@ -1,739 +1,10 @@
-// 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 } 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 { isManifestStaleError } from './manifest-stale.js';
-import { operationIdContext } from './events/operation-id.js';
-import { ExitCode } from '../types.js';
-import { readFileSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
-import { constants as osConstants } from 'node:os';
-import { isatty } from 'node:tty';
-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) {
-    return Object.freeze({
-        kind: 'leaf',
-        name: opts.name,
-        description: opts.description,
-        whenToUse: opts.whenToUse,
-        tier: opts.tier,
-        help: freezeCommandMetadata(opts.help),
-        slash: opts.slash === undefined ? undefined : freezeCommandMetadata(opts.slash),
-        hookEligible: opts.hookEligible,
-        plugin: opts.plugin,
-        run: opts.run,
-        render: opts.render,
-    });
-}
-/** 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: c.tier ?? 'normal',
-            ...(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,
-        rootEntry: opts.rootEntry,
-        extensible: opts.extensible,
-        plugin: opts.plugin,
-        slash: opts.slash,
-        passthrough: opts.passthrough,
-        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)
-        .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 = visible
-            .filter((c) => c.tier === 'common' || c.tier === 'important')
-            .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) => s.tier !== 'hidden').map((s) => s.name);
-    if (node.kind === 'branch')
-        return node.children.filter((c) => c.tier !== 'hidden').map((c) => c.name);
-    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) };
-}
-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.help, focusedFlag);
-    }
-    const body = node.kind === 'leaf' && node.effectiveHelp !== undefined
-        ? renderLeafArgv(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, coreCommandPaths, 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,
-        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';
-    return new CrtrError('unknown_path', `unknown subcommand: ${bad}`, ExitCode.USAGE, {
-        received: bad,
-        next: `Valid children: ${validStr}. Run \`${entryCmd}\` for the full list.`,
-    });
-}
-// 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]));
-    // 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 positionalWasSupplied = false; // Track if positional came from argv (not stdin)
-    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 {
-                // string or path
-                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);
-            positionalWasSupplied = true;
-            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);
-                positionalWasSupplied = true;
-                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', `unexpected extra positional argument: ${token}`, 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', `this leaf takes no positional arguments: ${token}`, token, undefined, 'Use --flag for parameters. Run -h for the schema.');
-        }
-        positionalValues.push(token);
-        positionalWasSupplied = true;
-        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 {
-            // Check if stdin is non-TTY (piped, redirected, or positional)
-            const stdinIsTTY = isatty(0);
-            // 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();
-            // As above: an empty required stdin falls through to the completeness
-            // check so it is reported alongside any missing flags/positional.
-            if (raw.trim() !== '' || !stdinParam.required) {
-                result[flagNameToKey(stdinParam.name)] = raw;
-            }
-            // stdin is supplied if it was non-TTY (piped) OR if a positional was used
-            stdinWasSupplied = !stdinIsTTY || positionalWasSupplied;
-        }
-    }
-    // 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.
- */
-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'))) {
-        process.stdout.write(renderRoot(root.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));
-        }
-        // 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') {
-            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();
-        const input = await parseArgv(params, remaining, {
-            leafPath: path,
-            onProvidedParams: (provided) => {
-                providedParams = provided;
-            },
-            onContextFilePaths: (paths) => {
-                contextFilePaths = paths;
-            },
-        });
-        const context = { providedParams, contextFilePaths };
-        const result = await operationIdContext.fresh(() => leaf.run(input, context));
-        publishPreviewResult(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 + '\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);
-    }
-}
+var W=Object.defineProperty;var f=(e,i)=>W(e,"name",{value:i,configurable:!0});import{renderRoot as V,renderBranch as M,renderLeafArgv as T}from"./help.js";import{beginPreview as z,publishPreviewResult as I,readStdinRaw as B,peekStdinRaw as J,emit as G,handle as L,setJsonOutput as K,isJsonOutput as D}from"./io.js";import{renderResult as Y}from"./render.js";import{CrtrError as O}from"./errors.js";import{isManifestStaleError as Q}from"./manifest-stale.js";import{operationIdContext as X}from"./events/operation-id.js";import{ExitCode as P}from"../types.js";import{readFileSync as Z}from"node:fs";import{spawnSync as ee}from"node:child_process";import{constants as ne}from"node:os";import{isatty as te}from"node:tty";import{resolve as ie}from"node:path";function F(e){if(e===null||typeof e!="object"||Object.isFrozen(e))return e;for(const i of Object.values(e))F(i);return Object.freeze(e)}f(F,"freezeCommandMetadata");function _e(e){return Object.freeze({kind:"leaf",name:e.name,description:e.description,whenToUse:e.whenToUse,tier:e.tier,help:F(e.help),slash:e.slash===void 0?void 0:F(e.slash),hookEligible:e.hookEligible,plugin:e.plugin,run:e.run,render:e.render})}f(_e,"defineLeaf");function re(e){return e.kind!=="branch"?0:(e.help.listing??[]).filter(i=>i.tier!=="hidden").length}f(re,"visibleSubCount");function Ue(e){if(e.passthrough!==void 0&&e.children.length>0)throw new Error(`defineBranch("${e.name}"): a passthrough branch must declare no children (found ${e.children.length})`);return e.help.listing=e.children.map(i=>{const r=re(i);return{name:i.name,description:i.description??"",whenToUse:i.whenToUse??"",tier:i.tier??"normal",...i.plugin!==void 0?{plugin:i.plugin}:{},...r>0?{subCount:r}:{}}}),{kind:"branch",name:e.name,description:e.description,whenToUse:e.whenToUse,tier:e.tier,help:e.help,rootEntry:e.rootEntry,extensible:e.extensible,plugin:e.plugin,slash:e.slash,passthrough:e.passthrough,children:e.children}}f(Ue,"defineBranch");function Ne(e){const i=[],r=f(n=>{if(n.slash!==void 0&&i.push(n.slash),n.kind==="branch")for(const o of n.children)r(o)},"visit");for(const n of e.subtrees)r(n);return i}f(Ne,"collectSlashSpecs");function Re(e){const i=e.subtrees.filter(n=>n.rootEntry!==void 0).map(n=>{const o=(n.help.listing??[]).filter(s=>s.tier!=="hidden"),d=o.filter(s=>s.tier==="common"||s.tier==="important").map(s=>({path:`${n.name} ${s.name}`,desc:s.tier==="important"?s.description:void 0}));return{name:n.name,concept:n.rootEntry.concept,desc:n.rootEntry.desc,useWhen:n.rootEntry.useWhen,dynamicState:n.rootEntry.dynamicState,subcommands:d.length>0?d:void 0,otherSubcommandCount:o.length-d.length}});return{kind:"root",help:{tagline:e.tagline,commands:i,globals:e.globals},subtrees:e.subtrees}}f(Re,"defineRoot");function oe(e){return e.kind==="root"?e.subtrees.filter(i=>i.tier!=="hidden").map(i=>i.name):e.kind==="branch"?e.children.filter(i=>i.tier!=="hidden").map(i=>i.name):[]}f(oe,"childNames");function ae(e,i){let r=e;const n=[];let o=0;for(;o<i.length;){const d=i[o];if(d==="-h"||d==="--help")break;if(r.kind==="root"){const s=r.subtrees.find(a=>a.name===d);if(s===void 0)break;r=s,n.push(s.name),o++}else if(r.kind==="branch"){const s=r.children.find(a=>a.name===d);if(s===void 0)break;r=s,n.push(s.name),o++}else break}return{node:r,path:n,remaining:i.slice(o)}}f(ae,"walk");function se(e){return e.kind==="root"?V(e.help):e.kind==="branch"?M(e.help):T(e.help)}f(se,"renderNode");async function H(e,i,r){if(r!==void 0&&e.kind==="leaf")return T(e.help,r);const n=e.kind==="leaf"&&e.effectiveHelp!==void 0?T(await e.effectiveHelp()):se(e);if(i.length===0)return n;const{hasEffectiveCommandPlugins:o}=await import("./command-plugins/presence.js");if(!o())return n;const[{collectHelpAddenda:d},{SUBTREE_NAMES:s,coreCommandPaths:a,extensibleCoreBranches:C}]=await Promise.all([import("./command-plugins/help-addenda.js"),import("../build-root.js")]),y=await d(i.join(" "),{reservedCoreNames:new Set(s),coreCommandPaths:a,extensibleCoreBranches:C});return n+y.map(S=>`
+
+<plugin-help plugin="${S.plugin}">
+${S.text}
+</plugin-help>`).join("")}f(H,"renderNodeWithAddenda");function le(e){return e.some(i=>i==="-h"||i==="--help")}f(le,"helpRequested");function de(e,i){if(e.kind!=="leaf"||i.length!==2)return;const[r,n]=i;if(n!=="-h"&&n!=="--help"||!r.startsWith("--")||r.includes("="))return;const o=r.slice(2);return(e.help.params??[]).find(s=>s.kind==="flag"&&s.name===o)?.focusedHelp!==void 0?o:void 0}f(de,"focusedHelpFlag");function fe(e,i){let r=0;for(let n=0;n<e.length;n++){if(r===i.length)return e.slice(n);e[n]!=="--json"&&e[n]===i[r]&&r++}return[]}f(fe,"rawArgsAfterPath");function ue(e,i){const r=ee(e.bin,i,{stdio:"inherit"});if(r.error!==void 0){const n=r.error;throw new O("binary_missing",`${e.bin} could not be run (${n.code??n.message})`,P.USAGE,{received:e.bin,next:e.installHint})}if(r.status!==null&&process.exit(r.status),r.signal!==null){const n=ne.signals[r.signal];n!==void 0&&process.exit(128+n)}process.exit(1)}f(ue,"runPassthrough");function ce(e,i,r){const n=oe(e),o=n.length>0?n.join(", "):"(none)",d=i.length>0?`crtr ${i.join(" ")} -h`:"crtr -h";return new O("unknown_path",`unknown subcommand: ${r}`,P.USAGE,{received:r,next:`Valid children: ${o}. Run \`${d}\` for the full list.`})}f(ce,"unknownPathError");function p(e,i,r,n,o){return new O(e,i,P.USAGE,{received:r,field:n,next:o!==void 0?o:"Run the command with -h to see the parameter schema."})}f(p,"parseArgvError");function w(e){return e.replace(/-([a-z])/g,(i,r)=>r.toUpperCase())}f(w,"flagNameToKey");async function he(e,i,r){const n={},o=new Set,d=new Map,s=e.filter(t=>t.kind==="positional"),a=e.find(t=>t.kind==="stdin"),C=e.find(t=>t.kind==="context-file"),y=e.filter(t=>t.kind==="flag"),S=new Map(y.map(t=>[t.name,t]));for(const t of y)t.type==="bool"?n[w(t.name)]=t.default!==void 0?t.default:!1:t.default!==void 0&&(n[w(t.name)]=t.default);const b=[];let N=0,m=!1,x=!1,g=0;for(;g<i.length;){const t=i[g];if(t==="--"&&!x){x=!0,g++;continue}if(!x&&t.startsWith("--")){const c=t.indexOf("=");let l,v;if(c!==-1?(l=t.slice(2,c),v=t.slice(c+1)):l=t.slice(2),l==="context-file"){if(C===void 0)throw p("unknown_flag","unknown flag: --context-file","--context-file",void 0,"This leaf does not accept --context-file.");const h=v!==void 0?v:i[++g];if(h===void 0)throw p("missing_parameter","--context-file requires a PATH argument","--context-file","context-file");let U;try{U=Z(h,"utf8")}catch{throw p("invalid_type",`--context-file: cannot read file: ${h}`,h,"context-file","Provide a readable file path.")}let q;try{q=JSON.parse(U)}catch{throw p("invalid_type",`--context-file: file is not valid JSON: ${h}`,h,"context-file","Ensure the file contains a valid JSON object.")}const A=w(C.name);n[A]=q,d.set(A,ie(h)),o.add(A),g++;continue}const $=S.get(l);if($===void 0)throw p("unknown_flag",`unknown flag: --${l}`,`--${l}`,void 0,"Use --<flag-name> for declared flags only. Run -h for the schema.");const j=w(l);if(o.add(j),$.type==="bool"){if(v!==void 0)throw p("invalid_type",`boolean flag --${l} takes no value`,`--${l}=${v}`,l,`Use --${l} (presence = true) with no value.`);n[j]=!0,g++;continue}const k=v!==void 0?v:i[++g];if(k===void 0||v===void 0&&k.startsWith("--")){const h=$.focusedHelp!==void 0&&(r?.leafPath?.length??0)>0?`Run \`crtr ${r.leafPath.join(" ")} --${l} -h\` and read the focused value contract before retrying.`:void 0;throw p("missing_parameter",`--${l} requires a value`,`--${l}`,l,h)}let _;if($.type==="int"){const h=Number(k);if(!Number.isInteger(h))throw p("invalid_type",`--${l} must be an integer`,k,l,`Provide an integer value for --${l}.`);_=h}else if($.type==="enum"){const h=$.choices;if(h!==void 0&&!h.includes(k))throw p("invalid_type",`--${l} must be one of: ${h.join(", ")}`,k,l,`Retry with one of: ${h.join(", ")}.`);_=k}else _=k;if($.repeatable===!0){const h=n[j],U=Array.isArray(h)?h:[];U.push(_),n[j]=U}else n[j]=_;g++;continue}const u=s[N];if(u!==void 0){const c=w(u.name);if(u.repeatable===!0){const l=n[c]??[];l.push(t),n[c]=l}else n[c]=t,N++;b.push(t),m=!0,o.add(c),g++;continue}if(b.length>0){if(a!==void 0&&s.length===0){b.push(t),m=!0,g++;continue}throw a!==void 0?p("bad_invocation",`unexpected extra positional argument (value withheld: this leaf reads "${a.name}" from stdin, never argv)`,void 0,void 0,"Pipe it on stdin instead of passing it as a positional argument."):p("bad_invocation",`unexpected extra positional argument: ${t}`,i.join(" "),void 0,"Use declared flags or positional parameters. Run -h for the schema.")}if(s.length===0&&(a===void 0||a.allowPositional===!1))throw p("bad_invocation",`this leaf takes no positional arguments: ${t}`,t,void 0,"Use --flag for parameters. Run -h for the schema.");b.push(t),m=!0,g++}let R=!1;if(a!==void 0){if(b.length>1&&s.length===0){const t=a.positionalStdinConflict?.(n);throw t!==void 0?p("bad_invocation",t.message,void 0,t.field,t.next):p("bad_invocation",`unexpected extra positional argument (value withheld: this leaf reads "${a.name}" from stdin, never argv)`,void 0,void 0,"Pipe it on stdin instead of passing it as a positional argument.")}if(b.length>0&&s.length===0&&a.allowPositional!==!1){const t=b[0];if(t==="-"){const u=await B();(u.trim()!==""||!a.required)&&(n[w(a.name)]=u),R=!0}else{if((await J()).trim()!==""){const c=a.positionalStdinConflict?.(n);throw p("bad_invocation",c?.message??`both a positional argument ("${t}") and piped stdin were provided for ${a.name}`,t,c?.field??a.name,c?.next??"Pass exactly one: either the positional argument or piped stdin, not both.")}n[w(a.name)]=t,R=!0}}else{const t=te(0),u=await B();(u.trim()!==""||!a.required)&&(n[w(a.name)]=u),R=!t||m}}R&&a!==void 0&&o.add(w(a.name));for(const t of e){if(t.kind!=="flag"&&t.kind!=="positional"||t.defaultFromEnv===void 0)continue;const u=w(t.name);if(o.has(u))continue;const c=process.env[t.defaultFromEnv];c===void 0||c===""||(n[u]=t.kind==="positional"&&t.repeatable===!0?[c]:c,o.add(u))}const E=[];for(const t of e){const u=w(t.name),c=t.kind==="flag"&&t.type==="bool"&&!o.has(u);if(t.required&&(c||n[u]===void 0||n[u]===null)){const l=t.kind==="positional"?`positional ${t.name.toUpperCase()}`:t.kind==="flag"?`--${t.name}`:t.kind==="context-file"?"--context-file":"stdin";E.push({display:l,name:t.name})}}if(E.length>0){const t=E.map(l=>l.display).join(", "),u=r?.leafPath,c=u!==void 0&&u.length>0?`\`crtr ${u.join(" ")} -h\``:"this command with -h";throw p("missing_parameter",E.length===1?`required parameter is missing: ${t}`:`required parameters are missing: ${t}`,void 0,E.map(l=>l.name).join(", "),`Run ${c} and read the full schema before re-issuing \u2014 do not guess parameters one at a time.`)}return r?.onProvidedParams!==void 0&&r.onProvidedParams(o),r?.onContextFilePaths!==void 0&&r.onContextFilePaths(d),n}f(he,"parseArgv");const pe=new Set(["--json","--no-autostart"]);async function Ae(e,i){const r=i.slice(2);r.includes("--json")&&K(!0);const n=r.filter(a=>!pe.has(a));if(n.length===0||n.length===1&&(n[0]==="-h"||n[0]==="--help")){process.stdout.write(V(e.help)+`
+`),process.exitCode=P.SUCCESS;return}if(n.length===1&&(n[0]==="--version"||n[0]==="-v")){const{readPackageVersion:a}=await import("../commands/sys/shared.js");process.stdout.write(a()+`
+`),process.exitCode=P.SUCCESS;return}let{node:o,path:d,remaining:s}=ae(e,n);try{if(o.kind==="branch"&&o.passthrough!==void 0&&ue(o.passthrough,fe(r,d)),(o.kind==="root"||o.kind==="branch")&&s.length>0&&s[0]!=="-h"&&s[0]!=="--help")throw ce(o,d,s[0]);if(le(s)){process.stdout.write(await H(o,d,de(o,s))+`
+`),process.exitCode=P.SUCCESS;return}if(o.kind==="root"||o.kind==="branch"){process.stdout.write(await H(o,d)+`
+`),process.exitCode=P.SUCCESS;return}const a=o;z(d.join(" "));const C=a.help.params!==void 0?a.help.params:[];let y=new Set,S=new Map;const b=await he(C,s,{leafPath:d,onProvidedParams:f(x=>{y=x},"onProvidedParams"),onContextFilePaths:f(x=>{S=x},"onContextFilePaths")}),N={providedParams:y,contextFilePaths:S},m=await X.fresh(()=>a.run(b,N));if(I(m),m!=null)if(D())G(m);else{const x=a.render!==void 0?a.render(m):Y(m,a.help);process.stdout.write(x+`
+`)}}catch(a){if(Q(a))throw a;L(a)}}f(Ae,"runCli");export{pe as GLOBAL_TOKENS,Ne as collectSlashSpecs,Ue as defineBranch,_e as defineLeaf,Re as defineRoot,he as parseArgv,Ae as runCli,ce as unknownPathError,ae as walk};