@better-fs-tools/shell 0.0.0-tegami-trusted-publish-setup → 0.2.0

package/dist/core/stages.d.ts

@@ -0,0 +1,20 @@
+import type { Note, ToolCallContext } from "@better-fs-tools/read";
+import type { ShellDependencies } from "../contract/deps.ts";
+import type { PlannedRun, ShellHookContext } from "../contract/extensions.ts";
+import type { ShellPhase } from "../contract/result.ts";
+import type { CommandRunner } from "../contract/runner.ts";
+import { StageStop } from "./stop.ts";
+export interface CallScope<THost> {
+    readonly deps: ShellDependencies<THost>;
+    readonly call: ToolCallContext<THost>;
+    readonly notes: Note[];
+    readonly ctx: ShellHookContext<THost>;
+}
+export declare function extensionFailure<THost>(scope: Pick<CallScope<THost>, "deps">, extension: unknown, phase: ShellPhase): StageStop;
+export declare function runnerFor<THost>(deps: ShellDependencies<THost>, call: ToolCallContext<THost>): CommandRunner;
+export declare function baseCwd<THost>(deps: ShellDependencies<THost>, call: ToolCallContext<THost>, runner: CommandRunner): string;
+export declare function resolveCwd<THost>(scope: CallScope<THost>, base: string, requested: string | null): Promise<string>;
+export declare function beforeRun<THost>(scope: CallScope<THost>, planned: PlannedRun): Promise<PlannedRun>;
+export declare function authorize<THost>(scope: CallScope<THost>, run: PlannedRun, base: string): Promise<void>;
+export declare function relativePosix(base: string, path: string): string;
+export declare function environment<THost>(scope: CallScope<THost>, run: PlannedRun): Promise<Readonly<Record<string, string>>>;

package/dist/core/stages.js

@@ -0,0 +1,166 @@
+import { containsPosix, posixPaths, resolvePosix } from "@better-fs-tools/fs";
+import { AbortStop, raceAbort } from "./abort.js";
+import { isAbsolute, isRunner } from "./deps.js";
+import { isRecord } from "./input.js";
+import { StageStop, errorNote, extensionId, hostErrorNote, isNote, isNoteList } from "./stop.js";
+export function extensionFailure(scope, extension, phase) {
+    const message = scope.deps.messages.extensionFailed({ extension: extensionId(extension), phase });
+    return new StageStop("EXTENSION_FAILED", phase, errorNote("EXTENSION_FAILED", message));
+}
+async function hostCall(scope, extension, phase, start) {
+    try {
+        return await raceAbort(start, scope.call.signal);
+    }
+    catch (error) {
+        if (error instanceof AbortStop)
+            throw new AbortStop(phase);
+        throw extensionFailure(scope, extension, phase);
+    }
+}
+export function runnerFor(deps, call) {
+    const { runner } = deps;
+    if (typeof runner !== "function")
+        return runner;
+    let made;
+    try {
+        made = runner(call);
+    }
+    catch {
+        throw extensionFailure({ deps }, { id: "runner" }, "run");
+    }
+    if (!isRunner(made))
+        throw extensionFailure({ deps }, { id: "runner" }, "run");
+    return made;
+}
+export function baseCwd(deps, call, runner) {
+    const { cwd } = deps;
+    if (cwd === null)
+        return runner.cwd;
+    if (typeof cwd === "string")
+        return cwd;
+    let made;
+    try {
+        made = cwd(call);
+    }
+    catch {
+        throw extensionFailure({ deps }, { id: "cwd" }, "resolve");
+    }
+    if (!isAbsolute(made))
+        throw extensionFailure({ deps }, { id: "cwd" }, "resolve");
+    return made;
+}
+export async function resolveCwd(scope, base, requested) {
+    if (requested === null)
+        return base;
+    const resolver = scope.deps.resolve;
+    if (resolver === null)
+        return resolvePosix(base, requested);
+    const ctx = {
+        ...scope.ctx,
+        paths: posixPaths,
+        list: async () => ({
+            ok: false,
+            error: { reason: "unsupported", detail: "the bash tool cannot list" },
+        }),
+    };
+    const outcome = await hostCall(scope, resolver, "resolve", () => resolver.resolve(requested, ctx));
+    const malformed = () => extensionFailure(scope, resolver, "resolve");
+    if (!isRecord(outcome))
+        throw malformed();
+    const { note } = outcome;
+    if (note !== undefined && !isNote(note))
+        throw malformed();
+    if (note !== undefined)
+        scope.notes.push(note);
+    if (outcome.kind === "not-found") {
+        const message = scope.deps.messages.cwdNotFound({ cwd: requested });
+        throw new StageStop("CWD_NOT_FOUND", "resolve", errorNote("CWD_NOT_FOUND", message));
+    }
+    const { path } = outcome;
+    if (outcome.kind !== "path" || typeof path !== "string" || path.trim() === "")
+        throw malformed();
+    return resolvePosix(base, path);
+}
+export async function beforeRun(scope, planned) {
+    let run = planned;
+    for (const hook of scope.deps.beforeRun) {
+        const current = run;
+        const decision = await hostCall(scope, hook, "beforeRun", () => hook.beforeRun(current, scope.ctx));
+        const malformed = () => extensionFailure(scope, hook, "beforeRun");
+        if (!isRecord(decision))
+            throw malformed();
+        if (decision.allow === false) {
+            if (decision.note !== undefined && !isNote(decision.note))
+                throw malformed();
+            const note = decision.note === undefined
+                ? errorNote("REFUSED", scope.deps.messages.refused({ hook: hook.id }))
+                : hostErrorNote("REFUSED", decision.note);
+            throw new StageStop("REFUSED", "beforeRun", note);
+        }
+        if (decision.allow !== true)
+            throw malformed();
+        const { command, notes } = decision;
+        if (notes !== undefined && !isNoteList(notes))
+            throw malformed();
+        if (command !== undefined) {
+            if (typeof command !== "string" || command.trim() === "" || command.includes("\u0000")) {
+                throw malformed();
+            }
+            run = { ...run, command };
+        }
+        scope.notes.push(...(notes ?? []));
+    }
+    return run;
+}
+export async function authorize(scope, run, base) {
+    const authorizer = scope.deps.authorize;
+    if (authorizer === null)
+        return;
+    const target = {
+        action: "run",
+        requestedPath: scope.ctx.request.cwd ?? ".",
+        resolvedPath: run.cwd,
+        displayPath: relativePosix(base, run.cwd),
+        command: run.command,
+        cwd: run.cwd,
+        timeoutMs: run.timeoutMs,
+    };
+    const decision = await hostCall(scope, authorizer, "authorize", () => authorizer.authorize(target, scope.ctx));
+    const malformed = () => extensionFailure(scope, authorizer, "authorize");
+    if (!isRecord(decision))
+        throw malformed();
+    if (decision.allow === true) {
+        if (decision.notes !== undefined && !isNoteList(decision.notes))
+            throw malformed();
+        scope.notes.push(...(decision.notes ?? []));
+        return;
+    }
+    if (decision.allow !== false)
+        throw malformed();
+    if (decision.note !== undefined && !isNote(decision.note))
+        throw malformed();
+    const note = decision.note === undefined
+        ? errorNote("DENIED", scope.deps.messages.denied({ path: run.cwd, detail: null }))
+        : hostErrorNote("DENIED", decision.note);
+    throw new StageStop("DENIED", "authorize", note);
+}
+export function relativePosix(base, path) {
+    if (path === base)
+        return ".";
+    if (containsPosix(base, path))
+        return path.slice(base === "/" ? 1 : base.length + 1);
+    const from = base.split("/").filter(Boolean);
+    const to = path.split("/").filter(Boolean);
+    let shared = 0;
+    while (shared < from.length && shared < to.length && from[shared] === to[shared])
+        shared += 1;
+    return [...from.slice(shared).map(() => ".."), ...to.slice(shared)].join("/");
+}
+export async function environment(scope, run) {
+    const { env } = scope.deps;
+    const made = await hostCall(scope, { id: "env" }, "env", () => env(run, scope.ctx));
+    if (!isRecord(made) || !Object.values(made).every((value) => typeof value === "string")) {
+        throw extensionFailure(scope, { id: "env" }, "env");
+    }
+    return made;
+}

package/dist/core/stop.d.ts

@@ -0,0 +1,17 @@
+import type { JsonObject, Note } from "@better-fs-tools/read";
+import type { ShellErrorCode, ShellPhase } from "../contract/result.ts";
+export declare class StageStop extends Error {
+    readonly code: ShellErrorCode;
+    readonly phase: ShellPhase;
+    readonly note: Note;
+    constructor(code: ShellErrorCode, phase: ShellPhase, note: Note);
+}
+export declare function warning(code: string, message: string, data?: JsonObject): Note;
+export declare function info(code: string, message: string, data?: JsonObject): Note;
+export declare function noteCode(code: ShellErrorCode): string;
+export declare function errorNote(code: ShellErrorCode, message: string, data?: JsonObject): Note;
+export declare function hostErrorNote(code: ShellErrorCode, note: Note): Note;
+export declare function isNote(value: unknown): value is Note;
+export declare function isNoteList(value: unknown): value is readonly Note[];
+export declare function messageOf(error: unknown): string;
+export declare function extensionId(extension: unknown): string;

package/dist/core/stop.js

@@ -0,0 +1,50 @@
+export class StageStop extends Error {
+    code;
+    phase;
+    note;
+    constructor(code, phase, note) {
+        super(code);
+        this.code = code;
+        this.phase = phase;
+        this.note = note;
+    }
+}
+export function warning(code, message, data) {
+    return data === undefined
+        ? { code, severity: "warning", message }
+        : { code, severity: "warning", message, data };
+}
+export function info(code, message, data) {
+    return data === undefined
+        ? { code, severity: "info", message }
+        : { code, severity: "info", message, data };
+}
+export function noteCode(code) {
+    return code.toLowerCase().replaceAll("_", "-");
+}
+export function errorNote(code, message, data) {
+    return warning(noteCode(code), message, data);
+}
+export function hostErrorNote(code, note) {
+    const kebab = noteCode(code);
+    return errorNote(code, note.message, note.code === kebab ? note.data : { ...note.data, source: note.code });
+}
+export function isNote(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const note = value;
+    return (typeof note.code === "string" &&
+        typeof note.message === "string" &&
+        (note.severity === "info" || note.severity === "warning"));
+}
+export function isNoteList(value) {
+    return Array.isArray(value) && value.every(isNote);
+}
+export function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function extensionId(extension) {
+    if (extension === null || typeof extension !== "object" || !("id" in extension))
+        return "unknown";
+    return typeof extension.id === "string" ? extension.id : "unknown";
+}

package/dist/formatters/default.d.ts

@@ -0,0 +1,20 @@
+import type { Note } from "@better-fs-tools/read";
+import type { ShellFormatter } from "../contract/format.ts";
+export interface ShellFormatterOptions {
+    /** Filter or rewrite a note for the model text. null hides it. Default: show every note. */
+    readonly notes?: (note: Note) => Note | null;
+    /** Default: `[bash:${note.code}] ${note.message}`. */
+    readonly noteLine?: (note: Note) => string;
+}
+/**
+ * The status line, then the output view, then a blank line and the note
+ * lines. A call that did not run prints the note lines only. "view" mode
+ * leaves out the notes. The `notes` option hides or rewrites a note, as the
+ * read tool's formatters do.
+ *
+ * ```text
+ * Exit code 1 · 0.4 s
+ * <output>
+ * ```
+ */
+export declare function defaultShellFormatter(options?: ShellFormatterOptions): ShellFormatter<unknown>;

package/dist/formatters/default.js

@@ -0,0 +1,77 @@
+/**
+ * The status line, then the output view, then a blank line and the note
+ * lines. A call that did not run prints the note lines only. "view" mode
+ * leaves out the notes. The `notes` option hides or rewrites a note, as the
+ * read tool's formatters do.
+ *
+ * ```text
+ * Exit code 1 · 0.4 s
+ * <output>
+ * ```
+ */
+export function defaultShellFormatter(options = {}) {
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("defaultShellFormatter options must be an object");
+    }
+    const { notes: filter = showNote, noteLine = defaultNoteLine } = options;
+    if (typeof filter !== "function")
+        throw new TypeError("notes must be a function");
+    if (typeof noteLine !== "function")
+        throw new TypeError("noteLine must be a function");
+    return Object.freeze({
+        id: "default",
+        format(report, ctx) {
+            const main = body(report, ctx.messages);
+            if (ctx.mode === "view")
+                return main.join("\n");
+            const notes = noteLines(report.notes, filter, noteLine);
+            if (notes.length === 0)
+                return main.join("\n");
+            if (main.length === 0)
+                return notes.join("\n");
+            return `${main.join("\n")}\n\n${notes.join("\n")}`;
+        },
+    });
+}
+function noteLines(notes, filter, line) {
+    const lines = [];
+    for (const note of notes) {
+        const shown = filter(note);
+        if (shown !== null)
+            lines.push(line(shown));
+    }
+    return lines;
+}
+function showNote(note) {
+    return note;
+}
+function defaultNoteLine(note) {
+    return `[bash:${note.code}] ${note.message}`;
+}
+function body(report, messages) {
+    const { run, output } = report;
+    if (run === null)
+        return [];
+    return [statusLine(run, messages), ...outputLines(output, messages)];
+}
+function statusLine(run, messages) {
+    if (run.stoppedBy === "timeout")
+        return messages.timedOut({ timeoutMs: run.timeoutMs });
+    return messages.exited({ code: run.exitCode, signal: run.signal, durationMs: run.durationMs });
+}
+function outputLines(output, messages) {
+    if (output === null || (output.head === "" && output.tail === null))
+        return [messages.noOutput()];
+    if (output.tail === null)
+        return [output.head];
+    const gap = messages.omitted({
+        lines: output.omittedLines,
+        bytes: output.omittedBytes,
+        spill: output.spill,
+    });
+    return [
+        ...(output.head === "" ? [] : [output.head]),
+        gap,
+        ...(output.tail === "" ? [] : [output.tail]),
+    ];
+}

package/dist/formatters/index.d.ts

@@ -0,0 +1,2 @@
+export { defaultShellFormatter } from "./default.ts";
+export type { ShellFormatterOptions } from "./default.ts";

package/dist/formatters/index.js

@@ -0,0 +1 @@
+export { defaultShellFormatter } from "./default.js";

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export type { BashInput, BashRequest } from "./contract/input.ts";
+export type { BashTool } from "./contract/context.ts";
+export type { CommandRunner, OutputChunk, RunExit, RunHandle, RunRequest, RunStartError, } from "./contract/runner.ts";
+export type { ShellError, ShellErrorCode, ShellFailure, ShellOutput, ShellPhase, ShellReport, ShellResult, ShellRun, ShellRunReport, ShellStatus, } from "./contract/result.ts";
+export type { ShellDependencies, ShellToolDeps } from "./contract/deps.ts";
+export type { AfterRunHook, AfterRunUpdate, BeforeRunDecision, BeforeRunHook, PlannedRun, RunOutcome, ShellAuthorizer, ShellAuthorizeTarget, ShellEnv, ShellHookContext, SpillSink, SpillWriter, } from "./contract/extensions.ts";
+export type { ShellFormatContext, ShellFormatter } from "./contract/format.ts";
+export type { ShellLimits } from "./contract/limits.ts";
+export type { ShellCanonicalParam, ShellMessageCatalog } from "./contract/messages.ts";
+export { createBashTool } from "./core/create-bash-tool.ts";
+export { parseBashInput } from "./core/input.ts";
+export { defaultShellLimits, resolveShellLimits } from "./core/limits.ts";
+export { defaultShellMessages, formatBytes, formatDuration, resolveShellMessages, } from "./core/messages.ts";
+export { defaultShellEnv, shellEnv } from "./core/env.ts";
+export { defaultShellFormatter } from "./formatters/index.ts";
+export type { ShellFormatterOptions } from "./formatters/index.ts";
+export { textOf } from "@better-fs-tools/read";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { createBashTool } from "./core/create-bash-tool.js";
+export { parseBashInput } from "./core/input.js";
+export { defaultShellLimits, resolveShellLimits } from "./core/limits.js";
+export { defaultShellMessages, formatBytes, formatDuration, resolveShellMessages, } from "./core/messages.js";
+export { defaultShellEnv, shellEnv } from "./core/env.js";
+export { defaultShellFormatter } from "./formatters/index.js";
+export { textOf } from "@better-fs-tools/read";

package/dist/signature/bash.d.ts

@@ -0,0 +1,28 @@
+import type { SignatureDocs, ToolSignature } from "@better-fs-tools/read";
+import type { BashInput } from "../contract/input.ts";
+import type { ShellLimits } from "../contract/limits.ts";
+import type { ShellCanonicalParam, ShellMessageCatalog } from "../contract/messages.ts";
+/** The bash tool's model-facing signature, with `duration` for the timeout unit. */
+export interface BashSignature extends ToolSignature<BashInput, ShellCanonicalParam> {
+    /** A duration in the unit of the timeout parameter, for messages. */
+    duration(ms: number): string;
+}
+/** The parameter names of `defaultBashSignature`. */
+export type BashParam = "command" | "timeout" | "cwd";
+export interface BashSignatureOptions extends SignatureDocs<BashParam> {
+    /** Unit of the timeout parameter. Default "ms". */
+    readonly timeoutUnit?: "ms" | "s";
+    /** Add the cwd parameter. Default true. With false, `names.cwd` and `describe.cwd` are ignored. */
+    readonly cwd?: boolean;
+    /** Put the runner id in the description, for example "just-bash (emulated)". */
+    readonly runner?: string;
+    /** The tool's limits, so the description names the right timeouts. Default defaultShellLimits. */
+    readonly limits?: Partial<ShellLimits>;
+}
+/**
+ * bash({ command, timeout?, cwd? }). The timeout unit is milliseconds unless
+ * `timeoutUnit` is "s".
+ */
+export declare function defaultBashSignature(options?: BashSignatureOptions): BashSignature;
+/** The parts of the message catalog a signature owns: parameter names and the timeout unit. */
+export declare function bashSignatureMessages(signature: BashSignature): Pick<ShellMessageCatalog, "param" | "duration">;

package/dist/signature/bash.js

@@ -0,0 +1,158 @@
+import { resolveShellLimits } from "../core/limits.js";
+import { formatDuration } from "../core/messages.js";
+const ALL_PARAMS = ["command", "timeout", "cwd"];
+/**
+ * bash({ command, timeout?, cwd? }). The timeout unit is milliseconds unless
+ * `timeoutUnit` is "s".
+ */
+export function defaultBashSignature(options = {}) {
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("defaultBashSignature options must be an object");
+    }
+    const { name = "bash", describe = {}, names = {}, timeoutUnit = "ms", cwd: withCwd = true, runner, } = options;
+    if (typeof name !== "string" || name.trim() === "") {
+        throw new TypeError("defaultBashSignature name must be a non-blank string");
+    }
+    if (timeoutUnit !== "ms" && timeoutUnit !== "s") {
+        throw new TypeError('defaultBashSignature timeoutUnit must be "ms" or "s"');
+    }
+    if (typeof withCwd !== "boolean")
+        throw new TypeError("defaultBashSignature cwd must be a boolean");
+    if (runner !== undefined && typeof runner !== "string") {
+        throw new TypeError("defaultBashSignature runner must be a string");
+    }
+    if (options.description !== undefined && typeof options.description !== "string") {
+        throw new TypeError("defaultBashSignature description must be a string");
+    }
+    const enabledParams = withCwd
+        ? ["command", "timeout", "cwd"]
+        : ["command", "timeout"];
+    checkKeys(describe, "describe", ALL_PARAMS);
+    checkKeys(names, "names", ALL_PARAMS);
+    const host = {};
+    for (const param of enabledParams) {
+        const value = names[param] ?? param;
+        if (value.trim() === "")
+            throw new TypeError(`names.${param} must be a non-blank string`);
+        if (Object.values(host).includes(value)) {
+            throw new TypeError(`Parameter name ${value} is used twice`);
+        }
+        host[param] = value;
+    }
+    const params = enabledParams.map((param) => host[param]);
+    const limits = resolveShellLimits(options.limits);
+    const scale = timeoutUnit === "s" ? 1_000 : 1;
+    const unitWord = timeoutUnit === "s" ? "seconds" : "milliseconds";
+    const inUnit = (ms) => `${ms / scale} ${unitWord}`;
+    const properties = [
+        [
+            host.command,
+            {
+                type: "string",
+                minLength: 1,
+                description: describe.command ?? "The shell command to run with bash -c.",
+            },
+        ],
+        [
+            host.timeout,
+            {
+                type: "number",
+                exclusiveMinimum: 0,
+                description: describe.timeout ??
+                    `Timeout in ${unitWord}. Default ${inUnit(limits.defaultTimeoutMs)}, maximum ${inUnit(limits.maxTimeoutMs)}.`,
+            },
+        ],
+    ];
+    if (withCwd) {
+        properties.push([
+            host.cwd,
+            {
+                type: "string",
+                minLength: 1,
+                description: describe.cwd ??
+                    "Working directory for this command, relative to the default directory or absolute. Use it instead of cd.",
+            },
+        ]);
+    }
+    const schema = deepFreeze({
+        type: "object",
+        additionalProperties: false,
+        properties: Object.fromEntries(properties),
+        required: [host.command],
+    });
+    const description = options.description ??
+        [
+            "Run a shell command with bash -c and return its exit code and output.",
+            "Each call starts a new shell: a cd, an export, or a variable does not carry to the next call.",
+            "stdin is closed, so a command that waits for input gets end of file. Do not start interactive programs.",
+            `The command stops after ${formatDuration(limits.defaultTimeoutMs)} unless you set a timeout. The whole process tree is stopped at the timeout.`,
+            `stdout and stderr are merged. Long output keeps the first and the last lines, up to ${limits.maxOutputLines} lines or ${limits.maxOutputBytes} bytes.`,
+            "Prefer the read, edit, and write tools for files.",
+            ...(runner === undefined ? [] : [`Commands run in: ${runner}.`]),
+        ].join(" ");
+    const canonical = {
+        command: host.command,
+        timeoutMs: host.timeout,
+        cwd: withCwd ? host.cwd : "",
+    };
+    return Object.freeze({
+        name,
+        description,
+        schema,
+        toInput(input) {
+            if (input === null || typeof input !== "object" || Array.isArray(input)) {
+                throw new TypeError(`bash input must be an object with ${params.join(", ")}`);
+            }
+            const record = input;
+            for (const key of Object.keys(record)) {
+                if (!params.includes(key)) {
+                    throw new TypeError(`Unknown bash input key: ${key}. Expected ${params.join(", ")}`);
+                }
+            }
+            const command = record[host.command];
+            const timeout = record[host.timeout];
+            const cwd = withCwd ? record[host.cwd] : undefined;
+            if (typeof command !== "string" || command.trim() === "") {
+                throw new TypeError(`${host.command} must be a non-blank string`);
+            }
+            if (timeout !== undefined &&
+                (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0)) {
+                throw new TypeError(`${host.timeout} must be a positive number`);
+            }
+            if (cwd !== undefined && (typeof cwd !== "string" || cwd.trim() === "")) {
+                throw new TypeError(`${host.cwd} must be a non-blank string`);
+            }
+            return {
+                command,
+                ...(timeout === undefined ? {} : { timeoutMs: timeout * scale }),
+                ...(cwd === undefined ? {} : { cwd: cwd }),
+            };
+        },
+        param: (name) => canonical[name],
+        duration: inUnit,
+    });
+}
+/** The parts of the message catalog a signature owns: parameter names and the timeout unit. */
+export function bashSignatureMessages(signature) {
+    return { param: signature.param, duration: signature.duration };
+}
+function checkKeys(map, key, params) {
+    if (map === null || typeof map !== "object" || Array.isArray(map)) {
+        throw new TypeError(`defaultBashSignature ${key} must be an object`);
+    }
+    for (const [param, value] of Object.entries(map)) {
+        if (!params.includes(param)) {
+            throw new TypeError(`Unknown parameter in ${key}: ${param}. Expected ${params.join(", ")}`);
+        }
+        if (typeof value !== "string")
+            throw new TypeError(`${key}.${param} must be a string`);
+    }
+}
+function deepFreeze(value) {
+    if (value !== null && typeof value === "object") {
+        for (const child of Object.values(value))
+            deepFreeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}

package/dist/signature/index.d.ts

@@ -0,0 +1,3 @@
+/** The `./signature` subpath: the model-facing name, schema, and description of the bash tool. */
+export { bashSignatureMessages, defaultBashSignature } from "./bash.ts";
+export type { BashParam, BashSignature, BashSignatureOptions } from "./bash.ts";

package/dist/signature/index.js

@@ -0,0 +1,2 @@
+/** The `./signature` subpath: the model-facing name, schema, and description of the bash tool. */
+export { bashSignatureMessages, defaultBashSignature } from "./bash.js";

package/docs/architecture.md

@@ -0,0 +1,74 @@
+# Architecture
+
+This page explains how `@better-fs-tools/shell` runs one `bash` call, and why it is built this way. [result-schema.md](result-schema.md) describes the result. The [README](../README.md) shows how to configure each step.
+
+## The pipeline
+
+```text
+bash(input, ctx?)
+  │  parseBashInput ........... strict canonical validation, timeout clamp   phase input
+  │  runner(call), cwd(call) .. once; a runner and a default cwd, or factories phase run, resolve
+  ▼
+BashRequest { command, timeoutMs, cwd }
+  │  resolve .................. the requested cwd string                     phase resolve
+  │  beforeRun ................ checks and rewrites, in order                phase beforeRun
+  │  authorize ................ host policy on the final command             phase authorize
+  │  env ...................... the whole environment of the command         phase env
+  │  spill.open ............... optional sink for every output byte          phase spill
+  │  runner.run ............... start, capture, timeout, abort, output cap   phase run
+  │  afterRun ................. output and note changes, in order            phase afterRun
+  ▼
+formatter.format(report, { mode: "model", call, ... }) ─▶ content
+  ▼
+ShellResult
+```
+
+| Stage     | Dependency              | What happens                                                                                                                    |
+| --------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| Input     | `limits`                | `parseBashInput` accepts only `command`, `timeoutMs`, and `cwd`. A timeout over `maxTimeoutMs` is clamped with a `clamped` note |
+| Runner    | `runner`, `cwd`         | A `CommandRunner`, or a factory of the call context. The default cwd is `cwd`, or the runner's `cwd`                            |
+| Resolve   | `resolve`               | A read tool resolver may change the requested cwd string, or report it not found (`CWD_NOT_FOUND`)                              |
+| beforeRun | `beforeRun`             | Each hook returns `{ allow: true, command?, notes? }` or `{ allow: false, note? }`. A rewrite feeds the next hook               |
+| Authorize | `authorize`             | One target with the final command, the absolute cwd, and a display path relative to the default cwd. A denial is `DENIED`       |
+| Env       | `env`                   | The host function returns the whole environment. Nothing else reaches the command                                               |
+| Run       | `runner`, `spill`       | The runner starts the command. The core reads the output into a bounded capture, and stops the process tree when it must        |
+| afterRun  | `afterRun`              | Each hook returns `{ output?, notes? }`. The status, the error, and the run stay as the core set them                           |
+| Format    | `formatter`, `messages` | Turns the report into content parts                                                                                             |
+
+The core owns the stage order, the timeout, the abort, the output budget and view, the status, and note assembly. Policy, rewrites, the environment, and where output is saved belong to the host.
+
+## Why `authorize` runs after `beforeRun`
+
+A `beforeRun` hook can rewrite the command, for example to add a flag or wrap it in a sandbox call. The authorizer sees the command after every rewrite, so an approval prompt shows the command that runs. A `beforeRun` refusal stops the call before `authorize` runs.
+
+## `env` is required
+
+The core has no default environment. A default of `process.env` would leak the host's secrets on every host, and an empty default would break `PATH` and `HOME` without a sign. The host chooses once: `shellEnv(() => process.env)`, an allow list such as `shellEnv({ PATH, HOME })`, or `shellEnv()` for `defaultShellEnv` alone. The Node and Pi factories default it to `shellEnv(() => process.env)`, because they run a local shell.
+
+## Stopping a command
+
+A timeout, the caller's abort, and the capture cap all abort the runner's signal. The runner must then stop the whole process tree: SIGTERM, and SIGKILL after `killGraceMs`. The core waits `killGraceMs` plus one second for the exit. When the runner does not settle it, the run has `unconfirmedStop: true` and an `unconfirmed-stop` warning.
+
+- A timeout gives `status: "timeout"` and keeps the output.
+- An abort gives `error` with `ABORTED`. Before the start, `run` and `output` are null.
+- The capture cap gives `error` with `OUTPUT_CAP`, and keeps the run and the output.
+
+After a normal exit, the core reads output for one more second, then lets go of the stream. A background child that holds the pipes open keeps running.
+
+## Output
+
+The core keeps at most `maxCaptureBytes` in memory. The model view is at most `maxOutputBytes` and `maxOutputLines`: a head of `headPercent`, then a gap line, then the tail. Errors are usually at the end, so the tail gets most of it. A spill sink gets every byte in arrival order, and its reference goes into the gap line.
+
+A failing output stream, chunks that are not output, or a stream that has not ended one second after the exit, end the capture with an `output-incomplete` warning. After that deadline the core lets go of the stream and captures no later chunk. The status still comes from the exit. A stop the tool started (timeout, abort, output cap) has its own note and adds no `output-incomplete` for the stream it cut.
+
+## Host code
+
+A throw or a malformed return from host code gives `EXTENSION_FAILED` with the phase of the stage. An `afterRun` failure keeps the run and the output. A formatter failure is the exception: the status stays, the core adds no note, and `defaultShellFormatter()` makes the content, as in the read and write tools.
+
+Every host function gets `ctx`: the tool name, the request, the limits, the messages, `digest`, `clock`, and the call context. The bash tool hashes nothing itself. `digest` and `clock` come from the dependencies, so a bundle can give bash the same digest and clock as its file tools.
+
+## Runners
+
+A runner starts one command and never throws for a failed command. `run(request)` gets the command, an absolute cwd, the whole environment, an abort signal, and `killGraceMs`. It returns `output`, an async iterable of `{ stream, bytes }` chunks, and `exit`, a promise that never rejects. A start that fails is an exit with `code: null` and an `error` reason: `cwd-not-found`, `cwd-not-a-directory`, or `spawn-failed`.
+
+`nodeCommandRunner()` in `@better-fs-tools/node` runs `bash -c` in its own process group. `justBashCommandRunner()` in `@better-fs-tools/just-bash` runs an emulated shell with no process.