@jr2/orchestrator 0.5.1 → 0.7.0

package/docs/reference/authoring-surface/workspace.md

@@ -1,11 +1,11 @@
 ---
 title: workspace
-description: "Run a body Machine in a Sandbox: a pod of its own, with a Worktree of each Repo Slot on one branch."
+description: "Run a body Machine in a Sandbox: a pod of its own, with a clone of each Repo Slot."
 ---
 
 # `workspace`
 
-Function, in `@jr2/orchestrator/src/workspace.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Workspaces and Repos.
+Function, in `@jr2/orchestrator/src/workspace.ts`. It is an export of `@jr2/orchestrator`, in the [Workspaces and Repos](group-workspaces-and-repos.md) group of the [Authoring surface](../authoring-surface.md) page.
 
 ## Overload 1
 
@@ -20,30 +20,33 @@ function workspace<
 ): WorkspaceMachine<WithoutEmptyIndex<z.infer<TSchema>>, OutputFrom<TBody>, TBody, TSlots>
 ```
 
-Run a body Machine in a Sandbox: a pod of its own, with a Worktree of each Repo Slot on one
-branch. The result is a Machine. Register it as a Workflow, or invoke it from another Machine as
+Run a body Machine in a Sandbox: a pod of its own, with a clone of each Repo Slot. The result is
+a Machine. Register it as a Workflow, or invoke it from another Machine as
 an actor slot.
 
 When a run enters it, the Workspace makes the Sandbox and waits for room on a node, with no
-deadline. It clones each Repo Slot and makes its Worktree on the `branch` that `spec` gives. Then
-it runs the body with the run input plus `workspace`, the handles (see [`Workspaced`](type-workspaced.md)). The
-Agents with Working tools and the `command` Effects in the body run in that Sandbox. An Agent
+deadline. It clones each Repo Slot to `/work/<slot>/default`, on the Binding's base, and makes no
+Worktree: the body cuts each Worktree that it needs with `worktree()`. A slot that is only read
+needs no cut. No work happens in `default/`. Then it runs the body with the run input plus
+`workspace`, the handles (see [`Workspaced`](type-workspaced.md)). The Agents with Working tools and the `command` Effects in the body run in that Sandbox. An Agent
 with `workspace: "none"` runs on the Instance Harness. When the body reaches a final state, the
-Workspace deletes the Sandbox, and its output is the body's output. Push the branch before
+Workspace deletes the Sandbox, and its output is the body's output. Push each branch before
 then: jr2 deletes the Sandbox's commits with it.
 
+The author chooses how many Agents work in a Workspace. Agents in one Worktree share git, as
+people in one checkout do. Each coder that needs its own branch gets its own Worktree of the one
+clone.
+
 Leave out `repos` for a Workspace with no Repo Slot: its Agents and `command` Effects share
-`/work`, as the steps of one job share a folder, and `spec` is optional and gives only
-`workGroup`. The body's input is then `Workspaced<RunInput, never>`. An `http` Effect sends a
-file of `/work` with `file(path)`. A `push`, and a `command` with an Effect secret in its `env`,
-need a Repo Slot, so jr2 refuses them there. jr2 deletes `/work` with the Sandbox: send what
+`/work`, as the steps of one job share a folder. The body's input is then `Workspaced<RunInput, never>`. An `http` Effect sends a
+file of `/work` with `file(path)`. A `worktree()`, a `push`, and a `command` with an Effect secret in its
+`env`, need a Repo Slot, so jr2 refuses them there. jr2 deletes `/work` with the Sandbox: send what
 must stay before the body ends.
 
 Give each run a different branch, so that two runs do not push to one branch. Make it from a
 field of the run input, or from `instanceId` when the run input has no field that is different
-for each run: ``spec: ({ input }) => ({ branch: `fix/${input.instanceId}` })``. The input of
-`spec` holds `instanceId` with no cast, also for the door `z.object({})`. Only a root
-`workspace()` gets `instanceId` from jr2. A `workspace()` that a different Machine invokes gets
+for each run: ``branch: `fix/${context.instanceId}` `` in the input of the cut. Add
+`HostInjectedInput` to the body's input type to read it. Only a root `workspace()` gets `instanceId` from jr2. A `workspace()` that a different Machine invokes gets
 it only when its parent gives it.
 
 The Sandbox is Lost when its pod is evicted or its node goes. Then the body gets the event
@@ -67,7 +70,7 @@ It refuses, when you call it:
 - a body with its own `input`: ``workspace(): the body "<id>" declares its own run input, which
   nothing will ever serve or enforce — the wrapper feeds the body the run input PLUS the injected
   `workspace` handles, so the body's schema is not the door. Move it to the wrapper:
-  workspace(body, { input, spec }) (ADR-0033).``
+  workspace(body, { input }) (ADR-0033).``
 - an empty `image`: ``workspace(): `image` must be a non-empty string (got <value>) — either a
   `file:` URL to a docker context this module ships (`import.meta.resolve("./image")`) or a
   registry ref (ADR-0037).``
@@ -77,9 +80,7 @@ It refuses, when you call it:
   `repos: { app: "https://…" }` — or `open` whole, for a map the consumer names; leave it out
   for a Workspace with no Repo Slot (ADR-0051).``
 - a bad Repo Slot name or value (see [`RepoSlot`](type-reposlot.md))
-- a `spec` that is not a function, or no `spec` on a Workspace with Repo Slots: ``workspace():
-  `spec` must be a function from the run input to the spec — spec: ({ input }) => ({ branch }) —
-  and only a Workspace with no Repo Slot may leave it out (ADR-0051).``
+- a `workGroup` that is not a gid: ``workspace(): `workGroup` must be a gid (got <value>)``
 - a bad `secrets` list: ``workspace(): `secrets` must be a list of distinct names from
   jr2.config.ts's `secrets` list (got <value>) — secrets: ["JIRA_TOKEN"] (ADR-0059).``
 - a bad `effector`: ``workspace(): `effector` is { image } — a `file:` URL to a docker context
@@ -95,19 +96,16 @@ It refuses, when you call it:
   (ADR-0060)``, or the same text for `resources.limits.<key>`. The other texts are in
   [`Size`](type-size.md).
 
-And when a run enters it, a spec without a `branch` (or with `branch: "default"`), or with a bad
-`reviewSha` or `workGroup`: ``workspace spec invalid: <fields> — the spec derives from run input;
-does `jr2 run --input` carry every field this workflow's workspace() mapping reads?``. With no
-Repo Slot, a spec with a `branch` or a `reviewSha`: ``workspace spec invalid: <field> (the
-Workspace has no Repo Slot, so it has no branch and no review Worktree; its spec gives only
-workGroup) …``
+And when a run enters it, a per-run Repo Slot's mapper that gives no `url`, or a bad `ref`:
+``workspace invalid: repos.<slot> mapper returned <fields> — the mapper derives from run
+input; does `jr2 run --input` carry every field this workflow's workspace() slot reads?``
 
 **Parameters**
 
 - `body`: The Machine to run in the Sandbox. Its input is `Workspaced<RunInput, Slots>`.
 - `options` ([`WorkspaceOptions`](type-workspaceoptions.md) | [`NoSlotWorkspaceOptions`](type-noslotworkspaceoptions.md)): What the Sandbox is made of (`image`, `user`, `resources`, `effector`), the
-  Repo Slots it clones (`repos`), the Held secrets it can use (`secrets`), the run input
-  (`input`), and the function from the run input to the branch (`spec`).
+  Repo Slots it clones (`repos`), the Held secrets it can use (`secrets`), the pod's `fsGroup`
+  (`workGroup`), and the run input (`input`).
 
 **Returns**: A Machine whose input is the run input and whose output is the body's output.
 
@@ -118,8 +116,10 @@ import { z } from "zod";
 import {
   command,
   fail,
+  isReady,
   jr2Setup,
   workspace,
+  worktree,
   type CommandOutput,
   type Workspaced,
 } from "@jr2/orchestrator";
@@ -127,23 +127,36 @@ import {
 const runInput = z.object({ ticket: z.string(), repo: z.string() });
 type BodyInput = Workspaced<z.infer<typeof runInput>, "app" | "docs">;
 
+// The Worktree of this run. An Agent or a command that only reads `docs` uses `/work/docs/default`.
+const buildTree = (context: BodyInput) => `${context.workspace.repos.app}/build` as const;
+
 const passed = (output: CommandOutput): boolean =>
   output.outcome === "exited" && output.code === 0;
 
 const body = jr2Setup({
-  types: {} as { input: BodyInput },
+  types: {} as { input: BodyInput; context: BodyInput },
   actors: {
-    build: command(["npm", "run", "build"], { slot: "app" }),
+    cut: worktree(),
+    build: command(["npm", "run", "build"]),
     fail: fail(),
   },
 }).createMachine({
   id: "build",
+  context: ({ input }) => input,
   on: { "workspace.lost": ".lost" },
-  initial: "building",
+  initial: "cutting",
   states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: buildTree(context), branch: `fix/${context.ticket}` }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "building" }, { target: "notCut" }],
+      },
+    },
     building: {
       invoke: {
         src: "build",
+        input: ({ context }) => ({ worktree: buildTree(context) }),
         onDone: [
           { guard: ({ event }) => passed(event.output), target: "built" },
           { target: "broken" },
@@ -152,6 +165,7 @@ const body = jr2Setup({
     },
     built: { type: "final" },
     broken: { invoke: { src: "fail", input: { reason: "npm run build did not pass" } } },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
   },
 });
@@ -164,7 +178,6 @@ export const machine = workspace(body, {
     app: ({ input }) => input.repo,
     docs: { url: "https://github.com/you/docs.git", ref: "main" },
   },
-  spec: ({ input }) => ({ branch: `fix/${input.ticket}` }),
 });
 ```
 
@@ -175,9 +188,12 @@ import { z } from "zod";
 import {
   command,
   fail,
+  isReady,
   jr2Setup,
   workspace,
+  worktree,
   type CommandOutput,
+  type HostInjectedInput,
   type Workspaced,
 } from "@jr2/orchestrator";
 
@@ -187,18 +203,30 @@ const passed = (output: CommandOutput): boolean =>
 // The run input has no field that is different for each run, so the branch comes from
 // `instanceId`.
 const runInput = z.object({});
+type BodyInput = Workspaced<z.infer<typeof runInput> & HostInjectedInput, "app">;
+
+const nightlyTree = (context: BodyInput) => `${context.workspace.repos.app}/nightly` as const;
 
 const body = jr2Setup({
-  types: {} as { input: Workspaced<z.infer<typeof runInput>, "app"> },
-  actors: { test: command(["npm", "test"], { slot: "app" }), fail: fail() },
+  types: {} as { input: BodyInput; context: BodyInput },
+  actors: { cut: worktree(), test: command(["npm", "test"]), fail: fail() },
 }).createMachine({
   id: "nightly",
+  context: ({ input }) => input,
   on: { "workspace.lost": ".lost" },
-  initial: "testing",
+  initial: "cutting",
   states: {
+    cutting: {
+      invoke: {
+        src: "cut",
+        input: ({ context }) => ({ path: nightlyTree(context), branch: `nightly/${context.instanceId}` }),
+        onDone: [{ guard: ({ event }) => isReady(event.output), target: "testing" }, { target: "notCut" }],
+      },
+    },
     testing: {
       invoke: {
         src: "test",
+        input: ({ context }) => ({ worktree: nightlyTree(context) }),
         onDone: [
           { guard: ({ event }) => passed(event.output), target: "tested" },
           { target: "red" },
@@ -207,6 +235,7 @@ const body = jr2Setup({
     },
     tested: { type: "final" },
     red: { invoke: { src: "fail", input: { reason: "npm test did not pass" } } },
+    notCut: { invoke: { src: "fail", input: { reason: "the Worktree was not cut" } } },
     lost: { invoke: { src: "fail", input: { reason: "the Sandbox is gone" } } },
   },
 });
@@ -215,7 +244,6 @@ export const machine = workspace(body, {
   input: runInput,
   image: "docker.io/library/node:24",
   repos: { app: "https://github.com/you/app.git" },
-  spec: ({ input }) => ({ branch: `fix/${input.instanceId}` }),
 });
 ```
 
@@ -234,10 +262,10 @@ export const machine = workspace(body, {
 function workspace<
   TBody extends AnyStateMachine,
   TSlots extends string = never,
-  TInput = unknown,
+  TInput = DoorlessInput<TBody>,
 >(
   body: TBody & BodyAcceptsSlots<TBody, TSlots>,
-  options: PermissiveWorkspaceOptions<TSlots, TInput> | PermissiveNoSlotWorkspaceOptions<TInput>,
+  options: PermissiveWorkspaceOptions<TSlots, Exclude<TInput, undefined>> | PermissiveNoSlotWorkspaceOptions,
 ): WorkspaceMachine<TInput, OutputFrom<TBody>, TBody, TSlots>
 ```
 
@@ -249,7 +277,7 @@ what it refuses.
 
 - `body`: The Machine to run in the Sandbox. Its input is the input of the Workspace plus
   `workspace`, the handles.
-- `options` ([`PermissiveWorkspaceOptions`](type-permissiveworkspaceoptions.md) | [`PermissiveNoSlotWorkspaceOptions`](type-permissivenoslotworkspaceoptions.md)): The options of the Sandbox, and `spec`. There is no `input`.
+- `options` ([`PermissiveWorkspaceOptions`](type-permissiveworkspaceoptions.md) | [`PermissiveNoSlotWorkspaceOptions`](type-permissivenoslotworkspaceoptions.md)): The options of the Sandbox. There is no `input`.
 
 **Returns**: A Machine whose input is the run input and whose output is the body's output.
 

package/docs/reference/authoring-surface/worktree.md

@@ -0,0 +1,71 @@
+---
+title: worktree
+description: "Make a `worktree` Effect: it cuts a Worktree of a Repo Slot, or reads the one that is there."
+---
+
+# `worktree`
+
+Function, in `@jr2/orchestrator/src/worktree.ts`. It is an export of `@jr2/orchestrator`, in the [Effects](group-effects.md) group of the [Authoring surface](../authoring-surface.md) page.
+
+```ts
+function worktree(options: WorktreeOptions = {}): 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)`.
+
+**Parameters**
+
+- `options` ([`WorktreeOptions`](type-worktreeoptions.md)): 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 [`WorktreeOutput`](type-worktreeoutput.md).
+
+**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 also**
+
+- [Cut a Worktree](../../guides/cut-a-worktree.md)
+- [Workspaces](../../concepts/workspaces.md)
+- [Effects](../../concepts/effects.md)
+- [ADR-0075: A Machine cuts a Worktree, and the Workspace only clones](../decisions/0075-a-machine-cuts-a-worktree-and-the-workspace-only-clones.md)