@jr2/cli 0.3.0 → 0.4.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/kube.ts

@@ -52,8 +52,8 @@ export type KubePort = {
 const ctxArgs = (context?: string): string[] => (context ? ["--context", context] : []);
 
 /** The loosely-typed kube object shape the converge logic inspects: labels carry the instance's
- * identity and the instance image's content hash; annotations carry the converged image map, which
- * is too long for a label value (ADR-0038). */
+ * identity; annotations carry the converged image map, which is too long for a label value
+ * (ADR-0038). */
 export type KubeObject = {
   metadata: {
     name: string;
@@ -138,6 +138,13 @@ export type KubeAdmin = {
     previous?: boolean;
     context?: string;
   }): Promise<string>;
+  /** The API server's `gitVersion` (`kubectl get --raw /version`), e.g. `v1.35.0-gke.1200` — what
+   * ADR-0037's Kubernetes floor is judged against. THROWS when the server does not answer, like
+   * `listJson`: a floor check that passed because it could not look is no check at all. */
+  serverVersion(opts: { context?: string }): Promise<string>;
+  /** `kubectl create --dry-run=server -o json -f -`: the object as admission would store it,
+   * stored nowhere. THROWS on a refusal, with kubectl's reason. */
+  dryRunCreate(opts: { manifest: string; context?: string }): Promise<{ spec?: { resources?: unknown } }>;
   /** Run a one-shot node script IN the cluster (`kubectl run --rm`) and return its output — the
    * provider-preflight seam (ADR-0019: reachability must be probed from where pods live).
    * `caPem` makes the probe trust a private CA the same way the Harness does (ADR-0020):
@@ -154,8 +161,8 @@ export type KubeAdmin = {
 
 const nsArgs = (namespace?: string): string[] => (namespace ? ["--namespace", namespace] : []);
 
-/** The two workload kinds `jr2 up` rolls out and waits on. */
-export type RolloutKind = "deployment" | "daemonset";
+/** The workload kinds `jr2 up` rolls out and waits on. */
+export type RolloutKind = "deployment" | "daemonset" | "statefulset";
 
 /** One rollout to wait for: the object, by kind and name, in its namespace. */
 export type RolloutRequest = {
@@ -186,6 +193,28 @@ export function rolloutStatusArgs({
   ];
 }
 
+/** ADR-0037's Kubernetes floor: every Sandbox's `/opt/jr2` is an `image` volume of the harness
+ * image, and image volumes are on by default from 1.35 (GA in 1.36). There is no fallback below it
+ * — a second pod shape kept alive for clusters no Instance runs on — so `jr2 up` refuses there. */
+export const KUBE_FLOOR = { major: 1, minor: 35 } as const;
+
+/**
+ * Why this server version cannot host an Instance, or undefined when it can. Pure, so the floor is
+ * checkable without a cluster. Judged on the leading `v<major>.<minor>` alone: distributions append
+ * their own suffixes (`-gke.1200`, `+k3s1`, `-eks-…`), and none of them moves the feature gate. A
+ * version with no such prefix is refused BY NAME rather than passed — a floor that waves through
+ * what it cannot read is the timeout ADR-0046 exists to replace.
+ */
+export function kubeFloorRefusal(gitVersion: string): string | undefined {
+  const floor = `${KUBE_FLOOR.major}.${KUBE_FLOOR.minor}`;
+  const why = `jr2 needs Kubernetes ${floor} or newer (every Sandbox mounts jr2's runtime as an image volume, ADR-0037)`;
+  const m = /^v?(\d+)\.(\d+)/.exec(gitVersion);
+  if (!m) return `reports version "${gitVersion}", which names no major.minor; ${why}`;
+  const [major, minor] = [Number(m[1]), Number(m[2])];
+  if (major > KUBE_FLOOR.major || (major === KUBE_FLOOR.major && minor >= KUBE_FLOOR.minor)) return undefined;
+  return `runs Kubernetes ${gitVersion}; ${why}`;
+}
+
 /**
  * Did this read fail because the cluster has no such RESOURCE TYPE (`kubectl get sandboxes… ` on a
  * cluster with no jr2 CRD)? kubectl exits 1 with `the server doesn't have a resource type "…"`, and
@@ -288,6 +317,28 @@ export const kubectlAdmin: KubeAdmin = {
     }
   },
 
+  async serverVersion({ context }) {
+    // `get --raw /version`, not `kubectl version`: that one reports the CLIENT too; this asks the
+    // server alone, and answers in the server's own JSON. Bounded like every first contact: it is
+    // the first thing `jr2 up` asks, so a dead context fails here, fast, with kubectl's own reason.
+    try {
+      const { stdout } = await exec("kubectl", [...ctxArgs(context), "get", "--raw", "/version", ...reachArgs], {
+        timeout: REACH_BUDGET_MS,
+      });
+      return (JSON.parse(stdout) as { gitVersion?: string }).gitVersion ?? "";
+    } catch (e) {
+      throw new Error(unreachable(e));
+    }
+  },
+
+  async dryRunCreate({ manifest, context }) {
+    const out = await execStdinOut(
+      ["kubectl", ...ctxArgs(context), "create", "--dry-run=server", "-o", "json", "-f", "-"],
+      manifest,
+    );
+    return JSON.parse(out) as { spec?: { resources?: unknown } };
+  },
+
   async runOneShot({ namespace, name, script, caPem, context }) {
     // With a CA bundle: write the PEM to a file BEFORE node starts, because NODE_EXTRA_CA_CERTS
     // is only honored as process-start env. The PEM rides an env var base64'd (multiline values
@@ -350,6 +401,8 @@ export type RolloutTarget = {
   namespace: string;
   selector: string;
   context?: string;
+  /** Default 180s (see `rolloutStatusArgs`). */
+  timeoutSeconds?: number;
 };
 
 /** One container's state, as the kubelet tells it. `reason`/`message` are its words verbatim — the
@@ -474,7 +527,12 @@ async function gatherRolloutEvidence(kube: KubeAdmin, target: RolloutTarget): Pr
   const live = pods.filter((p) => !p.metadata.deletionTimestamp);
   if (pods.length > 0 && live.length === 0) notes.push(`every pod matching ${selector} is terminating`);
   if (pods.length === 0 && notes.length === 0) {
-    const maker = target.kind === "daemonset" ? "the DaemonSet" : "the ReplicaSet";
+    const maker =
+      target.kind === "daemonset"
+        ? "the DaemonSet"
+        : target.kind === "statefulset"
+          ? "the StatefulSet"
+          : "the ReplicaSet";
     notes.push(`no pod matches ${selector} — ${maker} made none (check quota, node taints, and the selector)`);
   }
 
@@ -732,6 +790,50 @@ function execStdin(cmd: string[], stdin: string): Promise<void> {
   });
 }
 
+/** `execStdin`, keeping stdout. */
+function execStdinOut(cmd: string[], stdin: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd[0]!, cmd.slice(1));
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (d: Buffer) => (out += d.toString()));
+    child.stderr.on("data", (d: Buffer) => (err += d.toString()));
+    child.on("error", reject);
+    child.on("close", (code) =>
+      code === 0 ? resolve(out) : reject(new Error(`${cmd.join(" ")} exited (${code}): ${err.trim()}`)),
+    );
+    child.stdin.write(stdin);
+    child.stdin.end();
+  });
+}
+
+/**
+ * The pod ADR-0060's check dry-runs: one that states pod-level resources (KEP-2837). A server
+ * whose PodLevelResources gate is off drops `spec.resources` at admission without a word, and
+ * every Sandbox then runs Burstable — a User Container with no split unbounded, against "jr2
+ * reserves the whole Size". On by default from 1.34, below KUBE_FLOOR, so only an owner who turned
+ * it off trips this. Shaped for the `restricted` Pod Security level, so a namespace that enforces
+ * it does not refuse the probe for another reason. Never scheduled, never pulled.
+ */
+export function podResourcesProbe(namespace: string): object {
+  return {
+    apiVersion: "v1",
+    kind: "Pod",
+    metadata: { name: "jr2-pod-resources-probe", namespace },
+    spec: {
+      resources: { requests: { cpu: "10m", memory: "16Mi" }, limits: { cpu: "10m", memory: "16Mi" } },
+      securityContext: { runAsNonRoot: true, runAsUser: 65532, seccompProfile: { type: "RuntimeDefault" } },
+      containers: [
+        {
+          name: "probe",
+          image: "registry.k8s.io/pause:3.10",
+          securityContext: { allowPrivilegeEscalation: false, capabilities: { drop: ["ALL"] } },
+        },
+      ],
+    },
+  };
+}
+
 /** The real kube port, over `kubectl` subprocesses. */
 export const kubectlKube: KubePort = {
   async currentContext() {

package/src/nodes.ts

@@ -7,13 +7,13 @@
 // at the moment of the read. The set moves (a pool autoscales, a node is cordoned), which is why an
 // empty set is reported and never refused.
 
-import type { SandboxPlacement, Toleration } from "@jr2/orchestrator";
+import { cpuMillis, memoryBytes, type ResolvedSize, type SandboxPlacement, type Toleration } from "@jr2/orchestrator";
 
 /** A cluster node, read for the facts that decide placement and platform (ADR-0045/0052). */
 export type NodeObject = {
   metadata: { name: string; labels?: Record<string, string> };
   spec?: { unschedulable?: boolean; taints?: readonly Taint[] };
-  status?: { nodeInfo?: { architecture?: string } };
+  status?: { nodeInfo?: { architecture?: string }; allocatable?: Record<string, string> };
 };
 
 export type Taint = { key: string; value?: string; effect: string };
@@ -72,3 +72,28 @@ export function tolerates(t: Toleration, taint: Taint): boolean {
   if (t.operator === "Exists") return true;
   return (t.value ?? "") === (taint.value ?? "");
 }
+
+/**
+ * Whether any of `nodes` could hold `size` (ADR-0060): its allocatable memory and cpu both at least
+ * the whole Size — what the scheduler compares a Guaranteed pod against on an empty node. `undefined`
+ * when no node reports allocatable, which is an unknown, never a no. A WARNING at `jr2 up`, never a
+ * refusal: the node set moves (ADR-0052), and a pool may scale up a bigger node tomorrow.
+ */
+export function anyNodeHolds(nodes: readonly NodeObject[], size: ResolvedSize): boolean | undefined {
+  let known = false;
+  for (const node of nodes) {
+    const alloc = node.status?.allocatable;
+    if (alloc?.memory === undefined || alloc.cpu === undefined) continue;
+    let memory: number;
+    let cpu: number;
+    try {
+      memory = memoryBytes(alloc.memory);
+      cpu = cpuMillis(alloc.cpu);
+    } catch {
+      continue;
+    }
+    known = true;
+    if (memory >= size.memory.bytes && cpu >= size.cpu.millis) return true;
+  }
+  return known ? false : undefined;
+}

package/src/sweep.ts

@@ -7,11 +7,12 @@
 // is not this instance's garbage):
 //   1. the `jr2-images` ConfigMap of every jr2 instance (namespaces labeled `jr2.dev/instance`) — what
 //      FUTURE Sandboxes will be provisioned with;
-//   2. every Sandbox CR's `spec.image` in those namespaces — a parked Workspace must survive a pod
-//      restart, and `imagePullPolicy: IfNotPresent` cannot re-pull a local tag;
-//   3. every pod's container images in those namespaces plus `jr2-system` — what is actually running
-//      (orchestrator, Instance Harness, Custodians, Sandboxes, operator), mid-roll pods INCLUDED,
-//      without naming Deployments one by one.
+//   2. every Sandbox CR's `spec.image`, sidecar, init container and `image` volume in those
+//      namespaces — a parked Workspace must survive a pod restart, and `imagePullPolicy:
+//      IfNotPresent` cannot re-pull a local tag;
+//   3. every pod's container and `image` volume refs in those namespaces plus `jr2-system` — what is
+//      actually running (orchestrator, Instance Harness, Custodians, Sandboxes, operator), mid-roll
+//      pods INCLUDED, without naming Deployments one by one.
 // The keep set is their union. "Kit images are never pruned" is not a rule here: a kit ref is kept
 // because some instance's map or pod names it, and collects like anything else when the last
 // instance leaves the cluster.
@@ -53,13 +54,18 @@ export type Roots = { keep: Set<string>; namespaces: string[] };
 
 type NamespacedObject = { metadata: { name: string; namespace?: string } };
 type ConfigMapObject = NamespacedObject & { data?: Record<string, string> };
-type SandboxObject = NamespacedObject & { spec?: { image?: string; sidecars?: ContainerSpec[] } };
+type SandboxObject = NamespacedObject & {
+  spec?: { image?: string; sidecars?: ContainerSpec[]; initContainers?: ContainerSpec[]; volumes?: VolumeSpec[] };
+};
 type ContainerSpec = { image?: string };
+/** Only an `image` volume names a ref: every Sandbox's `/opt/jr2` is one, of the harness image (ADR-0037). */
+type VolumeSpec = { image?: { reference?: string } };
 type PodObject = NamespacedObject & {
   spec?: {
     containers?: ContainerSpec[];
     initContainers?: ContainerSpec[];
     ephemeralContainers?: ContainerSpec[];
+    volumes?: VolumeSpec[];
   };
 };
 
@@ -93,18 +99,20 @@ export async function readRoots(kube: KubeAdmin, ctx: { context?: string } = {})
   }
 
   // 2. what a parked Workspace's pod will be recreated with — the Sandbox Image AND every sidecar's
-  // ref. The CR always carries the Custodian as a sidecar (sandbox-kubectl.ts), and its ref is not
+  // ref. The CR always carries the Custodian as a sidecar (sandbox-kube.ts), and its ref is not
   // covered by the other roots: a running Sandbox is deliberately never re-imaged, so an `up` that
   // moved the Custodian's pin leaves the CR naming the OLD one while the map names the new. If that pod
   // is then lost (node restart, eviction, drain), the recreated one pulls the CR's sidecar ref —
-  // and `IfNotPresent` cannot re-pull a local tag a sweep took.
+  // and `IfNotPresent` cannot re-pull a local tag a sweep took. The same holds for the harness ref: it
+  // reaches the pod only as the `runtime` image volume (ADR-0037), never as a container's image.
   const sandboxes = await listSandboxes(kube, ctx);
   for (const sandbox of sandboxes) {
     if (!instanceNs.has(sandbox.metadata.namespace ?? "")) continue;
     if (sandbox.spec?.image) keep.add(sandbox.spec.image);
-    for (const sidecar of sandbox.spec?.sidecars ?? []) {
-      if (sidecar.image) keep.add(sidecar.image);
+    for (const c of [...(sandbox.spec?.sidecars ?? []), ...(sandbox.spec?.initContainers ?? [])]) {
+      if (c.image) keep.add(c.image);
     }
+    for (const ref of volumeRefs(sandbox.spec?.volumes)) keep.add(ref);
   }
 
   // 3. what is running right now — plus the operator, which lives in the shared `jr2-system`.
@@ -116,11 +124,17 @@ export async function readRoots(kube: KubeAdmin, ctx: { context?: string } = {})
     for (const c of [...(spec.containers ?? []), ...(spec.initContainers ?? []), ...(spec.ephemeralContainers ?? [])]) {
       if (c.image) keep.add(c.image);
     }
+    for (const ref of volumeRefs(spec.volumes)) keep.add(ref);
   }
 
   return { keep, namespaces };
 }
 
+/** The refs a volume list mounts as `image` volumes — invisible to a read of containers alone. */
+function volumeRefs(volumes: VolumeSpec[] | undefined): string[] {
+  return (volumes ?? []).flatMap((v) => (v.image?.reference ? [v.image.reference] : []));
+}
+
 /**
  * Root #2's read, with the ONE degradation the fail-closed rule allows: a cluster that has no
  * `sandboxes.core.jr2.dev` resource type can hold no Sandbox CRs, so "no Sandboxes" is the complete