@decocms/blocks-cli 7.69.1 → 7.71.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks-cli",
-  "version": "7.69.1",
+  "version": "7.71.0",
   "type": "module",
   "description": "Deco codegen (generate-blocks, generate-schema, generate-invoke) and Fresh-to-TanStack migration tooling",
   "repository": {
@@ -33,7 +33,7 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.69.1",
+    "@decocms/blocks": "7.71.0",
     "ts-morph": "^27.0.0",
     "tsx": "^4.22.5"
   },

package/scripts/analyze-traces.mjs

@@ -361,6 +361,7 @@ function imageStats(events, ns) {
   const imgDomains = [
     "vtexassets",
     "decoims",
+    "assets.decocms.com",
     "decoazn",
     "decocache",
     "deco-sites-assets",

package/scripts/lib/wrangler-config.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import { setKvNamespaceIdInJsonc } from "./wrangler-config";
+
+describe("setKvNamespaceIdInJsonc", () => {
+  // The scaffolded wrangler.jsonc carries the comments explaining why each
+  // binding exists; a parse-and-restringify round trip would drop every one.
+  const WRANGLER = `{
+  "name": "acme",
+  "kv_namespaces": [
+    // Fast Deploy content store.
+    { "binding": "DECO_KV", "id": "" },
+    // A/B testing assignments.
+    { "binding": "SITES_KV", "id": "" }
+  ],
+  "vars": { "DECO_FAST_DEPLOY": "1" }
+}`;
+
+  it("writes the id into the DECO_KV entry and leaves comments intact", () => {
+    const out = setKvNamespaceIdInJsonc(WRANGLER, "ns-123");
+    expect(out).toContain('{ "binding": "DECO_KV", "id": "ns-123" }');
+    expect(out).toContain("// Fast Deploy content store.");
+    expect(out).toContain("// A/B testing assignments.");
+  });
+
+  it("does not touch a different binding's id", () => {
+    const out = setKvNamespaceIdInJsonc(WRANGLER, "ns-123");
+    expect(out).toContain('{ "binding": "SITES_KV", "id": "" }');
+  });
+
+  it("targets the requested binding", () => {
+    const out = setKvNamespaceIdInJsonc(WRANGLER, "ab-9", "SITES_KV");
+    expect(out).toContain('{ "binding": "SITES_KV", "id": "ab-9" }');
+    expect(out).toContain('{ "binding": "DECO_KV", "id": "" }');
+  });
+
+  it("handles reversed field order and an entry with no id yet", () => {
+    const src = '{ "kv_namespaces": [{ "id": "old", "binding": "DECO_KV" }] }';
+    expect(setKvNamespaceIdInJsonc(src, "new")).toContain('"id": "new"');
+    const noId = '{ "kv_namespaces": [{ "binding": "DECO_KV" }] }';
+    expect(setKvNamespaceIdInJsonc(noId, "new")).toContain('"id": "new"');
+  });
+
+  it("returns the source unchanged when the binding is absent", () => {
+    // Not an error: the builder re-forces the id from CF_KV_NAMESPACE_ID on
+    // every build, so a repo without the binding is just nothing to personalize.
+    const src = '{ "kv_namespaces": [{ "binding": "SITES_KV", "id": "x" }] }';
+    expect(setKvNamespaceIdInJsonc(src, "ns-123")).toBe(src);
+  });
+});

package/scripts/lib/wrangler-config.ts

@@ -72,3 +72,34 @@ function matchTomlString(body: string, key: string): string | null {
   const m = body.match(new RegExp(`(?:^|\\n)\\s*${key}\\s*=\\s*["']([^"']+)["']`));
   return m ? m[1] : null;
 }
+
+/**
+ * Set the `id` of a `kv_namespaces` entry in a `wrangler.jsonc` SOURCE string,
+ * preserving comments and formatting.
+ *
+ * Deliberately text-level rather than parse-and-restringify: the scaffolded
+ * `wrangler.jsonc` carries the comments explaining why each binding exists, and
+ * a round-trip through `JSON.parse`/`stringify` would drop every one of them.
+ *
+ * Returns the original string unchanged when the binding is absent — callers
+ * treat that as "nothing to personalize", never as an error, because the
+ * builder re-forces the id from `CF_KV_NAMESPACE_ID` on every build anyway.
+ */
+export function setKvNamespaceIdInJsonc(
+  src: string,
+  id: string,
+  binding = DEFAULT_BINDING,
+): string {
+  // Match the object literal holding this binding, in either field order, and
+  // rewrite only its `id` value. Bounded to a single `{...}` so it cannot reach
+  // past the entry into the next one.
+  const entry = new RegExp(`\\{[^{}]*?"binding"\\s*:\\s*"${binding}"[^{}]*?\\}`, "s");
+  const m = src.match(entry);
+  if (!m) return src;
+
+  const patched = m[0].includes('"id"')
+    ? m[0].replace(/"id"\s*:\s*"[^"]*"/, `"id": ${JSON.stringify(id)}`)
+    : m[0].replace(/\}$/, `, "id": ${JSON.stringify(id)} }`);
+
+  return src.slice(0, m.index) + patched + src.slice(m.index! + m[0].length);
+}

package/scripts/migrate/fast-deploy-scaffold.test.ts

@@ -0,0 +1,130 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { describe, expect, it } from "vitest";
+import { parseJsonc } from "../lib/jsonc";
+import { generateWranglerConfig } from "./phase-scaffold";
+import { checks } from "./phase-verify";
+import { generateSetup } from "./templates/setup";
+import type { MigrationContext } from "./types";
+
+/**
+ * Fast Deploy is inert unless THREE things line up: the `DECO_KV` binding,
+ * `DECO_FAST_DEPLOY=1`, and `setup.ts` handing the KV resolver to
+ * `@decocms/blocks-admin` (which cannot import `@decocms/tanstack` itself).
+ *
+ * Two of three is the worst state: it looks configured, a Studio publish
+ * reports success, and nothing ever reaches KV. These tests pin the scaffold to
+ * emit all three and pin the verify check to actually catch a partial config.
+ */
+
+const FIXTURE: MigrationContext = {
+  sourceDir: "",
+  siteName: "test-site",
+  platform: "custom",
+  vtexAccount: null,
+  gtmId: null,
+  importMap: {},
+  discoveredNpmDeps: {},
+  themeColors: {},
+  tailwindConfig: {
+    colors: {},
+    fontFamily: {},
+    screens: {},
+    safelist: [],
+    safelistPatterns: [],
+    plugins: [],
+    reviewItems: [],
+    animations: {},
+    keyframes: {},
+  },
+  fontFamily: null,
+  googleFonts: [],
+  layout: null,
+  files: [],
+  sectionMetas: [],
+  islandClassifications: [],
+  loaderInventory: [],
+  patterns: {},
+  scaffoldedFiles: [],
+  transformedFiles: [],
+  deletedFiles: [],
+  movedFiles: [],
+  manualReview: [],
+  dryRun: false,
+  verbose: false,
+} as unknown as MigrationContext;
+
+const fastDeployCheck = checks.find((c) => c.name === "Fast Deploy wired end to end");
+
+/** Write a site tree with the given wrangler + setup contents. */
+function makeSite(wrangler: string, setup: string): MigrationContext {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "fd-scaffold-"));
+  fs.writeFileSync(path.join(dir, "wrangler.jsonc"), wrangler);
+  fs.mkdirSync(path.join(dir, "src"), { recursive: true });
+  fs.writeFileSync(path.join(dir, "src", "setup.ts"), setup);
+  return { ...FIXTURE, sourceDir: dir };
+}
+
+describe("scaffolded wrangler.jsonc", () => {
+  // Parse it rather than grep it: the template is hand-written JSONC, and a
+  // stray comma or comment that breaks parsing silently disables fast-deploy
+  // everywhere at once (the builder, the control-plane and the verify check
+  // below all read this file through a JSONC parser).
+  const cfg = parseJsonc(generateWranglerConfig(FIXTURE)) as {
+    kv_namespaces: Array<{ binding: string }>;
+    vars: Record<string, string>;
+    tail_consumers?: unknown[];
+  };
+
+  it("declares the DECO_KV binding and DECO_FAST_DEPLOY together", () => {
+    expect(cfg.kv_namespaces.map((n) => n.binding)).toContain("DECO_KV");
+    expect(cfg.vars.DECO_FAST_DEPLOY).toBe("1");
+    expect(cfg.vars.DECO_SITE_NAME).toBe("test-site");
+  });
+
+  it("declares a tail consumer, without which exceededMemory is unobservable", () => {
+    // Cloudflare kills the isolate over the 128MB cap before any in-worker code
+    // could report it — the tail worker is the only channel that sees it.
+    expect(cfg.tail_consumers).toBeTruthy();
+  });
+});
+
+describe("scaffolded setup.ts", () => {
+  it("calls setupTanstackFastDeploy, or the Studio publish write-through no-ops", () => {
+    const setup = generateSetup(FIXTURE);
+    expect(setup).toContain("setupTanstackFastDeploy()");
+    expect(setup).toMatch(/import \{[^}]*setupTanstackFastDeploy[^}]*\} from "@decocms\/tanstack"/);
+  });
+});
+
+describe('verify check "Fast Deploy wired end to end"', () => {
+  const FULL_WRANGLER = `{
+  // comment + trailing comma: real wrangler.jsonc, not JSON
+  "kv_namespaces": [{ "binding": "DECO_KV", "id": "" }],
+  "vars": { "DECO_FAST_DEPLOY": "1" },
+}`;
+  const FULL_SETUP = "setupTanstackFastDeploy();\n";
+
+  it("passes on a fully wired site", () => {
+    expect(fastDeployCheck?.fn(makeSite(FULL_WRANGLER, FULL_SETUP))).toBe(true);
+  });
+
+  it("fails when the DECO_KV binding is missing", () => {
+    const w = '{ "kv_namespaces": [], "vars": { "DECO_FAST_DEPLOY": "1" } }';
+    expect(fastDeployCheck?.fn(makeSite(w, FULL_SETUP))).toBe(false);
+  });
+
+  it("fails when DECO_FAST_DEPLOY is not set", () => {
+    const w = '{ "kv_namespaces": [{ "binding": "DECO_KV", "id": "" }] }';
+    expect(fastDeployCheck?.fn(makeSite(w, FULL_SETUP))).toBe(false);
+  });
+
+  it("fails when setup.ts never hands over the KV resolver", () => {
+    expect(fastDeployCheck?.fn(makeSite(FULL_WRANGLER, "// nothing\n"))).toBe(false);
+  });
+
+  it("is an error, not a warning — a silent half-config is the failure mode", () => {
+    expect(fastDeployCheck?.severity).toBe("error");
+  });
+});

package/scripts/migrate/phase-scaffold.ts

@@ -277,21 +277,48 @@ export { type Font as SiteThemeFont };
 `;
 }
 
-function generateWranglerConfig(ctx: MigrationContext): string {
-  return (
-    JSON.stringify(
-      {
-        name: ctx.siteName,
-        main: "src/worker-entry.ts",
-        compatibility_date: "2025-05-01",
-        compatibility_flags: ["nodejs_compat", "no_handle_cross_request_promise_resolution"],
-        cache: { enabled: true },
-        kv_namespaces: [{ binding: "SITES_KV", id: "dev-sites-kv" }],
-      },
-      null,
-      2,
-    ) + "\n"
-  );
+export function generateWranglerConfig(ctx: MigrationContext): string {
+  // Emitted as real JSONC (not JSON.stringify) so the comments survive — every
+  // field below is load-bearing and the next person to edit this file needs to
+  // know why. The ids are placeholders: the control-plane owns them (it
+  // provisions the site's OWN namespaces and overrides these at build time),
+  // so a wrong id here can never reach production.
+  return `{
+  "name": "${ctx.siteName}",
+  "main": "src/worker-entry.ts",
+  "compatibility_date": "2025-05-01",
+  // no_handle_cross_request_promise_resolution: the framework's SWR/dedup
+  // caches hold in-flight promises across requests; without this flag the
+  // worker hangs.
+  "compatibility_flags": ["nodejs_compat", "no_handle_cross_request_promise_resolution"],
+  // Workers Cache — tiered cache IN FRONT of the worker. On a hit the worker
+  // never runs. Per-response cacheability is still driven by Cache-Control.
+  "cache": { "enabled": true },
+  // Surfaces the build sha as service.version on every span and log line.
+  "version_metadata": { "binding": "CF_VERSION_METADATA" },
+  // Tail worker. The ONLY channel that can see exceededMemory / exceededCpu:
+  // Cloudflare kills the isolate before any in-worker code could report them.
+  // Without this a memory incident is invisible — see docs/runbooks/.
+  "tail_consumers": [{ "service": "deco-otel-tail" }],
+  "kv_namespaces": [
+    // Fast Deploy content store. Holds decofile:<deployment-id> + the revision
+    // index, so a CMS publish goes live without a code deploy. The id is
+    // written by the control-plane at site creation and re-forced from
+    // CF_KV_NAMESPACE_ID on every build (per-site KV isolation).
+    { "binding": "DECO_KV", "id": "" }
+    // No SITES_KV: withABTesting (server-entry) passes through when it is
+    // unbound, and nothing provisions it — an empty id would fail deploy.
+    // Add it with the shared namespace's real id when starting an A/B test.
+  ],
+  "vars": {
+    "DECO_SITE_NAME": "${ctx.siteName}",
+    "DECO_ENV_NAME": "production",
+    // Fast Deploy opt-in. Requires BOTH this flag AND the DECO_KV binding
+    // above; inert if either is missing. Set to "0" to disable.
+    "DECO_FAST_DEPLOY": "1"
+  }
+}
+`;
 }
 
 function generateGitignore(): string {

package/scripts/migrate/phase-verify.ts

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { parseJsonc } from "../lib/jsonc";
 import type { MigrationContext } from "./types";
 import { logPhase } from "./types";
 
@@ -84,6 +85,45 @@ export const checks: Check[] = [
       return true;
     },
   },
+  {
+    // Fast Deploy needs THREE things and is inert unless all three are present:
+    // the DECO_KV binding, DECO_FAST_DEPLOY=1, and setup.ts handing the KV
+    // resolver to blocks-admin. Two of three is the worst state — it looks
+    // configured, the Studio publish reports success, and nothing reaches KV.
+    name: "Fast Deploy wired end to end",
+    severity: "error",
+    fn: (ctx) => {
+      const missing: string[] = [];
+      const wranglerPath = path.join(ctx.sourceDir, "wrangler.jsonc");
+      try {
+        const cfg = parseJsonc(fs.readFileSync(wranglerPath, "utf-8")) as {
+          kv_namespaces?: Array<{ binding?: string }>;
+          vars?: Record<string, unknown>;
+        };
+        const flag = cfg.vars?.DECO_FAST_DEPLOY;
+        if (!(cfg.kv_namespaces ?? []).some((n) => n?.binding === "DECO_KV")) {
+          missing.push("wrangler.jsonc kv_namespaces is missing the DECO_KV binding");
+        }
+        if (flag !== "1" && flag !== "true") {
+          missing.push('wrangler.jsonc vars.DECO_FAST_DEPLOY is not "1"');
+        }
+      } catch (e) {
+        missing.push(`wrangler.jsonc could not be parsed: ${(e as Error).message}`);
+      }
+
+      const setupPath = path.join(ctx.sourceDir, "src", "setup.ts");
+      const setup = fs.existsSync(setupPath) ? fs.readFileSync(setupPath, "utf-8") : "";
+      if (!setup.includes("setupTanstackFastDeploy()")) {
+        missing.push("src/setup.ts does not call setupTanstackFastDeploy()");
+      }
+
+      if (missing.length > 0) {
+        for (const m of missing) console.log(`    ${m}`);
+        return false;
+      }
+      return true;
+    },
+  },
   {
     name: "Old artifacts removed",
     severity: "error",

package/scripts/migrate/templates/routes.ts

@@ -46,7 +46,7 @@ function generateRoot(ctx: MigrationContext, siteTitle: string, vtexAccount: str
 
   // Build preconnect list based on platform
   const preconnects: string[] = [];
-  preconnects.push(`      { rel: "preconnect", href: "https://decoims.com", crossOrigin: "anonymous" as const },`);
+  preconnects.push(`      { rel: "preconnect", href: "https://assets.decocms.com", crossOrigin: "anonymous" as const },`);
   if (isVtex) {
     preconnects.push(`      { rel: "preconnect", href: "https://${vtexAccount}.vtexassets.com", crossOrigin: "anonymous" as const },`);
   }

package/scripts/migrate/templates/setup.ts

@@ -104,7 +104,7 @@ import { initVtexFromBlocks, setVtexFetch } from "@decocms/apps-vtex";` : ""}${h
 import { registerLocationMatcher } from "./matchers/location";` : ""}
 import { blocks as generatedBlocks } from "../.deco/blocks.gen";
 import { sectionMeta, syncComponents, loadingFallbacks, renderJsons } from "../.deco/sections.gen";
-import { PreviewProviders } from "@decocms/tanstack";
+import { PreviewProviders, setupTanstackFastDeploy } from "@decocms/tanstack";
 // @ts-ignore Vite ?url import
 import appCss from "./styles/app.css?url";
 
@@ -131,6 +131,13 @@ createSiteSetup({
     return null;
   },
 });
+
+// -- Fast Deploy --
+// Hands the KV binding resolver to @decocms/blocks-admin, which cannot import
+// @decocms/tanstack itself (wrong direction in the package graph). Without this
+// call a Studio publish silently no-ops instead of writing through to KV.
+// Inert unless the worker has DECO_FAST_DEPLOY=1 + a DECO_KV binding.
+setupTanstackFastDeploy();
 ${isVtex ? `
 // -- VTEX wiring --
 setVtexFetch(createInstrumentedFetch("vtex"));

package/scripts/migrate.ts

@@ -27,6 +27,7 @@
 import { execSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { setKvNamespaceIdInJsonc } from "./lib/wrangler-config";
 import { banner, green, red, stat, yellow } from "./migrate/colors";
 import { loadConfig, validateConfig } from "./migrate/config";
 import { analyze } from "./migrate/phase-analyze";
@@ -119,6 +120,15 @@ function showHelp() {
                           via \`deco-post-cleanup\` if needed)
     --help, -h            Show this help message
 
+  Environment (all optional — each step is skipped, never fatal, when unset):
+    DECO_CONTROL_PLANE_TOKEN  Provision the site via the control-plane's
+                              SITE_CREATE: repo, org ownership, the site's OWN
+                              Cloudflare KV namespace, and the deploy CR.
+    DECO_ORG                  Studio organization id that will own the site.
+                              Required together with the token above.
+    DECO_CONTROL_PLANE_URL    Override the control-plane base URL.
+    SUPABASE_ACCESS_TOKEN     Flip the site's analytics provider.
+
   Examples:
     npx -p @decocms/blocks-cli deco-migrate --dry-run --verbose
     npx -p @decocms/blocks-cli deco-migrate --source ./my-site
@@ -198,6 +208,7 @@ async function main() {
     // Phase 7: Bootstrap (install + generate)
     if (!ctx.dryRun) {
       bootstrap(ctx);
+      await provisionSite(ctx.sourceDir);
       await provisionAnalytics(ctx.sourceDir);
     }
 
@@ -284,6 +295,162 @@ function bootstrap(ctx: { sourceDir: string }) {
   }
 }
 
+/** A site slug: lower-case, the shape SITE_CREATE itself enforces. */
+const SITE_SLUG = /^[a-z0-9][a-z0-9._-]*$/;
+
+const CONTROL_PLANE_URL = "https://control-plane.decocms.com";
+
+/** `owner/name` of the repo in `dir`, from its `origin` remote, or null. */
+function repoFullName(dir: string): string | null {
+  try {
+    const url = execSync("git remote get-url origin", { cwd: dir, stdio: "pipe" })
+      .toString()
+      .trim();
+    const m = url.match(/[:/]([^/:]+)\/([^/]+?)(?:\.git)?$/);
+    return m ? `${m[1]}/${m[2]}` : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Provision the site on the control-plane (SITE_CREATE) and write the KV
+ * namespace id it returns into the scaffolded `wrangler.jsonc`.
+ *
+ * SITE_CREATE is idempotent and create-if-absent at every step: it claims the
+ * admin `sites` row, the org ownership, the site's OWN Cloudflare KV namespace
+ * (`deco-kv-<site>` — never shared, since `index:live` is one key per namespace
+ * and two sites sharing one would clobber each other's live pointer), the
+ * production environment, and the Deco CR that makes the site actually deploy.
+ * So a migrated site comes out of the box deployable and fast-deploy-ready
+ * instead of needing a dashboard click per worker.
+ *
+ * Inert without credentials: prints the equivalent call and continues. A
+ * migration must never fail because an operator ran it without a token — and
+ * the id is not load-bearing anyway, since the builder re-forces the DECO_KV id
+ * from `CF_KV_NAMESPACE_ID` on every build.
+ */
+async function provisionSite(sourceDir: string): Promise<void> {
+  logPhase("Provision site (control-plane)");
+
+  let siteName: string;
+  try {
+    siteName = JSON.parse(fs.readFileSync(path.join(sourceDir, "package.json"), "utf8")).name;
+  } catch {
+    console.log(`  ${yellow("⚠")} Could not read package.json — skipping site provision`);
+    return;
+  }
+
+  const base = process.env.DECO_CONTROL_PLANE_URL || CONTROL_PLANE_URL;
+  const token = process.env.DECO_CONTROL_PLANE_TOKEN;
+  const org = process.env.DECO_ORG;
+  const repo = repoFullName(sourceDir);
+
+  const args: Record<string, string> = { name: siteName, org: org ?? "<DECO_ORG>" };
+  // Shared/existing-repo mode: the repo already exists (we just migrated it),
+  // so SITE_CREATE must reference it rather than generate one from a template.
+  if (repo) args.repo = repo;
+
+  if (!token || !org) {
+    const which = [!token && "DECO_CONTROL_PLANE_TOKEN", !org && "DECO_ORG"]
+      .filter(Boolean)
+      .join(" + ");
+    console.log(`  ${yellow("⚠")} ${which} not set — skipping site provision`);
+    printSiteCreate(base, args);
+    return;
+  }
+
+  try {
+    const res = await fetch(`${base}/mcp`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+      signal: AbortSignal.timeout(30_000),
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "SITE_CREATE", arguments: args },
+      }),
+    });
+    if (!res.ok) {
+      console.log(
+        `  ${yellow("⚠")} SITE_CREATE failed (${res.status}): ${(await res.text()).slice(0, 160)}`,
+      );
+      printSiteCreate(base, args);
+      return;
+    }
+    const body = (await res.json()) as {
+      error?: { message?: string };
+      result?: { structuredContent?: unknown; content?: Array<{ text?: string }> };
+    };
+    if (body.error) {
+      console.log(`  ${yellow("⚠")} SITE_CREATE error: ${body.error.message ?? "unknown"}`);
+      printSiteCreate(base, args);
+      return;
+    }
+    const out = readToolResult(body.result);
+    console.log(
+      `  ${green("✓")} ${siteName} provisioned (org ${org}${out?.cluster ? `, cluster ${out.cluster}` : ""})`,
+    );
+
+    if (out?.kvNamespaceId) {
+      applyKvNamespaceId(sourceDir, out.kvNamespaceId);
+    } else {
+      // SITE_CREATE omits it on a knative site, when CF isn't configured, or
+      // when provisioning failed — the absence is the signal, not a default.
+      console.log(
+        `  ${yellow("⚠")} no kvNamespaceId returned — DECO_KV id left blank in wrangler.jsonc`,
+      );
+    }
+  } catch (err: any) {
+    console.log(`  ${yellow("⚠")} control-plane request failed: ${err.message}`);
+    printSiteCreate(base, args);
+  }
+}
+
+/** MCP tool output: `structuredContent` when present, else the JSON text block. */
+function readToolResult(
+  result: { structuredContent?: unknown; content?: Array<{ text?: string }> } | undefined,
+): { kvNamespaceId?: string; cluster?: string } | null {
+  if (!result) return null;
+  if (result.structuredContent && typeof result.structuredContent === "object") {
+    return result.structuredContent as { kvNamespaceId?: string; cluster?: string };
+  }
+  const text = result.content?.[0]?.text;
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+/** Write the site's own KV namespace id into the scaffolded wrangler.jsonc. */
+function applyKvNamespaceId(sourceDir: string, id: string): void {
+  const file = path.join(sourceDir, "wrangler.jsonc");
+  try {
+    const src = fs.readFileSync(file, "utf-8");
+    const next = setKvNamespaceIdInJsonc(src, id);
+    if (next === src) {
+      console.log(`  ${yellow("⚠")} wrangler.jsonc has no DECO_KV binding — id not written`);
+      return;
+    }
+    fs.writeFileSync(file, next);
+    console.log(`  ${green("✓")} wrangler.jsonc DECO_KV id → ${id}`);
+  } catch (err: any) {
+    console.log(`  ${yellow("⚠")} could not write wrangler.jsonc: ${err.message}`);
+  }
+}
+
+function printSiteCreate(base: string, args: Record<string, string>): void {
+  console.log(`  Run manually once you have a control-plane token:`);
+  console.log(
+    `  curl -s ${base}/mcp -XPOST -H 'content-type: application/json' \\\n` +
+      `    -H "authorization: Bearer $DECO_CONTROL_PLANE_TOKEN" \\\n` +
+      `    -d '${JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "SITE_CREATE", arguments: args } })}'`,
+  );
+}
+
 // Supabase project ref for decocms — the central platform DB that tracks all sites.
 const DECOCMS_SUPABASE_REF = "ozksgdmyrqcxcwhnbepg";
 
@@ -306,6 +473,16 @@ async function provisionAnalytics(sourceDir: string): Promise<void> {
     return;
   }
 
+  // The Supabase Management API takes raw SQL with no bind parameters, so the
+  // only safe move is to refuse anything that isn't a plain site slug rather
+  // than interpolate whatever `package.json` happens to contain.
+  if (!SITE_SLUG.test(siteName)) {
+    console.log(
+      `  ${yellow("⚠")} "${siteName}" is not a plain site slug — skipping analytics provision`,
+    );
+    return;
+  }
+
   const sql = `UPDATE public.sites SET metadata = metadata || '{"analytics": "onedollarstats"}'::jsonb WHERE name = '${siteName}'`;
 
   try {