@miroshnik/elves 0.0.0 → 2026.1018.1

package/skills/spec/scripts/spec-run.ts

@@ -0,0 +1,235 @@
+#!/usr/bin/env bun
+/**
+ * spec-run — the green run that checked the merge commit's tree, for publishing the spec on a PR merge (without CI on
+ * main): the run id goes to stdout, `gh run download` downloads the artifact `docs-spec-<tree hash>` from it. A PR run
+ * checks the merge-ref and names the artifact by its tree; the merge commit has the same tree only if nothing was merged
+ * into main between the run's start and the merge — then main is checked as a whole. A PR that fell behind was merged —
+ * there is no such artifact, and publishing is skipped: from its head's run it would roll the spec branch back (the pages
+ * of a PR merged earlier would vanish from it).
+ *
+ * Among this repository's runs with an unexpired artifact of the tree: a green one exists — it (the newest); one is
+ * running — polling until its outcome, not finished by the ceiling — an error; otherwise (no artifact, expired, from a
+ * fork, the run isn't green) — skip: code 0, stdout empty, the reason in a stderr line.
+ *
+ * `--artifact <name>` — for spec-shard: the newest green run of this repository with an unexpired artifact of that name
+ * (the `spec` job's reports — durations of the last green run). Without waiting: a run in progress isn't green yet, the
+ * previous green one does. In Actions (`GITHUB_RUN_ID`) — green by the start of the current run's first attempt: every
+ * shard of the run gets one answer whenever it reaches the step, a re-run of failed shards too. None — code 0, stdout
+ * empty, the reason in stderr: the shards are split by count.
+ *
+ *   bun spec-run.ts --tree <hash> [--timeout 1800] [--interval 15]
+ *   bun spec-run.ts --artifact <name>
+ *
+ * Codes: 0 — found or publishing skipped, 1 — the run didn't finish by the ceiling, 2 — a call error (arguments, gh).
+ * Runs under Bun, no dependencies; needs `gh` with a token (in Actions — `GH_TOKEN`, `actions: read`).
+ */
+
+import { execFileSync } from "node:child_process";
+import { parseArgs } from "node:util";
+
+const USAGE = "spec-run --tree <hash> [--timeout 1800] [--interval 15]\nspec-run --artifact <name>";
+/** `--help`, `-h` (tests/standards/cli-help): the synopsis, what it does and examples; `elves` prints it under its name. */
+export const HELP = `${USAGE}
+
+The green run that checked the merge commit's tree: its id to stdout, for gh run download of docs-spec-<tree hash>; no
+such run — skip: code 0, stdout empty, the reason in stderr. Code 1 — the run didn't finish by the ceiling, 2 — a call
+error. --artifact — the newest green run with an unexpired artifact of that name, without waiting (for spec-shard); in
+Actions (GITHUB_RUN_ID) — green by the start of this run's first attempt: one answer for all of its shards.
+
+Examples:
+  spec-run --tree "$(git rev-parse 'HEAD^{tree}')"
+  spec-run --artifact spec-reports`;
+
+interface Artifact {
+  name: string;
+  expired: boolean;
+  created_at: string;
+  workflow_run: { id: number; repository_id: number; head_repository_id: number } | null;
+}
+
+/** A run (`runs/<id>` — its latest attempt) or one attempt of it (`runs/<id>/attempts/<k>`). */
+interface Run {
+  id: number;
+  status: string;
+  conclusion: string | null;
+  html_url: string;
+  run_attempt?: number;
+  run_started_at?: string;
+  /** a completed attempt isn't updated any more: its finish */
+  updated_at?: string;
+}
+
+class Fail extends Error {
+  code: number;
+  constructor(message: string, code: number) {
+    super(message);
+    this.code = code;
+  }
+}
+
+function api<T>(endpoint: string): T {
+  try {
+    return JSON.parse(execFileSync("gh", ["api", endpoint], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })) as T;
+  } catch (e) {
+    const stderr = (e as { stderr?: string }).stderr?.trim();
+    throw new Fail(`gh api ${endpoint}: ${stderr || (e as Error).message.split("\n")[0]}`, 2);
+  }
+}
+
+const time = (iso: string | undefined): number => Date.parse(iso ?? "");
+
+/**
+ * Ids of the runs with a live artifact, newest first. Only this repository's runs count: a PR run from a fork can upload
+ * an artifact with any name too. `before` — only artifacts uploaded by then: a run finished by a moment uploaded its
+ * artifact before it. A page of 100: newer artifacts keep coming while a run lasts, an older source stays on it.
+ */
+function runIds(artifact: string, before?: number): number[] {
+  const { artifacts } = api<{ artifacts: Artifact[] }>(`repos/{owner}/{repo}/actions/artifacts?name=${encodeURIComponent(artifact)}&per_page=100`);
+  const own = artifacts.filter(
+    (a) => !a.expired && a.workflow_run && a.workflow_run.head_repository_id === a.workflow_run.repository_id && !(time(a.created_at) > (before ?? Infinity)),
+  );
+  // a rerun uploads the artifact again under the same run id
+  return [...new Set(own.map((a) => a.workflow_run!.id))];
+}
+
+/** The outcome — a separate request for the run: the artifact is uploaded mid-run and doesn't prove a green outcome. */
+const runOf = (id: number): Run => api<Run>(`repos/{owner}/{repo}/actions/runs/${id}`);
+
+/** The moment the shards' source is fixed at (`--artifact`) and the run it belongs to. */
+interface Anchor {
+  run: string;
+  at: number;
+  iso: string;
+}
+
+/**
+ * The start of the current run's first attempt (`GITHUB_RUN_ID` in Actions). The newest green run "now" depends on when
+ * a shard reaches the step: a run that finished between two shards' requests gave them different layouts, and files ran
+ * in two shards or in none. By a fixed moment every shard gets one answer. The first attempt, not the current one: a
+ * re-run of failed jobs keeps the passed shards of the first attempt with their layout. Outside Actions — none.
+ */
+function anchor(): Anchor | null {
+  const run = process.env.GITHUB_RUN_ID;
+  if (!run) return null;
+  const first = api<Run>(`repos/{owner}/{repo}/actions/runs/${run}/attempts/1`);
+  const at = time(first.run_started_at);
+  if (Number.isNaN(at)) throw new Fail(`run ${run}: attempt 1 has no run_started_at`, 2);
+  return { run, at, iso: first.run_started_at! };
+}
+
+/**
+ * The run as it was at `at`: its latest attempt started by then. A re-run of the run started later doesn't change the
+ * answer — the previous attempts are asked; null — the run started later.
+ */
+function asOf(id: number, at: number): Run | null {
+  let run = runOf(id);
+  for (let k = (run.run_attempt ?? 1) - 1; time(run.run_started_at) > at; k--) {
+    if (k < 1) return null;
+    run = api<Run>(`repos/{owner}/{repo}/actions/runs/${id}/attempts/${k}`);
+  }
+  return run;
+}
+
+/** Green by the moment `at` (none — now): succeeded and finished by then, a later finish counts as unfinished. */
+const greenBy = (run: Run, at?: number): boolean =>
+  run.status === "completed" && run.conclusion === "success" && !(at !== undefined && time(run.updated_at) > at);
+
+/** The run's state for the "no green run" line: its outcome, or status, and whether it finished after the moment. */
+function stateOf(run: Run, at?: number): string {
+  const late = at !== undefined && run.status === "completed" && time(run.updated_at) > at;
+  return `${run.id} ${run.conclusion ?? run.status}${late ? " (finished later)" : ""} ${run.html_url}`;
+}
+
+/**
+ * The newest green run with the artifact (`--artifact`): runs are asked newest first, up to the first green one. In
+ * Actions — as of the start of the current run (`anchor`).
+ */
+function latest(artifact: string): number {
+  const by = anchor();
+  const at = by?.at;
+  const when = by ? ` before run ${by.run} started (${by.iso})` : "";
+  const asked: string[] = [];
+  for (const id of runIds(artifact, at)) {
+    const run = at === undefined ? runOf(id) : asOf(id, at);
+    if (!run) {
+      asked.push(`${id} started later`);
+      continue;
+    }
+    if (greenBy(run, at)) {
+      console.error(`spec-run: artifact ${artifact}: run ${run.id} succeeded${when} — ${run.html_url}`);
+      process.stdout.write(`${run.id}\n`);
+      return 0;
+    }
+    asked.push(stateOf(run, at));
+  }
+  const why = asked.length ? asked.join(", ") : `no artifact ${artifact}`;
+  console.error(`spec-run: artifact ${artifact}: no green run${when} — ${why}`);
+  return 0;
+}
+
+const seconds = (name: string, value: string): number => {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < 0) throw new Fail(`--${name}: a number of seconds is needed, not «${value}»\n${USAGE}`, 2);
+  return n;
+};
+
+export async function main(argv: string[]): Promise<number> {
+  try {
+    let opts;
+    try {
+      opts = parseArgs({
+        args: argv,
+        options: {
+          tree: { type: "string" },
+          artifact: { type: "string" },
+          timeout: { type: "string", default: "1800" },
+          interval: { type: "string", default: "15" },
+          help: { type: "boolean", short: "h", default: false },
+        },
+      });
+    } catch (e) {
+      throw new Fail(`${(e as Error).message}\n${USAGE}`, 2);
+    }
+    const v = opts.values;
+    if (v.help) return console.log(HELP), 0;
+    if (v.tree && v.artifact) throw new Fail(`--tree and --artifact don't go together\n${USAGE}`, 2);
+    if (v.artifact) return latest(v.artifact);
+    if (!v.tree) throw new Fail(`--tree <hash> or --artifact <name> is required\n${USAGE}`, 2);
+    if (!/^[0-9a-f]{40,64}$/.test(v.tree)) throw new Fail(`--tree: a full tree hash is needed (git rev-parse 'HEAD^{tree}'), not «${v.tree}»\n${USAGE}`, 2);
+    const timeout = seconds("timeout", v.timeout);
+    const interval = seconds("interval", v.interval);
+    const artifact = `docs-spec-${v.tree}`;
+    const at = `main tree ${v.tree.slice(0, 12)}`;
+    const deadline = Date.now() + timeout * 1000;
+    let said = "";
+    for (;;) {
+      const all = runIds(artifact).map(runOf);
+      // the listing is newest first: of several green runs the latest is taken
+      const ok = all.find((r) => r.status === "completed" && r.conclusion === "success");
+      if (ok) {
+        console.error(`spec-run: ${at}: run ${ok.id} succeeded — ${ok.html_url}`);
+        process.stdout.write(`${ok.id}\n`);
+        return 0;
+      }
+      const going = all.filter((r) => r.status !== "completed");
+      if (!going.length) {
+        // not an error: a PR that fell behind was merged — no run checked such a main, the spec branch waits for the next merge
+        const why = all.length ? all.map((r) => `${r.id} ${r.conclusion} ${r.html_url}`).join(", ") : `no artifact ${artifact}`;
+        console.error(`spec-run: ${at} not fully checked — publishing skipped: ${why}`);
+        return 0;
+      }
+      if (Date.now() >= deadline) throw new Fail(`${at}: run ${going.map((r) => r.id).join(", ")} didn't finish in ${timeout} s`, 1);
+      const now = `${at}: run ${going.map((r) => `${r.id} ${r.status}`).join(", ")} — waiting`;
+      // only a change of state goes to the log, not a line on every poll
+      if (now !== said) console.error(`spec-run: ${(said = now)}`);
+      await new Promise((resolve) => setTimeout(resolve, Math.min(interval * 1000, Math.max(0, deadline - Date.now()))));
+    }
+  } catch (e) {
+    console.error(`spec-run: ${(e as Error).message}`);
+    return e instanceof Fail ? e.code : 2;
+  }
+}
+
+if (import.meta.main) {
+  process.exitCode = await main(process.argv.slice(2));
+}

package/skills/spec/scripts/spec-shard.ts

@@ -0,0 +1,267 @@
+#!/usr/bin/env bun
+/**
+ * spec-shard — a CI shard's test files by the durations of the last green run, not by the count of tests. A runner's
+ * `--shard` doesn't look at time: Playwright cuts the suite in a row by the count of tests in path order, Vitest —
+ * files by the hash of the path; the heavy tests of one folder go to one shard, the PR waits for it, the others stand
+ * idle. The script lays out the files greedily — the longest into the lightest shard — and prints the shard's filters
+ * for the runner, one per line; CI passes them to the runner instead of `--shard`.
+ *
+ *   bun spec-shard.ts --shard <k>/<n> --runner vitest|playwright|bun --list <file|-> [--report <file>]… [--root DIR]
+ *
+ * - `--list` — the run's test files: `vitest list --filesOnly --json=<file>`, `playwright test --list --reporter=json`
+ *   or one path per line (bun test lists nothing without a run — `git ls-files`); absolute paths — relative to the root
+ *   (`--root`, default — the current directory: the runner reads the filters from it).
+ * - `--report` — the last green run's reports, the same formats as for spec-doc (Vitest/Jest JSON, Playwright JSON,
+ *   JUnit from `bun test`); a report's path is matched to the listed file it ends with — a report from another machine
+ *   works. A missing report file isn't an error: the reports are an artifact of the previous run, and it may be gone.
+ *   No durations — the files are split equally by count; a file without a measurement gets the mean.
+ * - A filter is what the runner understands: Vitest — the path (it takes a file whose path contains the filter),
+ *   Playwright — an escaped regular expression anchored at the end of the path, bun test — the path with `./` (such a
+ *   filter is the file's path, not a substring). A filter that also takes another file (a path inside another path) —
+ *   both go into one shard: the shard's filters take exactly its files.
+ * - The same inputs give the same shards: files and ties — by path, without time or randomness.
+ *
+ * Codes: 0 — the shard is printed (an empty one too: more shards than files — stdout is empty, CI doesn't start the
+ * runner: without filters it would run everything), 2 — a call error (arguments, the list or a report unreadable).
+ * Runs under Bun, no dependencies.
+ */
+
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+
+import { loadDurations } from "./speclib.ts";
+
+const posix = path.posix;
+
+const USAGE = "spec-shard --shard <k>/<n> --runner vitest|playwright|bun --list <file|-> [--report <file>]… [--root DIR]";
+/** `--help`, `-h` (tests/standards/cli-help): the synopsis, what it does and examples; `elves` prints it under its name. */
+export const HELP = `${USAGE}
+
+A CI shard's test files by the durations of the last green run, not by the count of tests: greedily — the longest file
+into the lightest shard; the shard's filters for the runner go to stdout, one per line (an empty shard — nothing).
+--list — vitest list --filesOnly --json=<file>, playwright test --list --reporter=json or one path per line (bun test —
+git ls-files); --report — the last green run's reports (Vitest/Jest JSON, Playwright JSON, JUnit from bun test), a
+missing one is skipped; no durations — the files are split equally by count, a file without a measurement gets the
+mean. A filter: vitest — the path, playwright — a regular expression, bun — ./<path>. Code 2 — a call error.
+
+Examples:
+  spec-shard --shard 2/3 --runner vitest --list .spec-files.json --report .spec-last/.spec-report.json
+  spec-shard --shard 1/2 --runner playwright --list .spec-files.json --report .spec-last/.spec-playwright.json
+  spec-shard --shard 1/3 --runner bun --list .spec-files.txt --report .spec-last/.spec-report-1.xml --report .spec-last/.spec-report-2.xml`;
+
+const RUNNERS = ["vitest", "playwright", "bun"] as const;
+type Runner = (typeof RUNNERS)[number];
+
+class Fail extends Error {
+  code: number;
+  constructor(message: string, code: number) {
+    super(message);
+    this.code = code;
+  }
+}
+
+type Json = Record<string, unknown>;
+const str = (v: unknown): string => (typeof v === "string" ? v : "");
+
+/** The run's test files from the list: paths relative to the root, without repeats, by path. */
+function listed(file: string, roots: string[]): string[] {
+  let text: string;
+  try {
+    text = readFileSync(file === "-" ? 0 : file, "utf8");
+  } catch (e) {
+    throw new Fail(`--list ${file}: ${(e as Error).message}`, 2);
+  }
+  let data: unknown;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    data = undefined; // not JSON — one path per line
+  }
+  let paths: string[];
+  if (Array.isArray(data)) {
+    // vitest list --json: [{ file }], with --filesOnly too
+    paths = data.map((x) => (typeof x === "string" ? x : str((x as Json | null)?.file)));
+  } else if (data && typeof data === "object" && "suites" in data && "config" in data) {
+    // playwright test --list --reporter=json: a file's suite — the path relative to config.rootDir
+    const d = data as Json;
+    const rootDir = str((d.config as Json | null)?.rootDir).replace(/\\/g, "/");
+    paths = (Array.isArray(d.suites) ? (d.suites as Json[]) : []).map((s) => {
+      const f = (str(s.file) || str(s.title)).replace(/\\/g, "/");
+      return rootDir ? posix.join(rootDir, f) : f;
+    });
+  } else if (data !== undefined) {
+    throw new Fail(`--list ${file}: unknown format (expected vitest list --json, playwright test --list --reporter=json or one path per line)`, 2);
+  } else {
+    paths = text.split("\n");
+  }
+  const out = new Set<string>();
+  for (const raw of paths) {
+    const p = raw.trim().replace(/\\/g, "/");
+    if (p) out.add(relative(p, roots));
+  }
+  return [...out].sort();
+}
+
+/** A path from the list — relative to the root; the root is given as is and as the real path (a symlink in it). */
+function relative(p: string, roots: string[]): string {
+  if (!posix.isAbsolute(p)) return posix.normalize(p);
+  for (const root of roots) {
+    const rel = posix.relative(root, p);
+    if (rel && rel !== ".." && !rel.startsWith("../")) return rel;
+  }
+  throw new Fail(`${p}: outside the root ${roots[0]} — run from the repository root or pass --root`, 2);
+}
+
+/**
+ * The listed files' durations, ms. A report's path goes to the listed file it ends with (the longest such); several
+ * paths of one report end with one listed file — the shortest is that file, the others lie deeper, in a directory the
+ * list doesn't have. A file in several reports — the longest duration: the same report passed twice doesn't double it.
+ */
+function durations(files: string[], reports: string[]): Map<string, number> {
+  const byName = new Map<string, string[]>();
+  for (const f of files) byName.set(posix.basename(f), [...(byName.get(posix.basename(f)) ?? []), f]);
+  const out = new Map<string, number>();
+  for (const report of reports) {
+    if (!existsSync(report)) {
+      console.error(`spec-shard: no report ${report} — no durations from it`);
+      continue;
+    }
+    let found: Map<string, number>;
+    try {
+      found = loadDurations(report);
+    } catch (e) {
+      throw new Fail(`--report ${(e as Error).message}`, 2);
+    }
+    const mine = new Map<string, { length: number; ms: number }>();
+    for (const [p, ms] of found) {
+      const f = (byName.get(posix.basename(p)) ?? []).filter((l) => p === l || p.endsWith("/" + l)).sort((a, b) => b.length - a.length)[0];
+      if (!f) continue;
+      const seen = mine.get(f);
+      if (!seen || p.length < seen.length) mine.set(f, { length: p.length, ms });
+    }
+    for (const [f, { ms }] of mine) out.set(f, Math.max(out.get(f) ?? 0, ms));
+  }
+  return out;
+}
+
+/**
+ * Does the filter of file `a` also take file `b` — by the runner's matching of a filter against a path.
+ *
+ * - Vitest (`filterFiles` in `vitest/node`) takes a file whose path relative to its project's root contains the filter
+ *   or the filter's path relative to that root, case-insensitively; the project root isn't known here — any directory
+ *   common to both paths is tried.
+ * - Playwright tests the regular expression against the absolute path: `(^|/)<a>$` takes a file whose path ends with
+ *   `/<a>`.
+ * - bun test takes a filter starting with `./` as the file's path — only that file; without `./` it would take a file
+ *   whose path from the current directory contains the filter, case-sensitively.
+ */
+function takes(runner: Runner, a: string, b: string, root: string): boolean {
+  if (runner === "bun") return false;
+  if (runner === "playwright") return `${root}/${b}`.endsWith(`/${a}`);
+  const [la, lb] = [a.toLowerCase(), b.toLowerCase()];
+  if (!lb.includes(posix.basename(la))) return false;
+  for (let i = 0; ; ) {
+    if (lb.slice(i).includes(la.slice(i))) return true;
+    const j = la.indexOf("/", i);
+    if (j < 0 || lb.slice(0, j + 1) !== la.slice(0, j + 1)) return false;
+    i = j + 1;
+  }
+}
+
+const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+
+/** The runner's filter of a file: it takes the file and at most files of its group (`groupsOf`). */
+function filterOf(runner: Runner, file: string): string {
+  if (runner === "bun") return `./${file}`;
+  return runner === "playwright" ? `/(^|\\/)${escapeRe(file)}$/` : file;
+}
+
+/** Files whose filters take one another — groups (a union of the "takes" relation), each by path. */
+function groupsOf(runner: Runner, files: string[], root: string): string[][] {
+  const parent = files.map((_, i) => i);
+  const find = (i: number): number => (parent[i] === i ? i : (parent[i] = find(parent[i]!)));
+  for (let i = 0; i < files.length; i++)
+    for (let j = 0; j < files.length; j++) if (i !== j && takes(runner, files[i]!, files[j]!, root)) parent[find(j)] = find(i);
+  const groups = new Map<number, string[]>();
+  files.forEach((f, i) => groups.set(find(i), [...(groups.get(find(i)) ?? []), f]));
+  return [...groups.values()];
+}
+
+/**
+ * Greedy layout: groups from the heaviest into the lightest shard (ties — the first). The sort is stable: groups of one
+ * weight stay in path order — the list is sorted.
+ */
+function layout(groups: { files: string[]; weight: number }[], n: number): { files: string[]; load: number }[] {
+  const shards = Array.from({ length: n }, () => ({ files: [] as string[], load: 0 }));
+  const order = [...groups].sort((x, y) => y.weight - x.weight);
+  for (const g of order) {
+    const lightest = shards.reduce((best, s) => (s.load < best.load ? s : best));
+    lightest.files.push(...g.files);
+    lightest.load += g.weight;
+  }
+  return shards;
+}
+
+const sec = (ms: number): string => `${Math.round(ms / 1000)} s`;
+
+export function main(argv: string[]): number {
+  try {
+    let opts;
+    try {
+      opts = parseArgs({
+        args: argv,
+        options: {
+          shard: { type: "string" },
+          runner: { type: "string" },
+          list: { type: "string" },
+          report: { type: "string", multiple: true, default: [] },
+          root: { type: "string" },
+          help: { type: "boolean", short: "h", default: false },
+        },
+      });
+    } catch (e) {
+      throw new Fail(`${(e as Error).message}\n${USAGE}`, 2);
+    }
+    const v = opts.values;
+    if (v.help) return console.log(HELP), 0;
+    const m = /^(\d+)\/(\d+)$/.exec(v.shard ?? "");
+    const [k, n] = m ? [Number(m[1]), Number(m[2])] : [0, 0];
+    if (!m || k < 1 || k > n) throw new Fail(`--shard: <k>/<n> with 1 ≤ k ≤ n is needed, not «${v.shard ?? ""}»\n${USAGE}`, 2);
+    if (!RUNNERS.includes(v.runner as Runner)) throw new Fail(`--runner: ${RUNNERS.join(" or ")}, not «${v.runner ?? ""}»\n${USAGE}`, 2);
+    const runner = v.runner as Runner;
+    if (!v.list) throw new Fail(`--list <file|-> is required\n${USAGE}`, 2);
+    const root = path.resolve(v.root ?? process.cwd()).replace(/\\/g, "/");
+    if (!existsSync(root)) throw new Fail(`--root ${root}: no such directory`, 2);
+    const real = realpathSync(root).replace(/\\/g, "/");
+
+    const files = listed(v.list, [root, real]);
+    const measured = durations(files, v.report);
+    const known = [...measured.values()];
+    // no durations at all — every file weighs the same: the split is by count
+    const mean = known.length ? known.reduce((a, b) => a + b, 0) / known.length : 1;
+    const weight = (f: string): number => measured.get(f) ?? mean;
+    const groups = groupsOf(runner, files, real).map((g) => ({ files: g, weight: g.reduce((s, f) => s + weight(f), 0) }));
+    for (const g of groups)
+      if (g.files.length > 1) console.error(`spec-shard: one shard for ${g.files.join(", ")} — the filter of one also takes another`);
+    const shards = layout(groups, n);
+    const mine = shards[k - 1]!;
+    const total = shards.reduce((s, x) => s + x.load, 0);
+    const count = `shard ${k}/${n} — ${mine.files.length} of ${files.length} files`;
+    if (!known.length) console.error(`spec-shard: no durations of the last green run — the files are split equally by count; ${count}`);
+    else {
+      const unknown = files.filter((f) => !measured.has(f)).length;
+      console.error(`spec-shard: ${count}, ${sec(mine.load)} of ${sec(total)} by the last green run${unknown ? `; ${unknown} without a measurement — the mean, ${sec(mean)}` : ""}`);
+    }
+    const out = [...mine.files].sort().map((f) => filterOf(runner, f));
+    if (out.length) process.stdout.write(out.join("\n") + "\n");
+    return 0;
+  } catch (e) {
+    console.error(`spec-shard: ${(e as Error).message}`);
+    return e instanceof Fail ? e.code : 2;
+  }
+}
+
+if (import.meta.main) {
+  process.exitCode = main(process.argv.slice(2));
+}