@struktoai/mirage-core/dist/commands/cli/walk.d.ts

A Unified Virtual Filesystem For AI Agents

import { CommandSpec, UsageStyle } from '../spec/types.ts';
import { WalkResult, type CLI } from './types.ts';
/** The subcommand a word names, by canonical name or alias. */
export declare function findChild(node: CommandSpec, word: string): CommandSpec | null;
/**
 * Every `Argument.env` variable a program tree reads.
 *
 * The env-plane fill step asks this per installed head word on the
 * line, so a managed name a CLI reads from the environment joins the
 * fetch set even though no `$NAME` appears in the line's text.
 */
export declare function envNames(node: CommandSpec): ReadonlySet<string>;
/**
 * Env names on the verb paths the line's words could select.
 *
 * The words prune the tree: a subcommand joins only when some word
 * spells its name or an alias, recursively, so a bare head reads the
 * root's env names and `ntn api get` adds exactly the api and get
 * nodes. A word doubling as an operand over-selects, which costs one
 * fetch; a verb can never hide, because dispatch only runs a verb the
 * line spells. Null means a word no static read can spell (an
 * expansion), where the whole tree is the only safe answer.
 */
export declare function invokedEnvNames(spec: CommandSpec, words: ReadonlySet<string> | null): ReadonlySet<string>;
/**
 * Env names whose every reader on the walked path is supplied.
 *
 * The parser never reads `Argument.env` for a destination the line
 * already fills (typed outranks environment), so a supplied option's
 * managed variable is not a read and must not fetch: a dead source
 * would otherwise fail a line that never consults it. Tracking is by
 * destination, never by bare name: two options may declare one
 * variable, and a variable shared by a supplied and an unsupplied
 * destination stays a read, because the unsupplied one still falls
 * back to it. Presence is claimed only where consumption is certain,
 * walking level by level the way `walk` does and matching only the
 * exact-token forms. Anything subtler stops the scan -- keeping what
 * was proven for a word that only ends option parsing (an operand
 * under a remainder leaf, a verb that matches nothing; `--` also
 * drops every variable readable below the group, since the walk keeps
 * descending after it), and keeping nothing for a word whose
 * consumption is in doubt (a cluster, an abbreviation, `--help`) --
 * so a wrong guess can only over-fetch, never skip a real read.
 */
export declare function suppliedEnvNames(spec: CommandSpec, args: readonly string[]): ReadonlySet<string>;
/**
 * Descend a tree by verb words, null if a word names no subcommand.
 *
 * Returns the node and its canonical path, so an alias renders under the
 * name it resolves to, the attribution rule `walk` uses. This is
 * introspection only (`man`): no options are parsed and no usage error is
 * produced, so a caller gets the node or nothing.
 */
export declare function findNode(spec: CommandSpec, verbs: readonly string[]): {
    node: CommandSpec;
    path: string[];
} | null;
/**
 * True when the node parses its own command line instead of mirage.
 *
 * A script root that declares no grammar is the only such node: the
 * embedded program is the parser, so its flags are not mirage's to
 * recognize, and a generated help page would document nothing. Mirage
 * forwards the whole line to it (a pass-through rest operand) and leaves
 * `--help` to the program. A script root that does declare options or
 * operands opts back into the ordinary machinery, which then renders
 * truthful help and refuses undeclared flags.
 */
export declare function ownsArgv(cli: CLI): boolean;
/**
 * A group node's help: the ordinary command help plus Commands rows.
 * One renderer serves leaves and groups; the same text serves `--help`
 * (stdout, exit 0) and the bare-group refusal (stdout, exit 1, matching
 * git). `name` is the full display path as typed ('gws gmail'), so a
 * renamed install renders its own spelling.
 */
export declare function nodeHelp(name: string, node: CommandSpec, style?: UsageStyle): string;
/** The node's child rows, as the renderer lists them. */
export declare function subcommandRows(node: CommandSpec): [string, string][];
export declare function listedNode(node: CommandSpec, style?: UsageStyle): CommandSpec;
/**
 * Resolve one command line against a CLI tree.
 *
 * Each level consumes its own options in POSIX order (stop at the first
 * non-option word, which names the subcommand), so `git -C <path> status`
 * shapes parse the way a terminal user expects. Behavior is pinned to git
 * (docker, git 2.47.3): bare group prints its usage to stdout and exits 1,
 * `--help` prints the same to stdout and exits 0, an unknown verb refuses
 * on stderr with exit 1, and group-level option errors refuse on stderr
 * with exit 129. The leaf's own argv is not parsed here; it rides the
 * ordinary spec machinery. `head` is the installed head word, used in
 * every rendering so a renamed install prints its own name, `cwd` is the
 * working directory PATH-typed group values resolve against, so a group option
 * resolves the way a leaf option does, and `env` is the session environment,
 * so a group option declaring `Argument.env` fills at its own level exactly as
 * a leaf one does in the flat parser. `deferEnv` lets target selection reach
 * a leaf before fetching managed values; only an absent environment-backed
 * required option is deferred, and execution still performs the full walk.
 */
export declare function walk(head: string, spec: CommandSpec, argv: readonly string[], cwd?: string, env?: Readonly<Record<string, string>> | null, deferEnv?: boolean): WalkResult;
//# sourceMappingURL=walk.d.ts.map