@decocms/blocks-cli 8.0.0 → 8.1.0-next.0

package/scripts/migrate-blocks-to-kv.ts

@@ -30,8 +30,14 @@
  */
 
 import * as path from "node:path";
+import { splitExactRedirects } from "@decocms/blocks/sdk/redirects";
 import { createKvRestClient, kvConfigFromEnv } from "./lib/cf-kv-rest";
-import { buildSnapshot, verifySnapshotInKv, writeSnapshotToKv } from "./lib/kv-snapshot";
+import {
+  buildSnapshot,
+  syncRedirectsToKv,
+  verifySnapshotInKv,
+  writeSnapshotToKv,
+} from "./lib/kv-snapshot";
 import { readDecofileFromDir } from "./lib/read-decofile";
 
 function parseArgs(argv: string[]) {
@@ -77,8 +83,15 @@ async function main() {
     process.exit(2);
   }
 
-  const snap = buildSnapshot(blocks);
+  // Exact redirects live under their own `redirect:<id>:<path>` keys, not in
+  // the decofile — see splitExactRedirects. Must match what sync-blocks-to-kv
+  // writes, or a one-shot seed and a CI sync would disagree on the snapshot.
+  const split = splitExactRedirects(blocks);
+  const snap = buildSnapshot(split.blocks);
   console.log(`decofile: ${snap.count} blocks, revision ${snap.revision}, ${snap.snapshot.length} bytes`);
+  if (split.exact.length > 0) {
+    console.log(`redirects: ${split.exact.length} exact rule(s) as individual keys`);
+  }
 
   if (!opts.write) {
     console.log("\nDry-run only. Re-run with --write to populate KV.");
@@ -94,6 +107,7 @@ async function main() {
   }
 
   try {
+    await syncRedirectsToKv(client, split.exact, opts.deploymentId);
     await writeSnapshotToKv(client, snap, opts.deploymentId);
     const verify = await verifySnapshotInKv(client, snap.revision, opts.deploymentId);
     if (!verify.ok) {

package/scripts/migrate-to-cf-observability.test.ts

@@ -46,13 +46,13 @@ describe("migrate-to-cf-observability codemod", () => {
     fs.writeFileSync(
       wranglerPath,
       `{
-  "name": "lebiscuit-tanstack",
+  "name": "acme-tanstack",
   "compatibility_date": "2026-02-14",
   "main": "./src/worker-entry.ts",
   "kv_namespaces": [{ "binding": "SITES_KV", "id": "abc" }],
   "version_metadata": { "binding": "CF_VERSION_METADATA" },
   "analytics_engine_datasets": [
-    { "binding": "DECO_METRICS", "dataset": "deco_metrics_lebiscuit" }
+    { "binding": "DECO_METRICS", "dataset": "deco_metrics_acme" }
   ],
   "observability": {
     "logs": {
@@ -77,7 +77,7 @@ describe("migrate-to-cf-observability codemod", () => {
     // No destinations by default.
     expect(result).not.toContain('"destinations"');
     // Original keys preserved.
-    expect(result).toContain('"name": "lebiscuit-tanstack"');
+    expect(result).toContain('"name": "acme-tanstack"');
     expect(result).toContain('"binding": "DECO_METRICS"');
     // Result must be valid JSONC.
     expect(() => JSON.parse(stripJsoncComments(result))).not.toThrow();
@@ -87,7 +87,7 @@ describe("migrate-to-cf-observability codemod", () => {
     fs.writeFileSync(
       wranglerPath,
       `{
-  "name": "lebiscuit-tanstack",
+  "name": "acme-tanstack",
   "main": "./src/worker-entry.ts",
   "observability": {
     "enabled": true,
@@ -146,7 +146,7 @@ describe("migrate-to-cf-observability codemod", () => {
     fs.writeFileSync(
       wranglerPath,
       `{
-  "name": "lebiscuit-tanstack",
+  "name": "acme-tanstack",
   "main": "./src/worker-entry.ts",
   "observability": {
     "logs": { "enabled": true }

package/scripts/migrate-to-cf-observability.ts

@@ -21,7 +21,7 @@
  * Cloudflare captures nothing, regardless of the sub-block flags.
  * `persist: true` keeps the data queryable in the CF dashboard
  * (Workers Logs view + Traces view). Discovered the hard way during the
- * lebiscuit canary cutover.
+ * production canary cutover.
  *
  * Behavior:
  *   - dry-run by default — prints a unified diff against the existing

package/scripts/migrate.ts

@@ -25,7 +25,9 @@
  */
 
 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";
@@ -118,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
@@ -156,18 +167,21 @@ async function main() {
     config: siteConfig,
   });
 
-  // Phase 0: Source-layout detection (early-abort for unsupported layouts).
-  // The analyzer assumes a classic root layout (sections/, islands/, ...);
-  // running it on a modern src/ layout silently yields a near-empty
-  // migration. Detect-and-abort here so the user gets an actionable error
-  // before we touch any files.
+  // Phase 0: Source-layout detection. `classic` (root sections/) and `modern`
+  // (src/sections/) are both supported — the analyzer scans src/ natively for
+  // modern layouts. Only genuinely ambiguous (`mixed`) or unrecognizable
+  // (`empty`) layouts abort with an actionable error before we touch files.
   const layout = detectSourceLayout(sourceDir);
-  if (layout !== "classic") {
+  ctx.layout = layout;
+  if (layout === "mixed" || layout === "empty") {
     console.error(red(`Error: ${layout} source layout`));
     console.error("");
     console.error(explainNonClassicLayout(layout, sourceDir));
     process.exit(2);
   }
+  if (layout === "modern") {
+    console.log(`  Source layout: modern (src/) — scanning src/ natively`);
+  }
 
   try {
     // Phase 1: Analyze source
@@ -194,6 +208,8 @@ async function main() {
     // Phase 7: Bootstrap (install + generate)
     if (!ctx.dryRun) {
       bootstrap(ctx);
+      await provisionSite(ctx.sourceDir);
+      await provisionAnalytics(ctx.sourceDir);
     }
 
     // Phase 8: Compile (typecheck + optional build)
@@ -279,4 +295,226 @@ 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";
+
+async function provisionAnalytics(sourceDir: string): Promise<void> {
+  logPhase("Provision analytics (decocms Supabase)");
+
+  let siteName: string;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(sourceDir, "package.json"), "utf8"));
+    siteName = pkg.name;
+  } catch {
+    console.log(`  ${yellow("⚠")} Could not read package.json — skipping analytics provision`);
+    return;
+  }
+
+  const token = process.env.SUPABASE_ACCESS_TOKEN;
+  if (!token) {
+    console.log(`  ${yellow("⚠")} SUPABASE_ACCESS_TOKEN not set — skipping analytics provision`);
+    printAnalyticsSQL(siteName);
+    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 {
+    const res = await fetch(
+      `https://api.supabase.com/v1/projects/${DECOCMS_SUPABASE_REF}/database/query`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ query: sql }),
+      },
+    );
+    if (res.ok) {
+      console.log(`  ${green("✓")} ${siteName} → analytics: onedollarstats`);
+    } else {
+      const body = await res.text();
+      console.log(`  ${yellow("⚠")} Supabase update failed (${res.status}): ${body.slice(0, 120)}`);
+      printAnalyticsSQL(siteName);
+    }
+  } catch (err: any) {
+    console.log(`  ${yellow("⚠")} Supabase request failed: ${err.message}`);
+    printAnalyticsSQL(siteName);
+  }
+}
+
+function printAnalyticsSQL(siteName: string): void {
+  console.log(`  Run manually on decocms Supabase (${DECOCMS_SUPABASE_REF}):`);
+  console.log(
+    `  UPDATE public.sites SET metadata = metadata || '{"analytics": "onedollarstats"}'::jsonb WHERE name = '${siteName}';`,
+  );
+}
+
 main();

package/scripts/reconcile.test.ts

@@ -0,0 +1,162 @@
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  detectTargetSnapshot,
+  isSkipped,
+  parseNameStatus,
+  type ReconcileManifest,
+  targetCandidates,
+} from "./reconcile";
+
+describe("parseNameStatus", () => {
+  it("splits plain and rename entries", () => {
+    expect(parseNameStatus("M\tsections/A.tsx\nR094\tislands/B.tsx\tislands/C.tsx\n"))
+      .toEqual([
+        { status: "M", path: "sections/A.tsx" },
+        { status: "R094", path: "islands/C.tsx", oldPath: "islands/B.tsx" },
+      ]);
+  });
+});
+
+describe("isSkipped", () => {
+  it("drops CMS content, lockfiles and binaries but keeps source", () => {
+    expect(isSkipped(".deco/blocks/pages-home.json")).toBe(true);
+    expect(isSkipped("deno.lock")).toBe(true);
+    expect(isSkipped("static/logo.png")).toBe(true);
+    expect(isSkipped("sections/Header.tsx")).toBe(false);
+  });
+
+  it("drops what the migration deletes — no target file to port into", () => {
+    expect(isSkipped("fresh.gen.ts")).toBe(true);
+    expect(isSkipped("manifest.gen.ts")).toBe(true);
+    expect(isSkipped("deno.json")).toBe(true);
+    expect(isSkipped("sdk/cart/vtex.ts")).toBe(true);
+    // routes/ is rescaffolded but a NEW upstream route is a real change — keep it.
+    expect(isSkipped("routes/blog.tsx")).toBe(false);
+    expect(isSkipped("redirects.csv")).toBe(false);
+  });
+});
+
+describe("targetCandidates", () => {
+  it("ranks the conventional guess first, keeps other basename matches", () => {
+    const byBasename = new Map([
+      ["Cart.tsx", ["src/sections/Cart.tsx", "src/components/Cart.tsx"]],
+    ]);
+    expect(targetCandidates("islands/Cart.tsx", byBasename)).toEqual([
+      "src/components/Cart.tsx",
+      "src/sections/Cart.tsx",
+    ]);
+  });
+
+  it("returns nothing when the file does not exist on the target", () => {
+    expect(targetCandidates("sections/New.tsx", new Map())).toEqual([]);
+  });
+});
+
+describe("detectTargetSnapshot", () => {
+  it("takes the OLDEST add — git log is newest-first, re-adds must not win", () => {
+    expect(detectTargetSnapshot("bbb\naaa\n")).toBe("aaa");
+    expect(detectTargetSnapshot("")).toBeUndefined();
+  });
+});
+
+describe("reconcile end to end", () => {
+  let tmp: string;
+  const git = (cwd: string, ...args: string[]) =>
+    execFileSync("git", ["-C", cwd, ...args], { encoding: "utf8" }).trim();
+
+  const write = (repo: string, rel: string, body: string) => {
+    fs.mkdirSync(path.join(repo, path.dirname(rel)), { recursive: true });
+    fs.writeFileSync(path.join(repo, rel), body);
+  };
+  const commit = (repo: string, msg: string) => {
+    git(repo, "add", "-A");
+    git(repo, "commit", "-m", msg);
+    return git(repo, "rev-parse", "HEAD");
+  };
+  const init = (name: string) => {
+    const repo = path.join(tmp, name);
+    fs.mkdirSync(repo, { recursive: true });
+    git(repo, "init", "-q", "-b", "main");
+    git(repo, "config", "user.email", "t@t.t");
+    git(repo, "config", "user.name", "t");
+    return repo;
+  };
+
+  beforeEach(() => {
+    // realpath: macOS /var → /private/var, which git resolves and we compare against.
+    tmp = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), "reconcile-"));
+  });
+  afterEach(() => fs.rmSync(tmp, { recursive: true, force: true }));
+
+  it("auto-detects the target snapshot, emits one patch per file, flags hand-fixes", () => {
+    const source = init("source");
+    write(source, "sections/Header.tsx", "export default () => <h1>a</h1>;\n");
+    write(source, "sections/Footer.tsx", "export default () => <footer/>;\n");
+    write(source, "deno.lock", "{}\n");
+    const snapshot = commit(source, "cut");
+
+    write(source, "sections/Header.tsx", "export default () => <h1>b</h1>;\n");
+    write(source, "sections/Footer.tsx", "export default () => <footer id='f'/>;\n");
+    write(source, "deno.lock", '{"v":2}\n');
+    const sourceHead = commit(source, "upstream work");
+
+    const target = init("target");
+    write(target, "src/sections/Header.tsx", "export default () => <h1>a</h1>;\n");
+    // The island/section re-export pair — Header has TWO target candidates.
+    write(target, "src/components/Header.tsx", "export default () => <h1>a</h1>;\n");
+    write(target, "src/sections/Footer.tsx", "export default () => <footer/>;\n");
+    // The marker deco-migrate leaves behind — this is what auto-detection finds.
+    write(target, "MIGRATION_REPORT.md", "# Migration\n");
+    const targetSnapshot = commit(target, "migrate to tanstack");
+
+    // One hand-fix touching both candidates → must count as ONE collision.
+    write(target, "src/sections/Header.tsx", "export default () => <h1>a fixed</h1>;\n");
+    write(target, "src/components/Header.tsx", "export default () => <h1>a fixed</h1>;\n");
+    commit(target, "fix: codemod ate the heading");
+
+    const out = path.join(tmp, "out");
+    execFileSync(
+      path.join(__dirname, "../../../node_modules/.bin/tsx"),
+      [
+        path.join(__dirname, "reconcile.ts"),
+        "--source", source,
+        "--target", target,
+        "--snapshot", snapshot,
+        // no --target-snapshot: exercise the MIGRATION_REPORT.md auto-detection
+        "--out", out,
+      ],
+      { encoding: "utf8" },
+    );
+
+    const manifest: ReconcileManifest = JSON.parse(
+      fs.readFileSync(path.join(out, "manifest.json"), "utf8"),
+    );
+
+    expect(manifest.sourceHead).toBe(sourceHead);
+    expect(manifest.targetSnapshot).toBe(targetSnapshot);
+    // deno.lock filtered out.
+    expect(manifest.files.map((f) => f.sourcePath).sort()).toEqual([
+      "sections/Footer.tsx",
+      "sections/Header.tsx",
+    ]);
+
+    const header = manifest.files.find((f) => f.sourcePath === "sections/Header.tsx")!;
+    expect(header.targetCandidates).toEqual([
+      "src/sections/Header.tsx", // conventional guess ranks first
+      "src/components/Header.tsx",
+    ]);
+    expect(header.collision).toHaveLength(1); // deduped by SHA, not 2
+    expect(header.collision[0]).toContain("codemod ate the heading");
+    expect(fs.readFileSync(path.join(out, header.patch), "utf8")).toContain("<h1>b</h1>");
+
+    const footer = manifest.files.find((f) => f.sourcePath === "sections/Footer.tsx")!;
+    expect(footer.collision).toEqual([]);
+    expect(footer.done).toBe(false);
+
+    expect(fs.readFileSync(path.join(out, "INDEX.md"), "utf8")).toContain(sourceHead);
+  });
+});