@jr2/cli 0.1.1 → 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.1",
+  "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.1"
+    "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/build.ts

@@ -998,30 +998,47 @@ const execCommand: RunCommand = async (command, args, cwd) => {
 
 /**
  * Materialize the Instance into `outDir` (ADR-0043, as amended there). Two shapes, and the key is
- * the INSTANCE's own: walk up for a `pnpm-workspace.yaml`, because that — not
- * {@link detectKitCheckout} — is what says whether `pnpm deploy` can run at all. A checkout CLI can
- * legitimately drive a standalone instance (the developer's `/tmp` folder), and keying on the CLI's
- * own provenance would send that instance down a path whose job — materializing workspace symlinks
- * — only exists in a workspace. The mirror holds too: an INSTALLED kit driving an instance nested
- * in the user's own pnpm monorepo takes `pnpm deploy`, because that instance carries no lockfile of
- * its own — the workspace root holds it.
+ * the INSTANCE's own, asked in this order:
  *
- * - Workspace member (the kit checkout's `templates/*` and `features/kind-instance`): `pnpm deploy
- *   --legacy`, unchanged. pnpm is a contributor prerequisite, like go for the operator, never a
- *   product dependency.
- * - Standalone: stage a copy ({@link BUNDLE_STAGE_EXCLUDE}) and run a frozen production install
- *   from the committed lockfile ({@link lockfileInstall}) inside it.
+ * 1. Its own lockfile. An instance that carries one is self-contained — the lockfile IS its
+ *    dependency graph, wherever the folder sits — so it is staged as a copy
+ *    ({@link BUNDLE_STAGE_EXCLUDE}) and installed frozen and production-only by the lockfile's own
+ *    package manager ({@link lockfileInstall}). This is how a standalone instance committed INSIDE
+ *    a pnpm monorepo bundles: the kit's own `docs/intro` sits under the checkout's
+ *    `pnpm-workspace.yaml` and is deliberately not one of its packages.
+ * 2. A `pnpm-workspace.yaml` above it. A workspace member carries no lockfile of its own — the
+ *    workspace root holds it — so it is the ABSENCE of one that sends the instance to `pnpm deploy
+ *    --legacy`, unchanged. pnpm is a contributor prerequisite, like go for the operator, never a
+ *    product dependency.
+ * 3. Neither: {@link lockfileInstall}'s named refusal.
+ *
+ * Neither key is {@link detectKitCheckout}: a checkout CLI legitimately drives a standalone
+ * instance (the developer's `/tmp` folder), and an installed kit legitimately drives a member of
+ * the user's own monorepo. Asking "is there a workspace file above me" FIRST — the previous rule —
+ * answered a question about an ancestor, and sent shape (1) down `pnpm deploy`, which pnpm answers
+ * for a non-member with "No projects matched the filters" and exit 0: no bundle, and the failure
+ * surfaced later as an ENOENT from the seal. That silent success is why the deploy branch checks
+ * that the bundle exists, and names the shape when it does not.
  */
 export async function bundleInstance(
   instanceDir: string,
   outDir: string,
   run: RunCommand = execCommand,
 ): Promise<void> {
-  if (await pnpmWorkspaceRoot(instanceDir)) {
+  const root = (await hasOwnLockfile(instanceDir)) ? undefined : await pnpmWorkspaceRoot(instanceDir);
+  if (root) {
     const pkg = JSON.parse(await readFile(join(instanceDir, "package.json"), "utf8")) as { name?: string };
     if (!pkg.name) throw new Error(`${instanceDir}/package.json has no "name" — needed to bundle the instance`);
     // --legacy: materialize (copy) workspace deps into the bundle rather than linking them.
     await run("pnpm", ["--filter", pkg.name, "--prod", "deploy", "--legacy", outDir], instanceDir);
+    // pnpm exits 0 — "No projects matched the filters" — for a `--filter` that names no member.
+    if (!(await exists(outDir))) {
+      throw new Error(
+        `pnpm deploy wrote no bundle for ${instanceDir}: it sits under the pnpm workspace at ${root} but is not ` +
+          `one of its packages, and it has no lockfile of its own — add it to the workspace's \`packages:\`, ` +
+          `or install and commit a lockfile so it bundles as a standalone instance`,
+      );
+    }
     return;
   }
   // Asked before the copy: an instance with no lockfile must fail on the cheap half.
@@ -1033,9 +1050,26 @@ export async function bundleInstance(
   await run(command, args, outDir);
 }
 
-/** The nearest `pnpm-workspace.yaml` at or above `dir`, i.e. "is this instance a workspace member".
- * A file test, not a manifest parse: pnpm's own membership rule starts here, and a `packages:` glob
- * that excluded this directory would leave `pnpm deploy --filter` failing loudly by name. */
+/** Whether the instance carries a lockfile of ANY manager — yarn included, so a yarn instance under
+ * a workspace reaches {@link lockfileInstall}'s named refusal rather than `pnpm deploy`. */
+async function hasOwnLockfile(instanceDir: string): Promise<boolean> {
+  const present = new Set(await readdir(instanceDir));
+  return [...LOCKFILE_INSTALLS.flatMap((row) => row.lockfiles), YARN_LOCKFILE].some((f) => present.has(f));
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The nearest `pnpm-workspace.yaml` at or above `dir`. A file test, not a manifest parse:
+ * membership proper is pnpm's to decide, and this is asked only for an instance with no lockfile of
+ * its own ({@link bundleInstance}). A `packages:` glob that excludes the directory does NOT fail
+ * `pnpm deploy --filter` — pnpm exits 0 having deployed nothing — which the caller checks. */
 async function pnpmWorkspaceRoot(dir: string): Promise<string | undefined> {
   let d = resolve(dir);
   for (;;) {

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;
+  }
+}