graftfork 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# graftfork
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The command line for [Graft](https://graftfork.com). Graft keeps your changes to an open-source project on each
+upstream release: it moves your changes onto the new release, runs your tests, and keeps the moved branch for you
+only if every change lands and the tests pass. Otherwise your copy stays where it was and Graft says why.
+
+This package is a thin client for graftfork.com's HTTP API. Syncs run on graftfork.com, not on your machine.
+
+```
+npm install -g graftfork          # Node 22.18 or newer; the command is `graft`
+export GRAFT_TOKEN=graft_...      # make a token at https://graftfork.com/app#settings
+
+graft copies                      # your copies and where each one is
+graft connect you/project         # connect a repository Graft's GitHub app is installed on
+graft sync                        # start a sync now (inside the clone, or pass the copy)
+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-pr <build> <url>   # the pull request you opened; Graft tells you when it's merged
+```
+
+Also `graft whoami`, `graft status` and `graft usage`; `--json` prints the API's answers as they are. API docs:
+https://graftfork.com/docs/api. Support by email: support@graftfork.com. Apache-2.0.

package/graft.mjs

@@ -0,0 +1,447 @@
+#!/usr/bin/env node
+
+// src/client/cli.ts
+import { spawnSync as spawnSync3 } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+
+// src/pull.ts
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+var git = (cwd, args) => spawnSync("git", args, { cwd, encoding: "utf8" });
+function repoOfRemote(url) {
+  const m = url.trim().match(/[:/]([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/);
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+async function pull(o) {
+  const f = o.fetchImpl ?? fetch;
+  if (!o.token) return { ok: false, message: "graft pull needs a personal API token: make one at graftfork.com/app#settings, then set GRAFT_TOKEN or pass --token." };
+  if (git(o.cwd, ["rev-parse", "--git-dir"]).status !== 0) return { ok: false, message: "Run graft pull inside your clone of the copy." };
+  const headers = { authorization: `Bearer ${o.token}` };
+  const get = async (path) => {
+    const r = await f(`${o.api}${path}`, { headers });
+    const body = await r.json().catch(() => ({}));
+    if (!r.ok) throw new Error(body?.error?.message ?? `graftfork.com answered ${r.status}`);
+    return body;
+  };
+  try {
+    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." };
+      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.` };
+      id = c.id;
+    }
+    const t = await get(`/api/v1/copies/${id}/take`);
+    const r = await f(t.download);
+    if (!r.ok) return { ok: false, message: `Downloading the move failed (${r.status}). Try again; the link is made fresh each time.` };
+    const dir = mkdtempSync(join(tmpdir(), "graft-pull-"));
+    const file = join(dir, "move.bundle");
+    try {
+      writeFileSync(file, new Uint8Array(await r.arrayBuffer()));
+      const v = git(o.cwd, ["bundle", "verify", "-q", file]);
+      if (v.status !== 0) {
+        return { ok: false, message: `This clone is missing what the move builds on (${v.stderr.trim().split("\n").pop()}). Bring ${t.copy.branch} up to date (git fetch origin ${t.copy.branch}), then run graft pull again.` };
+      }
+      const fetched = git(o.cwd, ["fetch", "-q", file, `+refs/heads/${t.branch}:refs/heads/${t.branch}`]);
+      if (fetched.status !== 0) return { ok: false, message: `git fetch failed: ${fetched.stderr.trim().split("\n").pop()}` };
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+    const sha = git(o.cwd, ["rev-parse", "--short", t.branch]).stdout.trim();
+    return { ok: true, branch: t.branch, message: `Fetched ${t.branch} (${sha}): ${t.release ? `your changes on ${t.release}` : "the branch Graft delivered"}. Your branch is untouched.
+Switch with: git switch ${t.branch}
+Or take it into ${t.copy.branch}: git checkout ${t.copy.branch} && git merge --ff-only ${t.branch}` };
+  } catch (e) {
+    return { ok: false, message: e.message };
+  }
+}
+
+// src/client/upstream.ts
+import { spawnSync as spawnSync2 } from "node:child_process";
+import { mkdtempSync as mkdtempSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { tmpdir as tmpdir2 } from "node:os";
+import { join as join2 } from "node:path";
+var git2 = (cwd, args) => spawnSync2("git", args, { cwd, encoding: "utf8" });
+async function upstream(o) {
+  const started = await o.call("POST", `/api/v1/copies/${o.copyId}/upstream`, { change: o.change });
+  let u = started.upstream;
+  if (o.noWait) return { ok: true, message: `${started.message ?? "Building."}
+Build: ${u.id}. Check it with graft upstream-status ${u.id}.` };
+  const until = Date.now() + (o.waitMs ?? 30 * 6e4);
+  while (u.status === "queued" || u.status === "running") {
+    if (Date.now() > until) return { ok: false, message: `Still building after ${Math.round((o.waitMs ?? 30 * 6e4) / 6e4)} minutes. Check it later with graft upstream-status ${u.id}.` };
+    await new Promise((r) => setTimeout(r, o.pollMs ?? 1e4));
+    u = (await o.call("GET", `/api/v1/upstreams/${u.id}`)).upstream;
+  }
+  if (u.status !== "built") return { ok: false, message: `Not built: ${u.note ?? "the build failed"}` };
+  return take(o, u);
+}
+async function take(o, u) {
+  if (!u.downloads?.bundle) return { ok: false, message: `Built ${u.branch}, but Graft doesn't keep it any more. Build it again with graft upstream.` };
+  if (git2(o.cwd, ["rev-parse", "--git-dir"]).status !== 0) return { ok: false, message: `Built ${u.branch}. Run this inside your clone of the copy to fetch it, or download it: ${u.downloads.bundle}` };
+  const r = await o.fetchImpl(u.downloads.bundle);
+  if (!r.ok) return { ok: false, message: `Downloading the branch failed (${r.status}). Try again; graft upstream-status makes a fresh link.` };
+  const dir = mkdtempSync2(join2(tmpdir2(), "graft-upstream-"));
+  const file = join2(dir, "upstream.bundle");
+  try {
+    writeFileSync2(file, new Uint8Array(await r.arrayBuffer()));
+    const v = git2(o.cwd, ["bundle", "verify", "-q", file]);
+    if (v.status !== 0) return { ok: false, message: `This clone is missing what the branch builds on (${v.stderr.trim().split("\n").pop()}). Bring your copy's branch up to date, then run it again.` };
+    const f = git2(o.cwd, ["fetch", "-q", file, `+refs/heads/${u.branch}:refs/heads/${u.branch}`]);
+    if (f.status !== 0) return { ok: false, message: `git fetch failed: ${f.stderr.trim().split("\n").pop()}` };
+  } finally {
+    rmSync2(dir, { recursive: true, force: true });
+  }
+  let saved = "";
+  if (o.patchDir && u.downloads.patch) {
+    const p = await o.fetchImpl(u.downloads.patch);
+    if (p.ok) {
+      const path = join2(o.patchDir, `${String(u.branch).split("/").pop()}.patch`);
+      writeFileSync2(path, await p.text());
+      saved = `
+The patch, for projects that take them by email: ${path}`;
+    }
+  }
+  const t = u.tests ?? {};
+  const pr = u.pullRequest ?? {};
+  return {
+    ok: true,
+    branch: u.branch,
+    message: [
+      `Fetched ${u.branch}: only "${u.change?.subject}" on ${u.release}${t.ran ? `; your tests: ${t.verdict ?? "ran"}` : "; no tests ran"}.${saved}`,
+      "Nothing was pushed. To send it, from your account:",
+      ...(u.commands ?? []).slice(2).map((c) => `  ${c}`),
+      `Pull request title: ${pr.title}`,
+      "Pull request text:",
+      ...String(pr.body ?? "").split("\n").map((l) => `  ${l}`),
+      `Then: graft upstream-pr ${u.id} <the pull request's URL>, and Graft tells you when it's merged.`
+    ].join("\n")
+  };
+}
+
+// src/client/cli.ts
+var USAGE = `graft: the command line for graftfork.com (a thin client; syncs run on graftfork.com)
+
+  graft whoami                 the token's account and scopes
+  graft copies                 your copies and where each one is
+  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
+  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
+  graft upgrade <dependency> [version] [--copy <copy>]
+                               upgrade a dependency (npm or Python), delivered only if the tests pass
+  graft upgrades [id]          your upgrades, or one with what its tests said
+  graft upstream <change> [copy]   build one change alone on your release, tested; fetch graft/upstream/<change>
+               [--patch <dir>] [--no-wait]   (nothing is pushed: you open the pull request yourself)
+  graft upstream-status <build>    an upstream build's status, tests and links
+  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
+  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]
+                               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
+
+[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.`;
+var ApiError = class extends Error {
+};
+async function run(argv, io) {
+  const { values: a, positionals } = parseArgs({
+    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" } }
+  });
+  const [cmd, arg, arg2] = positionals;
+  if (!cmd || a.help || cmd === "help") {
+    io.out(USAGE);
+    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 (!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;
+  }
+  const call = async (method, path, body) => {
+    const r = await io.fetch(`${api}${path}`, { method, headers: { authorization: `Bearer ${token}`, ...body && { "content-type": "application/json" } }, ...body && { body: JSON.stringify(body) } });
+    const b = await r.json().catch(() => ({}));
+    if (!r.ok) throw new ApiError(b?.error?.message ?? `graftfork.com answered ${r.status}`);
+    return b;
+  };
+  const show = (b, text) => io.out(a.json ? JSON.stringify(b, null, 1) : text);
+  const copyId = async (given) => {
+    if (given && !given.includes("/") && /^[A-Za-z0-9_-]{8,64}$/.test(given)) return given;
+    const repo = given ?? repoOfRemote(spawnSync3("git", ["remote", "get-url", "origin"], { cwd: io.cwd, encoding: "utf8" }).stdout ?? "");
+    if (!repo) throw new ApiError("Couldn't tell which copy: give its id or owner/name, or run this inside its clone.");
+    const { copies } = await call("GET", "/api/v1/copies");
+    const c = copies.find((x) => String(x.repo).toLowerCase() === repo.toLowerCase());
+    if (!c) throw new ApiError(`${repo} isn't one of your copies on Graft. Connect it with: graft connect ${repo}`);
+    return c.id;
+  };
+  try {
+    if (cmd === "whoami") {
+      const b = await call("GET", "/api/v1/token");
+      show(b, `${b.email}: scopes ${b.scopes.join(", ")}`);
+    } else if (cmd === "copies") {
+      const b = await call("GET", "/api/v1/copies");
+      const rows = b.copies.map((c) => `${c.id}  ${c.repo} ${c.branch ?? ""} on ${c.base ?? "?"}${c.last ? `  last: ${c.last.status}${c.last.release ? ` ${c.last.release}` : ""}` : "  never synced"}`);
+      show(b, rows.length ? rows.join("\n") : "No copies yet. Connect one with: graft connect <owner/name>");
+    } else if (cmd === "connect") {
+      if (!arg) {
+        io.out("graft connect <owner/name> [--branch <b> --upstream <repo> --base <tag>] [--tags <pattern>]");
+        return 1;
+      }
+      const b = await call("POST", "/api/v1/copies", { repo: arg, ...a.branch && { branch: a.branch }, ...a.upstream && { upstream: a.upstream }, ...a.base && { base: a.base }, ...a.tags && { tags: a.tags } });
+      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`);
+      show(b, `${b.message}
+Run: ${b.run}`);
+    } else if (cmd === "status") {
+      const b = await call("GET", `/api/v1/copies/${await copyId(arg)}`);
+      const c = b.copy;
+      const runs = (b.recentRuns ?? []).map((r) => `  ${r.at ?? r.created_at ?? ""}  ${r.status}${r.release ? ` ${r.release}` : ""}${r.note ? `: ${r.note}` : ""}`);
+      show(b, [`${c.repo} ${c.branch ?? ""} on ${c.base ?? "?"}, following ${c.upstream ?? "?"}`, ...runs.length ? ["Recent runs:", ...runs] : ["No runs yet."]].join("\n"));
+    } else if (cmd === "why") {
+      const b = await call("GET", `/api/v1/copies/${await copyId(arg)}/explain`);
+      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 });
+      io.out(r.message);
+      return r.ok ? 0 : 1;
+    } else if (cmd === "agent-record") {
+      if (!arg) {
+        io.out("graft agent-record <organization id> [--from <YYYY-MM-DD> --to <YYYY-MM-DD>]");
+        return 1;
+      }
+      const q = new URLSearchParams({ ...a.from && { from: String(a.from) }, ...a.to && { to: String(a.to) } }).toString();
+      const b = await call("GET", `/api/v1/orgs/${encodeURIComponent(arg)}/agent-record${q ? `?${q}` : ""}`);
+      io.out(JSON.stringify(b, null, 1));
+    } else if (cmd === "check") {
+      return await check(positionals[1], positionals[2]);
+    } else if (cmd === "checks") {
+      if (arg) {
+        const b = await call("GET", `/api/v1/checks/${encodeURIComponent(arg)}`);
+        show(b, checkText(b.check));
+      } else {
+        const b = await call("GET", "/api/v1/checks");
+        const rows = b.checks.map((c) => `${c.id}  ${c.repo} ${c.head} vs ${c.base}${c.pr ? ` (#${c.pr})` : ""}  ${c.outcome ?? c.status}`);
+        show(b, [...rows.length ? rows : ["No change checks yet. Start one with: graft check <base> <head>"], ...b.usage ? [`${b.usage.used} of ${b.usage.limit} checks this month.`] : []].join("\n"));
+      }
+    } else if (cmd === "upgrade") {
+      if (!arg) {
+        io.out("graft upgrade <dependency> [version] [--copy <copy id or owner/name>]");
+        return 1;
+      }
+      const b = await call("POST", "/api/v1/upgrades", { copy_id: await copyId(a.copy), dependency: arg, ...positionals[2] && { version: positionals[2] } });
+      show(b, `${b.message}
+Upgrade: ${b.upgrade}  (graft upgrades ${b.upgrade})`);
+    } else if (cmd === "upgrades") {
+      if (arg) {
+        const { upgrade: u } = await call("GET", `/api/v1/upgrades/${encodeURIComponent(arg)}`);
+        const lines = [`${u.dependency} ${u.from ?? ""} to ${u.version ?? u.requested} on ${u.repo ?? "?"}: ${u.status}`, ...u.why ? [`  ${u.why}`] : []];
+        if (u.tests?.newFailures?.length) lines.push("Broken by the upgrade:", ...u.tests.newFailures.map((f) => `  ${f}`));
+        if (u.fix) lines.push(`Graft's agent: ${u.fix.applied ? `changed ${(u.fix.files ?? []).join(", ")}` : `not used (${u.fix.why})`}`);
+        if (u.delivered) lines.push(`Delivered as ${u.delivered.branch}. Take it in your clone with: graft pull ${u.run}`);
+        if (u.prUrl) lines.push(`Pull request: ${u.prUrl}`);
+        show({ upgrade: u }, lines.join("\n"));
+      } else {
+        const b = await call("GET", "/api/v1/upgrades");
+        const rows = b.upgrades.map((u) => `${u.id}  ${u.repo ?? "?"}  ${u.dependency} to ${u.version ?? u.requested}: ${u.status}`);
+        show(b, rows.length ? rows.join("\n") : "No upgrades yet. Start one with: graft upgrade <dependency> [version]");
+      }
+    } else if (cmd === "upstream") {
+      if (!arg) {
+        io.out("graft upstream <change> [copy] [--patch <dir>] [--no-wait]: the change's subject (or part of it), or its number in the latest move");
+        return 1;
+      }
+      const r = await upstream({ cwd: io.cwd, copyId: await copyId(arg2), change: arg, call, fetchImpl: io.fetch, noWait: !!a["no-wait"], ...a.patch && { patchDir: String(a.patch) }, ...io.env.GRAFT_POLL_MS && { pollMs: Number(io.env.GRAFT_POLL_MS) } });
+      io.out(r.message);
+      return r.ok ? 0 : 1;
+    } else if (cmd === "upstream-status") {
+      if (!arg) {
+        io.out("graft upstream-status <build>");
+        return 1;
+      }
+      const b = await call("GET", `/api/v1/upstreams/${encodeURIComponent(arg)}`);
+      const u = b.upstream;
+      const pr = u.pullRequest ?? {};
+      show(b, [`${u.change?.subject} on ${u.release}: ${u.status}${u.phase ? ` (${u.phase})` : ""}${u.note ? `. ${u.note}` : ""}`, ...(u.commands ?? []).map((c) => `  ${c}`), ...pr.url ? [`Pull request: ${pr.url}${pr.state ? ` (${pr.state})` : ""}`] : []].join("\n"));
+    } else if (cmd === "upstream-pr") {
+      if (!arg || !arg2) {
+        io.out("graft upstream-pr <build> <https://github.com/owner/name/pull/123>");
+        return 1;
+      }
+      const b = await call("POST", `/api/v1/upstreams/${encodeURIComponent(arg)}/pr`, { url: arg2 });
+      show(b, b.message);
+    } else if (cmd === "regen") {
+      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}.`);
+    } else {
+      io.out(USAGE);
+      return 1;
+    }
+    return 0;
+  } catch (e) {
+    io.out(e instanceof ApiError ? e.message : `graft: ${e.message}`);
+    return 1;
+  }
+  async function check(base, head) {
+    const pr = a.pr === void 0 ? void 0 : Number(a.pr);
+    if ((!base || !head) && pr === void 0) {
+      io.out("graft check <base> <head> [--pr <n>] [--repo <owner/name> | --clone-url <url>] [--wait]");
+      return 1;
+    }
+    let where;
+    if (a.repo) where = { repo: a.repo };
+    else if (a["clone-url"]) where = { clone_url: a["clone-url"] };
+    else {
+      const remote = (spawnSync3("git", ["remote", "get-url", "origin"], { cwd: io.cwd, encoding: "utf8" }).stdout ?? "").trim();
+      const repo = repoOfRemote(remote);
+      if (/github\.com[:/]/.test(remote) && repo) where = { repo };
+      else if (/^https:\/\//.test(remote) && !/@/.test(remote.split("/")[2] ?? "")) where = { clone_url: remote };
+      else {
+        io.out("Couldn't tell which repository: pass --repo <owner/name> or --clone-url <url>, or run this inside its clone.");
+        return 1;
+      }
+    }
+    const b = await call("POST", "/api/v1/checks", { ...where, ...base && { base }, ...head && { head }, ...pr !== void 0 && { pr } });
+    if (!a.wait) {
+      show(b, `${b.message}
+Check: ${b.check}  (graft checks ${b.check})`);
+      return 0;
+    }
+    const sleep = io.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    for (let i = 0; i < 200; i++) {
+      const c = (await call("GET", `/api/v1/checks/${encodeURIComponent(b.check)}`)).check;
+      if (!["queued", "running"].includes(c.status)) {
+        show({ check: c }, checkText(c));
+        return c.outcome === "pass" ? 0 : c.outcome === "fail" ? 1 : 2;
+      }
+      await sleep(15e3);
+    }
+    io.out(`Still running. Read it later with: graft checks ${b.check}`);
+    return 2;
+  }
+}
+function checkText(c) {
+  const word = c.outcome === "pass" ? "PASS" : c.outcome === "fail" ? "FAIL" : c.outcome === "could_not_run" ? "COULD NOT RUN" : String(c.status).toUpperCase();
+  const sha = (r) => r?.sha ? ` (${String(r.sha).slice(0, 7)})` : "";
+  return [
+    `${word}: ${c.repo} ${c.head}${sha(c.headRun)} against ${c.base}${sha(c.baseRun)}${c.pr ? `, pull request #${c.pr}` : ""}`,
+    ...c.reason ? [c.reason] : [],
+    ...(c.newFailures ?? []).length ? ["New failures:", ...c.newFailures.map((f) => `  ${f}`)] : [],
+    ...(c.alreadyFailing ?? []).length ? [`${c.alreadyFailing.length} already failing on the base (not counted against the change).`] : [],
+    ...(c.testFilesChanged ?? []).length ? [`The change edits files that shape the tests: ${c.testFilesChanged.join(", ")}. Read them before trusting the result.`] : []
+  ].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}` : ""}`;
+  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]");
+      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 } });
+    show(b, `${b.message ?? "Connected."}
+Spec id: ${b.id}`);
+  } else if (sub === "run") {
+    if (!id) {
+      io.out("graft regen run <spec id>");
+      return 1;
+    }
+    const b = await call("POST", `/api/v1/regen/${encodeURIComponent(id)}/run`);
+    show(b, `${b.message}
+Rebuild: ${b.run}`);
+  } else if (sub === "status") {
+    if (!id) {
+      const b = await call("GET", "/api/v1/regen");
+      const rows = b.specs.map((s) => `${s.id}  ${s.repo} ${s.branch}: ${s.record} -> ${s.impl} (${s.lang})${s.last ? `
+    last: ${line(s.last)}` : "\n    never rebuilt"}`);
+      show(b, rows.length ? rows.join("\n") : b.available ? "No specs yet. Connect one with: graft regen connect <owner/name> --branch main --record spec/ --impl impl --lang ts" : "Rebuilding from a spec is on Premium, Team and Enterprise.");
+      return 0;
+    }
+    const spec = await call("GET", `/api/v1/regen/${encodeURIComponent(id)}`).catch(() => null);
+    if (spec) {
+      show(spec, [`${spec.spec.repo} ${spec.spec.branch}: ${spec.spec.record} -> ${spec.spec.impl} (${spec.spec.lang})`, ...spec.runs.length ? spec.runs.map((r) => `  ${line(r)}`) : ["  No rebuilds yet."]].join("\n"));
+      return 0;
+    }
+    const { run: run2 } = await call("GET", `/api/v1/regen/runs/${encodeURIComponent(id)}`);
+    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.take) lines.push("Take it, in your clone:", ...run2.take.commands.map((c) => `  ${c}`));
+    show({ run: run2 }, lines.join("\n"));
+  } else {
+    io.out("graft regen connect|run|status (graft help)");
+    return 1;
+  }
+  return 0;
+}
+var unb64 = (s) => Uint8Array.from(atob(s), (c) => c.charCodeAt(0));
+async function verify(file, api, io) {
+  if (!file) {
+    io.out("graft verify-record <file>");
+    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 (e?.graft_record !== 1 || e.alg !== "Ed25519" || typeof e.payload !== "string" || typeof e.signature !== "string") {
+    io.out(`${file} isn't a Graft record.`);
+    return 1;
+  }
+  const { keys } = await (await io.fetch(`${api}/.well-known/graft-record-key`)).json();
+  const k = keys.find((x) => x.id === e.key);
+  if (!k) {
+    io.out(`NOT valid: signed with a key Graft doesn't publish (${e.key}).`);
+    return 1;
+  }
+  let good = false;
+  try {
+    const pub = await crypto.subtle.importKey("raw", unb64(k.public), { name: "Ed25519" }, false, ["verify"]);
+    good = await crypto.subtle.verify({ name: "Ed25519" }, pub, unb64(e.signature), new TextEncoder().encode(e.payload));
+  } catch {
+  }
+  if (!good) {
+    io.out("NOT valid: the record was changed after Graft signed it, or Graft didn't sign it.");
+    return 1;
+  }
+  const r = JSON.parse(e.payload);
+  if (r.graft_agent_record === 1) {
+    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).`);
+  return 0;
+}
+if (process.argv[1] && /graft(\.mjs)?$|client[/\\]cli\.ts$/.test(process.argv[1])) {
+  process.exitCode = await run(process.argv.slice(2), { env: process.env, cwd: process.cwd(), fetch, out: (s) => console.log(s) });
+}
+export {
+  run
+};

package/package.json

@@ -1,6 +1,14 @@
 {
   "name": "graftfork",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.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",
+  "bugs": { "email": "support@graftfork.com" },
+  "author": "Craig Merry",
+  "type": "module",
+  "bin": { "graft": "graft.mjs" },
+  "files": ["graft.mjs", "LICENSE", "README.md"],
+  "engines": { "node": ">=22.18" },
+  "keywords": ["fork", "git", "upstream", "releases", "graftfork"]
+}