@jr2/cli 0.1.2 → 0.1.3

package/README.md

@@ -15,4 +15,9 @@ jr2 run <workflow>
 Orchestrator, Sandboxes, secrets), and every other verb (`run`, `runs`, `status`, `logs`, `send`, `down`, `gc`,
 `kit push`) talks to what `up` deployed. Node 24, a kube context, and docker for the image `up` builds.
 
+Inside an Instance, the global `jr2` hands off to the Instance's own `@jr2/cli` (the gulp model), so the version that
+runs is the one the Instance pins and the global's stops mattering. An Instance has one kit version: `@jr2/cli` and
+`@jr2/orchestrator` at the same exact number — every verb refuses a mismatch by name. Upgrade by editing both lines and
+reinstalling.
+
 Docs, glossary, and architecture decisions: [github.com/snapwich/jr2](https://github.com/snapwich/jr2).

package/bin/jr2.js

@@ -9,8 +9,12 @@
 // bundle solves the same problem with `tsx` (see INSTANCE_DOCKERFILE) because there the entry is
 // the orchestrator's, not this one.
 //
-// After the hook it does nothing but hand argv to `main` and surface the exit code. `main` is
-// pure-ish (takes an injectable IO) so the dispatch + commands stay unit-testable without a process.
+// After the hook, the launcher's one decision (ADR-0056): inside an Instance that resolves its own
+// `@jr2/cli` to a different copy, hand off — run THAT copy's binary with the same argv and stdio
+// and exit with its code — so the `jr2` that runs is the one the Instance pins, whatever this one's
+// version is. Otherwise hand argv to `main` and surface the exit code. `main` is pure-ish (takes an
+// injectable IO) so the dispatch + commands stay unit-testable without a process. The handoff
+// modules import no kit code: a global with no orchestrator beside it can still hand off.
 
 import { readFileSync } from "node:fs";
 import { registerHooks } from "node:module";
@@ -31,8 +35,12 @@ registerHooks({
   },
 });
 
-const { main } = await import("../src/cli.ts");
-
-main(process.argv.slice(2)).then((code) => {
-  process.exitCode = code;
-});
+const argv = process.argv.slice(2);
+const { handoffTarget, handoff } = await import("../src/handoff.ts");
+const local = handoffTarget(process.cwd());
+if (local) {
+  process.exitCode = await handoff(local, argv);
+} else {
+  const { main } = await import("../src/cli.ts");
+  process.exitCode = await main(argv);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jr2/cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "The jr2 CLI: init, up, run — the interface to a jr2 Instance.",
   "license": "MIT",
   "private": false,
@@ -36,13 +36,16 @@
   },
   "types": "./src/index.ts",
   "dependencies": {
-    "ts-blank-space": "^0.9.0",
-    "@jr2/orchestrator": "0.1.2"
+    "ts-blank-space": "^0.9.0"
+  },
+  "peerDependencies": {
+    "@jr2/orchestrator": "0.1.3"
   },
   "devDependencies": {
     "@types/node": "^26.0.1",
     "xstate": "^5.18.0",
-    "zod": "^4.4.3"
+    "zod": "^4.4.3",
+    "@jr2/orchestrator": "0.1.3"
   },
   "files": [
     "bin",

package/src/commands/init.ts

@@ -13,19 +13,22 @@
 // Templates mirror `templates/default/` verbatim (that folder is the model instance, ADR-0054) —
 // byte-for-byte except package.json's `name`/`description`, which are per-instance.
 // `test/init.test.ts` enforces that; without it the two drift silently, and since the manifest
-// carries KIT_VERSION that same test is the version-bump tripwire (bump the kit, re-render the
+// carries the kit version that same test is the version-bump tripwire (bump the kit, re-render the
 // template). Existing files are left untouched (init is additive); created paths are reported on
 // stderr.
 //
 // ONE template serves both checkout and installed mode (ADR-0043) — a branch there would mean the
 // tested output and the shipped output diverge. So the scaffold names no package manager, and pins
-// @jr2/* at the exact running KIT_VERSION: 0.x minors break, and the checkout resolves that literal
-// to its own packages via `linkWorkspacePackages: true`.
+// @jr2/* at the exact running version: 0.x minors break, and the checkout resolves that literal
+// to its own packages via `linkWorkspacePackages: true`. The number is the CLI's OWN (ADR-0056),
+// not the orchestrator's `KIT_VERSION`: a global `jr2` with no Instance around it must scaffold
+// without a peer resolved, and the two numbers are equal by construction (one release train,
+// lockstep — ADR-0055).
 
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 import { parseArgs } from "node:util";
-import { KIT_VERSION } from "@jr2/orchestrator";
+import { CLI_VERSION } from "../kit-version.ts";
 import { activity, type Io } from "../output.ts";
 
 export async function init(args: string[], io: Io): Promise<number> {
@@ -90,8 +93,8 @@ function packageJson(name: string): string {
       private: true,
       type: "module",
       scripts: { typecheck: "tsc --noEmit" },
-      dependencies: { "@jr2/orchestrator": KIT_VERSION, xstate: "^5.18.0" },
-      devDependencies: { "@jr2/cli": KIT_VERSION, "@types/node": "^26.0.1", typescript: "^5.6.0" },
+      dependencies: { "@jr2/orchestrator": CLI_VERSION, xstate: "^5.18.0" },
+      devDependencies: { "@jr2/cli": CLI_VERSION, "@types/node": "^26.0.1", typescript: "^5.6.0" },
     },
     null,
     2,

package/src/env.ts

@@ -16,7 +16,7 @@
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { findRoot } from "./instance.ts";
+import { findRoot } from "./root.ts";
 import { activity, type Io } from "./output.ts";
 
 /**

package/src/handoff.ts

@@ -0,0 +1,44 @@
+// The Handoff (ADR-0056, the gulp/grunt model): a global `jr2` run inside an Instance that resolves
+// its own `@jr2/cli` to a DIFFERENT copy runs that copy's binary with the same arguments and stdio,
+// returns its exit code, and does nothing else. So the copy that runs is the one the Instance pins,
+// and the global's version stops mattering inside an Instance. No Instance, or the Instance resolves
+// the running copy itself (a workspace member in the checkout, `npx jr2`): no handoff.
+//
+// Spawn, not import. gulp loads local gulp in-process because local gulp is a LIBRARY; here the
+// local is a BINARY, and spawning couples the global to one contract — the package's `bin` field,
+// npm's own — where importing `src/cli.ts` would make the local's internal layout a cross-version
+// API the global (the copy that cannot be updated once shipped) must honor forever. The local's own
+// preamble runs: its pinned erasure hook, whatever a future bin adds.
+//
+// Builtins only, like everything the launcher runs before it knows which `jr2` will run.
+
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { CLI_ROOT, resolvePackage } from "./kit-version.ts";
+import { findRoot } from "./root.ts";
+
+/** The local binary to hand off to, or `undefined` when this copy is the one that runs. */
+export function handoffTarget(cwd: string, selfRoot: string = CLI_ROOT): string | undefined {
+  const root = findRoot(cwd);
+  if (!root) return undefined;
+  const local = resolvePackage("@jr2/cli", root);
+  if (!local || local.root === selfRoot) return undefined;
+  const bin = typeof local.bin === "string" ? local.bin : local.bin?.jr2;
+  return bin ? join(local.root, bin) : undefined;
+}
+
+/** Run `bin` with `argv` on this node, sharing stdio; resolves to its exit code. A child that dies
+ * by signal re-raises that signal here, so the shell sees what it would have seen. */
+export function handoff(bin: string, argv: string[]): Promise<number> {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [bin, ...argv], { stdio: "inherit" });
+    child.on("error", (err) => {
+      process.stderr.write(`error: cannot run ${bin}: ${err.message}\n`);
+      resolve(1);
+    });
+    child.on("exit", (code, signal) => {
+      if (signal) process.kill(process.pid, signal);
+      resolve(code ?? 1);
+    });
+  });
+}

package/src/index.ts

@@ -6,6 +6,7 @@ export { JR2Client } from "./client.ts";
 export type { RunStatus, RunFeedEvent, RunEvent, FetchLike } from "./client.ts";
 export type { Io } from "./output.ts";
 export { resolveRoot, resolveTarget } from "./instance.ts";
+export { assertKitVersion, resolvePackage, CLI_VERSION } from "./kit-version.ts";
 export type { Target, TargetOptions } from "./instance.ts";
 export { kubectlKube } from "./kube.ts";
 export type { KubePort } from "./kube.ts";

package/src/instance.ts

@@ -2,7 +2,9 @@
 // folder we are in, and WHERE its deployed orchestrator is.
 //
 //   - `resolveRoot` walks up from cwd to the dir holding `jr2.config.ts` — the root marker (mirrors
-//     flue's `flue.config.ts`).
+//     flue's `flue.config.ts`) — and refuses unless that Instance and this CLI resolve the same
+//     `@jr2/orchestrator` (ADR-0056: an Instance has one Kit version). Every Instance verb goes
+//     through it; `--url` verbs skip the walk and so skip the check.
 //   - `resolveTarget` finds the orchestrator. `--url` / `JR2_URL` (+ `JR2_TOKEN`) short-circuits
 //     everything — the ingress-exposed/remote-caller escape hatch, no folder walk. Otherwise the
 //     DEPLOYMENT is addressed by the current kube context + the instance's namespace (`-n` >
@@ -11,27 +13,21 @@
 //     kube RBAC is the real gate, and no local state file can go stale (ADR-0019).
 //   - Every resolution prints its target on stderr, so ambient-context drift stays visible.
 
-import { existsSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { basename } from "node:path";
 import { loadConfig } from "@jr2/orchestrator";
 import { INSTANCE_SECRET, kubectlKube, ORCHESTRATOR_PORT, ORCHESTRATOR_SERVICE } from "./kube.ts";
+import { assertKitVersion } from "./kit-version.ts";
 import { activity, type Io } from "./output.ts";
+import { findRoot } from "./root.ts";
 
-/** Walk up from `cwd` to the directory containing `jr2.config.ts`; `undefined` if there is none. */
-export function findRoot(cwd: string): string | undefined {
-  let dir = cwd;
-  for (;;) {
-    if (existsSync(join(dir, "jr2.config.ts"))) return dir;
-    const parent = dirname(dir);
-    if (parent === dir) return undefined;
-    dir = parent;
-  }
-}
+export { findRoot } from "./root.ts";
 
-/** `findRoot`, for the callers that cannot proceed without one. */
+/** `findRoot` for the callers that cannot proceed without one — and the Kit version check, which
+ * every Instance verb therefore makes before it reads a byte of the Instance. */
 export function resolveRoot(cwd: string): string {
   const root = findRoot(cwd);
   if (!root) throw new Error("not inside a jr2 instance — no jr2.config.ts found walking up from cwd");
+  assertKitVersion(root);
   return root;
 }
 

package/src/kit-version.ts

@@ -0,0 +1,88 @@
+// An Instance has ONE Kit version (ADR-0056): the `@jr2/orchestrator` it resolves, because that is
+// what its image bakes. Published `@jr2/cli@X` used to DEPEND on `@jr2/orchestrator@X` exact, so an
+// Instance pinning any other orchestrator quietly held two copies — the CLI's `KIT_VERSION` named
+// 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.
+//
+// Builtins only: the launcher (`bin/jr2.js`) resolves through here before any kit import.
+
+import { readFileSync, realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type ResolvedPackage = {
+  /** The package's REAL root directory (symlinks resolved). */
+  root: string;
+  version: string;
+  bin?: string | Record<string, string>;
+};
+
+/**
+ * Resolve `name` the way code in `fromDir` would — Node resolution from that folder — and answer
+ * the package's real root. `undefined` when nothing resolves (no `node_modules` yet, or a global
+ * with no peer beside it). Walks up from the resolved ENTRY to the nearest manifest carrying the
+ * name, rather than resolving `<name>/package.json`, because an `exports` map hides the manifest
+ * and the kits already published export none.
+ */
+export function resolvePackage(name: string, fromDir: string): ResolvedPackage | undefined {
+  const require = createRequire(join(fromDir, "package.json"));
+  let entry: string;
+  try {
+    entry = realpathSync(require.resolve(name));
+  } catch {
+    return undefined;
+  }
+  let dir = dirname(entry);
+  for (;;) {
+    try {
+      const m = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as ResolvedPackage & { name?: string };
+      if (m.name === name) return { root: dir, version: m.version, bin: m.bin };
+    } catch {
+      // not a manifest, or not this package's — keep walking
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+/** This CLI's own real root and version — what `jr2 init` pins (ADR-0056), what the refusal names. */
+export const CLI_ROOT = realpathSync(fileURLToPath(new URL("..", import.meta.url)));
+export const CLI_VERSION = (JSON.parse(readFileSync(join(CLI_ROOT, "package.json"), "utf8")) as { version: string })
+  .version;
+
+const ORCHESTRATOR = "@jr2/orchestrator";
+const CLI = "@jr2/cli";
+
+/**
+ * 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.
+ */
+export function assertKitVersion(root: string): void {
+  const instance = resolvePackage(ORCHESTRATOR, root);
+  const own = resolvePackage(ORCHESTRATOR, CLI_ROOT);
+  if (instance && own && instance.root === own.root) return;
+
+  const manifest = join(root, "package.json");
+  const local = instance && resolvePackage(CLI, root);
+  const fix = !instance
+    ? `install the Instance's dependencies (${manifest} pins "${ORCHESTRATOR}" and "${CLI}" at one exact version)`
+    : local
+      ? `pin "${ORCHESTRATOR}" and "${CLI}" at ONE exact version in ${manifest} and reinstall`
+      : `add "${CLI}": "${instance.version}" to devDependencies in ${manifest} and reinstall — the Instance's ` +
+        `own jr2 then runs`;
+  const have = instance
+    ? `${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`;
+  throw new Error(`Kit version mismatch — an Instance has one (ADR-0056):\n  ${have}\n  ${self}\n  ${fix}`);
+}

package/src/root.ts

@@ -0,0 +1,17 @@
+// The Instance root walk (ADR-0009): up from `cwd` to the directory holding `jr2.config.ts`, the
+// root marker. Its own module — builtins only — because the launcher runs it BEFORE it knows which
+// `jr2` will run (ADR-0056), so nothing here may import the kit.
+
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** Walk up from `cwd` to the directory containing `jr2.config.ts`; `undefined` if there is none. */
+export function findRoot(cwd: string): string | undefined {
+  let dir = cwd;
+  for (;;) {
+    if (existsSync(join(dir, "jr2.config.ts"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}