@jr2/cli 0.3.0 → 0.5.1

package/src/commands/send.ts

@@ -1,45 +1,44 @@
 // `jr2 send` (ADR-0009/0011/0013): the two down-channels a human has into a live run.
 //
-//   jr2 send <runId|abbrev> --event CANCEL                           run control (the only verb left)
+//   jr2 send <runId|abbrev> --event CANCEL [--keep]                  run control (the only verb left)
 //   jr2 send <runId|abbrev> --gate <gate> --event <name> [--input '<json>'] deliver to an open Gate
 //
 // Run control used to carry APPROVE and STEER too. Those rode the `deferred` (held tool result)
-// and `poll` (steer inbox) semantics, which ADR-0013 reserves but does not build — so they are
-// gone rather than left pretending. Workflow-defined events reach a run through its GATES
+// and `poll` (steer inbox) semantics: `deferred` is retired (ADR-0006) and `poll` is reserved but
+// not built (ADR-0013) — so they are gone rather than left pretending. Workflow-defined events reach a run through its GATES
 // (`POST /runs/:id/gates/:gate/events` — ADR-0011): the gate names the pending decision, the
 // event name must be in its derived accepts, and the input is validated against the event's
-// schema host-side. Discover a run's open gates (names + accepts + meta) with `jr2 status <runId>`.
+// schema host-side. An answer the run would not take now is refused (409, ADR-0013) and prints as
+// an error naming what the Gate takes now; "delivered" is printed only when the run took it.
+// Discover a run's open gates (names + accepts + meta) with `jr2 status <runId>`.
 //
 // The run id resolves BEFORE either branch: both are writes, and a write must never be
 // prefix-sensitive (ADR-0009). It also gives a bad id a real error — `host.stop()` returns silently
 // for an unknown run, so an unresolved CANCEL used to report success.
+//
+// A CANCEL destroys the run's Workspaces; `--keep` leaves them for inspection until the operator's
+// idle timeout (ADR-0025). It is a fact of this cancel, so it is a flag here and never a config key,
+// and it means nothing on any other event — refused there rather than ignored.
 
-import { parseArgs } from "node:util";
 import { JR2Client } from "../client.ts";
-import { resolveTarget, TARGET_ARGS, targetOptions } from "../instance.ts";
+import { resolveTarget, targetOptions } from "../instance.ts";
 import { activity, type Io } from "../output.ts";
 import { resolveRunId } from "../run-id.ts";
-
-const USAGE =
-  "usage: jr2 send <runId|abbrev> --event CANCEL | jr2 send <runId|abbrev> --gate <gate> --event <name> [--input '<json>']";
+import { commandNamed, parseCommand, renderCommand } from "../command-table.ts";
 
 export async function send(args: string[], io: Io): Promise<number> {
-  const { values, positionals } = parseArgs({
-    args,
-    allowPositionals: true,
-    strict: false,
-    options: {
-      event: { type: "string" },
-      gate: { type: "string" },
-      input: { type: "string" },
-      ...TARGET_ARGS,
-    },
-  });
+  const { values, positionals } = parseCommand("send", args);
   const given = positionals[0];
   const gate = values.gate as string | undefined;
   const event = values.event as string | undefined;
   if (!given || !event) {
-    activity(io, USAGE);
+    activity(io, renderCommand(commandNamed("send")));
+    return 2;
+  }
+  const keep = values.keep === true;
+  // Refused before the run id resolves: a usage error needs no instance to be one.
+  if (values.keep !== undefined && (gate || event.toUpperCase() !== "CANCEL")) {
+    activity(io, `jr2 send: --keep goes with --event CANCEL alone (it keeps a cancelled run's Workspaces)`);
     return 2;
   }
   const target = await resolveTarget(io, targetOptions(values));
@@ -74,8 +73,8 @@ export async function send(args: string[], io: Io): Promise<number> {
       activity(io, `jr2 send: unknown event "${event}" (run control accepts: CANCEL; workflow events need --gate)`);
       return 2;
     }
-    await client.send(runId, { type: control });
-    activity(io, `sent ${control} to ${runId}`);
+    await client.send(runId, keep ? { type: control, keep } : { type: control });
+    activity(io, keep ? `sent ${control} to ${runId}; its Workspaces are kept` : `sent ${control} to ${runId}`);
     return 0;
   } finally {
     target.close?.();

package/src/commands/status.ts

@@ -1,8 +1,9 @@
 // `jr2 status [runId|abbrev]` (ADR-0009): print a run's status as JSON on stdout, reading through to the
 // store so a completed run still reports its terminal status + final context. A genuinely unknown run → 1.
 //
-// With NO run named, the verb answers about the INSTANCE instead (ADR-0048/0051): whether it has a
-// data plane at all, and every Repo resource's per-node state, so a Repo that will not clone — an
+// With NO run named, the verb answers about the INSTANCE instead (ADR-0048/0051/0069): every
+// Assembly a live run holds, the current one first, whether it has a data plane at all, and every Repo
+// resource's per-node state, so a Repo that will not clone — an
 // unregistered deploy key (ADR-0047), a wrong url, a git host outage — is discoverable by asking
 // the thing that knows, rather than by tailing pod logs. The Orchestrator serves either way; only
 // the Repo is degraded, and the cache agent retries it on its own.
@@ -10,21 +11,27 @@
 // Two output classes (ADR-0009 as amended): `status <runId>` is a RESULT verb — the RunStatus as one
 // JSON line on stdout, for the pipe. Bare `status` is a REPORT verb — a human table on stdout, or the
 // one object with `--json`.
+//
+// A run that binds a Chart (ADR-0070) carries `bound: true`; the verb says so beside the result as
+// `chart: bound`, with the route that draws the Machine the run binds, its Charts compiled in.
+//
+// A dispatched run (ADR-0071) says beside the result who dispatched it: `dispatched by: <run>
+// (<slot>), depth <n>`. A run that dispatched says the other direction, one line per run it
+// started: `dispatched: <run> (<slot>)`. The result itself carries `dispatchedBy`, `dispatched`
+// and, once the run is no longer live, its `output`, as the Orchestrator sends them.
+//
+// A failed run (ADR-0073) says its reason beside the result: `failed: <reason>`. The result's
+// `output` holds the whole Failure, `{ reason, detail? }`.
 
-import { parseArgs } from "node:util";
-import type { RepoStatus } from "@jr2/orchestrator";
-import { JR2Client } from "../client.ts";
-import { resolveTarget, TARGET_ARGS, targetOptions } from "../instance.ts";
+import type { AssemblyView, RepoStatus } from "@jr2/orchestrator/internal";
+import { JR2Client, type FetchLike, type RunStatus, workflowPath } from "../client.ts";
+import { resolveTarget, targetOptions } from "../instance.ts";
 import { activity, result, type Io } from "../output.ts";
 import { resolveRunId } from "../run-id.ts";
+import { parseCommand } from "../command-table.ts";
 
 export async function status(args: string[], io: Io): Promise<number> {
-  const { values, positionals } = parseArgs({
-    args,
-    allowPositionals: true,
-    strict: false,
-    options: { ...TARGET_ARGS, json: { type: "boolean" } },
-  });
+  const { values, positionals } = parseCommand("status", args);
   // NO run named, not an EMPTY one: `jr2 status "$RUNID"` with the variable unset asked about a run
   // and got an empty string, and answering that with the instance's repos would report exit 0 on a
   // question nobody asked. An empty positional falls through to the resolver, which says so.
@@ -32,7 +39,7 @@ export async function status(args: string[], io: Io): Promise<number> {
   const target = await resolveTarget(io, targetOptions(values));
   try {
     const client = new JR2Client(target.url, io.fetch, target.token);
-    if (given === undefined) return await instanceStatus(client, io, values.json === true);
+    if (given === undefined) return await instanceStatus(client, io, target.url, values.json === true);
     const ref = await resolveRunId(client, given);
     if (!ref.ok) {
       activity(io, ref.message);
@@ -44,18 +51,65 @@ export async function status(args: string[], io: Io): Promise<number> {
       return 1;
     }
     result(io, s);
+    const notes = [failureActivity(s), dispatchedActivity(s), ...dispatchedLines(s), boundActivity(s)];
+    for (const note of notes) if (note) activity(io, note);
     return 0;
   } finally {
     target.close?.();
   }
 }
 
+/** The `failed:` line for a run that ended `failed` (ADR-0073): the Failure's reason, read from its
+ * output. Undefined for every other status, and for an output with no reason text. */
+export function failureActivity(s: Pick<RunStatus, "status" | "output">): string | undefined {
+  if (s.status !== "failed") return undefined;
+  const reason = (s.output as { reason?: unknown } | undefined)?.reason;
+  return typeof reason === "string" ? `failed: ${reason}` : undefined;
+}
+
+/** The most `dispatched:` lines `jr2 status` prints: a watcher dispatches on every pass, and the
+ * result carries the whole list. */
+const DISPATCHED_LINES = 10;
+
+/** The `dispatched:` lines for the runs this run's `dispatch` Effects started (ADR-0071), newest
+ * last, the older ones counted. */
+export function dispatchedLines(s: RunStatus): string[] {
+  const all = s.dispatched ?? [];
+  const shown = all.slice(-DISPATCHED_LINES);
+  const older = all.length - shown.length;
+  return [
+    ...(older > 0 ? [`dispatched: ${older} older run(s); the result lists them all`] : []),
+    ...shown.map((d) => `dispatched: ${d.run} (${d.slot})`),
+  ];
+}
+
+/** The `dispatched by:` line for a run a `dispatch` Effect started (ADR-0071), or undefined for a
+ * run nobody dispatched. A foreign caller is named by its Orchestrator, as that one sent it: opaque
+ * text, which this Orchestrator could not verify. */
+export function dispatchedActivity(s: RunStatus): string | undefined {
+  const by = s.dispatchedBy;
+  if (!by) return undefined;
+  return `dispatched by: ${by.run} (${by.slot}), depth ${by.depth}${by.instance ? `, from Orchestrator ${by.instance}` : ""}`;
+}
+
+/** The `chart: bound` line for a run that binds a Chart (ADR-0070), or undefined for one that binds
+ * none. The Workflow name rides the route as one encoded segment. */
+export function boundActivity(s: RunStatus): string | undefined {
+  if (s.bound !== true) return undefined;
+  const route = `GET ${workflowPath(s.workflow)}/runs/${encodeURIComponent(s.runId)}/machine`;
+  // A drifted run's Chart may no longer admit (D-B): the route then draws the slot's own subgraph
+  // and names why in `chartsNotDrawn`, so the line does not claim more than the route draws.
+  if (s.status === "drifted") return `chart: bound, drifted — ${route} names each Chart it cannot draw`;
+  return `chart: bound — ${route} draws the Machine this run binds`;
+}
+
 /**
- * The instance's own status: the data-plane switch and every Repo resource. As a table on stdout —
+ * The instance's own status: the held Assemblies, the data-plane switch and every Repo resource. As a table on stdout —
  * every node's state per Repo, and every node whose last attempt FAILED spelled out with git's own
  * error, since that is the line a human acts on — or, with `--json`, as the one object (extensible:
- * the instance has more to report eventually). An instance with no data plane says so — "no
- * registered Machine composes a Sandbox" is the answer, not an empty list.
+ * the instance has more to report eventually). An instance with no data plane says so — "it runs
+ * outside a cluster" is the answer, not an empty list. A deployed Orchestrator always has one: it
+ * wires its kube client whatever the current Assembly composes (ADR-0069).
  *
  * Two failures, two consequences (ADR-0004/0051): a cache that is ABSENT on the node (a cold clone
  * failed) parks every Workspace that needs it there; a cache that is PRESENT but whose last fetch
@@ -65,18 +119,76 @@ export async function status(args: string[], io: Io): Promise<number> {
  * Exit 0 even with Repos failing: this is a report, and a degraded Repo is a state the instance
  * is serving in, not a failure of the asking.
  */
-async function instanceStatus(client: JR2Client, io: Io, json: boolean): Promise<number> {
-  const report = await client.repos();
+async function instanceStatus(client: JR2Client, io: Io, url: string, json: boolean): Promise<number> {
+  const report = { assembly: await readAssembly(io.fetch ?? globalThis.fetch, url), ...(await client.repos()) };
   if (json) result(io, report);
   else io.stdout(renderInstanceStatus(report));
   return 0;
 }
 
-/** The human table — one line per Repo, one per node under it, then the hints for what was seen. */
-export function renderInstanceStatus({ dataPlane, repos }: { dataPlane: boolean; repos: RepoStatus[] }): string {
-  let out = dataPlane
+/** `GET /assembly` (ADR-0069): open, like `GET /workflows`, so it needs no token. An answer that
+ * cannot be read is reported as the reason, never as a failure of the verb. */
+async function readAssembly(fetchImpl: FetchLike, url: string): Promise<AssemblyView | { error: string }> {
+  try {
+    const res = await fetchImpl(`${url.replace(/\/+$/, "")}/assembly`);
+    if (!res.ok) return { error: `GET /assembly answered HTTP ${res.status}` };
+    // Read loosely: a `held` that is absent or not a list reads as none held, so a report never
+    // fails on the shape of one field (ADR-0048: a report is not a failure of the asking).
+    const view = (await res.json()) as Partial<AssemblyView>;
+    return {
+      kitVersion: view.kitVersion ?? "",
+      current: view.current ?? null,
+      held: Array.isArray(view.held) ? view.held : [],
+    };
+  } catch (e) {
+    return { error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+/**
+ * The Assembly lines (ADR-0069): one per Assembly a live run holds, the current one first and so
+ * marked, each with how many live runs hold it — or why there is none. A run holds the Assembly it
+ * started under, so after a publish the previous one stays on the volume while a run still holds it.
+ * The current Assembly prints first, whatever order `held` uses; the other held Assemblies follow
+ * in the server's order.
+ */
+function assemblyLines(view: AssemblyView | { error: string } | undefined): string {
+  if (view === undefined) return "";
+  if ("error" in view) return `assembly: unknown — ${view.error}\n`;
+  const current = view.current;
+  const heldList = view.held;
+  const line = (hash: string, kitVersion: string, runs: number, isCurrent: boolean): string =>
+    `assembly: ${hash} (kit v${kitVersion}${isCurrent ? ", current" : ""}), ` +
+    `${runs} live run${runs === 1 ? "" : "s"} hold${runs === 1 ? "s" : ""} it\n`;
+  let out = "";
+  if (current) {
+    const runs = heldList.find((h) => h.hash === current.hash)?.runs.length ?? 0;
+    out += line(current.hash, current.kitVersion, runs, true);
+  } else {
+    out += "assembly: none — `jr2 up` publishes\n";
+  }
+  for (const held of heldList) {
+    if (held.hash === current?.hash) continue;
+    out += line(held.hash, held.kitVersion, held.runs.length, false);
+  }
+  return out;
+}
+
+/** The human table — the held Assemblies, current first, one line per Repo, one per node under it, then the
+ * hints for what was seen. */
+export function renderInstanceStatus({
+  assembly,
+  dataPlane,
+  repos,
+}: {
+  assembly?: AssemblyView | { error: string };
+  dataPlane: boolean;
+  repos: RepoStatus[];
+}): string {
+  let out = assemblyLines(assembly);
+  out += dataPlane
     ? "data plane: yes\n"
-    : "data plane: none — this instance has no data plane (no registered Machine composes a Sandbox)\n";
+    : "data plane: none — this Orchestrator runs outside a cluster, so it provisions no Sandbox (ADR-0069)\n";
   let absent = 0;
   let stale = 0;
   for (const repo of repos) {