@jr2/cli 0.4.1 → 0.6.0

package/README.md

@@ -12,8 +12,9 @@ jr2 run <workflow>
 ```
 
 `init` scaffolds an Instance pinned at this CLI's version; `up` converges the target namespace to match it (operator,
-Orchestrator, Sandboxes, secrets), and every other verb (`run`, `runs`, `status`, `logs`, `send`, `down`, `gc`,
-`kit push`) talks to what `up` deployed. Node 24, a kube context, and docker for the image `up` builds.
+Orchestrator, Sandboxes, secrets); `check` runs the typecheck and the Machine walk of `up` with no cluster; and every
+other verb (`run`, `runs`, `status`, `logs`, `send`, `down`, `gc`, `kit push`) talks to what `up` deployed. Node 24, a
+kube context, and docker for the image `up` builds.
 
 Inside an Instance, the global `jr2` hands off to the Instance's own `@jr2/cli` (the gulp model), so the version that
 runs is the one the Instance pins and the global's stops mattering. An Instance has one kit version: `@jr2/cli` and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jr2/cli",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "The jr2 CLI: init, up, run — the interface to a jr2 Instance.",
   "license": "MIT",
   "private": false,
@@ -39,14 +39,14 @@
     "ts-blank-space": "^0.9.0"
   },
   "peerDependencies": {
-    "@jr2/orchestrator": "0.4.1"
+    "@jr2/orchestrator": "0.6.0"
   },
   "devDependencies": {
     "@anthropic-ai/sdk": "0.91.1",
     "@types/node": "^26.0.1",
     "xstate": "^5.18.0",
     "zod": "^4.4.3",
-    "@jr2/orchestrator": "0.4.1"
+    "@jr2/orchestrator": "0.6.0"
   },
   "files": [
     "bin",

package/src/agents-md.ts

@@ -0,0 +1,149 @@
+// The Instance's `AGENTS.md` block (ADR-0072): an Assistant reads `AGENTS.md` on every start, so
+// the index of the docs this Kit version bundles goes there, between two marker lines. `jr2 init`
+// writes the file; `jr2 up` keeps the text between the markers equal to the block of the Kit the
+// Instance resolves, because every upgrade ends in `up`. The block's text is the bundle's
+// (`docs/agents-block.md` in `@jr2/orchestrator`, assembled by `docs:build`), never this module's,
+// so it names its own Kit version and cannot describe another one.
+//
+// The file is the user's. The markers are the whole contract: a folder without them has opted out,
+// so `up` never creates the file or the markers and no config key exists for it; a broken pair is
+// said and left alone, since any repair would guess which half the user meant; and every byte
+// outside the markers survives a rewrite, line endings included. The block takes the line ending
+// of the BEGIN marker's line, so a CRLF checkout compares equal and is not rewritten on every `up`.
+//
+// Builtins only: `init` reads the bundle from the CLI's own peer, which a global `jr2` has before
+// any Instance exists.
+
+import { readFileSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { activity, type Io } from "./output.ts";
+
+export const AGENTS_MD = "AGENTS.md";
+export const BEGIN_MARKER = "<!-- BEGIN:jr2-docs -->";
+export const END_MARKER = "<!-- END:jr2-docs -->";
+
+/** Where the bundle keeps the block, relative to the `@jr2/orchestrator` root. */
+export const AGENTS_BLOCK_PATH = join("docs", "agents-block.md");
+
+/** The `AGENTS.md` that `jr2 init` writes: the line that says who owns the markers, the markers
+ * with `block` between them (empty when init has no bundle to read), and room for the user's own
+ * instructions after the END marker. `templates/default/AGENTS.md` is this with no block. */
+export function scaffoldAgentsMd(block = ""): string {
+  return (
+    "<!-- jr2 up writes the text between the jr2-docs markers. Write your own instructions after the END marker. -->\n" +
+    `${BEGIN_MARKER}\n${block}${END_MARKER}\n`
+  );
+}
+
+/** Claude Code reads `AGENTS.md` only when no `CLAUDE.md` exists, so the scaffold's `CLAUDE.md`
+ * imports it and holds nothing else. */
+export const CLAUDE_MD = "@AGENTS.md\n";
+
+/** The block a Kit at `kitRoot` bundles; `undefined` when it has none (a checkout before
+ * `docs:build`, or a Kit that predates the bundle). */
+export function readAgentsBlock(kitRoot: string): string | undefined {
+  try {
+    return readFileSync(join(kitRoot, AGENTS_BLOCK_PATH), "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+/** Where the block sits in an `AGENTS.md` text: `from` is where the line after BEGIN starts, `to`
+ * where the END line starts, and `eol` the BEGIN line's own line ending. */
+export type BlockPlace =
+  | { kind: "opted-out" }
+  | { kind: "broken"; reason: string }
+  | { kind: "found"; from: number; to: number; eol: string };
+
+type MarkerLine = { marker: typeof BEGIN_MARKER | typeof END_MARKER; start: number; end: number; eol: string };
+
+/** Each line that IS a marker (a CR before its LF included), with where it starts, where the next
+ * line starts, and its own line ending. A marker inside other text on a line is not a marker. */
+function markerLines(text: string): MarkerLine[] {
+  const found: MarkerLine[] = [];
+  let start = 0;
+  while (start < text.length) {
+    const lf = text.indexOf("\n", start);
+    const stop = lf < 0 ? text.length : lf + 1;
+    const raw = text.slice(start, lf < 0 ? text.length : lf);
+    const eol = lf < 0 ? "" : raw.endsWith("\r") ? "\r\n" : "\n";
+    const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+    if (line === BEGIN_MARKER || line === END_MARKER) found.push({ marker: line, start, end: stop, eol });
+    start = stop;
+  }
+  return found;
+}
+
+/** Find the markers in `text`, or say why there is no block to rewrite. */
+export function placeAgentsBlock(text: string): BlockPlace {
+  const lines = markerLines(text);
+  if (lines.length === 0) return { kind: "opted-out" };
+  const begins = lines.filter((l) => l.marker === BEGIN_MARKER);
+  const ends = lines.filter((l) => l.marker === END_MARKER);
+  if (begins.length > 1) return { kind: "broken", reason: `${BEGIN_MARKER} occurs ${begins.length} times` };
+  if (ends.length > 1) return { kind: "broken", reason: `${END_MARKER} occurs ${ends.length} times` };
+  const [begin] = begins;
+  const [end] = ends;
+  if (!begin) return { kind: "broken", reason: `${END_MARKER} has no ${BEGIN_MARKER} before it` };
+  if (!end) return { kind: "broken", reason: `${BEGIN_MARKER} has no ${END_MARKER} after it` };
+  if (end.start < begin.start) return { kind: "broken", reason: `${END_MARKER} comes before ${BEGIN_MARKER}` };
+  return { kind: "found", from: begin.end, to: end.start, eol: begin.eol };
+}
+
+/** What {@link rewriteAgentsBlock} found. Only `updated` carries a text to write. */
+export type BlockRewrite =
+  | Exclude<BlockPlace, { kind: "found" }>
+  | { kind: "current" }
+  | { kind: "updated"; text: string };
+
+/**
+ * Put `block` between the markers of the `AGENTS.md` text `text`. Pure: the caller reads and
+ * writes. `block` is the bundle's, with LF line endings; it is written with the BEGIN line's.
+ */
+export function rewriteAgentsBlock(text: string, block: string): BlockRewrite {
+  const place = placeAgentsBlock(text);
+  if (place.kind !== "found") return place;
+  const wanted = place.eol === "\r\n" ? block.replace(/\r?\n/g, "\r\n") : block;
+  if (text.slice(place.from, place.to) === wanted) return { kind: "current" };
+  return { kind: "updated", text: text.slice(0, place.from) + wanted + text.slice(place.to) };
+}
+
+/**
+ * `jr2 up`'s step: bring the Instance's `AGENTS.md` to the block of the Kit at `kitRoot`, which is
+ * `version`. Says what it did on stderr in at most one line, and nothing when there was nothing to
+ * do. Never throws for the file's content, and never refuses the converge: the block describes the
+ * installed Kit, not the cluster.
+ */
+export async function syncAgentsMd(io: Io, root: string, kitRoot: string, version: string): Promise<void> {
+  // Read and written as latin1, one char per byte, so a byte outside the markers that is not valid
+  // UTF-8 survives too. The markers are ASCII; the block is re-encoded to match.
+  let text: string;
+  try {
+    text = (await readFile(join(root, AGENTS_MD))).toString("latin1");
+  } catch {
+    return; // no AGENTS.md: opted out
+  }
+  // The markers are checked before the bundle is read, so a broken pair is said even by a Kit
+  // with no bundle.
+  const place = placeAgentsBlock(text);
+  if (place.kind === "opted-out") return;
+  if (place.kind === "broken") {
+    activity(io, `warning: AGENTS.md: ${place.reason}, so the jr2 block was not updated`);
+    return;
+  }
+  const block = readAgentsBlock(kitRoot);
+  if (block === undefined) {
+    activity(
+      io,
+      `AGENTS.md: jr2 block not updated: the Kit at ${kitRoot} has no ${AGENTS_BLOCK_PATH} ` +
+        "(a kit checkout makes it with docs:build)",
+    );
+    return;
+  }
+  const rewrite = rewriteAgentsBlock(text, Buffer.from(block, "utf8").toString("latin1"));
+  if (rewrite.kind !== "updated") return;
+  await writeFile(join(root, AGENTS_MD), Buffer.from(rewrite.text, "latin1"));
+  activity(io, `AGENTS.md: jr2 block updated for ${version}`);
+}

package/src/assembly.ts

@@ -13,7 +13,7 @@
 import { lstat, mkdtemp, readdir, readFile, readlink, realpath, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { assemblyHash, discoverModules, KIT_VERSION } from "@jr2/orchestrator";
+import { assemblyHash, discoverModules, KIT_VERSION } from "@jr2/orchestrator/internal";
 import { lockfileInstall, type BuildPort } from "./build.ts";
 
 const ORCHESTRATOR = "@jr2/orchestrator";

package/src/build.ts

@@ -37,7 +37,7 @@ import { cp, readdir, readFile, rm, stat } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
-import { contentHash, KIT_VERSION } from "@jr2/orchestrator";
+import { contentHash, KIT_VERSION } from "@jr2/orchestrator/internal";
 import { LABEL_INSTANCE } from "./deploy.ts";
 
 const exec = promisify(execFile);
@@ -142,6 +142,12 @@ export type BuildPort = {
  * so it must stay hashed — the old shared set excluded it and lied. */
 const KIT_PACKAGE_EXCLUDE = new Set(["node_modules", "dist"]);
 
+/** For the walk of the Orchestrator image's sources: the kit root's `.dockerignore` also drops
+ * `docs` at any depth under each of them (`packages/orchestrator/**\/docs`, …), the docs bundle that
+ * `docs:build` writes into `@jr2/orchestrator` (ADR-0072). The image never reads it, so a local
+ * `docs:build` must move neither the image nor its tag. */
+const KIT_ORCHESTRATOR_EXCLUDE = new Set([...KIT_PACKAGE_EXCLUDE, "docs"]);
+
 /** For the walk of `operator/`: its context is `operator/` itself, governed by
  * `operator/.dockerignore`, an ALLOWLIST (`**` then `!**\/*.go`, go.mod, go.sum). `bin/` (~400 MB
  * of downloaded tooling) and `testbin/` hold no `.go`, and `cover.out` is not one — all three are
@@ -149,9 +155,9 @@ const KIT_PACKAGE_EXCLUDE = new Set(["node_modules", "dist"]);
  * rest of the non-go tree (Makefile, config/, hack/) stays hashed: over-hash, the cheap side. */
 const KIT_OPERATOR_EXCLUDE = new Set(["bin", "testbin", "cover.out"]);
 
-// `contentHash` lives in `@jr2/orchestrator` (ADR-0069): the door recomputes an Assembly's hash
+// `contentHash` lives in `@jr2/orchestrator/internal` (ADR-0069): the door recomputes an Assembly's hash
 // with the same function. Re-exported so every CLI caller keeps its import.
-export { contentHash } from "@jr2/orchestrator";
+export { contentHash } from "@jr2/orchestrator/internal";
 
 // --- ownership: who built this image (ADR-0039) ------------------------------------------------
 
@@ -376,7 +382,7 @@ export const KIT_IMAGES: Record<KitImageName, KitImage> = {
     // this list equals the Orchestrator's `workspace:` dependencies, both asserted in
     // test/orchestrator-image.test.ts.
     sources: ["packages/orchestrator", "packages/agent-protocol", "deploy/orchestrator"],
-    exclude: KIT_PACKAGE_EXCLUDE,
+    exclude: KIT_ORCHESTRATOR_EXCLUDE,
   },
 };
 
@@ -619,9 +625,10 @@ export type NodeSweepPlan = {
  *
  * Aggressive by ADR-0039: nothing RUNS from the host daemon — its images are scratch awaiting
  * delivery — and BuildKit's cache is a separate store `docker rmi` does not touch, so regenerating
- * a swept tag costs seconds. The accepted cost, written down so nobody adds a name filter to
- * "fix" it: a second checkout converging to a different cluster can have its host kit generation
- * swept, because this keep set only sees the current context's roots.
+ * a swept tag costs seconds. Written down so nobody adds a name filter to "fix" it: this keep set
+ * only sees the current context's roots, so a converge to another cluster — a second checkout's,
+ * or this one's — can lose a host tag it built and has not used yet. `jr2 up` rebuilds a tag it
+ * finds missing at its use and retries ({@link isMissingHostImage}).
  */
 export function hostSweepPlan(images: ObservedImage[], keep: Iterable<string>): HostSweepPlan {
   const reachable = keepSet(keep);
@@ -722,6 +729,16 @@ function isAlreadyGone(err: unknown): boolean {
   return /no such image/i.test(err instanceof Error ? err.message : String(err));
 }
 
+/** A host-daemon read or delivery that found no image under its tag, in each verb's own words:
+ * `docker image inspect`, `docker create`, `kind load docker-image`, `docker push`. The one failure
+ * `jr2 up` answers with a rebuild: another converge's sweep can take a tag between this converge's
+ * build (or host-held skip) and its use (ADR-0039). */
+export function isMissingHostImage(err: unknown): boolean {
+  return /no such image|unable to find image .* locally|not present locally|does not exist locally/i.test(
+    err instanceof Error ? err.message : String(err),
+  );
+}
+
 /**
  * Sweep the host daemon: every labeled ref no root names. `keep` is the caller's assembled keep
  * set — the union of the cluster's live roots plus whatever this converge just resolved, which the

package/src/cli.ts

@@ -1,6 +1,9 @@
 // Top-level dispatch (ADR-0009). `argv[0]` is the verb; the rest is handed to that command, which does
-// its own `parseArgs`. `main` returns an exit code (the bin sets `process.exitCode`) and never throws:
-// a command error becomes an `error: …` line on stderr + code 1. Codes: 0 ok, 1 runtime error, 2 usage.
+// its own `parseArgs` against its entry in the command table (`command-table.ts`). Every help prints
+// from that table too: `jr2 --help` the whole of it, `jr2 <verb> --help` (or `-h`) one entry — and
+// then the verb does NOT run, so `jr2 up --help` never converges a cluster. `main` returns an exit
+// code (the bin sets `process.exitCode`) and never throws: a command error becomes an `error: …` line
+// on stderr + code 1. Codes: 0 ok, 1 runtime error, 2 usage.
 
 import { activity, defaultIo, type Io } from "./output.ts";
 import { JR2HttpError } from "./client.ts";
@@ -12,46 +15,12 @@ import { status } from "./commands/status.ts";
 import { logs } from "./commands/logs.ts";
 import { send } from "./commands/send.ts";
 import { up } from "./commands/up.ts";
+import { check } from "./commands/check.ts";
 import { down } from "./commands/down.ts";
 import { gc } from "./commands/gc.ts";
 import { kit } from "./commands/kit.ts";
 import { version } from "./commands/version.ts";
-
-const USAGE = `jr2 — orchestrate agentic workflows (ADR-0009)
-
-usage: jr2 <command> [args]
-
-  version [--local] [--json]        what runs here (this jr2, the global that handed off, the
-                                    Instance's Kit) and what the cluster runs; --local skips the cluster
-  init [dir] [--name <n>]            scaffold a new instance folder
-  up [--yes] [--force]              converge the current kube context to this instance (ADR-0019)
-  down [--all]                      remove the instance from the cluster (--all: operator too)
-  gc [--dry-run] [--repo-ttl 7d]    remove jr2's images that no live instance names (ADR-0039), and
-                                    Repo resources no Machine binds and no run attached lately (ADR-0051)
-  kit push <registry>               mirror the published kit images into a registry (ADR-0044)
-  run <workflow> [--input <json>]   start a run; stream activity, print terminal result
-       [--detach]                   ...or just print the runId and return
-  runs                              list live runs; "placing" names the Workspaces that wait for
-                                    capacity (ADR-0064), and "status <runId>" says why; the
-                                    Workflows and their named Charts on stderr (ADR-0070)
-       [--workflows]                ...or print that listing as the result (see "runs --help")
-  status [runId]                    print a run's current status (read-through),
-         [--json]                   or the instance's Repos, per node, when given none (ADR-0048/0051)
-  logs <runId> [-f]                 replay a run's status; -f to follow until it settles
-  send <runId> --event CANCEL       abandon a live run and destroy its Workspaces
-       [--keep]                     ...or keep them for inspection until the idle timeout
-  send <runId> --gate <gate> --event <name> [--input <json>]
-                                    deliver a workflow event to an open gate
-
-run ids: any <runId> above may be abbreviated to a unique prefix (4+ chars, git-style);
-         an ambiguous prefix lists the candidates and fails rather than guessing
-
-global (run verbs): -n/--namespace <ns>, --context <ctx> address the deployment (ADR-0019);
-                    --url <u> / JR2_URL attaches to a specific orchestrator (skips kube entirely)
-
-output: result verbs (run, runs, status <runId>, send, logs) print one JSON result on stdout and
-        activity on stderr, so \`jr2 run … | jq\` yields the result; report verbs (version, bare
-        status) print a table on stdout, or the one object with --json`;
+import { asksForHelp, commandsFor, GLOBAL, renderCommand, renderHelp } from "./command-table.ts";
 
 /**
  * The catch-all half of skew reporting: a route-shaped failure gets ONE extra line naming what the
@@ -78,6 +47,15 @@ export async function main(argv: string[], io: Io = defaultIo): Promise<number>
     // Before any verb, so the instance's `.env` is in `process.env` by the time a command imports
     // `jr2.config.ts` (whose deployment-varying values are read from there — ADR-0019).
     loadDotenv(io);
+    const entries = cmd === undefined ? [] : commandsFor(cmd);
+    if (entries.length && asksForHelp(entries, rest)) {
+      activity(io, entries.map(renderCommand).join("\n\n"));
+      return 0;
+    }
+    if (cmd !== undefined && (GLOBAL.help as readonly string[]).includes(cmd)) {
+      activity(io, renderHelp());
+      return 0;
+    }
     switch (cmd) {
       case "init":
         return await init(rest, io);
@@ -91,6 +69,8 @@ export async function main(argv: string[], io: Io = defaultIo): Promise<number>
         return await logs(rest, io);
       case "send":
         return await send(rest, io);
+      case "check":
+        return await check(rest, io);
       case "up":
         return await up(rest, io);
       case "down":
@@ -102,17 +82,12 @@ export async function main(argv: string[], io: Io = defaultIo): Promise<number>
       case "version":
       case "--version":
         return await version(rest, io);
-      case "help":
-      case "--help":
-      case "-h":
-        activity(io, USAGE);
-        return 0;
       case undefined:
-        activity(io, USAGE);
+        activity(io, renderHelp());
         return 2;
       default:
         activity(io, `unknown command: ${cmd}`);
-        activity(io, USAGE);
+        activity(io, renderHelp());
         return 2;
     }
   } catch (err) {

package/src/client.ts

@@ -6,7 +6,15 @@
 // `fetchImpl` is injectable so tests drive it with a hono `app.request` (no socket) the same way the
 // orchestrator's own http tests do; in production it defaults to the global `fetch`.
 
-import type { ChildErrorMarker, MachineDoc, PlacingMarker, RepoStatus, RunChild, RunWaiting } from "@jr2/orchestrator";
+import type {
+  ChildErrorMarker,
+  DispatchedBy,
+  MachineDoc,
+  PlacingMarker,
+  RepoStatus,
+  RunChild,
+  RunWaiting,
+} from "@jr2/orchestrator/internal";
 import { parseSSE } from "./sse.ts";
 
 /** A run's current observable state — mirrors the orchestrator's `RunStatus` (run-host.ts). */
@@ -35,6 +43,19 @@ export type RunStatus = {
   bound?: true;
   /** The hashes of the Charts the run binds now, distinct and sorted (ADR-0070). */
   chartHashes?: string[];
+  /** The run that dispatched this one through a `dispatch` Effect, the caller's slot, its ledger
+   * row id (the idempotency key) and this run's depth in the chain (ADR-0071); `instance` names a
+   * foreign caller, as opaque text. Absent for a run nobody dispatched. */
+  dispatchedBy?: DispatchedBy;
+  /** The Machine's output, for a run that is no longer live (ADR-0071): what a `dispatch` with
+   * `wait` settles with. Never for a live run. */
+  output?: unknown;
+  /** The runs this run's `dispatch` Effects started, oldest first: the slot, the run, and when its
+   * ledger row was written (ADR-0071). Absent when it started none. */
+  dispatched?: Array<{ slot: string; run: string; at: string }>;
+  /** The Worktrees this run's cuts made, oldest first: the Repo Slot, the path, and the branch,
+   * `null` when detached (ADR-0075). Absent when it cut none. */
+  worktrees?: Array<{ slot: string; path: string; branch: string | null }>;
 };
 
 /** Where a Workflow came from (ADR-0070): a Machine in the Assembly, a Chart file in the Assembly, or