willfire 0.1.18 → 0.1.20

package/README.md

@@ -54,9 +54,9 @@ workflows all applied. That is the unit required status checks key on, so it
 is the one worth comparing against. On a `JobEntry` it is `null` only where no
 single name is knowable ahead of the run:
 
-- a matrix computed at runtime (`fromJSON` of another job's output) whose
-  outputs were not supplied, reported as one `unknown` entry for that job and
-  nothing else — see "Supplying job outputs" below;
+- a matrix computed at runtime (`fromJSON` of another job's output) that
+  execution could not resolve, reported as one `unknown` entry for that job
+  and nothing else — see "Executing needed jobs" below;
 - a reusable workflow we cannot read — private, deleted, a ref that does not
   exist, a `uses:` built from an expression, or one nested past GitHub's
   four-level limit;
@@ -84,8 +84,7 @@ Auth is any token with `contents: read`, `actions: read`, and
 
 ```sh
 GH_TOKEN=... willfire --repo owner/repo --pr 123 \
-  [--action opened|synchronize|reopened] [--json] \
-  [--execute owner/repo:job1,job2]...
+  [--action opened|synchronize|reopened] [--json]
 ```
 
 Plain-text output is one line per entry, then a `# read owner/repo@ref -> sha`
@@ -102,8 +101,9 @@ workflows — both the local `./.github/workflows/x.yml` form and the cross-repo
 commit and the callee then read at that commit. Jobs whose `if` is false are
 predicted as `skipped` entries, matching how they appear in the checks UI.
 
-Things that cannot be known statically are reported as `unknown` rather than
-guessed.
+A matrix computed by another job's outputs is not static; willfire resolves it
+by running that job in a sandbox — see "Executing needed jobs". Everything
+else that cannot be known is reported as `unknown` rather than guessed.
 
 ## Supplying job outputs
 
@@ -138,47 +138,46 @@ lookup against it then stays unknown.
 `needs` is workflow-scoped and is not inherited across a reusable-workflow
 call: a callee's `needs.detect` is the callee's own job.
 
-Nothing in willfire works out what those outputs are on its own. `predict`
-supplies none unless the caller grants execution — see below — so a dynamic
-matrix stays `unknown` by default.
+Nothing here guesses what those outputs are. By default `predict` computes
+them, by executing the jobs that produce them — the section below. With
+execution turned off (`executor: null` in `PredictOptions`) a dynamic matrix
+stays `unknown`.
 
-## Executing granted jobs
+## Executing needed jobs
 
 The job those outputs come from is usually a few shell steps over the checked
-out tree — cheap to run for real. `predict` will do that, but only for jobs
-the caller names:
-
-```ts
-await predict(octokit, "owner/repo", 123, {
-  execute: [{ repo: "the-org/conventions", jobs: ["detect"] }],
-});
-```
-
-```sh
-willfire --repo owner/repo --pr 123 \
-  --execute the-org/conventions:detect
-```
-
-A grant names the repo the workflow *file* lives in — for a reusable workflow,
-the callee — and the job ids within it. Before expansion reads `needs`, each
-granted job that is predicted to run is executed: the PR's head tree is
-materialized from a tarball, the job's steps run in order under their declared
-shell and env, step-level `if:` guards are evaluated, composite actions are
-fetched at their pinned commit and recursed into, and a bare
-`actions/checkout` is satisfied by the tree already present. What the steps
-write to `$GITHUB_OUTPUT` becomes the job's outputs, exactly as if they had
-been supplied by hand.
-
-Execution is mechanism, not policy: willfire knows nothing about any repo, and
-with no grants nothing runs. The steps execute for real — nothing interprets
-or approximates shell — so grant only jobs whose code you trust at the commit
-being predicted; a granted job runs the PR's version of itself.
-
-Anything execution cannot do faithfully fails the grant rather than guessing:
-a JavaScript or Docker action, a checkout with inputs, a matrix'd or
-containerized granted job, an undecidable step `if:`, a non-zero exit, output
-willfire cannot parse. The failure does not change any verdict — entries that
-needed the outputs stay `unknown`, with the reason threaded through:
+out tree — cheap to run for real. `predict` does that, and works out for
+itself which jobs are worth it: a job is executed exactly when some sibling
+job reads its `needs.<id>.outputs`. That fact is written in the workflow being
+predicted, so there is nothing to configure and no repo knowledge in willfire.
+
+Each selected job that is predicted to run is executed before expansion reads
+`needs`: the PR's head tree is materialized from a tarball, the job's steps
+run in order under their declared shell and env, step-level `if:` guards are
+evaluated, composite actions are fetched at their pinned commit and recursed
+into, and a bare `actions/checkout` is satisfied by the tree already present.
+A checkout asking for history (`fetch-depth: 0`) switches the workspace to a
+real clone at the same commit. What the steps write to `$GITHUB_OUTPUT`
+becomes the job's outputs, exactly as if they had been supplied by hand.
+
+The steps execute for real — nothing interprets or approximates shell — and
+the code that runs is the PR's own version of itself. What makes that safe to
+do by default is the sandbox: steps run in a docker container with no network,
+none of the host's environment, no credentials, an unprivileged user, and a
+read-only image (`node:24-slim` plus git and python3), with only the workspace tree
+writable. Docker is the one runtime requirement; where it is missing,
+execution fails and the entries that needed it stay `unknown` with the reason
+attached.
+
+Node actions (`runs.using: node24`) run under the sandbox's node with their
+`inputs:` bound as `INPUT_*` variables; `actions/setup-node` is satisfied as a
+no-op when it asks for exactly the node the sandbox has. Anything execution
+cannot do faithfully fails rather than guessing: a Docker action, a node
+action wanting another major, a checkout with inputs beyond `fetch-depth`, a
+matrix'd or containerized job, an undecidable step `if:`, a non-zero exit,
+output willfire cannot parse. The failure does not change any verdict —
+entries that needed the outputs stay `unknown`, with the reason threaded
+through:
 
 ```
 dynamic matrix; executing 'detect' failed: step 'scan': exited 1 (...)

package/dist/cli/parseArgs.d.ts

@@ -1,9 +1,7 @@
-import { type ExecutionGrant } from "../execute.js";
 import type { PrEventAction } from "../types.js";
 export declare function parseArgs(argv: string[]): {
     repo: string;
     pr: number;
     json: boolean;
     action?: PrEventAction;
-    execute: ExecutionGrant[];
 };

package/dist/cli/parseArgs.js

@@ -1,6 +1,4 @@
-import { parseGrant } from "../execute.js";
-const USAGE = "usage: predict --repo owner/name --pr N [--action opened|synchronize|reopened]" +
-    " [--execute owner/repo:job1,job2]... [--json]";
+const USAGE = "usage: predict --repo owner/name --pr N [--action opened|synchronize|reopened] [--json]";
 const isPrEventAction = (v) => v === "opened" || v === "synchronize" || v === "reopened";
 export function parseArgs(argv) {
     const get = (flag) => {
@@ -22,22 +20,5 @@ export function parseArgs(argv) {
         console.error(USAGE);
         process.exit(2);
     }
-    // Repeatable, one grant per flag. A malformed grant is refused for the same
-    // reason a bad --action is: silently dropping it would predict without the
-    // execution the caller thought they asked for.
-    const execute = [];
-    for (let i = 0; i < argv.length; i++) {
-        if (argv[i] !== "--execute") {
-            continue;
-        }
-        const spec = argv[i + 1];
-        const grant = spec == null ? null : parseGrant(spec);
-        if (grant == null) {
-            console.error(`bad --execute: ${spec}`);
-            console.error(USAGE);
-            process.exit(2);
-        }
-        execute.push(grant);
-    }
-    return { repo, pr: Number(pr), json: argv.includes("--json"), action, execute };
+    return { repo, pr: Number(pr), json: argv.includes("--json"), action };
 }

package/dist/cli.js

@@ -13,7 +13,6 @@ if (isMain) {
     const args = parseArgs(process.argv.slice(2));
     const prediction = await predict(makeOctokit(), args.repo, args.pr, {
         action: args.action,
-        execute: args.execute,
     });
     const { entries, skip, sources } = prediction;
     if (args.json) {

package/dist/execute.d.ts

@@ -1,76 +1,46 @@
 /**
- * Execute a job the caller granted, to learn what static reading cannot.
- *
- * A dynamic matrix — `language: ${{ fromJSON(needs.detect.outputs.x) }}` — is
- * the values another job computes at runtime. No amount of reading the YAML
- * yields them; the fleet's `detect` job runs a script over the repo tree and
- * writes what it finds to `$GITHUB_OUTPUT`. So this module runs that job the
- * way the runner would: materialize the tree at the pinned commit, walk the
- * steps in order, execute each `run:` under its declared shell and env, and
- * assemble the job's `outputs:` map from what the steps actually wrote.
- *
- * Three rules keep this honest:
- *
- * 1. **Nothing runs without a grant.** willfire has no opinion about which
- *    jobs are safe to execute; the caller names them, one repo and job id at
- *    a time, and everything else stays as unresolved as it was.
- * 2. **Run it, never interpret it.** The `run:` script is handed to the shell
- *    the step declares, with the env it declares. What lands in
- *    `$GITHUB_OUTPUT` is the answer; no shell text is ever parsed for meaning.
- * 3. **Anything off the modelled path is a hard stop with a reason.** A
- *    JavaScript action, an undecidable `if:`, a `${{ }}` that will not
- *    resolve, a step that exits non-zero — each fails the execution and says
- *    what it hit, and the consumers of that job's outputs stay unresolved.
- *    Guessing is the one move this module never makes.
- *
- * `actions/checkout` is the deliberate exception to rule 2. It is provided by
- * the runner, not run from its repo, and its whole postcondition — the
- * workspace tree at the commit under test — is something the executor has
- * already satisfied by materializing the tree. A bare checkout is therefore
- * recorded as done; a checkout *with inputs* is not modelled and stops.
+ * Execute a job whose outputs another job reads, the way the runner would:
+ * materialize the tree, walk the steps, read what they wrote to
+ * `$GITHUB_OUTPUT`. Two invariants: run it, never interpret it (no shell text
+ * is parsed for meaning), and anything off the modelled path is a hard stop
+ * with a reason — never a guess.
  */
 import { type Scope } from "./expr/val.js";
 import type { ResolveRef, WorkflowSource } from "./types.js";
-/**
- * Permission to execute named jobs from one repo's workflows.
- *
- * `repo` is the repo the *workflow file* lives in — for a fleet consumer
- * calling `testing-conventions/.github/workflows/testing-conventions.yml@v0`,
- * that is `thekevinscott/testing-conventions`, whatever repo the PR is on.
- * The grant is deliberately this narrow: a job id alone would execute
- * whatever any transitively-reached workflow happens to call by that name.
- */
-export interface ExecutionGrant {
-    /** `owner/name` of the repo whose workflow defines the jobs. */
-    repo: string;
-    /** Job ids within that repo's workflows that may be executed. */
-    jobs: string[];
+/** A host path a sandboxed runner must expose inside, at the same path. */
+export interface Mount {
+    path: string;
+    writable: boolean;
 }
-/** `owner/repo:job1,job2` as the CLI spells a grant. */
-export declare function parseGrant(spec: string): ExecutionGrant | null;
 /** One shell invocation, fully specified — nothing is inherited implicitly. */
 export interface RunSpec {
     script: string;
     shell: "bash" | "sh";
     cwd: string;
     env: Record<string, string>;
+    /** For runners that isolate: what of the host this run may see. A direct
+     * shell ignores this — it already sees everything. */
+    mounts?: Mount[];
 }
 export interface RunResult {
     code: number;
-    /** Captured so a failing step can say *why* in its reason. */
     stderr: string;
 }
 export type RunCommand = (spec: RunSpec) => Promise<RunResult>;
 /**
- * Materialize a repo tree at a commit and return its root directory, or null
- * when it cannot be had. Must not throw.
+ * Materialize a repo tree at a commit, or null when it cannot be had. Must not
+ * throw. `history: true` demands full git history (the `fetch-depth: 0`
+ * postcondition); a provider that cannot supply it answers null.
  */
-export type ProvideTree = (source: WorkflowSource) => Promise<string | null>;
-/** The three reaches into the world an execution needs, bundled for injection. */
+export type ProvideTree = (source: WorkflowSource, opts?: {
+    history?: boolean;
+}) => Promise<string | null>;
 export interface ExecDeps {
     provideTree: ProvideTree;
     runCommand: RunCommand;
     resolveRef: ResolveRef;
+    /** The node major `runCommand`'s world provides; asking for another is refused. */
+    nodeMajor: number;
 }
 export type ExecOutcome = {
     ok: true;
@@ -80,44 +50,46 @@ export type ExecOutcome = {
     reason: string;
 };
 /**
- * What expansion asks of an executor. The caller decides *whether* a job
- * runs with its own scope — the executor only decides what running it
- * yields. Step-level guards inside the job are evaluated here, against the
- * fixed facts of the run (notably `github.repository`, which the fleet's
- * hermetic-vs-published guards are written against).
+ * The caller decides *whether* a job runs; the executor only decides what
+ * running it yields.
  */
 export interface JobExecutor {
-    granted(source: WorkflowSource, jobId: string): boolean;
     executeJob(jobId: string, job: any, wf: any, scope: Scope): Promise<ExecOutcome>;
 }
 /**
- * The `$GITHUB_OUTPUT` file format: `name=value` lines, or a
- * `name<<DELIMITER … DELIMITER` heredoc for multi-line values. Anything else
- * fails the parse — the runner fails the step on a malformed line, so
- * tolerating one here would invent outputs a real run never had.
+ * Render every `${{ }}` to literal text, or null when any cannot be settled —
+ * a partial render would be a different program.
+ */
+export declare function renderTemplate(text: string, scope: Scope): string | null;
+/**
+ * `name=value` lines or `name<<DELIMITER` heredocs. Anything else fails the
+ * parse, as the runner fails the step on a malformed line.
  */
 export declare function parseGithubOutput(text: string): Record<string, string> | null;
 export declare function makeExecutor(opts: {
-    grants: ExecutionGrant[];
     /**
-     * The PR's own repo at the head commit — what `actions/checkout` provides
-     * on a real runner, wherever the workflow file itself lives. A reusable
-     * workflow's jobs run in the caller's workspace; this is that fact.
+     * The PR's own repo at the head commit. A reusable workflow's jobs run in
+     * the caller's workspace, wherever the workflow file lives.
      */
     workspace: WorkflowSource;
     deps: ExecDeps;
 }): JobExecutor;
 /**
- * The runner's default shell invocations, faithfully: `bash --noprofile
- * --norc -e -o pipefail` and `sh -e`. Nothing of the parent environment
- * leaks in beyond what the spec names.
+ * The runner's default shell invocations, faithfully. Nothing of the parent
+ * environment leaks in beyond what the spec names.
  */
 export declare const runShell: RunCommand;
 /**
- * Materialize repo trees from tarballs, one download per commit however many
- * steps ask. GitHub's tarballs wrap the tree in a single
- * `owner-repo-shortsha/` directory, which is unwrapped so callers get the
- * tree root itself. Extraction shells out to `tar` through the same
- * `RunCommand` seam every other subprocess uses.
+ * Materialize repo trees from tarballs, one download per commit. GitHub wraps
+ * the tree in a single `owner-repo-shortsha/` directory, unwrapped here.
  */
 export declare function makeTreeProvider(download: (source: WorkflowSource) => Promise<Uint8Array | null>, runCommand: RunCommand): ProvideTree;
+/**
+ * Materialize repo trees by full clone, on the host — it needs the network
+ * the sandbox denies. The token never touches the URL or persisted git
+ * config, because `.git/config` later rides into the sandbox: auth travels
+ * as a per-invocation `http.extraheader` and is gone when the command is.
+ */
+export declare function makeCloneProvider(runCommand: RunCommand, token: string | null, opts?: {
+    remoteUrl?: (source: WorkflowSource) => string;
+}): ProvideTree;