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

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.1",
+  "version": "1.3.0-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",

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);
@@ -204,23 +205,42 @@ async function runNativePublic(workspace, args, ctx) {
   return bootNative(runnerDir, workspace, port, url, args);
 }
 
+/**
+ * Read the hosted-activity-bridge credential (minted alongside the invite's
+ * browserless `tot login --code` paste — see login.mjs's cacheActivityBridge)
+ * and shape it as the two env vars dev-loop-state.mjs's postActivity reads.
+ * Returns {} when absent (an older cached session, a bare `tot login`, or the
+ * zero-login --sample path) — the local loop runs exactly the same either way,
+ * it just has no hosted signal to report. EVERY path that spawns the runner
+ * (native monorepo, native standalone, Docker) must thread this in, or the
+ * developer's hosted /dev panel never lights up even though they cached a
+ * valid bridge credential at login.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {{TOT_DEV_ACTIVITY_TOKEN?: string, TOT_DEV_ACTIVITY_URL?: string}}
+ */
+export function activityBridgeEnv(env = process.env) {
+  const creds = readCredentials(defaultCredentialsPath(env));
+  if (!creds?.activityToken || !creds?.activityUrl) return {};
+  return { TOT_DEV_ACTIVITY_TOKEN: creds.activityToken, TOT_DEV_ACTIVITY_URL: creds.activityUrl };
+}
+
+/**
+ * Flatten an env object into repeated `-e KEY=VAL` docker-run args. Pure, so the
+ * Docker activity-bridge threading is testable without a real Docker daemon.
+ * @param {Record<string, string>} env
+ * @returns {string[]}
+ */
+export function dockerEnvArgs(env) {
+  return Object.entries(env).flatMap(([k, v]) => ["-e", `${k}=${v}`]);
+}
+
 function runMonorepo(ctx, argv) {
   const script = join(ctx.repoRoot, "scripts", "tot-dev.mjs");
   if (!existsSync(script)) {
     console.error(`✗ expected the dev runner at ${script} but it's missing.`);
     return 2;
   }
-  // Thread the hosted-activity-bridge credential (if this cached session has one —
-  // minted alongside the invite's cli-signin-code paste) so the spawned tot-dev.mjs
-  // can report file-save activity up to the developer's own hosted /dev panel.
-  // Best-effort: an older cached session (or a bare `tot login`) simply has
-  // neither field, and the local loop runs exactly as before with no hosted signal.
-  const creds = readCredentials(defaultCredentialsPath(process.env));
-  const env = { ...process.env };
-  if (creds?.activityToken && creds?.activityUrl) {
-    env.TOT_DEV_ACTIVITY_TOKEN = creds.activityToken;
-    env.TOT_DEV_ACTIVITY_URL = creds.activityUrl;
-  }
+  const env = { ...process.env, ...activityBridgeEnv() };
   return new Promise((resolvePromise) => {
     const child = spawn(process.execPath, [script, ...argv], { stdio: "inherit", env });
     child.on("exit", (code) => resolvePromise(code ?? 0));
@@ -270,7 +290,9 @@ async function runNative(workspace, args, ctx) {
  * zero-login sample path (runSample) so both boot identically.
  */
 function bootNative(runnerDir, workspace, port, url, args) {
-  const handle = spawnNativeDev(runnerDir, workspace, port, { stdio: "inherit" });
+  // activityBridgeEnv() is a no-op {} for the zero-login sample path (no cached
+  // credential exists there) — safe to always thread it through.
+  const handle = spawnNativeDev(runnerDir, workspace, port, { stdio: "inherit", env: activityBridgeEnv() });
 
   // Auto-open the browser the moment the server answers (D). Non-blocking so
   // Ctrl-C / logs are unaffected; --no-open suppresses it.
@@ -500,20 +522,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") {
@@ -535,12 +601,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}`,
       {
@@ -551,10 +644,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. */
@@ -682,17 +779,19 @@ function runPnpmInstall(runnerDir) {
  * auto-open-browser logic works unchanged for either runtime. Exported (and
  * `stdio` overridable) so `tot start` can pipe the logs instead of inheriting.
  */
-export function spawnNativeDev(runnerDir, workspace, port, { stdio = "inherit" } = {}) {
+export function spawnNativeDev(runnerDir, workspace, port, { stdio = "inherit", env = {} } = {}) {
   const script = join(runnerDir, "scripts", "tot-dev.mjs");
   // Translate the same "inherit"|"piped" contract spawnDevContainer honors:
   // "piped" means stdin ignored + stdout/stderr captured so `tot start` can hold
   // the prompt on stdin and stream the logs after the aha. child_process.spawn
   // doesn't understand the bare string "piped", so map it to the array here.
   const stdioArr = stdio === "piped" ? ["ignore", "pipe", "pipe"] : stdio;
+  // `env` (e.g. activityBridgeEnv()) merges OVER process.env — {} is a pure
+  // passthrough, identical to the old no-env-key behavior.
   const child = spawn(
     process.execPath,
     [script, "--workspace", workspace, "--port", port],
-    { cwd: runnerDir, stdio: stdioArr },
+    { cwd: runnerDir, stdio: stdioArr, env: { ...process.env, ...env } },
   );
   const handle = { child, exited: false, done: null };
   handle.done = new Promise((resolvePromise) => {
@@ -798,6 +897,10 @@ export function buildContainerPlan(workspace, args, _ctx) {
     "CHOKIDAR_USEPOLLING=1",
     "-e",
     "CHOKIDAR_INTERVAL=300",
+    // Docker containers don't inherit the host env — thread the activity-bridge
+    // credential explicitly (see activityBridgeEnv), or the Docker runtime never
+    // reports to the developer's hosted /dev panel even when native would.
+    ...dockerEnvArgs(activityBridgeEnv()),
     image,
   ];
 

package/src/commands/start.mjs

@@ -60,7 +60,7 @@ import {
   buildContainerPlan, spawnDevContainer, dockerAvailable, tryStartDocker,
   resolveDevImage, isPrivateRegistryImage, ensureRegistryLogin,
   ensureRendererArtifact, ensureSampleRenderer, spawnNativeDev, deriveUrl,
-  NativeArtifactUnavailableError,
+  activityBridgeEnv, NativeArtifactUnavailableError,
 } from "./dev.mjs";
 import { scaffoldSample, isSampleCheckout, sampleConfig, SAMPLE_DIR_NAME } from "../sample.mjs";
 import { IDEAS } from "./ideas.mjs";
@@ -233,7 +233,7 @@ export async function run(argv, ctx) {
     } else {
       url = deriveUrl(ctxDev.config || {}, devArgs.port).url;
       console.log(`  → starting dev … ${url}`);
-      handle = spawnNativeDev(runtime.runnerDir, dir, devArgs.port, { stdio: "piped" });
+      handle = spawnNativeDev(runtime.runnerDir, dir, devArgs.port, { stdio: "piped", env: activityBridgeEnv(env) });
     }
 
     const up = await Promise.race([

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;

package/src/token-store.mjs

@@ -14,8 +14,9 @@
  * to a different one. `activityToken`/`activityUrl` are a SEPARATE credential
  * (storefront-issued, not MCP OAuth) that `tot login --code` caches when the
  * invite paste carries it — see commands/login.mjs `cacheActivityBridge` and
- * commands/dev.mjs `runMonorepo`, which threads them to the local dev-loop
- * process so it can report file saves to the developer's hosted /dev panel.
+ * commands/dev.mjs `activityBridgeEnv`, which every runner-spawning path (native
+ * monorepo, native standalone, Docker) threads in so the local dev-loop process
+ * can report file saves to the developer's hosted /dev panel.
  * Dependency-free (node:fs/os/path).
  *
  * `TOT_HOME` overrides the home dir (used by tests to point at a temp dir).