@tokenoftrust/storefront-runner 1.4.1 → 1.4.2-rc.0

package/packages/public-runtime/src/static-bundle.ts

@@ -0,0 +1,357 @@
+/**
+ * Digest-addressed static-bundle serving (T2, ADR 0012 —
+ * `docs/architecture/decisions/0012-instant-static-rollback-pointer-substrate.md`),
+ * T6-aware (per-file content-addressed asset dedup,
+ * `docs/epics/proposed/storefront-instant-static-rollback.md` Addendum §A).
+ *
+ * Reads an already-materialized, already-staged static bundle
+ * (`scripts/publish/materialize-tenant.mjs` output, staged by
+ * `scripts/publish/stage-bundle.mjs` to `versions/<treeDigest>/…` PLUS the
+ * shared `assets/<sha256>` pool, T6) straight out of R2 and serves the bytes
+ * VERBATIM — no re-render, no per-request CSP-nonce middleware (the bundle
+ * carries one pinned nonce for its whole tree; see the ADR's "Consequences"
+ * section). This is the read half: the write path (what PUTs a bundle into this
+ * R2 bucket) is `scripts/publish/lib/r2-runner.mjs`, which stages every
+ * `versions/<digest>/` bundle at candidate-prebuild time. Every static-publish
+ * tenant's production reads are served through here.
+ *
+ * DIGEST CONTRACT (RECONCILED, T14 — ADR 0012): the caller resolves "what to
+ * serve" via `resolveChannelDigest(get, tenantId, "live")` — the `channelDigests`
+ * companion to the `live` channel pointer, NOT `resolveChannelVersion` (which
+ * returns the versionId / Gitea sha, a DIFFERENT namespace than the treeDigest).
+ * `gatedPromote` (go-live) and `rollbackCandidateAtomic` (rollback) write the
+ * staged bundle's real `treeDigest` to `channelDigests.live` in the SAME CAS flip
+ * that moves the versionId, so this module gets the exact R2 key prefix
+ * `versions/<treeDigest>/`. A static tenant whose `live` has a versionId but no
+ * digest companion yet resolves to `null` here and fails closed (see below)
+ * rather than serving the wrong bytes under the versionId.
+ *
+ * T6 KEY RESOLUTION (`kind: "route"` vs `kind: "asset"`, `scripts/publish/lib/
+ * asset-pool.mjs`'s classification, carried verbatim in `manifest.files`): the
+ * manifest is now read on EVERY request (not just HTML, as before T6) because
+ * it's the ONLY source of truth for which R2 key a bundle-relative path
+ * resolves to — `kind: "route"` files still live at `versions/<digest>/<rel>`
+ * (rendered fresh per version), `kind: "asset"` files live at the SHARED,
+ * content-addressed `assets/<sha256><ext>` pool (`staticBundleAssetPoolKey`,
+ * kept in lockstep with `scripts/publish/lib/asset-pool.mjs`'s `assetPoolKey`
+ * — that module can't be imported here, this is the Worker bundle, that one
+ * runs under plain node). A `rel` absent from `manifest.files` (a genuinely
+ * unexpected path, or a pre-T6 manifest with no `files` classification) falls
+ * back to the OLD `versions/<digest>/<rel>` lookup — fail-closed on a miss
+ * either way, never a guess.
+ */
+import { assetContentType } from "./tenant-assets.js";
+
+// ---------------------------------------------------------------------------
+// R2 seam — same structural subset tenant-assets.ts uses (no workers-types dep)
+// ---------------------------------------------------------------------------
+
+export interface StaticBundleR2ObjectLike {
+  body: ReadableStream<Uint8Array> | null;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  size?: number;
+}
+
+export interface StaticBundleR2BucketLike {
+  get(key: string): Promise<StaticBundleR2ObjectLike | null>;
+}
+
+// ---------------------------------------------------------------------------
+// Path mapping — request pathname -> bundle-relative object path
+// ---------------------------------------------------------------------------
+
+/**
+ * Reject empty, absolute-outside-bundle, or traversal-bearing relative paths
+ * (mirrors `tenant-assets.ts`'s `isSafeRel`, duplicated here to keep this
+ * module import-independent of the assets pointer model).
+ */
+function isSafeRel(rel: string): boolean {
+  if (!rel) return false;
+  return !rel.split("/").some((seg) => seg === ".." || seg === ".");
+}
+
+/**
+ * Map a request pathname to the bundle-relative file the materializer wrote
+ * for it — the SAME transform `scripts/publish/lib/materialize.mjs`'s
+ * `bundlePathForRoute` (routes) and `assetFilePath` (assets) apply, ported
+ * here as one pure function since `scripts/` is not importable from the
+ * Worker bundle:
+ *   "/"            -> "index.html"
+ *   "/about"       -> "about/index.html"   (directory-index for pretty URLs)
+ *   "/a/b/"        -> "a/b/index.html"
+ *   "/sitemap.xml" -> "sitemap.xml"        (a real file extension: as-is)
+ *   "/_astro/x.js" -> "_astro/x.js"        (asset: as-is)
+ * Returns null for an unsafe path (traversal, decode failure).
+ */
+export function staticBundleRelPath(pathname: string): string | null {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    return null;
+  }
+  const clean = decoded.replace(/^\/+/, "").replace(/\/+$/, "");
+  if (clean === "") return "index.html";
+  if (!isSafeRel(clean)) return null;
+  const last = clean.split("/").pop() || "";
+  if (/\.[a-z0-9]+$/i.test(last)) return clean;
+  return `${clean}/index.html`;
+}
+
+/** Full R2 object key for a `route`-kind bundle-relative path at a given digest. */
+export function staticBundleObjectKey(digest: string, rel: string): string {
+  return `versions/${digest}/${rel}`;
+}
+
+/** R2 key for a digest's bundle manifest (materialize-tenant.mjs's `manifest.json`). */
+export function staticBundleManifestKey(digest: string): string {
+  return `versions/${digest}/manifest.json`;
+}
+
+/**
+ * T6: the shared content-addressed pool key for one asset's hash — MUST stay
+ * in lockstep with `scripts/publish/lib/asset-pool.mjs`'s `assetPoolKey`
+ * (same extension-preserving `assets/<sha256hex><ext>` shape; that module
+ * can't be imported here since this is the Worker bundle and that one runs
+ * under plain node — both sides' tests assert the exact key shape).
+ */
+export function staticBundleAssetPoolKey(hash: string, rel: string): string {
+  const dot = rel.lastIndexOf(".");
+  const slash = rel.lastIndexOf("/");
+  const ext = dot > slash ? rel.slice(dot) : "";
+  return `assets/${hash}${ext}`;
+}
+
+/**
+ * Resolve the R2 key to fetch for a `rel` bundle path, using the manifest's
+ * T6 file classification: `kind: "asset"` -> the shared pool key (by content
+ * hash, NOT the version); anything else (`kind: "route"`, or `rel` absent
+ * from `files` entirely — a pre-T6 manifest, or a genuinely unlisted path) ->
+ * the per-version `versions/<digest>/<rel>` key, same as before T6.
+ */
+export function resolveStaticBundleObjectKey(
+  digest: string,
+  rel: string,
+  files: StaticBundleManifest["files"] | undefined,
+): string {
+  const entry = files?.[rel];
+  if (entry?.kind === "asset" && entry.hash) {
+    return staticBundleAssetPoolKey(entry.hash, rel);
+  }
+  return staticBundleObjectKey(digest, rel);
+}
+
+// ---------------------------------------------------------------------------
+// Manifest (CSP pinned-nonce header) — read once per hit for an HTML response
+// ---------------------------------------------------------------------------
+
+/** One `manifest.files` entry (T6, `scripts/publish/lib/asset-pool.mjs`'s `classifyBundleFiles` shape). */
+export interface StaticBundleFileEntry {
+  hash: string;
+  kind: "route" | "asset";
+}
+
+/** The slice of `materialize-tenant.mjs`'s manifest this read path needs. */
+export interface StaticBundleManifest {
+  treeDigest: string;
+  pinnedNonce: string;
+  csp: { headerName: string; value: string } | null;
+  /** T6 classification: relPath -> {hash, kind}. Absent on a pre-T6 manifest — every lookup then falls back to the old versions/<digest>/<rel> key (see `resolveStaticBundleObjectKey`). */
+  files?: Record<string, StaticBundleFileEntry>;
+}
+
+function parseManifest(raw: string): StaticBundleManifest | null {
+  try {
+    const m = JSON.parse(raw) as Partial<StaticBundleManifest>;
+    if (typeof m.treeDigest !== "string" || typeof m.pinnedNonce !== "string") return null;
+    const csp =
+      m.csp &&
+      typeof (m.csp as { headerName?: unknown }).headerName === "string" &&
+      typeof (m.csp as { value?: unknown }).value === "string"
+        ? (m.csp as { headerName: string; value: string })
+        : null;
+    let files: StaticBundleManifest["files"];
+    if (m.files && typeof m.files === "object") {
+      files = {};
+      for (const [rel, entry] of Object.entries(m.files as Record<string, unknown>)) {
+        const e = entry as Partial<StaticBundleFileEntry> | null;
+        if (
+          e &&
+          typeof e.hash === "string" &&
+          (e.kind === "route" || e.kind === "asset")
+        ) {
+          files[rel] = { hash: e.hash, kind: e.kind };
+        }
+      }
+    }
+    return { treeDigest: m.treeDigest, pinnedNonce: m.pinnedNonce, csp, files };
+  } catch {
+    return null;
+  }
+}
+
+/** Read+parse a digest's `manifest.json` from R2. Null on any miss/malformed data. */
+export async function readStaticBundleManifest(
+  bucket: StaticBundleR2BucketLike,
+  digest: string,
+): Promise<StaticBundleManifest | null> {
+  const object = await bucket.get(staticBundleManifestKey(digest));
+  if (!object) return null;
+  const text = new TextDecoder().decode(await object.arrayBuffer());
+  return parseManifest(text);
+}
+
+// ---------------------------------------------------------------------------
+// Serve — resolve digest, stream the object from R2, fail closed on a miss
+// ---------------------------------------------------------------------------
+
+export interface ServeStaticBundleDeps {
+  bucket: StaticBundleR2BucketLike;
+  /**
+   * The digest to serve, already resolved by the caller (typically
+   * `resolveChannelVersion(get, tenantId, "live")` — see the module
+   * docstring's DIGEST CONTRACT). `null` means "pointer-serving is on for
+   * this tenant but nothing is live yet" — fails closed, same as a missing
+   * object, per the ADR: this path is only ever reached for a confirmed
+   * pointer-serving tenant, so an unresolved digest is itself a fault, not a
+   * "fall through to SSR" signal.
+   */
+  digest: string | null;
+  /** Best-effort diagnostic sink (never throws, never blocks the response). */
+  onFailClosed?: (detail: string) => void;
+}
+
+/** Structured detail for the one fail-closed shape this module can produce. */
+export class StaticBundleUnavailableError extends Error {
+  readonly code = "static-bundle-unavailable" as const;
+  constructor(detail: string) {
+    super(detail);
+    this.name = "StaticBundleUnavailableError";
+  }
+}
+
+function failClosed(deps: ServeStaticBundleDeps, detail: string): Response {
+  try {
+    deps.onFailClosed?.(detail);
+  } catch {
+    /* diagnostic sink must never break the response path */
+  }
+  // 503, not a 200 masquerading as content and not a 404 (which would read as
+  // "this route doesn't exist" — it does, the bundle is just unreachable) and
+  // never an SSR fallthrough: this route is ONLY reached for a tenant
+  // confirmed to be on the pointer-serving model, so an unreadable bundle is
+  // an infra fault to surface (verify/monitoring), not a content gap.
+  return new Response("Static bundle unavailable", {
+    status: 503,
+    headers: {
+      "cache-control": "no-store",
+      "x-tot-static-bundle": "fail-closed",
+    },
+  });
+}
+
+/** Cache-Control for a `route`-kind file (HTML/xml/txt — rendered fresh per version, stable non-digest url). */
+const ROUTE_CACHE_CONTROL = "public, max-age=0, s-maxage=300, stale-while-revalidate=86400";
+/** Cache-Control for an `asset`-kind file — the pool key IS the content hash, so caching forever is always correct (epic §A). */
+const ASSET_CACHE_CONTROL = "public, max-age=31536000, immutable";
+
+/**
+ * Serve `pathname` from the digest-addressed static bundle in R2.
+ *
+ * Returns `null` — the ONE "fall through to SSR" signal — when the manifest's
+ * `files` map proves `pathname` is not part of this bundle's static surface:
+ * app surfaces (/admin, /cockpit, checkout, …) share the tenant's host but are
+ * never materialized into a bundle, so the caller must render them. Only a
+ * manifest WITH `files` can prove non-membership; a pre-T6 manifest keeps the
+ * fetch-then-fail-closed path.
+ *
+ * Every OTHER outcome (hit, unsafe path, unresolved digest, missing manifest,
+ * missing object for a LISTED file) terminates the request here rather than
+ * falling through — a staged digest's listed route must never silently degrade
+ * into SSR (wrong/divergent bytes), per the ADR's fail-closed guidance.
+ *
+ * T6: the manifest is now read FIRST, on every request (not just HTML, as
+ * before T6) — it's the only source of truth for whether `rel` resolves to
+ * the per-version `versions/<digest>/<rel>` key or the shared content-addressed
+ * `assets/<sha256>` pool key (`resolveStaticBundleObjectKey`). A missing
+ * manifest fails closed the same way a missing object always has: the
+ * manifest is deliberately the LAST thing `stage-bundle.mjs` writes for a
+ * digest (see `s3-publish.mjs`'s `buildManifestPromoteStep`), so its absence
+ * means this digest was never fully staged — serving from it would be wrong
+ * before T6 too, this just makes the fail-closed check unconditional.
+ *
+ * On a hit, serves the R2 bytes VERBATIM with a Cache-Control keyed by the
+ * manifest's file `kind` (long-lived immutable for the shared `asset` pool —
+ * safe because the key itself is the content hash; short/revalidating for a
+ * `route` doc, rendered fresh per version at a STABLE, non-digest url) and,
+ * for an HTML response, the bundle's PINNED CSP header read back from the
+ * same manifest read — never the Worker's per-request nonce middleware, per
+ * the ADR's CSP-consequences note.
+ */
+export async function serveStaticBundle(
+  deps: ServeStaticBundleDeps,
+  pathname: string,
+): Promise<Response | null> {
+  const { bucket, digest } = deps;
+  if (!digest) {
+    return failClosed(deps, "pointer-serving tenant has no resolved live digest");
+  }
+
+  const rel = staticBundleRelPath(pathname);
+  if (!rel) {
+    return failClosed(deps, `unsafe/unparseable path: ${JSON.stringify(pathname)}`);
+  }
+
+  const manifest = await readStaticBundleManifest(bucket, digest);
+  if (!manifest) {
+    return failClosed(deps, `missing/unreadable manifest for digest ${digest}`);
+  }
+
+  const entry = manifest.files?.[rel];
+  if (manifest.files && !entry) {
+    // Provably not in this bundle's static surface — an app surface (/admin,
+    // /cockpit, …) or a route this version never materialized. SSR owns it.
+    return null;
+  }
+  const objectKey = resolveStaticBundleObjectKey(digest, rel, manifest.files);
+  const object = await bucket.get(objectKey);
+  if (!object) {
+    return failClosed(deps, `missing R2 object ${objectKey}`);
+  }
+
+  const isHtml = rel.endsWith(".html");
+  // T6 cache tier: use the manifest's `kind` classification when present.
+  // A pre-T6 manifest (no `files` at all) falls back to the ORIGINAL
+  // isHtml-based heuristic — every non-html path used to be treated as a
+  // long-cacheable asset, which this preserves exactly for an old bundle
+  // this Worker version might still encounter mid-rollout.
+  const cacheControl = entry
+    ? entry.kind === "asset"
+      ? ASSET_CACHE_CONTROL
+      : ROUTE_CACHE_CONTROL
+    : isHtml
+      ? ROUTE_CACHE_CONTROL
+      : ASSET_CACHE_CONTROL;
+  const headers: Record<string, string> = {
+    "content-type": assetContentType(rel),
+    // Cache-key-by-digest lives in the caller's edge-cache layer for `route`
+    // keys (versions/<digest>/<rel> is digest-scoped — a pointer flip is a
+    // clean cache miss on the NEW digest's keys, never a stale serve of the
+    // old one); `asset` keys are ADDITIONALLY digest-independent (content-
+    // addressed by hash), so they're safe to cache forever downstream too.
+    // This header governs downstream/browser caching of the STABLE URL:
+    "cache-control": cacheControl,
+    "x-tot-static-bundle": "hit",
+    "x-tot-static-bundle-digest": digest,
+  };
+
+  if (isHtml && manifest.csp) {
+    headers[manifest.csp.headerName] = manifest.csp.value;
+  }
+
+  if (typeof object.size === "number") {
+    headers["content-length"] = String(object.size);
+  }
+  const body: BodyInit = object.body ?? (await object.arrayBuffer());
+  return new Response(body, { status: 200, headers });
+}

package/packages/public-runtime/src/tenant.ts

@@ -392,6 +392,34 @@ export interface TenantConfig {
   features?: Partial<TenantFeatures>;
   /** Regulated-commerce affordances; undefined for unregulated tenants. */
   compliance?: ComplianceConfig;
+  /**
+   * Per-tenant newsletter compliance/sender config. Sourced when a digest is
+   * built and sent (the send pipeline is a later unit). Distinct from the
+   * {@link TenantFeatures} `newsletter` flag, which only gates the CAPTURE form:
+   * this object supplies the CAN-SPAM physical postal address rendered in every
+   * email footer, plus the sender identity. Absent for tenants that don't send a
+   * newsletter; a sender falls back to a platform default when a field is unset.
+   */
+  newsletter?: {
+    /**
+     * Physical postal mailing address rendered in every newsletter email footer
+     * (CAN-SPAM §5(a)(5) requirement). Plain text; multi-line allowed.
+     */
+    postalAddress: string;
+    /** Display name on the `From:` header; falls back to `displayName`. */
+    fromName?: string;
+    /** `Reply-To:` address for the newsletter; falls back to a platform default. */
+    replyTo?: string;
+    /**
+     * Verified sending address on the `From:` header, e.g.
+     * `the-build@mail.tokenoftrust.store`. MUST be an address on a domain that is
+     * SPF/DKIM/DMARC-verified with the ESP (Resend) — NOT the tenant's own store
+     * domain, which is not a verified sending domain and would fail alignment.
+     * Unset → the send path derives `<collection>@mail.tokenoftrust.store` (the
+     * shared verified domain). Override only to use a per-tenant verified sender.
+     */
+    fromAddress?: string;
+  };
   /**
    * Cart/checkout engine wiring (Track A). Present on commerce tenants
    * that have a checkout store; drives the loader + signed add-to-cart. The
@@ -426,14 +454,14 @@ export interface TenantConfig {
    */
   capabilities?: Partial<CapabilityConfig>;
   /**
-   * Static-publish target (T5, tokenoftrust-com-static-publish epic). This
-   * tenant's PUBLIC site is materialized to an external static host
-   * (S3/CloudFront) OFF the Worker and republished on go-live. A per-tenant
-   * PROPERTY, not a global dark flag: presence opts the tenant in (default ON);
-   * `enabled: false` opts back out without dropping the target coordinates. The
-   * dispatch credentials/coordinates live in env/secrets, NEVER here. `target` is
-   * an opaque, TARGET-NEUTRAL label (S3 now, R2 later) forwarded verbatim into the
-   * publish job so ONE reconcile publish-sink drives any target.
+   * Static-publish target. This tenant's PUBLIC site is served by the Worker+R2
+   * pointer/digest plane (ADR 0012): go-live and rollback are instant, in-request
+   * KV `live` pointer flips over an already-staged, content-addressed bundle in
+   * R2. A per-tenant PROPERTY, not a global dark flag: presence opts the tenant in
+   * (default ON); `enabled: false` opts back out without dropping the target
+   * coordinates. The dispatch credentials/coordinates live in env/secrets, NEVER
+   * here. `target` is an opaque, TARGET-NEUTRAL label forwarded verbatim into the
+   * background stage/publish job so ONE reconcile publish-sink drives any target.
    */
   staticPublish?: {
     /** Target-neutral label, e.g. "www-s3". Forwarded into the dispatch payload. */

package/scripts/build/copy-tenant-assets.mjs

@@ -16,12 +16,20 @@
  * Idempotent: it wipes+rewrites the destination on every run. `TENANT_ASSETS_DEST`
  * overrides the destination (used by tests / spikes).
  *
- * VERSIONED TENANTS (decision `assets-r2-versioned`): a tenant whose assets are
+ * VERSIONED TENANTS: a tenant whose assets are
  * served version-scoped from R2 (src/pages/tenants/[id]/[...path].ts) must NOT be
  * baked here — otherwise the static file would shadow the R2 route. Opt a tenant
  * out by adding a `tenants/<id>/.tot/assets-versioned` marker file, or by listing
  * its id in the `TENANT_ASSETS_VERSIONED` env (comma-separated). Non-versioned
- * tenants keep the baked path unchanged (back-compat).
+ * tenants are baked here.
+ *
+ * TENANT_ASSETS_BAKE_VERSIONED=1 overrides ALL of the above and bakes every
+ * tenant's public/ regardless of versioned-ness. Set by the STATIC-plane bundle
+ * build (scripts/publish/materialize-tenant.mjs): the S3/CloudFront static site
+ * has no R2 asset route — a bundle is self-contained by definition — so
+ * skipping a versioned tenant's assets there just produces a bundle whose pages
+ * reference files that don't exist. The Worker-plane build never sets this, so
+ * R2 shadowing semantics are unchanged there.
  */
 import { cp, mkdir, readdir, rm } from "node:fs/promises";
 import { existsSync } from "node:fs";
@@ -44,9 +52,11 @@ const versionedEnv = new Set(
     .map((s) => s.trim())
     .filter(Boolean),
 );
+const bakeVersioned = process.env.TENANT_ASSETS_BAKE_VERSIONED === "1";
 const isVersioned = (id) =>
-  versionedEnv.has(id) ||
-  existsSync(join(src, id, ".tot", "assets-versioned"));
+  !bakeVersioned &&
+  (versionedEnv.has(id) ||
+    existsSync(join(src, id, ".tot", "assets-versioned")));
 
 let copied = 0;
 let skipped = 0;

package/scripts/dev/ai-edit.mjs

@@ -15,7 +15,7 @@
  * `tot` CLI, so `~/.tot/credentials.json` is directly readable. No token
  * plumbing needed between the CLI and the dev server.
  *
- * Scope (decision `d2-resolved-inline-ai-scope`): content + theme.json ONLY.
+ * Scope: content + theme.json ONLY.
  * The MCP tool enforces this server-side; nothing here widens it.
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from "node:fs";

package/scripts/dev/checkout-watch.mjs

@@ -35,8 +35,8 @@ export function resync(sourceRoot, targetRoot, rel) {
  * RELIABILITY-FIRST: defaults to an mtime POLL, not native `fs.watch`. Native watch
  * is event-driven but LOSSY on macOS — editors that save via write-temp-then-rename
  * (VS Code, vim, JetBrains, …) routinely deliver NO change event on the original
- * path, so the save silently fails to hot-reload (the 2026-07-14 "didn't reload"
- * report). The poll stat()s the tree on a short interval and never misses an edit.
+ * path, so the save silently fails to hot-reload. The poll stat()s the tree on a
+ * short interval and never misses an edit.
  *
  * Opt into event-driven native watch with TOT_DEV_NATIVE_WATCH=1 (it still falls
  * back to polling where recursive watch is unavailable, e.g. Linux). Dependency-free

package/scripts/dev/file-browser.mjs

@@ -5,13 +5,11 @@
  *
  * Follows the scripts/dev delegation pattern (see ai-edit.mjs): all logic lives
  * here, dependency-free and testable under `node --test`; a thin dev-only Vite
- * plugin (dev-plugins/dev-file-browser.mjs — added when C0/C1 integrate) maps
+ * plugin (dev-plugins/dev-file-browser.mjs) maps
  * req/res onto `handleTree` / `handleFile`. Every path is routed through
  * safe-path.mjs; the source root comes from tenant-source-root.mjs (never SSR).
  *
- * Git-status badges (C3 acceptance) layer on when C4's git-status.mjs lands —
- * the tree here carries structure only, so this module owns no git surface and
- * doesn't collide with C4.
+ * The tree here carries structure only, so this module owns no git surface.
  */
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { join, extname, sep } from "node:path";

package/scripts/dev/file-writer.mjs

@@ -123,7 +123,7 @@ export function handleWrite(env = process.env, body = {}) {
     return { status: 400, json: { ok: false, status: "no_path", message: "path is required" } };
   }
 
-  const result = writeSourceFile(root.sourceRoot, relPath, body.content, {
+  const result = writeSourceFile(root.sourceRoot, relPath, /** @type {string} */ (body.content), {
     baseVersion: body ? body.baseVersion : undefined,
   });
   const status = result.ok

package/scripts/dev/git-status.mjs

@@ -118,10 +118,10 @@ export function computeDiff(gitCwd, sourceRoot, relPath) {
   } catch {
     workingExists = false;
   }
-  if (workingExists && st.isDirectory()) {
+  if (st && st.isDirectory()) {
     return { ok: false, status: "is_dir", message: `${relPath} is a directory` };
   }
-  if (workingExists) {
+  if (workingExists && st) {
     if (BINARY_EXT.has(extname(posix).toLowerCase())) {
       return { ok: true, path: posix, status: fileStatus(gitCwd, relPath), shown: false, reason: "binary" };
     }

package/scripts/dev/locate-handler.mjs

@@ -3,12 +3,12 @@
  *   POST /__tot/locate          {domPath, path} → {ok, path, line, col} | {status}
  *   POST /__tot/open-in-editor   {path, line, col} → {ok} | {status}
  *
- * Keeps locate.mjs a PURE parse5 walk (already integrated + tested 5/5); this module
+ * Keeps locate.mjs a PURE parse5 walk; this module
  * adds the env/path-resolution/refusal concerns and is itself unit-testable under
  * `node --test` with no running dev server (the scripts/dev delegation pattern — see
  * file-browser.mjs). The thin dev-plugins/dev-locate.mjs wrapper maps req/res onto it.
  *
- * HONORS decision `click-to-source-anchors-at-content-region`: the served page wraps
+ * The served page wraps
  * the raw content region (<main>, the whole of content/home.html) in the storefront's
  * own chrome (skip-link, header, nav, footer) that is NOT in the tenant source. So we
  * resolve the clicked URL to its raw content source and walk THAT from <body>:
@@ -90,7 +90,7 @@ export function handleLocate(env = process.env, body = {}) {
 
   const html = readFileSync(abs, "utf8");
   const found = locate(html, body.domPath);
-  if (typeof found.line === "number") {
+  if ("line" in found && typeof found.line === "number") {
     return { status: 200, json: { ok: true, path: rel, line: found.line, col: found.col } };
   }
   // The walk missed: the element is outside the raw content region — i.e. the storefront

package/scripts/dev/port-check.mjs

@@ -8,9 +8,9 @@ import net from "node:net";
  * predicts astro's own bind on either IP family.
  *
  * WHY THIS EXISTS: Vite's `strictPort` defaults OFF, so when the requested port is
- * taken astro SILENTLY moves to the next free port. On 2026-07-14 that stranded the
- * CLI's liveness poll on the ORIGINAL port (answered by a stale foreign server) →
- * a false "✨ You're live" pointing at the wrong server. Pre-flighting the port and
+ * taken astro SILENTLY moves to the next free port — stranding the CLI's liveness
+ * poll on the ORIGINAL port (answered by a stale foreign server) → a false
+ * "✨ You're live" pointing at the wrong server. Pre-flighting the port and
  * failing clearly removes that whole class of silent failure.
  *
  * Dependency-free (node:net only) so it copies into the standalone runner and is

package/scripts/dev/publish.mjs

@@ -20,15 +20,11 @@
  * Auth: the developer's own cached OAuth session (`tot login`,
  * `~/.tot/credentials.json`), via `packages/cli/src/auth.mjs`'s
  * `resolveDeveloperSession` — reads, silently refreshes, and attaches the
- * Bearer exactly as `tot submit` does. NOT the storefront-operator
- * TOT_API_KEY/TOT_SECRET_KEY path this module used before 2026-07-26:
- * tot-mcp went OAuth-first on 2026-07-23 ("Require OAuth before remote MCP
- * initialize"), which retired the old no-browser operator/credential_validate
- * trust path entirely — every caller, including this one, now needs a real
- * OAuth bearer just to complete `initialize`. There is no service-account /
- * client-credentials grant on this MCP (confirmed against its OAuth
- * authorization-server metadata), so a human `tot login` (one-time; refresh
- * is silent afterward, ~30-day refresh tokens) is the only way in.
+ * Bearer exactly as `tot submit` does. Every caller needs a real OAuth bearer
+ * just to complete `initialize`; there is no service-account / client-credentials
+ * grant on this MCP (confirmed against its OAuth authorization-server metadata),
+ * so a human `tot login` (one-time; refresh is silent afterward, ~30-day refresh
+ * tokens) is the only way in.
  */
 import { createHash } from "node:crypto";
 import { readFile } from "./file-browser.mjs";

package/scripts/dev/shot.mjs

@@ -20,7 +20,7 @@ const CHROME_PATHS = [
   "/usr/bin/chromium-browser",
   "/usr/bin/chromium",
 ].filter(Boolean);
-const executablePath = CHROME_PATHS.find((p) => existsSync(p));
+const executablePath = CHROME_PATHS.find((p) => !!p && existsSync(p));
 
 const args = process.argv.slice(2);
 const url = args[0];

package/scripts/dev/unified-diff.mjs

@@ -1,8 +1,8 @@
 /**
  * Minimal unified-diff applier for the inline-AI edit loop (WS5 G1).
  *
- * The MCP `content_edit` tool returns a per-file unified diff (`--- a/<path>` /
- * `+++ b/<path>` header, `@@ -l,c +l,c @@` hunks) rather than a full-file
+ * The MCP `content_edit` tool returns a per-file unified diff (a `---`/`+++`
+ * file header, then hunk headers of the form "-l,c +l,c") rather than a full-file
  * rewrite — this is what turns that diff back into the file's new content, so
  * `tot dev` can apply it, hot-reload, and undo it cleanly. Dependency-free
  * (matches the rest of the tenant tooling — see packages/cli/src/mcp.mjs).
@@ -12,10 +12,15 @@
  * that's exactly the shape content_edit's system prompt asks the model for.
  */
 
-/** One `@@ -l,c +l,c @@` hunk: the old/new starting line + its body lines. */
+/**
+ * One hunk (its "-l,c +l,c" header): the old/new starting line + its body lines.
+ * @typedef {{ oldStart: number, body: string[] }} Hunk
+ */
 function parseHunks(diff) {
   const lines = diff.split(/\r?\n/);
+  /** @type {Hunk[]} */
   const hunks = [];
+  /** @type {Hunk | null} */
   let current = null;
   const hunkHeader = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;