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

package/cli/ui.mjs

@@ -0,0 +1,126 @@
+// @ts-check
+import { createInterface } from "node:readline";
+import { Writable } from "node:stream";
+
+/**
+ * How the onboarding command talks to a developer who has never done this
+ * (spec 2026-10-09 §3.0): numbered steps with one plain sentence each, a
+ * recommended default on every question, and every stop ending in the exact
+ * next command. `explain` mode answers no to everything and asks nothing.
+ */
+
+export class StopError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} [nextCommand]
+   */
+  constructor(message, nextCommand) {
+    super(message);
+    this.name = "StopError";
+    this.nextCommand = nextCommand;
+  }
+}
+
+/**
+ * @param {{ input: NodeJS.ReadableStream, output: NodeJS.WritableStream, explain?: boolean }} io
+ */
+export function createUi({ input, output, explain = false }) {
+  /** @type {string[]} */
+  const queued = [];
+  /** @type {((line: string) => void)[]} */
+  const waiting = [];
+  // Lines are read without echo from readline; a hidden answer is simply not
+  // written back. Interactive terminals echo typed characters themselves, so
+  // askSecret also turns raw mode on when it can.
+  const sink = new Writable({
+    write(_chunk, _enc, cb) {
+      cb();
+    },
+  });
+  const rl = createInterface({ input, output: sink, terminal: false });
+  rl.on("line", (line) => {
+    const next = waiting.shift();
+    if (next) next(line);
+    else queued.push(line);
+  });
+
+  /** @returns {Promise<string>} */
+  const readLine = () =>
+    new Promise((resolve) => {
+      const line = queued.shift();
+      if (line !== undefined) resolve(line);
+      else waiting.push(resolve);
+    });
+
+  /** @param {string} s */
+  const say = (s) => output.write(`${s}\n`);
+
+  return {
+    explain,
+    /** @param {number} n @param {number} total @param {string} title @param {string} why */
+    step(n, total, title, why) {
+      say("");
+      say(`Step ${n} of ${total}: ${title}`);
+      say(`  ${why}`);
+    },
+    /** @param {string} s */
+    info(s) {
+      say(`  ${s}`);
+    },
+    /** @param {string} question @param {string} def */
+    async ask(question, def) {
+      if (explain) return def;
+      output.write(`  ${question} (${def}): `);
+      const answer = (await readLine()).trim();
+      return answer === "" ? def : answer;
+    },
+    /** @param {string} question */
+    async askSecret(question) {
+      output.write(`  ${question} (it will not show as you paste): `);
+      const tty = /** @type {NodeJS.ReadStream} */ (input);
+      const canHide = typeof tty.setRawMode === "function" && tty.isTTY;
+      if (canHide) tty.setRawMode(true);
+      try {
+        const line = await readLine();
+        // In raw mode Ctrl+C arrives as a character instead of stopping the
+        // program; honour it.
+        if (line.includes("\u0003")) {
+          throw new StopError("Stopped. Run this again whenever you are ready; it continues from here.");
+        }
+        return line.trim();
+      } finally {
+        if (canHide) tty.setRawMode(false);
+        output.write("\n");
+      }
+    },
+    /** @param {string} question @param {boolean} [defYes] */
+    async confirm(question, defYes = true) {
+      if (explain) {
+        say(`  Would ask: ${question}`);
+        return false;
+      }
+      output.write(`  ${question} ${defYes ? "[Y/n]" : "[y/N]"}: `);
+      const a = (await readLine()).trim().toLowerCase();
+      if (a === "") return defYes;
+      return a === "y" || a === "yes";
+    },
+    /** @param {string} message @param {string} [nextCommand] @returns {never} */
+    stop(message, nextCommand) {
+      throw new StopError(message, nextCommand);
+    },
+    /** Hand the terminal to a child process (Claude Code, the app's checks). */
+    pause() {
+      rl.pause();
+      input.pause();
+    },
+    /** Take the terminal back after the child exits. */
+    resume() {
+      rl.resume();
+    },
+    close() {
+      rl.close();
+    },
+  };
+}
+
+/** @typedef {ReturnType<typeof createUi>} Ui */

package/cli/writers.mjs

@@ -0,0 +1,148 @@
+// @ts-check
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import * as t from "./templates.mjs";
+
+/**
+ * The mechanical edits `init` makes (stage 2 plan, Task 4). Every writer is
+ * idempotent and never overwrites a file the app already has with different
+ * content: it reports it instead, so nothing the developer wrote is lost. The
+ * edits that need judgement (root layout, proxy, the content model) are left to
+ * the Claude Code step.
+ */
+
+/**
+ * @typedef {{ siteKey: string, theme: string, style: "flat" | "glass" }} SiteValues
+ * @typedef {{ written: string[], skipped: { path: string, reason: string }[] }} WriteReport
+ */
+
+/** @param {string} cwd */
+function codeRoot(cwd) {
+  return existsSync(path.join(cwd, "src", "app")) ? "src" : ".";
+}
+
+/** @param {string} cwd */
+function hasTestRunner(cwd) {
+  try {
+    const pkg = JSON.parse(readFileSync(path.join(cwd, "package.json"), "utf8"));
+    const all = { ...pkg.dependencies, ...pkg.devDependencies };
+    return "vitest" in all || "jest" in all;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {{ cwd: string, values: SiteValues, modules: string[] }} ctx
+ * @returns {Promise<WriteReport>}
+ */
+export async function writeSiteFiles({ cwd, values, modules }) {
+  const root = codeRoot(cwd);
+  const content = modules.includes("content");
+  const analytics = modules.includes("analytics");
+  // From app/api/<group>/<name>/route.ts back up to the code root's lib/.
+  const toLib = "../../../../lib";
+
+  /** @type {[string, string, { keepExisting?: boolean }?][]} */
+  const files = [];
+  const at = (/** @type {string} */ p) => (root === "." ? p : `${root}/${p}`);
+  if (content || analytics) files.push([at("lib/studio.ts"), t.studioTs(values)]);
+  if (content) {
+    files.push([at("lib/brand.ts"), t.brandTs(values)]);
+    files.push([at("lib/content-manifest.ts"), t.contentManifestTs(), { keepExisting: true }]);
+    files.push([at("lib/content.ts"), t.contentTs()]);
+    files.push([at("app/api/content/manifest/route.ts"), t.manifestRouteTs(toLib)]);
+    files.push([at("app/api/content/revalidate/route.ts"), t.revalidateRouteTs()]);
+  }
+  if (analytics) files.push([at("app/api/analytics/collect/route.ts"), t.collectRouteTs(toLib, content)]);
+
+  /** @type {WriteReport} */
+  const report = { written: [], skipped: [] };
+
+  if (content) {
+    if (hasTestRunner(cwd)) files.push(["tests/studio-frame-ancestors.test.ts", t.frameAncestorsTestTs()]);
+    else {
+      report.skipped.push({
+        path: "tests/studio-frame-ancestors.test.ts",
+        reason: "this app has no test runner yet; the Claude Code step can add Vitest and this test",
+      });
+    }
+  }
+
+  for (const [rel, body, opts] of files) {
+    const abs = path.join(cwd, rel);
+    if (existsSync(abs)) {
+      const current = readFileSync(abs, "utf8");
+      if (current === body || opts?.keepExisting) continue;
+      report.skipped.push({ path: rel, reason: "already exists with different content; merge the Studio version by hand" });
+      continue;
+    }
+    mkdirSync(path.dirname(abs), { recursive: true });
+    writeFileSync(abs, body);
+    report.written.push(rel);
+  }
+  return report;
+}
+
+const IMPORT_LINE = 'import { withStudio } from "@web-my-money/studio-consumer/next";';
+const CONFIG_NAMES = ["next.config.ts", "next.config.mjs", "next.config.js"];
+
+/**
+ * Wrap the app's next.config with withStudio. Recognises the two shapes nearly
+ * every config has (`export default name;` and `export default { … };`); any
+ * other shape is left untouched and the exact edit is returned instead.
+ *
+ * @param {{ cwd: string }} ctx
+ * @returns {Promise<"wrapped" | "already" | { manual: string }>}
+ */
+export async function wrapNextConfig({ cwd }) {
+  const name = CONFIG_NAMES.find((n) => existsSync(path.join(cwd, n)));
+  if (!name) {
+    writeFileSync(path.join(cwd, "next.config.mjs"), `${IMPORT_LINE}\n\nexport default withStudio({});\n`);
+    return "wrapped";
+  }
+  const file = path.join(cwd, name);
+  const src = readFileSync(file, "utf8");
+  if (src.includes("withStudio(")) return "already";
+
+  const manual = {
+    manual:
+      `Edit ${name} by hand: add\n  ${IMPORT_LINE}\nat the top, and wrap the exported config: export default withStudio(yourConfig);`,
+  };
+
+  let out = null;
+  const named = /^export default ([A-Za-z_$][\w$]*);[ \t]*$/m;
+  if (named.test(src)) {
+    out = src.replace(named, "export default withStudio($1);");
+  } else if (/^export default \{/m.test(src)) {
+    const start = src.search(/^export default \{/m);
+    const open = start + "export default ".length;
+    // Find the brace that closes the exported object. Only wrap when that object
+    // is the last thing in the file: a brace inside a string, or code after the
+    // export, makes the match uncertain, and a wrong splice breaks the config.
+    let depth = 0;
+    let close = -1;
+    for (let i = open; i < src.length; i++) {
+      if (src[i] === "{") depth++;
+      else if (src[i] === "}" && --depth === 0) {
+        close = i;
+        break;
+      }
+    }
+    const rest = close === -1 ? "x" : src.slice(close + 1).replace(/^;/, "");
+    if (close !== -1 && rest.trim() === "") {
+      out = `${src.slice(0, start)}export default withStudio(${src.slice(open, close + 1)});${rest}`;
+    }
+  }
+  if (!out) return manual;
+
+  // The import goes after the last existing import, or at the very top.
+  const lines = out.split("\n");
+  let last = -1;
+  lines.forEach((l, i) => {
+    if (/^import\s/.test(l)) last = i;
+  });
+  lines.splice(last + 1, 0, IMPORT_LINE);
+  writeFileSync(file, lines.join("\n"));
+  return "wrapped";
+}

package/package.json

@@ -1,29 +1,33 @@
-{
-  "name": "@web-my-money/studio-consumer",
-  "version": "2.2.0",
-  "description": "Consumer-side integration for WMM Studio: content, analytics, attribution.",
-  "license": "UNLICENSED",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Web-My-Money/wmm-studio.git",
-    "directory": "packages/studio-consumer"
-  },
-  "type": "module",
-  "sideEffects": false,
-  "publishConfig": {
-    "access": "public"
-  },
-  "exports": {
-    "./analytics": "./src/analytics/index.ts",
-    "./content": "./src/content/index.ts",
-    "./attribution": "./src/attribution/index.ts",
-    "./headers": "./src/content/headers.mjs",
-    "./brand": "./src/brand/index.ts",
-    "./image": "./src/image/index.ts"
-  },
-  "peerDependencies": {
-    "next": ">=16",
-    "react": ">=19"
-  },
-  "files": ["src"]
-}
+{
+  "name": "@web-my-money/studio-consumer",
+  "version": "2.4.0",
+  "description": "Consumer-side integration for WMM Studio: content, analytics, attribution.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Web-My-Money/wmm-studio.git",
+    "directory": "packages/studio-consumer"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./analytics": "./src/analytics/index.ts",
+    "./content": "./src/content/index.ts",
+    "./attribution": "./src/attribution/index.ts",
+    "./headers": "./src/content/headers.mjs",
+    "./brand": "./src/brand/index.ts",
+    "./image": "./src/image/index.ts",
+    "./next": "./src/next/index.mjs"
+  },
+  "peerDependencies": {
+    "next": ">=16",
+    "react": ">=19"
+  },
+  "bin": {
+    "studio-consumer": "./bin/studio-consumer.mjs"
+  },
+  "files": ["src", "bin", "cli", "skills"]
+}

package/skills/onboard-site/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: onboard-site
+description: Finish connecting this Next.js app to WMM Studio after `npx @web-my-money/studio-consumer init` has run. Wires the root layout and the proxy/middleware, then proposes which text should be editable in Studio and writes the content manifest once the developer approves. For a new site made from WMM's template, sets the client's colours and first copy instead. Use when the init command opens Claude Code on /onboard-site.
+---
+
+# Finish connecting this app to WMM Studio
+
+The `init` command already did the mechanical part: it installed
+`@web-my-money/studio-consumer`, wrapped `next.config` with `withStudio`, and wrote
+`lib/studio.ts` (the site key), `lib/brand.ts`, `lib/content.ts`, a starter
+`lib/content-manifest.ts` and the API routes under `app/api/`. (In a `src/` app all of
+these live under `src/`.) Your job is the part that needs judgement on someone else's
+code.
+
+**The developer may never have seen Studio before.** Explain each change in one plain
+sentence, show the diff, and wait for a yes before writing it. Never rewrite a file
+wholesale; make the smallest edit that does the job. Never remove an existing redirect,
+rewrite, header or script.
+
+Read `.wmm-onboarding/state.json` first: it lists the modules this site uses
+(`content`, `analytics`, `forms`, `attribution`, `ab`, …). Skip anything for a module
+that is not listed.
+
+## 0. A new site from WMM's template (`"mode": "new"` in state.json)
+
+The site was just created from `Web-My-Money/wmm-site-template`, so sections 1 and 2 are
+already done: the layout (`app/[lang]/layout.tsx`) has the brand attributes, the editor
+overlay and analytics, and `proxy.ts` sets the visitor cookie. Check they are there, say so in
+one line, and skip to the client's details. Read `CLAUDE.md` for the site's rules.
+
+1. Ask the developer, one question at a time:
+   - the business name exactly as the client writes it, and one sentence on what they do and
+     for whom;
+   - the brand's primary and accent colours as hex codes (from the client's logo or brand
+     guide; "not yet" is a fine answer: leave the magenta placeholder and say so);
+   - which language visitors should land in by default (English or Spanish);
+   - where the main button should go (the client's booking calendar or form link), if known.
+2. Then propose, as one diff per file, and write only after a yes:
+   - `app/client-theme.css`: the colours (`--primary`, `--accent`, and a readable
+     `--primary-foreground`: white on a dark primary, near-black on a light one);
+   - `dictionaries/en.json` and `es.json`: `meta`, `hero` and `services` from what the
+     developer told you, in both languages (Spanish neutral, no regional slang). Keep every
+     key; the two files must keep identical keys;
+   - `lib/i18n.ts`: `DEFAULT_LOCALE`, only if it changes;
+   - the main button's link in `app/[lang]/page.tsx` (the `TODO` on the closing banner).
+3. **Never invent reviews, results, prices or credentials.** Leave the review placeholders
+   and the FAQ answers you do not know, and list them as "still needed from the client".
+4. Section 3 below is a review here, not a rebuild: `lib/content-manifest.ts` already makes
+   the home page's marketing text editable. Show the list of slots, ask whether anything should
+   be added or removed, and change it only on a yes.
+5. Go to section 4.
+
+## 1. Root layout (`app/layout.tsx`, or the layout that renders `<html>`)
+
+- **Brand (content):** `import { brandRootAttributes } from "@web-my-money/studio-consumer/brand";`
+  and `import { brand } from "<relative path>/lib/brand";`, then spread
+  `{...brandRootAttributes(brand)}` on `<html>`. Keep every attribute already there.
+- **Click-to-edit (content):** render `<WmmEditOverlay studioOrigin={process.env.NEXT_PUBLIC_STUDIO_ORIGIN} />`
+  from `@web-my-money/studio-consumer/content` once, inside `<body>`.
+- **Analytics (analytics):** render `<FunnelAnalytics />` and `<EngagementTracking />` from
+  `@web-my-money/studio-consumer/analytics` once, inside `<body>`.
+- **Overrides (content):** wherever the app loads its dictionary for a locale (often a
+  `[lang]` layout or a `getDictionary` helper), pass it through
+  `await applyDictOverrides(dict, locale)` from `lib/content.ts` before rendering. This is
+  what makes an edit in Studio appear on the page; without it the checklist goes green
+  and edits never show. If the app has no dictionary, say so and use `getLocalizedSlot`
+  for each editable value in step 3 instead.
+
+## 2. Proxy / middleware (analytics)
+
+Studio's analytics and A/B testing need the `wmm_vid` visitor cookie, which
+`withVisitorCookie` from `@web-my-money/studio-consumer/analytics` sets.
+
+- Next 16 uses `proxy.ts` (older apps: `middleware.ts`), at the code root.
+- **None exists:** create `proxy.ts` that returns `withVisitorCookie(request)`, with a
+  matcher that skips `_next`, `api` and static files.
+- **One exists:** compose, never replace. Call `withVisitorCookie(request)` for the
+  pass-through case, and keep every existing redirect and rewrite exactly as it is. If the
+  existing code returns its own `NextResponse`, show the developer the two options (set
+  the cookie on that response, or call `withVisitorCookie` first) and let them choose.
+
+## 3. Choose the editable text (content)
+
+This is the real decision in the whole onboarding. **Do not decide it alone.**
+
+1. Find the copy: the per-locale dictionary (e.g. `dictionaries/en.json`, `es.json`), or,
+   if there is none, the text in the page components.
+2. Propose a table grouped by page and section, one row per candidate:
+
+   | Key | Current text (EN) | Editable? | Why |
+   |---|---|---|---|
+
+   Keys are `page.section.thing` (e.g. `home.hero.headline`). Give a one-line reason for
+   **every "no"**. Lean towards "no" for, and always justify:
+   - legal and compliance text (privacy, terms, disclaimers, medical or financial claims);
+   - form field names, validation and error messages;
+   - analytics, tracking and pixel ids;
+   - icons and component references (never editable);
+   - anything the code uses as an identifier, a route or a CSS class.
+   Lean towards "yes" for headlines, sub-headlines, body copy, calls to action, testimonials
+   and images a marketer would change.
+3. Wait for the developer to approve or edit the table.
+4. Then fill in `lib/content-manifest.ts`, keeping its `getManifest()` shape and the
+   `siteKey: SITE_KEY` it returns:
+   - a slot only for text the code actually renders;
+   - `type`: `text` (or `richtext`, `image`, `list`, `select` where that fits);
+   - `dictPath` for dictionary text (the override is merged into the dictionary, no
+     component changes needed); no `dictPath` for images or other non-dictionary values,
+     which are read with `getSlot` and passed down as props;
+   - `default` is read from the dictionary (`en`/`es` imports), **never retyped**, so it
+     cannot go stale;
+   - `label` in plain words a client understands ("Home: hero headline");
+   - `group` per page section, `sortOrder` in reading order.
+
+If `lib/content-manifest.ts` already had real slots before `init` ran, keep them and only
+add what the developer approves.
+
+## 4. Check, then hand back
+
+Run `npm run verify` (or the app's equivalent: typecheck, lint, test, build). Fix what it
+reports. If the app has no test runner and `tests/studio-frame-ancestors.test.ts` was not
+written, offer to add Vitest and that test.
+
+When everything passes, tell the developer in one sentence what changed, and that they can
+close Claude Code (type `/exit`) so the `init` command continues with the next step.

package/src/analytics/index.ts

@@ -1,37 +1,37 @@
-/** Proves at runtime which build a consumer is actually running. */
-export const PACKAGE_VERSION = "2.2.0";
-
-export {
-  resolveVariant,
-  bucketFor,
-  CONTROL,
-  VARIANT,
-  VISITOR_COOKIE,
-  type RunningExperiment,
-} from "./bucketing";
-
-export {
-  trackFunnelEvent,
-  registerExperiments,
-  flushFunnelEvents,
-  currentSessionId,
-  funnelAnalyticsEnabled,
-  consentGranted,
-  resetFunnelAnalytics,
-  type FunnelEventProps,
-} from "./collector";
-
-export { useFormAnalytics, type FormAnalytics, type FormAnalyticsOptions } from "./use-form-analytics";
-
-export {
-  FunnelAnalytics,
-  EngagementTracking,
-  AbArm,
-  THRESHOLDS,
-  crossedThresholds,
-  labelFor,
-} from "./components";
-
-export { createCollectHandler } from "./collect-handler";
-
-export { withVisitorCookie } from "./proxy";
+/** Proves at runtime which build a consumer is actually running. */
+export const PACKAGE_VERSION = "2.4.0";
+
+export {
+  resolveVariant,
+  bucketFor,
+  CONTROL,
+  VARIANT,
+  VISITOR_COOKIE,
+  type RunningExperiment,
+} from "./bucketing";
+
+export {
+  trackFunnelEvent,
+  registerExperiments,
+  flushFunnelEvents,
+  currentSessionId,
+  funnelAnalyticsEnabled,
+  consentGranted,
+  resetFunnelAnalytics,
+  type FunnelEventProps,
+} from "./collector";
+
+export { useFormAnalytics, type FormAnalytics, type FormAnalyticsOptions } from "./use-form-analytics";
+
+export {
+  FunnelAnalytics,
+  EngagementTracking,
+  AbArm,
+  THRESHOLDS,
+  crossedThresholds,
+  labelFor,
+} from "./components";
+
+export { createCollectHandler } from "./collect-handler";
+
+export { withVisitorCookie } from "./proxy";

package/src/attribution/index.ts

@@ -1,14 +1,14 @@
-/** Proves at runtime which build a consumer is actually running. */
-export const PACKAGE_VERSION = "2.2.0";
-
-export {
-  getAttribution,
-  captureAttribution,
-  getAttributionPayload,
-  computeAttribution,
-  flattenAttribution,
-  hasCampaignSignal,
-} from "./store";
-export type { Attribution, Touch, AttributionPayload } from "./store";
-
-export { sessionIdField, SESSION_ID_FIELD } from "./crm";
+/** Proves at runtime which build a consumer is actually running. */
+export const PACKAGE_VERSION = "2.4.0";
+
+export {
+  getAttribution,
+  captureAttribution,
+  getAttributionPayload,
+  computeAttribution,
+  flattenAttribution,
+  hasCampaignSignal,
+} from "./store";
+export type { Attribution, Touch, AttributionPayload } from "./store";
+
+export { sessionIdField, SESSION_ID_FIELD } from "./crm";