@tokenoftrust/cli 2.0.18 → 2.0.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.0.18",
+  "version": "2.0.20",
   "description": "Token of Trust developer CLI — clone 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/clone.mjs

@@ -287,21 +287,26 @@ export async function run(argv, ctx) {
  *   cloned: boolean, dir: string|null, head: string|null }>}
  */
 export async function checkoutTenant(client, { tenant, tag = "main", cloneDir = null, redact = (s) => s }) {
-  // The switch is LOAD-BEARING, so its refusal is the error the developer must see. When
-  // the tenant is not one of this session's clients the server refuses here with the real
-  // cause (no grant / a grant issued to a client this identity is not bound to / a grant
-  // issued after sign-in that needs a re-auth) — far more specific than the tenant_checkout
-  // refusal that follows it. Surfacing the switch's own words, with the server's nextAction,
-  // stops a genuinely-unentitled tenant from being reported as a scope-selection slip.
+  // The switch CARRIES the best diagnosis but is NOT a precondition, and the difference
+  // matters in both directions:
+  //
+  //   - Discarding its refusal (the original behaviour) meant a genuinely unentitled tenant
+  //     surfaced later as tenant_checkout complaining about your PRIOR active tenant, which
+  //     reads as a scope-selection slip rather than a missing grant.
+  //   - Treating it as fatal breaks the STAFF-PREVIEW path, where the refusal is expected:
+  //     a staff human checking out a merchant tenant under an authorization holds no client
+  //     grant on it, so client_switch MUST fail while tenant_checkout legitimately succeeds
+  //     (it takes the tenant as an argument and resolves the app from the authorization).
+  //     `tot git-credential` mints through this same function, so a fatal switch also breaks
+  //     every fetch and push in such a checkout, not just the initial clone.
+  //
+  // So: remember it, proceed, and surface it only if the checkout ALSO fails — at which
+  // point it is the more specific of the two errors.
+  let switchRefusal = null;
   try {
     await client.callTool("client_switch", { tenant });
   } catch (e) {
-    throw new CliError(redact(String(e?.message || e)), {
-      next:
-        "confirm you're entitled to this store — `tot grants` lists what your session can " +
-        "act on, and `tot login` refreshes a grant issued after you signed in",
-      cause: e,
-    });
+    switchRefusal = e;
   }
   // vc-app-binding safety-net (08-18, §5): ensure THIS developer is bound to the
   // storefront version-control app BEFORE checkout, so tenant_checkout can resolve
@@ -319,13 +324,37 @@ export async function checkoutTenant(client, { tenant, tag = "main", cloneDir =
   } catch {
     /* fail-open — see above */
   }
-  const checkout = await client.callTool("tenant_checkout", { tenant, tag });
+  let checkout;
+  try {
+    checkout = await client.callTool("tenant_checkout", { tenant, tag });
+  } catch (e) {
+    // Both failed: the switch's refusal names the cause more precisely than a thrown
+    // checkout, so lead with it.
+    if (switchRefusal) {
+      throw new CliError(redact(String(switchRefusal?.message || switchRefusal)), {
+        next:
+          "confirm you're entitled to this store — `tot grants` lists what your session can " +
+          "act on, and `tot login` refreshes a grant issued after you signed in",
+        cause: switchRefusal,
+      });
+    }
+    throw e;
+  }
 
   // A non-checkout result (not provisioned / not entitled / failed) must surface
   // the MCP's human message + a concrete next step, NEVER a raw JSON.stringify
   // dump (James's 2026-07-19 first-experience failure).
   const err = checkoutError(checkout);
   if (err) {
+    // Same precedence: an unentitled tenant is better explained by the switch.
+    if (switchRefusal) {
+      throw new CliError(redact(String(switchRefusal?.message || switchRefusal)), {
+        next:
+          "confirm you're entitled to this store — `tot grants` lists what your session can " +
+          "act on, and `tot login` refreshes a grant issued after you signed in",
+        cause: switchRefusal,
+      });
+    }
     throw new CliError(redact(err.message), { next: err.next });
   }
   const gitRemote = checkout.gitRemote;

package/src/commands/dev.mjs

@@ -66,7 +66,7 @@ export function parseArgs(argv) {
   const a = {
     workspace: null, port: "4321", mcp: null,
     noLogin: false, noOpen: false, sample: false, help: false,
-    rendererVersion: null,
+    rendererVersion: null, resetCache: false,
   };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
@@ -77,12 +77,34 @@ export function parseArgs(argv) {
     else if (t === "--no-open") a.noOpen = true;
     else if (t === "--sample") a.sample = true;
     else if (t === "--renderer-version") a.rendererVersion = argv[++i];
+    else if (t === "--reset-cache") a.resetCache = true;
     else if (t === "--help" || t === "-h") a.help = true;
   }
   return a;
 }
 
-const USAGE = `tot dev — run your store locally with save→reload
+/**
+ * Delete the cached preview engines so the next run downloads and installs fresh.
+ *
+ * The recovery path this replaces was "hand-delete a directory under ~/.tot/cache" —
+ * which agent guidance forbids and no developer should have to know
+ * (fb-1789008798249-sc4tgy: the reporter had no way back to a working dev loop
+ * without it). A first-class flag makes the supported recovery discoverable in
+ * `tot dev --help`.
+ *
+ * Scoped deliberately to the renderer cache: it is a pure download+install artifact,
+ * rebuilt on demand, so removing it can only cost time. It never touches the
+ * tenant checkout, the login session, or anything else under ~/.tot.
+ * @param {{cacheRoot?: string, rm?: (p: string, o: object) => void}} [deps]
+ * @returns {{removed: boolean, path: string}}
+ */
+export function resetRendererCache({ cacheRoot = RENDERER_CACHE_ROOT, rm = rmSync } = {}) {
+  const existed = existsSync(cacheRoot);
+  rm(cacheRoot, { recursive: true, force: true });
+  return { removed: existed, path: cacheRoot };
+}
+
+export const USAGE = `tot dev — run your store locally with save→reload
 
   tot dev <tenant>              (in the monorepo) run tenants/<tenant>/
   tot dev                       (in a checkout) run this store natively (no Docker)
@@ -91,6 +113,7 @@ const USAGE = `tot dev — run your store locally with save→reload
   tot dev --workspace <dir>     run a specific checkout directory
   tot dev --port <n>            host port (default 4321)
   tot dev --no-open             don't auto-open the browser when the server is up
+  tot dev --reset-cache         delete the downloaded preview engines and re-fetch
 
 Edit content/*.html or the theme + save → the browser reloads. Private local
 preview — nothing is published. Prerequisites: Node.js and an invite (or just
@@ -104,6 +127,16 @@ export async function run(argv, ctx) {
     return 0;
   }
 
+  // Before anything else, so a wedged cache cannot break the very run meant to clear
+  // it. Then fall through and start normally: the flag is a modifier, not a separate
+  // command, because "clear it and go" is what a stuck developer actually wants.
+  if (args.resetCache) {
+    const { removed, path } = resetRendererCache();
+    console.error(removed
+      ? `~ cleared the preview-engine cache (${path}) — this run re-downloads it.`
+      : `~ no preview-engine cache to clear (${path}).`);
+  }
+
   // Resolve a free port up front so the URL we derive/open/print matches the port
   // the runner actually binds — Vite's strictPort is off, so a busy default would
   // silently drift and strand the browser/liveness poll on the wrong port. No-op