withruntime 0.23.0 → 0.33.0

package/dist/ci-cli.js

@@ -0,0 +1,343 @@
+import { me, named } from "./cli-name.js";
+import { ci, } from "./products/ci.js";
+export const CI_HELP = `runtime ci <command>
+
+  CI/CD checks each push and pull request of a connected GitHub repository in
+  sandboxes, as the steps its config file names. A fork's pull request waits
+  until a writer re-runs it on GitHub. In a private beta: outside it, each
+  command says how to ask to join.
+
+  connect <owner/name> [--branch main] [--config runtime.yml] [--installation <id>]
+          [--trust <app-slug>[bot]]... [--name <name>]
+                                              Connect a repository; prints its id. Takes a full key.
+                                              --trust runs that App's pushes as its own from the start
+  repos [ls] [--all]                          Connected repositories, with the Apps each trusts;
+                                              --all: disconnected ones too
+  repos trust <repoId | owner/name> <app-slug>[bot]...
+                                              Run that App's pushes as the repository's own code,
+                                              keeping the Apps it trusts already
+  repos untrust <repoId | owner/name> <app-slug>[bot]...
+                                              Stop trusting those Apps, keeping the rest
+  disconnect <repoId | owner/name>            Stop checking it; its checks still going are cancelled
+  ls [--repository <repoId>] [--branch <name>] [--commit <sha>] [--pr <number>]
+     [--state <state>]... [--limit 20]        Checks, newest first, with their jobs by state
+  get <checkId>                               One check and its jobs in plan order
+  logs <jobId>                                A job's output, its last 256 KiB, and its sandboxes
+  tests <repoId> [--quarantined]              Its test files: time, recent outcomes, quarantine
+  flakes [--repository <repoId>] [--all]      Flaky tests: each quarantined (or still gating), its
+                                              owner and 48-hour deadline; --all: ended ones too
+  flake <flakeId>                             One flaky test: its proof, owner, and recent runs
+  flake prove <flakeId>                       Its 100 proof runs again at main's next commit
+  flake hand <flakeId> <login | org/team>     Hand it to someone else
+  flake delete <flakeId> --reason <why>       Say why its test is deleted; it ends once main
+                                              no longer holds the file
+
+  A failed job's sandbox may be kept paused: \`runtime sandboxes wake <id>\`, then
+  \`runtime sandboxes shell <id>\` to look around where it failed.
+
+Examples
+  runtime ci connect acme/web --config .runtime/ci.yml
+  runtime ci repos trust acme/web acme-bot[bot]
+  runtime ci ls --commit $(git rev-parse HEAD)
+  runtime ci logs <jobId>
+`;
+const when = (ms) => (ms === null ? "-" : new Date(ms).toISOString());
+const took = (from, to) => from === null || to === null ? "-" : `${((to - from) / 1000).toFixed(1)}s`;
+const counted = (c) => Object.entries(c)
+    .map(([state, n]) => `${n} ${state}`)
+    .join(", ") || "-";
+/** Where a check's machines came from and how soon, in a line. */
+const machined = (m) => {
+    if (!m)
+        return null;
+    const from = [
+        m.reused && `${m.reused} its pull request's own`,
+        m.pooled && `${m.pooled} pooled`,
+        m.forked && `${m.forked} forked in ${m.forks}`,
+        m.created && `${m.created} created`,
+    ].filter(Boolean);
+    const s = (ms) => (ms === null ? "-" : `${(ms / 1000).toFixed(2)}s`);
+    return `machines: ${from.join(", ") || "none"}; first in ${s(m.firstMs)}, first test at ${s(m.firstTestMs)}${m.lineMs ? `, ${s(m.lineMs)} in line` : ""}${m.kept ? `; ${m.kept} kept for the next push` : ""}`;
+};
+const where = (c) => c.pullRequest !== null ? `#${c.pullRequest}` : (c.branch ?? c.event);
+const STATES = ["queued", "running", "passed", "failed", "cancelled"];
+const ownerOf = (f) => f.owner === null
+    ? "nobody found"
+    : `@${f.owner.login}${f.owner.pullRequest === null ? "" : ` (#${f.owner.pullRequest})`}`;
+export async function ciCommand(argv, out, client, kit) {
+    const { parse, flag, has, need, table, usage, unknown } = kit;
+    const [verb, ...rest] = argv;
+    const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
+    if (!verb || verb === "help" || verb === "--help") {
+        print(named(CI_HELP), { usage: named(CI_HELP) });
+        return 0;
+    }
+    const api = ci((await client()).transport);
+    const whole = (value, what) => {
+        if (value === undefined)
+            return undefined;
+        if (!/^[1-9][0-9]{0,8}$/.test(value))
+            throw usage(`${what} takes a whole number: ${value}`);
+        return Number(value);
+    };
+    const apps = (words) => {
+        if (!words.length)
+            throw usage(`Name an App by its login, such as acme-bot[bot].`);
+        for (const word of words)
+            if (!/^[A-Za-z0-9][A-Za-z0-9-]{0,38}\[bot\]$/.test(word))
+                throw usage(`${word} is not an App's login: name it <app-slug>[bot], as GitHub shows its pushes (quote it in your shell: '${word.replace(/\[bot\]$/, "")}[bot]').`);
+        return words;
+    };
+    const trusted = (r) => r.trustedApps?.join(", ") || "none";
+    const disconnect = async (idOrName) => {
+        const found = await api.repositories.find(idOrName);
+        const repo = await api.repositories.disconnect(found?.id ?? idOrName);
+        print(`${repo.repository} disconnected; its checks that ended stay.`, repo);
+        return 0;
+    };
+    switch (verb) {
+        case "connect": {
+            const args = parse(rest, [], ["branch", "config", "installation", "trust", "name"]);
+            const repository = need(args.positional[0], "the repository, such as acme/web");
+            const installation = whole(flag(args, "installation"), "--installation");
+            const trust = args.flags.get("trust") ?? [];
+            const input = {
+                repository,
+                ...(flag(args, "branch") ? { productionBranch: flag(args, "branch") } : {}),
+                ...(flag(args, "config") ? { configPath: flag(args, "config") } : {}),
+                ...(installation === undefined ? {} : { installation }),
+                ...(trust.length ? { trustedApps: apps(trust) } : {}),
+                ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
+            };
+            const repo = await api.repositories.connect(input);
+            if (!out.json)
+                out.error(`Connected ${repo.repository}: each push and pull request is checked as ${repo.configPath} says; ${repo.productionBranch} is its production branch; it trusts ${trusted(repo)}. Its checks: ${me} ci ls --repository ${repo.id}`);
+            print(repo.id, repo);
+            return 0;
+        }
+        case "repos":
+        case "repositories": {
+            const [action, ...more] = rest;
+            if (action === "trust" || action === "untrust") {
+                const [which, ...logins] = more;
+                const id = need(which, "the repository's id or owner/name");
+                const listed = apps(logins);
+                const repo = action === "trust"
+                    ? await api.repositories.trust(id, listed)
+                    : await api.repositories.untrust(id, listed);
+                print(`${repo.repository} trusts ${trusted(repo)}.`, repo);
+                return 0;
+            }
+            if (action === "connect")
+                return ciCommand(["connect", ...more], out, client, kit);
+            if (action === "disconnect" || action === "rm")
+                return disconnect(need(more[0], "the repository's id or owner/name"));
+            const listing = action === "ls" || action === "list" ? more : rest;
+            if (listing.length && !listing[0].startsWith("-"))
+                throw unknown("ci repos command", listing[0], [
+                    "ls",
+                    "connect",
+                    "trust",
+                    "untrust",
+                    "disconnect",
+                ]);
+            const args = parse(listing, ["all"], []);
+            const all = await (await api.repositories.list({
+                limit: 100,
+                ...(has(args, "all") ? {} : { state: ["connected"] }),
+            })).toArray(Infinity);
+            print(all.length
+                ? table([
+                    ["ID", "REPOSITORY", "BRANCH", "CONFIG", "TRUSTED APPS", "STATE"],
+                    ...all.map((r) => [
+                        r.id,
+                        r.repository,
+                        r.productionBranch,
+                        r.configPath,
+                        trusted(r),
+                        r.state,
+                    ]),
+                ])
+                : `No repositories this key lists. Connect one: ${me} ci connect acme/web`, all);
+            return 0;
+        }
+        case "disconnect":
+            return disconnect(need(rest[0], "the repository's id or owner/name"));
+        case "ls":
+        case "list": {
+            const args = parse(rest, [], ["repository", "branch", "commit", "pr", "state", "limit"]);
+            const commit = flag(args, "commit");
+            if (commit !== undefined && !/^([0-9a-f]{40}|[0-9a-f]{64})$/.test(commit))
+                throw usage(`--commit takes a full sha in lower case: ${me} ci ls --commit $(git rev-parse HEAD)`);
+            const states = args.flags.get("state");
+            for (const state of states ?? [])
+                if (!STATES.includes(state))
+                    throw unknown("state", state, STATES);
+            const pullRequest = whole(flag(args, "pr"), "--pr");
+            const limit = whole(flag(args, "limit"), "--limit") ?? 20;
+            const page = await api.checks.list({
+                limit: Math.min(limit, 100),
+                ...(flag(args, "repository") ? { repositoryId: flag(args, "repository") } : {}),
+                ...(flag(args, "branch") ? { branch: flag(args, "branch") } : {}),
+                ...(commit ? { commit } : {}),
+                ...(pullRequest === undefined ? {} : { pullRequest }),
+                ...(states ? { state: states } : {}),
+            });
+            const all = await page.toArray(limit);
+            print(all.length
+                ? table([
+                    ["ID", "STATE", "REPOSITORY", "WHERE", "COMMIT", "JOBS", "TOOK", "CREATED"],
+                    ...all.map((c) => [
+                        c.id,
+                        c.waiting ? "waiting" : c.state,
+                        c.repository,
+                        where(c),
+                        c.commit.slice(0, 12),
+                        counted(c.counts),
+                        took(c.startedAt, c.endedAt),
+                        when(c.createdAt),
+                    ]),
+                ])
+                : "No checks.", all);
+            return 0;
+        }
+        case "get": {
+            const check = await api.checks.get(need(rest[0], "a check's id"));
+            const job = (j) => [
+                j.id,
+                j.parts > 1 ? `${j.name} (${j.part}/${j.parts})` : j.name,
+                j.state,
+                j.ms === null ? "-" : `${(j.ms / 1000).toFixed(1)}s`,
+                j.exitCode === null ? "-" : String(j.exitCode),
+                j.sandboxIds.join(",") || "-",
+            ];
+            print([
+                `${check.repository} ${check.commit.slice(0, 12)} ${where(check)}: ${check.waiting ? "waiting for a writer to re-run it on GitHub" : check.state}${check.reason ? ` (${check.reason})` : ""}`,
+                ...(check.machines ? [machined(check.machines)] : []),
+                check.jobs.length
+                    ? table([["JOB", "NAME", "STATE", "TOOK", "EXIT", "SANDBOXES"], ...check.jobs.map(job)])
+                    : "No jobs yet.",
+            ].join("\n"), check);
+            return 0;
+        }
+        case "logs":
+        case "job": {
+            const job = await api.jobs.get(need(rest[0], "a job's id (runtime ci get <checkId>)"));
+            if (out.json) {
+                out.write(JSON.stringify(job));
+                return 0;
+            }
+            out.write(job.log.endsWith("\n") || !job.log ? job.log : `${job.log}\n`);
+            if (job.review)
+                out.write(reviewed(job.review));
+            out.error(`[${job.name}${job.parts > 1 ? ` ${job.part}/${job.parts}` : ""} ${job.state}${job.exitCode === null ? "" : `, exit code ${job.exitCode}`}${job.reason ? `, ${job.reason}` : ""}]`);
+            if (job.state === "failed" && job.sandboxIds.length)
+                out.error(`Its sandbox may be kept paused, to look into: ${me} sandboxes wake ${job.sandboxIds[0]}, then ${me} sandboxes shell ${job.sandboxIds[0]}`);
+            return 0;
+        }
+        case "flakes": {
+            const args = parse(rest, ["all"], ["repository"]);
+            const repositoryId = flag(args, "repository");
+            const all = await (await api.flakes.list({
+                limit: 100,
+                ...(repositoryId ? { repositoryId } : {}),
+                ...(has(args, "all") ? {} : { state: ["quarantined", "gating"] }),
+            })).toArray(Infinity);
+            print(all.length
+                ? table([
+                    ["ID", "FILE", "STATE", "OWNER", "DUE"],
+                    ...all.map((f) => [
+                        f.id,
+                        f.file,
+                        f.state,
+                        ownerOf(f),
+                        f.endedAt !== null ? "-" : `${when(f.dueAt)}${f.overdue ? " (overdue)" : ""}`,
+                    ]),
+                ])
+                : "No flaky tests.", all);
+            return 0;
+        }
+        case "flake": {
+            const [sub, ...more] = rest;
+            if (sub === "prove" || sub === "hand" || sub === "delete") {
+                const args = parse(more, [], ["reason"]);
+                const id = need(args.positional[0], "a flake's id (runtime ci flakes)");
+                const change = sub === "prove"
+                    ? { prove: true }
+                    : sub === "hand"
+                        ? { owner: need(args.positional[1], "a GitHub login, or org/team") }
+                        : { deleteReason: need(flag(args, "reason"), "--reason <why its test is deleted>") };
+                const f = await api.flakes.update(id, change);
+                print(sub === "prove"
+                    ? `${f.file}: its 100 proof runs come at main's next commit.\n`
+                    : sub === "hand"
+                        ? `${f.file}: handed to ${ownerOf(f)}.\n`
+                        : `${f.file}: it ends once main no longer holds the file.\n`, f);
+                return 0;
+            }
+            const f = await api.flakes.get(need(sub, "a flake's id (runtime ci flakes)"));
+            const runs = f.runs
+                .slice(0, 20)
+                .map((r) => `${r.passed ? "pass" : "FAIL"} ${r.attempt}`)
+                .join(", ");
+            print([
+                `${f.file}: ${f.state}${f.gates ? ` (still gates: ${f.gates.words})` : ""}`,
+                `  owner   ${ownerOf(f)}, due ${when(f.dueAt)}${f.overdue ? " (overdue)" : ""}`,
+                `  proof   passed and failed under key ${f.proof.key.slice(0, 12)} at ${f.proof.commit.slice(0, 9)}`,
+                `  runs    ${runs || "-"}`,
+                ...f.failures
+                    .slice(0, 5)
+                    .map((x) => `  failed  ${x.jobId} at ${x.commit.slice(0, 9)}: ${x.message ?? ""} (${me} ci logs ${x.jobId})`),
+                ...(f.deleteReason ? [`  delete  ${f.deleteReason}`] : []),
+                "",
+            ].join("\n"), f);
+            return 0;
+        }
+        case "tests": {
+            const args = parse(rest, ["quarantined"], []);
+            const repositoryId = need(args.positional[0], "a repository's id (runtime ci repos)");
+            const all = await (await api.tests.list(repositoryId, {
+                limit: 100,
+                ...(has(args, "quarantined") ? { quarantined: true } : {}),
+            })).toArray(Infinity);
+            print(all.length
+                ? table([
+                    ["FILE", "TOOK", "RECENT", "QUARANTINED"],
+                    ...all.map((t) => [
+                        t.file,
+                        `${(t.ms / 1000).toFixed(1)}s`,
+                        t.runs
+                            .slice(-5)
+                            .map((r) => r.outcome)
+                            .join(" "),
+                        t.quarantinedSince === null ? "-" : when(t.quarantinedSince),
+                    ]),
+                ])
+                : "No test files yet.", all);
+            return 0;
+        }
+    }
+    throw unknown("ci command", verb, [
+        "connect",
+        "repos",
+        "disconnect",
+        "ls",
+        "get",
+        "logs",
+        "tests",
+        "flakes",
+        "flake",
+    ]);
+}
+/** A review's verdict in words: each finding with its place and fix, then
+ * the notes, then who reviewed. */
+function reviewed(r) {
+    const at = (f) => (f.line > 0 ? `${f.file}:${f.line}` : f.file);
+    return [
+        `\n${r.verdict === "pass" ? "Passed review" : `Blocked: ${r.findings.length} finding(s)`}. ${r.summary}`,
+        ...r.findings.map((f) => `  ${f.kind} at ${at(f)}: ${f.what}\n    Fix: ${f.fix}`),
+        ...r.notes.map((n) => `  note at ${at(n)}: ${n.what}`),
+        `Reviewed by agent ${r.agent} (${r.model}) on ${r.account}${r.cut ? ", diff cut short" : ""}: session ${r.session}`,
+        "",
+    ].join("\n");
+}

package/dist/cli.d.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { type Sandbox } from "./sandbox.js";
 import { RuntimeError } from "./errors.js";
 import type { OutOfMemory, Usage } from "./types.js";
 import type { SwitchProvider } from "./products/switching.js";
@@ -31,6 +32,9 @@ declare const kit: {
     table: (rows: string[][]) => string;
     usage: (message: string) => RuntimeError;
     unknown: (what: string, word: string, choices: readonly string[]) => RuntimeError;
+    /** `sandboxes exec`'s run and output, for any machine that execs. */
+    execute: (machine: Pick<Sandbox, "id" | "exec">, command: string[], args: Args, out: Out, env: NodeJS.ProcessEnv) => Promise<number>;
+    copyFile: (from: string, to: string, use: (id: string) => Promise<Pick<Sandbox, "files">>, side: string) => Promise<void>;
 };
 export type CliKit = typeof kit;
 export declare function run(argv: string[], env?: NodeJS.ProcessEnv, out?: Out): Promise<number>;
@@ -46,8 +50,9 @@ export declare function usageCsv(u: Usage): string;
  * command: the API's message and hint, on standard error. A bare exit -9 (or
  * 137) said nothing of memory until 9 October 2026. */
 export declare function outOfMemoryLines(memory: OutOfMemory | undefined): string | undefined;
-/** How to move a rival's code across, when one import does it. */
-export declare function dropInLines(provider: SwitchProvider | undefined): string[];
+/** How to move a rival's code across, when one import (or, for Fly's
+ * Machines, one address) does it. `from` is the name the caller gave. */
+export declare function dropInLines(provider: SwitchProvider | undefined, from?: string): string[];
 /** A secret's value, from standard input only, so it never sits in shell
  * history or a process list. Piped: everything, less one trailing newline.
  * A terminal: one line, not shown. */
@@ -62,16 +67,22 @@ export declare function cleanSecret(raw: string): string;
  * (ARCHITECTURE.md section 10, "Per-path rules on an egress secret") and says
  * which one it refused. */
 export declare function parseSecretRules(values: string[]): SecretRule[];
-/** `--only-label role=hub,tier=x --only-sandbox <id>`: a sandbox whose labels
- * hold every pair of any one --only-label gets the secret, and so does each
- * --only-sandbox. `--all-sandboxes`: every sandbox again. Nothing: undefined,
- * so a replacement keeps the scope it has. */
-export declare function parseSecretScope(labels: string[] | undefined, sandboxes: string[] | undefined, all: boolean): SecretScope | undefined;
+/** `--only-label role=hub,tier=x --only-sandbox <id> --only-app <id>`: a
+ * sandbox whose labels hold every pair of any one --only-label gets the
+ * secret, and so does each --only-sandbox and every copy of each --only-app.
+ * `--all-sandboxes`: every sandbox again. Nothing: undefined, so a
+ * replacement keeps the scope it has. */
+export declare function parseSecretScope(labels: string[] | undefined, sandboxes: string[] | undefined, all: boolean, apps?: string[]): SecretScope | undefined;
 /** Who gets a secret, in a few words. */
 export declare const scopeText: (only: SecretScope | undefined) => string;
 export declare function secretsCommand(argv: string[], env: NodeJS.ProcessEnv, out: Out, 
 /** Tests give the value here; the CLI reads standard input. */
 read?: () => Promise<string>): Promise<number>;
+/** A booking's time on the command line: an ISO time, `now`, or HH:MM on this
+ * machine's clock. HH:MM is the next such time at or after `after` (the
+ * window's start for `--to`, so an end before the start is the next day, and
+ * `now` for `--from`: today, or tomorrow once it has passed). */
+export declare function bookingTime(name: string, value: string, now: number, after?: number): Date;
 export declare function imageCommand(argv: string[], env: NodeJS.ProcessEnv, out: Out, 
 /** Tests give the registry secret here; the CLI reads standard input. */
 read?: () => Promise<string>): Promise<number>;