@jr2/orchestrator 0.5.1 → 0.6.0

package/src/worktree.ts

@@ -0,0 +1,249 @@
+// `worktree()`, the kit Effect that cuts a Worktree, and the
+// path types that carry a body's Repo Slots to every Worktree input.
+//
+// A Worktree is a folder, `/work/<slot>/<name>`. The Workspace clones only; the Machine cuts. The cut
+// runs on the `command` machinery: a kit program (`packages/harness/src/cut.ts`) on the runtime
+// volume, no new wire kind, marked idempotent, so a restore that finds no exec sends it again with
+// the same id. What an Agent's param can cause settles as `refused`, never `onError` (ADR-0067). A
+// settled `ready` row keeps the slot, the path and the branch as fields: a push reads its branch
+// there, because the row's output drops its tail and a name in an input is a Chart's word.
+
+import { z } from "zod";
+import type { Duration, EffectLogic, ExecPortFactory, LaterOutcome, Unknown } from "./effect.ts";
+import { commandWith } from "./effect.ts";
+import { createExecPort } from "./harness-client.ts";
+
+/** What a Worktree's name may start with: neither `.` nor `-`, and not the end of the path. */
+type NameStart =
+  | "a"
+  | "b"
+  | "c"
+  | "d"
+  | "e"
+  | "f"
+  | "g"
+  | "h"
+  | "i"
+  | "j"
+  | "k"
+  | "l"
+  | "m"
+  | "n"
+  | "o"
+  | "p"
+  | "q"
+  | "r"
+  | "s"
+  | "t"
+  | "u"
+  | "v"
+  | "w"
+  | "x"
+  | "y"
+  | "z"
+  | "A"
+  | "B"
+  | "C"
+  | "D"
+  | "E"
+  | "F"
+  | "G"
+  | "H"
+  | "I"
+  | "J"
+  | "K"
+  | "L"
+  | "M"
+  | "N"
+  | "O"
+  | "P"
+  | "Q"
+  | "R"
+  | "S"
+  | "T"
+  | "U"
+  | "V"
+  | "W"
+  | "X"
+  | "Y"
+  | "Z"
+  | "0"
+  | "1"
+  | "2"
+  | "3"
+  | "4"
+  | "5"
+  | "6"
+  | "7"
+  | "8"
+  | "9"
+  | "_";
+
+/** A Worktree of any Repo Slot: what a kit factory states, before `jr2Setup` narrows it to the
+ * slots of the body. */
+export type AnyWorktreePath = `/work/${string}/${string}`;
+/** A Worktree of the Repo Slots `S`. One segment below the slot, that starts with a letter, a
+ * digit or `_`: `${context.workspace.repos.app}/run`. The compiler sees the start of the name; a
+ * `/` further on is the Effect's own refusal. */
+export type WorktreePath<S extends string> = `/work/${S}/${NameStart}${string}`;
+/** A Turn's Frame: a Worktree, or `/work`, stated. `jr2Setup` narrows it to the body's slots. */
+export type AnyFramePath = "/work" | `/work/${string}`;
+/** A Turn's Frame in a Workspace with the Repo Slots `S`. */
+export type FramePath<S extends string> = WorktreePath<S> | "/work";
+
+/** A pick param that names a branch: the rule the cut and the push share, as one JSON-schema
+ * pattern, so that a bad name is refused at the Menu, and the Agent can correct it. */
+export const BRANCH_NAME =
+  /^(?!\/)(?!HEAD$)(?!refs\/)(?!origin\/)(?![0-9a-f]{7,40}$)(?!.*\.\.)(?!.*\/\/)(?!(?:.*\/)?[.-])(?!.*\.lock(?:\/|$))(?!.*[./]$)[A-Za-z0-9._/-]+$/;
+
+/** A kit schema for a pick param that names a branch. For example:
+ * `input: z.object({ branch: branchName })`. */
+export const branchName = z.string().regex(BRANCH_NAME, "a branch name git and jr2's push both take");
+
+/** The input of a `worktree()`: a branch Worktree, or a detached one. */
+export type WorktreeInput =
+  | {
+      /** The root of the Worktree: `${context.workspace.repos.app}/<name>`, a constant word. */
+      path: AnyWorktreePath;
+      /** The branch. It resolves as a local branch, then `origin/<branch>` (tracked), then a new
+       * branch. */
+      branch: string;
+      /** Where a new branch starts. Default: the Binding's base. On a branch that exists, it must
+       * be that branch's tip, or the cut is `refused`. */
+      from?: string;
+      detach?: never;
+      expect?: never;
+    }
+  | {
+      path: AnyWorktreePath;
+      /** The commit to check out, with no branch. The Worktree is forced to it and cleaned on each
+       * cut. Ignored files stay, so that a reviewer can run the tests. */
+      detach: string;
+      branch?: never;
+      from?: never;
+      expect?: never;
+    };
+
+/** What a cut found: `held`, a cut made this Worktree earlier, so what is in it is earlier work;
+ * `local`, a local branch; `remote`, `origin/<branch>`, now tracked; `none`, a new branch with no
+ * upstream; `commit`, a detached cut. Open: a later value does not break an author's code. */
+export type WorktreeFound = "held" | "local" | "remote" | "none" | "commit" | (string & {});
+
+export type WorktreeReady<S extends string = string> = {
+  outcome: "ready";
+  slot: S;
+  path: WorktreePath<S>;
+  /** The branch of the cut, from git and the cut's record, never from the folder or HEAD. `null`
+   * when the Worktree is detached. */
+  branch: string | null;
+  /** The tip of `branch` (of the commit, when detached). Never HEAD. */
+  head: string;
+  found: WorktreeFound;
+  /** ADR-0053's words when the remote did not answer. The cut used what the clone holds. */
+  stale?: string;
+};
+
+/** No Worktree, and nothing changed: a bad path, a name git or the push refuses, a re-cut that does
+ * not agree with the first, a branch that another Worktree holds, an `expect` that does not hold, or a
+ * name that the remote cannot confirm. */
+export type WorktreeRefused = { outcome: "refused"; reason: string };
+
+/** The output of a `worktree()`. `unknown`: its state exited while it ran, or the cut did not end. */
+export type WorktreeOutput<S extends string = string> = WorktreeReady<S> | WorktreeRefused | Unknown | LaterOutcome;
+
+/** Is it `ready`? For a guard. A Chart's form is the guard `jr2.ready`. */
+export const isReady = <O extends { outcome: string }>(output: O): output is Extract<O, { outcome: "ready" }> =>
+  output.outcome === "ready";
+
+/** The `ready` output of an `onDone` arm that `isReady` guards. xstate carries no guard's narrowing
+ * to its actions, so an `assign` reads the output through this. */
+export function readyOf<O extends { outcome: string }>(output: O): Extract<O, { outcome: "ready" }> {
+  if (output.outcome !== "ready") throw new Error("readyOf: the output is not ready: guard the arm with isReady");
+  return output as Extract<O, { outcome: "ready" }>;
+}
+
+/** The options of `worktree()`. */
+export type WorktreeOptions = {
+  /** `"new"`: refuse a branch that exists, local or on the remote. For a name that a planner or a
+   * door chose for new work: a collision is a refusal, not someone else's branch. `"existing"`:
+   * refuse a branch that does not exist, and make nothing. For a run that must continue a branch.
+   * A Chart cannot change it, and a cut lent to a Chart must state it. */
+  expect?: "new" | "existing";
+  /** How long the fetch and the cut can take. Default `"10m"`. */
+  timeout?: Duration;
+};
+
+/** Over an injected port: the seam of the tests. */
+export function worktreeWith(
+  portFactory: ExecPortFactory,
+  options: WorktreeOptions = {},
+): EffectLogic<WorktreeInput, WorktreeOutput> {
+  return commandWith(
+    portFactory,
+    ["/opt/jr2/bin/node", "/opt/jr2/src/cut.ts"],
+    { timeout: options.timeout ?? "10m" },
+    undefined,
+    { ...(options.expect !== undefined ? { expect: options.expect } : {}) },
+  ) as unknown as EffectLogic<WorktreeInput, WorktreeOutput>;
+}
+
+/**
+ * Make a `worktree` Effect: it cuts a Worktree of a Repo Slot, or reads the one that is there. Put it
+ * in `actors`, and invoke it from a `workspace()` body.
+ *
+ * With `{ path, branch, from? }`, the branch resolves in this order, after a fetch: a local branch;
+ * `origin/<branch>`, tracked; a new branch from `from` or the Binding's base, with no upstream. With
+ * `{ path, detach }`, the Worktree is forced to that commit and cleaned, each time. `path` is exactly
+ * `/work/<slot>/<name>`. Each outcome is output: `ready`, `refused`, `unknown`.
+ *
+ * `expect` says if the branch can exist: `worktree({ expect: "new" })` refuses a branch that exists,
+ * and `worktree({ expect: "existing" })` refuses a branch that does not exist. A run cannot change it.
+ *
+ * A cut needs a Repo Slot. Under a Workspace with no Repo Slot, `jr2 up` refuses it, and the invoke
+ * fails with `worktree "<slot>" runs under a Workspace with no Repo Slot: a cut makes a Worktree of a
+ * Repo Slot, and there is none — declare one: repos: { app: "<url>" } (ADR-0075)`.
+ *
+ * @param options - Optional. `expect`, and `timeout`, how long the fetch and the cut can take.
+ *   Default: `"10m"`.
+ * @returns The actor logic of the Effect's slot. Its output is a {@link WorktreeOutput}.
+ *
+ * @example
+ * ```ts
+ * import { fail, isReady, jr2Setup, worktree, type Workspaced } from "@jr2/orchestrator";
+ *
+ * type BodyInput = Workspaced<{ branch: string }, "app">;
+ * const tree = (context: BodyInput) => `${context.workspace.repos.app}/fix` as const;
+ *
+ * export const body = jr2Setup({
+ *   types: {} as { input: BodyInput; context: BodyInput },
+ *   actors: { cut: worktree({ expect: "new" }), fail: fail() },
+ * }).createMachine({
+ *   context: ({ input }) => input,
+ *   on: { "workspace.lost": ".notCut" },
+ *   initial: "cutting",
+ *   states: {
+ *     cutting: {
+ *       invoke: {
+ *         src: "cut",
+ *         input: ({ context }) => ({ path: tree(context), branch: context.branch }),
+ *         // The last arm has no guard: it takes `refused`, `unknown` and each later outcome.
+ *         onDone: [{ guard: ({ event }) => isReady(event.output), target: "done" }, { target: "notCut" }],
+ *       },
+ *     },
+ *     done: { type: "final" },
+ *     notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
+ *   },
+ * });
+ * ```
+ *
+ * @see docs/guides/cut-a-worktree.md
+ * @see docs/concepts/workspaces.md
+ * @see docs/concepts/effects.md
+ * @see docs/reference/decisions/0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md
+ */
+export function worktree(options: WorktreeOptions = {}): EffectLogic<WorktreeInput, WorktreeOutput> {
+  return worktreeWith(
+    (endpoint, bearer) => createExecPort({ baseUrl: endpoint, ...(bearer ? { token: bearer } : {}) }),
+    options,
+  );
+}

package/docs/reference/authoring-surface/type-noslotspec.md

@@ -1,26 +0,0 @@
----
-title: NoSlotSpec
-description: "What the `spec` of a `workspace()` with no Repo Slot returns: only `workGroup`."
----
-
-# `NoSlotSpec`
-
-Type, in `@jr2/orchestrator/src/workspace.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
-
-```ts
-type NoSlotSpec = Pick<WorkspaceSpec, "workGroup"> & { branch?: never; reviewSha?: never };
-```
-
-What the `spec` of a `workspace()` with no Repo Slot returns: only `workGroup`. There is no
-branch and no review Worktree, because the Workspace has no Repo Slot.
-
-**Fields**
-
-- `workGroup` (optional): `number`
-
-  The group id that owns the files in `/work`. With it, the Sandbox Image and the User
-  Container can both write those files when they run as different users. Default: 2000. Set it
-  to a group id that the User Container's sessions already have, for example when a root sshd
-  builds their groups from `/etc/group`. A non-negative integer.
-- `branch` (optional): `never`
-- `reviewSha` (optional): `never`

package/docs/reference/authoring-surface/type-workspacespec.md

@@ -1,37 +0,0 @@
----
-title: WorkspaceSpec
-description: "What the `spec` of a `workspace()` returns: the branch that the Workspace works on, and two optional fields."
----
-
-# `WorkspaceSpec`
-
-Type, in `@jr2/orchestrator/src/workspace.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.
-
-```ts
-type WorkspaceSpec = {
-  branch: string;
-  workGroup?: number;
-  reviewSha?: string;
-};
-```
-
-What the `spec` of a `workspace()` returns: the branch that the Workspace works on, and two
-optional fields. jr2 calls `spec` with the run input when the run enters the Workspace.
-
-**Fields**
-
-- `branch`: `string`
-
-  The branch that the Workspace works on: each Repo Slot gets a Worktree for it, at
-  `/work/<slot>/<branch>`, with each `/` in the branch written as `-`. Required, and not
-  `default`, which is the directory of the clone. Your Machine decides its name.
-- `workGroup` (optional): `number`
-
-  The group id that owns the files in `/work`. With it, the Sandbox Image and the User
-  Container can both write those files when they run as different users. Default: 2000. Set it
-  to a group id that the User Container's sessions already have, for example when a root sshd
-  builds their groups from `/etc/group`. A non-negative integer.
-- `reviewSha` (optional): `string`
-
-  A commit to check out in a second, detached Worktree beside each branch Worktree, for a
-  reviewer: `/work/<slot>/<branch>-review`. The body gets its paths as `workspace.review`.