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

package/README.md

@@ -7,6 +7,22 @@ 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)
+
+In Studio, open the site, Site settings, **Get the setup command**, then in the
+app's 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.
+
 ## Entry points
 
 - `@web-my-money/studio-consumer/analytics`
@@ -15,6 +31,7 @@ for no gain.
 - `@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.
@@ -48,7 +65,8 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 import { brand } from "@/lib/brand";
 
 export const GET = createManifestHandler(getManifest, brand);
-export const dynamic = "force-dynamic";
+// 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

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 7 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();
+  }
+}

package/cli/init.mjs

@@ -0,0 +1,439 @@
+// @ts-check
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { createRunner } from "./run.mjs";
+import { createUi, StopError } from "./ui.mjs";
+import { loadState, saveState } from "./state.mjs";
+import { exchangeCode, markReady, requestKey } from "./studio-api.mjs";
+import { preflight } from "./preflight.mjs";
+import { cliProvisioner } from "./provisioner.mjs";
+import { writeSiteFiles, wrapNextConfig } from "./writers.mjs";
+import { claudeStep } from "./claude-step.mjs";
+
+/**
+ * `npx @web-my-money/studio-consumer init <code>`: connect an existing Next.js
+ * app to WMM Studio, one guided step at a time (spec 2026-10-09 §1, §3).
+ *
+ * Every step is resumable: progress is saved after each one, so a rerun picks up
+ * where the last run stopped. The ingest key lives only in memory for the run in
+ * which Studio hands it over, and goes straight into Vercel.
+ */
+
+/** @typedef {import("./run.mjs").Runner} Runner */
+/** @typedef {import("./ui.mjs").Ui} Ui */
+/** @typedef {import("./state.mjs").OnboardingState} OnboardingState */
+/** @typedef {import("./provisioner.mjs").Provisioner} AnyProvisioner */
+/** @typedef {(url: string, init?: RequestInit) => Promise<Response>} Fetch */
+
+const DEFAULT_STUDIO = "https://studio.webmymoney.com";
+const DEFAULT_SCOPE = "web-my-money-team";
+const TARGETS = /** @type {("production" | "preview")[]} */ (["production", "preview"]);
+const BRANCH = "studio-onboarding";
+const POLL_EVERY_MS = 10_000;
+const POLL_TIMES = 60;
+
+/**
+ * @typedef {{
+ *   cwd: string, ui: Ui, run: Runner, fetchImpl: Fetch, sleep: (ms: number) => Promise<void>,
+ *   studioUrl: string, code: string | null, state: OnboardingState | null,
+ *   provisioner: AnyProvisioner | null, provisionerScope?: string,
+ *   injectedProvisioner: AnyProvisioner | null,
+ * }} Ctx
+ */
+
+/** @type {{ id: string, title: string, why: string, run: (ctx: Ctx) => Promise<void> }[]} */
+const STEPS = [
+  {
+    id: "preflight",
+    title: "Check your setup",
+    why: "Makes sure Node, GitHub, Vercel and this app are ready before anything changes.",
+    async run(ctx) {
+      await preflight({ cwd: ctx.cwd, run: ctx.run, ui: ctx.ui, resuming: ctx.state !== null });
+    },
+  },
+  {
+    id: "connect",
+    title: "Connect to Studio",
+    why: "Uses your one-time code to fetch this site's settings from WMM Studio.",
+    async run(ctx) {
+      if (!ctx.code) {
+        if (ctx.state) return ctx.ui.info(`Continuing setup for ${ctx.state.siteName}.`);
+        ctx.ui.stop(
+          "This needs the one-time setup code from Studio.",
+          "In Studio: open the site, Site settings, Get the setup command, then run the command it shows.",
+        );
+      }
+      const r = await exchangeCode(ctx.studioUrl, /** @type {string} */ (ctx.code), ctx.fetchImpl);
+      if (!r.ok) return ctx.ui.stop(r.message);
+      const d = /** @type {Record<string, unknown>} */ (r.data);
+      const modules = Array.isArray(d.modules) ? d.modules.map(String) : [];
+      const before = ctx.state;
+      // A new code with different modules means the files, the settings and the
+      // layout work are redone for them. The writers are idempotent, so redoing
+      // them is safe.
+      let done = before?.done ?? [];
+      const changed = before !== null && [...modules].sort().join() !== [...before.modules].sort().join();
+      if (changed) done = done.filter((id) => !["files", "env", "claude"].includes(id));
+      ctx.state = {
+        ...(before ?? {}),
+        done,
+        siteKey: String(d.siteKey),
+        siteName: String(d.siteName ?? d.siteKey),
+        studioUrl: String(d.studioUrl ?? ctx.studioUrl),
+        manifestUrl: String(d.manifestUrl ?? ""),
+        revalidateUrl: String(d.revalidateUrl ?? ""),
+        modules,
+        siteHasKey: d.siteHasKey === true,
+        readyToken: String(d.readyToken),
+      };
+      ctx.ui.info(`Connected to ${ctx.state.siteName} (${ctx.state.siteKey}). Modules: ${ctx.state.modules.join(", ")}.`);
+    },
+  },
+  {
+    id: "install",
+    title: "Install the package",
+    why: "Adds WMM Studio's package to this app.",
+    async run(ctx) {
+      const r = await ctx.run("npm", ["install", "--install-links", "@web-my-money/studio-consumer@^2.3"], { cwd: ctx.cwd });
+      if (r.code !== 0) ctx.ui.stop("npm could not install the package.", "npm install --install-links @web-my-money/studio-consumer@^2.3");
+    },
+  },
+  {
+    id: "files",
+    title: "Add Studio's files",
+    why: "Writes the small files Studio talks to, and lets Studio show this site inside its editor.",
+    async run(ctx) {
+      const s = need(ctx);
+      if (s.modules.includes("content")) {
+        s.theme = await ctx.ui.ask(
+          "Brand theme id for this site (the client's theme in WMM's design system)",
+          s.theme ?? s.siteKey,
+        );
+      }
+      const report = await writeSiteFiles({
+        cwd: ctx.cwd,
+        values: { siteKey: s.siteKey, theme: s.theme ?? s.siteKey, style: "flat" },
+        modules: s.modules,
+      });
+      for (const f of report.written) ctx.ui.info(`Added ${f}`);
+      for (const f of report.skipped) ctx.ui.info(`Left ${f.path} alone: ${f.reason}.`);
+      const wrapped = await wrapNextConfig({ cwd: ctx.cwd });
+      if (wrapped === "wrapped") ctx.ui.info("Wrapped next.config with withStudio.");
+      else if (wrapped === "already") ctx.ui.info("next.config already uses withStudio.");
+      else ctx.ui.info(wrapped.manual);
+    },
+  },
+  {
+    id: "vercel",
+    title: "Connect Vercel",
+    why: "Links this folder to its Vercel project under the WMM team, so settings and deploys land in the right place.",
+    async run(ctx) {
+      const s = need(ctx);
+      s.scope = await ctx.ui.ask("Vercel team", s.scope ?? DEFAULT_SCOPE);
+      const p = provisioner(ctx);
+
+      // Vercel deploys from GitHub, so the app needs a repository first.
+      const origin = await ctx.run("git", ["remote", "get-url", "origin"], { cwd: ctx.cwd });
+      if (origin.code !== 0) {
+        const create = await ctx.ui.confirm(
+          `This app is not on GitHub yet. Create the private repository Web-My-Money/${s.siteKey} for it?`,
+        );
+        if (!create) {
+          ctx.ui.stop(
+            "Vercel needs the app on GitHub to deploy it. Create a repository, then run this again.",
+            `gh repo create Web-My-Money/${s.siteKey} --private --source . --remote origin`,
+          );
+        }
+        await p.createRepoFromSource(s.siteKey);
+        ctx.ui.info(`Created Web-My-Money/${s.siteKey}.`);
+      }
+
+      const ok = await ctx.ui.confirm(`Link this folder to the Vercel project "${s.siteKey}" in "${s.scope}"?`);
+      if (!ok) ctx.ui.stop("Setup needs a Vercel project. Run this again when you are ready to link it.");
+      await p.linkVercel(s.siteKey);
+      ctx.ui.info(`Linked to the Vercel project "${s.siteKey}" (${s.scope}).`);
+    },
+  },
+  {
+    id: "env",
+    title: "Set environment variables",
+    why: "Tells the site where Studio is and gives it its private analytics key. The key goes straight to Vercel and is never shown.",
+    async run(ctx) {
+      const s = need(ctx);
+      const p = provisioner(ctx);
+      /** @type {[string, string][]} */
+      const plain = [];
+      if (s.modules.includes("content")) {
+        plain.push(["STUDIO_CONTENT_URL", s.studioUrl], ["NEXT_PUBLIC_STUDIO_ORIGIN", s.studioUrl]);
+      }
+      if (s.modules.includes("analytics")) plain.push(["NEXT_PUBLIC_FUNNEL_ANALYTICS", "1"]);
+      for (const [name, value] of plain) {
+        if (await p.hasEnv(name)) ctx.ui.info(`${name} is already set; kept.`);
+        else {
+          await p.setEnv(name, value, TARGETS);
+          ctx.ui.info(`Set ${name}.`);
+        }
+      }
+      if (!s.modules.includes("analytics")) return;
+
+      const has = await p.hasEnv("FUNNEL_INGEST_TOKEN");
+      if (!s.siteHasKey) {
+        // A new site: Studio creates its key now, at the moment it is saved to
+        // Vercel, so an earlier stop cannot lose it.
+        if (has) {
+          const replace = await ctx.ui.confirm(
+            "FUNNEL_INGEST_TOKEN is already set on Vercel, but this site gets a new key from Studio. Replace the old value (recommended)?",
+          );
+          if (!replace) return ctx.ui.info("Kept the existing FUNNEL_INGEST_TOKEN. Analytics only work if it matches Studio's key.");
+        }
+        const key = await requestKey(s.studioUrl, s.readyToken, ctx.fetchImpl);
+        if (key.ok) {
+          await p.setEnv("FUNNEL_INGEST_TOKEN", key.ingestKey, TARGETS, { sensitive: true, force: has });
+          return ctx.ui.info("Set FUNNEL_INGEST_TOKEN (this site's analytics key).");
+        }
+        if (!key.inUse) return ctx.ui.stop(key.message);
+      } else if (has) {
+        return ctx.ui.info("FUNNEL_INGEST_TOKEN is already set; kept.");
+      }
+
+      ctx.ui.info("This site already has an analytics key in Studio, so Studio will not create another one.");
+      ctx.ui.info(`Get a fresh one: in Studio open ${s.siteName}, Site settings, Rotate key, and copy the key it shows.`);
+      const pasted = await ctx.ui.askSecret("Paste the key");
+      if (!/^wmmk_[A-Za-z0-9_-]{20,}$/.test(pasted)) {
+        ctx.ui.stop("That does not look like a Studio analytics key (it starts with wmmk_). Run this again and paste it once more.");
+      }
+      await p.setEnv("FUNNEL_INGEST_TOKEN", pasted, TARGETS, { sensitive: true });
+      ctx.ui.info("Set FUNNEL_INGEST_TOKEN.");
+    },
+  },
+  {
+    id: "claude",
+    title: "Wire the layout and choose the editable text",
+    why: "Claude Code reads your app, shows each change it suggests, and writes it only after your yes.",
+    async run(ctx) {
+      await claudeStep({ cwd: ctx.cwd, run: ctx.run, ui: ctx.ui });
+    },
+  },
+  {
+    id: "verify",
+    title: "Check everything",
+    why: "Runs the app's checks and build, so nothing broken gets deployed.",
+    async run(ctx) {
+      const pkg = JSON.parse(readFileSync(path.join(ctx.cwd, "package.json"), "utf8"));
+      const script = pkg.scripts?.verify ? "verify" : "build";
+      // The terminal belongs to the checks while they run.
+      ctx.ui.pause();
+      const r = await ctx.run("npm", ["run", script], { cwd: ctx.cwd, inherit: true }).finally(() => ctx.ui.resume());
+      if (r.code !== 0) {
+        ctx.ui.stop(
+          `\`npm run ${script}\` failed. Fix what it reported (Claude Code can help: run \`claude\` here), then run this again; it continues from this step.`,
+          `npm run ${script}`,
+        );
+      }
+    },
+  },
+  {
+    id: "publish",
+    title: "Publish",
+    why: "Puts these changes on their own branch and opens a pull request for you to merge.",
+    async run(ctx) {
+      const ok = await ctx.ui.confirm(`Commit everything on a new branch "${BRANCH}", push it and open a pull request?`);
+      if (!ok) {
+        ctx.ui.stop("Commit, push and deploy these changes your usual way, then run this again; it will wait for the site.");
+      }
+      // Every part is safe to rerun: an existing branch is reused, an empty
+      // commit is skipped, an open pull request is kept.
+      const s = need(ctx);
+      const head = await ctx.run("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: ctx.cwd });
+      // The branch the pull request goes into: the one the app was on before
+      // this step, remembered so a rerun (already on the onboarding branch)
+      // still knows it.
+      if (!s.baseBranch) {
+        const current = head.stdout.trim();
+        s.baseBranch = current && current !== BRANCH && current !== "HEAD" ? current : "main";
+        saveState(ctx.cwd, s);
+      }
+      const base = s.baseBranch;
+      // A repository this command just created has nothing on GitHub yet. Push
+      // the base first, so it becomes the default branch and the pull request
+      // has something to go into. (Found in the real end-to-end run.)
+      const remoteBase = await ctx.run("git", ["ls-remote", "--heads", "origin", base], { cwd: ctx.cwd });
+      if (remoteBase.code === 0 && remoteBase.stdout.trim() === "" && head.stdout.trim() === base) {
+        await must(ctx, "git", ["push", "-u", "origin", base]);
+      }
+      if (head.stdout.trim() !== BRANCH) {
+        const exists = await ctx.run("git", ["rev-parse", "--verify", "--quiet", BRANCH], { cwd: ctx.cwd });
+        await must(ctx, "git", exists.code === 0 ? ["checkout", BRANCH] : ["checkout", "-b", BRANCH]);
+      }
+      await must(ctx, "git", ["add", "-A"]);
+      // Secrets and machine-local settings never go into the commit, even in an
+      // app whose .gitignore does not cover them.
+      const staged = await ctx.run("git", ["diff", "--cached", "--name-only"], { cwd: ctx.cwd });
+      const files = staged.stdout.split(/\r?\n/).map((f) => f.trim()).filter(Boolean);
+      for (const f of files.filter(isPrivateFile)) {
+        await must(ctx, "git", ["reset", "-q", "--", f]);
+        ctx.ui.info(`Left ${f} out of the commit (it holds secrets or local settings).`);
+      }
+      if (files.some((f) => !isPrivateFile(f))) {
+        await must(ctx, "git", ["commit", "-m", "Connect this site to WMM Studio"]);
+      } else {
+        ctx.ui.info("Nothing new to commit.");
+      }
+      await must(ctx, "git", ["push", "-u", "origin", BRANCH]);
+      const pr = await ctx.run("gh", ["pr", "list", "--head", BRANCH, "--json", "number"], { cwd: ctx.cwd });
+      const open = pr.code === 0 && pr.stdout.trim() !== "" && pr.stdout.trim() !== "[]";
+      if (open) ctx.ui.info("The pull request is already open.");
+      else await must(ctx, "gh", ["pr", "create", "--fill", "--base", base, "--head", BRANCH]);
+      ctx.ui.info("Merge the pull request (or deploy your usual way); the next step waits for the live site.");
+    },
+  },
+  {
+    id: "wait",
+    title: "Wait for the site",
+    why: "Watches the live site until it answers Studio, so the sync in the last step sees the new code.",
+    async run(ctx) {
+      const s = need(ctx);
+      if (!s.manifestUrl) {
+        ctx.ui.stop(
+          `Studio has no address for ${s.siteName} yet. In Studio open the site, Site settings, set its manifest URL (https://<domain>/api/content/manifest), then run this again.`,
+        );
+      }
+      for (let i = 0; i < POLL_TIMES; i++) {
+        try {
+          const res = await ctx.fetchImpl(s.manifestUrl, { cache: "no-store" });
+          if (res.ok) {
+            const body = /** @type {{ siteKey?: unknown }} */ (await res.json());
+            if (body.siteKey === s.siteKey) return ctx.ui.info(`The site is answering at ${s.manifestUrl}.`);
+            ctx.ui.stop(
+              `${s.manifestUrl} answers, but for "${String(body.siteKey)}", not "${s.siteKey}". Check SITE_KEY in lib/studio.ts and the address in Studio's Site settings.`,
+            );
+          }
+        } catch (e) {
+          if (e instanceof StopError) throw e;
+        }
+        if (i > 0 && i % 6 === 0) ctx.ui.info(`Still waiting for ${s.manifestUrl} (${i / 6} min)…`);
+        await ctx.sleep(POLL_EVERY_MS);
+      }
+      ctx.ui.stop(
+        `The site is not answering at ${s.manifestUrl} yet. Merge the pull request and let it deploy, then run this again; it continues from here.`,
+      );
+    },
+  },
+  {
+    id: "ready",
+    title: "Tell Studio",
+    why: "Asks Studio to read the site's editable content, so it appears in the editor.",
+    async run(ctx) {
+      const s = need(ctx);
+      const r = await markReady(s.studioUrl, s.readyToken, ctx.fetchImpl);
+      if (!r.ok) return ctx.ui.stop(r.message);
+      const report = /** @type {{ created?: unknown[], updated?: unknown[] }} */ (r.data.report ?? {});
+      const count = (report.created?.length ?? 0) + (report.updated?.length ?? 0);
+      ctx.ui.info("");
+      ctx.ui.info(`Done. ${s.siteName} is connected to WMM Studio${count ? ` with ${count} editable item${count === 1 ? "" : "s"}` : ""}.`);
+      ctx.ui.info(`Edit it at ${s.studioUrl.replace(/\/+$/, "")}/sites/${s.siteKey}`);
+      ctx.ui.info("The onboarding checklist there fills in as real visitors arrive.");
+      ctx.ui.info("Still for a person, if they apply: the client's brand colours in WMM's design system, and the CRM and ads hand-offs.");
+    },
+  },
+];
+
+/** @param {Ctx} ctx @returns {OnboardingState} */
+function need(ctx) {
+  if (!ctx.state) throw new StopError("Setup lost its place. Run this again with a new code from Studio.");
+  return ctx.state;
+}
+
+/** @param {Ctx} ctx @returns {AnyProvisioner} */
+function provisioner(ctx) {
+  if (ctx.injectedProvisioner) return ctx.injectedProvisioner;
+  // The team the developer chose is saved in state, so a rerun uses it too.
+  const scope = ctx.state?.scope ?? DEFAULT_SCOPE;
+  if (!ctx.provisioner || ctx.provisionerScope !== scope) {
+    ctx.provisioner = cliProvisioner({ cwd: ctx.cwd, run: ctx.run, scope });
+    ctx.provisionerScope = scope;
+  }
+  return ctx.provisioner;
+}
+
+/** Env files and machine-local settings: never committed by this command. @param {string} file */
+function isPrivateFile(file) {
+  const base = file.split("/").pop() ?? file;
+  if (base.startsWith(".env") && !/\.(example|sample|template)$/.test(base)) return true;
+  return file === ".claude/settings.local.json" || file.startsWith(".wmm-onboarding/") || file.startsWith(".vercel/");
+}
+
+/** @param {Ctx} ctx @param {string} cmd @param {string[]} args */
+async function must(ctx, cmd, args) {
+  const r = await ctx.run(cmd, args, { cwd: ctx.cwd });
+  if (r.code !== 0) ctx.ui.stop(`\`${cmd} ${args.join(" ")}\` failed: ${(r.stderr || r.stdout).trim()}`, `${cmd} ${args.join(" ")}`);
+}
+
+/**
+ * @param {string[]} args
+ * @param {Partial<{ cwd: string, input: NodeJS.ReadableStream, output: NodeJS.WritableStream, run: Runner, fetchImpl: Fetch, provisioner: AnyProvisioner, sleep: (ms: number) => Promise<void> }>} [deps]
+ * @returns {Promise<number>} exit code
+ */
+export async function runInit(args, deps = {}) {
+  const explain = args.includes("--explain");
+  const studioAt = args.indexOf("--studio");
+  const studioUrl = studioAt >= 0 && args[studioAt + 1] ? args[studioAt + 1] : DEFAULT_STUDIO;
+  const code = args.find((a, i) => !a.startsWith("--") && args[i - 1] !== "--studio") ?? null;
+  const cwd = deps.cwd ?? process.cwd();
+  const output = deps.output ?? process.stdout;
+  const ui = createUi({ input: deps.input ?? process.stdin, output, explain });
+
+  output.write("\nWMM Studio setup\n");
+  if (explain) {
+    output.write("Showing every step without changing anything.\n");
+    STEPS.forEach((s, i) => ui.step(i + 1, STEPS.length, s.title, s.why));
+    ui.close();
+    return 0;
+  }
+
+  const saved = loadState(cwd);
+  /** @type {Ctx} */
+  const ctx = {
+    cwd,
+    ui,
+    run: deps.run ?? createRunner(),
+    fetchImpl: deps.fetchImpl ?? fetch,
+    sleep: deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms))),
+    studioUrl,
+    code,
+    state: saved,
+    provisioner: null,
+    injectedProvisioner: deps.provisioner ?? null,
+  };
+
+  try {
+    for (const [i, step] of STEPS.entries()) {
+      const done = ctx.state?.done.includes(step.id) ?? false;
+      // The code is re-exchanged when a new one is given, even mid-setup.
+      const redo = step.id === "connect" && ctx.code !== null;
+      if (done && !redo) {
+        ui.step(i + 1, STEPS.length, step.title, "Already done.");
+        continue;
+      }
+      ui.step(i + 1, STEPS.length, step.title, step.why);
+      await step.run(ctx);
+      if (step.id !== "preflight" && ctx.state) {
+        if (!ctx.state.done.includes(step.id)) ctx.state.done.push(step.id);
+        saveState(cwd, ctx.state);
+      }
+    }
+    return 0;
+  } catch (err) {
+    if (err instanceof StopError) {
+      output.write(`\n  ${err.message}\n`);
+      if (err.nextCommand) output.write(`  Next: ${err.nextCommand}\n`);
+    } else {
+      output.write(`\n  Something went wrong: ${err instanceof Error ? err.message : String(err)}\n`);
+      output.write("  Run this again; it continues from where it stopped.\n");
+    }
+    return 1;
+  } finally {
+    ui.close();
+  }
+}
+

package/cli/preflight.mjs

@@ -0,0 +1,78 @@
+// @ts-check
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * Step 1 of the onboarding command: check the machine and the app BEFORE
+ * changing anything, and stop with the exact next command when something is
+ * missing (spec 2026-10-09 §3.1). Nothing here writes.
+ */
+
+/** @typedef {import("./run.mjs").Runner} Runner */
+/** @typedef {import("./ui.mjs").Ui} Ui */
+
+/** @param {string} version */
+function majorOf(version) {
+  const m = /(\d+)/.exec(version);
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * @param {{ cwd: string, run: Runner, ui: Ui, resuming?: boolean }} ctx
+ * @returns {Promise<{ mode: "existing", nextMajor: number | null }>}
+ */
+export async function preflight({ cwd, run, ui, resuming = false }) {
+  const node = majorOf(process.versions.node) ?? 0;
+  if (node < 22) {
+    ui.stop(`This needs Node.js 22 or newer; you have ${process.versions.node}.`, "Install Node 22 from https://nodejs.org");
+  }
+
+  const pkgPath = path.join(cwd, "package.json");
+  if (!existsSync(pkgPath)) {
+    const entries = readdirSync(cwd).filter((f) => f !== ".git");
+    if (entries.length === 0) {
+      ui.stop(
+        "This folder is empty, so it would be a new site from WMM's template. That path opens once the template is upgraded to Next.js 16; for now, run this inside an existing Next.js app.",
+      );
+    }
+    ui.stop("Run this inside the app's folder: the one that has package.json.");
+  }
+
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  const nextVersion = pkg.dependencies?.next ?? pkg.devDependencies?.next ?? null;
+  if (!nextVersion) ui.stop("This app does not use Next.js. Studio's package needs a Next.js 16 app.");
+  const nextMajor = majorOf(nextVersion);
+  if (nextMajor !== null && nextMajor < 16) {
+    ui.stop(
+      `This app uses Next.js ${nextMajor}. Studio needs Next.js 16 or newer. Upgrade first (this command will not do it for you), then run this again.`,
+      "npx @next/codemod@canary upgrade latest",
+    );
+  }
+
+  const gh = await run("gh", ["auth", "status"], { cwd });
+  if (gh.code === 127) ui.stop("The GitHub CLI is not installed.", "Install it from https://cli.github.com");
+  if (gh.code !== 0) ui.stop("You are not signed in to GitHub.", "gh auth login");
+
+  const vercel = await run("vercel", ["whoami"], { cwd });
+  if (vercel.code === 127) ui.stop("The Vercel CLI is not installed.", "npm install -g vercel");
+  if (vercel.code !== 0) ui.stop("You are not signed in to Vercel.", "vercel login");
+
+  const git = await run("git", ["status", "--porcelain"], { cwd });
+  if (git.code !== 0) ui.stop("This folder is not a git repository yet.", "git init");
+  // A resumed run expects the changes its own earlier steps made.
+  if (git.stdout.trim() !== "" && !resuming) {
+    ui.stop(
+      "You have uncommitted changes. Commit or stash them first, so the changes this command makes are easy to review on their own.",
+      "git stash",
+    );
+  }
+
+  const claude = await run("claude", ["--version"], { cwd });
+  if (claude.code !== 0) {
+    ui.info(
+      "Heads up: Claude Code is not installed. You will need it at step 7, where it helps wire your layout and choose the editable text. Install: https://claude.com/claude-code",
+    );
+  }
+
+  return { mode: "existing", nextMajor };
+}