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

package/dist/contract/result.d.ts

@@ -0,0 +1,77 @@
+import type { ContentPart, Note, ToolError } from "@better-fs-tools/read";
+import type { BashRequest } from "./input.ts";
+/**
+ * "ok", "failed", and "timeout" describe a command that ran. "failed": it
+ * exited with a code other than 0. It is a normal result, not a tool error.
+ * "error": the call stopped, or the tool stopped the command for a reason
+ * other than its timeout. `error.code` says why.
+ */
+export type ShellStatus = "ok" | "failed" | "timeout" | "error";
+/**
+ * The error note's code is the kebab-case form. DENIED: the authorizer
+ * refused. REFUSED: a beforeRun hook refused. ABORTED: the caller's signal fired.
+ */
+export type ShellErrorCode = "INVALID_INPUT" | "CWD_NOT_FOUND" | "CWD_NOT_A_DIRECTORY" | "DENIED" | "REFUSED" | "ABORTED" | "SPAWN_FAILED" | "OUTPUT_CAP" | "EXTENSION_FAILED";
+export type ShellPhase = "input" | "resolve" | "authorize" | "beforeRun" | "env" | "run" | "spill" | "afterRun" | "format";
+/** The error of a failed call. */
+export type ShellError = ToolError<ShellErrorCode, ShellPhase>;
+/** Facts about one run. null in an error report when the command did not start. */
+export interface ShellRun {
+    /** As run, after any beforeRun rewrite. */
+    readonly command: string;
+    readonly cwd: string;
+    readonly timeoutMs: number;
+    readonly exitCode: number | null;
+    readonly signal: string | null;
+    readonly durationMs: number;
+    /** What stopped the command before it ended by itself. null when it ended by itself. */
+    readonly stoppedBy: "timeout" | "abort" | "output-cap" | null;
+    /** true when the runner did not settle its exit in the grace time after a stop. */
+    readonly unconfirmedStop: boolean;
+}
+/**
+ * The bounded view of the merged output. `head` holds all of it when
+ * `omittedBytes` is 0. Otherwise the view is `head`, a gap, then `tail`.
+ */
+export interface ShellOutput {
+    readonly head: string;
+    /** null when nothing was cut. */
+    readonly tail: string | null;
+    readonly totalBytes: number;
+    readonly totalLines: number;
+    readonly omittedBytes: number;
+    readonly omittedLines: number;
+    readonly stdoutBytes: number;
+    readonly stderrBytes: number;
+    /** The spill sink's reference to the full output. null without a sink. */
+    readonly spill: string | null;
+}
+/**
+ * One variant for a command that ran to its own end or its timeout, and one
+ * for an error. `status` narrows the union: only the "error" variant has
+ * `error`, and it is never null there.
+ */
+export type ShellReport = ShellRunReport | ShellFailure;
+export interface ShellRunReport {
+    readonly tool: "bash";
+    readonly status: "ok" | "failed" | "timeout";
+    readonly request: BashRequest;
+    readonly run: ShellRun;
+    readonly output: ShellOutput;
+    readonly notes: readonly Note[];
+}
+export interface ShellFailure {
+    readonly tool: "bash";
+    readonly status: "error";
+    readonly error: ShellError;
+    /** null when parse failed. */
+    readonly request: BashRequest | null;
+    /** Set when the command started: an abort, the capture cap, or a failed afterRun hook. */
+    readonly run: ShellRun | null;
+    readonly output: ShellOutput | null;
+    readonly notes: readonly Note[];
+}
+/** The report plus the formatter's model-facing content. */
+export type ShellResult = ShellReport & {
+    readonly content: readonly ContentPart[];
+};

package/dist/contract/runner.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Starts one command for the bash tool. The tool handles the timeout, the
+ * abort, and the output budget.
+ */
+export interface CommandRunner {
+    /** Shown in the tool description, for example "node" or "just-bash (emulated)". */
+    readonly id: string;
+    /** The default working directory. The tool resolves the cwd input against it. */
+    readonly cwd: string;
+    /**
+     * Starts the command. Must not throw for a failed command or a failed
+     * start: a start that fails is an exit with `code: null` and an `error`.
+     */
+    run(request: RunRequest): RunHandle;
+}
+export interface RunRequest {
+    readonly command: string;
+    /** Absolute and lexically resolved. The runner checks that it is a directory. */
+    readonly cwd: string;
+    /** The whole environment of the command. The runner adds nothing to it. */
+    readonly env: Readonly<Record<string, string>>;
+    /**
+     * The tool aborts it on a timeout, on the caller's abort, and past the
+     * capture cap. The runner must then stop the whole process tree.
+     */
+    readonly signal: AbortSignal;
+    /** After the stop signal, the runner waits this long before it forces the stop (SIGKILL). */
+    readonly killGraceMs: number;
+}
+export interface OutputChunk {
+    readonly stream: "stdout" | "stderr";
+    readonly bytes: Uint8Array;
+}
+export interface RunHandle {
+    /**
+     * stdout and stderr chunks in arrival order. Ends soon after the process
+     * ends, even when a background child still holds the pipes open.
+     */
+    readonly output: AsyncIterable<OutputChunk>;
+    /** Settles when the process ends. Never rejects. */
+    readonly exit: Promise<RunExit>;
+}
+export interface RunExit {
+    /** null when a signal ended the process or the start failed. */
+    readonly code: number | null;
+    /** The signal name, for example "SIGKILL". null for a normal exit. */
+    readonly signal: string | null;
+    /** Set when the command did not start. */
+    readonly error?: RunStartError;
+}
+export interface RunStartError {
+    readonly reason: "cwd-not-found" | "cwd-not-a-directory" | "spawn-failed";
+    /** Non-sensitive detail for the note. */
+    readonly detail?: string;
+}

package/dist/core/abort.d.ts

@@ -0,0 +1,12 @@
+import type { ShellPhase } from "../contract/result.ts";
+/** Thrown when the caller's signal aborted before the command started. `phase` names the stage. */
+export declare class AbortStop extends Error {
+    readonly phase: ShellPhase;
+    constructor(phase?: ShellPhase);
+}
+export declare function raceAbort<T>(start: () => T | Promise<T>, signal: AbortSignal | undefined): Promise<T>;
+export declare function delay(ms: number): {
+    readonly done: Promise<void>;
+    cancel(): void;
+};
+export declare function unref(timer: unknown): void;

package/dist/core/abort.js

@@ -0,0 +1,41 @@
+/** Thrown when the caller's signal aborted before the command started. `phase` names the stage. */
+export class AbortStop extends Error {
+    phase;
+    constructor(phase = "run") {
+        super("aborted");
+        this.phase = phase;
+    }
+}
+export async function raceAbort(start, signal) {
+    if (!signal)
+        return start();
+    if (signal.aborted)
+        throw new AbortStop();
+    let removeListener;
+    const aborted = new Promise((_resolve, reject) => {
+        const onAbort = () => reject(new AbortStop());
+        signal.addEventListener("abort", onAbort, { once: true });
+        removeListener = () => signal.removeEventListener("abort", onAbort);
+    });
+    try {
+        return await Promise.race([(async () => start())(), aborted]);
+    }
+    finally {
+        removeListener?.();
+    }
+}
+export function delay(ms) {
+    let timer;
+    const done = new Promise((resolve) => {
+        timer = setTimeout(resolve, ms);
+        unref(timer);
+    });
+    return { done, cancel: () => clearTimeout(timer) };
+}
+export function unref(timer) {
+    if (timer !== null && typeof timer === "object" && "unref" in timer) {
+        const { unref: release } = timer;
+        if (typeof release === "function")
+            release.call(timer);
+    }
+}

package/dist/core/capture.d.ts

@@ -0,0 +1,11 @@
+import type { ShellLimits } from "../contract/limits.ts";
+import type { ShellOutput } from "../contract/result.ts";
+import type { OutputChunk } from "../contract/runner.ts";
+/** Keeps the first and last `maxOutputBytes` bytes of the merged output, and counts. */
+export declare class OutputCapture {
+    #private;
+    constructor(limits: Readonly<ShellLimits>);
+    get totalBytes(): number;
+    push(chunk: OutputChunk): void;
+    view(limits: Readonly<ShellLimits>, spill: string | null): ShellOutput;
+}

package/dist/core/capture.js

@@ -0,0 +1,171 @@
+const NEWLINE = 0x0a;
+/** Keeps the first and last `maxOutputBytes` bytes of the merged output, and counts. */
+export class OutputCapture {
+    #cap;
+    #head;
+    #headLength = 0;
+    #tail = [];
+    #tailLength = 0;
+    #total = 0;
+    #newlines = 0;
+    #lastByte = -1;
+    #stdout = 0;
+    #stderr = 0;
+    constructor(limits) {
+        this.#cap = limits.maxOutputBytes;
+        this.#head = new Uint8Array(this.#cap);
+    }
+    get totalBytes() {
+        return this.#total;
+    }
+    push(chunk) {
+        const { bytes } = chunk;
+        if (bytes.byteLength === 0)
+            return;
+        this.#total += bytes.byteLength;
+        if (chunk.stream === "stderr")
+            this.#stderr += bytes.byteLength;
+        else
+            this.#stdout += bytes.byteLength;
+        for (const byte of bytes)
+            if (byte === NEWLINE)
+                this.#newlines += 1;
+        this.#lastByte = bytes[bytes.byteLength - 1] ?? this.#lastByte;
+        if (this.#headLength < this.#cap) {
+            const take = Math.min(this.#cap - this.#headLength, bytes.byteLength);
+            this.#head.set(bytes.subarray(0, take), this.#headLength);
+            this.#headLength += take;
+        }
+        // Copy: the runner may reuse its buffer.
+        const kept = bytes.byteLength > this.#cap ? bytes.slice(-this.#cap) : bytes.slice();
+        this.#tail.push(kept);
+        this.#tailLength += kept.byteLength;
+        while (this.#tail.length > 1 &&
+            this.#tailLength - (this.#tail[0]?.byteLength ?? 0) >= this.#cap) {
+            this.#tailLength -= this.#tail.shift()?.byteLength ?? 0;
+        }
+    }
+    view(limits, spill) {
+        const total = this.#total;
+        const totalLines = this.#newlines + (total > 0 && this.#lastByte !== NEWLINE ? 1 : 0);
+        const counts = {
+            totalBytes: total,
+            totalLines,
+            stdoutBytes: this.#stdout,
+            stderrBytes: this.#stderr,
+            spill,
+        };
+        const head = this.#head.subarray(0, this.#headLength);
+        if (total <= limits.maxOutputBytes && totalLines <= limits.maxOutputLines) {
+            return { ...counts, head: text(head), tail: null, omittedBytes: 0, omittedLines: 0 };
+        }
+        const headBytes = Math.floor((limits.maxOutputBytes * limits.headPercent) / 100);
+        const headLines = Math.floor((limits.maxOutputLines * limits.headPercent) / 100);
+        const headEnd = headCut(head, headBytes, headLines);
+        const tailStore = concat(this.#tail, this.#tailLength);
+        const storeStart = total - tailStore.byteLength;
+        const tailBytes = limits.maxOutputBytes - headBytes;
+        const tailLines = limits.maxOutputLines - headLines;
+        const from = Math.max(total - tailBytes, headEnd);
+        const startsLine = this.#isLineStart(from, tailStore, storeStart);
+        const tailStart = tailCut(tailStore, from - storeStart, tailLines, startsLine);
+        const shownTail = tailStore.subarray(tailStart);
+        const shownHead = head.subarray(0, headEnd);
+        const omittedBytes = total - shownHead.byteLength - shownTail.byteLength;
+        const omittedLines = Math.max(0, totalLines - lineCount(shownHead) - lineCount(shownTail));
+        return {
+            ...counts,
+            head: text(shownHead),
+            tail: text(shownTail),
+            omittedBytes,
+            omittedLines,
+        };
+    }
+    #isLineStart(position, tailStore, storeStart) {
+        const before = position - 1;
+        return (position === 0 ||
+            (before >= storeStart
+                ? tailStore[before - storeStart] === NEWLINE
+                : before < this.#headLength && this.#head[before] === NEWLINE));
+    }
+}
+function headCut(head, bytes, lines) {
+    if (lines <= 0)
+        return 0;
+    const limit = Math.min(bytes, head.byteLength);
+    let seen = 0;
+    let lastNewline = -1;
+    for (let index = 0; index < limit; index += 1) {
+        if (head[index] !== NEWLINE)
+            continue;
+        seen += 1;
+        lastNewline = index;
+        if (seen >= lines)
+            break;
+    }
+    if (lastNewline >= 0)
+        return lastNewline + 1;
+    return charBoundaryBack(head, limit);
+}
+function tailCut(store, from, lines, startsLine) {
+    let start = from;
+    if (!startsLine) {
+        const next = store.indexOf(NEWLINE, start);
+        if (next >= 0 && next < store.byteLength - 1)
+            start = next + 1;
+        else
+            start = charBoundaryForward(store, start);
+    }
+    const endBeforeFinalNewline = store[store.byteLength - 1] === NEWLINE ? store.byteLength - 1 : store.byteLength;
+    let seen = 0;
+    for (let index = endBeforeFinalNewline - 1; index >= start; index -= 1) {
+        if (store[index] !== NEWLINE)
+            continue;
+        seen += 1;
+        if (seen >= lines)
+            return index + 1;
+    }
+    return lines === 0 ? store.byteLength : start;
+}
+function charBoundaryBack(bytes, end) {
+    let cut = end;
+    while (cut > 0 && cut < bytes.byteLength && isContinuation(bytes[cut]))
+        cut -= 1;
+    return cut;
+}
+function charBoundaryForward(bytes, start) {
+    let cut = start;
+    while (cut < bytes.byteLength && isContinuation(bytes[cut]))
+        cut += 1;
+    return cut;
+}
+function isContinuation(byte) {
+    return byte !== undefined && (byte & 0xc0) === 0x80;
+}
+function lineCount(bytes) {
+    if (bytes.byteLength === 0)
+        return 0;
+    let count = 0;
+    for (const byte of bytes)
+        if (byte === NEWLINE)
+            count += 1;
+    return bytes[bytes.byteLength - 1] === NEWLINE ? count : count + 1;
+}
+function concat(chunks, length) {
+    const out = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+const CONTROL_SEQUENCE = "\\u001b\\[[0-?]*[ -/]*[@-~]";
+const OPERATING_SYSTEM_COMMAND = "\\u001b\\][^\\u0007\\u001b]*(?:\\u0007|\\u001b\\\\)";
+const TWO_BYTE_ESCAPE = "\\u001b[@-Z\\\\-_]";
+const EIGHT_BIT_CONTROL_SEQUENCE = "\\u009b[0-?]*[ -/]*[@-~]";
+const ANSI_ESCAPE = new RegExp([CONTROL_SEQUENCE, OPERATING_SYSTEM_COMMAND, TWO_BYTE_ESCAPE, EIGHT_BIT_CONTROL_SEQUENCE].join("|"), "gu");
+function text(bytes) {
+    const decoded = new TextDecoder("utf-8").decode(bytes).replace(ANSI_ESCAPE, "");
+    return decoded.endsWith("\n") ? decoded.slice(0, -1) : decoded;
+}

package/dist/core/create-bash-tool.d.ts

@@ -0,0 +1,8 @@
+import type { BashTool } from "../contract/context.ts";
+import type { ShellToolDeps } from "../contract/deps.ts";
+/**
+ * Creates the bash tool. Throws TypeError on an unknown key, a missing runner
+ * or env, or a malformed dependency. `limits` and `messages` merge key by key.
+ * Every other dependency replaces its default.
+ */
+export declare function createBashTool<THost = undefined>(deps: ShellToolDeps<THost>): BashTool<THost>;

package/dist/core/create-bash-tool.js

@@ -0,0 +1,18 @@
+import { resolveShellDependencies } from "./deps.js";
+import { isRecord } from "./input.js";
+import { runBash } from "./pipeline.js";
+/**
+ * Creates the bash tool. Throws TypeError on an unknown key, a missing runner
+ * or env, or a malformed dependency. `limits` and `messages` merge key by key.
+ * Every other dependency replaces its default.
+ */
+export function createBashTool(deps) {
+    const resolved = resolveShellDependencies(deps);
+    const bash = async (input, ctx) => {
+        if (ctx !== undefined && !isRecord(ctx))
+            throw new TypeError("bash context must be an object");
+        const call = ctx ?? {};
+        return runBash(resolved, input, call);
+    };
+    return bash;
+}

package/dist/core/deps.d.ts

@@ -0,0 +1,5 @@
+import type { ShellDependencies, ShellToolDeps } from "../contract/deps.ts";
+import type { CommandRunner } from "../contract/runner.ts";
+export declare function resolveShellDependencies<THost>(deps: ShellToolDeps<THost>): ShellDependencies<THost>;
+export declare function isRunner(value: unknown): value is CommandRunner;
+export declare function isAbsolute(value: unknown): value is string;

package/dist/core/deps.js

@@ -0,0 +1,103 @@
+import { defaultShellFormatter } from "../formatters/default.js";
+import { isRecord } from "./input.js";
+import { resolveShellLimits } from "./limits.js";
+import { resolveShellMessages } from "./messages.js";
+const KNOWN = new Set([
+    "runner",
+    "cwd",
+    "limits",
+    "messages",
+    "resolve",
+    "authorize",
+    "beforeRun",
+    "env",
+    "spill",
+    "afterRun",
+    "formatter",
+    "digest",
+    "clock",
+]);
+export function resolveShellDependencies(deps) {
+    if (!isRecord(deps))
+        throw new TypeError("bash tool dependencies must be an object");
+    for (const key of Object.keys(deps)) {
+        if (!KNOWN.has(key))
+            throw new TypeError(`Unknown bash tool dependency: ${key}`);
+    }
+    const { runner } = deps;
+    if (typeof runner !== "function" && !isRunner(runner)) {
+        throw new TypeError("runner must be a command runner or a function that returns one");
+    }
+    const cwd = deps.cwd ?? null;
+    if (cwd !== null && typeof cwd !== "function" && !isAbsolute(cwd)) {
+        throw new TypeError("cwd must be an absolute path, a function that returns one, or null");
+    }
+    const resolve = deps.resolve ?? null;
+    if (resolve !== null && (!isRecord(resolve) || typeof resolve.resolve !== "function")) {
+        throw new TypeError("resolve must be a path resolver or null");
+    }
+    const authorize = deps.authorize ?? null;
+    if (authorize !== null && (!isRecord(authorize) || typeof authorize.authorize !== "function")) {
+        throw new TypeError("authorize must be an authorizer or null");
+    }
+    const beforeRun = deps.beforeRun ?? [];
+    if (!Array.isArray(beforeRun) || !beforeRun.every(isBeforeRunHook)) {
+        throw new TypeError("beforeRun must be an array of hooks with an id and beforeRun");
+    }
+    const { env } = deps;
+    if (env === undefined) {
+        throw new TypeError("env is required: pass shellEnv(() => process.env), an allow list such as shellEnv({ PATH }), or shellEnv()");
+    }
+    if (typeof env !== "function")
+        throw new TypeError("env must be a function");
+    const spill = deps.spill ?? null;
+    if (spill !== null && (!isRecord(spill) || typeof spill.open !== "function")) {
+        throw new TypeError("spill must be a spill sink with open, or null");
+    }
+    const afterRun = deps.afterRun ?? [];
+    if (!Array.isArray(afterRun) || !afterRun.every(isAfterRunHook)) {
+        throw new TypeError("afterRun must be an array of hooks with an id and afterRun");
+    }
+    const formatter = deps.formatter ?? defaultShellFormatter();
+    if (!isRecord(formatter) || typeof formatter.format !== "function") {
+        throw new TypeError("formatter must have a format function");
+    }
+    const digest = deps.digest ?? null;
+    if (digest !== null &&
+        (!isRecord(digest) || typeof digest.create !== "function" || typeof digest.hash !== "function")) {
+        throw new TypeError("digest must be a digest with create and hash, or null");
+    }
+    const clock = deps.clock ?? (() => new Date());
+    if (typeof clock !== "function")
+        throw new TypeError("clock must be a function");
+    return Object.freeze({
+        runner,
+        cwd,
+        limits: resolveShellLimits(deps.limits),
+        messages: resolveShellMessages(deps.messages),
+        resolve,
+        authorize,
+        beforeRun: Object.freeze([...beforeRun]),
+        env,
+        spill,
+        afterRun: Object.freeze([...afterRun]),
+        formatter,
+        digest,
+        clock,
+    });
+}
+export function isRunner(value) {
+    return (isRecord(value) &&
+        typeof value.id === "string" &&
+        isAbsolute(value.cwd) &&
+        typeof value.run === "function");
+}
+export function isAbsolute(value) {
+    return typeof value === "string" && value.startsWith("/");
+}
+function isBeforeRunHook(value) {
+    return isRecord(value) && typeof value.id === "string" && typeof value.beforeRun === "function";
+}
+function isAfterRunHook(value) {
+    return isRecord(value) && typeof value.id === "string" && typeof value.afterRun === "function";
+}

package/dist/core/env.d.ts

@@ -0,0 +1,14 @@
+type EnvRecord = Readonly<Record<string, string | undefined>>;
+/**
+ * Variables shellEnv sets over the base, so a command does not wait on a
+ * pager or a prompt and does not print colour codes.
+ */
+export declare const defaultShellEnv: Readonly<Record<string, string>>;
+/**
+ * An env dependency for any host: `base` with defaultShellEnv over it.
+ * Entries whose value is undefined are left out. A function base is read
+ * again on each call, so `shellEnv(() => process.env)` follows changes to
+ * process.env.
+ */
+export declare function shellEnv(base?: EnvRecord | (() => EnvRecord)): () => Readonly<Record<string, string>>;
+export {};

package/dist/core/env.js

@@ -0,0 +1,32 @@
+/**
+ * Variables shellEnv sets over the base, so a command does not wait on a
+ * pager or a prompt and does not print colour codes.
+ */
+export const defaultShellEnv = Object.freeze({
+    PAGER: "cat",
+    GIT_PAGER: "cat",
+    GIT_TERMINAL_PROMPT: "0",
+    NO_COLOR: "1",
+    TERM: "dumb",
+});
+/**
+ * An env dependency for any host: `base` with defaultShellEnv over it.
+ * Entries whose value is undefined are left out. A function base is read
+ * again on each call, so `shellEnv(() => process.env)` follows changes to
+ * process.env.
+ */
+export function shellEnv(base = {}) {
+    if (typeof base === "function")
+        return () => merge(base());
+    const fixed = merge(base);
+    return () => fixed;
+}
+function merge(base) {
+    const merged = {};
+    for (const [key, value] of Object.entries(base)) {
+        if (typeof value === "string")
+            merged[key] = value;
+    }
+    Object.assign(merged, defaultShellEnv);
+    return Object.freeze(merged);
+}

package/dist/core/execute.d.ts

@@ -0,0 +1,11 @@
+import type { PlannedRun } from "../contract/extensions.ts";
+import type { ShellOutput, ShellRun } from "../contract/result.ts";
+import type { CommandRunner } from "../contract/runner.ts";
+import type { CallScope } from "./stages.ts";
+import { StageStop } from "./stop.ts";
+export interface Executed {
+    readonly run: ShellRun;
+    readonly output: ShellOutput;
+    readonly stop: StageStop | null;
+}
+export declare function execute<THost>(scope: CallScope<THost>, runner: CommandRunner, planned: PlannedRun, env: Readonly<Record<string, string>>): Promise<Executed>;