@jr2/cli 0.6.0 → 0.7.0

package/src/commands/watch.ts

@@ -0,0 +1,57 @@
+// `jr2 watch <runId|abbrev> [--json]` (ADR-0009): attach to a run's feed and follow it to its end.
+// The orchestrator replays the current status on attach, so a parked run shows where it is, and an
+// ended run prints its last status once. It prints the lines that `jr2 run` prints while it is
+// attached, in the same form: the header `run <id> (<workflow>) — attached`, then each
+// `attachedLine` with the same indent, and after a failed run's last status its reason
+// (`failureActivity`). They go on stdout: a report verb. Its exit code is the watch's, not the
+// run's: 0 when it followed the feed to its end, a failed or a parked run too. `jr2 run` exits with
+// the run's result. `--json` prints each status as one JSON line on stdout and the other
+// lines as activity on stderr. A run that is parked before it settles ends the watch, as it ends
+// `jr2 run`'s attach.
+import { JR2Client } from "../client.ts";
+import { resolveTarget, targetOptions } from "../instance.ts";
+import { activity, result, type Io } from "../output.ts";
+import { resolveRunId } from "../run-id.ts";
+import { attachedLine } from "./run.ts";
+import { failureActivity } from "./status.ts";
+import { parseCommand, usageLine } from "../command-table.ts";
+
+export async function watch(args: string[], io: Io): Promise<number> {
+  const { values, positionals } = parseCommand("watch", args);
+  const given = positionals[0];
+  if (!given || positionals.length > 1) {
+    activity(io, usageLine("watch"));
+    return 2;
+  }
+  const target = await resolveTarget(io, targetOptions(values));
+  try {
+    const client = new JR2Client(target.url, io.fetch, target.token, target.onBehalfOf);
+    const ref = await resolveRunId(client, given);
+    if (!ref.ok) {
+      activity(io, ref.message);
+      return ref.code;
+    }
+    let headed = false;
+    for await (const ev of client.events(ref.runId)) {
+      if (values.json !== true && !headed) {
+        headed = true;
+        const workflow = ev.kind === "status" ? ev.status.workflow : "?";
+        io.stdout(`run ${ref.runId} (${workflow}) — attached\n`);
+      }
+      if (values.json !== true) io.stdout(`  ${attachedLine(ev)}\n`);
+      else if (ev.kind === "status") result(io, ev.status);
+      else activity(io, attachedLine(ev));
+      if (ev.kind === "status" && ev.status.status !== "active") {
+        // A failed run's reason, as `jr2 run` prints it after the last status.
+        const failed = failureActivity(ev.status);
+        if (failed && values.json !== true) io.stdout(`${failed}\n`);
+        else if (failed) activity(io, failed);
+        return 0;
+      }
+    }
+    activity(io, `run ${ref.runId} is parked: stopped before it settled`);
+    return 0;
+  } finally {
+    target.close?.();
+  }
+}

package/src/commands/whoami.ts

@@ -0,0 +1,22 @@
+// `jr2 whoami` (ADR-0078): the Caller that this credential is, as `GET /whoami` gives it — how jr2
+// knows it, its name, the name jr2 shows, what it may do, and the party it says it acts for. A
+// person runs it to see what a credential may do before an act fails. On a kube context it is
+// `token/instance`, on behalf of the kube user; with `--url` and `JR2_TOKEN` it is that token's
+// Caller. The route needs no scope, so a credential that may do nothing still sees why.
+
+import { JR2Client } from "../client.ts";
+import { parseCommand } from "../command-table.ts";
+import { resolveTarget, targetOptions } from "../instance.ts";
+import { result, type Io } from "../output.ts";
+
+export async function whoami(args: string[], io: Io): Promise<number> {
+  const { values } = parseCommand("whoami", args);
+  const target = await resolveTarget(io, targetOptions(values));
+  try {
+    const client = new JR2Client(target.url, io.fetch, target.token, target.onBehalfOf);
+    result(io, await client.whoami());
+    return 0;
+  } finally {
+    target.close?.();
+  }
+}

package/src/commands/workflows.ts

@@ -0,0 +1,58 @@
+// `jr2 workflows` (ADR-0009, ADR-0070): the Workflows that a run can start, from `GET /workflows`.
+// One line per Workflow with its origin (`machine`, `chart file`, `chart`), a Chart wrapper's Charts
+// indented under it, and `unrunnable` with its reason. `--json` prints the listing as the report.
+// No verb puts or deletes a runtime Chart: `PUT`/`DELETE /workflows/<wrapper>/charts/<name>` is for
+// an MCP or curl.
+
+import { JR2Client, type WorkflowListing, type WorkflowOrigin } from "../client.ts";
+import { resolveTarget, targetOptions } from "../instance.ts";
+import { result, type Io } from "../output.ts";
+import { parseCommand } from "../command-table.ts";
+
+export async function workflows(args: string[], io: Io): Promise<number> {
+  const { values } = parseCommand("workflows", args);
+  const target = await resolveTarget(io, targetOptions(values));
+  try {
+    const listing = await new JR2Client(target.url, io.fetch, target.token, target.onBehalfOf).workflows();
+    if (values.json === true) result(io, listing);
+    else io.stdout(`${renderWorkflows(listing)}\n`);
+    return 0;
+  } finally {
+    target.close?.();
+  }
+}
+
+/** How a listing names an origin (ADR-0070): a runtime Chart is plainly a `chart`. */
+const ORIGIN_LABEL: Record<WorkflowOrigin, string> = { machine: "machine", file: "chart file", runtime: "chart" };
+
+/**
+ * The Workflow listing as lines: each Workflow with its origin, a Chart wrapper's Open body and
+ * whether its door takes a Chart one-shot, its Charts indented under it, and `unrunnable` with the
+ * reason. A Chart the listing also gives at the top level (or whose wrapper it does not list) prints
+ * once: under its wrapper when the wrapper is listed, else at the top level.
+ */
+export function renderWorkflows(listing: readonly WorkflowListing[]): string {
+  const underWrapper = new Set<string>();
+  for (const w of listing) for (const c of w.wrapper?.charts ?? []) underWrapper.add(chartFullName(w.name, c.name));
+  const line = (indent: string, name: string, label: string, unrunnable?: string): string =>
+    `${indent}${name} (${label})${unrunnable ? ` unrunnable: ${unrunnable}` : ""}`;
+  const out: string[] = [];
+  for (const w of listing) {
+    if (w.origin !== "machine" && underWrapper.has(w.name)) continue;
+    const wrapper = w.wrapper;
+    const label = wrapper
+      ? `${ORIGIN_LABEL[w.origin]}, Chart wrapper: body "${wrapper.body}"${wrapper.oneShot ? ", one-shot" : ""}`
+      : ORIGIN_LABEL[w.origin];
+    out.push(line("", w.name, label, w.unrunnable));
+    for (const c of wrapper?.charts ?? []) {
+      out.push(line("  ", chartFullName(w.name, c.name), ORIGIN_LABEL[c.origin], c.unrunnable));
+    }
+  }
+  if (out.length === 0) out.push("none registered — `jr2 up` publishes the Assembly");
+  return out.join("\n");
+}
+
+/** A Chart's Workflow name, `<wrapper>/<name>` (ADR-0070), whether the listing gives it short or whole. */
+function chartFullName(wrapper: string, name: string): string {
+  return name.includes("/") ? name : `${wrapper}/${name}`;
+}

package/src/commands/workspace.ts

@@ -0,0 +1,316 @@
+// `jr2 workspace ls | shell | forward | rm` (ADR-0009, ADR-0012, ADR-0021): the Workspaces as the
+// cluster holds them. Each sub-verb reads the Sandbox CRs over the kube API (`workspaces.ts`) and
+// never the Orchestrator, so it works when the Orchestrator is down, and kube RBAC is the gate. They
+// take the deployment's addressing (`-n`, `--context`) and not `--url`. With `-n`, no instance
+// folder is needed: an ssh ProxyCommand runs in any folder.
+//
+//   ls [run]                     the Workspaces, and whether a run holds each
+//   shell <ws> [--user] [-- cmd] a shell in the Agents' Landlock domain (ADR-0076), or in the User Container
+//   forward <ws> <port> [--stdio] a local port to the pod, or one connection on stdin and stdout
+//   rm <ws>                      remove a Sandbox that no run holds
+
+import { connect as netConnect, type Socket } from "node:net";
+import { constants as osConstants } from "node:os";
+import { basename } from "node:path";
+import { loadConfig } from "@jr2/orchestrator/internal";
+import { commandNamed, parseCommand, renderCommand, usageLine } from "../command-table.ts";
+import { resolveRoot } from "../instance.ts";
+import { activity, result, type Io } from "../output.ts";
+import {
+  age,
+  kubectlWorkspaces,
+  matchHandle,
+  removable,
+  rowOf,
+  WorkspaceChangedError,
+  type WorkspaceKube,
+  type WorkspaceRow,
+} from "../workspaces.ts";
+
+/** How `jr2 workspace shell` starts in the Harness container: the client that asks the Harness for the
+ * shell, which its spawner starts in the Agents' domain (ADR-0076). It starts as the Harness starts,
+ * with the client's entry in place of the Harness's. */
+export const SHELL_ENTRY: readonly string[] = [
+  "/opt/jr2/bin/effector",
+  "nocore",
+  "--harness-env",
+  "--",
+  "/opt/jr2/bin/node",
+  "--disable-sigusr1",
+  "/opt/jr2/src/workspace-shell-main.ts",
+];
+
+/** A User Container's shell: bash where the image has it, else sh. */
+export const USER_SHELL: readonly string[] = ["sh", "-c", "command -v bash >/dev/null 2>&1 && exec bash || exec sh"];
+
+/** What `forward --stdio` needs of the process: its stdin and stdout, and a TCP connect. Seams for tests. */
+export type StdioPipe = {
+  stdin: NodeJS.ReadableStream;
+  stdout: NodeJS.WritableStream;
+  connect(port: number): Socket;
+};
+
+const SUBS = ["ls", "shell", "forward", "rm"] as const;
+type Sub = (typeof SUBS)[number];
+
+function usage(io: Io, sub: string | undefined): number {
+  activity(io, sub === undefined ? "jr2 workspace: no subcommand" : `unknown workspace subcommand: ${sub}`);
+  activity(io, SUBS.map((s) => renderCommand(commandNamed(`workspace ${s}`))).join("\n\n"));
+  return 2;
+}
+
+/** The deployment: `-n` as given, else the instance folder's config name, else its folder's name. */
+async function deployment(
+  io: Io,
+  kube: WorkspaceKube,
+  values: { namespace?: string | boolean; context?: string | boolean },
+): Promise<{ namespace: string; context?: string }> {
+  let namespace = typeof values.namespace === "string" ? values.namespace : undefined;
+  if (namespace === undefined) {
+    const root = resolveRoot(io.cwd);
+    namespace = (await loadConfig(root))?.name ?? basename(root);
+  }
+  const context = typeof values.context === "string" ? values.context : await kube.context();
+  if (!context) throw new Error("no kube context — `kind create cluster` (or point kubectl at one), then `jr2 up`");
+  activity(io, `→ context ${context} / namespace ${namespace}`);
+  return { namespace, ...(typeof values.context === "string" ? { context: values.context } : {}) };
+}
+
+/** Every Workspace of the instance, and the API server's clock. */
+async function rows(
+  kube: WorkspaceKube,
+  where: { namespace: string; context?: string },
+): Promise<{ rows: WorkspaceRow[]; serverNow?: number }> {
+  let listed;
+  try {
+    listed = await kube.list(where);
+  } catch (e) {
+    throw new Error(`cannot list the Sandboxes in namespace ${where.namespace}: ${(e as Error).message}`);
+  }
+  return {
+    rows: listed.items.map((cr) => rowOf(cr, listed.serverNow)),
+    ...(listed.serverNow !== undefined ? { serverNow: listed.serverNow } : {}),
+  };
+}
+
+/** The one Workspace a handle names, or a refusal that lists the candidates. */
+function one(io: Io, all: readonly WorkspaceRow[], handle: string): WorkspaceRow | undefined {
+  const found = matchHandle(all, handle);
+  if (found.length === 1) return found[0];
+  if (found.length === 0) {
+    activity(io, `no Workspace "${handle}" — \`jr2 workspace ls\` lists them`);
+  } else {
+    activity(io, `"${handle}" names ${found.length} Workspaces — give more of the run id:`);
+    for (const r of found) activity(io, `  ${r.runId}/${r.path}  (${r.name})`);
+  }
+  return undefined;
+}
+
+/** The `ls` table: one row a Workspace, the columns padded. */
+export function workspaceTable(all: readonly WorkspaceRow[], now: number): string {
+  const LIVE: Record<WorkspaceRow["hold"], string> = {
+    held: "held",
+    released: "released",
+    idle: "idle",
+    unknown: "unknown",
+  };
+  const table = [
+    ["WORKSPACE", "SANDBOX", "WORKFLOW", "PHASE", "AGE", "RUN"],
+    ...all.map((r) => [r.handle, r.name, r.workflow, r.phase, age(r.created, now), LIVE[r.hold]]),
+  ];
+  const widths = table[0]!.map((_, i) => Math.max(...table.map((row) => row[i]!.length)));
+  return table
+    .map((row) =>
+      row
+        .map((cell, i) => cell.padEnd(widths[i]!))
+        .join("  ")
+        .trimEnd(),
+    )
+    .join("\n");
+}
+
+/** The signals that end a forward: ssh's SIGHUP to its ProxyCommand, SIGTERM, and Ctrl-C. */
+const ENDING_SIGNALS = ["SIGHUP", "SIGTERM", "SIGINT"] as const;
+
+/**
+ * On each of `ENDING_SIGNALS`, `close` runs, then this process exits as that signal would have
+ * ended it (128 + its number). Without it a signal ends node by its default action, and the
+ * kubectl child that holds the forward runs on. Returns the unhook.
+ */
+export function endOnSignals(close: () => void): () => void {
+  const handlers = ENDING_SIGNALS.map((signal) => {
+    const handler = () => {
+      close();
+      process.exit(128 + osConstants.signals[signal]);
+    };
+    process.once(signal, handler);
+    return [signal, handler] as const;
+  });
+  return () => {
+    for (const [signal, handler] of handlers) process.removeListener(signal, handler);
+  };
+}
+
+/** `forward --stdio`: one connection to the forwarded port, on stdin and stdout, then the forward
+ * closes. */
+function stdioForward(
+  io: Io,
+  given: StdioPipe | undefined,
+  fwd: { port: number; close: () => void },
+  where: string,
+): Promise<number> {
+  const pipe: StdioPipe = given ?? {
+    stdin: process.stdin,
+    stdout: process.stdout,
+    connect: (p) => netConnect({ host: "127.0.0.1", port: p }),
+  };
+  return new Promise<number>((resolve) => {
+    const socket = pipe.connect(fwd.port);
+    const end = (code: number) => {
+      fwd.close();
+      resolve(code);
+    };
+    socket.on("error", (err) => {
+      activity(io, `the forward to ${where} failed: ${err.message}`);
+      end(1);
+    });
+    socket.on("close", () => end(0));
+    pipe.stdin.pipe(socket);
+    socket.pipe(pipe.stdout, { end: false });
+  });
+}
+
+export async function workspace(
+  args: string[],
+  io: Io,
+  opts: { pipe?: StdioPipe; onSignals?: (close: () => void) => () => void } = {},
+): Promise<number> {
+  const sub = args[0] as Sub | undefined;
+  if (sub === undefined || !SUBS.includes(sub)) return usage(io, sub);
+  const kube = io.workspaces ?? kubectlWorkspaces;
+
+  if (sub === "ls") {
+    const { values, positionals } = parseCommand("workspace ls", args);
+    const where = await deployment(io, kube, values);
+    const run = positionals[1];
+    const listed = await rows(kube, where);
+    const shown = listed.rows
+      .filter((r) => run === undefined || r.runId.startsWith(run))
+      .sort((a, b) => (a.created ?? "").localeCompare(b.created ?? "") || a.handle.localeCompare(b.handle));
+    if (values.json === true) result(io, { workspaces: shown });
+    else io.stdout(`${workspaceTable(shown, listed.serverNow ?? Date.now())}\n`);
+    return 0;
+  }
+
+  if (sub === "shell") {
+    // `-- <cmd>` is the command, kept apart before the parse.
+    const dash = args.indexOf("--");
+    const own = dash >= 0 ? args.slice(0, dash) : args;
+    const command = dash >= 0 ? args.slice(dash + 1) : [];
+    const { values, positionals } = parseCommand("workspace shell", own);
+    const handle = positionals[1];
+    if (!handle || positionals.length > 2) {
+      activity(io, usageLine("workspace shell"));
+      return 2;
+    }
+    const where = await deployment(io, kube, values);
+    const row = one(io, (await rows(kube, where)).rows, handle);
+    if (!row) return 1;
+    if (values.user === true) {
+      const listed = await kube.list(where);
+      const cr = listed.items.find((c) => c.metadata.name === row.name);
+      if (!cr?.spec?.sidecars?.some((s) => s.name === "user")) {
+        activity(io, `Workspace ${row.handle} has no User Container: its workspace() names no \`user\` image`);
+        return 1;
+      }
+      const code = await kube.exec({
+        ...where,
+        pod: row.name,
+        container: "user",
+        argv: command.length ? command : USER_SHELL,
+        tty: command.length === 0,
+      });
+      if (code === 126 || code === 127) {
+        activity(
+          io,
+          command.length
+            ? `the User Container could not run ${command[0]} (exit ${code})`
+            : "the User Container's image has no sh: give it a shell, or name a command after --",
+        );
+      }
+      return code;
+    }
+    return await kube.exec({
+      ...where,
+      pod: row.name,
+      container: "harness",
+      argv: command.length ? [...SHELL_ENTRY, "--", ...command] : SHELL_ENTRY,
+      tty: command.length === 0,
+    });
+  }
+
+  if (sub === "forward") {
+    const { values, positionals } = parseCommand("workspace forward", args);
+    const [, handle, portText] = positionals;
+    const port = Number(portText);
+    if (!handle || !Number.isInteger(port) || port < 1 || port > 65535 || positionals.length > 3) {
+      activity(io, usageLine("workspace forward"));
+      return 2;
+    }
+    const where = await deployment(io, kube, values);
+    const row = one(io, (await rows(kube, where)).rows, handle);
+    if (!row) return 1;
+    const fwd = await kube.forward({ ...where, pod: row.name, port });
+    // The forward ends with this verb. ssh ends a ProxyCommand with SIGHUP, a supervisor with
+    // SIGTERM, a person with Ctrl-C: each closes the forward first, then exits as the signal would.
+    const unhook = (opts.onSignals ?? endOnSignals)(() => fwd.close());
+    try {
+      if (values.stdio !== true) {
+        io.stdout(`127.0.0.1:${fwd.port}\n`);
+        activity(io, `forwarding 127.0.0.1:${fwd.port} → ${row.handle}:${port} — Ctrl-C ends it`);
+        return await fwd.closed;
+      }
+      return await stdioForward(io, opts.pipe, fwd, `${row.handle}:${port}`);
+    } finally {
+      unhook();
+    }
+  }
+
+  const { values, positionals } = parseCommand("workspace rm", args);
+  const handle = positionals[1];
+  if (!handle || positionals.length > 2) {
+    activity(io, usageLine("workspace rm"));
+    return 2;
+  }
+  const where = await deployment(io, kube, values);
+  const row = one(io, (await rows(kube, where)).rows, handle);
+  if (!row) return 1;
+  if (!removable(row)) {
+    const why =
+      row.hold === "held" ? `run ${row.runId} holds it` : `it has no hold mark, so it may be held by run ${row.runId}`;
+    activity(
+      io,
+      `Workspace ${row.handle} (${row.name}) is not removed: ${why} — cancel the run first ` +
+        `(\`jr2 send ${row.runId} --event CANCEL\`)`,
+    );
+    return 1;
+  }
+  try {
+    // Only the version that was read: a run that placed the same name again since then holds it.
+    await kube.delete({
+      ...where,
+      name: row.name,
+      ...(row.resourceVersion !== undefined ? { resourceVersion: row.resourceVersion } : {}),
+    });
+  } catch (err) {
+    if (!(err instanceof WorkspaceChangedError)) throw err;
+    activity(
+      io,
+      `Workspace ${row.handle} (${row.name}) is not removed: it changed after it was read, ` +
+        "so a run may hold it again — run `jr2 workspace ls` and try again",
+    );
+    return 1;
+  }
+  activity(io, `removed Workspace ${row.handle} (${row.name})`);
+  return 0;
+}