@tokenoftrust/cli 1.3.0-rc.3 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.3.0-rc.3",
+  "version": "1.3.0",
   "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/auth.mjs

@@ -119,6 +119,7 @@ export async function resolveDeveloperSession(client, env, deps = {}) {
         { hint: "run `tot login` to sign in again." },
       );
     }
+    const prior = creds;
     creds = credentialsFromToken({
       mcpUrl: creds.mcpUrl,
       clientId: creds.clientId,
@@ -128,6 +129,15 @@ export async function resolveDeveloperSession(client, env, deps = {}) {
       token: { ...refreshed, refresh_token: refreshed.refresh_token || creds.refreshToken },
       now,
     });
+    // credentialsFromToken only returns the OAuth shape — it knows nothing about
+    // activityToken/activityUrl, a SEPARATE credential (storefront-issued, cached
+    // by `tot login --code`; see token-store.mjs). Carry it across a silent
+    // refresh, or a routine near-expiry refresh permanently and silently kills
+    // the activity bridge (the invite code that could re-mint it is single-use).
+    if (prior.activityToken && prior.activityUrl) {
+      creds.activityToken = prior.activityToken;
+      creds.activityUrl = prior.activityUrl;
+    }
     writeCredentials(path, creds);
   }
 

package/src/commands/dev.mjs

@@ -44,6 +44,7 @@ import { establishSession } from "../auth.mjs";
 import { defaultCredentialsPath, readCredentials } from "../token-store.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
 import { openBrowser, waitForServer, firstFreePort } from "../open.mjs";
+import { startProgress } from "../progress.mjs";
 import {
   scaffoldSample, isSampleCheckout, sampleConfig,
   resolveRendererSource as resolveLocalRendererSource, newestCachedRunner, SAMPLE_DIR_NAME,
@@ -240,7 +241,7 @@ function runMonorepo(ctx, argv) {
     console.error(`✗ expected the dev runner at ${script} but it's missing.`);
     return 2;
   }
-  const env = { ...process.env, ...activityBridgeEnv() };
+  const env = { ...process.env, ...activityBridgeEnv(process.env) };
   return new Promise((resolvePromise) => {
     const child = spawn(process.execPath, [script, ...argv], { stdio: "inherit", env });
     child.on("exit", (code) => resolvePromise(code ?? 0));
@@ -289,10 +290,24 @@ async function runNative(workspace, args, ctx) {
  * promise. Shared by the authenticated native path (runNative) and the
  * zero-login sample path (runSample) so both boot identically.
  */
-function bootNative(runnerDir, workspace, port, url, args) {
-  // 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() });
+/**
+ * The env bootNative threads into the spawned runner. NEVER thread a real
+ * developer's activity-bridge credential into the zero-login --sample run:
+ * activityBridgeEnv() reads ~/.tot/credentials.json unconditionally, so a
+ * developer who's ever run `tot login --code` and then runs `tot dev --sample`
+ * (the "free taste"/demo path) would otherwise leak their real credential,
+ * posting fake sample-store activity to their real hosted /dev panel —
+ * contradicting the sample banner's "no login, no ToT account, nothing
+ * published" claim. Exported + pure (besides the credentials-file read) so
+ * this gate is testable without spawning a real process.
+ * @param {{ sample?: boolean }} args
+ */
+export function bootNativeEnv(args) {
+  return args.sample ? {} : activityBridgeEnv();
+}
+
+export function bootNative(runnerDir, workspace, port, url, args) {
+  const handle = spawnNativeDev(runnerDir, workspace, port, { stdio: "inherit", env: bootNativeEnv(args) });
 
   // Auto-open the browser the moment the server answers (D). Non-blocking so
   // Ctrl-C / logs are unaffected; --no-open suppresses it.
@@ -679,11 +694,23 @@ export async function installRunnerTarball({ source, version, isUrl = true, stri
   const marker = join(runnerDir, ".tot-cache-complete");
   if (existsSync(marker)) return runnerDir; // already downloaded + installed
 
-  log(`~ preparing the native renderer (version ${version}, first run only)...`);
+  // First run only — set the expectation so the one-time cost doesn't read as a
+  // hang: this downloads + installs the renderer once, then every later run of
+  // this version is a no-network cache hit.
+  log(`~ first run: downloading + installing the renderer (~a minute; cached after this)…`);
   const localSource = isUrl ? null : resolveLocalTarball(source);
   const archivePath = isUrl ? join(tmpdir(), `tot-renderer-${process.pid}-${Date.now()}.tar.gz`) : localSource;
   try {
-    if (isUrl) await downloadFile(source, archivePath);
+    if (isUrl) {
+      // The fetch itself is otherwise silent (no per-byte output) and can run
+      // tens of seconds on a cold cache — tick a spinner so it never looks hung.
+      const spin = startProgress("downloading the renderer…");
+      try {
+        await downloadFile(source, archivePath);
+      } finally {
+        spin.stop();
+      }
+    }
     if (!existsSync(archivePath)) {
       throw new Error(`renderer tarball not found: ${archivePath}`);
     }

package/src/commands/login.mjs

@@ -100,8 +100,9 @@ export async function loginAndCache(mcpUrl, env = process.env, { log = () => {},
       creds = await deviceLoginFlow({ mcpUrl, clientId, log });
     }
   }
-  writeCredentials(path, creds);
-  return creds;
+  const merged = mergeActivityBridge(prior, mcpUrl, creds);
+  writeCredentials(path, merged);
+  return merged;
 }
 
 /**
@@ -115,7 +116,24 @@ export async function redeemAndCache(mcpUrl, code, env = process.env) {
   const prior = readCredentials(path);
   const clientId = prior && prior.mcpUrl === mcpUrl ? prior.clientId : undefined;
   const creds = await redeemCodeFlow({ mcpUrl, clientId, code });
-  writeCredentials(path, creds);
+  const merged = mergeActivityBridge(prior, mcpUrl, creds);
+  writeCredentials(path, merged);
+  return merged;
+}
+
+/**
+ * `loginFlow`/`deviceLoginFlow`/`redeemCodeFlow` all return the bare OAuth shape —
+ * none of them know about activityToken/activityUrl, a SEPARATE credential this
+ * same file caches via cacheActivityBridge. A bare re-login (no --code) after a
+ * prior --code sign-in would otherwise silently drop it on the next `writeCredentials`
+ * (a full-object overwrite, not a merge) — carry it forward when re-authing against
+ * the SAME mcpUrl (a different MCP means a different session; the old bridge
+ * credential no longer applies).
+ */
+export function mergeActivityBridge(prior, mcpUrl, creds) {
+  if (prior?.mcpUrl === mcpUrl && prior.activityToken && prior.activityUrl) {
+    return { ...creds, activityToken: prior.activityToken, activityUrl: prior.activityUrl };
+  }
   return creds;
 }
 

package/src/commands/start.mjs

@@ -53,6 +53,7 @@ import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { CliError, fail, formatError, exitCodeFor } from "../errors.mjs";
 import { openBrowser, waitForServer, firstFreePort } from "../open.mjs";
+import { startProgress } from "../progress.mjs";
 import { defaultLastTenantPath, readLastTenant, writeLastTenant } from "../last-tenant.mjs";
 import { collectChecks } from "./doctor.mjs";
 import { normalizeStores, storeListError, checkoutTenant } from "./checkout.mjs";
@@ -236,10 +237,9 @@ export async function run(argv, ctx) {
       handle = spawnNativeDev(runtime.runnerDir, dir, devArgs.port, { stdio: "piped", env: activityBridgeEnv(env) });
     }
 
-    const up = await Promise.race([
-      waitForServer(url, { until: () => handle.exited }),
-      handle.done.then(() => "exited"),
-    ]);
+    // The runner's stdio is "piped" (its logs are held until the aha), so this
+    // boot would otherwise be a silent 5–60s gap. Tick a spinner over it.
+    const up = await waitForBoot(url, handle);
     if (up !== true) {
       throw new CliError("the dev server didn't come up", {
         next: `cd ${tenant} && tot dev   (to watch the runner logs)`,
@@ -307,10 +307,7 @@ async function runSampleStart(args, ctx, env, startedAt) {
     console.log(`  → starting the free local preview … ${url}`);
     const handle = spawnNativeDev(runnerDir, workspace, devArgs.port, { stdio: "piped" });
 
-    const up = await Promise.race([
-      waitForServer(url, { until: () => handle.exited }),
-      handle.done.then(() => "exited"),
-    ]);
+    const up = await waitForBoot(url, handle);
     if (up !== true) {
       throw new CliError("the local preview server didn't come up", {
         next: `cd ${SAMPLE_DIR_NAME} && tot dev --sample   (to watch the runner logs)`,
@@ -436,7 +433,12 @@ async function prefetchRuntime(client, devArgs, env, runtime, ctx) {
       console.log(`  ~ entitled renderer unavailable (${e.message}) — using the public runner (no Docker).`);
       runtime.runnerDir = await ensureSampleRenderer(devArgs, ctx, { env });
     } catch (e2) {
-      console.log(`  ~ public runner unavailable (${e2?.message || e2}) — falling back to the Docker runner.`);
+      // Only an actual "can't reach the public runner" failure should fall to
+      // Docker — anything else (a real bug in ensureSampleRenderer/pickRunnerVersion,
+      // say) would otherwise be silently masked behind a confusing Docker fallback
+      // that may not even be installed. Mirrors dev.mjs's runStandalone.
+      if (!(e2 instanceof NativeArtifactUnavailableError)) throw e2;
+      console.log(`  ~ public runner unavailable (${e2.message}) — falling back to the Docker runner.`);
       runtime.useDocker = true;
       await prefetchDockerLogin(client, devArgs, env);
     }
@@ -564,6 +566,30 @@ async function ensureCheckout(client, tenant, dir, env) {
   console.log(`  ✓ checked out ./${tenant}`);
 }
 
+/**
+ * Wait for the dev server to answer while showing progress, then return the
+ * `waitForServer` result ("exited" if the runner died first). Both the runner
+ * (native or Docker) runs with "piped" stdio here, so its boot logs are withheld
+ * until the aha — without this the terminal is a silent 5–60s gap that reads as
+ * hung (the D1 "perceived speed" problem). The spinner keeps the interval well
+ * under 5s and, once past the warm-boot window, explains the first-render cost.
+ */
+async function waitForBoot(url, handle) {
+  const spin = startProgress("starting the dev server…", {
+    stages: [
+      { afterMs: 6000, text: "compiling your store — first render can take a moment…" },
+    ],
+  });
+  try {
+    return await Promise.race([
+      waitForServer(url, { until: () => handle.exited }),
+      handle.done.then(() => "exited"),
+    ]);
+  } finally {
+    spin.stop();
+  }
+}
+
 /**
  * Format elapsed milliseconds as a short human string for the "you're live"
  * ending (A3 — measure, don't just claim, "instant"). Pure + exported so it's

package/src/progress.mjs

@@ -0,0 +1,101 @@
+/**
+ * A dependency-free, non-blocking progress indicator for the "and then it just
+ * runs" waits — the first-run renderer download and the dev server's cold boot,
+ * where the CLI would otherwise sit SILENT for tens of seconds (piped runner
+ * logs, a background fetch) and read as hung. Node built-ins only.
+ *
+ * Two behaviours, chosen from whether stderr is a TTY:
+ *   - TTY   → an in-place braille spinner rewritten with \r, showing an elapsed
+ *             seconds counter, so the terminal visibly ticks.
+ *   - non-TTY (CI, piped) → NO \r animation (that spams a log with control
+ *             chars); instead one line at start and then a heartbeat line every
+ *             ~10s, so a CI log shows liveness without a wall of frames.
+ *
+ * Both surface staged labels: pass `stages: [{ afterMs, text }]` and the label
+ * advances as the wait crosses each threshold (e.g. "starting…" → "compiling
+ * your store (first render)…"), so a long wait explains itself instead of
+ * staring back blankly.
+ */
+
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const CLEAR_LINE = "\r\x1b[K";
+
+/**
+ * Given the elapsed ms and the (optionally staged) labels, return the label to
+ * show right now: the last stage whose `afterMs` has passed, else `initial`.
+ * Pure + exported so the staging is unit-tested without any timers or TTY.
+ * @param {string} initial
+ * @param {Array<{afterMs:number,text:string}>} stages
+ * @param {number} elapsedMs
+ * @returns {string}
+ */
+export function stageLabel(initial, stages, elapsedMs) {
+  let label = initial;
+  for (const s of stages || []) {
+    if (elapsedMs >= s.afterMs) label = s.text;
+  }
+  return label;
+}
+
+/**
+ * Start a progress indicator. Returns a handle with `stop(finalText?)` — always
+ * call it (a `finally` is ideal) so the interval clears and, on a TTY, the
+ * spinner line is erased. Safe to call `stop` more than once.
+ *
+ * @param {string} initialText the label shown until the first stage (if any).
+ * @param {{ stream?: NodeJS.WriteStream, stages?: Array<{afterMs:number,text:string}>,
+ *   isTTY?: boolean, intervalMs?: number, heartbeatMs?: number, now?: () => number }} [opts]
+ * @returns {{ stop: (finalText?: string) => void }}
+ */
+export function startProgress(initialText, opts = {}) {
+  const {
+    stream = process.stderr,
+    stages = [],
+    isTTY = Boolean(stream.isTTY),
+    intervalMs = isTTY ? 90 : 1000,
+    heartbeatMs = 10000,
+    now = Date.now,
+  } = opts;
+
+  const startedAt = now();
+  let frame = 0;
+  let lastHeartbeat = startedAt;
+  let stopped = false;
+
+  const secs = () => Math.floor((now() - startedAt) / 1000);
+  const label = () => stageLabel(initialText, stages, now() - startedAt);
+
+  function tick() {
+    if (stopped) return;
+    if (isTTY) {
+      frame = (frame + 1) % FRAMES.length;
+      stream.write(`${CLEAR_LINE}  ${FRAMES[frame]} ${label()} (${secs()}s)`);
+    } else if (now() - lastHeartbeat >= heartbeatMs) {
+      lastHeartbeat = now();
+      stream.write(`  … ${label()} (${secs()}s)\n`);
+    }
+  }
+
+  // Announce immediately so there's never a silent lead-in, then tick.
+  if (isTTY) {
+    stream.write(`  ${FRAMES[0]} ${initialText} (0s)`);
+  } else {
+    stream.write(`  … ${initialText}\n`);
+  }
+  const timer = setInterval(tick, intervalMs);
+  if (typeof timer.unref === "function") timer.unref(); // never keep the process alive
+
+  return {
+    stop(finalText) {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+      if (isTTY) {
+        stream.write(CLEAR_LINE); // erase the spinner line
+        if (finalText) stream.write(`  ${finalText}\n`);
+      } else if (finalText) {
+        stream.write(`  ${finalText}\n`);
+      }
+    },
+  };
+}