@jr2/cli 0.3.0 → 0.5.1

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,42 +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
-  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
-  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
@@ -74,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);
@@ -87,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":
@@ -98,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 { MachineDoc, RepoStatus } 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). */
@@ -17,19 +25,66 @@ export type RunStatus = {
   status: string;
   value: unknown;
   context: unknown;
-  /** Why the host set this status, for statuses the Machine did not choose — `drifted` says the
-   * workflow changed shape since the run was saved, and names both fingerprints (ADR-0030). */
+  /** The live child machines beneath the root, context-free — where most of a run is. */
+  children?: RunChild[];
+  /** Every Workspace waiting for capacity, and why (ADR-0064). Optional: an orchestrator older
+   * than ADR-0064 does not send it. */
+  waiting?: RunWaiting[];
+  /** Why the host set this status, for statuses the Machine did not choose — `drifted` names the
+   * Assembly hash and why this Orchestrator cannot read it: not on the volume, published for
+   * another Kit version, or does not load (ADR-0030, ADR-0069). */
   reason?: string;
+  /** The hash of the Assembly the run started under, and holds while it is live (ADR-0069).
+   * Absent for a run no Assembly started. */
+  assembly?: string;
+  /** The run binds at least one Chart (ADR-0070): its Machine is the Chart wrapper's with each bound
+   * Open body's Chart compiled in, which `GET /workflows/:name/runs/:runId/machine` serves.
+   * Absent when the run binds none. */
+  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 }>;
+};
+
+/** Where a Workflow came from (ADR-0070): a Machine in the Assembly, a Chart file in the Assembly, or
+ * a runtime Chart put by `PUT /workflows/:wrapper/charts/:name`. */
+export type WorkflowOrigin = "machine" | "file" | "runtime";
+
+/** One entry of `GET /workflows` (ADR-0070) — mirrors the orchestrator's `WorkflowListing`
+ * (run-host.ts). A Chart wrapper's entry carries its Open body slot, whether its door takes a Chart
+ * one-shot, and its named Charts, inside its entry and not beside it. `unrunnable` is why a
+ * Workflow cannot start now (a runtime Chart a publish no longer admits). */
+export type WorkflowListing = {
+  name: string;
+  origin: WorkflowOrigin;
+  wrapper?: {
+    body: string;
+    oneShot: boolean;
+    charts: Array<{ name: string; origin: "file" | "runtime"; unrunnable?: string }>;
+  };
+  unrunnable?: string;
 };
 
 /** One item on a run's observation feed — mirrors the orchestrator's `RunFeedEvent`. */
 export type RunFeedEvent =
   | { kind: "status"; status: RunStatus }
   | { kind: "emit"; event: { type: string } & Record<string, unknown> }
-  | { kind: "retry"; child: string; attempt: number; reason: string };
+  | { kind: "retry"; child: string; attempt: number; reason: string }
+  | PlacingMarker
+  | ChildErrorMarker;
 
-/** A run-control event posted to a live run (ADR-0013): CANCEL is the vocabulary that is left. */
-export type RunEvent = { type: string };
+/** A run-control event posted to a live run (ADR-0013): CANCEL is the vocabulary that is left.
+ * `keep` leaves a cancelled run's Workspaces instead of destroying them (ADR-0025). */
+export type RunEvent = { type: string; keep?: boolean };
 
 /** The subset of `fetch` the client uses. `globalThis.fetch` and hono's `app.request` both satisfy it. */
 export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
@@ -57,16 +112,27 @@ export class JR2HttpError extends Error {
   readonly status: number;
   readonly path: string;
   readonly instance?: InstanceIdentity;
+  /** The door's report lines, when the answer carried them: a refused Chart is
+   * `422 { error: "refused", report }` (ADR-0070), one line per rule it fails. */
+  readonly report?: string[];
 
-  constructor(message: string, status: number, path: string, instance?: InstanceIdentity) {
+  constructor(message: string, status: number, path: string, instance?: InstanceIdentity, report?: string[]) {
     super(message);
     this.name = "JR2HttpError";
     this.status = status;
     this.path = path;
     this.instance = instance;
+    if (report) this.report = report;
   }
 }
 
+/** The path of a Workflow's routes. The name is ONE path segment, encoded: a named Chart's
+ * `<wrapper>/<name>` rides as `<wrapper>%2F<name>` (ADR-0070), which the Orchestrator reads as the
+ * same Workflow as `/workflows/<wrapper>/charts/<name>`. */
+export function workflowPath(workflow: string): string {
+  return `/workflows/${encodeURIComponent(workflow)}`;
+}
+
 export class JR2Client {
   readonly baseUrl: string;
   private readonly fetchImpl: FetchLike;
@@ -85,20 +151,40 @@ export class JR2Client {
     return this.token ? { ...extra, authorization: `Bearer ${this.token}` } : extra;
   }
 
-  /** `GET /workflows` — names of the registered workflows. */
-  async workflows(): Promise<string[]> {
-    return (await this.json(await this.fetchImpl(`${this.baseUrl}/workflows`), "/workflows")) as string[];
+  /** `GET /workflows` — every registered Workflow with its origin, each Chart wrapper's Charts inside
+   * its entry (ADR-0070). An orchestrator older than ADR-0070 answers bare names; each reads as a
+   * Machine, so the listing has one shape for every caller. */
+  async workflows(): Promise<WorkflowListing[]> {
+    const body = await this.json(await this.fetchImpl(`${this.baseUrl}/workflows`), "/workflows");
+    // An answer that is no listing is not "none registered": say what came back (`jr2 runs` prints
+    // `workflows: unknown — ...` for it, never "none registered").
+    if (!Array.isArray(body)) throw new Error("GET /workflows: the answer is not a listing");
+    return body.map((w: unknown) =>
+      typeof w === "string" ? { name: w, origin: "machine" as const } : (w as WorkflowListing),
+    );
   }
 
   /** `GET /workflows/:name/machine` — the workflow's Machine as the Console's DTO. */
   async machine(workflow: string): Promise<MachineDoc> {
-    const res = await this.fetchImpl(`${this.baseUrl}/workflows/${encodeURIComponent(workflow)}/machine`);
+    const res = await this.fetchImpl(`${this.baseUrl}${workflowPath(workflow)}/machine`);
     return (await this.json(res, "/workflows/:name/machine")) as MachineDoc;
   }
 
-  /** `POST /workflows/:name/runs` — start a run; unknown workflow → 404 → throws. */
+  /** `GET /workflows/:name/runs/:runId/machine` — the run's bound Machine (ADR-0070): the Chart
+   * wrapper's Machine with each bound Open body's Chart compiled in. An unknown run → undefined. */
+  async runMachine(workflow: string, runId: string): Promise<MachineDoc | undefined> {
+    const res = await this.fetchImpl(
+      `${this.baseUrl}${workflowPath(workflow)}/runs/${encodeURIComponent(runId)}/machine`,
+    );
+    if (res.status === 404) return undefined;
+    return (await this.json(res, "/workflows/:name/runs/:runId/machine")) as MachineDoc;
+  }
+
+  /** `POST /workflows/:name/runs` — start a run; unknown workflow → 404 → throws. A named Chart's
+   * name `<wrapper>/<name>` rides the path as one encoded segment (ADR-0070); a refused Chart in
+   * the input → 422 → throws with the door's `report`. */
   async start(workflow: string, input: Record<string, unknown> = {}): Promise<{ runId: string; instanceId: string }> {
-    const res = await this.fetchImpl(`${this.baseUrl}/workflows/${encodeURIComponent(workflow)}/runs`, {
+    const res = await this.fetchImpl(`${this.baseUrl}${workflowPath(workflow)}/runs`, {
       method: "POST",
       headers: this.headers(JSON_HEADERS),
       body: JSON.stringify(input),
@@ -142,7 +228,8 @@ export class JR2Client {
 
   /** `POST /runs/:runId/gates/:gate/events` — deliver a workflow-defined event to an open gate
    * (ADR-0011). The body is `{ type, ...input }`, validated against the event's schema host-side;
-   * an unknown gate (404) or rejected payload (400) surfaces as a throw. */
+   * an unknown gate (404), a rejected payload (400) or an answer the run would not take now (409,
+   * ADR-0013) surfaces as a throw. */
   async sendToGate(runId: string, gate: string, event: { type: string } & Record<string, unknown>): Promise<void> {
     const res = await this.fetchImpl(
       `${this.baseUrl}/runs/${encodeURIComponent(runId)}/gates/${encodeURIComponent(gate)}/events`,
@@ -165,26 +252,48 @@ export class JR2Client {
    * `GET /runs/:runId/events` — the SSE feed as an async-iterable of `RunFeedEvent`. The current status
    * is replayed first (attach), then deltas + author `emit`s until the terminal status (or the consumer
    * breaks, which cancels the stream). A settled run streams its final status once and ends.
+   *
+   * A feed that ends BEFORE a terminal status is re-attached, never read as the run's end: the
+   * server closes a reader that fell behind (a paused pager on `jr2 run | less`), and the feed is
+   * level-triggered, so the re-attach opens with where the run stands now (ADR-0022). What falls in
+   * the gap is activity — Emits, retries — never state. The one end that IS the run's own without
+   * a terminal status is `gone`: the run was stopped and is parked (ADR-0025); the generator ends.
    */
   async *events(runId: string): AsyncGenerator<RunFeedEvent> {
-    const res = await this.fetchImpl(`${this.baseUrl}/runs/${encodeURIComponent(runId)}/events`, {
-      headers: this.headers({ accept: "text/event-stream" }),
-    });
-    if (res.status === 404) {
-      throw new JR2HttpError(`no run "${runId}"`, 404, "/runs/:runId/events", await this.identify());
-    }
-    if (!res.body) return;
-    for await (const frame of parseSSE(res.body)) {
-      if (frame.event === "emit") {
-        yield { kind: "emit", event: JSON.parse(frame.data) as { type: string } & Record<string, unknown> };
-      } else if (frame.event === "retry") {
-        yield { kind: "retry", ...(JSON.parse(frame.data) as { child: string; attempt: number; reason: string }) };
-      } else if (frame.event === "status") {
-        yield { kind: "status", status: JSON.parse(frame.data) as RunStatus };
+    for (;;) {
+      const res = await this.fetchImpl(`${this.baseUrl}/runs/${encodeURIComponent(runId)}/events`, {
+        headers: this.headers({ accept: "text/event-stream" }),
+      });
+      if (res.status === 404) {
+        throw new JR2HttpError(`no run "${runId}"`, 404, "/runs/:runId/events", await this.identify());
+      }
+      if (!res.body) return;
+      let settled = false;
+      for await (const frame of parseSSE(res.body)) {
+        if (frame.event === "emit") {
+          yield { kind: "emit", event: JSON.parse(frame.data) as { type: string } & Record<string, unknown> };
+        } else if (frame.event === "retry") {
+          yield { kind: "retry", ...(JSON.parse(frame.data) as { child: string; attempt: number; reason: string }) };
+        } else if (frame.event === "status") {
+          const status = JSON.parse(frame.data) as RunStatus;
+          settled = status.status !== "active";
+          yield { kind: "status", status };
+        } else if (frame.event === "placing" || frame.event === "placed") {
+          // A wait for capacity starting and ending (ADR-0064) — activity, never a status.
+          yield { ...(JSON.parse(frame.data) as object), kind: frame.event } as PlacingMarker;
+        } else if (frame.event === "child-error") {
+          // A child's error below an Agent's state, which the Agent's answer does not carry (ADR-0024).
+          yield { ...(JSON.parse(frame.data) as object), kind: "child-error" } as ChildErrorMarker;
+        } else if (frame.event === "gone") {
+          // The run left the live set without settling — stopped, parked for the next boot's
+          // restore (ADR-0025). This end is the run's own (ADR-0022): nothing to re-attach to.
+          return;
+        }
+        // Any other frame (a Turn marker — ADR-0023 — or a kind this CLI predates) is skipped, not
+        // misread as a status: `jr2 logs -f` decides "settled" off `status.status`, and a marker
+        // parsed as a status would end the follow mid-run.
       }
-      // Any other frame (a Turn marker — ADR-0023 — or a kind this CLI predates) is skipped, not
-      // misread as a status: `jr2 logs -f` decides "settled" off `status.status`, and a marker
-      // parsed as a status would end the follow mid-run.
+      if (settled) return;
     }
   }
 
@@ -209,10 +318,12 @@ export class JR2Client {
     const text = await res.text();
     const body = text ? JSON.parse(text) : undefined;
     if (!res.ok) {
-      const message = (body as { error?: string } | undefined)?.error ?? `HTTP ${res.status}`;
+      const { error, report } = (body ?? {}) as { error?: string; report?: unknown };
+      const message = error ?? `HTTP ${res.status}`;
+      const lines = Array.isArray(report) ? report.map(String) : undefined;
       // Probe HERE, not at the catch site: by the time the error reaches `cli.ts` the command's
       // `finally` has closed the port-forward, and there is nothing left to ask.
-      throw new JR2HttpError(message, res.status, path, await this.identify());
+      throw new JR2HttpError(message, res.status, path, await this.identify(), lines);
     }
     return body;
   }