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

package/package.json

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

package/src/commands/dev.mjs

@@ -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`.