@tokenoftrust/cli 1.3.0-rc.4 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.3.0-rc.4",
+  "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/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,
@@ -693,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/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)`,
@@ -569,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`);
+      }
+    },
+  };
+}