@web-my-money/studio-consumer 2.2.0 → 2.4.0

package/cli/provisioner.mjs

@@ -0,0 +1,103 @@
+// @ts-check
+
+/**
+ * The provisioning actions behind one interface (spec 2026-10-09 §6). This
+ * implementation runs the developer's own `gh` and `vercel` CLIs, so their
+ * sessions do the work and Studio holds no GitHub or Vercel credentials.
+ * Studio-driven provisioning (option 2) is another implementation of the same
+ * interface; nothing else changes.
+ *
+ * Flags checked against Vercel CLI 54 (2026-10-09): `env add` needs `--yes`
+ * (it otherwise asks to confirm, which hangs with the value on stdin), and has
+ * `--sensitive` and `--force`; `link` takes `--project`; `env ls` has `--format json`.
+ *
+ * @typedef {"production" | "preview"} EnvTarget
+ * @typedef {{
+ *   createRepoFromTemplate(name: string): Promise<void>,
+ *   createRepoFromSource(name: string): Promise<void>,
+ *   linkVercel(project: string): Promise<void>,
+ *   hasEnv(name: string): Promise<boolean>,
+ *   setEnv(name: string, value: string, targets: EnvTarget[], opts?: { sensitive?: boolean, force?: boolean }): Promise<void>,
+ * }} Provisioner
+ */
+
+/** @typedef {import("./run.mjs").Runner} Runner */
+
+/**
+ * @param {{ cwd: string, run: Runner, scope: string }} ctx
+ * @returns {Provisioner}
+ */
+export function cliProvisioner({ cwd, run, scope }) {
+  /**
+   * @param {string} cmd
+   * @param {string[]} args
+   * @param {{ input?: string, cwd?: string }} [opts]
+   * @param {string} [shown] what to tell the developer to run by hand (never contains a secret)
+   */
+  async function must(cmd, args, opts = {}, shown = `${cmd} ${args.join(" ")}`) {
+    const r = await run(cmd, args, { cwd: opts.cwd ?? cwd, input: opts.input });
+    if (r.code !== 0) {
+      const why = (r.stderr || r.stdout).trim().split(/\r?\n/).slice(-1)[0] ?? "";
+      throw new Error(`\`${shown}\` failed${why ? `: ${why}` : ""}`);
+    }
+    return r;
+  }
+
+  /** @type {Map<string, string[]> | null} read once per run: name → targets */
+  let envs = null;
+
+  return {
+    async createRepoFromTemplate(name) {
+      // No --clone: it would clone into ./<name>, and this folder already holds
+      // the command's progress. The command pulls the repository in itself.
+      await must("gh", [
+        "repo",
+        "create",
+        `Web-My-Money/${name}`,
+        "--private",
+        "--template",
+        "Web-My-Money/wmm-site-template",
+      ]);
+    },
+    async createRepoFromSource(name) {
+      await must("gh", ["repo", "create", `Web-My-Money/${name}`, "--private", "--source", ".", "--remote", "origin"]);
+    },
+    async linkVercel(project) {
+      // --scope pins the WMM team (a personal Vercel login would otherwise link
+      // to the wrong account); --project names the project instead of guessing
+      // it from the folder name.
+      await must("vercel", ["link", "--yes", "--project", project, "--scope", scope]);
+      // `vercel link` usually connects the GitHub repo itself; then this answers
+      // "already connected", which is the state we want (seen in the real run).
+      const connect = await run("vercel", ["git", "connect", "--yes", "--scope", scope], { cwd });
+      if (connect.code !== 0 && !/already connected/i.test(`${connect.stderr}\n${connect.stdout}`)) {
+        const why = (connect.stderr || connect.stdout).trim().split(/\r?\n/).slice(-1)[0] ?? "";
+        throw new Error(`\`vercel git connect\` failed${why ? `: ${why}` : ""}`);
+      }
+    },
+    async hasEnv(name) {
+      if (!envs) {
+        const r = await must("vercel", ["env", "ls", "--format", "json", "--scope", scope]);
+        envs = new Map();
+        const parsed = /** @type {{ envs?: { key: string, target?: string[] | string }[] }} */ (JSON.parse(r.stdout || "{}"));
+        for (const e of parsed.envs ?? []) {
+          const targets = Array.isArray(e.target) ? e.target : e.target ? [e.target] : [];
+          envs.set(e.key, [...(envs.get(e.key) ?? []), ...targets]);
+        }
+      }
+      const targets = envs.get(name) ?? [];
+      return targets.includes("production") || targets.includes("preview");
+    },
+    async setEnv(name, value, targets, opts = {}) {
+      for (const target of targets) {
+        const args = ["env", "add", name, target, "--yes"];
+        if (opts.sensitive) args.push("--sensitive");
+        if (opts.force) args.push("--force");
+        args.push("--scope", scope);
+        // The value goes on stdin: never in the argument list, never on screen.
+        await must("vercel", args, { input: value }, `vercel env add ${name} ${target}`);
+      }
+      if (envs) envs.set(name, [...(envs.get(name) ?? []), ...targets]);
+    },
+  };
+}

package/cli/run.mjs

@@ -0,0 +1,89 @@
+// @ts-check
+import { spawn } from "node:child_process";
+
+/**
+ * Every external command the onboarding command runs goes through here: an
+ * argument array, never a shell string. Secrets travel on stdin (`input`), never
+ * as arguments, so they never show in a process list or a shell history.
+ *
+ * Windows: npm, vercel and other npm-installed CLIs are `.cmd` shims, which Node
+ * will only start through a shell. So a command that is not found as a real
+ * executable is retried through `cmd.exe` with every argument quoted, and an
+ * argument cmd could reinterpret (a double quote, %, a newline) is refused rather
+ * than escaped by guesswork. Our arguments are names, keys and messages we build.
+ */
+
+/**
+ * @typedef {{ code: number, stdout: string, stderr: string }} RunResult
+ * @typedef {{ cwd?: string, input?: string, inherit?: boolean }} RunOptions
+ * @typedef {(cmd: string, args: string[], opts?: RunOptions) => Promise<RunResult>} Runner
+ */
+
+/**
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {RunOptions} opts
+ * @param {boolean} viaShell
+ * @returns {Promise<RunResult & { notFound?: boolean }>}
+ */
+function once(cmd, args, opts, viaShell) {
+  return new Promise((resolve) => {
+    /** @type {import("node:child_process").ChildProcess} */
+    let child;
+    try {
+      if (viaShell) {
+        // The command NAME is passed bare: quoting it makes cmd.exe resolve a
+        // .cmd shim's own folder (%~dp0) to the cwd, which breaks npm on
+        // nvm-windows. So the name may only be a plain program name.
+        if (!/^[A-Za-z0-9_.-]+$/.test(cmd)) {
+          resolve({ code: 2, stdout: "", stderr: `refusing to run ${JSON.stringify(cmd)} through cmd.exe` });
+          return;
+        }
+        for (const a of args) {
+          if (/["%\r\n]/.test(a)) {
+            resolve({ code: 2, stdout: "", stderr: `refusing to pass ${JSON.stringify(a)} through cmd.exe` });
+            return;
+          }
+        }
+        const line = [cmd, ...args.map((a) => `"${a}"`)].join(" ");
+        child = spawn(line, { cwd: opts.cwd, shell: true, stdio: opts.inherit ? "inherit" : "pipe", windowsHide: true });
+      } else {
+        child = spawn(cmd, args, { cwd: opts.cwd, stdio: opts.inherit ? "inherit" : "pipe", windowsHide: true });
+      }
+    } catch {
+      resolve({ code: 127, stdout: "", stderr: "", notFound: true });
+      return;
+    }
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (d) => (stdout += String(d)));
+    child.stderr?.on("data", (d) => (stderr += String(d)));
+    child.on("error", (err) => {
+      const notFound = /** @type {NodeJS.ErrnoException} */ (err).code === "ENOENT";
+      resolve({ code: 127, stdout, stderr: stderr || err.message, notFound });
+    });
+    child.on("close", (code) => {
+      const notRecognised = viaShell && /is not recognized as an internal or external command/i.test(stderr);
+      resolve({ code: notRecognised ? 127 : (code ?? 1), stdout, stderr });
+    });
+    if (!opts.inherit && child.stdin) {
+      if (opts.input !== undefined) child.stdin.end(opts.input);
+      else child.stdin.end();
+    }
+  });
+}
+
+/** @returns {Runner} */
+export function createRunner() {
+  return async function run(cmd, args, opts = {}) {
+    if (/[&|<>^"%\r\n]/.test(cmd)) {
+      return { code: 2, stdout: "", stderr: `refusing to run ${JSON.stringify(cmd)}: not a plain program name` };
+    }
+    const first = await once(cmd, args, opts, false);
+    if (first.notFound && process.platform === "win32") {
+      const viaShell = await once(cmd, args, opts, true);
+      return { code: viaShell.code, stdout: viaShell.stdout, stderr: viaShell.stderr };
+    }
+    return { code: first.code, stdout: first.stdout, stderr: first.stderr };
+  };
+}

package/cli/scaffold.mjs

@@ -0,0 +1,155 @@
+// @ts-check
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { isOwnGitignore } from "./state.mjs";
+
+/**
+ * A new site from WMM's template (spec 2026-10-09 §3.2): pull the repository
+ * GitHub created from `Web-My-Money/wmm-site-template` into the developer's
+ * folder, then make it this site's.
+ */
+
+/** @typedef {import("./run.mjs").Runner} Runner */
+
+/** The only two strings in the template that become this site's (see its README). */
+export const MARKERS = { key: "wmm-template-site", name: "WMM Template Site" };
+
+const FETCH_TRIES = 10;
+const FETCH_WAIT_MS = 3000;
+
+/**
+ * GitHub copies a template into the new repository in the background, so for a
+ * few seconds the repository has no `main`. That case is waited out; any other
+ * failure (usually git not signed in to GitHub) stops at once with the fix.
+ *
+ * @param {{ cwd: string, run: Runner, sleep: (ms: number) => Promise<void>, name: string }} ctx
+ * @returns {Promise<{ ok: true } | { ok: false, message: string, nextCommand?: string }>}
+ */
+export async function pullTemplateRepo({ cwd, run, sleep, name }) {
+  const url = `https://github.com/Web-My-Money/${name}.git`;
+  if (!existsSync(path.join(cwd, ".git"))) {
+    const init = await run("git", ["init", "-b", "main"], { cwd });
+    if (init.code !== 0) return { ok: false, message: `git could not start a repository here: ${lastLine(init)}` };
+  }
+  const origin = await run("git", ["remote", "get-url", "origin"], { cwd });
+  if (origin.code !== 0) {
+    const add = await run("git", ["remote", "add", "origin", url], { cwd });
+    if (add.code !== 0) return { ok: false, message: `git could not add the new repository: ${lastLine(add)}` };
+  } else {
+    // A folder already tied to some other repository would fetch the wrong one forever.
+    const current = origin.stdout.trim();
+    const ours = new RegExp(`github\\.com[/:]Web-My-Money/${name}(\\.git)?$`, "i");
+    if (!ours.test(current)) {
+      return {
+        ok: false,
+        message: `This folder's git remote points at ${current}, not at Web-My-Money/${name}. Point it at the new site's repository, then run this again.`,
+        nextCommand: `git remote set-url origin ${url}`,
+      };
+    }
+  }
+
+  for (let i = 0; i < FETCH_TRIES; i++) {
+    const r = await run("git", ["fetch", "origin", "main"], { cwd });
+    if (r.code === 0) {
+      // The progress file's one-line .gitignore would block checking out the
+      // template's own (which already ignores the progress folder).
+      if (isOwnGitignore(cwd)) rmSync(path.join(cwd, ".gitignore"));
+      const co = await run("git", ["checkout", "-B", "main", "origin/main"], { cwd });
+      if (co.code !== 0) return { ok: false, message: `git could not check out the new site: ${lastLine(co)}` };
+      return { ok: true };
+    }
+    if (!/couldn't find remote ref/i.test(r.stderr)) {
+      return {
+        ok: false,
+        message: `git could not download the new repository: ${lastLine(r)}. If git is not signed in to GitHub, this fixes it; then run this again.`,
+        nextCommand: "gh auth setup-git",
+      };
+    }
+    if (i < FETCH_TRIES - 1) await sleep(FETCH_WAIT_MS);
+  }
+  return { ok: false, message: "GitHub is still preparing the repository. Run this again in a minute; it continues from here." };
+}
+
+// The same rule and reserved ids as defineSiteBrand (src/brand/index.ts): in a
+// template site the key IS the theme id, so it must be a valid client theme.
+const THEME_ID = /^[a-z][a-z0-9-]{0,40}$/;
+const WMM_THEMES = ["wmm", "site", "light", "dark"];
+
+/**
+ * Why a site key cannot be used for a site made from the template, or null.
+ * Checked before anything is created, so a bad key never leaves a repository behind.
+ *
+ * @param {string} siteKey
+ * @returns {string | null}
+ */
+export function templateKeyProblem(siteKey) {
+  if (THEME_ID.test(siteKey) && !WMM_THEMES.includes(siteKey)) return null;
+  return `The site key "${siteKey}" cannot be used for a site made from WMM's template: it becomes the brand theme id, so it must start with a letter, use only lowercase letters, digits and dashes, be at most 41 characters, and not be one of ${WMM_THEMES.join(", ")}. Add the site again in Studio with a key like that.`;
+}
+
+/** @param {{ stdout: string, stderr: string }} r */
+function lastLine(r) {
+  return (r.stderr || r.stdout).trim().split(/\r?\n/).slice(-1)[0] ?? "";
+}
+
+/**
+ * Replace the template's markers in every tracked file, escaped for where they
+ * land, and swap the template's README for one about this site.
+ *
+ * @param {{ cwd: string, run: Runner, siteKey: string, siteName: string }} ctx
+ * @returns {Promise<string[]>} the files that changed
+ */
+export async function personalise({ cwd, run, siteKey, siteName }) {
+  const problem = templateKeyProblem(siteKey);
+  if (problem) throw new Error(problem);
+  const listed = await run("git", ["ls-files"], { cwd });
+  const files = listed.stdout.split(/\r?\n/).map((f) => f.trim()).filter(Boolean);
+
+  /** @type {string[]} */
+  const changed = [];
+  for (const rel of files) {
+    const abs = path.join(cwd, rel);
+    if (!existsSync(abs)) continue;
+    if (rel === "README.md") {
+      writeFileSync(abs, siteReadme(siteName));
+      changed.push(rel);
+      continue;
+    }
+    const body = readFileSync(abs, "utf8");
+    if (body.includes("\0")) continue; // binary
+    if (!body.includes(MARKERS.key) && !body.includes(MARKERS.name)) continue;
+    const next = body.replaceAll(MARKERS.key, siteKey).replaceAll(MARKERS.name, nameFor(rel, siteName));
+    writeFileSync(abs, next);
+    changed.push(rel);
+  }
+  return changed;
+}
+
+/**
+ * The display name, escaped for the file it lands in: inside a JSON or code
+ * string it must not end the string; inside a CSS comment it must not end the
+ * comment.
+ *
+ * @param {string} rel
+ * @param {string} name
+ */
+function nameFor(rel, name) {
+  if (/\.(json|[cm]?[jt]sx?)$/.test(rel)) return JSON.stringify(name).slice(1, -1);
+  if (rel.endsWith(".css")) return name.replaceAll("*/", "");
+  return name;
+}
+
+/** @param {string} name */
+function siteReadme(name) {
+  return `# ${name}
+
+${name}'s website, built from WMM's site template and connected to WMM Studio.
+
+- Copy: \`dictionaries/en.json\` and \`es.json\` (same keys in both).
+- Brand colours: \`app/client-theme.css\`.
+- What the client can edit in Studio: \`lib/content-manifest.ts\`.
+- Rules for working on this site: \`CLAUDE.md\`.
+
+Before every push: \`npm run verify\`.
+`;
+}

package/cli/state.mjs

@@ -0,0 +1,49 @@
+// @ts-check
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * Where the onboarding command keeps its progress, so a rerun resumes instead
+ * of starting over. Lives in `.wmm-onboarding/` (gitignored by this module).
+ * NEVER holds the ingest key: that goes straight into Vercel and nowhere else.
+ *
+ * @typedef {{
+ *   siteKey: string, siteName: string, studioUrl: string, manifestUrl: string,
+ *   revalidateUrl: string, modules: string[], readyToken: string, done: string[],
+ *   theme?: string, scope?: string, baseBranch?: string, siteHasKey?: boolean,
+ *   mode?: "new" | "existing", repoCreated?: boolean
+ * }} OnboardingState
+ */
+
+const DIR = ".wmm-onboarding";
+
+/**
+ * True when `.gitignore` is the one-line file saveState wrote into a folder that
+ * had none: the command's own file, safe to treat as absent.
+ *
+ * @param {string} cwd
+ */
+export function isOwnGitignore(cwd) {
+  const file = path.join(cwd, ".gitignore");
+  return existsSync(file) && readFileSync(file, "utf8").trim() === `${DIR}/`;
+}
+
+/** @param {string} cwd @returns {OnboardingState | null} */
+export function loadState(cwd) {
+  const file = path.join(cwd, DIR, "state.json");
+  if (!existsSync(file)) return null;
+  return JSON.parse(readFileSync(file, "utf8"));
+}
+
+/** @param {string} cwd @param {OnboardingState} state */
+export function saveState(cwd, state) {
+  const { ingestKey: _never, ...safe } = /** @type {OnboardingState & { ingestKey?: unknown }} */ (state);
+  mkdirSync(path.join(cwd, DIR), { recursive: true });
+  writeFileSync(path.join(cwd, DIR, "state.json"), `${JSON.stringify(safe, null, 2)}\n`);
+  const gitignore = path.join(cwd, ".gitignore");
+  const current = existsSync(gitignore) ? readFileSync(gitignore, "utf8") : "";
+  if (!current.split(/\r?\n/).includes(`${DIR}/`)) {
+    const sep = current === "" || current.endsWith("\n") ? "" : "\n";
+    writeFileSync(gitignore, `${current}${sep}${DIR}/\n`);
+  }
+}

package/cli/studio-api.mjs

@@ -0,0 +1,127 @@
+// @ts-check
+
+/**
+ * The two Studio calls the onboarding command makes, with every failure turned
+ * into a sentence a developer can act on.
+ */
+
+/** @typedef {(url: string, init: { method: string, headers: Record<string, string>, body: string }) => Promise<Response>} FetchLike */
+/** @typedef {{ ok: true, data: Record<string, unknown> } | { ok: false, message: string }} ApiResult */
+
+/**
+ * @param {FetchLike} fetchImpl
+ * @param {string} url
+ * @param {unknown} body
+ */
+async function post(fetchImpl, url, body) {
+  const res = await fetchImpl(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  /** @type {Record<string, unknown>} */
+  let json = {};
+  try {
+    json = /** @type {Record<string, unknown>} */ (await res.json());
+  } catch {
+    json = {};
+  }
+  return { status: res.status, json };
+}
+
+const unreachable = (/** @type {string} */ base) =>
+  `Could not reach Studio at ${base}. Check your internet connection, then run this again.`;
+
+/**
+ * @param {string} studioUrl
+ * @param {string} code
+ * @param {FetchLike} [fetchImpl]
+ * @returns {Promise<ApiResult>}
+ */
+export async function exchangeCode(studioUrl, code, fetchImpl = fetch) {
+  const base = studioUrl.replace(/\/+$/, "");
+  let r;
+  try {
+    r = await post(fetchImpl, `${base}/api/public/setup/exchange`, { code });
+  } catch {
+    return { ok: false, message: unreachable(base) };
+  }
+  if (r.status === 200) return { ok: true, data: r.json };
+  if (r.status === 429) {
+    return { ok: false, message: "Too many attempts from this network. Wait a minute, then run this again." };
+  }
+  if (r.status === 400) {
+    return {
+      ok: false,
+      message:
+        "That setup code has expired or was already used. Get a new one in Studio: open the site, Site settings, Get the setup command.",
+    };
+  }
+  return {
+    ok: false,
+    message:
+      typeof r.json.error === "string"
+        ? r.json.error
+        : "Studio could not finish the setup. Ask for a new code in Site settings.",
+  };
+}
+
+/**
+ * @param {string} studioUrl
+ * @param {string} readyToken
+ * @param {FetchLike} [fetchImpl]
+ * @returns {Promise<ApiResult>}
+ */
+export async function markReady(studioUrl, readyToken, fetchImpl = fetch) {
+  const base = studioUrl.replace(/\/+$/, "");
+  let r;
+  try {
+    r = await post(fetchImpl, `${base}/api/public/setup/ready`, { readyToken });
+  } catch {
+    return { ok: false, message: unreachable(base) };
+  }
+  if (r.status === 200) return { ok: true, data: r.json };
+  if (r.status === 429) {
+    return { ok: false, message: "Studio synced this site moments ago. Wait 30 seconds, then run this again." };
+  }
+  return {
+    ok: false,
+    message: typeof r.json.error === "string" ? r.json.error : "Studio could not sync the site. Run this again in a minute.",
+  };
+}
+
+/**
+ * The site's analytics key, asked for at the moment it is saved to Vercel.
+ * `inUse` means the site already has a key Studio will not replace.
+ *
+ * @param {string} studioUrl
+ * @param {string} readyToken
+ * @param {FetchLike} [fetchImpl]
+ * @returns {Promise<{ ok: true, ingestKey: string } | { ok: false, inUse: boolean, message: string }>}
+ */
+export async function requestKey(studioUrl, readyToken, fetchImpl = fetch) {
+  const base = studioUrl.replace(/\/+$/, "");
+  let r;
+  try {
+    r = await post(fetchImpl, `${base}/api/public/setup/key`, { readyToken });
+  } catch {
+    return { ok: false, inUse: false, message: unreachable(base) };
+  }
+  if (r.status === 200 && typeof r.json.ingestKey === "string") return { ok: true, ingestKey: r.json.ingestKey };
+  if (r.status === 409) {
+    return { ok: false, inUse: true, message: "This site already has an analytics key in use." };
+  }
+  if (r.status === 400) {
+    return {
+      ok: false,
+      inUse: false,
+      message: "This setup has expired (it lasts 24 hours). Get a new command in Studio's Site settings and run it.",
+    };
+  }
+  return {
+    ok: false,
+    inUse: false,
+    message: typeof r.json.error === "string" ? r.json.error : "Studio could not create the key. Run this again.",
+  };
+}
+

package/cli/templates.mjs

@@ -0,0 +1,134 @@
+// @ts-check
+
+/**
+ * The files `init` writes into a site, as functions of the values Studio handed
+ * over. They mirror docs/ONBOARD-A-SITE.md in wmm-studio; imports are relative
+ * so they work whether or not the app has an `@/` alias.
+ *
+ * Paths are relative to the app's code root (`.` or `src`), except the test,
+ * which lives at the repo root.
+ */
+
+const HEADER = "// Written by `npx @web-my-money/studio-consumer init`. Safe to edit.\n";
+
+/** @param {string} s */
+const q = (s) => JSON.stringify(s);
+
+/** @param {{ siteKey: string }} v */
+export const studioTs = (v) => `${HEADER}
+/**
+ * This site's key in WMM Studio. A constant on purpose, never an env var: every
+ * event and every content slot is filed under it, so it must not differ between
+ * environments.
+ */
+export const SITE_KEY = ${q(v.siteKey)};
+`;
+
+/** @param {{ theme: string, style: "flat" | "glass" }} v */
+export const brandTs = (v) => `${HEADER}import { defineSiteBrand } from "@web-my-money/studio-consumer/brand";
+
+/**
+ * The site's brand theme. Spread brandRootAttributes(brand) on <html> in the
+ * root layout. A missing or WMM-owned theme fails the build on purpose: a
+ * client site must never inherit WMM's look by accident.
+ */
+export const brand = defineSiteBrand({ theme: ${q(v.theme)}, style: ${q(v.style)} });
+`;
+
+export const contentManifestTs = () => `${HEADER}import { SITE_KEY } from "./studio";
+
+/**
+ * What Studio may edit on this site. Starts empty: the onboarding skill
+ * (\`/onboard-site\` in Claude Code) proposes the editable text and fills this
+ * in once you approve it.
+ */
+export async function getManifest() {
+  return {
+    siteKey: SITE_KEY,
+    generatedAt: new Date().toISOString(),
+    slots: [],
+  };
+}
+`;
+
+export const contentTs = () => `${HEADER}import "server-only";
+import { createContentClient, type StudioForm } from "@web-my-money/studio-consumer/content";
+import { getManifest } from "./content-manifest";
+import { SITE_KEY } from "./studio";
+
+// Built ONCE, at module scope: its methods share one cached fetch per render,
+// so every section of a page agrees on the content and the A/B arm.
+const client = createContentClient({
+  studioUrl: process.env.STUDIO_CONTENT_URL,
+  siteKey: SITE_KEY,
+  getManifest,
+});
+
+export type { StudioForm };
+export const getSlot = client.getSlot;
+export const getLocalizedSlot = client.getLocalizedSlot;
+export const applyDictOverrides = client.applyDictOverrides;
+export const activeVariant = client.activeVariant;
+export const getRunningExperiments = client.getRunningExperiments;
+export const getDecidedWinners = client.getDecidedWinners;
+export const getStudioForms = client.getStudioForms;
+`;
+
+/** @param {string} toLib relative path from the route file to the lib folder */
+export const manifestRouteTs = (toLib) => `${HEADER}import { createManifestHandler } from "@web-my-money/studio-consumer/content";
+import { getManifest } from "${toLib}/content-manifest";
+import { brand } from "${toLib}/brand";
+
+// Always answers from the live code (the handler waits for a request), so
+// Studio never syncs against a copy frozen at build time.
+export const GET = createManifestHandler(getManifest, brand);
+`;
+
+export const revalidateRouteTs = () => `${HEADER}import { createRevalidateHandler } from "@web-my-money/studio-consumer/content";
+
+// Built per request so the env is read at request time, not frozen at load.
+export function POST(request: Request): Promise<Response> {
+  return createRevalidateHandler({
+    studioUrl: process.env.STUDIO_CONTENT_URL,
+  })(request);
+}
+`;
+
+/**
+ * @param {string} toLib
+ * @param {boolean} withExperiments
+ */
+export const collectRouteTs = (toLib, withExperiments) => `${HEADER}import { createCollectHandler } from "@web-my-money/studio-consumer/analytics";
+import { SITE_KEY } from "${toLib}/studio";
+${withExperiments ? `import { getRunningExperiments } from "${toLib}/content";\n` : ""}
+// Built per request so the env is read at request time, not frozen at load.
+export function POST(request: Request): Promise<Response> {
+  return createCollectHandler({
+    siteKey: SITE_KEY,
+    ingestUrl: process.env.FUNNEL_INGEST_URL ?? "",
+    ingestKey: process.env.FUNNEL_INGEST_TOKEN ?? "",${withExperiments ? "\n    getRunningExperiments," : ""}
+  })(request);
+}
+`;
+
+export const frameAncestorsTestTs = () => `${HEADER}import { describe, expect, it } from "vitest";
+import nextConfig from "../next.config";
+
+type Rule = { source: string; headers: { key: string; value: string }[] };
+
+// Studio's click-to-edit frames this site's real pages. If this header is
+// lost, editing silently turns into a grey box in Studio while the site and its
+// build stay green. This test is what makes that loud.
+describe("Studio can frame this site, and nothing else can", () => {
+  it("every page sends frame-ancestors 'self' plus Studio, and no X-Frame-Options", async () => {
+    const config = nextConfig as unknown as { headers?: () => Promise<Rule[]> };
+    const rules = (await config.headers?.()) ?? [];
+    const all = rules.find((r) => r.source === "/:path*");
+    const csp = all?.headers.find((h) => h.key.toLowerCase() === "content-security-policy")?.value ?? "";
+    const frameAncestors = csp.split(";").map((p) => p.trim()).find((p) => p.startsWith("frame-ancestors")) ?? "";
+    expect(frameAncestors).toMatch(/^frame-ancestors 'self' https:\\/\\/studio\\.webmymoney\\.com/);
+    expect(frameAncestors).not.toContain("*");
+    for (const r of rules) for (const h of r.headers) expect(h.key.toLowerCase()).not.toBe("x-frame-options");
+  });
+});
+`;