@tokenoftrust/storefront-runner 1.3.2

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

@@ -0,0 +1,384 @@
+/**
+ * Tenant configuration + theme token contract.
+ *
+ * Phase 1 resolves tenants from a static config map/KV by hostname. The lookup
+ * interface (resolveTenant) is intentionally async + many-ready so the same seam
+ * scales to Cloudflare-for-SaaS custom hostnames later without a rewrite.
+ */
+import type { FoxyCommerceConfig } from "./foxy.js";
+import type { CapabilityConfig } from "./capabilities.js";
+
+/**
+ * The shared semantic COLOR contract — the widget library's public API.
+ *
+ * Every platform component reads ONLY these tokens (as `var(--color-<key>)`,
+ * bridged into Tailwind by `styles/global.css` `@theme`). A tenant restyles the
+ * whole library by supplying token values — or aliasing its own brand vocabulary
+ * onto them — and NEVER edits a component. `themeToCssVars()` serializes each
+ * key `k` to `--color-<k>`.
+ *
+ * The REQUIRED keys are the core palette every theme states. The OPTIONAL keys
+ * are semantic/state + interaction extensions with platform-default fallbacks in
+ * the `@theme` bridge, so `var(--color-warning)`, `var(--color-primary-hover)`,
+ * etc. always resolve even when a theme omits them; a theme sets one only to
+ * brand-tune it. Canonical reference values live in `themes/reference.ts`.
+ * Full spec + tenant-alias guidance: `docs/architecture/token-contract.md`.
+ */
+export interface ThemeColorTokens {
+  /** Page background. */
+  bg: string;
+  /** Raised card/panel surface. */
+  surface: string;
+  /** Primary body + heading text. */
+  text: string;
+  /** Secondary / caption text. */
+  muted: string;
+  /** Brand anchor — primary CTAs, active nav, hero fill. */
+  primary: string;
+  /** Readable text/icon color ON `primary`. */
+  "primary-contrast": string;
+  /** Single brand spark — badges, marks, large accent type. */
+  accent: string;
+  /** Hairline borders, dividers, input outlines. */
+  border: string;
+  /** Success / in-stock / savings state. */
+  success: string;
+  /** Sale / markdown price emphasis. */
+  sale: string;
+
+  // --- Optional extensions — always resolvable via the @theme bridge default;
+  //     a theme sets one only to brand-tune it (see token-contract.md). ---
+  /** Subtle inset/raised fill between `bg` and `surface` (wells, table stripes). */
+  "surface-2"?: string;
+  /** Warning / low-stock state. */
+  warning?: string;
+  /** Error / out-of-stock / destructive state. */
+  error?: string;
+  /** Informational state (notices, help). */
+  info?: string;
+  /** Accent tuned for SMALL text/links on light surfaces (AA). Default: a
+   *  derived darken of `accent`; set to hand-tune contrast. */
+  "accent-ink"?: string;
+  /** Hover/active shade of `primary`. Default: a derived darken of `primary`. */
+  "primary-hover"?: string;
+  /** Hover/active shade of `accent`. Default: a derived darken of `accent`. */
+  "accent-hover"?: string;
+}
+
+export interface ThemeFontFamily {
+  family: string;
+  weights: number[];
+}
+
+export interface ThemeTypeTokens {
+  display: ThemeFontFamily;
+  body: ThemeFontFamily;
+  mono?: ThemeFontFamily;
+  /** Type scale ratio, e.g. 1.25 (major third). */
+  scale: number;
+  tracking?: string;
+}
+
+export interface ThemeSpaceTokens {
+  /** Base spacing unit in px. */
+  base: number;
+  /** Multiplier scale, e.g. [0, 0.25, 0.5, 1, 1.5, 2, 3, 4, 6, 8]. */
+  scale: number[];
+  containerMaxWidth: string;
+  sectionRhythm: string;
+}
+
+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 };
+}
+
+export interface ThemeBrandTokens {
+  logoLight: string;
+  logoDark: string;
+  favicon: string;
+  ogImage: string;
+  /** "full" | "reduced" — tenant-level default motion preference. */
+  motion: "full" | "reduced";
+  /**
+   * Header treatment. "dark" renders the bar in the primary color carrying the
+   * light logo (matches brands whose header is dark + white logo, e.g. vape
+   * stores); "light" (default) is a light bar with the dark logo/wordmark.
+   */
+  headerVariant?: "light" | "dark";
+  /**
+   * Hero treatment. "bold" (default) paints the hero full-bleed in the primary
+   * color (one signature moment). "light" renders the hero on the page
+   * background with the brand color used only as an accent on the headline/CTA —
+   * matches merchants whose own site is a light page with color accents. The
+   * brand adopter sets "light" when it captures a real hero image.
+   */
+  heroVariant?: "bold" | "light";
+}
+
+export interface ThemeTokens {
+  color: ThemeColorTokens;
+  type: ThemeTypeTokens;
+  space: ThemeSpaceTokens;
+  shape: ThemeShapeTokens;
+  brand: ThemeBrandTokens;
+}
+
+/**
+ * California Prop 65 warning content. The safe-harbor warning FORMAT is mandated
+ * (Cal. Code Regs. tit. 27 § 25601+): the component owns the fixed skeleton
+ * ("WARNING: … known to the State of California to cause …") and the official
+ * warnings URL; only the variable slots — which harm endpoint(s) the warning
+ * cites and the chemical name(s) named in the long form — come from tenant data.
+ * Never author the sentence in tenant/marketing copy; drive it from here.
+ */
+export interface Prop65Config {
+  /** Harm endpoint(s) the mandated clause cites. */
+  harm: "cancer" | "reproductive" | "cancer-and-reproductive";
+  /**
+   * Chemical name(s) named in the LONG-form warning (e.g. ["nicotine"]). When
+   * present the component renders the long form ("…including {chemicals}, which
+   * is/are known…"); omit for the short-form warning.
+   */
+  chemicals?: string[];
+  /** Official warnings URL. Defaults to www.P65Warnings.ca.gov. */
+  url?: string;
+}
+
+/**
+ * Purchase-quantity-limit DISPLAY. Display surface only — the limit is surfaced
+ * for the shopper; enforcement stays in the product/commerce layer, never hand-
+ * built here (per decision compliance-widgets-platform-owned).
+ */
+export interface PurchaseLimitConfig {
+  /** Human-readable limit, e.g. "2 units per order". Display only. */
+  text: string;
+  /** Optional short reason/citation, e.g. "per state law". */
+  reason?: string;
+}
+
+/**
+ * State/jurisdiction sale-eligibility DISPLAY. Display surface only — the widget
+ * SHOWS the tenant-configured eligibility messaging; it does NOT compute whether
+ * a given cart/address is eligible (that stays in the product/commerce layer,
+ * per decision compliance-widgets-platform-owned). List the restricted OR the
+ * eligible jurisdictions (or supply a custom note); the widget composes a
+ * default sentence when `note` is omitted.
+ */
+export interface StateEligibilityConfig {
+  /** State/jurisdiction codes or names where sale/shipment is NOT available. */
+  restrictedStates?: string[];
+  /** Allowlist — sale/shipment available ONLY in these. */
+  eligibleStates?: string[];
+  /** Custom display message; when omitted a sentence is composed from the lists. */
+  note?: string;
+}
+
+/**
+ * Excise-tax DISPLAY cue. Display surface only — it surfaces that applicable
+ * excise taxes apply and (optionally) a per-jurisdiction breakdown for shopper
+ * transparency; the actual tax CALCULATION is product/commerce-owned (never
+ * computed here), per decision compliance-widgets-platform-owned.
+ */
+export interface ExciseTaxConfig {
+  /** Display note, e.g. "State vapor excise taxes are calculated at checkout." */
+  note: string;
+  /** Optional per-jurisdiction lines (display only), e.g. { label: "CA", detail: "$0.05/ml" }. */
+  jurisdictions?: Array<{ label: string; detail: string }>;
+}
+
+/**
+ * Regulated-commerce compliance (e.g. vape/nicotine). Browse-surface only —
+ * the actual identity/age VERIFICATION is Token of Trust's product and is wired
+ * in a later phase; this config drives storefront affordances (FDA warning, the
+ * soft 21+ affirmation gate, shipping-restriction / jurisdiction notices).
+ * Omit/undefined for unregulated tenants and none of it renders.
+ *
+ * Every field below is data-driven: the matching platform widget in
+ * components/compliance/ renders ONLY when its field is present and NEVER
+ * fabricates or hand-authors mandated legal copy (per decision
+ * compliance-widgets-platform-owned). Additive — a tenant lists only what applies.
+ */
+export interface ComplianceConfig {
+  /** Minimum age to enter. Drives the soft affirmation gate (e.g. 21). */
+  minAge?: number;
+  /** Render the FDA nicotine warning sitewide + reinforced on PDP. */
+  nicotineWarning?: boolean;
+  /** Short PACT-Act / no-ship-states / adult-signature notice (plain text). */
+  shippingRestriction?: string;
+  /**
+   * Render the PACT Act compliance notice (ENDS/vapor shipments): age
+   * verification (21+), adult signature on delivery, no USPS carriage. The
+   * federal-requirement wording is fixed in PactActNotice; this is the on/off.
+   */
+  pactAct?: boolean;
+  /**
+   * Render the adult-signature-on-delivery notice. Wording is fixed in
+   * AdultSignatureNotice; the age reflects `minAge` (defaults to 21).
+   */
+  adultSignature?: boolean;
+  /**
+   * California Prop 65 warning. `true` renders the short cancer+reproductive
+   * safe-harbor warning; a Prop65Config selects the harm endpoint(s), chemical
+   * name(s), and URL. Absent → nothing renders.
+   */
+  prop65?: Prop65Config | boolean;
+  /** Purchase-quantity-limit display (display only; enforcement is product-owned). */
+  purchaseLimit?: PurchaseLimitConfig;
+  /**
+   * State/jurisdiction sale-eligibility display (display only; the eligibility
+   * DECISION for a given cart/address stays product-owned).
+   */
+  stateEligibility?: StateEligibilityConfig;
+  /**
+   * Excise-tax display cue (display only; the tax CALCULATION stays
+   * product/commerce-owned).
+   */
+  exciseTax?: ExciseTaxConfig;
+}
+
+/**
+ * What a tenant's site is FOR. "commerce" (default) is the browse/discover
+ * ecommerce storefront the platform was born as. "marketing" is a non-commerce
+ * B2B/SaaS site — chrome, rich page composition, and conversion CTAs, with the
+ * catalog/cart affordances switched off. The mode picks feature DEFAULTS
+ * (see resolveTenantFeatures); `features` overrides individual flags.
+ */
+export type SiteType = "commerce" | "marketing";
+
+/**
+ * Per-tenant capability switches. These gate whole surfaces so the same
+ * component library renders both a store and a marketing site without any
+ * tenant-specific `if` in shared code. Every flag has a sensible default keyed
+ * off `siteType`; a tenant only lists the ones it wants to flip.
+ */
+export interface TenantFeatures {
+  /** Catalog surfaces: /collections, /products/*, listing grids, PDPs. */
+  catalog: boolean;
+  /** Header search typeahead island. */
+  productSearch: boolean;
+  /** Wishlist / "saved items" surface + header heart control. */
+  savedItems: boolean;
+  /** Product quick-view dialog island. */
+  quickView: boolean;
+  /** Newsletter capture forms (footer + homepage block). */
+  newsletter: boolean;
+  /** Product/collection URLs in the XML sitemap. */
+  commerceSitemap: boolean;
+  /** Product-offer JSON-LD on product/collection pages. */
+  productJsonLd: boolean;
+  /** Soft age-affirmation gate + regulated-commerce chrome (also needs `compliance`). */
+  ageGate: boolean;
+}
+
+const COMMERCE_FEATURES: TenantFeatures = {
+  catalog: true,
+  productSearch: true,
+  savedItems: true,
+  quickView: true,
+  newsletter: true,
+  commerceSitemap: true,
+  productJsonLd: true,
+  ageGate: true,
+};
+
+const MARKETING_FEATURES: TenantFeatures = {
+  catalog: false,
+  productSearch: false,
+  savedItems: false,
+  quickView: false,
+  newsletter: false,
+  commerceSitemap: false,
+  productJsonLd: false,
+  ageGate: false,
+};
+
+/** Feature defaults for a site type (returns a fresh copy — safe to mutate). */
+export function siteTypeDefaults(siteType: SiteType): TenantFeatures {
+  return { ...(siteType === "marketing" ? MARKETING_FEATURES : COMMERCE_FEATURES) };
+}
+
+/**
+ * Resolve a tenant's effective features: siteType defaults, with any explicit
+ * `features` overrides layered on top (undefined entries ignored, so a tenant
+ * can flip one flag without restating the rest). Unset `siteType` == "commerce",
+ * preserving the platform's original behavior for existing tenants.
+ */
+export function resolveTenantFeatures(
+  tenant: Pick<TenantConfig, "siteType" | "features">,
+): TenantFeatures {
+  const base = siteTypeDefaults(tenant.siteType ?? "commerce");
+  if (!tenant.features) return base;
+  for (const [k, v] of Object.entries(tenant.features)) {
+    if (v !== undefined) base[k as keyof TenantFeatures] = v;
+  }
+  return base;
+}
+
+export interface TenantConfig {
+  tenant_id: string;
+  /** ToT-side merchant identifier (appDomain), e.g. "pilot.tokenoftrust.com". */
+  appDomain: string;
+  /** The hostname(s) that resolve to this tenant. */
+  domains: string[];
+  /** Primary canonical domain for SEO/canonical URLs. */
+  canonicalDomain: string;
+  displayName: string;
+  /** Storyblok delivery token for this tenant's child space. */
+  storyblok_space_token: string;
+  /** Data scope passed to the ToT catalog API (usually == appDomain). */
+  tot_data_scope: string;
+  /** Per-tenant theme overrides; merged over the reference theme defaults. */
+  theme_tokens: DeepPartial<ThemeTokens>;
+  /** Currency for display formatting. */
+  currency: string;
+  locale: string;
+  /**
+   * What the site is for: "commerce" (default) or "marketing". Drives feature
+   * defaults (resolveTenantFeatures) and non-commerce chrome. Omitted == commerce.
+   */
+  siteType?: SiteType;
+  /** Explicit feature overrides layered atop the siteType defaults. */
+  features?: Partial<TenantFeatures>;
+  /** Regulated-commerce affordances; undefined for unregulated tenants. */
+  compliance?: ComplianceConfig;
+  /**
+   * Cart/checkout engine wiring (FoxyCart, Track A). Present on commerce tenants
+   * that have a FoxyCart store; drives the loader + signed add-to-cart. The
+   * `storeSubDomain` here is a default — middleware may override it from env
+   * (FOXY_STORE_SUBDOMAIN) so the demo store swaps with zero code change. The
+   * signing SECRET is never stored on the tenant; it's an env Worker binding.
+   */
+  commerce?: {
+    foxy?: FoxyCommerceConfig;
+  };
+  /**
+   * PR-gated capability switches (cart/checkout, age/identity verification,
+   * excise tax). Source of truth is the tenant repo's `.tot/config.json`; this
+   * build-time default is overridden per environment by the published
+   * capabilities artifact (localhost=working tree, preview=PR head, live=promoted).
+   * Undefined entries default from siteType/compliance — see resolveCapabilities.
+   */
+  capabilities?: Partial<CapabilityConfig>;
+}
+
+export type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
+/** The interface the tenant-resolution middleware implements. */
+export interface TenantResolver {
+  /**
+   * Resolve a tenant for a hostname, falling back to a default tenant for
+   * unknown hosts (Phase 1 convenience so preview/local hosts still render).
+   */
+  resolveByHost(host: string): Promise<TenantConfig | null>;
+  /**
+   * Strict match: return the tenant that explicitly claims `host` in its
+   * `domains`, or null. Unlike resolveByHost it never falls back to a default,
+   * so callers can detect "this host/segment owns no tenant" — used by the
+   * `/<domain>/*` path-prefix routing fallback.
+   */
+  resolveStrict(host: string): Promise<TenantConfig | null>;
+}

package/packages/public-runtime/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"]
+}

package/packages/public-runtime/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["tests/**/*.test.ts"],
+    environment: "node",
+  },
+});

package/pnpm-workspace.yaml

@@ -0,0 +1,7 @@
+packages:
+  - "apps/*"
+  - "packages/*"
+onlyBuiltDependencies:
+  - esbuild
+  - sharp
+  - workerd

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

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * Prebuild step for the colocated tenant layout.
+ *
+ * A tenant IS the repo-root directory `tenants/<id>/` (holding content, public,
+ * theme.json). Astro serves static assets from `apps/storefront/public/`, so a
+ * tenant's public files must land at `apps/storefront/public/tenants/<id>/`
+ * for the `/tenants/<id>/...` URLs to resolve. This script mirrors every tenant's
+ * public directory into that generated location.
+ *
+ * The destination (`apps/storefront/public/tenants/`) is a BUILD ARTIFACT
+ * (gitignored) — the source of truth is `tenants/<id>/public/`. Wired into the
+ * storefront `prebuild`/`predev` lifecycle (package.json) and invoked directly by
+ * `scripts/tot-dev.mjs` before it boots `astro dev`.
+ *
+ * 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
+ * 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).
+ */
+import { cp, mkdir, readdir, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const src = resolve(repoRoot, "tenants");
+const dest = process.env.TENANT_ASSETS_DEST
+  ? resolve(process.env.TENANT_ASSETS_DEST)
+  : resolve(repoRoot, "apps/storefront/public/tenants");
+
+if (!existsSync(src)) process.exit(0);
+
+await rm(dest, { recursive: true, force: true });
+
+const versionedEnv = new Set(
+  (process.env.TENANT_ASSETS_VERSIONED ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean),
+);
+const isVersioned = (id) =>
+  versionedEnv.has(id) ||
+  existsSync(join(src, id, ".tot", "assets-versioned"));
+
+let copied = 0;
+let skipped = 0;
+for (const id of await readdir(src)) {
+  const pub = join(src, id, "public");
+  if (!existsSync(pub)) continue;
+  // Versioned tenants are served from R2 — baking would shadow the R2 route.
+  if (isVersioned(id)) {
+    skipped++;
+    continue;
+  }
+  await mkdir(join(dest, id), { recursive: true });
+  await cp(pub, join(dest, id), { recursive: true });
+  copied++;
+}
+
+const skipNote = skipped ? ` (skipped ${skipped} versioned → R2)` : "";
+console.log(
+  `copy-tenant-assets: mirrored ${copied} tenant public/ tree(s) → ${dest}${skipNote}`,
+);

package/scripts/dev/ai-edit.mjs

@@ -0,0 +1,183 @@
+/**
+ * The inline-AI edit loop's dev-server-side handlers (WS5 G1): the floating
+ * "✦ ask" box (see ai-widget-client.js) posts a prompt here; this resolves the
+ * developer's MCP session, calls the `content_edit` tool with the tenant's
+ * current content/theme, applies the returned unified diffs to disk (which
+ * fires the existing tenantHotReload/Vite HMR — see astro.config.mjs), and
+ * records the edit for one-key undo. Wired into `astro dev` as a Vite
+ * middleware plugin (astro.config.mjs's `inlineAiEditPlugin`), so it only
+ * ever runs in `astro dev` — never bundled into the production Cloudflare
+ * Worker (see the plugin's `apply: "serve"`).
+ *
+ * Reuses the CLI's own MCP transport + developer-session resolution
+ * (packages/cli/src/mcp.mjs, auth.mjs) via a plain relative import — both are
+ * dependency-free and the astro dev process runs on the same host/user as the
+ * `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.
+ * The MCP tool enforces this server-side; nothing here widens it.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join, dirname } from "node:path";
+import { createMcpClient } from "../../packages/cli/src/mcp.mjs";
+import { resolveDeveloperSession, AuthUnavailableError } from "../../packages/cli/src/auth.mjs";
+import { applyUnifiedDiff } from "./unified-diff.mjs";
+
+const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
+
+/** Where a tenant's editable files + AI-edit history live (monorepo layout). */
+export function tenantPaths(repoRoot, tenantId) {
+  const dir = join(repoRoot, "tenants", tenantId);
+  return {
+    dir,
+    home: join(dir, "content", "home.html"),
+    theme: join(dir, "theme.json"),
+    historyFile: join(dir, ".tot", "ai-history.jsonl"),
+  };
+}
+
+function readFileIfPresent(path) {
+  return existsSync(path) ? readFileSync(path, "utf8") : null;
+}
+
+function appendHistory(historyFile, entry) {
+  mkdirSync(dirname(historyFile), { recursive: true });
+  appendFileSync(historyFile, `${JSON.stringify(entry)}\n`);
+}
+
+function readHistory(historyFile) {
+  if (!existsSync(historyFile)) return [];
+  return readFileSync(historyFile, "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
+/**
+ * Resolve an authenticated MCP client for the developer signed in to THIS
+ * machine (`tot login`). Never refreshes an expired token — mirrors the
+ * "silently refresh" case as an explicit ask to re-run `tot login`, matching
+ * the CLI's own AuthUnavailableError guidance rather than an obscure 500.
+ */
+async function resolveClient(mcpBaseUrl) {
+  const client = createMcpClient(mcpBaseUrl || process.env.TOT_MCP_URL || DEFAULT_MCP_URL);
+  await client.initialize();
+  try {
+    await resolveDeveloperSession(client, process.env);
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      throw new Error(`${e.message} ${e.hint || ""}`.trim());
+    }
+    throw e;
+  }
+  return client;
+}
+
+/**
+ * Handle a "✦ ask" submission: prompt + tenant → MCP content_edit → diffs
+ * applied to disk + one history entry. Returns a plain object the widget
+ * renders directly (never throws for expected failure modes — auth/refusal/
+ * not-configured all come back as `{ ok:false, status, message }`).
+ */
+export async function handleAiEdit({ repoRoot, tenantId, prompt, mcpBaseUrl }, deps = {}) {
+  const { resolveClientImpl = resolveClient } = deps;
+  const paths = tenantPaths(repoRoot, tenantId);
+  const files = [
+    { path: "content/home.html", content: readFileIfPresent(paths.home) },
+    { path: "theme.json", content: readFileIfPresent(paths.theme) },
+  ].filter((f) => f.content !== null);
+
+  if (files.length === 0) {
+    return { ok: false, status: "no_files", message: `No content/home.html or theme.json found under tenants/${tenantId}/.` };
+  }
+
+  let client;
+  try {
+    client = await resolveClientImpl(mcpBaseUrl);
+  } catch (e) {
+    return { ok: false, status: "unauthenticated", message: e.message };
+  }
+
+  let result;
+  try {
+    result = await client.callTool("content_edit", { prompt, files });
+  } catch (e) {
+    return { ok: false, status: "error", message: e.message };
+  }
+  if (result?.status && result.status !== "ok") {
+    return { ok: false, status: result.status, message: result.message || "content_edit refused the request." };
+  }
+
+  const diffs = Array.isArray(result?.diffs) ? result.diffs : [];
+  if (diffs.length === 0) {
+    return { ok: true, status: "noop", summary: result?.summary || "No change was needed.", diffs: [] };
+  }
+
+  const pathFor = (relPath) => (relPath === "content/home.html" ? paths.home : relPath === "theme.json" ? paths.theme : null);
+  const applied = [];
+  for (const d of diffs) {
+    const target = pathFor(d.path);
+    if (!target) {
+      return { ok: false, status: "out_of_scope", message: `content_edit returned a diff for an unexpected path: ${d.path}` };
+    }
+    const before = readFileIfPresent(target) ?? "";
+    let after;
+    try {
+      after = applyUnifiedDiff(before, d.diff);
+    } catch (e) {
+      return { ok: false, status: "diff_apply_failed", message: `Could not apply the diff for ${d.path}: ${e.message}` };
+    }
+    applied.push({ path: d.path, target, before, after, diff: d.diff });
+  }
+
+  // Write only after every diff in the batch applies cleanly — a partial
+  // apply would leave content/theme inconsistent with each other.
+  for (const a of applied) writeFileSync(a.target, a.after);
+
+  const historyId = randomUUID();
+  appendHistory(paths.historyFile, {
+    id: historyId,
+    at: new Date().toISOString(),
+    kind: "edit",
+    prompt,
+    summary: result.summary,
+    files: applied.map(({ path, before, after, diff }) => ({ path, before, after, diff })),
+  });
+
+  return {
+    ok: true,
+    status: "ok",
+    summary: result.summary,
+    diffs: applied.map(({ path, diff }) => ({ path, diff })),
+    historyId,
+  };
+}
+
+/**
+ * One-key undo: restore the most recent (non-undone) edit's files to their
+ * pre-edit content, and record the undo as its own history entry so the log
+ * stays an honest append-only account of what happened.
+ */
+export function handleAiUndo({ repoRoot, tenantId }) {
+  const paths = tenantPaths(repoRoot, tenantId);
+  const history = readHistory(paths.historyFile);
+  const undoneIds = new Set(history.filter((h) => h.kind === "undo").map((h) => h.undoes));
+  const lastEdit = [...history].reverse().find((h) => h.kind === "edit" && !undoneIds.has(h.id));
+
+  if (!lastEdit) {
+    return { ok: false, status: "nothing_to_undo", message: "No AI edit to undo." };
+  }
+
+  for (const f of lastEdit.files) writeFileSync(f.path === "content/home.html" ? paths.home : paths.theme, f.before);
+
+  appendHistory(paths.historyFile, {
+    id: randomUUID(),
+    at: new Date().toISOString(),
+    kind: "undo",
+    undoes: lastEdit.id,
+  });
+
+  return { ok: true, status: "ok", restoredPaths: lastEdit.files.map((f) => f.path), undid: lastEdit.summary };
+}