@jr2/orchestrator 0.3.0 → 0.5.1

package/src/fail.ts

@@ -0,0 +1,209 @@
+// The `fail()` Part (ADR-0073): the end that a Machine chooses for work that did not succeed — a
+// Failure (GLOSSARY.md). It is a Part and not an Effect, because it does no work outside the
+// Machine: its actor throws an error that carries a brand, and xstate sends that error up through
+// each parent Machine by its own rules. An `onError` on the way catches it; `isFailure` tells it
+// from a defect. When no state catches it, the run host ends the run `failed`.
+//
+// The brand is a registry symbol (`Symbol.for`), not a module symbol, for the reason the walk is
+// structural (parts.ts): an Instance resolves its OWN `@jr2/orchestrator`, so the copy that throws
+// and the copy that reads the error (the run host, the CLI's walk) can be two module instances. The
+// brand is not exported: an author makes a Failure only with `fail()`.
+
+import { fromPromise, type PromiseActorLogic } from "xstate";
+
+const FAILURE: unique symbol = Symbol.for("jr2.failure") as never;
+const FAIL_SLOT: unique symbol = Symbol.for("jr2.fail.slot") as never;
+
+/** What a Failure carries: `reason`, text for a person, and `detail`, optional JSON for a machine
+ * reader. The input of `fail()` and the output of a run that ends `failed`. */
+export type FailureInput = { reason: string; detail?: unknown };
+
+/** A Failure as `isFailure` narrows an error to it: the payload's fields, on the error itself. */
+export type Failure = { readonly reason: string; readonly detail?: unknown };
+
+/** Make the branded error. Only this module makes one. */
+function failure(input: FailureInput): Error & Failure {
+  const error = new Error(input.reason) as Error & Failure & { [FAILURE]: true };
+  error.name = "Failure";
+  Object.defineProperty(error, "reason", { value: input.reason, enumerable: true });
+  if (input.detail !== undefined) Object.defineProperty(error, "detail", { value: input.detail, enumerable: true });
+  Object.defineProperty(error, FAILURE, { value: true });
+  return error;
+}
+
+/** Refuse an input that is not a Failure's. A defect of the Machine, not a Failure: it ends the run
+ * `error`, with this text as the fault. */
+function checked(raw: unknown): FailureInput {
+  const input = raw as Partial<FailureInput> | undefined;
+  if (typeof input !== "object" || input === null || typeof input.reason !== "string" || input.reason === "") {
+    throw new Error(
+      `fail: the input must be { reason: string; detail?: unknown } with a reason that is not empty (got ${describe(raw)}) — ` +
+        `invoke: { src: "fail", input: { reason: "the tests failed" } } (ADR-0073)`,
+    );
+  }
+  return input.detail === undefined ? { reason: input.reason } : { reason: input.reason, detail: input.detail };
+}
+
+function describe(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+/** The actor logic that throws. Unbranded: what `workspace()` invokes to send a caught Failure up
+ * again, which is the wrapper's mechanism and no state of the author's that fails the run. */
+export const failLogic: PromiseActorLogic<never, FailureInput> = fromPromise<never, FailureInput>(async ({ input }) => {
+  throw failure(checked(input));
+});
+
+/** The logic `fail()` returns: {@link failLogic} with the brand the walk reads. */
+export type FailSlot = PromiseActorLogic<never, FailureInput> & { readonly [FAIL_SLOT]: true };
+
+/**
+ * Fail the run: the Part a Machine invokes to end work that did not succeed. Put it in `actors`
+ * under a name, and invoke it from any state, at any depth: `actors: { fail: fail() }`, then
+ * `invoke: { src: "fail", input: { reason } }`.
+ *
+ * The input is `{ reason: string; detail?: unknown }`. `reason` is text for a person, and it must
+ * not be empty. `detail` is optional JSON for a machine reader.
+ *
+ * The Failure goes up from the state that invokes `fail`, through each parent Machine, as an error
+ * does. An `onError` on the way catches it; {@link isFailure} tells it from a defect. When no state
+ * catches it, the run ends `failed`: its output is `{ reason, detail }`, and `jr2 run` exits 1. A
+ * `workspace()` that a Failure goes through deletes its Sandbox first.
+ *
+ * To fail, invoke `fail`. Do not throw from a promise to fail: a throw is a defect, and the run
+ * ends `error`. A final state means `done`: do not use one for work that did not succeed. To keep
+ * the work for a person to read, wait at a Gate before the state that fails.
+ *
+ * It refuses an input that is not a Failure's, and the run ends `error`: ``fail: the input must be
+ * { reason: string; detail?: unknown } with a reason that is not empty (got <value>) — invoke:
+ * { src: "fail", input: { reason: "the tests failed" } } (ADR-0073)``.
+ *
+ * @returns The actor logic of the slot.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { command, fail, jr2Setup, workspace, type Workspaced } from "@jr2/orchestrator";
+ *
+ * const runInput = z.object({ branch: z.string() });
+ *
+ * const body = jr2Setup({
+ *   types: {} as { input: Workspaced<z.infer<typeof runInput>, "app"> },
+ *   actors: {
+ *     tests: command(["npm", "test"], { timeout: "15m" }),
+ *     fail: fail(),
+ *   },
+ * }).createMachine({
+ *   id: "check",
+ *   on: { "workspace.lost": ".lost" },
+ *   initial: "testing",
+ *   states: {
+ *     testing: {
+ *       invoke: {
+ *         src: "tests",
+ *         onDone: [
+ *           {
+ *             guard: ({ event }) => event.output.outcome === "exited" && event.output.code === 0,
+ *             target: "passed",
+ *           },
+ *           { target: "failing" },
+ *         ],
+ *       },
+ *     },
+ *     // Not a final state: the run ends `failed`, and the Workspace deletes the Sandbox.
+ *     failing: { invoke: { src: "fail", input: { reason: "npm test did not pass" } } },
+ *     passed: { type: "final" },
+ *     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
+ *   },
+ * });
+ *
+ * export const machine = workspace(body, {
+ *   input: runInput,
+ *   repos: { app: "https://github.com/you/app.git" },
+ *   spec: ({ input }) => ({ branch: input.branch }),
+ * });
+ * ```
+ *
+ * @see docs/reference/decisions/0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md
+ */
+export function fail(): FailSlot {
+  // Logic of its own per slot, so the brand is on this slot's logic and on no other's.
+  const logic = fromPromise<never, FailureInput>(async ({ input }) => {
+    throw failure(checked(input));
+  });
+  return Object.defineProperty(logic, FAIL_SLOT, { value: true }) as FailSlot;
+}
+
+/** Is this actor logic a `fail()` slot? A test on the brand, like `isAgent`: what the walk reads to
+ * list each state that can fail the run (ADR-0073). */
+export function isFailSlot(logic: unknown): logic is FailSlot {
+  return typeof logic === "object" && logic !== null && (logic as { [FAIL_SLOT]?: unknown })[FAIL_SLOT] === true;
+}
+
+/**
+ * Is this error a Failure, which a state invoked `fail` to make? A defect — any other error — is
+ * not. Use it in the guard of an `onError` to catch a Failure and let a defect go up, and read the
+ * Failure's `reason` and `detail` from the error it narrows.
+ *
+ * @param error - The error of an error event: `event.error` in an `onError`.
+ * @returns True for a Failure, with `error` narrowed to `{ reason, detail? }`.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { defineEvent, fail, isFailure, jr2Setup } from "@jr2/orchestrator";
+ *
+ * const retry = defineEvent({ name: "retry", description: "Try the plan again.", input: z.object({}) });
+ *
+ * const attempt = jr2Setup({ actors: { fail: fail() } }).createMachine({
+ *   id: "attempt",
+ *   initial: "stuck",
+ *   states: { stuck: { invoke: { src: "fail", input: { reason: "no plan fits the ticket" } } } },
+ * });
+ *
+ * export const machine = jr2Setup({ events: [retry], actors: { attempt } }).createMachine({
+ *   id: "planner",
+ *   initial: "planning",
+ *   states: {
+ *     planning: {
+ *       invoke: {
+ *         src: "attempt",
+ *         onDone: "planned",
+ *         // A Failure waits for a person; a defect has no route, so it goes up and the run ends `error`.
+ *         onError: { guard: ({ event }) => isFailure(event.error), target: "asking" },
+ *       },
+ *     },
+ *     asking: { invoke: { src: "gate" }, on: { retry: "planning" } },
+ *     planned: { type: "final" },
+ *   },
+ * });
+ * ```
+ *
+ * @see docs/reference/decisions/0073-a-machine-fails-a-run-with-fail-and-an-uncaught-failure-ends-it-failed.md
+ */
+export function isFailure(error: unknown): error is Failure {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (error as { [FAILURE]?: unknown })[FAILURE] === true &&
+    typeof (error as { reason?: unknown }).reason === "string"
+  );
+}
+
+/** The name of the guard that every Chart has (ADR-0070, ADR-0073): {@link isFailure} on the
+ * event's `error`, so a Chart's `onError` can tell a Failure from a defect. It is a predicate and
+ * gives no capability, so it is never lent, as `jr2.sentBy` is not. */
+export const FAILURE_GUARD = "jr2.failure";
+
+/** The implementation of {@link FAILURE_GUARD}: true when the event's `error` is a Failure. */
+export const failureGuard = ({ event }: { event: { error?: unknown } }): boolean => isFailure(event.error);
+
+/** A Failure's payload as plain JSON data: what a failed run's output is, and what `workspace()`
+ * keeps to send it up again. */
+export function failurePayload(error: Failure): FailureInput {
+  return error.detail === undefined ? { reason: error.reason } : { reason: error.reason, detail: error.detail };
+}

package/src/fingerprint.ts

@@ -1,7 +1,8 @@
 // The content address of a Machine's SHAPE (ADR-0030). A persisted snapshot names the Machine it
-// was written under; restore compares and refuses a mismatch, because a workflow is matched to a
-// run by filename alone and the state volume outlives the image that wrote it — so a run parked at
-// a Gate meets whatever `jr2 up` baked in next, and nothing used to notice.
+// was written under; restore compares and refuses a mismatch. A run restores inside the Assembly
+// its snapshot names (ADR-0069), and the same bytes give the same Machine, so inside one Assembly
+// a mismatch means a hash collision or a hand-edited volume. An unstamped blob is still matched to
+// its Machine by workflow name alone, and there the check is the only guard.
 //
 // What it hashes is RESTORABILITY, not behavior: the facts that decide whether an old snapshot can
 // still be interpreted — state ids and nesting, which state is initial, what each state invokes and

package/src/gate.ts

@@ -70,6 +70,14 @@ export const gate = fromCallback<DeliveredEvent, GateInput | undefined>(({ input
     path,
     defs,
     meta: input.meta,
+    // A Gate's caller sends as the Gate's invoke id (ADR-0015): static in the config (authored, or
+    // named by the walk), the same after a restore, and checkable at load — unlike the
+    // caller-facing `id`, which may be computed at run time.
+    sender: { party: "gate", id: self.id },
+    invokeId: self.id,
+    // The Machine that invoked the Gate: the one whose selection says which writing a caller's
+    // event would run (ADR-0029's question, asked for the Gate's caller too).
+    invoker: self._parent,
     deliver: (event) => sendBack(event),
   });
   return dispose;

package/src/git-clone.ts

@@ -0,0 +1,65 @@
+// The clone credentials (ADR-0051, ADR-0068): the token a Repo's cache clone spends. `jr2 up`
+// declares and writes every Secret that holds a git credential; the Orchestrator matches and names,
+// and holds no git credential.
+//
+//   - `jr2 up` writes each `git.credentials` entry's token, read from `.env`, into that entry's
+//     own Secret, `jr2-git-<hash of match>` (`gitTokenSecretName`), in Flux's key names
+//     (`username`/`password`), as it writes the entry's push Secret. An entry whose token variable
+//     is unset gets no Secret. And it writes `git-clone.json` in `jr2-held`: which clone Secrets it
+//     wrote, names only.
+//   - The Orchestrator resolves a Repo's url against `git.credentials` and names the matched
+//     entry's Secret as the Repo CR's `secretRef` when `git-clone.json` says it exists. Otherwise
+//     the CR carries no `secretRef` and the clone is anonymous.
+//   - The operator's cache agent reads the Secret the `secretRef` names, and spends it.
+
+import { readFile } from "node:fs/promises";
+import { gitTokenSecretName, type GitCredential } from "./config.ts";
+
+/** The `jr2-held` key of the clone manifest. */
+export const GIT_CLONE_MANIFEST_KEY = "git-clone.json";
+/** The label every entry's clone Secret carries, so a stale one is found. */
+export const LABEL_GIT_CLONE = "jr2.dev/git-clone";
+
+/** `git-clone.json`: the clone Secrets `jr2 up` wrote, by name. */
+export type GitCloneManifest = { version: 1; secrets: string[] };
+
+/** One entry's clone Secret, as `jr2 up` writes it. */
+export type GitCloneSecret = { match: string; name: string; data: { username: string; password: string } };
+
+/**
+ * Each `git.credentials` entry's clone Secret: the entries with a `token` whose variable is set.
+ * The values are plain strings; the caller encodes them. Two entries never share a name.
+ */
+export function gitCloneSecretsOf(
+  list: readonly GitCredential[],
+  env: (name: string) => string | undefined,
+): GitCloneSecret[] {
+  const out: GitCloneSecret[] = [];
+  for (const entry of list) {
+    if (entry.token === undefined) continue;
+    const value = env(entry.token);
+    if (!value) continue;
+    out.push({
+      match: entry.match,
+      name: gitTokenSecretName(entry.match),
+      data: { username: "x-access-token", password: value },
+    });
+  }
+  return out;
+}
+
+/** The manifest the Orchestrator reads, or an empty one when `jr2 up` wrote no clone Secret. */
+export async function readGitCloneManifest(path: string): Promise<GitCloneManifest> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return { version: 1, secrets: [] };
+    throw err;
+  }
+  const parsed = JSON.parse(raw) as GitCloneManifest;
+  if (parsed.version !== 1 || !Array.isArray(parsed.secrets)) {
+    throw new Error(`${path} is not a clone manifest jr2 reads (version 1)`);
+  }
+  return parsed;
+}

package/src/git-push.ts

@@ -0,0 +1,336 @@
+// The push credentials (ADR-0051, ADR-0067): a `push()` spends the `git.credentials` entry its
+// Repo Slot's url matches — longest prefix, the attach match — and that entry's push credential
+// reaches the pod by reference, placed by the pod's maker when the url is known.
+//
+//   - `jr2 up` writes each entry's push and sign credentials into that entry's own Secret,
+//     `jr2-git-push-<hash of match>`, never per Workspace: Flux's key names where Flux has them
+//     (`username`/`password` for a token, `identity`/`identity.pub`/`known_hosts` for an ssh key),
+//     `sign.identity` or `sign.private.asc` for the signing key, and `entry.json` — what the entry
+//     is, names only. A token is the `.env` value; a key is copied as data from the Secret the entry
+//     names, never decoded. And it writes the manifest `git-push.json` in `jr2-held`: which entries
+//     it wrote and what each can spend, names only.
+//   - At provision the Orchestrator resolves each pushed slot's url against the fence and names the
+//     matched entry's Secret on the Sandbox CR (`gitCredentials`, the Repo CR's `secretRef` shape);
+//     the operator projects it into the Sandbox Effector at `@git/<its name>/`. Static, per-run and
+//     `customize()`-bound urls take this one path, and the Orchestrator reads no value.
+//
+// The refusal is one function for both sides: `jr2 up` for a static Binding, from the entry as
+// written; the provision for any url, from what `jr2 up` wrote.
+
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { matchCredential, type GitCredential } from "./config.ts";
+import { repoIdentity } from "./repo-identity.ts";
+
+/** The `jr2-held` key of the push manifest. */
+export const GIT_PUSH_MANIFEST_KEY = "git-push.json";
+/** The label every entry's push Secret carries, so a stale one is found. */
+export const LABEL_GIT_PUSH = "jr2.dev/git-push";
+
+/** One entry's push Secret: deterministic in `match`, so a redeploy finds its own and two entries
+ * never share one. Apart from the clone token's Secret (`jr2-git-<hash>`), which the Orchestrator
+ * writes for the cache agent. */
+export function gitPushSecretName(match: string): string {
+  return `jr2-git-push-${createHash("sha256").update(match).digest("hex").slice(0, 8)}`;
+}
+
+/** The keys of an entry's push Secret — the operator projects exactly these, each when present. */
+export const GIT_PUSH_KEYS = {
+  entry: "entry.json",
+  username: "username",
+  password: "password",
+  identity: "identity",
+  identityPub: "identity.pub",
+  knownHosts: "known_hosts",
+  signSsh: "sign.identity",
+  signGpg: "sign.private.asc",
+} as const;
+
+export type PushKind = "ssh" | "token";
+
+/** One entry's push Secret as `jr2 up` wrote it: names only. */
+export type GitPushEntry = {
+  match: string;
+  /** Its place in `git.credentials`: a tie on the match's length goes to the first. */
+  order: number;
+  secret: string;
+  /** What it can push with. */
+  push: PushKind[];
+  sign?: "ssh" | "gpg";
+};
+
+/** `git-push.json`: every entry `jr2 up` wrote a push Secret for. */
+export type GitPushManifest = { version: 1; entries: GitPushEntry[] };
+
+/** The push credentials an entry declares: its `push` field alone when it has one; otherwise the
+ * clone credentials it holds, each spent over its own scheme. None: it admits a clone, never a push. */
+export function declaredPushKinds(entry: GitCredential): PushKind[] {
+  if (entry.push) return ["sshKey" in entry.push ? "ssh" : "token"];
+  return [...(entry.sshKey ? (["ssh"] as const) : []), ...(entry.token ? (["token"] as const) : [])];
+}
+
+/** What a push of one url needs from the entry it matches. */
+export type PushNeed = {
+  /** For the message: `workflow "w": push "p" pushes Repo Slot "app" (url)`. */
+  at: string;
+  url: string;
+  sign: boolean;
+  /** It squashes: unsigned, the entry's `committer` makes the commit (ADR-0067). */
+  squash?: boolean;
+};
+
+/**
+ * Why a push of `need.url` cannot be spent, with the fix that works, or undefined. `kinds` says
+ * what an entry can push with — as written (`jr2 up`, `declaredPushKinds`) or as placed (the
+ * provision, the manifest; undefined when `jr2 up` placed nothing for it); `signs` whether it holds
+ * a signing key. Refused: a local path and `git://` (jr2 never pushes there), `http://` (a
+ * credential over cleartext http is the credential in the clear: a token goes over https only and
+ * an ssh key over ssh only), a url no entry matches, an entry whose credentials the url's scheme
+ * cannot spend, `sign: true` on an entry with no `sign` field, and an unsigned squash on an entry
+ * with neither `sign` nor `committer` (ADR-0067: the squashed commit is new, and needs a committer).
+ *
+ * Each fix is one the next check accepts: the match it names is a prefix of the url's identity;
+ * an `http://` url is told the url its entry CAN push to, or the https url and the token to add;
+ * a field it names to add never takes away a credential the entry already pushes with.
+ */
+export function pushRefusal(
+  need: PushNeed,
+  list: readonly GitCredential[],
+  kinds: (entry: GitCredential) => readonly PushKind[] | undefined,
+  signs: (entry: GitCredential) => boolean,
+): { refusal: string } | { entry: GitCredential } {
+  const { at, url } = need;
+  const { scheme, identity } = repoIdentity(url);
+  if (scheme === "local") {
+    return {
+      refusal: `${at}, a local path — jr2 never pushes to one: git's local transport runs that repository's config and hooks (ADR-0067)`,
+    };
+  }
+  if (scheme === "git") {
+    return { refusal: `${at} over git://, which carries no credential — bind the slot over https or ssh (ADR-0051)` };
+  }
+  const entry = matchCredential(identity, list);
+  const held = entry === undefined ? [] : (kinds(entry) ?? []);
+  if (scheme === "http") {
+    const why =
+      `${at} over http://, and jr2 sends a push credential over https or ssh only — a token over http is the ` +
+      "token in the clear, and no ssh key is spent over http";
+    if (entry === undefined) {
+      return {
+        refusal:
+          `${why}; bind the slot to the https url, and add the entry it then spends: ` +
+          `git: { credentials: [{ match: "${matchFor(identity)}", token: "${TOKEN_ENV}" }] } (ADR-0051)`,
+      };
+    }
+    if (held.includes("token")) {
+      return {
+        refusal: `${why}; bind the slot to the https url (git.credentials entry "${entry.match}" then pushes with its token) (ADR-0051)`,
+      };
+    }
+    if (held.includes("ssh")) {
+      return {
+        refusal: `${why}; bind the slot to the ssh url (git.credentials entry "${entry.match}" then pushes with its ssh key) (ADR-0051)`,
+      };
+    }
+    return {
+      refusal:
+        `${why}; bind the slot to the https url, and add ${addLine(entry, "token")} to git.credentials entry ` +
+        `"${entry.match}" — it holds no push credential (ADR-0051)`,
+    };
+  }
+  const want: PushKind = scheme === "ssh" ? "ssh" : "token";
+  if (entry === undefined) {
+    const field = want === "ssh" ? `sshKey: "${SSH_SECRET}"` : `token: "${TOKEN_ENV}"`;
+    return {
+      refusal:
+        `${at}, and no git.credentials entry matches "${identity}" — a push spends the entry its url ` +
+        `matches; add one: git: { credentials: [{ match: "${matchFor(identity)}", ${field} }] } (ADR-0051)`,
+    };
+  }
+  if (!held.includes(want)) {
+    const other: PushKind = want === "ssh" ? "token" : "ssh";
+    const why = `${at}, and git.credentials entry "${entry.match}" holds no credential a push over ${scheme} can spend`;
+    // Its `push` field is the one credential it pushes with, and the field names one: the url that
+    // spends it is the fix, as a second credential there would take the first away.
+    if (entry.push !== undefined && held.includes(other)) {
+      return {
+        refusal:
+          `${why} — its push field names ${other === "ssh" ? "an ssh key" : "a token"}, and a push field names ` +
+          `one credential; bind the slot to ${other === "ssh" ? "the ssh url" : "the https url"} (ADR-0051)`,
+      };
+    }
+    return {
+      refusal:
+        held.length === 0
+          ? `${why} — an entry with none admits a clone, never a push; add ${addLine(entry, want)} to it (ADR-0051)`
+          : `${why}; add ${addLine(entry, want)} to it (ADR-0051)`,
+    };
+  }
+  if (need.sign && !signs(entry)) {
+    return {
+      refusal:
+        `${at} signed, and git.credentials entry "${entry.match}" holds no sign field — add ` +
+        `sign: { sshKey: "<a Secret with identity>", name: "<committer name>", email: "<committer email>" } ` +
+        "to it; the email must belong to the forge account that holds the key (ADR-0051, ADR-0067)",
+    };
+  }
+  if (need.squash && !need.sign && entry.sign === undefined && entry.committer === undefined) {
+    return {
+      refusal:
+        `${at} squashed without sign, and git.credentials entry "${entry.match}" holds neither sign nor committer ` +
+        "— the squashed commit is new and needs a committer; add " +
+        `committer: { name: "<committer name>", email: "<committer email>" } to it, or sign the push — ` +
+        `push({ squash: true, sign: true }) — and add sign: { sshKey: "<a Secret with identity>", ` +
+        `name: "<committer name>", email: "<committer email>" } to it (ADR-0051, ADR-0067)`,
+    };
+  }
+  return { entry };
+}
+
+const TOKEN_ENV = "<the env var that holds the token>";
+const SSH_SECRET = "<a Secret with identity and known_hosts>";
+
+/** The `match` a new entry needs to catch `identity`: its host and every directory above the
+ * repository — always a prefix of the identity (`gitea.local/app` → `gitea.local/`). */
+function matchFor(identity: string): string {
+  return identity.slice(0, identity.lastIndexOf("/") + 1);
+}
+
+/** The field that gives `entry` a push credential of `kind` and keeps each one it pushes with: a
+ * clone credential (`token`, `sshKey`) when it holds one and no `push` field — a clone credential
+ * pushes too, and a `push` field would replace it — else a `push` field. */
+function addLine(entry: GitCredential, kind: PushKind): string {
+  const value = kind === "ssh" ? `sshKey: "${SSH_SECRET}"` : `token: "${TOKEN_ENV}"`;
+  if (entry.push === undefined && (entry.token !== undefined || entry.sshKey !== undefined)) return value;
+  return `push: { ${value} }`;
+}
+
+/** The refusal against the manifest `jr2 up` wrote: what the provision checks for any url. An entry
+ * whose config holds what the push needs, and whose Secret `jr2 up` wrote without it — a token
+ * unset, a key's Secret absent at the last `jr2 up` — is refused as that, never as a field to add. */
+export function placedPushRefusal(
+  need: PushNeed,
+  list: readonly GitCredential[],
+  manifest: GitPushManifest,
+): { refusal: string } | { entry: GitPushEntry } {
+  const placed = (entry: GitCredential) => manifest.entries.find((e) => e.match === entry.match);
+  const out = pushRefusal(
+    need,
+    list,
+    (entry) => placed(entry)?.push,
+    (entry) => placed(entry)?.sign !== undefined,
+  );
+  if (!("refusal" in out)) return { entry: placed(out.entry)! };
+  const written = pushRefusal(need, list, declaredPushKinds, (entry) => entry.sign !== undefined);
+  // An http:// url is never pushed: the url to bind instead is read from the entry as written, so
+  // a token whose variable was unset is named as the entry's, and the https url then says so.
+  if (repoIdentity(need.url).scheme === "http" && "refusal" in written) return written;
+  // As written, would the entry push? Then what is missing is what `jr2 up` could not place.
+  if ("refusal" in written) return out;
+  const entry = written.entry;
+  const what =
+    placed(entry) === undefined
+      ? "no push credential"
+      : need.sign && placed(entry)!.sign === undefined
+        ? "no signing key"
+        : "no credential for this url's scheme";
+  return {
+    refusal:
+      `${need.at}, and jr2 up placed ${what} for git.credentials entry "${entry.match}" — its token's variable was ` +
+      "not set, or a Secret it names did not exist, when jr2 up last ran; set it or create it, and run jr2 up again " +
+      "(ADR-0051)",
+  };
+}
+
+/** One key of an entry's push Secret, and where its value comes from: a token's value, or a key of
+ * the Secret the entry names, copied as data. */
+export type GitPushSource =
+  | { key: string; literal: string }
+  | { key: string; from: { secret: string; key: string }; optional?: boolean };
+
+/** One entry's push Secret, as `jr2 up` plans it before it reads the cluster. */
+export type GitPushPlan = {
+  entry: GitPushEntry;
+  sources: GitPushSource[];
+};
+
+/**
+ * Each `git.credentials` entry's push Secret (ADR-0051): the entries whose declared push credentials
+ * `jr2 up` can place. A token whose variable is unset is left out of its entry, as a kind it
+ * cannot push with; an entry with nothing left is not written. `skipped` says why, by match.
+ */
+export function gitPushPlansOf(
+  list: readonly GitCredential[],
+  env: (name: string) => string | undefined,
+): { plans: GitPushPlan[]; skipped: Map<string, string> } {
+  const plans: GitPushPlan[] = [];
+  const skipped = new Map<string, string>();
+  list.forEach((entry, order) => {
+    const sources: GitPushSource[] = [];
+    const push: PushKind[] = [];
+    const token = entry.push ? ("token" in entry.push ? entry.push.token : undefined) : entry.token;
+    const sshKey = entry.push ? ("sshKey" in entry.push ? entry.push.sshKey : undefined) : entry.sshKey;
+    if (sshKey !== undefined) {
+      push.push("ssh");
+      sources.push(
+        { key: GIT_PUSH_KEYS.identity, from: { secret: sshKey, key: "identity" } },
+        { key: GIT_PUSH_KEYS.identityPub, from: { secret: sshKey, key: "identity.pub" }, optional: true },
+        { key: GIT_PUSH_KEYS.knownHosts, from: { secret: sshKey, key: "known_hosts" } },
+      );
+    }
+    if (token !== undefined) {
+      const value = env(token);
+      if (value) {
+        push.push("token");
+        sources.push(
+          { key: GIT_PUSH_KEYS.username, literal: "x-access-token" },
+          { key: GIT_PUSH_KEYS.password, literal: value },
+        );
+      } else {
+        skipped.set(entry.match, `its token's variable ${token} is not set — set it in .env`);
+      }
+    }
+    if (push.length === 0) return;
+    const sign = entry.sign;
+    if (sign) {
+      sources.push(
+        "gpgKey" in sign
+          ? { key: GIT_PUSH_KEYS.signGpg, from: { secret: sign.gpgKey, key: "private.asc" } }
+          : { key: GIT_PUSH_KEYS.signSsh, from: { secret: sign.sshKey, key: "identity" } },
+      );
+    }
+    const placed: GitPushEntry = {
+      match: entry.match,
+      order,
+      secret: gitPushSecretName(entry.match),
+      push: push.sort(),
+      ...(sign ? { sign: "gpgKey" in sign ? ("gpg" as const) : ("ssh" as const) } : {}),
+    };
+    const entryJson = {
+      match: entry.match,
+      order,
+      push: placed.push,
+      ...(sign ? { sign: { format: placed.sign, name: sign.name, email: sign.email } } : {}),
+      ...(entry.committer ? { committer: { name: entry.committer.name, email: entry.committer.email } } : {}),
+    };
+    sources.unshift({ key: GIT_PUSH_KEYS.entry, literal: JSON.stringify(entryJson) });
+    plans.push({ entry: placed, sources });
+  });
+  return { plans, skipped };
+}
+
+/** The manifest the provision reads, or none when `jr2 up` wrote no push Secret. */
+export async function readGitPushManifest(path: string): Promise<GitPushManifest> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return { version: 1, entries: [] };
+    throw err;
+  }
+  const parsed = JSON.parse(raw) as GitPushManifest;
+  if (parsed.version !== 1 || !Array.isArray(parsed.entries)) {
+    throw new Error(`${path} is not a push manifest jr2 reads (version 1)`);
+  }
+  return parsed;
+}