graftfork 0.2.0 → 0.3.0

package/README.md

@@ -17,8 +17,24 @@ graft why                         # why the copy stayed, and what to do next
 graft pull                        # fetch the latest move as graft/<release>; your branch is untouched
 graft upstream "fix the parser"   # Graft builds that one change alone on your release and runs your tests;
                                   # this fetches graft/upstream/<change>. Nothing is pushed: you open the PR
+graft upstream-status <build>     # an upstream build's status, tests and links
 graft upstream-pr <build> <url>   # the pull request you opened; Graft tells you when it's merged
+graft upgrade <dependency>        # upgrade one dependency (npm or Python), delivered only if the tests pass
+graft upgrades                    # your upgrades and what their tests said
+graft check <base> <head> --wait  # check a change against the project's own tests: exit 0 pass, 1 fail, 2 couldn't run
+graft checks                      # your recent change checks
+graft verify-record <file>        # check a signed run record or agent change record; no token needed
+graft agent-record <org>          # an organization's signed agent change record, as JSON
+graft regen connect <repo> ...    # connect a spec (a duramen record); Graft rebuilds its implementation blind
+graft regen run <spec>            # rebuild it now
+graft regen status [id]           # your specs, a spec's rebuilds, or one rebuild and how to take it
+graft regen report <spec>         # the spec's grade and why, before anything is spent
 ```
 
-Also `graft whoami`, `graft status` and `graft usage`; `--json` prints the API's answers as they are. API docs:
+Also `graft whoami`, `graft status` and `graft usage`; `--json` prints the API's answers as they are, and
+`graft --help` lists every command with its options.
+
+Which version has what: 0.1.0 had copies, connect, sync, status, why, pull, usage, whoami and verify-record; 0.1.1
+added agent-record; 0.2.0 added check(s), upgrade(s) and upstream, upstream-status and upstream-pr; 0.3.0 adds
+regen connect, run, status and report. API docs:
 https://graftfork.com/docs/api. Support by email: support@graftfork.com. Apache-2.0.

package/graft.mjs

@@ -2,7 +2,7 @@
 
 // src/client/cli.ts
 import { spawnSync as spawnSync3 } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 
 // src/pull.ts
@@ -30,7 +30,7 @@ async function pull(o) {
     let id = o.copy && /^[A-Za-z0-9_-]{8,64}$/.test(o.copy) && !o.copy.includes("/") ? o.copy : null;
     if (!id) {
       const repo = o.copy ?? repoOfRemote(git(o.cwd, ["remote", "get-url", "origin"]).stdout ?? "");
-      if (!repo) return { ok: false, message: "Couldn't tell which copy this is: pass --copy owner/name." };
+      if (!repo) return { ok: false, message: "Couldn't tell which copy this is: give its id or owner/name (graft pull <copy>, or --copy <copy>), or run this inside its clone." };
       const { copies } = await get("/api/v1/copies");
       const c = copies.find((x) => String(x.repo).toLowerCase() === repo.toLowerCase());
       if (!c) return { ok: false, message: `${repo} isn't one of your copies on Graft.` };
@@ -132,6 +132,7 @@ var USAGE = `graft: the command line for graftfork.com (a thin client; syncs run
   graft connect <owner/name>   connect a repository (Graft's GitHub app must be installed on it)
                [--branch <b> --upstream <owner/name or URL> --base <release tag>] [--tags <pattern>]
   graft sync [copy]            start a sync now
+               [--force]       again, though the last sync of this release stopped at the agent's per-sync budget
   graft status [copy]          a copy and its latest runs
   graft why [copy]             why the copy stayed, and what to do next
   graft pull [copy]            fetch the latest move as graft/<release> in your clone
@@ -144,16 +145,18 @@ var USAGE = `graft: the command line for graftfork.com (a thin client; syncs run
   graft upstream-pr <build> <url>  the pull request you opened upstream; Graft checks it until it's merged
   graft usage                  this month's syncs and agent work
   graft verify-record <file>   check a run's signed record (from /app or GET /api/v1/runs/{id}/record),
-                               or an organization's agent change record
+                               a rebuild's, or an organization's agent change record
+  graft verify-record <id>     fetch a rebuild's (or a sync's) signed record by its id, with the token, and check it
   graft agent-record <org>     an organization's signed agent change record, as JSON
                [--from <YYYY-MM-DD> --to <YYYY-MM-DD>]   (save it: graft agent-record <org> > record.json)
   graft check <base> <head>    check a change against the project's own tests (no push, no agent)
                [--pr <n>] [--repo <owner/name> | --clone-url <url>] [--wait]
   graft checks [id]            your recent change checks, or one check's result
-  graft regen connect <owner/name or URL> --branch <b> --record <path> --impl <dir> --lang ts|py [--builds 1-3] [--on-push]
+  graft regen connect <owner/name or URL> --branch <b> --record <path> --impl <dir> --lang ts|py|rs|go [--builds 1-3] [--on-push]
                                connect a spec (a duramen record): Graft rebuilds its implementation blind
-  graft regen run <spec>       rebuild it now
+  graft regen run <spec>       rebuild it now [--force: even if nothing changed] [--max-usd <n>: its budget]
   graft regen status [id]      your specs, a spec's rebuilds, or one rebuild and how to take it
+  graft regen report <spec>    the spec's grade (strong, usable, thin) and why [--refresh [--yes]]
 
 [copy] is a copy id or owner/name; left out, it's this clone's origin remote.
 Token: GRAFT_TOKEN or --token (make one at https://graftfork.com/app#settings). --json prints raw answers.`;
@@ -164,7 +167,7 @@ async function run(argv, io) {
     args: argv,
     allowPositionals: true,
     strict: false,
-    options: { token: { type: "string" }, api: { type: "string" }, json: { type: "boolean" }, patch: { type: "string" }, "no-wait": { type: "boolean" }, branch: { type: "string" }, upstream: { type: "string" }, base: { type: "string" }, tags: { type: "string" }, from: { type: "string" }, to: { type: "string" }, repo: { type: "string" }, "clone-url": { type: "string" }, pr: { type: "string" }, wait: { type: "boolean" }, copy: { type: "string" }, record: { type: "string" }, impl: { type: "string" }, lang: { type: "string" }, builds: { type: "string" }, "on-push": { type: "boolean" }, help: { type: "boolean", short: "h" } }
+    options: { token: { type: "string" }, api: { type: "string" }, json: { type: "boolean" }, patch: { type: "string" }, "no-wait": { type: "boolean" }, branch: { type: "string" }, upstream: { type: "string" }, base: { type: "string" }, tags: { type: "string" }, from: { type: "string" }, to: { type: "string" }, repo: { type: "string" }, "clone-url": { type: "string" }, pr: { type: "string" }, wait: { type: "boolean" }, copy: { type: "string" }, record: { type: "string" }, impl: { type: "string" }, lang: { type: "string" }, builds: { type: "string" }, "on-push": { type: "boolean" }, refresh: { type: "boolean" }, force: { type: "boolean" }, "max-usd": { type: "string" }, yes: { type: "boolean" }, help: { type: "boolean", short: "h" } }
   });
   const [cmd, arg, arg2] = positionals;
   if (!cmd || a.help || cmd === "help") {
@@ -172,8 +175,8 @@ async function run(argv, io) {
     return cmd || a.help ? 0 : 1;
   }
   const api = String(a.api ?? io.env.GRAFT_API ?? "https://graftfork.com").replace(/\/+$/, "");
-  if (cmd === "verify-record") return verify(arg, api, io);
   const token = a.token ?? io.env.GRAFT_TOKEN;
+  if (cmd === "verify-record") return verify(arg, api, io, token);
   if (!token) {
     io.out("graft needs a personal API token: make one at https://graftfork.com/app#settings, then set GRAFT_TOKEN or pass --token.");
     return 1;
@@ -211,7 +214,7 @@ async function run(argv, io) {
       show(b, `${b.message ?? "Connected."}
 Copy id: ${b.copyId}`);
     } else if (cmd === "sync") {
-      const b = await call("POST", `/api/v1/copies/${await copyId(arg)}/sync`);
+      const b = await call("POST", `/api/v1/copies/${await copyId(arg)}/sync`, a.force ? { force: true } : void 0);
       show(b, `${b.message}
 Run: ${b.run}`);
     } else if (cmd === "status") {
@@ -224,7 +227,7 @@ Run: ${b.run}`);
       const stuck = (b.stuck ?? []).map((s) => `  ${s.change}: ${s.why}`);
       show(b, [b.headline, ...stuck.length ? ["Stuck:", ...stuck] : [], ...b.action ? [`What to do: ${b.action}`] : [], ...b.command ? [`  ${b.command}`] : [], `Next: ${b.next?.why ?? ""}`].filter(Boolean).join("\n"));
     } else if (cmd === "pull") {
-      const r = await pull({ cwd: io.cwd, copy: arg, token, api, fetchImpl: io.fetch });
+      const r = await pull({ cwd: io.cwd, copy: arg ?? a.copy, token, api, fetchImpl: io.fetch });
       io.out(r.message);
       return r.ok ? 0 : 1;
     } else if (cmd === "agent-record") {
@@ -296,7 +299,9 @@ Upgrade: ${b.upgrade}  (graft upgrades ${b.upgrade})`);
       return await regen(arg, arg2, a, call, show, io);
     } else if (cmd === "usage") {
       const b = await call("GET", "/api/v1/usage");
-      show(b, `${b.plan}: ${b.syncs?.used ?? 0} of ${b.syncs?.limit ?? "?"} syncs this month; Graft's agent $${Number(b.graftAgentUsd ?? 0).toFixed(2)}. Resets ${b.resetsOn}.`);
+      const orgs = Array.isArray(b.coveredBy) ? b.coveredBy : [];
+      const covered = orgs.length ? ` Copies in ${orgs.map((o) => `${o.name} (${o.plan})`).join(", ")} work as Premium: up to ${b.syncs?.coveredSyncs ?? "?"} syncs this month.` : "";
+      show(b, `${b.plan}${orgs.length ? " (your own)" : ""}: ${b.syncs?.used ?? 0} of ${b.syncs?.limit ?? "?"} syncs this month; Graft's agent $${Number(b.graftAgentUsd ?? 0).toFixed(2)}.${covered} Resets ${b.resetsOn}.`);
     } else {
       io.out(USAGE);
       return 1;
@@ -356,10 +361,10 @@ function checkText(c) {
   ].join("\n");
 }
 async function regen(sub, id, a, call, show, io) {
-  const line = (r) => `${r.id}  ${r.status}${r.phase ? ` (${r.phase})` : ""}${r.suite?.total ? `  suite ${r.suite.passed}/${r.suite.total}` : ""}${r.choicesDiffer ? `  ${r.choicesDiffer} choice(s) differ` : ""}${r.why ? `: ${r.why}` : ""}`;
+  const line = (r) => `${r.id}  ${r.status === "stayed" ? "not kept" : r.status}${r.phase ? ` (${r.phase})` : ""}${r.suite?.total ? `  suite ${r.suite.passed}/${r.suite.total}` : ""}${r.choicesDiffer ? `  ${r.choicesDiffer} choice(s) differ` : ""}${r.why ? `: ${r.why}` : ""}`;
   if (sub === "connect") {
     if (!id || !a.record || !a.impl || !a.lang || !a.branch) {
-      io.out("graft regen connect <owner/name or https URL> --branch <b> --record <path> --impl <dir> --lang ts|py [--builds 1-3] [--on-push]");
+      io.out("graft regen connect <owner/name or https URL> --branch <b> --record <path> --impl <dir> --lang ts|py|rs|go [--builds 1-3] [--on-push]");
       return 1;
     }
     const b = await call("POST", "/api/v1/regen", { .../^https:\/\//.test(id) ? { clone_url: id } : { repo: id }, branch: a.branch, record: a.record, impl: a.impl, lang: a.lang, ...a.builds && { builds: Number(a.builds) }, ...a["on-push"] && { on_push: true } });
@@ -367,10 +372,18 @@ async function regen(sub, id, a, call, show, io) {
 Spec id: ${b.id}`);
   } else if (sub === "run") {
     if (!id) {
-      io.out("graft regen run <spec id>");
+      io.out("graft regen run <spec id> [--force] [--max-usd <n>]");
       return 1;
     }
-    const b = await call("POST", `/api/v1/regen/${encodeURIComponent(id)}/run`);
+    const max = a["max-usd"] === void 0 ? void 0 : Number(a["max-usd"]);
+    if (max !== void 0 && !(Number.isFinite(max) && max >= 0)) {
+      io.out("--max-usd is a number of dollars, 0 or more.");
+      return 1;
+    }
+    const body = { ...a.force && { force: true }, ...max !== void 0 && { max_usd: max } };
+    const b = await call("POST", `/api/v1/regen/${encodeURIComponent(id)}/run`, Object.keys(body).length ? body : void 0).catch((e) => {
+      throw e instanceof ApiError ? new ApiError(e.message.replace(/\bmax_usd\b/g, "--max-usd")) : e;
+    });
     show(b, `${b.message}
 Rebuild: ${b.run}`);
   } else if (sub === "status") {
@@ -390,26 +403,91 @@ Rebuild: ${b.run}`);
     const differ = run2.choicesDiff?.previous;
     const lines = [line(run2), ...run2.builds.map((b) => `  build ${b.n}: ${b.verdict?.why ?? b.note ?? b.status}`)];
     if (differ) for (const [k, label] of [["changed", "chosen differently"], ["added", "new"], ["removed", "gone"]]) for (const c of differ[k]) lines.push(`  ${label}: ${c.title}`);
+    if (run2.doctor?.gaps?.length) {
+      const say = (g) => g.kind === "failing" ? `${g.ref}: cases ${g.cases.join(", ")} fail${g.why ? ` (${g.why})` : ""}` : g.kind === "builds differ" ? `${g.ref ?? g.title}: the builds chose differently` : g.kind === "changed since" ? `${g.ref ?? g.title}: chosen differently from the last passing rebuild` : g.kind === "build crashed" ? `${g.build ? `build ${g.build}` : "a build"} crashed: ${g.why}` : g.kind === "hidden request" ? `build ${g.build} answered ${g.op} ${g.input} differently from the oracle` : `the oracle can't answer ${g.op} ${g.input}: ${g.error}`;
+      lines.push(run2.doctor.summary, ...run2.doctor.gaps.slice(0, 8).map((g) => `  - ${say(g)}`), ...run2.doctor.gaps.length > 8 ? [`  and ${run2.doctor.gaps.length - 8} more (--json)`] : []);
+    }
     if (run2.take) lines.push("Take it, in your clone:", ...run2.take.commands.map((c) => `  ${c}`));
     show({ run: run2 }, lines.join("\n"));
+  } else if (sub === "report") {
+    if (!id) {
+      io.out("graft regen report <spec id> [--refresh]");
+      return 1;
+    }
+    if (a.refresh) {
+      const before = await call("GET", `/api/v1/regen/${encodeURIComponent(id)}/report`);
+      const price = Number(before.nextReport?.priceUsd ?? 0);
+      if (before.nextReport?.available === false) {
+        io.out(before.nextReport.why);
+        return 1;
+      }
+      if (price > 0 && !a.yes) {
+        io.out(`A new report costs $${price.toFixed(2)} from your agent work (today's free ones are used). Run again with --yes to pay for it.`);
+        return 1;
+      }
+      const q = await call("POST", `/api/v1/regen/${encodeURIComponent(id)}/report`, { max_usd: price });
+      show(q, `${q.message}
+Report run: ${q.run}`);
+      return 0;
+    }
+    const b = await call("GET", `/api/v1/regen/${encodeURIComponent(id)}/report`);
+    const r = b.report;
+    if (!r) {
+      show(b, b.pending ? `A report is on its way (${b.pending}).` : b.message ?? "No report yet: graft regen report <spec id> --refresh");
+      return 0;
+    }
+    const n = r.numbers ?? {};
+    const m = r.mutation ?? {};
+    show(b, [
+      `${String(r.grade).toUpperCase()}${r.commit ? ` (at ${String(r.commit).slice(0, 12)})` : ""}`,
+      ...r.reasons.map((x) => `  - ${x}`),
+      `${n.requirements ?? "?"} requirements, ${n.examples ?? "?"} examples, ${n.decisions ?? "?"} decisions, ${n.open ?? "?"} open; ${n.oracle ? "an oracle" : "no oracle"}`,
+      m.ran ? `mistakes planted in the oracle: ${m.killed} caught, ${m.unpinned} unnoticed, ${m.silent} change nothing (of ${m.total})` : `no mutation score: ${m.why}`,
+      `fit: ${r.fit?.why ?? ""}`,
+      ...b.pending ? [`A newer report is on its way (${b.pending}).`] : []
+    ].join("\n"));
   } else {
-    io.out("graft regen connect|run|status (graft help)");
+    io.out("graft regen connect|run|status|report (graft help)");
     return 1;
   }
   return 0;
 }
 var unb64 = (s) => Uint8Array.from(atob(s), (c) => c.charCodeAt(0));
-async function verify(file, api, io) {
+async function verify(file, api, io, token) {
   if (!file) {
-    io.out("graft verify-record <file>");
+    io.out("graft verify-record <file or rebuild id>");
     return 1;
   }
   let e;
-  try {
-    e = JSON.parse(readFileSync(file, "utf8"));
-  } catch {
-    io.out(`${file} isn't a Graft record (not JSON).`);
-    return 1;
+  if (!existsSync(file) && /^[A-Za-z0-9_-]{8,64}$/.test(file)) {
+    if (!token) {
+      io.out(`${file} isn't a file. To fetch a record by its id, graft needs a personal API token: make one at https://graftfork.com/app#settings, then set GRAFT_TOKEN or pass --token.`);
+      return 1;
+    }
+    let got = null;
+    for (const path of [`/api/v1/regen/runs/${file}/record`, `/api/v1/runs/${file}/record`]) {
+      const r2 = await io.fetch(`${api}${path}`, { headers: { authorization: `Bearer ${token}` } });
+      if (r2.ok) {
+        got = await r2.json().catch(() => null);
+        break;
+      }
+      if (r2.status !== 404) {
+        io.out(`graftfork.com answered ${r2.status} for ${file}'s record.`);
+        return 1;
+      }
+    }
+    if (!got) {
+      io.out(`No signed record for ${file}: not one of your rebuilds or syncs (or a public spec's rebuild), or it hasn't finished.`);
+      return 1;
+    }
+    e = got;
+  } else {
+    try {
+      e = JSON.parse(readFileSync(file, "utf8"));
+    } catch {
+      io.out(`${file} isn't a Graft record (not JSON).`);
+      return 1;
+    }
   }
   if (e?.graft_record !== 1 || e.alg !== "Ed25519" || typeof e.payload !== "string" || typeof e.signature !== "string") {
     io.out(`${file} isn't a Graft record.`);
@@ -436,7 +514,23 @@ async function verify(file, api, io) {
     io.out(`Valid: signed by graftfork.com (key ${k.id}). Agent change record for ${r.org?.name ?? r.org?.id}, ${r.range?.from} to ${r.range?.to}: ${(r.changes ?? []).length} change(s) in ${r.counts?.runs ?? 0} run(s), ${(r.agent_actions ?? []).length} agent action(s).`);
     return 0;
   }
-  io.out(`Valid: signed by graftfork.com (key ${k.id}). Run ${r.run}, ${r.outcome}${r.upstream?.to ? ` onto ${r.upstream.to}` : ""}, ${(r.changes ?? []).length} change(s).`);
+  const i = r.initiator;
+  const by = !i?.kind ? "" : i.kind === "agent" ? ` Started by ${i.agent ? `the organization's agent ${i.agent} (org ${i.org ?? "unknown"}, ` : "an agent ("}token ${i.token ?? "unknown"}${i.client?.name ? `, ${i.client.name}${i.client.version ? ` ${i.client.version}` : ""}` : ""}).` : i.kind === "ops" ? " Started by Graft's operator." : i.kind === "schedule" ? " Started by Graft on its own (a release, a push or a new model)." : " Started by a person.";
+  if (r.kind === "regen") {
+    const outcome = r.outcome === "passed" ? "kept" : r.outcome === "stayed" ? "not kept" : r.outcome;
+    if (r.rejudge?.of) {
+      const verdict = r.outcome === "passed" ? "passed" : r.outcome === "stayed" ? "didn't pass" : r.outcome;
+      const agree = r.rejudge.agrees === true ? "agrees with" : r.rejudge.agrees === false ? "differs from" : "can't be compared with";
+      io.out(`Valid: signed by graftfork.com (key ${k.id}). Re-judge ${r.run} of rebuild ${r.rejudge.of}: ${verdict}${r.suite ? `, suite ${r.suite.passed}/${r.suite.total}` : ""}, holdout seed ${r.rejudge.seed}${r.rejudge.same_seed ? " (the rebuild's own)" : ""}; it ${agree} the first judge.${r.judge ? ` Judged as ${r.judge.driver_user === "separate" ? "a separate user" : "the oracle's user"}, network ${r.judge.network}.` : ""}${by}`);
+      return 0;
+    }
+    const what = r.draft?.branch ? `Draft rebuild ${r.run} of branch ${r.draft.branch}` : `Rebuild ${r.run}`;
+    const b = r.behaviour;
+    const beh = !b ? "" : b.sampled ? ` Against rebuild ${b.against?.run ?? "?"}: ${b.requests} requests, ${(b.paths ?? []).length} part(s) of the answer changed, ${b.unexplained} change(s) the record didn't ask for.` : ` Not compared with the kept build${b.why ? `: ${b.why}` : ""}.`;
+    io.out(`Valid: signed by graftfork.com (key ${k.id}). ${what}, ${outcome}${r.copy?.repo ? `: ${r.copy.repo} ${r.copy.record ?? ""} to ${r.copy.impl ?? ""}` : ""}${r.spec?.name ? ` (${r.spec.name}${r.spec.version ? ` ${r.spec.version}` : ""})` : ""}${r.suite ? `, suite ${r.suite.passed}/${r.suite.total}` : ""}, ${(r.builds ?? []).length} build(s).${beh}${by}`);
+    return 0;
+  }
+  io.out(`Valid: signed by graftfork.com (key ${k.id}). Run ${r.run}, ${r.outcome}${r.upstream?.to ? ` onto ${r.upstream.to}` : ""}, ${(r.changes ?? []).length} change(s).${by}`);
   return 0;
 }
 if (process.argv[1] && /graft(\.mjs)?$|client[/\\]cli\.ts$/.test(process.argv[1])) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graftfork",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The command line for graftfork.com: connect a copy, sync it, see why it stayed, and take each move. A thin client; syncs run on graftfork.com.",
   "license": "Apache-2.0",
   "homepage": "https://graftfork.com/docs/api",