@tokenoftrust/cli 1.3.4-rc.4 → 1.3.4-rc.5

package/src/commands/start.mjs

@@ -67,6 +67,7 @@ import {
 import { scaffoldSample, isSampleCheckout, sampleConfig, SAMPLE_DIR_NAME } from "../sample.mjs";
 import { startHeartbeatFromEnv } from "../dev-heartbeat.mjs";
 import { streamDevLogs } from "../dev-logs.mjs";
+import { milestoneBanner, cockpitUrlFrom, DEVELOPER_COCKPIT } from "../banner.mjs";
 import { IDEAS } from "./ideas.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
@@ -196,15 +197,36 @@ export async function run(argv, ctx) {
     await preflight(ctx, env);
     console.log(`  ✓ signed in as ${describeIdentity(session)} via ${mcpOrigin(baseUrl)}`);
 
+    // Resolve the activity-bridge credential + the hosted Developer Cockpit URL
+    // ONCE, up front — both the pre-pick "keep the cockpit alive" heartbeat below
+    // (b2) and the post-boot heartbeat + milestone banners (u2) use them.
+    const bridgeEnv = activityBridgeEnv(env);
+    const cockpitUrl = cockpitUrlFrom(bridgeEnv.TOT_DEV_ACTIVITY_URL);
+
+    // b2 — a >1-store identity blocks on the interactive store picker below, and
+    // (before this) the hosted cockpit got NO heartbeat until the dev server
+    // spawned much later, so a multi-store dev's cockpit sat on Step 1 forever
+    // while the terminal quietly waited for a number. Start beating NOW (no local
+    // URL yet — the store isn't checked out) so the cockpit keeps receiving
+    // liveness during the pick + checkout + boot; the post-boot heartbeat (with
+    // the live localhost URL) takes over once we have it.
+    const stopEarlyHeartbeat = startHeartbeatFromEnv(bridgeEnv, {});
+
     // 3. store — auto-pick, use --tenant, use the remembered one, or choose (A4).
     // Keep the raw client_list so a tool ERROR (unauthenticated / not-entitled) is
     // surfaced with who + where, not collapsed to an empty list (fb-...f45zg9).
-    const listResp = await client.callTool("client_list", {});
-    const stores = normalizeStores(listResp);
-    const tenant = await resolveTenant(stores, args, env, baseUrl, {
-      session,
-      listErr: storeListError(listResp),
-    });
+    let tenant;
+    try {
+      const listResp = await client.callTool("client_list", {});
+      const stores = normalizeStores(listResp);
+      tenant = await resolveTenant(stores, args, env, baseUrl, {
+        session,
+        listErr: storeListError(listResp),
+      });
+    } catch (e) {
+      stopEarlyHeartbeat();
+      throw e;
+    }
 
     // 4. checkout → ./<tenant> (reuse an existing checkout on a re-run),
     // OVERLAPPED (C1) with prefetching the runner: the native artifact by
@@ -225,11 +247,15 @@ export async function run(argv, ctx) {
       prefetchRuntime(client, devArgs, env, runtime, ctx),
     ]);
 
+    // u3 — say EXACTLY where the code landed + THE one next step, so a freshly
+    // checked-out dev is never left wondering what to open. Absolute path (works
+    // from any directory) and a single, unambiguous action.
+    printCheckoutLanding(dir, cockpitUrl);
+
     // 5. dev — native by default (F3), Docker on --docker or the fallback
     // above; wait for the server, open the browser (C/D).
     const ctxDev = detectContext(dir);
     let url, handle;
-    const bridgeEnv = activityBridgeEnv(env);
     if (runtime.useDocker) {
       const plan = buildContainerPlan(dir, devArgs, ctxDev);
       url = plan.url;
@@ -244,7 +270,10 @@ export async function run(argv, ctx) {
     // Heartbeat the hosted cockpit (G1) with the CLI version + this live localhost
     // URL for the life of the run — CLI-side, using the cached bridge credential
     // (no-op when none is cached). The runner keeps reporting file-saves itself.
-    const stopHeartbeat = startHeartbeatFromEnv(bridgeEnv, { url });
+    // Hand off from the pre-pick (URL-less) beat to this URL-bearing one so the
+    // cockpit's live local link lights up exactly when the server is up (b2).
+    stopEarlyHeartbeat();
+    const stopHeartbeat = startHeartbeatFromEnv(bridgeEnv, { url, cwd: dir });
     handle.done.finally(() => stopHeartbeat());
 
     // The runner's stdio is "piped" (its logs are held until the aha), so this
@@ -264,11 +293,11 @@ export async function run(argv, ctx) {
     // (A3) so the "instant" claim is measured. The "Connect Claude" step is
     // intentionally removed for now — a blocking prompt here meant Ctrl-C'ing it
     // tore down the dev server; revisit AI-connect as a non-blocking step later.
-    printLiveEnding(tenant, url, formatElapsed(Date.now() - startedAt));
+    printLiveEnding(tenant, url, formatElapsed(Date.now() - startedAt), cockpitUrl);
 
     // 7. hand the terminal to the running dev server until Ctrl-C.
     console.log("\n  Watching your store — edit content/home.html + save. Ctrl-C to stop.\n");
-    streamDevLogs(handle.child);
+    streamDevLogs(handle.child, { cockpitUrl });
     return handle.done;
   } catch (e) {
     console.error(formatError(e));
@@ -547,8 +576,14 @@ async function resolveTenant(stores, args, env, baseUrl, { session = null, listE
         next: `tot start --tenant <tenant>  (one of: ${pick.stores.map((s) => s.id).join(", ")})`,
       });
     }
-    console.log("  Which store do you want to work on?\n");
+    // Loud + unmissable: a >1-store dev is often looking at their browser
+    // cockpit (which is waiting on this pick), so make the terminal shout for
+    // their attention rather than sitting as a quiet one-liner (b2).
+    console.log("");
+    console.log("  ⚑ ACTION NEEDED IN YOUR TERMINAL — you can build on several stores.");
+    console.log("    Pick one here to light up your cockpit:\n");
     pick.stores.forEach((s, i) => console.log(`    ${i + 1}. ${s.id}${s.name ? `  — ${s.name}` : ""}`));
+    console.log("");
     const idx = await promptChoice(pick.stores.length);
     console.log("");
     tenant = pick.stores[idx].id;
@@ -611,13 +646,37 @@ export function formatElapsed(ms) {
   return ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(1)}s`;
 }
 
-/** The crafted "you're live" ending — leads with the AI-wow (G), seeded with
- * IDEAS[0] (G2/G3 — one prompt list shared with `tot ideas`, no drift). */
-function printLiveEnding(tenant, url, elapsed) {
+/**
+ * u3 — after checkout, tell the developer EXACTLY where their code landed and
+ * THE single next step. `dir` is absolute (from resolve(cwd, tenant)) so the
+ * "open this" path works no matter what directory they're in. When we know the
+ * Developer Cockpit URL, the one next step is framed as "edit a line → see it in
+ * your cockpit"; otherwise it's the same edit-to-see-it-reload action.
+ */
+function printCheckoutLanding(dir, cockpitUrl = null) {
   console.log("");
-  console.log(`  ✨ You're live.${elapsed ? `  (${elapsed})` : ""}`);
-  console.log(`     ${url}`);
-  console.log("     Edit content/home.html + save → it reloads.");
+  console.log(`  📁 Your store code is at:  ${dir}`);
+  const where = cockpitUrl ? `your ${DEVELOPER_COCKPIT}` : "your browser";
+  console.log(`     Next: open it in your editor and change one line in`);
+  console.log(`     content/home.html — you'll see it reflected in ${where}.`);
+}
+
+/** The crafted "you're live" ending — a PROMINENT milestone banner (u2) that,
+ * when we hold a Developer Cockpit URL, explicitly sends the developer BACK to
+ * their cockpit as the next place to look; then the AI-wow (G), seeded with
+ * IDEAS[0] (G2/G3 — one prompt list shared with `tot ideas`, no drift). */
+function printLiveEnding(tenant, url, elapsed, cockpitUrl = null) {
+  const lines = [
+    `✨  You're live.${elapsed ? `  (${elapsed})` : ""}`,
+    `    ${url}`,
+    "    Edit content/home.html + save → it reloads.",
+  ];
+  if (cockpitUrl) {
+    lines.push("");
+    lines.push(`➜  Back to your ${DEVELOPER_COCKPIT} to watch it happen:`);
+    lines.push(`   ${cockpitUrl}`);
+  }
+  console.log(milestoneBanner(lines));
   console.log("  " + versionStamp("native"));
   console.log("");
   console.log("  Now try, in Claude:");

package/src/commands/validate.mjs

@@ -79,6 +79,10 @@ export function run(argv, ctx) {
   const { ok, findings } = validateTenant(target.dir, {
     tenantId: target.tenantId ?? undefined,
     scope: target.scope ?? undefined,
+    // A checkout / bare-tenant target is served by the ToT storefront platform, so
+    // commerce tenants own the framework routes (/collections, /account, …). Only an
+    // arbitrary --workspace <dir> stays conservative (unless its config resolves the host).
+    mode: args.workspace ? "workspace" : "monorepo",
   });
 
   if (args.json) {

package/src/dev-logs.mjs

@@ -4,9 +4,10 @@
  * (dev.mjs). Extracted so the two entrypoints stream identically instead of one
  * inheriting the raw vite/astro firehose while the other collapses it.
  *
- * Dependency-free (no imports) — pure line buffering + filtering over a child's
- * stdout/stderr.
+ * Depends only on the shared, dependency-free banner helper — otherwise pure
+ * line buffering + filtering over a child's stdout/stderr.
  */
+import { milestoneBanner, DEVELOPER_COCKPIT } from "./banner.mjs";
 
 /**
  * Stream the running dev server's output in BUSINESS terms. The runner + Vite +
@@ -16,17 +17,32 @@
  * save-reload into one clean "↻ your store reloaded", drop the known internal
  * noise, and pass anything else through (indented) so nothing important is
  * hidden. Ctrl-C still tears the server down (the child owns the TTY signals).
+ *
+ * The FIRST save→reload is the aha milestone (u2): with a `cockpitUrl` it's a
+ * PROMINENT banner that sends the developer back to their Developer Cockpit to
+ * see the change; every reload after that is the quiet "↻ your store reloaded"
+ * line so a working dev loop doesn't get spammed with banners.
  * @param {import("node:child_process").ChildProcess} child
+ * @param {{ cockpitUrl?: string|null, out?: (s: string) => void, reloadDebounceMs?: number }} [opts]
+ *   `out` is the sink (default: process.stdout.write) — injectable for tests.
+ *   `reloadDebounceMs` collapses a single save's HMR burst into one line (default 1000ms).
  */
-export function streamDevLogs(child) {
+export function streamDevLogs(
+  child,
+  { cockpitUrl = null, out = (s) => process.stdout.write(s), reloadDebounceMs = 1000 } = {},
+) {
   // Startup churn + tool internals — never user-facing. Matched AFTER stripping
   // the runner/Vite "HH:MM:SS " timestamp prefix (see `body` below), so a
   // timestamped internal line like "10:50:17 [vite] connected" is still dropped.
+  // The node:* / ExperimentalWarning / (node:NNNN) / "--trace-warnings" and the
+  // boot "fatal: not a git repository" lines are dropped too (b4) — scary,
+  // non-actionable boot noise that reads as a broken first run.
   const NOISE =
-    /^(\[vite\]|\[types\]|\[@astrojs|\[WARN\]|▲|┃|astro\s+v[\d.]|(Local|Network)\s+http|watching for file changes|Scope: all \d|copy-tenant-assets:|.*dependency optimized|.*optimized dependencies changed|.*program reload|\d+ deprecated|Packages:\s*\+|Progress:\s*resolved|Downloading @|node_modules\/|devDependencies:|\+\s+\w+@|Done in \d)/i;
+    /^(\[vite\]|\[types\]|\[@astrojs|\[WARN\]|▲|┃|astro\s+v[\d.]|(Local|Network)\s+http|watching for file changes|Scope: all \d|copy-tenant-assets:|.*dependency optimized|.*optimized dependencies changed|.*program reload|\d+ deprecated|Packages:\s*\+|Progress:\s*resolved|Downloading @|node_modules\/|devDependencies:|\+\s+\w+@|Done in \d|\(node:\d+\)|ExperimentalWarning|node:internal\/|\(Use `node --trace-warnings|fatal: not a git repository)/i;
   // A real save-triggered reload (not startup "program reload" churn).
   const RELOAD = /(hmr update|page reload)/i;
   let reloadPending = null;
+  let sawFirstReload = false;
   const emit = (line) => {
     const t = line.replace(/\s+$/, "");
     if (!t) return;
@@ -35,13 +51,24 @@ export function streamDevLogs(child) {
     const body = t.replace(/^\d{1,2}:\d{2}:\d{2}(\.\d+)?\s+/, "").replace(/^\s+/, "");
     if (RELOAD.test(body)) {
       if (reloadPending) return; // debounce a burst into one line
-      reloadPending = setTimeout(() => { reloadPending = null; }, 1000);
+      reloadPending = setTimeout(() => { reloadPending = null; }, reloadDebounceMs);
       if (reloadPending.unref) reloadPending.unref();
-      process.stdout.write("  ↻ your store reloaded\n");
+      if (!sawFirstReload && cockpitUrl) {
+        sawFirstReload = true;
+        out(milestoneBanner([
+          "↻  Your edit is live — your store reloaded.",
+          "",
+          `➜  See it in your ${DEVELOPER_COCKPIT}:`,
+          `   ${cockpitUrl}`,
+        ]) + "\n");
+        return;
+      }
+      sawFirstReload = true;
+      out("  ↻ your store reloaded\n");
       return;
     }
     if (NOISE.test(body)) return;
-    process.stdout.write(`  ${t}\n`);
+    out(`  ${t}\n`);
   };
   lineStream(child.stdout, emit);
   lineStream(child.stderr, emit);

package/src/validate.mjs

@@ -7,8 +7,10 @@
  * mirror the reconcile pipeline's own gate (@tot/private-controlplane
  * customization-reconcile.ts `mapToArtifact` / `validateRawHtml`). Kept in step
  * with the in-repo source of truth `scripts/tenant/validate.mjs` (which the CI
- * regression test imports). FOLLOW-UP: collapse the two onto this module as the
- * single source once the package is the install surface.
+ * regression test imports) — including its platform-route awareness (commerce
+ * tenants own /collections, /products/<handle>, /search, /saved, /account, /cart,
+ * so links into those are not false `link-dangling` warnings). FOLLOW-UP: collapse
+ * the two onto this module as the single source once the package is the install surface.
  *
  * Pure + dependency-free (readFileSync only). `validateTenant(dir)` is the entry
  * point; `validateConfigShape` is exported for focused testing.
@@ -333,10 +335,72 @@ const HREF_RE = /\bhref\s*=\s*"([^"]*)"/gi;
 const SRC_RE = /\b(?:src|srcset)\s*=\s*"([^"]*)"/gi;
 const STYLE_OPEN_WITH_ATTRS_RE = /<style\s+[^>]*>/i;
 
+// --- platform-owned routes (framework surfaces, NOT tenant pages) ------------
+/**
+ * When the tenant is served BY this ToT storefront platform, the platform itself
+ * owns a set of framework routes — catalog (`/collections`, `/collections/<handle>`,
+ * `/products/<handle>`), `/search`, `/saved`, the auth/account route (`/account`),
+ * and `/cart` when cart/checkout is on. A COMMERCE tenant that links into those is
+ * linking to a live platform surface, so such links must NOT be flagged
+ * `link-dangling` — only genuinely-missing tenant pages/assets should warn.
+ *
+ * MARKETING tenants get none of these (their commerce affordances are off), so they
+ * stay strict. Standalone / unresolved hosts also stay conservative — they can't
+ * assume the eventual host is this platform — UNLESS the config resolves the host
+ * (`"hostPlatform": "tot-storefront"`).
+ *
+ * The route→feature mapping mirrors `resolveTenantFeatures` in
+ * `@tot/public-runtime` tenant.ts (catalog / productSearch / savedItems) — keep in step.
+ */
+const COMMERCE_ROUTE_FEATURES = { catalog: true, productSearch: true, savedItems: true };
+
+/**
+ * @param {any} config parsed `.tot/config.json` (or null)
+ * @param {boolean} hostIsPlatform is the serving host this ToT storefront platform?
+ * @returns {{active:boolean, owns:(path:string)=>boolean}}
+ */
+function resolvePlatformRouteOwnership(config, hostIsPlatform) {
+  const inert = { active: false, owns: () => false };
+  if (!hostIsPlatform) return inert; // standalone / unresolved host → conservative
+  const siteType = config?.siteType ?? "commerce"; // unset == commerce (platform default)
+  if (siteType === "marketing") return inert; // marketing owns no commerce routes
+  // commerce feature defaults, with any explicit per-flag overrides layered on
+  const features = { ...COMMERCE_ROUTE_FEATURES };
+  const overrides = config?.features;
+  if (overrides && typeof overrides === "object") {
+    for (const [k, v] of Object.entries(overrides)) if (v !== undefined && k in features) features[k] = v;
+  }
+  const cartEnabled = config?.capabilities?.cartCheckout?.enabled ?? true; // commerce default: on
+
+  const exact = new Set(["/account"]); // the auth/account route the platform currently serves
+  const prefixes = ["/account/"];
+  if (features.catalog) {
+    exact.add("/collections");
+    prefixes.push("/collections/", "/products/");
+  }
+  if (features.productSearch) exact.add("/search");
+  if (features.savedItems) exact.add("/saved");
+  if (cartEnabled) {
+    exact.add("/cart");
+    prefixes.push("/cart/");
+  }
+  return {
+    active: true,
+    owns(path) {
+      const norm = path.replace(/\/+$/, "") || "/";
+      if (exact.has(norm)) return true;
+      return prefixes.some((p) => path.startsWith(p));
+    },
+  };
+}
+
 /**
  * Full static validation of a tenant directory (content/ public/ theme.json [.tot/]).
  * @param {string} tenantDir absolute path to the tenant dir
- * @param {{tenantId?:string, scope?:string}} [opts]
+ * @param {{tenantId?:string, scope?:string, mode?:"monorepo"|"workspace"}} [opts]
+ *   `mode` — "monorepo" (default): served by this platform, so commerce tenants own
+ *   the framework routes. "workspace": a standalone checkout, conservative about
+ *   platform-route ownership unless the config resolves the host (`hostPlatform`).
  * @returns {{ok:boolean, findings:Finding[]}}
  */
 export function validateTenant(tenantDir, opts = {}) {
@@ -370,6 +434,10 @@ export function validateTenant(tenantDir, opts = {}) {
     );
   }
   const scope = opts.scope || config?.scope;
+  // platform-route awareness: which framework routes the host platform owns for this tenant
+  const mode = opts.mode === "workspace" ? "workspace" : "monorepo";
+  const hostIsPlatform = mode === "monorepo" || config?.hostPlatform === "tot-storefront";
+  const platformRoutes = resolvePlatformRouteOwnership(config, hostIsPlatform);
   if (config?.capabilities) {
     findings.push(...validateCapabilitiesDoc(config.capabilities, ".tot/config.json capabilities", config));
   }
@@ -456,7 +524,7 @@ export function validateTenant(tenantDir, opts = {}) {
     }
 
     for (const m of html.matchAll(HREF_RE)) {
-      findings.push(...checkLink(m[1].trim(), r, scope, pageTargets));
+      findings.push(...checkLink(m[1].trim(), r, scope, pageTargets, platformRoutes.owns));
     }
     for (const m of html.matchAll(SRC_RE)) {
       const f = checkAsset(m[1].trim(), r, publicDir, opts.tenantId || config?.tenant);
@@ -480,7 +548,7 @@ function buildPageTargetSet(contentDir, pagesDir) {
   return set;
 }
 
-function checkLink(href, file, scope, pageTargets) {
+function checkLink(href, file, scope, pageTargets, ownsPlatformRoute = () => false) {
   const out = [];
   if (!href || href.startsWith("#") || href.startsWith("mailto:") || href.startsWith("tel:")) return out;
   if (/^https?:\/\/localhost(?::\d+)?/i.test(href)) {
@@ -501,9 +569,10 @@ function checkLink(href, file, scope, pageTargets) {
     if (href.startsWith("/tenants/")) return out;
     const path = href.split(/[?#]/)[0];
     const norm = path.replace(/\/+$/, "") || "/";
-    if (!pageTargets.has(path) && !pageTargets.has(norm) && !pageTargets.has(norm + "/")) {
-      out.push(mk(WARN, "link-dangling", file, `internal link ${path} does not resolve to a known page (would 404)`));
-    }
+    if (pageTargets.has(path) || pageTargets.has(norm) || pageTargets.has(norm + "/")) return out;
+    // a framework route the host platform owns (e.g. /collections, /account) is not a dangling tenant page
+    if (ownsPlatformRoute(path)) return out;
+    out.push(mk(WARN, "link-dangling", file, `internal link ${path} does not resolve to a known page (would 404)`));
     return out;
   }
   out.push(mk(WARN, "link-relative", file, `relative link "${href}" — internal links should be root-absolute (/foo/)`));