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

A Unified Virtual Filesystem For AI Agents

import { type CommandSpec, UsageStyle } from '../spec/types.ts';
import type { ParsedCommand } from '../../workspace/executor/command/types.ts';
import type { FsCondition } from '../../errors/types.ts';
export declare const ARGPARSE_EXIT = 2;
export declare const HELP_SWITCH = "-h";
/**
 * git's usage block for one verb, as parse-options prints it.
 *
 * The synopsis lines come first, the first after `usage: ` and each next one
 * after `   or: `, then a blank line, one row per option and a closing blank
 * line. The lines are git's own (`GIT_SYNOPSES`); the rows are the leaf's spec
 * in git's layout, so the block lists exactly the options mirage takes: four
 * spaces, the short and long spellings, `--[no-]` where the spec declares a
 * long's negation beside it, the value's name, then the description from
 * column 26, or under that column on a line of its own when the spellings run
 * past it. Pinned against git 2.47.3.
 *
 * @param path the verb's path under git ('branch', 'stash list')
 * @param spec the leaf's grammar
 */
export declare function gitUsage(path: string, spec: CommandSpec): string;
/**
 * parse-options' answer to a word the verb does not take.
 *
 * `-h` asks for the usage block, which goes to stdout and exits 0 (git 2.56);
 * everything else here exits 129. A boolean long handed a value is refused on
 * one line, and so is an option that needs a value and ends
 * the line without one (it reaches the operands when the verb takes free text).
 * Anything else is an option the verb does not have: a long one is an "option"
 * and a short one a "switch", both named without their dashes and quoted with a
 * backquote-apostrophe pair, and the usage block follows on stderr. Pinned
 * against git 2.50.1 and 2.47.3.
 *
 * @param word the offending word with its dashes ('--nosuch', '-Z',
 *   '--quiet=1')
 * @param path the verb's path under git, for its synopsis
 * @param spec the leaf's grammar, for its rows
 * @returns the refusal's stdout and its stderr
 */
export declare function gitOptionRefusal(word: string, path: string, spec: CommandSpec): [string, string];
/**
 * The options a clap usage line echoes back, in clap's order.
 *
 * clap reprints the options the line carried, in the order they were typed,
 * then the ones an environment variable supplied. A *defaulted* option is not
 * among them: pinned against ntn 0.21.9, whose --limit declares `[default: 25]`
 * and never appears unless it was typed.
 *
 * @param spec the leaf's grammar, for spellings and value names
 * @param typed dests the line carried, in scan order (canonical dashed
 *   spellings, the key space the parser records flags under)
 * @param env the session environment, read for the options that declare one
 */
export declare function clapSupplied(spec: CommandSpec, typed: readonly string[], env: Readonly<Record<string, string>>): string[];
/**
 * clap's refusal for required operands the line did not supply.
 *
 * Pinned against ntn 0.21.9: the empty slots are listed one per line under a
 * fixed heading, then a usage line that carries the options the line supplied
 * and every operand slot, then the "try --help" footer. The usage line names
 * only what was supplied, which is why it is rebuilt here rather than taken
 * from the help page.
 *
 * @param prog the full display path of the leaf ("ntn pages get")
 * @param spec the leaf's grammar
 * @param missing bare names of the empty required slots
 * @param typed dests the line carried, in scan order
 * @param env the session environment
 */
export declare function clapMissingOperands(prog: string, spec: CommandSpec, missing: readonly string[], typed: readonly string[], env: Readonly<Record<string, string>>): Uint8Array;
/**
 * The message and exit code a leaf answers a bad option with.
 *
 * A leaf usage error exits 2 under argparse's style regardless of the GNU
 * USAGE_EXIT table, because an installed CLI name is never a GNU tool with its
 * own pinned exit. git exits 129 for the same mistake, which is neither that
 * nor its own 128 for a fatal. clap exits 2, agreeing with argparse by
 * coincidence rather than by lineage.
 *
 * git answers in parse-options' words, and some of them print the verb's
 * usage block: after an unknown option or an ambiguous abbreviation on
 * stderr, and on stdout for `-h`, which exits 0 (git 2.56). A missing value is
 * one line, a long named an "option" and a short one a "switch" (pinned
 * against git 2.50.1).
 *
 * @param style the dialect the CLI's root declares
 * @param argparseMessage the message the spec machinery built, used as-is for
 *   argparse and for anything another style words the same
 * @param parsed the parse, read for the offending tokens when the style
 *   rewrites the message
 * @param path the leaf's path under its head word, for git's synopsis
 * @param spec the leaf's grammar, for git's option rows
 * @returns the stderr, the exit code and the stdout, null when the refusal
 *   writes nothing there
 */
export declare function leafRefusal(style: UsageStyle, argparseMessage: Uint8Array, parsed: Pick<ParsedCommand, 'invalidOptions' | 'ambiguousOptions' | 'optionErrorKinds' | 'needsValueOptions'>, path: string, spec: CommandSpec): [Uint8Array, number, Uint8Array | null];
/** Render failure to enter a CLI's declared operand base. */
export declare function directoryRefusal(prog: string, path: string, reason: FsCondition, style: UsageStyle): [Uint8Array, number];
//# sourceMappingURL=refusal.d.ts.map