@struktoai/mirage-core/dist/workspace/executor/builtins/shared.d.ts

A Unified Virtual Filesystem For AI Agents

import { FlagView } from '../../../commands/spec/flag_view.ts';
import type { RedirectResult } from '../../../context/session_context.ts';
import { IOResult } from '../../../io/types.ts';
import type { PolicyDenied } from '../../../policy/errors.ts';
import type { DispatchFn } from '../../../runtime/types.ts';
import { PathSpec } from '../../../types.ts';
import type { SessionView } from '../../../view/types.ts';
import type { Namespace } from '../../mount/namespace/namespace.ts';
import type { ParsedCommand } from '../command/types.ts';
/**
 * Build the (stream, IOResult, ExecutionNode) triple builtins return.
 *
 * @param cmd - command name recorded on the ExecutionNode.
 * @param init - `out` stdout payload; `exitCode` for both results; `stderr`
 *   error text encoded onto both; `io` a prebuilt IOResult to reuse (e.g.
 *   carrying writes), whose exitCode/stderr are overwritten.
 */
export declare function result(cmd: string, init?: {
    out?: Uint8Array | null;
    exitCode?: number;
    stderr?: string;
    io?: IOResult;
}): RedirectResult;
export declare function ok(cmd: string, out?: Uint8Array | null): RedirectResult;
export declare function fail(cmd: string, message: string, exitCode?: number): RedirectResult;
/**
 * Close an operand loop: exit 1 with joined stderr when any operand failed,
 * exit 0 otherwise.
 *
 * @param cmd - command name.
 * @param errors - per-operand error messages collected so far.
 * @param io - prebuilt IOResult to reuse (e.g. carrying writes).
 */
export declare function finish(cmd: string, errors: string[], io?: IOResult): RedirectResult;
/**
 * Parse a builtin's words with its spec, the way getopt_long does: options
 * may follow operands until `--`, long options take their unique
 * abbreviations, and a bad one is refused in GNU's words with the `Try`
 * line. The operands keep the PathSpecs the classifier made. Mirrors
 * Python's parse_line.
 *
 * @param cmd - the builtin's name.
 * @param args - the classified words after the name.
 * @param cwd - the session working directory.
 */
export declare function parseLine(cmd: string, args: readonly (string | PathSpec)[], cwd: string): [ParsedCommand, FlagView, RedirectResult | null];
/**
 * A path operand as an absolute virtual path.
 *
 * @param arg - a classified command part.
 * @param cwd - session working directory for relative operands.
 */
export declare function absPath(arg: string | PathSpec, cwd: string): string;
export interface SplitValueFlags {
    flags: Set<string>;
    values: Map<string, string>;
    operands: (string | PathSpec)[];
    bad: string | null;
}
/**
 * Split leading flags where some take a value (`-t STAMP`), strictly: an
 * unknown letter is reported instead of tolerated.
 *
 * @param args - args after the command name.
 * @param boolean - single-letter flags with no value.
 * @param valued - single-letter flags that consume the next arg.
 */
export declare function splitValueFlags(args: readonly (string | PathSpec)[], boolean: string, valued: string): SplitValueFlags;
/**
 * Coerce operands to PathSpec and expand glob patterns per mount, through the
 * dispatcher's listings.
 *
 * A pattern spec only exists for a mounted word (classification gates it), so
 * the lookup propagates on a miss; a backend that lists nothing keeps the
 * literal spec.
 *
 * @param namespace - addressing authority (mount lookup).
 * @param dispatch - op dispatcher the patterns list through.
 * @param operands - positional operands.
 */
export declare function expandOperands(namespace: Namespace, dispatch: DispatchFn, operands: readonly (string | PathSpec)[]): Promise<PathSpec[]>;
/**
 * The gated session view this builtin writes through.
 *
 * Every session write goes through the workspace's gated view, which is
 * what makes `preSession` rules enforceable; this used to fall back to
 * an ungated view over the same session, so a caller that forgot to
 * thread one silently wrote past every policy. A write reached without
 * a view is a wiring bug, not a mode, so it throws.
 */
export declare function requireView(state: SessionView | null): SessionView;
/** Render a policy denial in the builtin's own voice. */
export declare function refusal(cmd: string, err: PolicyDenied): RedirectResult;
/**
 * The shell's own readonly refusal line, checked before the session view.
 * `declare`, `local` and `typeset` name themselves in it (`bash: declare: R:
 * readonly variable`); every other writer refuses in the assignment's voice
 * (`bash: R: readonly variable`).
 */
export declare function readonlyLine(cmd: string, name: string): string;
/** Render the readonly refusal (`readonlyLine`) as the result. */
export declare function readonlyRefusal(cmd: string, name: string): RedirectResult;
/** A count option's value (`read -n`/`-N`, `mapfile -n`/`-s` and the rest): a run of ASCII digits, else null. */
export declare function countOperand(text: string): number | null;
/** Whether the word is a shell identifier. */
export declare function isValidName(name: string): boolean;
/**
 * Whether the word is an optionally signed run of digits, which is what
 * `shift`, `return` and `exit` accept as their argument.
 */
export declare function isCountWord(word: string): boolean;
/** A shell builtin's diagnostic in bash's voice. Mirrors Python's builtin_error. */
export declare function builtinError(name: string, message: string): Uint8Array;
/**
 * A builtin's usage line, which bash prints after refusing one of its
 * options: the synopsis `help NAME` opens with. Mirrors Python's
 * builtin_usage.
 */
export declare function builtinUsage(name: string): string;
/**
 * The words a numeric builtin reads: a leading `--` ends its options, and
 * bash skips it before it reads the number. Mirrors Python's numeric_operands.
 */
export declare function numericOperands(args: readonly string[]): readonly string[];
/** A count word's value modulo 256, the status bash keeps of it. */
export declare function statusOf(word: string): number;
/**
 * The byte `read -d` and `mapfile -d` stop at. Bash takes the first byte of
 * the argument, not its first character (bash 5.2: `-d é` stops at 0xc3,
 * `-d $'\xff'` at the raw byte); an empty argument is NUL and no `-d` is a
 * newline. Mirrors Python's record_delimiter.
 */
export declare function recordDelimiter(text: string | null): number;
//# sourceMappingURL=shared.d.ts.map