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

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.2",
   "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";
@@ -852,10 +852,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 +921,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 +931,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 +958,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 };