@jr2/cli 0.3.0 → 0.5.1

package/src/effector-image.ts

@@ -0,0 +1,133 @@
+// What a push owes the author's Effector image (ADR-0068). The Sandbox Effector runs in the
+// author's image — the Sandbox Image by default — and runs jr2's own programs from one fixed PATH
+// (`/usr/local/bin:/usr/bin:/bin`, never the image's own). So, per push form the Workspace holds,
+// `jr2 up` reads the image it built — or, for the stock Harness image, which the kit builds, knows
+// what it holds — and refuses, with the fix, an image that lacks what that form needs:
+//
+//   - ssh transport (`ssh://`, `git@`): `ssh`, and a passwd entry for the uid the Effector runs as —
+//     OpenSSH's client calls `getpwuid(getuid())` before any option, and exits "No user exists for
+//     uid N" without one;
+//   - ssh signing (`sign: { sshKey }`): `ssh-keygen` (`-Y sign` does no passwd lookup);
+//   - GPG signing (`sign: { gpgKey }`): `gpg` and `gpg-agent`;
+//   - a token over https: nothing beyond `git`, the Sandbox Image floor (the helper is jr2's binary).
+//
+// The uid is the image's: its `USER` line by name or number, else 1000 (ADR-0037's fallback).
+// `http` (a Worktree file body included) and the credentialed command owe nothing: the first is
+// Go, the last is the author's argv.
+
+/** Where the Effector looks for jr2's own programs: effector/internal/gitclean's Path. */
+export const EFFECTOR_TOOL_DIRS = ["/usr/local/bin", "/usr/bin", "/bin"] as const;
+
+/** One form a push of a Workspace takes, by what it owes its image. */
+export type PushForm = "ssh-transport" | "ssh-sign" | "gpg-sign";
+
+/** The programs each form needs, by name. */
+const TOOLS: Record<PushForm, readonly string[]> = {
+  "ssh-transport": ["ssh"],
+  "ssh-sign": ["ssh-keygen"],
+  "gpg-sign": ["gpg", "gpg-agent"],
+};
+
+/** What to install, by program: the package name on Debian and on Alpine, where they differ. */
+const PACKAGES: Record<string, string> = {
+  ssh: "openssh-client",
+  "ssh-keygen": "openssh-client (Alpine: openssh-keygen)",
+  gpg: "gnupg",
+  "gpg-agent": "gnupg",
+};
+
+/**
+ * What the stock Harness image holds of the forms' programs, and its /etc/passwd: the fallback
+ * Sandbox Image, which the Sandbox Effector runs in when the Workspace names no image and the
+ * instance has no `images/default`. The kit builds it (deploy/harness/Dockerfile, its last stage:
+ * `node:24-slim` with `git` and `ca-certificates`, `USER 1000`, node's uid), so `jr2 up` knows it in both worlds
+ * without reading it — a published one is never pulled to the host for this. A test holds the
+ * Dockerfile to it.
+ */
+export const STOCK_HARNESS_IMAGE = {
+  present: ["/usr/bin/git"],
+  passwd: "root:x:0:0:root:/root:/bin/bash\nnode:x:1000:1000::/home/node:/bin/bash\n",
+  user: "1000",
+} as const;
+
+/** Every path the forms' programs may be at: each program in each of the Effector's tool dirs. */
+export function effectorImagePaths(forms: readonly PushForm[]): string[] {
+  const out: string[] = [];
+  for (const form of new Set(forms)) {
+    for (const tool of TOOLS[form]) for (const dir of EFFECTOR_TOOL_DIRS) out.push(`${dir}/${tool}`);
+  }
+  return out;
+}
+
+/** The uid the Effector runs as, from the image's recorded `USER`: a name, a number, or — none
+ * declared — ADR-0037's 1000. A `user:group` line decides by its user half. */
+export function effectorSeat(user: string): { name: string } | { uid: number } {
+  const head = user.split(":")[0]!.trim();
+  if (head === "") return { uid: 1000 };
+  if (/^\d+$/.test(head)) return { uid: Number(head) };
+  return { name: head };
+}
+
+/** Whether /etc/passwd's text holds an entry for the seat. */
+export function passwdHolds(passwd: string, seat: { name: string } | { uid: number }): boolean {
+  for (const line of passwd.split("\n")) {
+    const fields = line.split(":");
+    if (fields.length < 3) continue;
+    if ("name" in seat ? fields[0] === seat.name : fields[2] === String(seat.uid)) return true;
+  }
+  return false;
+}
+
+/**
+ * Why the image cannot run the forms, with the fix, or undefined. `present` is which of
+ * {@link effectorImagePaths} the image holds (links followed); `passwd` its `/etc/passwd`, "" when
+ * it has none; `user` its recorded `USER`.
+ */
+export function effectorImageRefusal(input: {
+  /** For the message: `Workspace of workflow "w"`. */
+  label: string;
+  ref: string;
+  user: string;
+  /** Each form, and the push it is for: `the push of Repo Slot "app"`. */
+  forms: ReadonlyArray<{ form: PushForm; push: string }>;
+  present: ReadonlySet<string>;
+  passwd: string;
+  /** The image is the stock Harness image: the fix is an image of the author's, not an install. */
+  stock?: boolean;
+}): string | undefined {
+  const { label, ref } = input;
+  for (const { form, push } of input.forms) {
+    for (const tool of TOOLS[form]) {
+      if (EFFECTOR_TOOL_DIRS.some((dir) => input.present.has(`${dir}/${tool}`))) continue;
+      const why =
+        form === "ssh-transport" ? "over ssh" : form === "ssh-sign" ? "signed with an ssh key" : "signed with GPG";
+      if (input.stock) {
+        return (
+          `${label}: ${push} ${why} needs ${tool}, and its Sandbox Effector runs in the stock Harness image ${ref}, ` +
+          `which holds git alone — the Workspace names no image and the instance has no images/default; give it an ` +
+          `image that holds ${tool} (${PACKAGES[tool]}): an images/default Sandbox Image, the workspace()'s image, ` +
+          `or its effector: { image } (ADR-0068)`
+        );
+      }
+      return (
+        `${label}: ${push} ${why} needs ${tool}, and its Sandbox Effector's image ${ref} holds none in ` +
+        `${EFFECTOR_TOOL_DIRS.join(", ")} — the Effector runs jr2's programs from there alone; install it in the ` +
+        `image (${PACKAGES[tool]}) (ADR-0068)`
+      );
+    }
+    if (form !== "ssh-transport") continue;
+    const seat = effectorSeat(input.user);
+    if (passwdHolds(input.passwd, seat)) continue;
+    const who = "name" in seat ? `user ${seat.name}` : `uid ${seat.uid}`;
+    const fix =
+      "name" in seat
+        ? `a USER line naming a user the image's /etc/passwd holds`
+        : `RUN adduser -D -u ${seat.uid} <name> in the image` +
+          (input.user === "" ? " (the image declares no USER, so the Effector runs as uid 1000)" : "");
+    return (
+      `${label}: ${push} over ssh needs a passwd entry for the ${who} the Sandbox Effector runs as, and its image ` +
+      `${ref} has none — ssh exits "No user exists for uid" before it connects; add ${fix} (ADR-0068)`
+    );
+  }
+  return undefined;
+}

package/src/index.ts

@@ -14,3 +14,29 @@ export type { KubePort } from "./kube.ts";
 // test can issue its own fixtures the same way (the @kind tier's HTTPS model provider).
 export { issueCa, issueLeaf } from "./held-pki.ts";
 export type { Pem } from "./held-pki.ts";
+// The command table (ADR-0072): every verb as data, and the renderers `--help` prints with — what the
+// docs' CLI Reference is generated from, so the help and the site cannot disagree.
+export {
+  COMMANDS,
+  GLOBAL,
+  GLOBAL_OPTIONS,
+  HELP_FLAG,
+  SECTIONS,
+  EXIT_CODES,
+  nameOf,
+  synopsis,
+  renderHelp,
+  renderCommand,
+} from "./command-table.ts";
+export type {
+  Command,
+  CommandName,
+  Flag,
+  Arg,
+  EnvVar,
+  Form,
+  Output,
+  OutputKind,
+  GlobalOption,
+  Section,
+} from "./command-table.ts";

package/src/instance-check.ts

@@ -0,0 +1,309 @@
+// The Instance check (ADR-0050): the typecheck and the Machine walk, which `jr2 up` and `jr2 check`
+// both run through this one function, so the two commands cannot give different answers. It reads
+// the Instance folder alone: no kube context, no cluster, no docker, no install. Each refusal is an
+// `activity` line that starts with `refusing:`, and the function then returns `undefined`. A module
+// that throws when it loads (a refusal of `createMachine`, `defineEvent` or `workspace()`) throws
+// out of `loadWorkflows`, and the CLI's dispatch prints it as one `error:` line, for each command.
+//
+// The order is the order of `jr2 up`: the compiler first, because a wrong name is a type error since
+// ADR-0049; then the walk, which holds the refusals that the compiler cannot make (an Open part, a
+// Chart file, a dispatch, an Effect secret, a Size). The Assembly is not staged here: staging installs
+// the Instance's production dependencies from its lockfile, and its refusals are about that install,
+// so they stay with `jr2 up`.
+
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  chartFileRefusals,
+  CUSTOM_PROVIDER_APIS,
+  dispatchRefusals,
+  doorRefusals,
+  loadCharts,
+  loadWorkflows,
+  machineBodies,
+  openPartRefusals,
+  partsOf,
+  placementWalkOf,
+  refuseEffectSecrets,
+  resolveSize,
+  seatLine,
+  serializeMachine,
+  splitSize,
+  targetText,
+  type JR2Config,
+  type PlacementWalk,
+  type ResolvedSize,
+} from "@jr2/orchestrator/internal";
+import { activity, type Io } from "./output.ts";
+import { tscTypecheck } from "./typecheck.ts";
+
+/** What the walk found, for the layers of `jr2 up` that come after it. */
+export type CheckedInstance = {
+  /** The registered Workflows, loaded as the Orchestrator loads them. */
+  workflows: Awaited<ReturnType<typeof loadWorkflows>>;
+  /** The parts that the registered Machines carry. */
+  carried: ReturnType<typeof partsOf>;
+  /** The placement walk: what names each secret, and where each Harness pod goes. */
+  placementWalk: PlacementWalk;
+  /** The Size of each `workspace()`, resolved and split as the provision does it. */
+  sizes: Array<{ workflow: string; size: ResolvedSize }>;
+  /** The Chart files under `workflows/`, as `<wrapper>/<name>`. */
+  chartFiles: string[];
+};
+
+/**
+ * Run the typecheck and the Machine walk of the Instance at `root`. Returns what the walk found, or
+ * `undefined` after a `refusing:` line. A module that fails to load throws.
+ */
+export async function checkInstance(io: Io, root: string, config: JR2Config): Promise<CheckedInstance | undefined> {
+  // --- typecheck (ADR-0050): the compiler agrees the folder is coherent, before anything is spent -
+  // A REFUSAL, not a warning. `jr2 up` runs it before the namespace apply and before the builds:
+  // the names a Machine carries (an Agent slot, a composed Machine, a Repo Slot, a `customize()` of
+  // any of them) are typed since ADR-0049/0051, so the answer here is the same answer the author's
+  // editor gives — and a converge that shipped a Machine the compiler rejects would surface it as
+  // an invoke-time failure mid-run, minutes and three image builds later.
+  activity(io, "typecheck: tsc --noEmit (the instance's own compiler)");
+  const checked = await (io.typecheck ?? tscTypecheck)(root);
+  if (!checked.ok) {
+    activity(io, "refusing: this instance does not typecheck — nothing was built and nothing was applied");
+    for (const line of checked.output.split("\n")) activity(io, `  ${line}`);
+    return undefined;
+  }
+  // A custom provider's wire protocol, from the Harness's own list (`CUSTOM_PROVIDER_APIS`): the
+  // Harness refuses any other at boot, and a check pod would only crash on it (ADR-0018).
+  const api = config.harness?.provider?.api;
+  if (api !== undefined && !CUSTOM_PROVIDER_APIS.includes(api)) {
+    activity(
+      io,
+      `refusing: harness.provider.api is "${api}" — the Harness speaks: ${CUSTOM_PROVIDER_APIS.join(", ")} (ADR-0018)`,
+    );
+    return undefined;
+  }
+
+  // --- the Machine walk (ADR-0049, ADR-0051) -----------------------------------------------------
+  // A Machine carries its parts, so the check LOADS the instance's registered Workflows — the
+  // same discovery and module contract the Orchestrator boots with — and walks them. The walk
+  // returns what `jr2 up` uses after the check: the Agent definitions whose models are preflighted
+  // (ADR-0018), any `workspace: "none"`, for which `jr2 up` converges the Instance Harness
+  // (ADR-0031), every `file:` docker context a `workspace()` names, which `jr2 up` builds
+  // (ADR-0037), every bound Repo, whose ssh key `jr2 up` asks for and whose resource the
+  // Orchestrator creates at boot (ADR-0051), and whether any Machine composes a Sandbox at all —
+  // the data-plane switch. The walk comes right after the gate, and `jr2 up` runs the check before
+  // ownership, because the walk holds REFUSALS the compiler cannot make: a part left Open on a
+  // registered Machine — a Repo Slot with no url, an Agent with no model (ADR-0054) — and a zod
+  // `input` on a Machine that `jr2Setup` did not make, which no door reads (ADR-0033). Nothing
+  // about Agents is published, because the definition rides each Turn.
+  const workflows = await loadWorkflows(root);
+  const carried = partsOf(workflows.map((w) => w.machine));
+  const { agents } = carried;
+  // The Machine is named by where it sits under the registered root — the slot chain a
+  // `customize()` walks — and the fix line nests the same way, so it pastes into
+  // `workflows/<name>.ts` with the imported Machine and the url filled in.
+  // Every Open part is refused in ONE listing, in walk order within each kind: a composer fixing a
+  // packaged Machine fixes all of them in the same edit, and a converge that refused the Repo Slot,
+  // then the Agent one run later, would cost them two rounds to learn one thing. The listing is the
+  // door's own (ADR-0069): the Orchestrator refuses a publish with the same lines, so the host walk
+  // and the door's walk cannot drift.
+  // A zod `input` that no door reads (ADR-0033) is in the same listing, first: the door refuses it
+  // with the same line.
+  const open = [...doorRefusals(workflows), ...openPartRefusals(workflows)];
+  if (open.length) {
+    for (const line of open) activity(io, `refusing: ${line}`);
+    return undefined;
+  }
+  // Each Chart file is admitted HERE by the door's own check (ADR-0070), so a Chart file the
+  // Orchestrator would refuse is refused at the same command as `tsc`'s errors, before any
+  // cluster work, with the lines the publish would answer.
+  const charts = await loadCharts(root, workflows, (line) => activity(io, `warning: ${line}`));
+  const chartRefusals = chartFileRefusals(charts, workflows);
+  if (chartRefusals.length) {
+    for (const line of chartRefusals) activity(io, `refusing: ${line}`);
+    return undefined;
+  }
+  // What each same-Instance dispatch names resolves in this Assembly, and its slot schema matches
+  // the callee's door (ADR-0071): the door's own check, so the publish would refuse the same lines.
+  // The host cannot see the Orchestrator's volume, so a named Chart that is no Chart file here is a
+  // warning, which the door decides.
+  const dispatched = dispatchRefusals(workflows, charts);
+  for (const line of dispatched.warnings) activity(io, `warning: ${line}`);
+  if (dispatched.errors.length) {
+    for (const line of dispatched.errors) activity(io, `refusing: ${line}`);
+    return undefined;
+  }
+  // What each registered Machine runs outside itself (ADR-0067, ADR-0068): every Effect slot, with
+  // the plain data it carries — a command's argv, its timeout, the Repo Slot it runs in; an http
+  // Effect's method, its fixed target and the secrets it names — read, never run.
+  for (const w of workflows) {
+    const effects = partsOf([w.machine]).effects;
+    if (!effects.length) continue;
+    activity(io, `effects: workflow "${w.name}" — what it runs outside itself (ADR-0067)`);
+    for (const e of effects) {
+      const where = e.path?.length ? ` (on ${e.path.map((k) => `"${k}"`).join(" → ")})` : "";
+      const slot = "slot" in e && e.slot !== undefined ? `, in Repo Slot "${e.slot}"` : "";
+      if (e.kind === "http") {
+        const names = e.secrets.length ? `, secrets ${e.secrets.map((n) => `"${n}"`).join(", ")}` : "";
+        // Its body decides where it runs (ADR-0067): a Worktree file needs its Workspace's Sandbox Effector.
+        const where2 = e.file
+          ? `in the Sandbox Effector, a Worktree file as its body${slot}`
+          : "in the Instance Effector";
+        activity(
+          io,
+          `  ${e.name}${where}: http ${e.method} ${e.target ? targetText({ target: e.target }) : "<open>"} — ${e.timeoutMs / 1000}s, ` +
+            `${where2}${names}${e.idempotent ? ", idempotent" : ""}`,
+        );
+        continue;
+      }
+      if (e.kind === "dispatch") {
+        // Where it runs is read from the target (ADR-0071): none is this Orchestrator, in-process.
+        const to = e.target ? targetText({ target: e.target }) : e.open ? "<open>" : "this Orchestrator";
+        const names = e.secrets.length ? `, token ${e.secrets.map((n) => `"${n}"`).join(", ")}` : "";
+        const where2 = e.placement === "instance" ? "in the Instance Effector" : "in the Orchestrator's own process";
+        activity(
+          io,
+          `  ${e.name}${where}: dispatch ${e.workflow}${e.wait ? " wait" : ""} → ${to} — ${e.timeoutMs / 1000}s, ` +
+            `${where2}${names}`,
+        );
+        continue;
+      }
+      if (e.kind === "push") {
+        const opts = (["pin", "sign", "squash", "force"] as const).filter((k) => e[k]);
+        activity(
+          io,
+          `  ${e.name}${where}: push${opts.length ? ` (${opts.join(", ")})` : ""} — ${e.timeoutMs / 1000}s, ` +
+            `in the Sandbox Effector${slot}`,
+        );
+        continue;
+      }
+      if (!("argv" in e)) continue;
+      const names = e.secrets?.length ? `, secrets ${e.secrets.map((n) => `"${n}"`).join(", ")}` : "";
+      const seat = e.secrets?.length ? `the Sandbox Effector${e.pin ? ", pinned" : ""}` : "the Harness";
+      activity(
+        io,
+        `  ${e.name}${where}: ${e.kind} ${JSON.stringify(e.argv)} — ${e.timeoutMs / 1000}s, in ${seat}${slot}${names}`,
+      );
+    }
+  }
+  // Each state that can fail the run (ADR-0073): every state that invokes a `fail()` slot, in the
+  // registered Machine and in each Machine it composes, read, never run — so an author sees which
+  // ends of a Workflow are `failed` and not `done` before a run.
+  for (const w of workflows) {
+    const failures = partsOf([w.machine]).failures;
+    if (!failures.length) continue;
+    activity(io, `failures: workflow "${w.name}" — the states that fail the run (ADR-0073)`);
+    for (const f of failures) {
+      const where = f.path?.length ? ` (on ${f.path.map((k) => `"${k}"`).join(" → ")})` : "";
+      activity(io, `  ${f.state}${where}: invokes ${f.slot}`);
+    }
+  }
+  // An Effect that names a secret the `secrets` list does not hold, and a literal Effect secret too
+  // short to scrub (ADR-0068), are refused HERE, off the walk and the config alone — before anything is
+  // built or applied (ADR-0050, ADR-0068). `jr2 up` places a secret read from the user's Secret
+  // after the check, once it reaches the cluster.
+  // What names each secret, read off the walk (ADR-0059, ADR-0068): every Effect, every Workspace's
+  // pod — its `workspace()`'s `secrets` and the models of the Agents whose Turns run there — and the
+  // models of the `"none"` Agents the Instance Harness hosts.
+  // An Open body that allows "none" needs the Instance Harness, holding a key for each model it
+  // allows (ADR-0070), as a "none" Agent does. The door's walk says both, so `jr2 up` and the
+  // publish door place the same set.
+  const placementWalk = placementWalkOf(workflows);
+  refuseEffectSecrets(config, placementWalk);
+  // Who may send what, per state (ADR-0015): the audience rule's answer for each registered
+  // Machine and every Machine it composes, as its doc carries it — so an author reads who holds a
+  // pick before a run finds out. Then what the build found legal and suspect: a warning, never a
+  // refusal (the refusals threw when the Machine loaded).
+  for (const w of workflows) {
+    const bodies = machineBodies(serializeMachine(w.name, w.machine));
+    const seats = bodies.flatMap((body) => body.seats.map(seatLine));
+    if (seats.length) {
+      activity(io, `seats: workflow "${w.name}" — who may send what, per state (ADR-0015)`);
+      for (const line of seats) activity(io, `  ${line}`);
+    }
+    for (const body of bodies) {
+      for (const warning of body.warnings) activity(io, `warning: workflow "${w.name}": ${warning}  (ADR-0015)`);
+    }
+  }
+  // The Size (ADR-0060): every `workspace()` a registered Machine composes, resolved down its chain
+  // (the Machine's, then `sandbox.resources`, then the kit's) and split inside the pod, exactly as
+  // the provision will. A split that leaves the Harness below its floor is refused HERE, naming the
+  // Machine and the number to change, rather than at the first provision of a run. The check
+  // returns the resolved Sizes, and `jr2 up` uses them for its Sandbox-node warning.
+  const sizes: Array<{ workflow: string; size: ResolvedSize }> = [];
+  for (const w of workflows) {
+    for (const { path, resources, user } of partsOf([w.machine]).sizes) {
+      try {
+        const size = resolveSize(resources, config.sandbox?.resources);
+        splitSize(size, user);
+        sizes.push({ workflow: w.name, size });
+      } catch (e) {
+        const where =
+          path !== undefined && path.length
+            ? ` (on the Machine composed as ${path.map((k) => `"${k}"`).join(" → ")})`
+            : "";
+        const fix =
+          path === undefined
+            ? ""
+            : `; a composer retunes it where the Machine is registered: export const machine = ${sizeLine(path)}`;
+        activity(io, `refusing: workflow "${w.name}"${where}: ${(e as Error).message}${fix}`);
+        return undefined;
+      }
+    }
+  }
+  const agentNames = [...new Set(agents.map((a) => a.name))].join(", ") || "(none)";
+  activity(io, `agents: ${agentNames} (carried by ${workflows.length} workflow machine(s))`);
+  // Each Chart wrapper (ADR-0070): what its Open body lends a Chart, how many models a Chart's own
+  // Agents may name (`jr2 up` places a key for each), and the Chart files the Assembly carries for
+  // it. The walk reads the Open body's declaration, so the keys and the Instance Harness a Chart
+  // could need are placed before any run.
+  const chartFiles = await chartFilesIn(root);
+  for (const w of workflows) {
+    const bodies = partsOf([w.machine]).openBodies.filter((b) => b.path !== undefined && b.path.length === 0);
+    if (!bodies.length) continue;
+    const lends = [
+      ...new Set(
+        bodies.flatMap(({ declaration: { lends } }) => [
+          ...(lends.agents ?? []),
+          ...(lends.effects ?? []),
+          ...(lends.machines ?? []),
+          ...(lends.guards ?? []),
+          ...(lends.actions ?? []),
+          ...(lends.delays ?? []),
+        ]),
+      ),
+    ];
+    const models = new Set(bodies.flatMap((b) => b.declaration.allows.models));
+    const files = chartFiles.filter((n) => n.startsWith(`${w.name}/`)).length;
+    activity(
+      io,
+      `chart wrapper "${w.name}": lends ${lends.join(", ") || "nothing"}; allows ${models.size} model(s); ${files} Chart file(s)`,
+    );
+  }
+  return { workflows, carried, placementWalk, sizes, chartFiles };
+}
+
+/**
+ * The `customize` line that retunes a composed Machine's Size (ADR-0060), nested through `actors`
+ * the way `customize()` accepts — the Size twin of `customizeLine`, so the refusal pastes.
+ */
+function sizeLine(path: readonly string[]): string {
+  const binds = '{ resources: { limits: { memory: "<memory>" } } }';
+  return `customize(<import>, ${path.reduceRight((parts, key) => `{ actors: { ${key}: ${parts} } }`, binds)})`;
+}
+
+/**
+ * The Chart files under an Assembly root (ADR-0070), as Workflow names `<wrapper>/<name>`: each
+ * `workflows/<wrapper>/<name>.chart.json`, one level below the flat `workflows/*.ts`, in a directory
+ * named after its wrapper. The layout the Orchestrator's discovery reads (charts.ts); a directory
+ * whose name starts with `_` or `.` is not a wrapper's.
+ */
+export async function chartFilesIn(root: string): Promise<string[]> {
+  const out: string[] = [];
+  const dir = join(root, "workflows");
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith("_") || entry.name.startsWith(".")) continue;
+    const files = await readdir(join(dir, entry.name)).catch(() => [] as string[]);
+    for (const f of files)
+      if (f.endsWith(".chart.json")) out.push(`${entry.name}/${f.slice(0, -".chart.json".length)}`);
+  }
+  return out.sort();
+}

package/src/instance.ts

@@ -14,7 +14,7 @@
 //   - Every resolution prints its target on stderr, so ambient-context drift stays visible.
 
 import { basename } from "node:path";
-import { loadConfig } from "@jr2/orchestrator";
+import { loadConfig } from "@jr2/orchestrator/internal";
 import { INSTANCE_SECRET, kubectlKube, ORCHESTRATOR_PORT, ORCHESTRATOR_SERVICE } from "./kube.ts";
 import { assertKitVersion } from "./kit-version.ts";
 import { activity, type Io } from "./output.ts";
@@ -43,14 +43,8 @@ export type TargetOptions = {
   context?: string;
 };
 
-/** The parseArgs options every run-verb shares — how a target is addressed (ADR-0019). */
-export const TARGET_ARGS = {
-  url: { type: "string" },
-  namespace: { type: "string", short: "n" },
-  context: { type: "string" },
-} as const;
-
-/** Pull the target-addressing flags out of a strict:false parseArgs `values` bag. */
+/** Pull the target-addressing flags (the command table's shared `-n`, `--context`, `--url`) out of
+ * a strict:false parseArgs `values` bag. */
 export function targetOptions(values: Record<string, unknown>): TargetOptions {
   return {
     url: values.url as string | undefined,

package/src/kit-version.ts

@@ -4,9 +4,13 @@
 // one, the bundle baked the other, and the CLI's own code handled config objects built by a
 // different copy of the same classes. Now the orchestrator is the CLI's PEER (one copy can exist),
 // and every Instance verb asks this module whether the copy the CLI resolves IS the copy the
-// Instance resolves: same REAL path, never a version compare. Same file means same version by
-// construction under npm hoisting, pnpm dedup, and checkout symlinks alike — and identity is
-// exactly the property the class-identity bug needs.
+// Instance resolves: same REAL path. Same file means same version by construction under npm
+// hoisting, pnpm dedup, and checkout symlinks alike — and identity is exactly the property the
+// class-identity bug needs. One copy is not yet one Kit version: an Instance that pins only
+// `@jr2/orchestrator` at a new number gets a warning from npm (`ERESOLVE overriding peer
+// dependency`), not an error, because the root's own pin wins over a peer, and the one hoisted
+// copy is then the CLI's peer too. So the check also asks that copy's version to be the CLI's own:
+// one release train (ADR-0055) carries one number.
 //
 // Builtins only: the launcher (`bin/jr2.js`) resolves through here before any kit import.
 
@@ -59,11 +63,17 @@ export const CLI_VERSION = (JSON.parse(readFileSync(join(CLI_ROOT, "package.json
 const ORCHESTRATOR = "@jr2/orchestrator";
 const CLI = "@jr2/cli";
 
+/** The CLI a check is for: this one, unless a test names another copy. */
+export type CliCopy = { root: string; version: string };
+
+const THIS_CLI: CliCopy = { root: CLI_ROOT, version: CLI_VERSION };
+
 /**
  * The ADR-0056 question, answered rather than asserted: what the Instance at `root` resolves
- * `@jr2/orchestrator` to, what this CLI resolves it to, and whether they are one copy. `ok` is the
- * real-path identity, never a version compare. `jr2 version` prints this; every other Instance verb
- * goes through {@link assertKitVersion}, which turns a not-ok answer into the refusal.
+ * `@jr2/orchestrator` to, what this CLI resolves it to, and whether they are one copy at the CLI's
+ * own version. `ok` is the real-path identity AND that version. `jr2 version` prints this; every
+ * other Instance verb goes through {@link assertKitVersion}, which turns a not-ok answer into the
+ * refusal.
  */
 export type KitCheck = {
   /** The Instance's own resolution — its Kit version; absent when nothing resolves from `root`. */
@@ -76,14 +86,14 @@ export type KitCheck = {
   ok: boolean;
 };
 
-export function checkKitVersion(root: string): KitCheck {
+export function checkKitVersion(root: string, cli: CliCopy = THIS_CLI): KitCheck {
   const instance = resolvePackage(ORCHESTRATOR, root);
-  const own = resolvePackage(ORCHESTRATOR, CLI_ROOT);
+  const own = resolvePackage(ORCHESTRATOR, cli.root);
   return {
     instance,
     own,
     pinned: pinnedVersion(root, ORCHESTRATOR),
-    ok: instance !== undefined && own !== undefined && instance.root === own.root,
+    ok: instance !== undefined && own !== undefined && instance.root === own.root && own.version === cli.version,
   };
 }
 
@@ -106,13 +116,13 @@ export function pinnedVersion(root: string, name: string): string | undefined {
 }
 
 /**
- * Refuse unless the Instance at `root` and this CLI resolve the SAME `@jr2/orchestrator`. The
- * message names both versions and the lines to edit: an Instance with no `@jr2/cli` of its own is
- * told to add one (the launcher then hands off to it); one that has it is told to pin both lines
- * at one number.
+ * Refuse unless the Instance at `root` and this CLI resolve the SAME `@jr2/orchestrator`, at the
+ * CLI's own version. The message names the versions and the lines to edit: an Instance with no
+ * `@jr2/cli` of its own is told to add one (the launcher then hands off to it); one that has it is
+ * told to pin both lines at one number.
  */
-export function assertKitVersion(root: string): void {
-  const { instance, own, ok } = checkKitVersion(root);
+export function assertKitVersion(root: string, cli: CliCopy = THIS_CLI): void {
+  const { instance, own, ok } = checkKitVersion(root, cli);
   if (ok) return;
 
   const manifest = join(root, "package.json");
@@ -127,7 +137,7 @@ export function assertKitVersion(root: string): void {
     ? `${ORCHESTRATOR} resolves to ${instance.version} (${instance.root})`
     : `${ORCHESTRATOR} does not resolve from ${root}`;
   const self = own
-    ? `this jr2 (${CLI_VERSION}) runs against ${own.version} (${own.root})`
-    : `this jr2 (${CLI_VERSION}, at ${CLI_ROOT}) has no ${ORCHESTRATOR} beside it`;
+    ? `this jr2 (${cli.version}) runs against ${own.version} (${own.root})`
+    : `this jr2 (${cli.version}, at ${cli.root}) has no ${ORCHESTRATOR} beside it`;
   throw new Error(`Kit version mismatch — an Instance has one (ADR-0056):\n  ${have}\n  ${self}\n  ${fix}`);
 }