@tokenoftrust/cli 1.3.4-rc.1 → 1.3.4-rc.3

package/bin/tot.cjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * The `tot` bin entry: an ES5-only CommonJS launcher whose ONLY job is to
+ * enforce the Node floor, then hand off to the real ESM CLI (bin/tot.mjs).
+ *
+ * Why this exists (and why it must stay ES5/CJS): `engines.node` is advisory —
+ * npm warns (EBADENGINE) and installs anyway. And the ESM entry can't guard
+ * itself: the module loader PARSES the whole static import graph before
+ * evaluating a single line, so on an old Node any modern syntax anywhere in
+ * src/ becomes a raw SyntaxError before a version check could run. A CJS file
+ * written in ES5 parses on every Node ever shipped, so THIS message — not a
+ * stack trace — is what a Node 10/12/14/16 user sees.
+ *
+ *   KEEP THIS FILE ES5: var, string concat, no arrow functions, no template
+ *   literals, no optional chaining, no const/let. The dynamic import() is
+ *   hidden inside new Function so old parsers never see the syntax.
+ */
+"use strict";
+
+// BY-NECESSITY COPY of the floor in src/ensure-node.mjs (this file can't import
+// ESM) — the floor is Astro's engines requirement, the recommendation is the
+// current LTS. A test asserts the two files stay in sync; bump BOTH together.
+var MIN_NODE = "22.12.0";
+var RECOMMENDED_NODE = "24";
+
+var nodeVersion = process.versions.node;
+var have = nodeVersion.split(".");
+var floor = MIN_NODE.split(".");
+var meets = false;
+for (var i = 0; i < 3; i++) {
+  var h = parseInt(have[i], 10) || 0;
+  var f = parseInt(floor[i], 10) || 0;
+  if (h !== f) { meets = h > f; break; }
+  if (i === 2) meets = true; // equal on all three parts
+}
+
+if (!meets) {
+  process.stderr.write(
+    "✗ tot needs Node 22.12 or newer — you're on Node " + nodeVersion + ".\n" +
+      "  → next: install Node " + RECOMMENDED_NODE + " (LTS) — nvm: `nvm install " + RECOMMENDED_NODE +
+      " && nvm use " + RECOMMENDED_NODE + "`, or https://nodejs.org/ — then re-run the same command.\n"
+  );
+  process.exit(1);
+}
+
+// Supported Node from here on. Hand off to the ESM CLI; pathToFileURL keeps
+// the import specifier correct on Windows drive-letter paths too.
+var path = require("path");
+var pathToFileURL = require("url").pathToFileURL;
+var entry = pathToFileURL(path.join(__dirname, "tot.mjs")).href;
+
+// new Function with a CONSTANT body ("return import(u)") — nothing is ever
+// interpolated into the code string; the entry URL travels as an argument. This
+// indirection exists only so pre-import() parsers never see the import syntax.
+new Function("u", "return import(u)")(entry).catch(function (e) {
+  // tot.mjs formats + exits on its own errors; landing here means the CLI
+  // itself failed to LOAD on a supported Node — a packaging bug, worth the detail.
+  process.stderr.write("✗ tot failed to start: " + ((e && e.message) || e) + "\n");
+  process.exit(1);
+});

package/bin/tot.mjs

@@ -25,6 +25,7 @@
  * fetches the published storefront runner; `tot checkout/validate/submit` are
  * pure Node. Dependency-free by design so `npm i -g @tokenoftrust/cli` stays light.
  */
+import "../src/ensure-node.mjs"; // hard Node-version gate — must stay first (see the module doc)
 import { readFileSync } from "node:fs";
 import { detectContext } from "../src/context.mjs";
 import { printError } from "../src/errors.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.3.4-rc.1",
+  "version": "1.3.4-rc.3",
   "description": "Token of Trust developer CLI — check out a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",
@@ -20,7 +20,7 @@
   ],
   "type": "module",
   "bin": {
-    "tot": "./bin/tot.mjs"
+    "tot": "./bin/tot.cjs"
   },
   "files": [
     "bin",
@@ -29,7 +29,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22.12.0"
   },
   "publishConfig": {
     "access": "public",

package/src/commands/checkout.mjs

@@ -23,6 +23,7 @@ import { promisify } from "node:util";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
+import { writeNvmrc } from "../sample.mjs";
 
 const execFileP = promisify(execFile);
 
@@ -206,6 +207,7 @@ async function cloneRepo(gitRemote, dir, redact) {
     });
   }
   const head = (await git(["-C", dir, "log", "-1", "--oneline"])).trim();
+  writeNvmrc(dir); // version-manager hooks land on a supported Node on cd
   return { dir, head };
 }
 

package/src/commands/dev.mjs

@@ -32,7 +32,7 @@
  * either way.
  */
 import { spawn, spawnSync, execFileSync } from "node:child_process";
-import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, rmSync, readdirSync, createWriteStream, openSync, closeSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, rmSync, readdirSync, createWriteStream, openSync, closeSync, writeSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { createHash } from "node:crypto";
@@ -435,12 +435,24 @@ export async function resolveRendererSource(args, { client } = {}) {
  * version, so a mismatch is visible, not silent. If nothing exact/minor/≤-ceiling is
  * published, we THROW — a release gap to fix by publishing the aligned runner, not paper over.
  *
+ * PIN-DIRECTION DECISION (ADR 0011 — don't relitigate inline): the runner version
+ * should be DECLARED BY THE PRODUCT, not derived from the CLI's identity. The
+ * ladder below reflects the migration:
+ *   1. explicit flag/env pin        — developer intent, always wins
+ *   2. declaredVersion              — the STORE's own `.tot/config.json#runnerVersion`
+ *                                     (rust-toolchain.toml-style; the target state)
+ *   3. exact CLI-version match      — TRANSITIONAL lockstep rung. Delete it (and the
+ *                                     lockstep publish regime) once tenant_checkout
+ *                                     stamps runnerVersion into every checkout —
+ *                                     see ADR 0011 for the exit criteria.
+ *   4. CLI-minor / ≤-ceiling        — degraded-but-safe fallbacks (never a floating tag)
+ *
  * Pure (no I/O) for testability.
  * @param {any} meta npm packument (`dist-tags` + `versions`)
- * @param {{ cliVersion: string, explicitPin?: string|null }} opts
+ * @param {{ cliVersion: string, explicitPin?: string|null, declaredVersion?: string|null }} opts
  * @returns {{ version: string, reason: string }}
  */
-export function pickRunnerVersion(meta, { cliVersion, explicitPin }) {
+export function pickRunnerVersion(meta, { cliVersion, explicitPin, declaredVersion }) {
   const distTags = meta?.["dist-tags"] || {};
   const versions = Object.keys(meta?.versions || {});
 
@@ -457,12 +469,21 @@ export function pickRunnerVersion(meta, { cliVersion, explicitPin }) {
   };
 
   // 1) Explicit pin (flag/env): the deliberate escape hatch — honored verbatim,
-  // INCLUDING above the ceiling (someone testing a newer runner on purpose). This is
-  // the ONLY way past the ceiling; every automatic path below respects it.
+  // INCLUDING above the ceiling (someone testing a newer runner on purpose).
   if (explicitPin) {
     return { version: distTags[explicitPin] || explicitPin, reason: `pinned ${explicitPin}` };
   }
 
+  // 1.5) PRODUCT-DECLARED version (ADR 0011): the store's checkout says which runner
+  // it runs — the CLI is just the resolver. Honored verbatim when published, INCLUDING
+  // above the ceiling: a declaration newer than this CLI means the CLI is what's stale
+  // (the caller nudges an update), not that the product is wrong. A declaration that
+  // ISN'T published is a product release gap — fall through to the normal ladder
+  // rather than hard-failing the developer's loop (the caller warns loudly).
+  if (declaredVersion && versions.includes(declaredVersion)) {
+    return { version: declaredVersion, reason: "declared by the store checkout (runnerVersion)" };
+  }
+
   // 2) EXACT CLI-version match — the primary path for a lockstep release: the runner
   // is published at the SAME version as the CLI (incl. prereleases like 1.3.0-rc.0,
   // which the stable-only minor match below deliberately skips). This is what makes
@@ -507,6 +528,28 @@ export function pickRunnerVersion(meta, { cliVersion, explicitPin }) {
   );
 }
 
+/**
+ * The runner version a store checkout DECLARES for itself (ADR 0011) — the
+ * `runnerVersion` field of `<workspace>/.tot/config.json`. This is the
+ * rust-toolchain.toml of the storefront: the PRODUCT (via tenant_checkout
+ * stamping it server-side) owns which runtime the store runs; the CLI just
+ * resolves it. Returns null when absent/malformed/not-semver — silence is
+ * correct: an undeclared checkout falls back to the transitional lockstep rung.
+ * Pure-ish (one file read) + exported for tests.
+ * @param {string|null|undefined} workspaceDir
+ * @returns {string|null}
+ */
+export function declaredRunnerVersion(workspaceDir) {
+  if (!workspaceDir) return null;
+  try {
+    const cfg = JSON.parse(readFileSync(join(workspaceDir, ".tot", "config.json"), "utf8"));
+    const v = cfg?.runnerVersion;
+    return typeof v === "string" && /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(v) ? v : null;
+  } catch {
+    return null;
+  }
+}
+
 /** Parse the numeric {major, minor} from a semver (prerelease suffix ignored). Null if unparseable. */
 export function majorMinor(v) {
   const m = /^(\d+)\.(\d+)\./.exec(String(v || ""));
@@ -531,7 +574,7 @@ function compareStableAsc(a, b) {
  * override with `--renderer-version` / TOT_RUNNER_VERSION. Package/registry
  * overridable via env for testing.
  */
-export async function resolvePublicRendererSource(args, env = process.env) {
+export async function resolvePublicRendererSource(args, env = process.env, { declaredVersion = null } = {}) {
   const pkg = env.TOT_RUNNER_PACKAGE || PUBLIC_RUNNER_PACKAGE;
   const registry = (env.TOT_NPM_REGISTRY || DEFAULT_NPM_REGISTRY).replace(/\/$/, "");
   const explicitPin = args.rendererVersion || env.TOT_RUNNER_VERSION || null;
@@ -541,11 +584,29 @@ export async function resolvePublicRendererSource(args, env = process.env) {
     throw new Error(`npm metadata for ${pkg} failed: HTTP ${res.status} ${res.statusText}`);
   }
   const meta = await res.json();
-  const { version, reason } = pickRunnerVersion(meta, { cliVersion: CLI_VERSION, explicitPin });
-  // Exact is the goal (lockstep publish → runner@CLI_VERSION always present). If we
-  // resolved something ELSE, the versions are skewed — surface it LOUDLY instead of
-  // silently running a mismatched runner (the class of bug this whole change targets).
-  if (!explicitPin && version !== CLI_VERSION) {
+  const { version, reason } = pickRunnerVersion(meta, { cliVersion: CLI_VERSION, explicitPin, declaredVersion });
+  if (!explicitPin && declaredVersion) {
+    if (version === declaredVersion) {
+      // The product-declared path (ADR 0011) — the intended steady state, not skew.
+      // A declaration NEWER than this CLI means the CLI is the stale half: nudge.
+      const mm = majorMinor(declaredVersion);
+      const cliMM = majorMinor(CLI_VERSION);
+      if (mm && cliMM && (mm.major > cliMM.major || (mm.major === cliMM.major && mm.minor > cliMM.minor))) {
+        console.warn(
+          `  ~ this store declares runner ${declaredVersion}, newer than your CLI (${CLI_VERSION}) — ` +
+            `if anything misbehaves: npm i -g @tokenoftrust/cli@latest`,
+        );
+      }
+    } else {
+      console.warn(
+        `  ⚠ this store declares runner ${declaredVersion} but that version isn't on npm — ` +
+          `using ${version} (${reason}). The store's runnerVersion needs a published release.`,
+      );
+    }
+  } else if (!explicitPin && version !== CLI_VERSION) {
+    // No declaration (transitional lockstep regime — ADR 0011): exact is the goal.
+    // Resolving something ELSE means CLI/runner releases are skewed — say so LOUDLY
+    // instead of silently running a mismatched runner.
     console.warn(
       `  ⚠ runner ${version} — no exact @${CLI_VERSION} published (${reason}). ` +
         `CLI/runner versions are SKEWED; publish the runner at ${CLI_VERSION} to align ` +
@@ -733,26 +794,31 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env, cache
   }
 
   // kind === "none" — no override, not in the monorepo: fetch the PUBLIC runner
-  // from npm, PINNED to this CLI's version. No MCP, no entitlement, no login.
+  // from npm. Version = what the STORE declares (ADR 0011), else pinned to this
+  // CLI's version (transitional lockstep). No MCP, no entitlement, no login.
   const explicitPin = args.rendererVersion || env.TOT_RUNNER_VERSION || null;
-
-  // Fully-offline fast path: when the runner published lockstep at this exact CLI
-  // version is already cached, reuse it without touching npm — honouring "don't
-  // hit npm when the RIGHT version is already cached" without ever reusing a
-  // version the pin didn't choose. Safe because `public-<CLI_VERSION>` only exists
-  // if a prior run fetched exactly that (pinned) version. Skipped when an explicit
-  // pin is set (that must go through resolution).
+  const declared = declaredRunnerVersion(args.workspace || ctx?.workspacePath);
+  const wantVersion = declared || CLI_VERSION;
+
+  // Fully-offline fast path: when the WANTED version (declared, else lockstep) is
+  // already cached, reuse it without touching npm — honouring "don't hit npm when
+  // the RIGHT version is already cached" without ever reusing a version the
+  // resolution wouldn't choose. Safe because `public-<version>` only exists if a
+  // prior run fetched exactly that version. Skipped when an explicit pin is set
+  // (that must go through resolution).
   if (!explicitPin) {
-    const exact = pinnedPublicCacheDir(cacheRoot, CLI_VERSION);
+    const exact = pinnedPublicCacheDir(cacheRoot, wantVersion);
     if (exact) {
-      // Trust-but-verify: a `public-<CLI_VERSION>` dir SHOULD be a current runner,
+      // Trust-but-verify: a `public-<version>` dir SHOULD be a current runner,
       // but if it can't report its own version it predates the --version surface
       // (a corrupt/half-migrated cache) — force a fresh fetch rather than run a
       // runner we can't identify. When it DOES answer, reuse it (fully offline-safe).
       if (probeRunnerVersion(exact)) {
-        console.error(`~ renderer: cached public runner ${CLI_VERSION} (matches this CLI)`);
-        setRunnerVersion(CLI_VERSION);
-        prunePublicRunnerCache(cacheRoot, CLI_VERSION);
+        console.error(
+          `~ renderer: cached public runner ${wantVersion} (${declared ? "declared by this store" : "matches this CLI"})`,
+        );
+        setRunnerVersion(wantVersion);
+        prunePublicRunnerCache(cacheRoot, wantVersion);
         return exact;
       }
       console.error(`~ renderer: cached runner at ${exact} can't report a version — refetching (forced upgrade)`);
@@ -762,7 +828,7 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env, cache
 
   let pub;
   try {
-    pub = await resolvePublicRendererSource(args, env);
+    pub = await resolvePublicRendererSource(args, env, { declaredVersion: declared });
   } catch (e) {
     // OFFLINE / npm unreachable — no way to resolve the pinned version. Last
     // resort: reuse ANY complete cached runner rather than hard-failing `tot dev`.
@@ -852,10 +918,12 @@ export async function installRunnerTarball({ source, version, isUrl = true, stri
     // reach) — an invited dev's machine config must never decide where the
     // runner's public deps come from. A project-level .npmrc wins over the user's.
     writeFileSync(join(stagingDir, ".npmrc"), "registry=https://registry.npmjs.org/\n");
-    ensureCorepackPnpm(stagingDir);
     // The install is the long, noisy step — tick a spinner while its output goes
     // to a log, so the terminal shows one clean line instead of the pnpm firehose.
+    // corepack setup logs to the SAME file so its failures aren't invisible (they
+    // were the silent cause of "couldn't set up the store preview engine").
     const installLog = join(RENDERER_CACHE_ROOT, `${version}.install.log`);
+    ensureCorepackPnpm(stagingDir, { logPath: installLog });
     const installSpin = startProgress("installing the store preview engine…", {
       stages: [{ afterMs: 20000, text: "still setting up the preview engine (first run only)…" }],
     });
@@ -919,7 +987,7 @@ function extractTarball(archivePath, destDir, { strip = 0 } = {}) {
  * itself is missing (very old Node), pnpm install below will surface that
  * clearly instead.
  */
-function ensureCorepackPnpm(runnerDir) {
+function ensureCorepackPnpm(runnerDir, { logPath } = {}) {
   const pkgPath = join(runnerDir, "package.json");
   if (!existsSync(pkgPath)) return;
   let pm;
@@ -929,8 +997,22 @@ function ensureCorepackPnpm(runnerDir) {
     return;
   }
   if (!pm) return;
-  spawnSync("corepack", ["enable"], { stdio: "ignore" });
-  spawnSync("corepack", ["prepare", pm, "--activate"], { stdio: "ignore" });
+  const fd = logPath ? openSync(logPath, "a") : null;
+  try {
+    // `enable` writes global shims (needs write access to the Node bin dir — an
+    // invited dev often lacks it); `prepare --activate` caches+activates the
+    // pinned pnpm in corepack's OWN store, which `corepack pnpm …` can then run
+    // WITHOUT the global shim (see runPnpmInstall's fallback). Capture both to the
+    // log — a silent corepack failure was why the install error carried no cause.
+    for (const args of [["enable"], ["prepare", pm, "--activate"]]) {
+      const r = spawnSync("corepack", args, { stdio: ["ignore", fd ?? "ignore", fd ?? "ignore"] });
+      if (fd !== null && (r.error || r.status !== 0)) {
+        writeSync(fd, `[tot] corepack ${args.join(" ")} → ${r.error?.code || r.error?.message || `exit ${r.status}`}\n`);
+      }
+    }
+  } finally {
+    if (fd !== null) closeSync(fd);
+  }
 }
 
 /**
@@ -942,18 +1024,51 @@ function ensureCorepackPnpm(runnerDir) {
  */
 function runPnpmInstall(runnerDir, { logPath } = {}) {
   const fd = logPath ? openSync(logPath, "a") : null;
+  const installArgs = ["install", "--config.dangerouslyAllowAllBuilds=true"];
+  // npm FIRST: it ships with EVERY Node (including 25+, where corepack is no
+  // longer bundled), so it's the launcher with zero machine-specific setup —
+  // no global pnpm, no corepack shim dance. The runner tree is built to be
+  // npm-installable (build-runner.mjs rewrites `workspace:*` → "*" and emits an
+  // npm `workspaces` field; verified end-to-end with both installers). pnpm and
+  // the corepack-pinned pnpm remain as fallbacks for hosts with a broken npm.
+  // If a launcher isn't installed at all (ENOENT) we move on; a launcher that
+  // RAN but whose install failed is the real error and stops the loop.
+  // REQUIRES a runner >= 1.3.4-rc.2 — older runner tarballs still carry
+  // `workspace:*` deps npm rejects (harmless here: pickRunnerVersion pins the
+  // runner to this CLI's version, so this CLI never installs those).
+  const attempts = [
+    { cmd: "npm", args: ["install", "--no-audit", "--no-fund"] },
+    { cmd: "pnpm", args: installArgs },
+    { cmd: "corepack", args: ["pnpm", ...installArgs] },
+  ];
   try {
-    const r = spawnSync("pnpm", ["install", "--config.dangerouslyAllowAllBuilds=true"], {
-      cwd: runnerDir,
-      // Send both streams to the log fd (or swallow them) — never inherit.
-      stdio: ["ignore", fd ?? "ignore", fd ?? "ignore"],
-    });
-    if (r.status !== 0) {
-      throw new Error(
+    for (const { cmd, args } of attempts) {
+      const r = spawnSync(cmd, args, {
+        cwd: runnerDir,
+        // Send both streams to the log fd (or swallow them) — never inherit.
+        stdio: ["ignore", fd ?? "ignore", fd ?? "ignore"],
+      });
+      if (r.status === 0) return; // installed
+      if (r.error?.code === "ENOENT") {
+        // This launcher isn't on the machine — record it and try the next one.
+        if (fd !== null) writeSync(fd, `[tot] ${cmd} not found (ENOENT) — trying the next launcher\n`);
+        continue;
+      }
+      // The launcher ran; the install itself failed. That's the actionable error.
+      throw new CliError(
         `couldn't set up the store preview engine${pnpmFailureHint(logPath)}` +
           (logPath ? `\n     details: ${logPath}` : ""),
+        { next: "check the details log above, then re-run `tot start` (it resumes from the cache)" },
       );
     }
+    // Every launcher ENOENT'd → there's no pnpm on this machine and corepack
+    // couldn't provide one (corepack isn't bundled on Node 25+). npm ships with
+    // every Node, so `npm i -g pnpm` is the escape hatch that always exists.
+    throw new CliError(
+      "couldn't set up the store preview engine — pnpm isn't available on this machine" +
+        (logPath ? `\n     details: ${logPath}` : ""),
+      { next: "install pnpm with `npm i -g pnpm` (or `corepack enable`), then re-run `tot start`" },
+    );
   } finally {
     if (fd !== null) closeSync(fd);
   }

package/src/commands/doctor.mjs

@@ -23,6 +23,7 @@ import { existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { hasOperatorCreds } from "../auth.mjs";
+import { MIN_NODE, nodeMeetsFloor } from "../ensure-node.mjs";
 import { clientPackages, osLabel } from "../mcp.mjs";
 import { defaultCredentialsPath, readCredentials, isExpired } from "../token-store.mjs";
 import { dockerAvailable, tryStartDocker } from "./dev.mjs";
@@ -58,8 +59,25 @@ const USAGE = `tot doctor — is this machine ready to run the loop?
 export function collectChecks(_ctx, env = process.env) {
   const checks = [];
 
-  const nodeMajor = Number(process.versions.node.split(".")[0]);
-  checks.push({ name: "node >= 20", pass: nodeMajor >= 20, detail: `have ${process.versions.node}`, blocking: true });
+  checks.push({
+    name: `node >= ${MIN_NODE}`,
+    pass: nodeMeetsFloor(process.versions.node),
+    detail: `have ${process.versions.node}`,
+    blocking: true,
+  });
+
+  // Native Windows isn't a supported host for the local loop (the runner install
+  // + tar extraction assume a POSIX toolchain) — WSL is, and reports as linux
+  // here. Say so up front instead of letting `tot dev` fail with an opaque ENOENT.
+  const nativeWindows = process.platform === "win32";
+  checks.push({
+    name: "supported platform",
+    pass: !nativeWindows,
+    detail: nativeWindows
+      ? "native Windows isn't supported yet — run tot inside WSL (https://learn.microsoft.com/windows/wsl/install)"
+      : "macOS / Linux / WSL",
+    blocking: true,
+  });
 
   // Informational: the versions + OS this invocation is running on — the same
   // context the run banners/error footers stamp, surfaced up front for a bug report.

package/src/commands/start.mjs

@@ -49,6 +49,7 @@ import { resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 
 import { detectContext } from "../context.mjs";
+import { MIN_NODE, RECOMMENDED_NODE, nodeMeetsFloor } from "../ensure-node.mjs";
 import { createMcpClient, versionStamp } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { CliError, fail, formatError, exitCodeFor } from "../errors.mjs";
@@ -284,10 +285,9 @@ export async function run(argv, ctx) {
 async function runSampleStart(args, ctx, env, startedAt) {
   try {
     // Minimal preflight — the free path needs ONLY Node (no git, no Docker, no auth).
-    const nodeMajor = Number(process.versions.node.split(".")[0]);
-    if (nodeMajor < 20) {
-      throw new CliError(`Node 20+ is required (have ${process.versions.node})`, {
-        next: "upgrade Node, then re-run",
+    if (!nodeMeetsFloor(process.versions.node)) {
+      throw new CliError(`Node ${MIN_NODE}+ is required (have ${process.versions.node})`, {
+        next: `install Node ${RECOMMENDED_NODE} (LTS), then re-run`,
         exitCode: 2,
       });
     }

package/src/ensure-node.mjs

@@ -0,0 +1,44 @@
+/**
+ * The Node floor — single ESM source of truth — plus a runtime gate that is
+ * DEFENSE IN DEPTH behind bin/tot.cjs.
+ *
+ * THE FLOOR IS SET BY WHAT `tot dev` RUNS, not by the CLI's own code: the store
+ * preview engine is Astro (engines >=22.12.0) + wrangler (>=22). A CLI that let
+ * an older Node through would pass login/checkout and then fail deep inside the
+ * runner — the exact opaque dead-end this gate exists to prevent. Keep MIN_NODE
+ * aligned with the runner's real dependency floor when upgrading Astro.
+ *
+ * `engines.node` in package.json is advisory: `npm i -g` prints EBADENGINE and
+ * installs anyway (only `engine-strict=true` blocks it), so the floor must be
+ * enforced at runtime. The PRIMARY gate is bin/tot.cjs (the ES5 CommonJS
+ * launcher): ESM parses the entire static import graph before evaluating
+ * anything, so a check inside the .mjs world can be preempted by a SyntaxError
+ * on a Node old enough to matter. bin/tot.cjs carries a BY-NECESSITY COPY of
+ * this floor (it can't import ESM) — a test keeps the two in sync. This module
+ * re-runs the same check on the ESM side for anyone invoking `node bin/tot.mjs`
+ * directly (bypassing the bin shim). SIDE-EFFECTING BY DESIGN; bin/tot.mjs
+ * imports it first.
+ */
+export const MIN_NODE = "22.12.0"; // Astro's engines floor — see the module doc
+export const RECOMMENDED_NODE = "24"; // current LTS — what the fix-it copy suggests
+
+/** Does `version` (e.g. "22.12.0") meet the MIN_NODE floor? */
+export function nodeMeetsFloor(version) {
+  const [maj = 0, min = 0, pat = 0] = String(version).split(".").map((n) => parseInt(n, 10) || 0);
+  const [fMaj, fMin, fPat] = MIN_NODE.split(".").map((n) => parseInt(n, 10));
+  return maj !== fMaj ? maj > fMaj : min !== fMin ? min > fMin : pat >= fPat;
+}
+
+/** The house-style gate failure, shared by this module and (as copy) bin/tot.cjs. */
+export function floorMessage(haveVersion) {
+  return (
+    `✗ tot needs Node ${MIN_NODE.replace(/\.0$/, "")} or newer — you're on Node ${haveVersion}.\n` +
+    `  → next: install Node ${RECOMMENDED_NODE} (LTS) — nvm: \`nvm install ${RECOMMENDED_NODE} && nvm use ${RECOMMENDED_NODE}\`, ` +
+    `or https://nodejs.org/ — then re-run the same command.\n`
+  );
+}
+
+if (!nodeMeetsFloor(process.versions.node)) {
+  process.stderr.write(floorMessage(process.versions.node));
+  process.exit(1);
+}

package/src/sample.mjs

@@ -28,11 +28,55 @@
 import {
   cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync,
 } from "node:fs";
+import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { dirname, join, resolve } from "node:path";
+import { RECOMMENDED_NODE, nodeMeetsFloor } from "./ensure-node.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url)); // packages/cli/src
 
+/**
+ * Drop an `.nvmrc` into a fresh checkout/scaffold (when the repo doesn't carry
+ * one). Inert text — but nvm/fnm/asdf all read it, so developers with
+ * version-manager shell hooks land on a supported Node just by cd-ing into
+ * their store, and a plain `nvm use` works with no argument. Best-effort:
+ * never fails the checkout.
+ * @param {string} dir @param {NodeJS.ProcessEnv} [env]
+ */
+export function writeNvmrc(dir, env = process.env) {
+  try {
+    const p = join(dir, ".nvmrc");
+    if (existsSync(p)) return; // the store repo's own pin wins
+    writeFileSync(p, pickNvmrcVersion(env) + "\n");
+  } catch {
+    /* a missing .nvmrc never blocks the loop */
+  }
+}
+
+/**
+ * The version `.nvmrc` should pin: the NEWEST Node the developer ALREADY has
+ * installed under nvm that meets the floor — so `nvm use` succeeds with zero
+ * new downloads — falling back to the recommended LTS major when nvm is absent
+ * or has nothing recent enough (there `nvm use` correctly prompts an install).
+ * Pure given env; exported for tests.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string}
+ */
+export function pickNvmrcVersion(env = process.env) {
+  try {
+    const root = join(env.NVM_DIR || join(homedir(), ".nvm"), "versions", "node");
+    const best = readdirSync(root)
+      .map((name) => /^v(\d+)\.(\d+)\.(\d+)$/.exec(name))
+      .filter((m) => m && nodeMeetsFloor(m.slice(1).join(".")))
+      .map((m) => m.slice(1).map(Number))
+      .sort((a, b) => b[0] - a[0] || b[1] - a[1] || b[2] - a[2])[0];
+    if (best) return best.join(".");
+  } catch {
+    /* no nvm dir — fall through to the LTS recommendation */
+  }
+  return RECOMMENDED_NODE;
+}
+
 /** The generic sample tenant the runner registers with a compliance block (see module doc). */
 export const SAMPLE_TENANT = "sample-store.example";
 /** Dotted scope → the runner's path-prefix route + registry lookup (must contain a dot per context.mjs). */
@@ -128,6 +172,7 @@ export function scaffoldSample(destDir, { force = false, log = () => {} } = {})
   }
   mkdirSync(join(dir, ".tot"), { recursive: true });
   writeFileSync(join(dir, ".tot", "config.json"), JSON.stringify(sampleConfig(), null, 2) + "\n");
+  writeNvmrc(dir); // version-manager hooks land on a supported Node on cd
 
   log(`  ✓ scaffolded a sample store → ${dir}`);
   return { dir, tenant: SAMPLE_TENANT, scope: SAMPLE_SCOPE, created: true };