@tokenoftrust/storefront-runner 1.3.4-rc.3 → 1.4.0

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

@@ -7,6 +7,7 @@
  */
 import type { ManagedCheckoutConfig } from "./checkout.js";
 import type { CapabilityConfig } from "./capabilities.js";
+import type { AutopilotConfig, MembershipProgramConfig } from "./membership.js";
 
 /**
  * The shared semantic COLOR contract — the widget library's public API.
@@ -63,6 +64,22 @@ export interface ThemeColorTokens {
   "primary-hover"?: string;
   /** Hover/active shade of `accent`. Default: a derived darken of `accent`. */
   "accent-hover"?: string;
+
+  // --- Interaction/quality-bar extensions (unit F6). Same "always resolvable"
+  //     contract: each carries a derived @theme-bridge default so a component may
+  //     read it unconditionally; a theme sets one only to brand-tune it. ---
+  /** Keyboard focus-ring color (`:focus-visible` outline). Default: `accent`. */
+  "focus-ring"?: string;
+  /** Fill for a disabled/loading control (buttons, inputs). Default: a muted
+   *  greige mix of `muted`+`surface`. */
+  disabled?: string;
+  /** Readable text/icon color ON a `disabled` control. Default: `muted`. */
+  "disabled-contrast"?: string;
+  /** Form-field border — a stronger, ≥3:1 outline for inputs/selects than the
+   *  hairline `border`. Default: a mix of `border`+`text`. */
+  "field-border"?: string;
+  /** Review/rating star fill (trust/UGC surfaces). Default: `accent`. */
+  star?: string;
 }
 
 export interface ThemeFontFamily {
@@ -92,6 +109,13 @@ export interface ThemeShapeTokens {
   radius: { sm: string; md: string; lg: string; full: string };
   borderWeights: { thin: string; medium: string; thick: string };
   shadow: { sm: string; md: string; lg: string };
+  /**
+   * Minimum interactive tap-target size (WCAG 2.2 AA §2.5.8 · 24px floor, 44px
+   * recommended for mobile commerce). Serialized to `--tap-target`; components
+   * size touch controls with `min-height/min-width: var(--tap-target)`. Optional
+   * — the `:root` base default (44px) applies when a theme omits it. (Unit F6.)
+   */
+  tapTarget?: string;
 }
 
 export interface ThemeBrandTokens {
@@ -247,6 +271,29 @@ export interface ComplianceConfig {
  */
 export type SiteType = "commerce" | "marketing";
 
+/**
+ * The storefront paywall mode (decision `golive-paywall-storefront-mode-enabled`).
+ * `"enabled"` is the ONLY value that permits go-live; `"disabled"` (or an absent
+ * `storefront.mode`) fails the paywall closed. Kept OPEN as a string union with an
+ * `enabled` member so a future billing state (e.g. "trial", "past_due") can be added
+ * without changing the gate — {@link StorefrontModeAllowed} stays the single source
+ * of the allow test.
+ */
+export type StorefrontMode = "enabled" | "disabled";
+
+/** The one storefront mode value that permits go-live. The gate tests strict equality. */
+export const STOREFRONT_MODE_ENABLED = "enabled" as const;
+
+/**
+ * PURE paywall predicate: does this storefront mode permit go-live? True iff the
+ * mode is exactly `"enabled"` (decision `golive-paywall-storefront-mode-enabled`).
+ * Generic — takes the mode value, NEVER a domain — so there is no per-store
+ * special-case. Undefined/unknown → false (fail-closed).
+ */
+export function storefrontModeAllowsGoLive(mode: string | undefined | null): boolean {
+  return mode === STOREFRONT_MODE_ENABLED;
+}
+
 /**
  * Per-tenant capability switches. These gate whole surfaces so the same
  * component library renders both a store and a marketing site without any
@@ -355,6 +402,20 @@ export interface TenantConfig {
    */
   commerce?: {
     checkout?: ManagedCheckoutConfig;
+    /**
+     * Autopilot (subscription) program visibility (F10). Absent → subscription
+     * purchase options render wherever a product authors them (framework/dev
+     * default). `enabled: false` HIDES Autopilot at launch — the first-class
+     * hide-at-launch state for a tenant that isn't selling recurring orders yet.
+     */
+    autopilot?: AutopilotConfig;
+    /**
+     * Membership pricing program (F10): member-vs-list pricing + how a member
+     * discount stacks with a subscription discount. Absent/`enabled:false` → no
+     * member pricing renders (the launch default; shopper membership accounts are
+     * a Phase-2 managed-checkout capability).
+     */
+    membership?: MembershipProgramConfig;
   };
   /**
    * PR-gated capability switches (cart/checkout, age/identity verification,
@@ -364,6 +425,181 @@ export interface TenantConfig {
    * Undefined entries default from siteType/compliance — see resolveCapabilities.
    */
   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.
+   */
+  staticPublish?: {
+    /** Target-neutral label, e.g. "www-s3". Forwarded into the dispatch payload. */
+    target: string;
+    /** Opt back out without removing the target. Default true when present. */
+    enabled?: boolean;
+  };
+  /**
+   * Storefront product/subscription state — the paywall the platform gates GO-LIVE
+   * on (decision `golive-paywall-storefront-mode-enabled`). This is the storefront's
+   * analog of the ToT platform SDK's `apiClient.options.storefront.mode`: a per-store
+   * PROPERTY set from the merchant's account/subscription, NEVER a per-domain
+   * special-case in code. Go-live (the public LIVE publish, `POST /api/changes/accept`)
+   * is permitted ONLY when `mode === "enabled"`; any other value — including undefined
+   * (never provisioned) — refuses go-live (fail-closed paywall). Preview/dev never
+   * consult it. See `storefrontModeGate` (`lib/change/route.ts`).
+   */
+  storefront?: {
+    /**
+     * The storefront paywall mode. `"enabled"` = the store has an active storefront
+     * subscription and MAY go live. `"disabled"` (or absent) = not entitled to
+     * go-live yet.
+     */
+    mode?: StorefrontMode;
+  };
+  /**
+   * Internal test/e2e tenant — never a real client. A tenant carrying this
+   * marker (or an `.e2e.test` appDomain) is excluded from real/prospect-facing
+   * listings, HARD-blocked from go-live/promote, and excluded from
+   * billing/analytics. It exists only to host a destructive full-cycle e2e
+   * (candidate create/ship/rollback) against a CLONE of a real tenant.
+   */
+  classification?: "internal-test";
+}
+
+/**
+ * True when a tenant is an internal test/e2e tenant — either explicitly marked
+ * `classification: "internal-test"` or resolving to an `.e2e.test` appDomain
+ * (fail-safe belt-and-suspenders so a clone missing the marker is still caught).
+ * Callers use this to keep such tenants out of real listings and off the
+ * go-live/promote path.
+ */
+export function isInternalTestTenant(
+  t: Pick<TenantConfig, "classification" | "appDomain">,
+): boolean {
+  return t.classification === "internal-test" || t.appDomain.endsWith(".e2e.test");
+}
+
+// ---------------------------------------------------------------------------
+// Non-premium (self-serve) tenant identity — D4.
+//
+// A NEW self-serve / non-premium shop is minted with its identity anchored to a
+// per-tenant subdomain on our own Cloudflare zone: `<label>.tokenoftrust.store`.
+// That value is the tenant_id AND the appDomain AND the canonicalDomain AND the
+// tot_data_scope (the dir==tenant_id==appDomain==scope invariant the
+// `unify-tenant-id-equals-appdomain` decision established) — a REAL dotted
+// appDomain, NOT a reintroduced bare slug (bare slugs were deliberately retired).
+// A custom `.com` is layered on LATER as an optional premium alias/upgrade
+// (`rebindPremiumDomain`), never a precondition for a preview.
+//
+// See docs/epics/proposed/invite-gated-auto-build.md §D4.
+// ---------------------------------------------------------------------------
+
+/**
+ * The Cloudflare zone that hosts every non-premium (self-serve) store as a
+ * per-tenant subdomain. The `*.tokenoftrust.store` wildcard route already exists
+ * in apps/storefront/wrangler.toml, so routing a freshly minted store is free.
+ */
+export const HOSTED_STORE_ZONE = "tokenoftrust.store";
+
+/**
+ * A single DNS label — the `<label>` in `<label>.tokenoftrust.store`: lowercase
+ * alphanumerics with internal hyphens, 1–63 chars, no leading/trailing hyphen and
+ * NO dots (a dot would create a deeper subdomain the wildcard route can't reach).
+ */
+const HOSTED_STORE_LABEL_RE = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+
+/**
+ * The identity subset of a {@link TenantConfig} — the fields that establish WHO a
+ * tenant is (as opposed to how it looks or what it sells). {@link mintHostedStoreIdentity}
+ * produces exactly this; the rest of a config (theme, storyblok, compliance, …) is
+ * layered on by the app-level minter / build workstream.
+ */
+export type TenantIdentity = Pick<
+  TenantConfig,
+  "tenant_id" | "appDomain" | "canonicalDomain" | "tot_data_scope" | "domains"
+>;
+
+/**
+ * The hosted-store hostname for a label: `<label>.tokenoftrust.store`.
+ * @throws if `label` is not a valid single DNS label (see {@link HOSTED_STORE_LABEL_RE}).
+ */
+export function hostedStoreDomain(label: string): string {
+  const clean = String(label ?? "").toLowerCase().trim();
+  if (!HOSTED_STORE_LABEL_RE.test(clean)) {
+    throw new Error(
+      `hostedStoreDomain: invalid store label "${label}" — want a single DNS label ` +
+        `(lowercase alnum + internal hyphens, 1–63 chars, no dots), e.g. "acme-vapor".`,
+    );
+  }
+  return `${clean}.${HOSTED_STORE_ZONE}`;
+}
+
+/** True when `domain` is a `<label>.tokenoftrust.store` hosted-store hostname. */
+export function isHostedStoreDomain(domain: string): boolean {
+  const clean = String(domain ?? "").toLowerCase().split(":")[0]?.trim() ?? "";
+  const suffix = `.${HOSTED_STORE_ZONE}`;
+  if (!clean.endsWith(suffix)) return false;
+  return HOSTED_STORE_LABEL_RE.test(clean.slice(0, -suffix.length));
+}
+
+/**
+ * Mint the identity for a NEW self-serve / non-premium tenant (D4).
+ *
+ * tenant_id == appDomain == canonicalDomain == tot_data_scope ==
+ * `<label>.tokenoftrust.store`, with that single hostname as the sole `domains`
+ * entry. A premium custom domain is added later via {@link rebindPremiumDomain}.
+ *
+ * @throws if `label` is not a valid single DNS label.
+ */
+export function mintHostedStoreIdentity(label: string): TenantIdentity {
+  const appDomain = hostedStoreDomain(label); // validates the label
+  return {
+    tenant_id: appDomain,
+    appDomain,
+    canonicalDomain: appDomain,
+    tot_data_scope: appDomain,
+    domains: [appDomain],
+  };
+}
+
+/**
+ * Layer an optional PREMIUM custom domain onto an existing hosted-store tenant —
+ * the upgrade path in D4. Returns a NEW config (the input is not mutated).
+ *
+ * The tenant's IDENTITY stays anchored to its `.tokenoftrust.store` value:
+ * `tenant_id` AND `appDomain` are STABLE. This is the recorded recommendation for
+ * D4's open question — keep the id stable and treat the custom domain purely as an
+ * alias — which avoids repo-rename + registry-re-key churn. What changes:
+ *   - the custom domain (and its `www.` host) is ADDED to `domains` (idempotent);
+ *   - `canonicalDomain` FLIPS to the custom domain (SEO canonical → premium domain).
+ *
+ * NOTE (open human gate — invite-gated-auto-build.md §D4): whether a rebind should
+ * instead CHURN tenant_id/appDomain to the custom domain is an unresolved product
+ * decision that would need repo-rename + registry-re-key infrastructure which does
+ * not exist yet. This helper deliberately implements ONLY the churn-free alias form.
+ *
+ * @throws if `customDomain` is not a plausible dotted hostname.
+ */
+export function rebindPremiumDomain(
+  config: TenantConfig,
+  customDomain: string,
+): TenantConfig {
+  const clean = String(customDomain ?? "").toLowerCase().trim();
+  if (!clean || clean.includes("/") || clean.includes(" ") || !clean.includes(".")) {
+    throw new Error(
+      `rebindPremiumDomain: invalid custom domain "${customDomain}" — want a dotted hostname, e.g. "acme.com".`,
+    );
+  }
+  const domains = [...config.domains];
+  const add = (host: string): void => {
+    if (!domains.some((d) => d.toLowerCase() === host)) domains.push(host);
+  };
+  add(clean);
+  if (!clean.startsWith("www.")) add(`www.${clean}`);
+  return { ...config, domains, canonicalDomain: clean };
 }
 
 export type DeepPartial<T> = {

package/packages/public-runtime/src/widget-postmessage.ts

@@ -0,0 +1,205 @@
+/**
+ * Parent-side postMessage bridge for sandboxed widget iframes — PrivateApps
+ * epic, D5 (Chunk E). The widget sandbox (`allow-scripts`, no
+ * `allow-same-origin` — `customization-scripts.ts`'s `widgetFrameAttrs()`)
+ * blocks DOM/cookie/storage access outright; this is the ONLY channel a
+ * widget has back to the page, so it gets the same fail-closed discipline as
+ * the sandbox itself: a message is honored only when BOTH `event.source` is
+ * a TRACKED iframe's `contentWindow` AND `event.origin` is the OPAQUE sandbox
+ * origin `"null"` (see {@link OPAQUE_SANDBOX_ORIGIN} — a frame sandboxed
+ * without `allow-same-origin` has no origin of its own, so every browser
+ * reports its postMessage origin as the literal string `"null"`, never its
+ * real HTTP(S) endpoint; verified against a real sandboxed cross-origin
+ * iframe, not assumed — jsdom can't observe this, only a real browser can).
+ * Anything else — an untracked window, a non-opaque origin, an
+ * unrecognized/malformed `type` — is a silent no-op: no reply, no state
+ * change, so a probing widget can't learn whether its message was rejected
+ * for being unknown-type vs a weakened sandbox (no oracle).
+ *
+ * Dependency-free + Workers/browser-portable: nothing here touches
+ * `window`/`document` at module scope, only inside `mountWidgetPostMessageBridge`
+ * — so importing this module (via `@tot/public-runtime`'s barrel, which also
+ * loads server-side into the SSR bundle) is safe outside a browser; only
+ * calling the mount function needs one.
+ */
+
+/** Own-height clamp — a widget can't grow the iframe past a sane bound, never the width. */
+const MIN_HEIGHT_PX = 20;
+const MAX_HEIGHT_PX = 2000;
+
+/**
+ * The `event.origin` a browser reports for a message from an opaque-origin
+ * frame — i.e. every widget iframe, since all of them are rendered with
+ * `WIDGET_SANDBOX` (`allow-scripts`, no `allow-same-origin`). This is what
+ * the origin check below actually compares against — NOT the widget's real
+ * endpoint origin (`data-tot-widget-origin`, kept for install identification
+ * / diagnostics only). If the sandbox were ever weakened to add
+ * `allow-same-origin`, the frame would start reporting its real origin
+ * instead of `"null"`, and this check would then reject every message,
+ * turning a silent security downgrade into a loud, visible break.
+ */
+const OPAQUE_SANDBOX_ORIGIN = "null";
+
+/** Same-tenant relative path only: a leading `/`, never `//` (protocol-relative), never a scheme. */
+const RELATIVE_PATH = /^\/(?!\/)[a-zA-Z0-9\-._~!$&'()*+,;=:@%/?#]*$/;
+
+/** The closed set of message types a widget may send. Everything else is a no-op. */
+export type WidgetMessageType = "resize" | "navigate" | "analytics";
+
+export interface WidgetAnalyticsEvent {
+  installId: string;
+  name: string;
+  props: Record<string, string | number | boolean>;
+}
+
+/** Minimal DOM surface this module needs — a real `HTMLIFrameElement` satisfies it structurally. */
+export interface WidgetFrameHost {
+  contentWindow: unknown;
+  style: { height: string };
+  getAttribute(name: string): string | null;
+}
+export interface WidgetFrameRoot {
+  querySelectorAll(selector: string): Iterable<WidgetFrameHost>;
+}
+
+/** Minimal message-event surface — real `MessageEvent` satisfies it structurally. */
+export interface WidgetMessageEvent {
+  source: unknown;
+  origin: string;
+  data: unknown;
+}
+/** Minimal event-target surface — real `Window` satisfies it structurally. */
+export interface WidgetMessageTarget {
+  addEventListener(type: "message", listener: (event: WidgetMessageEvent) => void): void;
+  removeEventListener(type: "message", listener: (event: WidgetMessageEvent) => void): void;
+}
+
+export interface WidgetPostMessageBridgeOptions {
+  /** Sink for validated `analytics` messages. Defaults to a no-op (Phase 1 has no wired sink yet). */
+  onAnalytics?: (event: WidgetAnalyticsEvent) => void;
+  /** Sink for validated `navigate` messages. Defaults to `window.location.assign` (same-tab). */
+  onNavigate?: (path: string) => void;
+  /** Element scanned for tracked iframes. Defaults to `document`. */
+  root?: WidgetFrameRoot;
+  /** Event target the bridge listens on. Defaults to `window`. */
+  target?: WidgetMessageTarget;
+}
+
+interface TrackedFrame {
+  expectedOrigin: string;
+  installId: string;
+  el: WidgetFrameHost;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null;
+}
+
+/**
+ * Scan `root` for `iframe[data-tot-widget-origin]` — `AppWidgetFrame`'s
+ * render output — and index each by its `contentWindow`. Re-scanned on every
+ * message rather than cached once, so a widget that mounts after the initial
+ * page load (e.g. a `loading="lazy"` frame near the viewport) is still found.
+ */
+function collectTrackedFrames(root: WidgetFrameRoot): Map<unknown, TrackedFrame> {
+  const frames = new Map<unknown, TrackedFrame>();
+  for (const el of root.querySelectorAll("iframe[data-tot-widget-origin]")) {
+    const expectedOrigin = el.getAttribute("data-tot-widget-origin");
+    const installId = el.getAttribute("data-tot-install-id");
+    if (!expectedOrigin || !installId || !el.contentWindow) continue;
+    frames.set(el.contentWindow, { expectedOrigin, installId, el });
+  }
+  return frames;
+}
+
+function warn(message: string, detail: Record<string, unknown>): void {
+  console.warn(`[diag:widget-postmessage] ${message}`, detail);
+}
+
+/**
+ * Mount the parent-side bridge for the lifetime of the page. Returns an
+ * unmount function (removes the listener) — mainly for tests; the browser
+ * bootstrap script mounts once and never unmounts.
+ */
+export function mountWidgetPostMessageBridge(
+  options: WidgetPostMessageBridgeOptions = {},
+): () => void {
+  const root = options.root ?? (document as unknown as WidgetFrameRoot);
+  const target = options.target ?? (window as unknown as WidgetMessageTarget);
+  const onAnalytics = options.onAnalytics ?? (() => {});
+  const onNavigate = options.onNavigate ?? ((path: string) => window.location.assign(path));
+
+  function handleMessage(event: WidgetMessageEvent): void {
+    try {
+      const frame = collectTrackedFrames(root).get(event.source);
+      if (!frame) {
+        warn("rejected — source is not a tracked widget iframe", { origin: event.origin });
+        return;
+      }
+      if (event.origin !== OPAQUE_SANDBOX_ORIGIN) {
+        warn("rejected — origin is not the opaque sandbox origin (sandbox may have been weakened)", {
+          installId: frame.installId,
+          expected: OPAQUE_SANDBOX_ORIGIN,
+          got: event.origin,
+        });
+        return;
+      }
+
+      const data = event.data;
+      if (!isRecord(data) || typeof data.type !== "string") {
+        warn("rejected — malformed message", { installId: frame.installId });
+        return;
+      }
+
+      switch (data.type as WidgetMessageType | string) {
+        case "resize": {
+          if (typeof data.height !== "number" || !Number.isFinite(data.height)) {
+            warn("rejected — non-numeric resize height", { installId: frame.installId });
+            return;
+          }
+          const clamped = Math.min(MAX_HEIGHT_PX, Math.max(MIN_HEIGHT_PX, data.height));
+          // Own height only — width is never touched from a widget message.
+          frame.el.style.height = `${clamped}px`;
+          return;
+        }
+        case "navigate": {
+          if (typeof data.path !== "string" || !RELATIVE_PATH.test(data.path)) {
+            warn("rejected — navigate target is not a same-tenant relative path", {
+              installId: frame.installId,
+            });
+            return;
+          }
+          onNavigate(data.path);
+          return;
+        }
+        case "analytics": {
+          if (typeof data.name !== "string") {
+            warn("rejected — analytics event missing a name", { installId: frame.installId });
+            return;
+          }
+          const rawProps = isRecord(data.props) ? data.props : {};
+          const props: Record<string, string | number | boolean> = {};
+          for (const [key, value] of Object.entries(rawProps)) {
+            if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+              props[key] = value;
+            }
+          }
+          onAnalytics({ installId: frame.installId, name: data.name, props });
+          return;
+        }
+        default:
+          warn("rejected — unknown message type", { installId: frame.installId, type: data.type });
+      }
+    } catch {
+      // A hostile `event.data` (e.g. a throwing getter on `type` or a
+      // property read inside the analytics props loop) must never escape as
+      // an uncaught exception out of the message listener — treat it exactly
+      // like any other malformed message: a silent no-op, no reply, no state
+      // change, no oracle for what specifically was invalid.
+      warn("rejected — reading the message threw", { origin: event.origin });
+    }
+  }
+
+  target.addEventListener("message", handleMessage);
+  return () => target.removeEventListener("message", handleMessage);
+}

package/scripts/dev/publish.mjs

@@ -0,0 +1,158 @@
+/**
+ * publish.mjs — server-side logic for C5's "Publish" action: open/update a
+ * PR-backed candidate (g1b `candidate_open`) for the developer's current
+ * on-disk draft of one writable file (`POST /__tot/publish {path}`).
+ *
+ * Follows the file-writer.mjs / file-browser.mjs delegation pattern: all
+ * logic lives here, dependency-free (global fetch + node builtins) and
+ * testable under `node --test`; `dev-plugins/dev-publish.mjs` maps req/res
+ * onto `handlePublish`. Local mode has no draft-overlay concept — C5's writer
+ * already writes straight to the developer's real checkout (file-writer.mjs),
+ * so the "draft" IS whatever's currently on disk: this reads it fresh
+ * (file-browser.mjs's `readFile`) rather than tracking a separate store.
+ *
+ * `deriveChangeId` mirrors `tot submit`'s own scheme
+ * (packages/cli/src/commands/submit.mjs) so repeat publishes from this local
+ * editor update ONE PR instead of opening a new one each time — keyed on the
+ * signed-in DEVELOPER's identity (their email), same as the CLI's own
+ * `actorKeyFor`.
+ *
+ * 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.
+ */
+import { createHash } from "node:crypto";
+import { readFile } from "./file-browser.mjs";
+import { matchesWriteAllowlist } from "./safe-path.mjs";
+import { resolveTenantSourceRoot } from "./tenant-source-root.mjs";
+import { createMcpClient } from "../../packages/cli/src/mcp.mjs";
+import { resolveDeveloperSession, AuthUnavailableError } from "../../packages/cli/src/auth.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+
+/**
+ * A stable per-developer-per-tenant candidate handle, matching `tot submit`'s
+ * own scheme (`deriveChangeId` in packages/cli/src/commands/submit.mjs) so
+ * repeat local publishes update the SAME PR (`candidate_open` is idempotent
+ * on `changeId`) instead of piling up duplicates. Pure — unit-tested.
+ * @param {string} tenant
+ * @param {string} actorKey
+ * @returns {string}
+ */
+export function deriveChangeId(tenant, actorKey) {
+  const hash = createHash("sha256").update(`${tenant}|${actorKey}`).digest("hex").slice(0, 16);
+  return `local-${hash}`;
+}
+
+/**
+ * Open/update the PR-backed candidate via MCP `candidate_open` for one file's
+ * current on-disk content. `deps.mcpClient`/`deps.resolveSession` are
+ * injectable for tests (else a real client + `resolveDeveloperSession` are
+ * used, against `env.MCP_BASE_URL`).
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string} sourceRoot
+ * @param {string} tenantId
+ * @param {string} relPath
+ * @param {{mcpClient?: ReturnType<typeof createMcpClient>, resolveSession?: typeof resolveDeveloperSession}} [deps]
+ * @returns {Promise<{status:number, json:object}>}
+ */
+export async function publishFile(env, sourceRoot, tenantId, relPath, deps = {}) {
+  if (!matchesWriteAllowlist(relPath)) {
+    return {
+      status: 403,
+      json: { ok: false, status: "not_writable", message: `not in the write allowlist: ${relPath}` },
+    };
+  }
+
+  const file = readFile(sourceRoot, relPath);
+  if (!file.ok) {
+    return { status: file.status === "not_found" ? 404 : 400, json: file };
+  }
+  if (file.binary || file.content == null) {
+    return {
+      status: 400,
+      json: { ok: false, status: "not_publishable", message: `${relPath} has no text content to publish` },
+    };
+  }
+
+  const client = deps.mcpClient || createMcpClient(env.MCP_BASE_URL || DEFAULT_MCP_URL);
+
+  let session;
+  try {
+    // Developer handshake order (auth.mjs establishSession): attach the Bearer
+    // via setToken() BEFORE initialize() — the server binds the session to
+    // this identity at initialize time; init-then-attach leaves it anonymous.
+    session = await (deps.resolveSession || resolveDeveloperSession)(client, env);
+    await client.initialize();
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      return {
+        status: 503,
+        json: { ok: false, status: "not_signed_in", message: `${e.message}${e.hint ? ` — ${e.hint}` : ""}` },
+      };
+    }
+    return { status: 502, json: { ok: false, status: "error", message: String(e?.message || e) } };
+  }
+
+  const repo = `${tenantId}-main`;
+  const changeId = deriveChangeId(tenantId, session.email || session.token);
+
+  try {
+    const result = await client.callTool("candidate_open", {
+      repo,
+      changeId,
+      // Bounded to candidate_open's own schema limits (title<=200, body<=4000),
+      // same guard the hosted publish route applies.
+      title: `Cockpit draft: ${relPath}`.slice(0, 200),
+      body: `Submitted from the local \`tot dev\` cockpit for \`${relPath}\`.`.slice(0, 4000),
+      patch: [{ path: relPath, content: file.content }],
+    });
+    return {
+      status: 200,
+      json: {
+        ok: true,
+        status: "submitted",
+        path: relPath,
+        changeId: result?.changeId || changeId,
+        prNumber: result?.prNumber ?? null,
+        branch: result?.branch ?? null,
+        url: result?.url ?? null,
+        mergeable: result?.mergeable ?? null,
+        state: result?.state ?? null,
+      },
+    };
+  } catch (e) {
+    return { status: 502, json: { ok: false, status: "error", message: String(e?.message || e) } };
+  }
+}
+
+// --- request-level handler (env + body → {status, json}) -------------------
+// The deferred dev-plugins/dev-publish.mjs wrapper maps the HTTP req/res onto
+// this; keeping it here makes the endpoint contract unit-testable without a
+// running dev server (same pattern as file-writer.mjs's handleWrite).
+
+/**
+ * POST /__tot/publish — body {path}.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {{path?:string}} [body]
+ */
+export async function handlePublish(env = process.env, body = {}) {
+  const root = resolveTenantSourceRoot(env);
+  if (!root.ok) return { status: root.status === "no_tenant" ? 403 : 500, json: root };
+
+  const relPath = body && body.path;
+  if (!relPath) {
+    return { status: 400, json: { ok: false, status: "no_path", message: "path is required" } };
+  }
+
+  return publishFile(env, root.sourceRoot, root.tenantId, relPath);
+}

package/scripts/dev/transient-files.mjs

@@ -29,6 +29,7 @@ export function isTransientWatchFile(name) {
     /^#.*#$/.test(name) || // emacs autosave (#file#)
     name === ".DS_Store" ||
     name === "Thumbs.db" ||
-    name === "4913" // vim's write-probe file
+    name === "4913" || // vim's write-probe file
+    name.startsWith(".") // any dotfile — not store content, catches the rest (vim swaps included)
   );
 }