@foldrun/core 0.2.0

package/dist/src/tar.d.ts

@@ -0,0 +1,30 @@
+export interface TarEntry {
+    path: string;
+    content: Buffer;
+}
+/**
+ * Every regular file in a gzipped tarball.
+ *
+ * Directories, symlinks, and pax/global headers are skipped: a workspace is
+ * files, and following a link out of the archive is exactly the thing a deploy
+ * from an untrusted repository must not do.
+ */
+export declare function readTarGz(gz: Buffer): TarEntry[];
+/**
+ * Drop the single wrapper directory an archive is rooted at.
+ *
+ * GitHub tarballs are rooted at `owner-repo-<sha>/`, which is not part of
+ * anyone's workspace. Stripped only when *every* entry shares one first
+ * segment, so an archive that is already flat is left alone.
+ */
+export declare function stripRoot(entries: TarEntry[]): TarEntry[];
+/**
+ * Read a tarball as the file list a deploy ships.
+ *
+ * `subdir` picks a workspace living inside a larger repository — the common
+ * case, since a repo usually holds more than one thing.
+ */
+export declare function filesFromTarball(gz: Buffer, subdir?: string): {
+    path: string;
+    content: string;
+}[];

package/dist/src/tar.js

@@ -0,0 +1,111 @@
+// Reading a .tar.gz, so a deploy can come from a GitHub tarball.
+//
+// `GET /repos/{owner}/{repo}/tarball/{sha}` is one HTTP call and needs no git
+// binary, no clone, and no working copy on the server — which is the whole
+// reason a markdown workspace can deploy from a webhook in a few hundred
+// milliseconds. What it returns is a tar.gz, and Node has gzip but not tar.
+//
+// Deliberately dependency-free, for the same reason the cron parser is: tar is
+// 512-byte blocks with an octal size field, and a reader is shorter than the
+// argument about which library to add.
+import zlib from "node:zlib";
+const BLOCK = 512;
+const str = (b, off, len) => {
+    const raw = b.subarray(off, off + len);
+    const end = raw.indexOf(0);
+    return raw.subarray(0, end === -1 ? raw.length : end).toString("utf8");
+};
+// Sizes are octal, space- or NUL-padded. GNU also writes base-256 for large
+// files, flagged by the high bit — irrelevant for markdown, but a silent
+// misparse would be worse than a clear refusal.
+function size(b, off) {
+    if (b[off] & 0x80)
+        throw new Error("tar: base-256 size field is not supported");
+    const raw = str(b, off, 12).trim();
+    return raw ? parseInt(raw, 8) : 0;
+}
+/**
+ * Every regular file in a gzipped tarball.
+ *
+ * Directories, symlinks, and pax/global headers are skipped: a workspace is
+ * files, and following a link out of the archive is exactly the thing a deploy
+ * from an untrusted repository must not do.
+ */
+export function readTarGz(gz) {
+    const buf = zlib.gunzipSync(gz);
+    const out = [];
+    let longName = null;
+    for (let off = 0; off + BLOCK <= buf.length;) {
+        const header = buf.subarray(off, off + BLOCK);
+        // Two consecutive zero blocks end the archive; one is enough to stop.
+        if (header.every((b) => b === 0))
+            break;
+        const name = str(header, 0, 100);
+        const bytes = size(header, 124);
+        const type = String.fromCharCode(header[156]) || "0";
+        const prefix = str(header, 345, 155);
+        off += BLOCK;
+        const body = buf.subarray(off, off + bytes);
+        off += Math.ceil(bytes / BLOCK) * BLOCK;
+        // GNU long name: the next header's name lives in this entry's body.
+        if (type === "L") {
+            longName = body.toString("utf8").replace(/\0+$/, "");
+            continue;
+        }
+        if (type !== "0" && type !== "\0") {
+            longName = null;
+            continue;
+        }
+        const full = longName ?? (prefix ? `${prefix}/${name}` : name);
+        longName = null;
+        if (full)
+            out.push({ path: full, content: Buffer.from(body) });
+    }
+    return out;
+}
+/**
+ * Drop the single wrapper directory an archive is rooted at.
+ *
+ * GitHub tarballs are rooted at `owner-repo-<sha>/`, which is not part of
+ * anyone's workspace. Stripped only when *every* entry shares one first
+ * segment, so an archive that is already flat is left alone.
+ */
+export function stripRoot(entries) {
+    if (entries.length === 0)
+        return entries;
+    const first = entries[0].path.split("/")[0];
+    if (!entries.every((e) => e.path.split("/")[0] === first && e.path.includes("/"))) {
+        return entries;
+    }
+    return entries.map((e) => ({ ...e, path: e.path.slice(first.length + 1) }));
+}
+/**
+ * Read a tarball as the file list a deploy ships.
+ *
+ * `subdir` picks a workspace living inside a larger repository — the common
+ * case, since a repo usually holds more than one thing.
+ */
+export function filesFromTarball(gz, subdir = "") {
+    const prefix = subdir.replace(/^\/+|\/+$/g, "");
+    const out = [];
+    for (const entry of stripRoot(readTarGz(gz))) {
+        let rel = entry.path;
+        if (prefix) {
+            if (!rel.startsWith(`${prefix}/`))
+                continue;
+            rel = rel.slice(prefix.length + 1);
+        }
+        // A tarball is untrusted input: an entry can name anything at all, and
+        // `../` in an archive is the oldest way to write outside the destination.
+        if (rel.split("/").includes("..") || rel.startsWith("/"))
+            continue;
+        // AppleDouble sidecars. macOS `tar` writes a `._name` beside every file to
+        // carry metadata no other system wants; they are not part of anyone's
+        // workspace, and letting one through means a deploy rejected for shipping
+        // a file the author never wrote.
+        if ((rel.split("/").pop() ?? "").startsWith("._"))
+            continue;
+        out.push({ path: rel, content: entry.content.toString("utf8") });
+    }
+    return out;
+}

package/dist/src/tool-names.d.ts

@@ -0,0 +1,39 @@
+import { type Ref } from "./refs.ts";
+/** Groups: one word an author can hold in their head, expanded to SDK names. */
+export declare const TOOL_MAP: Record<string, string[]>;
+/** Exact SDK tool names, accepted alongside the group aliases so a Claude Code
+ *  subagent's `tools: Read, Grep` works unchanged. The aliases exist because
+ *  vendors rename tools; `web` survives a rename that `WebSearch` would not. */
+export declare const BUILTIN_TOOLS: Set<string>;
+/** The platform's own groups, served in-process rather than by the SDK. */
+export declare const PLATFORM_GROUPS: Set<string>;
+/** Would this name resolve to something the runtime provides? Built-ins win a
+ *  clash, so a tool file of the same name is shadowed rather than granted. */
+export declare function isRuntimeTool(name: string): boolean;
+/** The name an entry grants. `tools:` also takes the map form for approval
+ *  mode — `{Bash: ask}` — where the key is the tool and the value the mode. */
+export declare function toolEntryName(entry: unknown): string;
+type ToolFrontmatter = {
+    tools?: unknown;
+    use?: unknown;
+};
+/** Every entry of `tools:`, with whether it was written as a `[[link]]`. */
+export declare function toolRefs(front: ToolFrontmatter): Ref[];
+/** Is this entry one of the author's own tools? A `[[link]]` always is —
+ *  the brackets say "my file", so `[[search]]` is yours even though `search`
+ *  is a runtime group. A bare name is the author's only when no built-in
+ *  claims it. */
+export declare function isOwnToolRef(ref: Ref): boolean;
+/**
+ * Every name in `tools:` that can only mean one of the author's own tools.
+ * Deduped, order preserved. Names that resolve to nothing are still
+ * returned: the caller reports them, and "you asked for a tool that isn't
+ * there" is a better error than silence.
+ */
+export declare function ownToolNames(front: ToolFrontmatter): string[];
+/** What a file still says under the removed `use:` key — nothing is granted
+ *  for these; they exist so the error can quote the exact `tools:` line. */
+export declare function legacyUseNames(front: ToolFrontmatter): string[];
+/** The one sentence every reader of a `use:` key says. */
+export declare function legacyUseError(names: string[]): string;
+export {};

package/dist/src/tool-names.js

@@ -0,0 +1,79 @@
+// The one place that knows which names are the runtime's and which are the
+// author's.
+//
+// `tools:` is Claude Code's field, kept compatible, and grants anything: a
+// built-in group, an exact SDK tool name, or a tool this workspace or account
+// defines. There used to be a second spelling, `use:`, that meant only the
+// author's own tools. It is gone: two keys for one grant meant two places to
+// look for an agent's blast radius, and three readers — the container's
+// egress flag, the library's used-by list, Tool Test's agent picker — read
+// one and forgot the other. A file that still says `use:` gets an error
+// naming the rewrite, and scripts/migrate-use-to-tools.mjs makes it.
+import { refList, refNames } from "./refs.js";
+/** Groups: one word an author can hold in their head, expanded to SDK names. */
+export const TOOL_MAP = {
+    // `web` includes Anthropic's server-side WebSearch, the one built-in tool
+    // that runs off the box and bills per call. `fetch` is the local half only:
+    // an agent that searches through the account's own `websearch` tool and
+    // reads pages with WebFetch never leaves the box for anything but tokens.
+    web: ["WebSearch", "WebFetch"],
+    fetch: ["WebFetch"],
+    // `read` is deliberately separate from `files`: an agent that may inspect a
+    // repository but must never modify it is a real and common design.
+    read: ["Read", "Glob", "Grep"],
+    files: ["Read", "Write", "Edit", "Glob", "Grep"],
+    bash: ["Bash"],
+};
+/** Exact SDK tool names, accepted alongside the group aliases so a Claude Code
+ *  subagent's `tools: Read, Grep` works unchanged. The aliases exist because
+ *  vendors rename tools; `web` survives a rename that `WebSearch` would not. */
+export const BUILTIN_TOOLS = new Set([
+    "Read", "Write", "Edit", "MultiEdit", "Glob", "Grep", "Bash",
+    "WebSearch", "WebFetch", "NotebookEdit", "TodoWrite",
+]);
+/** The platform's own groups, served in-process rather than by the SDK. */
+export const PLATFORM_GROUPS = new Set(["search", "history", "desks"]);
+/** Would this name resolve to something the runtime provides? Built-ins win a
+ *  clash, so a tool file of the same name is shadowed rather than granted. */
+export function isRuntimeTool(name) {
+    return Boolean(TOOL_MAP[name]) || PLATFORM_GROUPS.has(name) || BUILTIN_TOOLS.has(name);
+}
+/** The name an entry grants. `tools:` also takes the map form for approval
+ *  mode — `{Bash: ask}` — where the key is the tool and the value the mode. */
+export function toolEntryName(entry) {
+    return refList([entry])[0]?.name ?? "";
+}
+/** Every entry of `tools:`, with whether it was written as a `[[link]]`. */
+export function toolRefs(front) {
+    return refList(front.tools);
+}
+/** Is this entry one of the author's own tools? A `[[link]]` always is —
+ *  the brackets say "my file", so `[[search]]` is yours even though `search`
+ *  is a runtime group. A bare name is the author's only when no built-in
+ *  claims it. */
+export function isOwnToolRef(ref) {
+    return ref.linked || !isRuntimeTool(ref.name);
+}
+/**
+ * Every name in `tools:` that can only mean one of the author's own tools.
+ * Deduped, order preserved. Names that resolve to nothing are still
+ * returned: the caller reports them, and "you asked for a tool that isn't
+ * there" is a better error than silence.
+ */
+export function ownToolNames(front) {
+    const out = [];
+    for (const ref of toolRefs(front)) {
+        if (isOwnToolRef(ref) && !out.includes(ref.name))
+            out.push(ref.name);
+    }
+    return out;
+}
+/** What a file still says under the removed `use:` key — nothing is granted
+ *  for these; they exist so the error can quote the exact `tools:` line. */
+export function legacyUseNames(front) {
+    return refNames(front.use);
+}
+/** The one sentence every reader of a `use:` key says. */
+export function legacyUseError(names) {
+    return `\`use:\` is no longer read — write \`tools: [${names.join(", ")}]\` instead (scripts/migrate-use-to-tools.mjs rewrites every agent). Nothing was granted for it.`;
+}

package/dist/src/tool-programs.d.ts

@@ -0,0 +1,18 @@
+export interface MissingProgram {
+    /** The tool's name, as an agent would write it in `tools:`. */
+    name: string;
+    /** Which shelf it came off — the two resolve differently. */
+    scope: "workspace" | "account";
+    /** The `run:` as the definition spells it, after folder qualification. */
+    run: string;
+    /** The absolute path that was looked for, so the message can be acted on. */
+    looked: string;
+}
+/**
+ * Every script tool an agent here could call whose program is not on disk.
+ *
+ * Both shelves, because a grant reaches both and the runtime resolves
+ * nearest-wins across them — a checker that only read the workspace would
+ * call a working account tool broken.
+ */
+export declare function missingToolPrograms(tenant: string, workspace: string): MissingProgram[];

package/dist/src/tool-programs.js

@@ -0,0 +1,52 @@
+// Does a script tool's `run:` actually point at a program?
+//
+// The failure this exists for is the quietest one the format has. A script
+// tool whose `run:` resolves to nothing does not raise an error at load: the
+// definition parses, the tool is counted, the agent is told it has the
+// capability — and then the call fails inside a turn as a tool error the
+// model paraphrases into something plausible. `foldrun check` counted such a
+// tool among the workspace's tools and printed "no problems", which is the
+// one report that makes a typo invisible.
+//
+// The resolution here is the runtime's, not a second copy of it. That matters
+// more than it looks: `run:` has six accepted spellings across three scopes,
+// and a checker that reimplemented them would eventually disagree with the
+// runner — passing a tool that cannot run, or failing one that can.
+import fs from "node:fs";
+import path from "node:path";
+import { workspaceDir, workspaceTools } from "./store.js";
+import { libraryDir, libraryTools } from "./library.js";
+import { resolveRunPath } from "./script-tools.js";
+/**
+ * Every script tool an agent here could call whose program is not on disk.
+ *
+ * Both shelves, because a grant reaches both and the runtime resolves
+ * nearest-wins across them — a checker that only read the workspace would
+ * call a working account tool broken.
+ */
+export function missingToolPrograms(tenant, workspace) {
+    const dir = workspaceDir(tenant, workspace);
+    // Tools are workspace- or account-scoped, so resolve as if from an agent
+    // directory one level down — the same base the runtime and the tool tester
+    // both use.
+    const from = path.join(dir, "agents", "_probe");
+    const libScripts = libraryDir(tenant, "scripts");
+    const out = [];
+    const scan = (defs, scope) => {
+        for (const [name, def] of Object.entries(defs)) {
+            if (def.kind !== "script")
+                continue;
+            const run = String(def.spec.run ?? "");
+            // A single-file tool carries its program in the body and has no path to
+            // resolve. It is a shape we still accept, not a missing program.
+            if (!run)
+                continue;
+            const looked = resolveRunPath(from, run, libScripts);
+            if (!fs.existsSync(looked))
+                out.push({ name, scope, run, looked });
+        }
+    };
+    scan(libraryTools(tenant), "account");
+    scan(workspaceTools(tenant, workspace), "workspace");
+    return out;
+}

package/dist/src/tool-test.d.ts

@@ -0,0 +1,19 @@
+import { type ToolDef } from "./store.ts";
+export interface ToolTestResult {
+    ok: boolean;
+    transport: "http" | "script" | "mcp";
+    /** One line, safe to show next to the button. */
+    summary: string;
+    /** The response body, stdout, or the server's tool list. Truncated. */
+    detail: string;
+    ms: number;
+    /** Names only — never values. */
+    missingSecrets: string[];
+}
+export interface ToolTestInput {
+    /** http: the path to try, appended to `base:`. */
+    path?: string;
+    /** script: values for the tool's declared `args:`. */
+    args?: Record<string, string>;
+}
+export declare function testTool(tenant: string, workspace: string, def: ToolDef, input?: ToolTestInput): Promise<ToolTestResult>;