@struktoai/mirage-core/dist/commands/spec/usage.d.ts

A Unified Virtual Filesystem For AI Agents

import { UsageError } from '../errors.ts';
import type { WordChoices, WordRefusalKind } from './word_choice.ts';
/**
 * GNU usage-error exit code for a command.
 *
 * `builtin` says whether the line was parsed against the builtin's own
 * grammar. The per-program voices and codes describe the real program, so a
 * command registered under its name answers like any other custom command.
 */
export declare function usageExitCode(cmdName: string, builtin?: boolean): number;
/** Exit code of a command refused on one operand before it ran. */
export declare function operandExitCode(cmdName: string): number;
export declare function readFailExitCode(cmdName: string, err: unknown): number;
/**
 * The same code, for a read failure known only as a rendered line.
 *
 * The cross-mount stream path fetches each operand with a native `cat`
 * sub-run, so a failed operand arrives as cat's rendered stderr rather
 * than as an error. That line is already respelled into the real
 * command's voice, and the exit code has to follow it or `sort a
 * /other/missing` answers 1 while `sort missing` answers 2, a split GNU
 * does not have. Classified against the very strerrors the renderer
 * wrote, so the forward and backward directions cannot drift; a blob that
 * carries no failed-read line keeps the catch-all 1.
 *
 * One fetch can render several lines, because one operand can be a glob
 * the owning mount expanded, and the most severe code is the answer: sed
 * is the only stream command whose code depends on the errno, and its rule
 * is the most severe (4 beats 2), which is also how the caller folds one
 * operand's code into the next.
 *
 * Mirrors the python `read_fail_exit_line`.
 */
export declare function readFailExitCodeFromLine(cmdName: string, rendered: string): number;
/**
 * curl's option refusal: one message line, then its own help hint.
 *
 * Pinned on curl 8.14.1 (debian:stable-slim). One divergence: curl names
 * a whole cluster with a bad letter (`option -sW: is unknown`) where the
 * parser reports the letter, so mirage says `option -W`.
 */
export declare function curlOptionError(line: string): [Uint8Array, number];
export declare function unknownOptionError(cmdName: string, token: string, builtin?: boolean): [Uint8Array, number];
/** Whether zgrep refuses a grep option itself (gzip 1.13). */
export declare function zgrepUnsupported(token: string): boolean;
/**
 * ripgrep's refusal of a flag it does not have (14.1.1): the flag as typed
 * without its value, then the similar flags its own table holds, if any:
 * `rg --colo` suggests `--color, --colors`, and `rg --pcr` suggests nothing.
 * No usage hint follows.
 */
export declare function rgUnknownFlag(token: string): [Uint8Array, number];
export declare function similarRgFlags(unrecognized: string): string[];
/**
 * getopt_long refusal for a BOOLEAN long option handed a value.
 *
 * `grep --byte-offset=2` is not an unrecognized option -- getopt_long
 * recognized it perfectly well and refused the `=2`, so the message names the
 * option and drops the value, where the unrecognized-option message quotes the
 * whole token including it. It also names the CANONICAL spelling, not the one
 * that was typed: `grep --byte=2` answers for `--byte-offset`. Shape pinned
 * against GNU grep 3.11 and coreutils 9.4 (`grep --byte-offset=2`,
 * `grep --line-buffered=2`, `nl --help=2`, `cut --complement=2`,
 * `sed --debug=2`), all exit 2 for grep and sort and 1 for the coreutils.
 *
 * GNU's per-tool usage dump is deliberately omitted, exactly as
 * unknownOptionError omits it; grep and sed print theirs between the message
 * and the hint, coreutils print none at all.
 *
 * `token` is the option's canonical long spelling and the value that was typed
 * on it ('--byte-offset=2'). It is carried whole because the programs in
 * NOT_GETOPT_LONG quote the value along with the option and getopt_long drops
 * it.
 */
export declare function unexpectedValueError(cmdName: string, token: string, builtin?: boolean): [Uint8Array, number];
/**
 * getopt_long refusal for an abbreviated long matching several options.
 *
 * Shape pinned against real GNU (`grep --c`): the typed spelling, then
 * every possibility quoted in declaration order on one line. The
 * per-tool usage dump GNU appends is deliberately omitted, like
 * unknownOptionError.
 */
export declare function ambiguousOptionError(cmdName: string, token: string, candidates: readonly string[], builtin?: boolean): [Uint8Array, number];
/**
 * Refusal for a non-integer value on an int-typed option.
 *
 * No GNU tool declares types through getopt (each words its own refusal,
 * e.g. `head: invalid number of lines`), so this mirrors argparse's
 * `invalid int value: 'abc'` with the option attributed the way
 * invalidArgumentError does.
 */
export declare function invalidIntError(cmdName: string, option: string, value: string, builtin?: boolean): [Uint8Array, number];
/**
 * Refusal for a non-number value on a float-typed option. Mirrors
 * argparse's `invalid float value: '5x'` the same way invalidIntError
 * mirrors the int wording.
 */
export declare function invalidFloatError(cmdName: string, option: string, value: string, builtin?: boolean): [Uint8Array, number];
/** GNU-shaped error for a declared value flag with no argument left. */
export declare function missingValueError(cmdName: string, token: string, builtin?: boolean): [Uint8Array, number];
/**
 * GNU tar refusal for an old-style cluster letter with no argument.
 *
 * First line and exit pinned against GNU tar 1.35 (`tar xzf` with
 * nothing after it, and `tar cfC a.tar`, which names C). tar's own
 * wording, capital and full stop included, because it counts the
 * cluster's argument needs before argp sees the line at all.
 *
 * The hint line is deliberately mirage's, not GNU's: GNU offers
 * `Try 'tar --help' or 'tar --usage' for more information.` because argp
 * gives every argp program a `--usage`, and mirage's tar serves only
 * `--help`. Naming a flag that does not exist would be worse than the
 * shorter hint, and every other refusal here words it this way, so tar's
 * two refusals stay consistent with each other.
 */
export declare function oldOptionError(cmdName: string, letter: string, builtin?: boolean): [Uint8Array, number];
/**
 * The first line of GNU's word-choice refusal, without its newline.
 *
 * Two wordings, and the CALLER's match result picks between them: the
 * wording is a property of how `matchWord` refused the value, not of the
 * value itself, so it arrives from there rather than being re-derived
 * here. There is deliberately no `value === ''` branch: the
 * empty word is ambiguous because it is a prefix of every candidate and
 * those candidates span two or more values, which is the same rule every
 * other word goes through and is what `tail --follow=`, `sort --check=`,
 * `wc --total=`, `uniq --all-repeated=`, `uniq --group=`, `ls --format=`,
 * `ls -l --time-style=`, `cp --update=` and `tee --output-error=` were
 * all measured answering `ambiguous argument ''` for. Re-adding the
 * special case would get those right and a one-candidate slot wrong.
 * `du --max-depth=` is NOT a word choice and says `invalid maximum depth ''`,
 * which is why that one is worded in du.
 *
 * The word is rendered through `quoteText`, quoted as GNU quotes it:
 * `tee --output-error=xé` is `invalid argument 'x\303\251'`. Callers must
 * therefore pass the value as typed and never pre-escape it.
 *
 * `word_refusal_line` in usage.py is the twin.
 */
export declare function wordRefusalLine(cmdName: string, option: string, value: string, kind?: WordRefusalKind): string;
/** GNU's `Valid arguments are:` block, without a trailing newline. */
export declare function validWordsBlock(choices: WordChoices): string;
/**
 * GNU's refusal of a value outside a declared choices set.
 *
 * Shape pinned against real GNU (`tee --output-error=bogus`): the
 * offending value, the option's canonical long spelling, then every valid
 * argument in declaration order, aliases of one value on one line, then
 * the `Try '--help'` hint.
 *
 * `exitCode` undefined takes the command's own usage code, which is 1 for
 * every command that reaches this renderer through the executor. ls and
 * sort pass 1 explicitly: GNU exits 1 on a refused word even though their
 * other usage errors are 2.
 */
export declare function invalidArgumentError(cmdName: string, option: string, value: string, choices: WordChoices, exitCode?: number, kind?: WordRefusalKind, builtin?: boolean): [Uint8Array, number];
/**
 * `invalidArgumentError` as the error a command throws.
 *
 * The commands that validate a word-choice value themselves (`sort`, `wc`,
 * `uniq`, `ls`, `cp`, `tail`) hold the value long after the parser is done
 * with it, so they render through the same function the executor does
 * rather than wording a second copy.
 *
 * `word_refusal_error` in usage.py is the twin.
 */
export declare function wordRefusalError(cmdName: string, option: string, value: string, choices: WordChoices, exitCode?: number, kind?: WordRefusalKind): UsageError;
/**
 * Refusal for a declared required option absent from the line.
 *
 * No GNU tool declares required options through getopt, so there is no
 * GNU shape to pin; this follows the unrecognized-option pattern (click
 * reports the same condition as "Missing option").
 */
export declare function missingRequiredError(cmdName: string, option: string, builtin?: boolean): [Uint8Array, number];
/**
 * The `Try '<cmd> --help'` line as that command prints it.
 *
 * coreutils writes the hint bare; diffutils routes it through `error()`,
 * so cmp and diff carry the command prefix on the hint line too.
 */
export declare function usageHint(cmdName: string, builtin?: boolean): string;
/**
 * GNU-shaped usage error for an operand past a command's arity.
 *
 * Shapes pinned against real GNU: `<cmd>: extra operand '<arg>'` with the
 * `Try '--help'` hint (diff and cmp prefix the hint line with the command
 * name; mktemp says `too many templates` with no operand). The operand must
 * be the as-typed spelling (`rawPath`), never the resolved path.
 */
export declare function extraOperandError(cmdName: string, operand: string): UsageError;
/**
 * GNU-shaped usage error for an operand short of a command's arity.
 *
 * Shapes pinned against real GNU: `<cmd>: missing operand after '<arg>'`
 * names `argv[argc - 1]` once getopt has moved the operands behind the
 * options, which is the last operand given, or the line's last word for a
 * program that reads its operands in order (join). With none given,
 * coreutils says a bare `missing operand`, while diffutils still names the
 * line's last word, an option or its value included (`cmp: missing operand
 * after '-s'`, `diff -U 3` names `3`), and the program itself on a bare line
 * (`cmp: missing operand after 'cmp'`; diffutils 3.10). `argv` is the
 * line's words after the command name. Mirrors Python's
 * missing_operand_error.
 */
export declare function missingOperandError(cmdName: string, last: string | null, argv?: readonly string[]): UsageError;
//# sourceMappingURL=usage.d.ts.map