@tokenoftrust/cli 2.4.7 → 2.4.8

package/README.md

@@ -73,4 +73,4 @@ A clean short name (`staff`, `dev`, `test-7`) becomes a readable `credentials.<n
 
 ## Design notes
 
-Dependency-free by design (global `fetch` + `git` + the system `tar`), so `npm i -g @tokenoftrust/cli` stays light. `tot dev` is the only command that pulls in the storefront runner: for a standalone checkout it downloads the moat-free runner artifact (`dev_renderer_artifact`, entitlement-gated) once per version to `~/.tot/cache/renderer/<version>/`, `pnpm install`s it there (via corepack — no separate pnpm install needed), and reuses that cache on every later run. See `src/` for the small modules: `context.mjs` (detection), `mcp.mjs` (transport), `auth.mjs` (the identity seam), `commands/`.
+Dependency-free by design (global `fetch` + `git` + the system `tar`), so `npm i -g @tokenoftrust/cli` stays light. `tot dev` is the only command that pulls in the storefront runner: for a standalone checkout it downloads the moat-free runner once per version — from the public npm package `@tokenoftrust/storefront-runner`, after the entitlement-gated `dev_renderer_artifact` answers `use_npm` (its artifact store is not kept in step with npm) — to `~/.tot/cache/renderer/`, `pnpm install`s it there (via corepack — no separate pnpm install needed), and reuses that cache on every later run. See `src/` for the small modules: `context.mjs` (detection), `mcp.mjs` (transport), `auth.mjs` (the identity seam), `commands/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.4.7",
+  "version": "2.4.8",
   "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/dev.mjs

@@ -185,7 +185,8 @@ async function runStandalone(workspace, args, ctx) {
       // Entitled artifact unavailable — stay NATIVE on the public npm runner
       // (@tokenoftrust/storefront-runner, the SAME renderer bits), so
       try {
-        console.error(`~ couldn't set up your store preview the usual way (${e.message}) — using the public preview engine instead.`);
+        const notice = artifactFallbackNotice(e);
+        if (notice) console.error(notice);
         return await runNativePublic(workspace, args, ctx);
       } catch (e2) {
         console.error(formatError(e2));
@@ -284,7 +285,31 @@ function runMonorepo(ctx, argv) {
  * specifically and falls back to Docker instead of hard-failing. Exported so
  * `tot start` can catch it too and fall back the same way.
  */
-export class NativeArtifactUnavailableError extends Error {}
+export class NativeArtifactUnavailableError extends Error {
+  /** @param {string} message @param {{ expected?: boolean }} [opts] */
+  constructor(message, { expected = false } = {}) {
+    super(message);
+    // True when the MCP answered that npm is the renderer source: the normal
+    // fallback, not a fault, so it is not reported to the developer.
+    this.expected = expected;
+  }
+}
+
+// dev_renderer_artifact statuses meaning "the artifact store holds no current
+// runner — install it from npm". `use_npm` is the current non-error answer;
+// `stale_artifact` / `not_found` are the error-shaped answers older servers send.
+const USE_NPM_STATUSES = new Set(["use_npm", "stale_artifact", "not_found"]);
+
+/**
+ * The line `tot dev` prints when it falls back from the entitled artifact to the
+ * public npm runner, or null when the fallback is the expected path.
+ * @param {NativeArtifactUnavailableError} e
+ * @returns {string|null}
+ */
+export function artifactFallbackNotice(e) {
+  if (e.expected) return null;
+  return `~ couldn't set up your store preview the usual way (${e.message}) — using the public preview engine instead.`;
+}
 
 /**
  * The local landing URL, shared by the native and Docker paths. The store's path is its canonical
@@ -724,12 +749,18 @@ export async function ensureRendererArtifact(args, { client: providedClient } =
       await establishSession(client, { env: process.env });
     }
     const res = await client.callTool("dev_renderer_artifact", {});
+    if (USE_NPM_STATUSES.has(res?.status)) {
+      throw new NativeArtifactUnavailableError(res.message || "the renderer is served from npm", { expected: true });
+    }
     if (!res?.url || !res?.version) {
       throw new Error(res?.error || "no renderer-artifact URL returned");
     }
     credential = res;
   } catch (e) {
-    throw new NativeArtifactUnavailableError(String(e?.message || e));
+    if (e instanceof NativeArtifactUnavailableError) throw e;
+    throw new NativeArtifactUnavailableError(String(e?.message || e), {
+      expected: USE_NPM_STATUSES.has(e?.diagnostic?.serverStatus),
+    });
   }
 
   try {