@tokenoftrust/cli 2.4.6 → 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.6",
+  "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 {

package/src/update-check.mjs

@@ -21,8 +21,8 @@
  *     result (instant, no network on the hot path); the registry refresh happens in a
  *     DETACHED, unref'd child so it can't add latency or hold the process open.
  *   • Cached in `~/.tot/update-check.json`; refreshed at most once per CHECK_INTERVAL_MS.
- *   • Suppressed when stderr isn't a TTY, in CI, or when TOT_NO_UPDATE_CHECK /
- *     NO_UPDATE_NOTIFIER is set. `TOT_HOME` overrides the home dir (tests).
+ *   • Printed to stderr whether or not it is a TTY; suppressed in CI or when
+ *     TOT_NO_UPDATE_CHECK / NO_UPDATE_NOTIFIER is set. `TOT_HOME` overrides the home dir (tests).
  */
 import { readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync } from "node:fs";
 import { homedir } from "node:os";
@@ -195,11 +195,15 @@ export function renderNotice(notice, current) {
     .join("\n");
 }
 
-/** Whether we should print a nudge at all in this environment. */
-export function shouldShowNudge(env = process.env, stream = process.stderr) {
+/**
+ * Whether we should print a nudge at all in this environment. Deliberately NOT
+ * gated on a TTY: agent-driven sessions run `tot` non-interactively, and a stale
+ * CLI caps the runner it resolves at its own major.minor. The nudge goes to
+ * stderr, so stdout stays parseable.
+ */
+export function shouldShowNudge(env = process.env) {
   if (env.TOT_NO_UPDATE_CHECK || env.NO_UPDATE_NOTIFIER) return false;
   if (env.CI) return false;
-  if (!stream || !stream.isTTY) return false;
   return true;
 }
 
@@ -292,7 +296,7 @@ function refreshInBackground(env) {
  */
 export function maybeNotifyUpdate(current, env = process.env, { stream = process.stderr } = {}) {
   try {
-    if (shouldShowNudge(env, stream)) {
+    if (shouldShowNudge(env)) {
       const notice = updateNotice(current, env);
       if (notice) stream.write(`${renderNotice(notice, current)}\n`);
     }