@tokenoftrust/storefront-runner 1.3.4-rc.1 → 1.3.4-rc.2

package/apps/storefront/astro.config.mjs

@@ -16,10 +16,19 @@ import cloudflare from "@astrojs/cloudflare";
 // npm before/as this storefront ships, else the pasted `npm i -g @tokenoftrust/cli@<v>` 404s.
 // The CLI publish workflow (.github/workflows/publish-cli.yml) is the publisher; there is no
 // deploy-time guard yet that asserts the embedded version exists on npm — a worthwhile add.
-const cliVersion = JSON.parse(
-  readFileSync(fileURLToPath(new URL("../../packages/cli/package.json", import.meta.url)), "utf8"),
-).version;
-const cliInstallSpec = `@tokenoftrust/cli@${cliVersion}`;
+// NEVER THROWS (like gitSha below): the published RUNNER tree prunes packages/cli, and a
+// bare read here crashed `astro dev` for every standalone invited-dev boot. The runner's
+// local page falls back to the floating spec — only the HOSTED cockpit needs the pin.
+const cliVersion = (() => {
+  try {
+    return JSON.parse(
+      readFileSync(fileURLToPath(new URL("../../packages/cli/package.json", import.meta.url)), "utf8"),
+    ).version;
+  } catch {
+    return null; // standalone runner tree — packages/cli isn't shipped
+  }
+})();
+const cliInstallSpec = cliVersion ? `@tokenoftrust/cli@${cliVersion}` : "@tokenoftrust/cli";
 
 // The commit THIS build was cut from, baked in at BUILD time so /health can report
 // exactly which code is live (see src/lib/health.ts + src/middleware). Prefer a CI-

package/apps/storefront/package.json

@@ -21,7 +21,7 @@
     "@astrojs/preact": "^6.0.0",
     "@storyblok/astro": "^10.0.0",
     "@tailwindcss/vite": "^4.3.1",
-    "@tot/public-runtime": "workspace:*",
+    "@tot/public-runtime": "*",
     "astro": "^7.0.3",
     "fuse.js": "^7.4.2",
     "jose": "^6.2.3",

package/apps/storefront/src/lib/dev/runtimeStore.ts

@@ -1,16 +1,23 @@
 /**
- * Per-vendor "local dev runtime" latest-state — the LIVE half of the
+ * Per-DEVELOPER "local dev runtime" latest-state — the LIVE half of the
  * local→hosted activity bridge (G1). Where activityStore.ts holds a ring buffer
- * of file-SAVE events, this holds ONE record per vendor: the most recent
- * heartbeat the developer's LOCAL `tot dev`/`tot start` sent (see the CLI's
- * dev-heartbeat.mjs). The hosted cockpit reads it to show a LIVE, clickable
- * local-dev link + the running CLI version.
+ * of file-SAVE events, this holds the most recent heartbeat a developer's LOCAL
+ * `tot dev`/`tot start` sent (see the CLI's dev-heartbeat.mjs). The hosted cockpit
+ * reads it to show a LIVE, clickable local-dev link + the running CLI version.
+ *
+ * SCOPED PER (tenant, developer email), NOT per tenant: a store can have many
+ * team members, each running their OWN local loop. Keying on the tenant alone
+ * made every teammate's heartbeat collapse into one latest-wins slot, so the
+ * owner saw "connected" whenever ANYONE with access was running `tot dev` —
+ * never their own machine specifically. The key is now
+ * `dev-runtime:<tenant>:<email>`; the POST writes under the HEARTBEATING dev's
+ * verified email, and the GET reads the VIEWER's own — so "connected" means
+ * "YOUR loop", not "someone on this store".
  *
  * Deliberately SEPARATE from the file-activity buffer: a heartbeat is
- * latest-wins state, not an appended event, so it lives under its own
- * `dev-runtime:<tenant>` key and never touches the ring buffer. No file CONTENT
- * is ever stored — `url` is only the local `http://localhost:<port>/<tenant>/`
- * (low-sensitivity, per decision).
+ * latest-wins state, not an appended event, so it lives under its own key and
+ * never touches the ring buffer. No file CONTENT is ever stored — `url` is only
+ * the local `http://localhost:<port>/<tenant>/` (low-sensitivity, per decision).
  *
  * Liveness is computed SERVER-side from `aliveAt` (the ingest-time server clock,
  * NOT the client's `at`) so a skewed local clock can't make a dead loop look
@@ -73,11 +80,12 @@ export interface DevRuntimeView extends Omit<DevRuntime, "email"> {
 
 const KEY_PREFIX = "dev-runtime:";
 /**
- * Secondary index: traceId -> the runtime record's tenant key, so support can
- * look a developer's LIVE session up by the trace id minted at sign-in without
- * scanning. Mirrors the developer+tenant index in activityIngestToken.ts; a KV
- * store has no GSI, so the smallest correct discovery path is a maintained index
- * key (written on every heartbeat, cleared on reset). Same TTL as the record.
+ * Secondary index: traceId -> {appDomain, email} (JSON), so support can look a
+ * developer's LIVE session up by the trace id minted at sign-in without scanning.
+ * Stores BOTH components because the record key is now per (tenant, email).
+ * Mirrors the developer+tenant index in activityIngestToken.ts; a KV store has no
+ * GSI, so the smallest correct discovery path is a maintained index key (written
+ * on every heartbeat, cleared on reset). Same TTL as the record.
  */
 const TRACE_INDEX_PREFIX = "dev-runtime-by-trace:";
 /**
@@ -107,8 +115,14 @@ const MAX_EMAIL_LEN = 320;
 /** A UUID; a touch of headroom for other id shapes. */
 const MAX_TRACE_LEN = 64;
 
-function key(appDomain: string): string {
-  return KEY_PREFIX + appDomain;
+/**
+ * The per-developer record key: `dev-runtime:<tenant>:<email>`. Email is the
+ * session principal (lowercased here for a stable key). An absent email degrades
+ * to a tenant-only suffix — never silently shared, just an unattributed slot the
+ * viewer's own-email read won't match.
+ */
+function key(appDomain: string, email: string | undefined): string {
+  return `${KEY_PREFIX}${appDomain}:${(email ?? "").toLowerCase()}`;
 }
 
 function traceKey(traceId: string): string {
@@ -188,10 +202,15 @@ export function shapeRuntime(
   return rt;
 }
 
-/** Read the vendor's latest runtime, or null when none/malformed. Never throws. */
-export async function readRuntime(kv: KVNamespace, appDomain: string): Promise<DevRuntime | null> {
+/** Read a developer's latest runtime (their tenant + email), or null when
+ * none/malformed. Never throws. */
+export async function readRuntime(
+  kv: KVNamespace,
+  appDomain: string,
+  email: string | undefined,
+): Promise<DevRuntime | null> {
   try {
-    const raw = await kv.get(key(appDomain));
+    const raw = await kv.get(key(appDomain, email));
     if (!raw) return null;
     const parsed = JSON.parse(raw);
     if (!parsed || typeof parsed !== "object" || typeof parsed.aliveAt !== "number") return null;
@@ -201,17 +220,21 @@ export async function readRuntime(kv: KVNamespace, appDomain: string): Promise<D
   }
 }
 
-/** Overwrite the vendor's runtime with the latest heartbeat (latest-wins, TTL'd).
- * When the record carries a traceId, also (re)write the by-trace index so support
- * can resolve trace -> tenant -> live runtime without a scan. */
+/** Overwrite a developer's runtime with their latest heartbeat (latest-wins, TTL'd),
+ * scoped to (tenant, email). When the record carries a traceId, also (re)write the
+ * by-trace index (storing BOTH tenant + email) so support can resolve
+ * trace -> record without a scan. */
 export async function writeRuntime(
   kv: KVNamespace,
   appDomain: string,
+  email: string | undefined,
   rt: DevRuntime,
 ): Promise<void> {
-  await kv.put(key(appDomain), JSON.stringify(rt), { expirationTtl: TTL_SECONDS });
+  await kv.put(key(appDomain, email), JSON.stringify(rt), { expirationTtl: TTL_SECONDS });
   if (rt.traceId) {
-    await kv.put(traceKey(rt.traceId), appDomain, { expirationTtl: TTL_SECONDS });
+    await kv.put(traceKey(rt.traceId), JSON.stringify({ appDomain, email: email ?? "" }), {
+      expirationTtl: TTL_SECONDS,
+    });
   }
 }
 
@@ -227,17 +250,36 @@ export async function readRuntimeByTrace(
   traceId: string,
 ): Promise<DevRuntime | null> {
   if (!traceId) return null;
-  const appDomain = await kv.get(traceKey(traceId));
+  const ptr = await kv.get(traceKey(traceId));
+  if (!ptr) return null;
+  // Pointer is JSON {appDomain, email}. A bare-string pointer is a legacy
+  // (pre per-developer) entry with no email to scope by — treat as unresolvable
+  // (it re-establishes on the next heartbeat, well within the 1h TTL).
+  let appDomain: string | undefined;
+  let email: string | undefined;
+  try {
+    const parsed = JSON.parse(ptr);
+    if (parsed && typeof parsed === "object") {
+      appDomain = parsed.appDomain;
+      email = parsed.email;
+    }
+  } catch {
+    return null;
+  }
   if (!appDomain) return null;
-  return readRuntime(kv, appDomain);
+  return readRuntime(kv, appDomain, email);
 }
 
-/** Delete the vendor's runtime record — a "true reset" so a killed store stops
- * reading as up immediately instead of lingering until the TTL/live-window expires.
- * Also drops the by-trace index entry for its current trace, if any. */
-export async function clearRuntime(kv: KVNamespace, appDomain: string): Promise<void> {
-  const existing = await readRuntime(kv, appDomain);
-  await kv.delete(key(appDomain));
+/** Delete a developer's runtime record (their tenant + email) — a "true reset" so a
+ * killed loop stops reading as up immediately instead of lingering until the
+ * TTL/live-window expires. Also drops the by-trace index entry for its current trace. */
+export async function clearRuntime(
+  kv: KVNamespace,
+  appDomain: string,
+  email: string | undefined,
+): Promise<void> {
+  const existing = await readRuntime(kv, appDomain, email);
+  await kv.delete(key(appDomain, email));
   if (existing?.traceId) await kv.delete(traceKey(existing.traceId));
 }
 

package/apps/storefront/src/pages/cockpit.astro

@@ -1927,7 +1927,7 @@ const hostedActivityScript = `
           <h1>Get your store running.
             <span class="info" id="info1">
               <button class="info-btn" type="button" aria-label="What does this command do?">i</button>
-              <span class="info-pop" role="tooltip">Installs the <code>tot</code> command, signs your terminal in with a single-use code, checks out your store, runs it, and opens your browser. No Docker, no browser sign-in, nothing to provision. From then on it's just <code>tot start</code>.</span>
+              <span class="info-pop" role="tooltip">Installs the <code>tot</code> command, signs your terminal in with a single-use code, checks out your store into a new <code>{appDomain}</code> folder, runs it, and opens your browser. No Docker, no browser sign-in, nothing to provision. From then on it's just <code>tot start</code>.</span>
             </span>
           </h1>
           <p class="goal">{hasStoreAccess
@@ -1951,10 +1951,10 @@ const hostedActivityScript = `
             </div>
           )}
           <p class="cmd-note" id="cli-cmd-note">{hasStoreAccess
-            ? <>This mints a <em>single-use, short-lived</em> sign-in code, shows the full command here, and copies it to your clipboard — paste it and press Enter. It signs you in, runs your store, and opens your browser. Nothing to retype.</>
-            : <>You'll need <em>Node.js and your invite</em>. Sign in through your invite link and this page hands you a one-paste setup command — no Docker, nothing to provision.</>}</p>
+            ? <>This mints a <em>single-use, short-lived</em> sign-in code, shows the full command here, and copies it to your clipboard. Paste it <em>from the folder where you keep projects</em> — it creates a <code>{appDomain}</code> folder there with your store's code, signs you in, runs your store, and opens your browser. Nothing to retype.</>
+            : <>You'll need <em>Node.js 22.12+ (24 LTS recommended) and your invite</em>. Sign in through your invite link and this page hands you a one-paste setup command — no Docker, nothing to provision.</>}</p>
 
-          <p class="cmd-steps">Prefer the steps? <code>npm i -g {cliInstallSpec}</code>, then <code>tot checkout {appDomain}</code>, <code>cd {appDomain}</code>, <code>tot dev</code>. New to Node? Get it at <a href="https://nodejs.org">nodejs.org</a> — it includes <code>npm</code>.</p>
+          <p class="cmd-steps">Prefer the steps? <code>npm i -g {cliInstallSpec}</code>, then <code>tot checkout {appDomain}</code>, <code>cd {appDomain}</code>, <code>tot dev</code>. New to Node? Get Node 24 (LTS) at <a href="https://nodejs.org">nodejs.org</a> — it includes <code>npm</code>.</p>
 
           {isLocalDevLoop && (
             <div class="detect" id="detect" data-listening="true">

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "1.3.4-rc.1",
+  "version": "1.3.4-rc.2",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",
   "engines": {
-    "node": ">=24"
+    "node": ">=22.12.0"
   },
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ],
   "scripts": {
     "dev": "pnpm --filter @tot/storefront-runner dev",
     "build": "pnpm --filter @tot/storefront-runner build",

package/pnpm-workspace.yaml

@@ -1,6 +1,7 @@
 packages:
   - "apps/*"
   - "packages/*"
+linkWorkspacePackages: true
 onlyBuiltDependencies:
   - esbuild
   - sharp

package/scripts/dev/checkout-watch.mjs

@@ -1,36 +1,17 @@
 // @ts-check
 import { watch, readdirSync, statSync, existsSync, cpSync, rmSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
+import { IGNORED_WATCH_DIRS, isTransientWatchFile } from "./transient-files.mjs";
+
+// Re-exported so existing importers (checkout-watch.test.mjs) keep working after the
+// predicate moved to its own typed module.
+export { isTransientWatchFile };
 
 // Standalone (`tot dev --workspace`) re-sync: the developer's checkout is COPIED
 // into the storefront's in-tree tenants/<id>/ (Vite's server.fs.allow refuses files
 // outside its root), and each save is mirrored back so Vite's own watcher fires the
 // browser reload. This module owns detecting the save + doing the copy.
 
-/** Directories never worth descending into — VCS/dep/build noise that would churn the poll. */
-const IGNORED_WATCH_DIRS = new Set([".git", "node_modules", ".astro", ".cache", ".turbo"]);
-
-/**
- * True for editor/OS transient files that are NOT real content edits. A raw poll of
- * the checkout subtree would otherwise treat a vim swap (`.home.html.swp`), a Finder
- * `.DS_Store`, an emacs autosave (`#home.html#`) or lock (`.#home.html`), a `~` backup,
- * or vim's `4913` write-probe as a content change — re-syncing it into the in-tree copy
- * and firing a spurious reload / "changed" report (the ".swp shows up as a change" bug).
- * Matched on the BASENAME so it's independent of depth. "Official" changes track the
- * store's real content; untracked editor junk is surfaced only at publish time, not here.
- */
-export function isTransientWatchFile(name) {
-  return (
-    /\.(sw[a-z]{1,2}|tmp|temp|orig|bak)$/i.test(name) || // vim swap (.swp/.swo/.swx/.swpx…), temp/backup
-    /~$/.test(name) || // gedit/emacs/kate trailing-tilde backup
-    /^\.#/.test(name) || // emacs lockfile (.#file)
-    /^#.*#$/.test(name) || // emacs autosave (#file#)
-    name === ".DS_Store" ||
-    name === "Thumbs.db" ||
-    name === "4913" // vim's write-probe file
-  );
-}
-
 /** Re-sync one changed checkout path into its in-tree copy (copy on save, remove on delete). */
 export function resync(sourceRoot, targetRoot, rel) {
   const from = rel ? join(sourceRoot, rel) : sourceRoot;

package/scripts/dev/file-browser.mjs

@@ -17,7 +17,7 @@ import { readFileSync, readdirSync, statSync } from "node:fs";
 import { join, extname, sep } from "node:path";
 import { resolveSafePath, matchesWriteAllowlist } from "./safe-path.mjs";
 import { resolveTenantSourceRoot } from "./tenant-source-root.mjs";
-import { isTransientWatchFile } from "./checkout-watch.mjs";
+import { isTransientWatchFile } from "./transient-files.mjs";
 
 /** Above this, the viewer degrades to "not shown" rather than shipping a huge string. */
 const MAX_FILE_BYTES = 512 * 1024;

package/scripts/dev/transient-files.mjs

@@ -0,0 +1,34 @@
+// @ts-check
+/**
+ * Editor/OS transient-file predicate — shared by the local dev loop's file WATCHER
+ * (checkout-watch.mjs) and the source-tree browser (file-browser.mjs) so both hide
+ * the same non-content noise: a vim swap (`.home.html.swp`), an emacs autosave
+ * (`#home.html#`) or lock (`.#home.html`), a `~` backup, `.DS_Store`/`Thumbs.db`, or
+ * vim's `4913` write-probe. Kept in its own tiny, fully-typed module so a consumer
+ * that only needs the predicate never drags the watcher's other internals into its
+ * typecheck graph.
+ */
+
+/** Directories never worth descending into — VCS/dep/build noise that would churn a poll. */
+export const IGNORED_WATCH_DIRS = new Set([".git", "node_modules", ".astro", ".cache", ".turbo"]);
+
+/**
+ * True for editor/OS transient files that are NOT real content edits. A raw poll of
+ * a checkout subtree would otherwise treat one as a content change — re-syncing it,
+ * firing a spurious reload, and showing it as an untracked change. Matched on the
+ * BASENAME so it's independent of depth. "Official" changes track the store's real
+ * content; untracked editor junk is surfaced only at publish time, not here.
+ * @param {string} name the file basename
+ * @returns {boolean}
+ */
+export function isTransientWatchFile(name) {
+  return (
+    /\.(sw[a-z]{1,2}|tmp|temp|orig|bak)$/i.test(name) || // vim swap (.swp/.swo/.swx/.swpx…), temp/backup
+    /~$/.test(name) || // gedit/emacs/kate trailing-tilde backup
+    /^\.#/.test(name) || // emacs lockfile (.#file)
+    /^#.*#$/.test(name) || // emacs autosave (#file#)
+    name === ".DS_Store" ||
+    name === "Thumbs.db" ||
+    name === "4913" // vim's write-probe file
+  );
+}

package/scripts/tot-dev.mjs

@@ -49,6 +49,7 @@
  * Ctrl-C stops the server. Exit 1 = can't resolve tenant/domain/workspace; 2 = bad usage.
  */
 import { spawn, spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
 import {
   readFileSync,
   existsSync,
@@ -356,10 +357,22 @@ const devSourceRoot = resolveDevSourceRoot(workspacePath, repoRoot, tenant);
 const spawnEnv = workspacePath
   ? { ...process.env, ASTRO_DEV_BACKGROUND: "1", TOT_DEV_TENANT: tenant, TOT_DEV_SOURCE_ROOT: devSourceRoot }
   : { ...process.env, TOT_DEV_TENANT: tenant, TOT_DEV_SOURCE_ROOT: devSourceRoot };
+// LAUNCHER-AGNOSTIC astro spawn: the published runner tree may have been
+// installed by pnpm OR npm (npm ships with every Node — the runner must not
+// require pnpm at RUNTIME), so resolve astro's real entry through Node's own
+// resolver from the app package and exec it with our Node. No package-manager
+// binary, no .bin shims, and no coupling to the package's name (the build
+// renames @tot/storefront → @tot/storefront-runner in the shipped tree, which
+// the old `pnpm --filter <name> exec` had to track).
+const appDir = resolve(repoRoot, "apps/storefront");
+const astroEntry = resolve(
+  dirname(createRequire(join(appDir, "package.json")).resolve("astro/package.json")),
+  "bin/astro.mjs", // astro's package.json bin entry
+);
 const child = spawn(
-  "pnpm",
-  ["--filter", "@tot/storefront-runner", "exec", "astro", "dev", "--port", port, "--host"],
-  { cwd: repoRoot, stdio: "inherit", env: spawnEnv },
+  process.execPath,
+  [astroEntry, "dev", "--port", port, "--host"],
+  { cwd: appDir, stdio: "inherit", env: spawnEnv },
 );
 
 // Clean up grafts on every exit path so we never leave symlinks in the tree.