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

package/README.md

@@ -1,88 +1,111 @@
-# @web-my-money/studio-consumer
-
-Consumer-side integration for WMM Studio: content, analytics, attribution.
-
-This is a source-only workspace package — no build step, no `dist`. Consumers
-are Next.js apps that already transpile workspace and scoped packages, so
-publishing compiled output here would only add a compile-and-publish cycle
-for no gain.
-
-## Entry points
-
-- `@web-my-money/studio-consumer/analytics`
-- `@web-my-money/studio-consumer/content`
-- `@web-my-money/studio-consumer/attribution`
-- `@web-my-money/studio-consumer/headers`
-- `@web-my-money/studio-consumer/brand` (2.0.0)
-- `@web-my-money/studio-consumer/image` (2.1.0)
-
-Each entry point exports `PACKAGE_VERSION`, to prove at runtime that a consumer
-is resolving this package rather than a stale copy.
-
-## Brand (2.0.0, breaking)
-
-A site declares its brand theme in code. Every invalid input throws, and this
-runs while the root layout renders, so a site with no brand, a malformed theme
-id, or WMM's own theme fails its build instead of silently inheriting WMM's
-palette.
-
-```ts
-// lib/brand.ts — its own module: Next refuses unknown named exports from a layout file
-import { defineSiteBrand } from "@web-my-money/studio-consumer/brand";
-
-export const brand = defineSiteBrand({ theme: "acme", style: "flat" });
-```
-
-```tsx
-// app/layout.tsx
-import { brandRootAttributes } from "@web-my-money/studio-consumer/brand";
-import { brand } from "@/lib/brand";
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return <html lang="en" {...brandRootAttributes(brand)}><body>{children}</body></html>;
-}
-```
-
-```ts
-// app/api/content/manifest/route.ts
-import { brand } from "@/lib/brand";
-
-export const GET = createManifestHandler(getManifest, brand);
-export const dynamic = "force-dynamic";
-```
-
-`createManifestHandler` now REQUIRES the brand (the breaking change in 2.0.0), so
-Studio records the theme the site ships. Only a WMM site may use a WMM theme
-(`wmm`, `site`, `light`, `dark`), by passing `wmmSite: true`.
-
-## Image focal point (2.1.0)
-
-An image value edited in Studio can carry `focal: { x, y }` (0–1 from the
-top-left): where the subject is. Apply it so responsive crops keep the subject
-in frame. No focal point, or a malformed one, reads as the centre, which is the
-browser default, so existing images render exactly as before.
-
-```tsx
-import { focalObjectPosition } from "@web-my-money/studio-consumer/image";
-
-<img src={value.url} alt={value.alt.en} style={{ objectFit: "cover", objectPosition: focalObjectPosition(value) }} />
-```
-
-## Analytics collector (2.2.0)
-
-`createCollectHandler` only accepts posts from the site's own pages (`Sec-Fetch-Site`,
-falling back to `Origin`), and it decides each event's A/B arm on the server from the
-`wmm_vid` cookie. The browser's own `variant` is always discarded. Pass the content
-client's `getRunningExperiments` so the arm can be resolved:
-
-```ts
-export const POST = createCollectHandler({
-  siteKey: SITE_KEY,
-  ingestUrl: process.env.FUNNEL_INGEST_URL ?? "",
-  ingestKey: process.env.FUNNEL_INGEST_TOKEN ?? "",
-  getRunningExperiments: () => content.getRunningExperiments(),
-});
-```
-
-Without it, events carry no arm and the site stays out of any A/B comparison.
-
+# @web-my-money/studio-consumer
+
+Consumer-side integration for WMM Studio: content, analytics, attribution.
+
+This is a source-only workspace package — no build step, no `dist`. Consumers
+are Next.js apps that already transpile workspace and scoped packages, so
+publishing compiled output here would only add a compile-and-publish cycle
+for no gain.
+
+## Connect a site: one command (2.3.0; new sites 2.4.0)
+
+In Studio, open the site, Site settings, **Get the setup command**, then in the
+app's folder (or, for a brand-new site, in an empty folder):
+
+```bash
+npx @web-my-money/studio-consumer init <code>
+```
+
+It checks the machine, installs this package, writes the routes, wraps
+`next.config` with `withStudio`, links Vercel and sets the env vars, opens Claude
+Code (the `onboard-site` skill shipped here) to wire the layout and choose the
+editable text, verifies, opens a pull request, waits for the deploy and asks
+Studio to sync. Rerun it after any stop; it resumes. `init --explain` shows the
+plan without changing anything.
+
+In an empty folder (2.4.0) it first creates the client's private repository from
+`Web-My-Money/wmm-site-template`, pulls it in and puts the site's key and name in
+place of the template's markers; the Claude step then sets the client's colours
+and first copy instead of wiring a layout.
+
+## Entry points
+
+- `@web-my-money/studio-consumer/analytics`
+- `@web-my-money/studio-consumer/content`
+- `@web-my-money/studio-consumer/attribution`
+- `@web-my-money/studio-consumer/headers`
+- `@web-my-money/studio-consumer/brand` (2.0.0)
+- `@web-my-money/studio-consumer/image` (2.1.0)
+- `@web-my-money/studio-consumer/next` (2.3.0): `withStudio(nextConfig)`
+
+Each entry point exports `PACKAGE_VERSION`, to prove at runtime that a consumer
+is resolving this package rather than a stale copy.
+
+## Brand (2.0.0, breaking)
+
+A site declares its brand theme in code. Every invalid input throws, and this
+runs while the root layout renders, so a site with no brand, a malformed theme
+id, or WMM's own theme fails its build instead of silently inheriting WMM's
+palette.
+
+```ts
+// lib/brand.ts — its own module: Next refuses unknown named exports from a layout file
+import { defineSiteBrand } from "@web-my-money/studio-consumer/brand";
+
+export const brand = defineSiteBrand({ theme: "acme", style: "flat" });
+```
+
+```tsx
+// app/layout.tsx
+import { brandRootAttributes } from "@web-my-money/studio-consumer/brand";
+import { brand } from "@/lib/brand";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return <html lang="en" {...brandRootAttributes(brand)}><body>{children}</body></html>;
+}
+```
+
+```ts
+// app/api/content/manifest/route.ts
+import { brand } from "@/lib/brand";
+
+export const GET = createManifestHandler(getManifest, brand);
+// No `export const dynamic` (2.3.0+): the handler waits for a real request, so the
+// manifest is always live, and cacheComponents apps refuse that export anyway.
+```
+
+`createManifestHandler` now REQUIRES the brand (the breaking change in 2.0.0), so
+Studio records the theme the site ships. Only a WMM site may use a WMM theme
+(`wmm`, `site`, `light`, `dark`), by passing `wmmSite: true`.
+
+## Image focal point (2.1.0)
+
+An image value edited in Studio can carry `focal: { x, y }` (0–1 from the
+top-left): where the subject is. Apply it so responsive crops keep the subject
+in frame. No focal point, or a malformed one, reads as the centre, which is the
+browser default, so existing images render exactly as before.
+
+```tsx
+import { focalObjectPosition } from "@web-my-money/studio-consumer/image";
+
+<img src={value.url} alt={value.alt.en} style={{ objectFit: "cover", objectPosition: focalObjectPosition(value) }} />
+```
+
+## Analytics collector (2.2.0)
+
+`createCollectHandler` only accepts posts from the site's own pages (`Sec-Fetch-Site`,
+falling back to `Origin`), and it decides each event's A/B arm on the server from the
+`wmm_vid` cookie. The browser's own `variant` is always discarded. Pass the content
+client's `getRunningExperiments` so the arm can be resolved:
+
+```ts
+export const POST = createCollectHandler({
+  siteKey: SITE_KEY,
+  ingestUrl: process.env.FUNNEL_INGEST_URL ?? "",
+  ingestKey: process.env.FUNNEL_INGEST_TOKEN ?? "",
+  getRunningExperiments: () => content.getRunningExperiments(),
+});
+```
+
+Without it, events carry no arm and the site stays out of any A/B comparison.
+

package/bin/studio-consumer.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// @ts-check
+
+/**
+ * `npx @web-my-money/studio-consumer <command>`. Plain ESM: Node will not strip
+ * TypeScript inside node_modules, so nothing on this path may be `.ts`.
+ */
+
+const USAGE = `Usage:
+  npx @web-my-money/studio-consumer init <code>     Connect this app to WMM Studio, step by step.
+  npx @web-my-money/studio-consumer init            Continue where the last run stopped.
+  npx @web-my-money/studio-consumer init --explain  Show every step without changing anything.
+
+Get <code> in Studio: open the site, Site settings, Get the setup command.`;
+
+const [command, ...rest] = process.argv.slice(2);
+
+if (!command || command === "--help" || command === "-h" || command === "help") {
+  process.stdout.write(`${USAGE}\n`);
+  process.exit(0);
+}
+
+if (command !== "init") {
+  process.stderr.write(`Unknown command "${command}".\n\n${USAGE}\n`);
+  process.exit(1);
+}
+
+const { runInit } = await import("../cli/init.mjs");
+process.exitCode = await runInit(rest);

package/cli/claude-step.mjs

@@ -0,0 +1,48 @@
+// @ts-check
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Step 8 of `init`: the edits that need judgement on someone else's code (root
+ * layout, proxy/middleware, which text is editable) are done by Claude Code, on
+ * the developer's own subscription, through the `onboard-site` skill this
+ * package ships. Each edit is shown and approved before it is written.
+ */
+
+/** @typedef {import("./run.mjs").Runner} Runner */
+/** @typedef {import("./ui.mjs").Ui} Ui */
+
+const SKILL_SOURCE = fileURLToPath(new URL("../skills/onboard-site/SKILL.md", import.meta.url));
+
+/**
+ * @param {{ cwd: string, run: Runner, ui: Ui }} ctx
+ */
+export async function claudeStep({ cwd, run, ui }) {
+  const target = path.join(cwd, ".claude", "skills", "onboard-site", "SKILL.md");
+  const source = readFileSync(SKILL_SOURCE, "utf8");
+  if (!existsSync(target) || readFileSync(target, "utf8") !== source) {
+    mkdirSync(path.dirname(target), { recursive: true });
+    copyFileSync(SKILL_SOURCE, target);
+  }
+
+  const version = await run("claude", ["--version"], { cwd });
+  if (version.code !== 0) {
+    ui.stop(
+      "This step needs Claude Code, to wire your layout and choose the editable text with you. Install it, then run this command again; it continues from here.",
+      "Install Claude Code from https://claude.com/claude-code",
+    );
+  }
+
+  ui.info("Opening Claude Code. It will show each change and wait for your yes.");
+  ui.info("When it says it is done, type /exit and this command carries on.");
+  if (ui.explain) return;
+  // Claude Code owns the terminal while it runs: the setup stops reading input,
+  // or keystrokes would be split between the two and replayed later as answers.
+  ui.pause();
+  try {
+    await run("claude", ["/onboard-site"], { cwd, inherit: true });
+  } finally {
+    ui.resume();
+  }
+}