@decocms/start 2.29.0 → 2.30.0

package/scripts/deploy/site-registry.mjs

@@ -0,0 +1,142 @@
+// Shared registry helpers for the deploy scripts.
+//
+// `loadSiteManifest(decoStartPath, siteName)` returns the validated
+// per-site manifest object. `mergeWithTemplate(template, site)` deep-merges a
+// site manifest on top of the canonical template and returns the wrangler
+// config object ready for serialization.
+//
+// Trust model: `siteName` is always derived from `${{ github.repository }}` in
+// CI (or from the local git remote in the wrapper CLI), never from a
+// user-supplied input. A site that is not registered in `deploy/sites/` cannot
+// be deployed -- this is enforced here.
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { readJsoncFile } from "./jsonc.mjs";
+
+/** @typedef {{
+ *   worker_name: string;
+ *   routes?: Array<{ pattern: string; zone_name?: string; custom_domain?: boolean }>;
+ *   kv_namespaces?: Array<{ binding: string; id: string; preview_id?: string }>;
+ *   analytics_engine_datasets?: Array<{ binding: string; dataset: string }>;
+ *   version_metadata?: { binding: string };
+ * }} SiteManifest
+ */
+
+const ALLOWED_SITE_KEYS = new Set([
+  "worker_name",
+  "routes",
+  "kv_namespaces",
+  "analytics_engine_datasets",
+  "version_metadata",
+]);
+
+/**
+ * @param {string} decoStartPath
+ * @returns {string}
+ */
+export function templatePath(decoStartPath) {
+  return join(decoStartPath, "deploy", "wrangler-template.jsonc");
+}
+
+/**
+ * @param {string} decoStartPath
+ * @param {string} siteName
+ * @returns {string}
+ */
+export function siteManifestPath(decoStartPath, siteName) {
+  return join(decoStartPath, "deploy", "sites", `${siteName}.jsonc`);
+}
+
+/**
+ * @param {string} decoStartPath
+ * @param {string} siteName
+ * @returns {SiteManifest}
+ */
+export function loadSiteManifest(decoStartPath, siteName) {
+  if (!siteName || !/^[a-z0-9][a-z0-9-]*$/.test(siteName)) {
+    throw new Error(
+      `Refusing to load manifest for invalid site name: ${JSON.stringify(siteName)}. Site names must be lowercase, hyphen-separated.`,
+    );
+  }
+  const path = siteManifestPath(decoStartPath, siteName);
+  if (!existsSync(path)) {
+    throw new Error(
+      `No registry entry for site "${siteName}" at ${path}.\n` +
+        `Add deploy/sites/${siteName}.jsonc to decocms/deco-start before deploying.`,
+    );
+  }
+  const raw = readJsoncFile(path);
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`Site manifest at ${path} must be a JSON object.`);
+  }
+  const manifest = /** @type {Record<string, unknown>} */ (raw);
+  if (typeof manifest.worker_name !== "string" || manifest.worker_name.length === 0) {
+    throw new Error(`Site manifest at ${path} is missing the required "worker_name" string.`);
+  }
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(/** @type {string} */ (manifest.worker_name))) {
+    throw new Error(
+      `Site manifest at ${path} has an invalid "worker_name": ${JSON.stringify(manifest.worker_name)}. Use lowercase, hyphen-separated.`,
+    );
+  }
+  for (const key of Object.keys(manifest)) {
+    if (!ALLOWED_SITE_KEYS.has(key)) {
+      throw new Error(
+        `Site manifest at ${path} contains unsupported key "${key}". Allowed: ${[...ALLOWED_SITE_KEYS].join(", ")}.`,
+      );
+    }
+  }
+  return /** @type {SiteManifest} */ (manifest);
+}
+
+/**
+ * @param {string} decoStartPath
+ * @returns {Record<string, unknown>}
+ */
+export function loadTemplate(decoStartPath) {
+  const path = templatePath(decoStartPath);
+  if (!existsSync(path)) {
+    throw new Error(`wrangler-template.jsonc not found at ${path}.`);
+  }
+  const raw = readJsoncFile(path);
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`Template at ${path} must be a JSON object.`);
+  }
+  return /** @type {Record<string, unknown>} */ (raw);
+}
+
+/**
+ * Deep-merge `source` on top of `target`. Arrays in `source` REPLACE arrays in
+ * `target` (they are not concatenated) -- this matches the semantics wrangler
+ * itself expects for `routes`, `kv_namespaces`, etc.
+ *
+ * @template T
+ * @param {T} target
+ * @param {unknown} source
+ * @returns {T}
+ */
+function deepMerge(target, source) {
+  if (source === null || source === undefined) return target;
+  if (Array.isArray(source)) return /** @type {T} */ (source);
+  if (typeof source !== "object") return /** @type {T} */ (source);
+  const base = target && typeof target === "object" && !Array.isArray(target) ? target : {};
+  const out = /** @type {Record<string, unknown>} */ ({ ...base });
+  for (const [k, v] of Object.entries(source)) {
+    out[k] = deepMerge(out[k], v);
+  }
+  return /** @type {T} */ (out);
+}
+
+/**
+ * Produce the wrangler config object by deep-merging a site manifest on top of
+ * the canonical template. The site's `worker_name` becomes wrangler's `name`.
+ *
+ * @param {Record<string, unknown>} template
+ * @param {SiteManifest} site
+ * @returns {Record<string, unknown>}
+ */
+export function mergeWithTemplate(template, site) {
+  const { worker_name, ...rest } = site;
+  const merged = deepMerge(template, rest);
+  return { name: worker_name, ...merged };
+}

package/scripts/deploy/wrangler-wrapper.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// deco-wrangler
+//
+// Local-dev wrapper around `wrangler` for storefront repos that no longer
+// commit a `wrangler.jsonc`. Generates the canonical config from
+// `@decocms/start`'s registry into `./wrangler.jsonc` (gitignored), then
+// optionally execs the real `wrangler` with that config in cwd.
+//
+// Usage from a customer repo (after `npm i -D @decocms/start@latest`):
+//
+//   npx deco-wrangler gen          # generate ./wrangler.jsonc and exit
+//                                  # (used by predev/prebuild/prepare hooks)
+//   npx deco-wrangler tail         # tail prod logs (worker name resolved automatically)
+//   npx deco-wrangler types        # regenerate worker-configuration.d.ts
+//   npx deco-wrangler deploy       # discouraged in dev; deploys go via CI
+//   npx deco-wrangler --help       # passes through to wrangler
+//
+// All non-`gen` invocations also (re)generate ./wrangler.jsonc first so the
+// file is always in sync with the registry before wrangler runs. The
+// `@cloudflare/vite-plugin` and the `wrangler` CLI both auto-discover
+// ./wrangler.jsonc in cwd, so no extra config plumbing is required.
+//
+// Site identity (which entry of `deploy/sites/` to load) resolves in this
+// order:
+//
+//   1. DECO_SITE_NAME env var (explicit override)
+//   2. git remote `origin` URL parsed for the GitHub repo name
+//   3. package.json `name` field
+//
+// Fails loudly if none of these match a registered site -- no implicit "guess
+// the worker" behavior. The local wrapper enforces the same trust model the CI
+// pipeline does.
+
+import { execSync, spawnSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadSiteManifest, loadTemplate, mergeWithTemplate } from "./site-registry.mjs";
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+// scripts/deploy/wrangler-wrapper.mjs -> deco-start root
+const DECO_START_PATH = resolve(SCRIPT_DIR, "..", "..");
+
+function eprintln(msg) {
+  process.stderr.write(`[deco-wrangler] ${msg}\n`);
+}
+
+function tryGitRemoteSiteName() {
+  try {
+    const url = execSync("git remote get-url origin", {
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+      .toString()
+      .trim();
+    // matches both git@github.com:org/repo(.git) and https://github.com/org/repo(.git)
+    const m = url.match(/github\.com[:/][^/]+\/([^/]+?)(?:\.git)?$/);
+    return m?.[1];
+  } catch {
+    return undefined;
+  }
+}
+
+function tryPackageJsonName() {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(process.cwd(), "package.json"), "utf8"));
+    return typeof pkg.name === "string" ? pkg.name : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveSiteName() {
+  const envName = process.env.DECO_SITE_NAME?.trim();
+  if (envName) return { name: envName, source: "DECO_SITE_NAME env var" };
+  const gitName = tryGitRemoteSiteName();
+  if (gitName) return { name: gitName, source: "git remote origin" };
+  const pkgName = tryPackageJsonName();
+  if (pkgName) return { name: pkgName, source: "package.json name" };
+  return undefined;
+}
+
+const resolved = resolveSiteName();
+if (!resolved) {
+  eprintln(
+    "Could not determine site name. Set DECO_SITE_NAME or run from a repo with a github.com 'origin' remote.",
+  );
+  process.exit(1);
+}
+
+let manifest;
+try {
+  manifest = loadSiteManifest(DECO_START_PATH, resolved.name);
+} catch (err) {
+  eprintln(err instanceof Error ? err.message : String(err));
+  eprintln(`Site name "${resolved.name}" was inferred from ${resolved.source}.`);
+  eprintln(
+    `If this is a personal sandbox, set DECO_SITE_NAME=<registered-site> or open a PR to deco-start adding deploy/sites/${resolved.name}.jsonc.`,
+  );
+  process.exit(1);
+}
+
+const merged = mergeWithTemplate(loadTemplate(DECO_START_PATH), manifest);
+
+const outputPath = resolve(process.cwd(), "wrangler.jsonc");
+const header = `// AUTOGENERATED by deco-wrangler -- DO NOT COMMIT.
+// Add wrangler.jsonc to .gitignore. Regenerated on every \`deco-wrangler\` run.
+// Source: @decocms/start deploy/sites/${resolved.name}.jsonc + wrangler-template.jsonc
+`;
+writeFileSync(outputPath, `${header}${JSON.stringify(merged, null, 2)}\n`);
+
+eprintln(
+  `Resolved site "${resolved.name}" -> worker "${manifest.worker_name}" (via ${resolved.source})`,
+);
+eprintln(`Generated ${outputPath}`);
+
+const argv = process.argv.slice(2);
+// `gen` mode: just write the config and exit. Used by package.json
+// predev/prebuild/prepare hooks to keep wrangler.jsonc in sync with the
+// registry without invoking wrangler itself.
+if (argv[0] === "gen" || argv[0] === "generate") {
+  process.exit(0);
+}
+
+const wranglerArgs = ["wrangler", ...argv];
+const result = spawnSync("npx", wranglerArgs, { stdio: "inherit" });
+process.exit(result.status ?? 1);

package/scripts/migrate/phase-scaffold.ts

@@ -5,7 +5,7 @@ import { log, logPhase } from "./types";
 import { generatePackageJson } from "./templates/package-json";
 import { generateTsconfig } from "./templates/tsconfig";
 import { generateViteConfig } from "./templates/vite-config";
-import { generateWrangler } from "./templates/wrangler";
+import { generateGithubWorkflows } from "./templates/github-workflows";
 import { generateKnipConfig } from "./templates/knip-config";
 import { generateRoutes } from "./templates/routes";
 import { generateSetup } from "./templates/setup";
@@ -50,13 +50,20 @@ function writeMultiFile(ctx: MigrationContext, files: Record<string, string>) {
 export function scaffold(ctx: MigrationContext): void {
   logPhase("Scaffold");
 
-  // Root config files
+  // Root config files. wrangler.jsonc is INTENTIONALLY not generated --
+  // per D6, the canonical wrangler config lives in decocms/deco-start under
+  // deploy/wrangler-template.jsonc and per-site overrides under
+  // deploy/sites/<repo>.jsonc; the file is materialized locally by
+  // `deco-wrangler gen` and gitignored.
   writeFile(ctx, "package.json", generatePackageJson(ctx));
   writeFile(ctx, "tsconfig.json", generateTsconfig());
   writeFile(ctx, "vite.config.ts", generateViteConfig(ctx));
-  writeFile(ctx, "wrangler.jsonc", generateWrangler(ctx));
   writeFile(ctx, "knip.config.ts", generateKnipConfig());
   writeFile(ctx, ".gitignore", generateGitignore());
+
+  // Caller workflow stubs that delegate to decocms/deco-start's reusable
+  // workflows. The customer repo holds no deploy logic of its own.
+  writeMultiFile(ctx, generateGithubWorkflows());
   writeFile(ctx, ".prettierrc", JSON.stringify({
     semi: true,
     singleQuote: false,
@@ -209,6 +216,9 @@ dist/
 # Cloudflare Workers
 .wrangler/
 .dev.vars
+# Generated by \`deco-wrangler\` from @decocms/start's central registry.
+# Source of truth lives in decocms/deco-start under deploy/sites/<repo>.jsonc.
+wrangler.jsonc
 
 # TanStack Router (auto-generated)
 src/routeTree.gen.ts

package/scripts/migrate/phase-verify.ts

@@ -13,7 +13,12 @@ const REQUIRED_FILES = [
   "package.json",
   "tsconfig.json",
   "vite.config.ts",
-  "wrangler.jsonc",
+  // wrangler.jsonc is INTENTIONALLY absent -- D6: it lives in decocms/deco-start
+  // under deploy/sites/<repo>.jsonc and is generated locally by `deco-wrangler gen`.
+  ".github/workflows/deploy.yml",
+  ".github/workflows/preview.yml",
+  ".github/workflows/regen-blocks.yml",
+  ".github/workflows/sync-secrets.yml",
   "knip.config.ts",
   ".prettierrc",
   "src/server.ts",

package/scripts/migrate/templates/github-workflows.ts

@@ -0,0 +1,98 @@
+// Caller workflow stubs for new sites. Each stub delegates to a reusable
+// workflow under `decocms/deco-start/.github/workflows/` -- the customer repo
+// holds no deploy/build logic of its own. See D6 in
+// `.cursor/rules/migration-tooling-policy.mdc` and the `deploy/` directory
+// for the central registry contract.
+
+const DEPLOY_YML = `name: Deploy
+
+# Thin caller for decocms/deco-start's central deploy workflow.
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    uses: decocms/deco-start/.github/workflows/deploy.yml@v2
+    secrets: inherit
+`;
+
+const PREVIEW_YML = `name: Preview
+
+# Thin caller for decocms/deco-start's central preview workflow.
+
+on:
+  repository_dispatch:
+    types: [preview-deploy]
+  pull_request:
+    types: [opened, synchronize, reopened]
+  push:
+    branches: ['env/**']
+
+permissions:
+  contents: read
+  pull-requests: write
+  statuses: write
+
+jobs:
+  preview:
+    uses: decocms/deco-start/.github/workflows/preview.yml@v2
+    secrets: inherit
+`;
+
+const REGEN_BLOCKS_YML = `name: Regenerate blocks.gen.json
+
+# Thin caller for decocms/deco-start's central regen-blocks workflow.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - ".deco/blocks/**"
+
+permissions:
+  contents: write
+
+jobs:
+  regen:
+    uses: decocms/deco-start/.github/workflows/regen-blocks.yml@v2
+    secrets: inherit
+`;
+
+const SYNC_SECRETS_YML = `name: Sync worker secrets
+
+# Thin caller for decocms/deco-start's central sync-secrets workflow.
+
+on:
+  workflow_dispatch:
+    inputs:
+      mode:
+        description: "dry-run = print diff only | apply = set secrets on worker"
+        required: true
+        default: "dry-run"
+        type: choice
+        options: [dry-run, apply]
+
+permissions:
+  contents: read
+
+jobs:
+  sync:
+    uses: decocms/deco-start/.github/workflows/sync-secrets.yml@v2
+    with:
+      mode: \${{ inputs.mode }}
+    secrets: inherit
+`;
+
+export function generateGithubWorkflows(): Record<string, string> {
+  return {
+    ".github/workflows/deploy.yml": DEPLOY_YML,
+    ".github/workflows/preview.yml": PREVIEW_YML,
+    ".github/workflows/regen-blocks.yml": REGEN_BLOCKS_YML,
+    ".github/workflows/sync-secrets.yml": SYNC_SECRETS_YML,
+  };
+}

package/scripts/migrate/templates/package-json.ts

@@ -109,8 +109,15 @@ export function generatePackageJson(ctx: MigrationContext): string {
       build:
         "npm run generate:blocks && npm run generate:sections && npm run generate:loaders && npm run generate:schema && npm run generate:invoke && tsr generate && vite build",
       preview: "vite preview",
-      deploy: "npm run build && wrangler deploy",
-      types: "wrangler types",
+      // wrangler.jsonc is generated by `deco-wrangler gen` from the central
+      // registry in @decocms/start (D6). Predev/prebuild ensure it is up to
+      // date before vite runs the @cloudflare/vite-plugin which reads it.
+      "gen:wrangler": "deco-wrangler gen",
+      predev: "deco-wrangler gen",
+      prebuild: "deco-wrangler gen",
+      deploy:
+        "echo 'Production deploys are managed by .github/workflows/deploy.yml on push to main. For an emergency manual deploy run: npx deco-wrangler deploy'; exit 1",
+      types: "deco-wrangler types",
       typecheck: "tsc --noEmit",
       format: 'prettier --write "src/**/*.{ts,tsx}"',
       "format:check": 'prettier --check "src/**/*.{ts,tsx}"',

package/scripts/migrate/templates/wrangler.ts

@@ -1,30 +0,0 @@
-import type { MigrationContext } from "../types";
-
-export function generateWrangler(ctx: MigrationContext): string {
-  const workerName = ctx.siteName
-    .toLowerCase()
-    .replace(/[^a-z0-9-]/g, "-")
-    .replace(/-+/g, "-");
-
-  return `{
-  "name": "${workerName}-tanstack",
-  // TODO: Set your Cloudflare account_id for deployment
-  // "account_id": "YOUR_ACCOUNT_ID",
-  "compatibility_date": "2026-02-14",
-  "compatibility_flags": ["nodejs_compat", "no_handle_cross_request_promise_resolution"],
-  "main": "./src/worker-entry.ts",
-  "workers_dev": true,
-  "preview_urls": true,
-  // Uncomment and set KV namespace ID for redirect/AB testing:
-  // "kv_namespaces": [
-  //   { "binding": "SITES_KV", "id": "YOUR_KV_NAMESPACE_ID" }
-  // ],
-  "observability": {
-    "logs": {
-      "enabled": true,
-      "invocation_logs": true
-    }
-  }
-}
-`;
-}