@sema-agent/core/dist/tools/fs/shell-read-builtins.d.ts

Stateless, task-oriented AI agent core

/**
 * WHETHER A BUILTIN RUNS BY ITS NAME — a binding of the same ordered thread as a variable's or a function's
 * (`shell-read-bindings.ts`). `enable -n NAME` disables a builtin (the word then finds no command: "command not found"),
 * `enable NAME` enables it again, and every builtin starts a text enabled. The thread keeps this the way it keeps a
 * function's definition, under a key neither a variable nor a function can spell, and a reader at a segment asks the one
 * ordered rule ({@link BuiltinState}) before it takes a word for the builtin of its name; this module is the vocabulary of
 * that key and the reading of an `enable` into bindings.
 */
import type { LexedWord } from "../../shell/lex.js";
import type { Binding, BoundValue, NameState } from "./shell-read-bindings.js";
/** What a builtin is at a reader: `enabled` — it certainly runs by its name; `disabled` — it certainly does not (`enable -n`:
 *  "command not found"); `maybe` — an `enable` that may not have run, a call that may have run one, one for every builtin. */
export type BuiltinState = "enabled" | "maybe" | "disabled";
/** The builtin whose words are read into the availability of the others. */
export declare const ENABLE_BUILTIN = "enable";
export declare const builtinKey: (name: string) => string;
export declare const isBuiltinKey: (name: string) => boolean;
/** Every builtin at once (`enable -f FILE` loads one over any name; a name the text computes may be any). */
export declare const BUILTINS_ALL: string;
export declare const BUILTIN_ENABLED: NameState;
export declare const isDisabledValue: (v: BoundValue) => boolean;
/** What the shell finds looking up each word of a chain it runs as builtins (`builtin` / `command` in front, then the name): the
 *  same reading ({@link BuiltinState}) for every word, since the chain runs no further than its first word that finds no command —
 *  one that certainly does not run makes the chain certainly not run, and one that may not makes it so. `ask` absent: all enabled. */
export declare function chainAvailability(words: readonly string[], ask: ((builtin: string) => BuiltinState) | undefined): BuiltinState;
/** Does an entry (or a made-unreadable name) with this name speak for `name`: no name (every name), the name itself, or —
 *  for a builtin's key — every builtin at once. */
export declare const speaksFor: (subject: string | undefined, name: string) => boolean;
/** The bindings an `enable [-a] [-dnps] [-f FILE] [NAME…]` makes: `enable NAME` enables each name, `enable -n NAME` disables it
 *  (a literal name: its key); any other switch — `-f FILE` loads a builtin over any name, `-d`, the listing switches — or a
 *  name the text computes may change every builtin; a bare listing (`enable`, `enable -n`) changes none. The words in front of
 *  the first name are read as the shell reads them: a word opening with `-` (but a lone `-`, which is a name) is switches, `--`
 *  ends them, and a letter outside the switches is an invalid option — the shell rejects the whole call (status 2) and nothing
 *  changes, whatever else the call says; a word after the first name is a name. */
export declare function enableBindings(args: readonly LexedWord[]): Binding[];