@tokenoftrust/cli 1.3.0-rc.0 → 1.3.0-rc.2

package/bin/tot.mjs

@@ -58,12 +58,21 @@ tot — Token of Trust developer CLI
   tot ideas                 copy-paste AI prompts that reliably wow
   tot feedback "<msg>"      send feedback to Token of Trust (attaches recent activity)
   tot help                  show this help
+  tot --version             print the CLI version
 
 Run \`tot <command> --help\` for command-specific options.
 `);
 }
 
 async function dispatch(cmd, rest, ctx) {
+  if (cmd === "--version" || cmd === "-v" || cmd === "version") {
+    // Bare version so it's greppable + machine-parseable (e.g. `tot --version` →
+    // `1.3.0-rc.2`). The FIRST thing to check when diagnosing "am I on the new
+    // CLI?" — a bare `npm i -g @tokenoftrust/cli` lands `latest`, not `@next`.
+    console.log(VERSION);
+    return 0;
+  }
+
   if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
     usage();
     return cmd ? 0 : 2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.3.0-rc.0",
+  "version": "1.3.0-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",

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, createWriteStream } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, rmSync, readdirSync, createWriteStream } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { createHash } from "node:crypto";
@@ -46,7 +46,7 @@ import { CliError, fail, formatError } from "../errors.mjs";
 import { openBrowser, waitForServer, firstFreePort } from "../open.mjs";
 import {
   scaffoldSample, isSampleCheckout, sampleConfig,
-  resolveRendererSource as resolveLocalRendererSource, SAMPLE_DIR_NAME,
+  resolveRendererSource as resolveLocalRendererSource, newestCachedRunner, SAMPLE_DIR_NAME,
 } from "../sample.mjs";
 
 /** The published runner image (--docker fallback). Override with --image / TOT_DEV_IMAGE. */
@@ -180,9 +180,10 @@ async function runStandalone(workspace, args, ctx) {
  * Native boot against the PUBLIC/local renderer (no MCP, no
  * entitlement) — the fallback for a standalone checkout when the entitled
  * artifact isn't available. Mirrors runNative but resolves the renderer via
- * ensureSampleRenderer (env override → cached runner → in-tree monorepo →
- * public npm), which throws NativeArtifactUnavailableError when even the public
- * runner can't be fetched (offline) so the caller can drop to Docker.
+ * ensureSampleRenderer (env override → in-tree monorepo → version-pinned public
+ * npm, reusing the matching `public-<version>` cache), which throws
+ * NativeArtifactUnavailableError when even the public runner can't be fetched
+ * (offline) so the caller can drop to Docker.
  */
 async function runNativePublic(workspace, args, ctx) {
   const cfg = readWorkspaceConfig(workspace);
@@ -386,7 +387,15 @@ export function pickRunnerVersion(meta, { cliVersion, explicitPin }) {
     return { version: distTags[explicitPin] || explicitPin, reason: `pinned ${explicitPin}` };
   }
 
-  // 2) CLI-minor match: highest published <major>.<minor>.* (numeric patch order).
+  // 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
+  // `tot@1.3.0-rc.0` pull `runner@1.3.0-rc.0` instead of falling back to stale latest.
+  if (versions.includes(cliVersion)) {
+    return { version: cliVersion, reason: "exact CLI-version match" };
+  }
+
+  // 3) CLI-minor match: highest published <major>.<minor>.* (numeric patch order).
   const m = /^(\d+)\.(\d+)\./.exec(cliVersion || "");
   if (m) {
     const prefix = `${m[1]}.${m[2]}.`;
@@ -398,7 +407,7 @@ export function pickRunnerVersion(meta, { cliVersion, explicitPin }) {
     }
   }
 
-  // 3) Fallback: the `latest` dist-tag (pre-alignment safety net).
+  // 4) Fallback: the `latest` dist-tag (pre-alignment safety net).
   if (distTags.latest) return { version: distTags.latest, reason: "fell back to latest (no CLI-minor match)" };
   throw new Error("no publishable runner version (no CLI-minor match and no `latest` dist-tag)");
 }
@@ -492,20 +501,64 @@ export async function ensureRendererArtifact(args, { client: providedClient } =
 }
 
 /**
- * Resolve the renderer for the ZERO-LOGIN sample path WITHOUT any MCP call — the
- * whole point of the free taste. Uses resolveRendererSource() (env override →
- * cached runner from a prior `tot dev` → in-tree monorepo), and only when none of
- * those exist does it fail with the exact seam WS3b fills (a public tarball URL).
+ * The version-pinned public-runner cache dir for `version` IFF it's present and
+ * fully installed (carries the `.tot-cache-complete` marker), else null. This is
+ * the VERSION-AWARE reuse that replaced the old "newest dir by mtime" reuse: it
+ * only ever returns the dir for the version the pin actually chose, so a stale
+ * pre-pin dir (public-0.1.0) can never be served in place of the pinned one
+ * (the 2026-07-14 "cached runner keeps being reused" bug). Pure fs probe.
+ */
+export function pinnedPublicCacheDir(cacheRoot, version) {
+  if (!cacheRoot || !version) return null;
+  const dir = join(cacheRoot, `public-${version}`);
+  return existsSync(join(dir, ".tot-cache-complete")) ? dir : null;
+}
+
+/**
+ * Delete every OTHER public-runner cache dir (`public-*` except `keepVersion`)
+ * once we've resolved the version this CLI pins to — so a pre-alignment dir
+ * (e.g. public-0.1.0 from before the version pin existed) can't linger to be
+ * picked up by the offline last-resort reuse, and disk doesn't accumulate one
+ * runner tree per version forever. Only touches `public-*` dirs: the entitled
+ * path caches by bare version and sample tarball runs by `sample-*`, both left
+ * alone. Best-effort — a failure here never breaks `tot dev`.
+ */
+function prunePublicRunnerCache(cacheRoot, keepVersion) {
+  try {
+    if (!cacheRoot || !existsSync(cacheRoot)) return;
+    const keep = `public-${keepVersion}`;
+    for (const name of readdirSync(cacheRoot)) {
+      if (!name.startsWith("public-") || name === keep) continue;
+      rmSync(join(cacheRoot, name), { recursive: true, force: true });
+    }
+  } catch {
+    /* best-effort cache hygiene */
+  }
+}
+
+/**
+ * Resolve the renderer for the ZERO-LOGIN sample / public-fallback path WITHOUT
+ * any MCP call — the whole point of the free taste. Resolution order:
+ *   1. env override (TOT_RUNNER_DIR/TARBALL/URL) or the in-tree monorepo runner
+ *      (resolveLocalRendererSource) — used verbatim.
+ *   2. otherwise the PUBLIC npm runner, VERSION-PINNED to this CLI (pickRunnerVersion):
+ *      reuse the matching `public-<version>` cache dir if present, else download it.
+ *
+ * The cache is keyed `public-<version>`, so we reuse the RIGHT version offline and
+ * NEVER a stale one. This is the fix for the 2026-07-14 bug: the resolver used to
+ * return the newest cache dir by mtime with no version check, short-circuiting
+ * BEFORE the pin ran, so a pre-pin public-0.1.0 was reused forever and the CLI
+ * never asked npm for the aligned runner.
+ *
  * Unlike ensureRendererArtifact it does NOT fall back to Docker — the sample is
  * deliberately Docker-free and login-free.
  * @returns {Promise<string>} the runner tree's root directory (has scripts/tot-dev.mjs).
  */
-export async function ensureSampleRenderer(args, ctx, { env = process.env } = {}) {
+export async function ensureSampleRenderer(args, ctx, { env = process.env, cacheRoot = RENDERER_CACHE_ROOT } = {}) {
   const src = resolveLocalRendererSource({
     env,
     mode: ctx?.mode,
     repoRoot: ctx?.repoRoot,
-    cacheRoot: RENDERER_CACHE_ROOT,
   });
 
   if (src.kind === "dir") {
@@ -527,12 +580,39 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env } = {}
     );
   }
 
-  // kind === "none" — nothing local: fetch the PUBLIC runner from npm (the seam
-  // ws1b left for WS3b). No MCP, no entitlement, no login — the point of --sample.
+  // 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.
+  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).
+  if (!explicitPin) {
+    const exact = pinnedPublicCacheDir(cacheRoot, CLI_VERSION);
+    if (exact) {
+      console.error(`~ renderer: cached public runner ${CLI_VERSION} (matches this CLI)`);
+      prunePublicRunnerCache(cacheRoot, CLI_VERSION);
+      return exact;
+    }
+  }
+
   let pub;
   try {
     pub = await resolvePublicRendererSource(args, env);
   } 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`.
+    // This is the ONLY place a version-unchecked reuse survives, and only because
+    // there's no network to pin against. (Once one online run has aligned + pruned
+    // the cache, this reuses the correct version anyway.)
+    const cached = newestCachedRunner(cacheRoot);
+    if (cached && existsSync(join(cached, "scripts", "tot-dev.mjs"))) {
+      console.error(`~ renderer: offline — reusing cached runner ${cached} (couldn't reach npm to pin the version)`);
+      return cached;
+    }
     throw new CliError(
       `can't run the sample — no local runner and the public runner is unavailable: ${e?.message || e}`,
       {
@@ -543,10 +623,14 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env } = {}
     );
   }
   console.error(`~ renderer: public npm ${pub.version} (${PUBLIC_RUNNER_PACKAGE})`);
-  return installRunnerTarball(
+  const dir = await installRunnerTarball(
     { source: pub.url, version: pub.cacheKey, isUrl: true, strip: pub.strip },
     { log: (m) => console.error(m) },
   );
+  // The pinned version is now installed under public-<version> — drop any other
+  // public-* dirs (e.g. the stale public-0.1.0) so they can never be reused.
+  prunePublicRunnerCache(cacheRoot, pub.version);
+  return dir;
 }
 
 /** A stable, filesystem-safe cache key for a renderer resolved from a tarball source. */

package/src/sample.mjs

@@ -142,19 +142,25 @@ export function scaffoldSample(destDir, { force = false, log = () => {} } = {})
  *   3. TOT_RUNNER_URL   — a PUBLIC https tarball URL. ← the seam WS3b bakes a
  *                          default into (a well-known public CDN URL), so a bare
  *                          `npx … dev --sample` on a clean machine Just Works.
- *   4. cache reuse      — a runner a prior authenticated `tot dev` already
- *                          downloaded under ~/.tot/cache/renderer/<version>/.
- *                          Piggybacks on it with no network at all.
- *   5. monorepo         — inside the storefront monorepo the runner IS the tree;
+ *   4. monorepo         — inside the storefront monorepo the runner IS the tree;
  *                          run its in-tree scripts/tot-dev.mjs directly.
- *   6. none             — nothing local + no public URL yet → caller emits the
- *                          exact seam WS3b must fill.
+ *   5. none             — no override + not in the monorepo → caller fetches the
+ *                          VERSION-PINNED public runner from npm (dev.mjs).
+ *
+ * NOTE — cache reuse deliberately does NOT live here anymore. This resolver is
+ * sync + offline, but the correct cached runner is the one matching the version
+ * the CLI PINS to (pickRunnerVersion), which needs npm metadata. Reusing "the
+ * newest cache dir by mtime" here (the pre-2026-07-14 behaviour) short-circuited
+ * BEFORE the version pin ever ran, so a stale pre-pin dir (public-0.1.0) got
+ * reused forever. Version-aware reuse now happens in dev.mjs `ensureSampleRenderer`
+ * (reuse `public-<pinnedVersion>` iff present, else fetch); `newestCachedRunner`
+ * is exported below only as an OFFLINE last resort when npm can't be reached at all.
  *
  * Pure/deterministic given its inputs (env + fs probes) — no network, no MCP.
- * @param {{ env?: NodeJS.ProcessEnv, mode?: string, repoRoot?: string|null, cacheRoot?: string }} [opts]
+ * @param {{ env?: NodeJS.ProcessEnv, mode?: string, repoRoot?: string|null }} [opts]
  * @returns {{ kind: "dir"|"tarball"|"none", dir?: string, source?: string, isUrl?: boolean, why: string }}
  */
-export function resolveRendererSource({ env = process.env, mode = "loose", repoRoot = null, cacheRoot } = {}) {
+export function resolveRendererSource({ env = process.env, mode = "loose", repoRoot = null } = {}) {
   if (env.TOT_RUNNER_DIR) {
     return { kind: "dir", dir: resolve(env.TOT_RUNNER_DIR), why: "TOT_RUNNER_DIR" };
   }
@@ -164,27 +170,25 @@ export function resolveRendererSource({ env = process.env, mode = "loose", repoR
   if (env.TOT_RUNNER_URL) {
     return { kind: "tarball", source: env.TOT_RUNNER_URL, isUrl: true, why: "TOT_RUNNER_URL" };
   }
-  const cached = newestCachedRunner(cacheRoot);
-  if (cached) {
-    return { kind: "dir", dir: cached, why: "cached runner (prior `tot dev`)" };
-  }
   if (mode === "monorepo" && repoRoot && existsSync(join(repoRoot, "scripts", "tot-dev.mjs"))) {
     return { kind: "dir", dir: repoRoot, why: "in-tree monorepo runner" };
   }
   return {
     kind: "none",
     why:
-      "no local runner and no public renderer URL configured yet (WS3b seam) — set TOT_RUNNER_URL / TOT_RUNNER_TARBALL / TOT_RUNNER_DIR, or run once inside the storefront monorepo",
+      "no local runner override and not in the monorepo — fetch the version-pinned public runner from npm (set TOT_RUNNER_URL / TOT_RUNNER_TARBALL / TOT_RUNNER_DIR to override)",
   };
 }
 
 /**
  * Newest fully-installed runner under the renderer cache (dirs carry a
- * `.tot-cache-complete` marker written by dev.mjs). Lets the sample path reuse a
- * runner a prior authenticated run already fetched, with no network. Returns the
- * absolute dir or null.
+ * `.tot-cache-complete` marker written by dev.mjs). Returns the absolute dir or
+ * null. NOT part of the normal resolution order — it's version-UNAWARE (picks by
+ * mtime), so dev.mjs uses it only as an OFFLINE last resort (npm unreachable, so
+ * no version to pin against); the online path reuses the version-pinned
+ * `public-<version>` dir instead. Exported for that single caller.
  */
-function newestCachedRunner(cacheRoot) {
+export function newestCachedRunner(cacheRoot) {
   if (!cacheRoot || !existsSync(cacheRoot)) return null;
   let best = null;
   let bestMtime = -1;