@foldrun/core 0.2.0

package/dist/src/flow-lint.js

@@ -0,0 +1,177 @@
+// Structural checks on a flow's arrangement.
+//
+// A flow can be perfectly valid markdown and still be guaranteed to produce
+// fiction — the clearest case being a reviewer scheduled in group 1, whose
+// instruction says "review both changes" while its context is empty because
+// nothing has run yet. The model won't fail; it will invent a review and the
+// run goes green. Work that quietly stops happening is exactly what these
+// checks exist to make loud.
+//
+// Every check here is *structural*: it reasons about what a step can possibly
+// have in context, never about whether the model did a good job. Nothing is
+// blocked — flows still run, warnings are advisory.
+// Anaphora: phrases that only mean something if earlier output exists.
+// Deliberately conservative — a false warning is worse than a missed one,
+// because noisy warnings get ignored and then the real one is invisible too.
+const REFERS_BACK = /\b(both|above|earlier|previous(ly)?|prior|the (changes|draft|research|results|findings|report|article|fixes|work)|what (they|the others?) (found|shipped|wrote|said))\b/i;
+export function lintFlow(flow, known) {
+    const warnings = [];
+    const agentNames = known ? new Set(known.agents) : null;
+    // Cron's oldest trap, and an expensive one: when day-of-month AND
+    // day-of-week are both restricted they are OR'd, not AND'd — the scheduler
+    // does it too, correctly (`domRestricted && dowRestricted` → `domOk ||
+    // dowOk`). So `0 5 1-7 * 5`, which every reader parses as "first Friday of
+    // the month", fires every Friday AND every day of the first week: about
+    // eleven runs where one was meant. Nothing about the expression looks wrong,
+    // which is exactly why it needs saying here rather than being discovered on
+    // the bill.
+    if (flow.schedule) {
+        const [, , dom, , dow] = flow.schedule.trim().split(/\s+/);
+        if (dom && dow && dom !== "*" && dow !== "*") {
+            warnings.push({
+                step: null,
+                message: `schedule "${flow.schedule}" restricts both day fields — cron runs it on EITHER, not both`,
+                detail: "Day-of-month and day-of-week are OR'd when both are set, so this fires far more often " +
+                    "than it reads. For \"the Nth weekday of the month\" there is no cron form; use a plain " +
+                    "day-of-month (`0 5 3 * *`) for monthly, or a plain weekday (`0 5 * * 1`) for weekly.",
+            });
+        }
+    }
+    // Trigger shapes that can never fire, said at check time rather than
+    // discovered as a flow that "never runs".
+    if (flow.trigger === "once" && !flow.at) {
+        warnings.push({ step: null, message: "trigger: once needs an `at:` instant", detail: "Write `at: 2026-09-05T09:00:00+10:00` (ISO 8601). Without a readable instant this flow never fires." });
+    }
+    if (flow.trigger === "watch" && !/^https?:\/\//.test(flow.url ?? "")) {
+        warnings.push({ step: null, message: "trigger: watch needs an http(s) `url:`", detail: "The scheduler polls that URL and starts the flow when its content changes." });
+    }
+    if (flow.trigger === "flow") {
+        if (!flow.after)
+            warnings.push({ step: null, message: "trigger: flow needs `after: <flow>`", detail: "Name the flow of this workspace whose finishing starts this one." });
+        else if (flow.after === flow.name)
+            warnings.push({ step: null, message: "trigger: flow — a flow cannot chain on itself", detail: "That is a loop with no bound. Chain on the flow that produces what this one needs." });
+    }
+    if (flow.signature && !flow.signingSecret) {
+        warnings.push({ step: null, message: `signature: ${flow.signature} needs \`signing_secret: \${NAME}\``, detail: "Every delivery will be refused until the secret is named and set in Settings → Secrets." });
+    }
+    if (flow.signature && flow.trigger !== "webhook") {
+        warnings.push({ step: null, message: "signature: only applies to trigger: webhook", detail: "Inbox and other triggers do not carry a provider signature; the line does nothing here." });
+    }
+    if (flow.steps.length === 0)
+        return warnings;
+    const firstGroup = Math.min(...flow.steps.map((s) => s.group));
+    flow.steps.forEach((step, i) => {
+        const inFirstGroup = step.group === firstGroup;
+        // The first group starts with context = null. An instruction that points
+        // at earlier output therefore points at nothing.
+        if (inFirstGroup && step.instruction && REFERS_BACK.test(step.instruction)) {
+            warnings.push({
+                step: i,
+                line: step.line,
+                message: `"${step.subflow ?? step.agent}" refers to earlier work but runs first`,
+                detail: "Steps in the first group start with no context — nothing has run yet. This agent will " +
+                    "invent what it was asked to review rather than fail. Move it to a later group.",
+            });
+        }
+        // A gate with no `preview:` shows only the previous step's reply and
+        // whatever files that reply happens to name. The person deciding sees a
+        // summary, not the thing — unless the agent remembered.
+        if ((step.approve || step.ask) && !step.preview?.length) {
+            warnings.push({
+                step: i,
+                line: step.line,
+                message: `"${step.subflow ?? step.agent}" is a gate with no preview:`,
+                detail: "The approval box shows the previous step's reply and any storage/ file it names. " +
+                    "Declare what to show — `preview: draft/*.mdx, draft/images/*.webp` — so the approver " +
+                    "always sees the document, not a pointer, even when the agent forgets to name it.",
+            });
+        }
+        // `each: items` fans out over DATA, and only an `output: json` step in
+        // an earlier group produces any. Without one the step expands to
+        // nothing every time, quietly — the exact failure this file exists for.
+        if (step.each === "items") {
+            const feeder = flow.steps.some((s) => s.group < step.group && s.output === "json");
+            if (!feeder) {
+                warnings.push({
+                    step: i,
+                    line: step.line,
+                    message: `"${step.subflow ?? step.agent}" fans out with each: items but no earlier step returns data`,
+                    detail: "each: items reads the JSON array an `output: json` step returned. No step before this " +
+                        "one declares output: json, so there are never any items and this step is always skipped. " +
+                        "Add `output: json` to the step that produces the list.",
+                });
+            }
+        }
+        // A step's OTHER agent references — the ones no parser validates,
+        // because they are options rather than the step's target. Both fail
+        // silently and at the worst possible moment: a misspelled `delegate:`
+        // name is simply never chosen (the runner filters picks to the declared
+        // set), and a misspelled `on-fail:` is discovered only once something
+        // has already gone wrong.
+        if (agentNames) {
+            for (const name of step.delegate ?? []) {
+                if (!agentNames.has(name)) {
+                    warnings.push({
+                        step: i,
+                        line: step.line,
+                        message: `delegate: "${name}" is not an agent in this workspace`,
+                        detail: "The runner only accepts picks from the declared set, so this name can never be " +
+                            "chosen — the step silently has one fewer colleague to call on. Fix the spelling, " +
+                            "or drop the name.",
+                    });
+                }
+            }
+            if (step.onFail && !agentNames.has(step.onFail)) {
+                warnings.push({
+                    step: i,
+                    line: step.line,
+                    message: `on-fail: "${step.onFail}" is not an agent in this workspace`,
+                    detail: "The recovery path is the one you cannot test by running the flow successfully. As " +
+                        "written, a failure here has nowhere to go and the step just fails.",
+                });
+            }
+        }
+        if (step.onFail && step.onFail === step.agent && !step.subflow) {
+            warnings.push({
+                step: i,
+                line: step.line,
+                message: `on-fail: "${step.onFail}" is the agent that just failed`,
+                detail: "The same agent is handed the same instruction with its own failure as context. That is " +
+                    "`retry:` with extra steps — name a different agent, or use retry:.",
+            });
+        }
+        // `when:` tests the previous results, which the first group doesn't have.
+        if (inFirstGroup && step.when) {
+            warnings.push({
+                step: i,
+                line: step.line,
+                message: `"${step.subflow ?? step.agent}" has a when: condition but runs first`,
+                detail: `Nothing has produced output yet, so "${step.when}" can never match and this step will ` +
+                    "always be skipped. Move it after the step whose output it depends on.",
+            });
+        }
+    });
+    // The same agent twice in one parallel group gets two identical contexts and
+    // no way to divide the work — almost always a drag that landed wrong.
+    const byGroup = new Map();
+    for (const s of flow.steps)
+        byGroup.set(s.group, [...(byGroup.get(s.group) ?? []), s]);
+    for (const [group, steps] of byGroup) {
+        const counts = new Map();
+        for (const s of steps) {
+            const key = s.subflow ? `flow:${s.subflow}` : s.agent;
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+        }
+        for (const [agent, n] of counts) {
+            if (n > 1) {
+                warnings.push({
+                    step: null,
+                    message: `"${agent}" appears ${n} times in group ${group}`,
+                    detail: "Both copies run at the same time with identical context, so they'll do the same work " +
+                        "twice. Put them in different groups, or give each a distinct instruction.",
+                });
+            }
+        }
+    }
+    return warnings;
+}

package/dist/src/git-hook.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/git-hook.js

@@ -0,0 +1,70 @@
+// The pre-receive check, run by git inside a push.
+//
+// git feeds "<old> <new> <ref>" lines on stdin. For a push to main, read the
+// tree at the new commit straight from the object store and run the deploy
+// checks on it. Any issue: print them and exit non-zero — the push is refused
+// and the person sees exactly what a dashboard deploy would have told them,
+// in their terminal, before anything changed.
+//
+// Runs as its own process under git's environment. GIT_DIR is set by git.
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { deployIssues, runsInFlight } from "./deploy.js";
+const dir = process.env.GIT_DIR;
+if (!dir)
+    process.exit(0);
+// `_library.git` is the account shelf, not a workspace: it holds tools,
+// skills and knowledge and has no agents by definition. The workspace rules
+// refused every push to it with "no agents". Its sync (syncLibraryFromTree)
+// validates what it accepts on receive; nothing here to add yet.
+// Inside a hook git sets GIT_DIR relative to the repo ("."), so resolve it
+// against the cwd before asking for its name.
+if (path.basename(path.resolve(process.cwd(), dir)) === "_library.git")
+    process.exit(0);
+const input = fs.readFileSync(0, "utf8");
+const git = (args) => {
+    const r = spawnSync("git", ["--git-dir", dir, ...args], { maxBuffer: 64 * 1024 * 1024 });
+    return r.status === 0 ? r.stdout.toString() : null;
+};
+// The client is gone by the time the deploy runs, so this is the only moment
+// a person can be told their push will not take effect yet. A warning, not a
+// refusal: the commit is fine and the scheduler applies it when the runs end.
+const here = path.basename(path.resolve(process.cwd(), dir));
+if (here.endsWith(".git")) {
+    const workspace = here.slice(0, -4);
+    const tenant = path.basename(path.resolve(process.cwd(), dir, "..", ".."));
+    try {
+        const live = runsInFlight(tenant, workspace);
+        if (live.length) {
+            process.stderr.write(`\nfoldrun: ${live.length} run${live.length === 1 ? " is" : "s are"} in flight, so this push is not live yet.\n` +
+                `  It is on main and will be applied automatically when they finish.\n\n`);
+        }
+    }
+    catch {
+        // A warning that cannot be computed must never fail a push.
+    }
+}
+let refused = false;
+for (const line of input.split("\n").filter(Boolean)) {
+    const [, newSha, ref] = line.split(" ");
+    if (ref !== "refs/heads/main" || /^0+$/.test(newSha))
+        continue;
+    const tree = git(["ls-tree", "-r", "--name-only", newSha]) ?? "";
+    const files = tree
+        .split("\n")
+        .filter(Boolean)
+        .flatMap((p) => {
+        const content = git(["show", `${newSha}:${p}`]);
+        return content === null ? [] : [{ path: p, content }];
+    });
+    const issues = deployIssues(files);
+    if (issues.length) {
+        refused = true;
+        process.stderr.write(`\nfoldrun: refusing this push — ${issues.length} problem${issues.length === 1 ? "" : "s"} the checks would have stopped at deploy:\n`);
+        for (const i of issues)
+            process.stderr.write(`  ${i.where}: ${i.message}\n`);
+        process.stderr.write(`\nFix and push again. (foldrun check runs the same rules locally.)\n\n`);
+    }
+}
+process.exit(refused ? 1 : 0);

package/dist/src/git.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The secret a repository signs its pushes with.
+ *
+ * Derived rather than stored, exactly like a flow's webhook token: HMAC of the
+ * workspace's identity under the install key. Nothing new to persist, unique
+ * per workspace, and rotating FOLDRUN_SECRET_KEY invalidates every connection
+ * at once.
+ */
+export declare function gitSecret(tenant: string, workspace: string): string;
+export declare function gitHookPath(tenant: string, workspace: string): string;
+/**
+ * Whether a request really came from the repository it claims to.
+ *
+ * Compared in constant time: a byte-by-byte early return leaks the expected
+ * signature to anyone willing to time enough requests. The raw body is
+ * required — re-serializing parsed JSON changes bytes GitHub signed.
+ */
+export declare function verifySignature(secret: string, rawBody: string, header: string | null): boolean;
+export interface PushEvent {
+    repo: string;
+    /** Full ref, e.g. refs/heads/main. */
+    ref: string;
+    branch: string;
+    commit: string;
+    message: string | null;
+    pusher: string | null;
+}
+/** What we need out of a GitHub push payload, or null if it isn't one. */
+export declare function parsePush(payload: unknown): PushEvent | null;
+/**
+ * The repository at one commit, as a gzipped tarball.
+ *
+ * A token is only needed for a private repository. It is read from the
+ * environment rather than taken as an argument so a caller cannot be tricked
+ * into forwarding one somewhere else.
+ */
+export declare function fetchTarball(repo: string, commit: string): Promise<Buffer>;

package/dist/src/git.js

@@ -0,0 +1,101 @@
+// git push → deployed.
+//
+// A workspace is markdown, so there is no build to run: a push is a fetch of
+// the tree at that commit, a check, and a swap. This module is the GitHub half
+// — the secret a repository signs with, the payload shape, and pulling the
+// tarball. `deploy.ts` decides whether the result is allowed to go live.
+//
+// The tarball, not a clone: one HTTP call, no git binary, no working copy kept
+// on the server. A markdown workspace is a few hundred kilobytes.
+import crypto from "node:crypto";
+import { installKey } from "./webhook.js";
+/** GitHub refuses to fetch anything larger, and neither should we. */
+const MAX_TARBALL = 25 * 1024 * 1024;
+/**
+ * The secret a repository signs its pushes with.
+ *
+ * Derived rather than stored, exactly like a flow's webhook token: HMAC of the
+ * workspace's identity under the install key. Nothing new to persist, unique
+ * per workspace, and rotating FOLDRUN_SECRET_KEY invalidates every connection
+ * at once.
+ */
+export function gitSecret(tenant, workspace) {
+    return crypto
+        .createHmac("sha256", installKey())
+        .update(`git/${tenant}/${workspace}`)
+        .digest("hex");
+}
+export function gitHookPath(tenant, workspace) {
+    return `/api/git/${tenant}/${workspace}`;
+}
+/**
+ * Whether a request really came from the repository it claims to.
+ *
+ * Compared in constant time: a byte-by-byte early return leaks the expected
+ * signature to anyone willing to time enough requests. The raw body is
+ * required — re-serializing parsed JSON changes bytes GitHub signed.
+ */
+export function verifySignature(secret, rawBody, header) {
+    if (!header)
+        return false;
+    const expected = `sha256=${crypto.createHmac("sha256", secret).update(rawBody).digest("hex")}`;
+    const a = Buffer.from(expected);
+    const b = Buffer.from(header);
+    return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+/** What we need out of a GitHub push payload, or null if it isn't one. */
+export function parsePush(payload) {
+    if (!payload || typeof payload !== "object")
+        return null;
+    const p = payload;
+    const repo = p.repository?.full_name;
+    const ref = p.ref;
+    const commit = p.after;
+    if (typeof repo !== "string" || typeof ref !== "string" || typeof commit !== "string") {
+        return null;
+    }
+    // A deleted branch reports all zeros and ships no tree.
+    if (/^0+$/.test(commit))
+        return null;
+    return {
+        repo,
+        ref,
+        branch: ref.replace(/^refs\/heads\//, ""),
+        commit,
+        message: typeof p.head_commit?.message === "string" ? p.head_commit.message : null,
+        pusher: typeof p.pusher?.name === "string" ? p.pusher.name : null,
+    };
+}
+/**
+ * The repository at one commit, as a gzipped tarball.
+ *
+ * A token is only needed for a private repository. It is read from the
+ * environment rather than taken as an argument so a caller cannot be tricked
+ * into forwarding one somewhere else.
+ */
+export async function fetchTarball(repo, commit) {
+    if (!/^[\w.-]+\/[\w.-]+$/.test(repo))
+        throw new Error(`refusing to fetch "${repo}"`);
+    if (!/^[0-9a-f]{7,40}$/i.test(commit))
+        throw new Error(`refusing to fetch commit "${commit}"`);
+    const headers = {
+        accept: "application/vnd.github+json",
+        "user-agent": "foldrun",
+        "x-github-api-version": "2022-11-28",
+    };
+    const token = process.env.GITHUB_TOKEN;
+    if (token)
+        headers.authorization = `Bearer ${token}`;
+    const res = await fetch(`https://api.github.com/repos/${repo}/tarball/${commit}`, { headers });
+    if (!res.ok) {
+        throw new Error(`GitHub returned ${res.status} for ${repo}@${commit.slice(0, 8)}` +
+            (res.status === 404 && !token
+                ? " — a private repository needs GITHUB_TOKEN set on the server"
+                : ""));
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (buf.length > MAX_TARBALL) {
+        throw new Error(`${repo} is ${Math.round(buf.length / 1e6)}MB — too large to deploy`);
+    }
+    return buf;
+}

package/dist/src/gitrepo.d.ts

@@ -0,0 +1,95 @@
+import type { DiffOp, Revision, RevisionFile, RevisionSummary } from "./history.ts";
+/** Where a workspace's bare repository lives. `@library` is the account shelf. */
+export declare function repoDir(tenant: string, scope: string): string;
+/** Is there a git binary? Checked once; an install without one keeps the journal. */
+export declare function gitAvailable(): boolean;
+export declare function repoExists(tenant: string, scope: string): boolean;
+/** Create the repository if it is not there. Idempotent. */
+export declare function ensureRepo(tenant: string, scope: string): string;
+export declare function headSha(tenant: string, scope: string, ref?: string): string | null;
+/**
+ * Apply a change set as one commit on main, using plumbing against a scratch
+ * index seeded from HEAD. No working copy, no checkout: each changed path is
+ * hashed straight from its content into the object store.
+ *
+ * Returns the new commit, or null when the tree did not change.
+ */
+export declare function commitChanges(tenant: string, scope: string, files: RevisionFile[], meta?: {
+    by?: string;
+    message?: string;
+    at?: string;
+}): string | null;
+/** Commits on main, newest first, as the same summary the journal gave. */
+export declare function listCommits(tenant: string, scope: string, opts?: {
+    forPath?: string;
+    limit?: number;
+    ref?: string;
+}): RevisionSummary[];
+/** One commit in full: every changed file with its before and after. */
+export declare function readCommit(tenant: string, scope: string, sha: string, forPath?: string): Revision | null;
+export interface RefInfo {
+    name: string;
+    sha: string;
+    /** Commit subject and time, for a branch list that says what each is. */
+    subject: string;
+    at: string;
+}
+export declare function listRefs(tenant: string, scope: string, kind: "heads" | "tags"): RefInfo[];
+/** The files at a commit, for a browser or a deploy. */
+export declare function listTree(tenant: string, scope: string, ref?: string): {
+    path: string;
+    mode: string;
+}[];
+export declare function readBlob(tenant: string, scope: string, ref: string, p: string): string | null;
+/** The whole tree at a ref as deploy files — what a push turns into a workspace. */
+export declare function filesAt(tenant: string, scope: string, ref: string): {
+    path: string;
+    content: string;
+}[];
+/**
+ * What a ref would change on main: every file that differs, with both sides.
+ * The branch's own commits are `listCommits({ ref })`; this is the net
+ * effect, which is what a reviewer reads.
+ */
+export declare function diffRefs(tenant: string, scope: string, base: string, head: string): RevisionFile[];
+/**
+ * Merge a branch into main and return the new main. A fast-forward when it
+ * is one; otherwise a merge commit whose tree is the BRANCH's — the branch
+ * is what the person reviewed and chose, and a three-way textual merge of
+ * markdown with no one to resolve conflicts would deploy text nobody wrote.
+ * Both parents are recorded, so history shows the merge for what it was.
+ */
+export declare function mergeBranch(tenant: string, scope: string, branch: string, meta?: {
+    by?: string;
+}): {
+    sha: string;
+    fastForward: boolean;
+};
+export declare function deleteBranch(tenant: string, scope: string, branch: string): void;
+/** Push main to another remote — a GitHub or GitLab mirror. Blocking; callers
+ *  run it off the request path. The token never touches disk: it is in the
+ *  URL for this one process and nowhere else. */
+export declare function pushMirror(tenant: string, scope: string, url: string): {
+    ok: boolean;
+    detail: string;
+};
+/**
+ * Where the compiled pre-receive check is, found on disk rather than through
+ * require.resolve — a bundler rewrites require.resolve("pkg") into a module
+ * id, and the hook was once told to run a script called "51113". Searched
+ * from the working directory upward: the monorepo layout, then an installed
+ * package. Empty when there is no compiled check (a dev server on the source
+ * tree), in which case a push is checked at deploy instead of refused — the
+ * same rules, one step later.
+ */
+export declare function hookScriptPath(): string;
+/**
+ * The pre-receive hook: a push that fails the deploy checks is refused with
+ * the errors in the pusher's terminal, instead of accepted and then not
+ * deployed. The hook shells out to node with the compiled check, so it runs
+ * the same rules as a dashboard deploy; which node and which script are
+ * passed in the environment by the HTTP route, because a hook inherits git's
+ * environment and nothing else.
+ */
+export declare function installHooks(dir: string): void;
+export { type DiffOp };