@decocms/start 2.30.1 → 3.0.0

package/deploy/README.md

@@ -1,111 +1,121 @@
-# `deploy/` — central deploy registry
+# `deploy/` — central wrangler template
 
-This directory is the single source of truth for **what gets deployed where**
-across every storefront on the platform. It is consumed by the reusable GitHub
-workflows under [`.github/workflows/`](../.github/workflows/) (`deploy.yml`,
-`preview.yml`, `sync-secrets.yml`) and by the local `deco-wrangler` CLI.
+This directory holds **`wrangler-template.jsonc`** — the canonical wrangler config
+that every storefront on the platform inherits. It is consumed by the reusable
+GitHub workflows under [`.github/workflows/`](../.github/workflows/)
+(`deploy.yml`, `preview.yml`, `sync-secrets.yml`) and by the local
+`deco-wrangler` CLI.
 
-## Files
-
-| File | Purpose |
-|------|---------|
-| `wrangler-template.jsonc` | Canonical wrangler config that every site inherits. Compatibility flags, worker-entry path, observability — everything that is the same for every site. |
-| `sites/<repo-name>.jsonc` | Per-site overrides. Only the keys that genuinely vary per-site live here (`worker_name` always; `routes`, `kv_namespaces`, `analytics_engine_datasets`, `version_metadata` when used). |
-
-The repository name (the part of `${{ github.repository }}` after the `/`) is
-the lookup key. `als-tanstack` deploys via `sites/als-tanstack.jsonc`. There is
-no other way to identify a site.
+There is **no per-site registry**. Worker name is the storefront repo basename
+by convention (`deco-sites/baggagio-tanstack` → worker `baggagio-tanstack`).
+Anything that must vary deterministically per worker (like the Analytics Engine
+dataset name) is encoded as a substitution token in the template — see
+[Substitution tokens](#substitution-tokens) below.
 
 ## Trust model
 
-- Customer caller workflows pass **no inputs** to the central reusable workflow.
-- The central workflow derives the site name from `${{ github.repository }}`
-  (set by GitHub, untamperable by user code) and looks up
-  `sites/<repo-name>.jsonc` from this registry.
-- A customer cannot misroute a deploy onto another customer's worker because
-  they can't write to `decocms/deco-start`.
-
-`deploy/**` is CODEOWNERS-protected. Only the platform team can change site
-manifests or the template.
+The deploy is gated by the `decocms-deployer` **GitHub App** being installed on
+the target storefront repo:
+
+1. The storefront's caller workflow mints a short-lived App-installation token.
+2. It calls `gh workflow run deploy.yml --repo decocms/deco-start -f site_owner=… -f site_name=…`.
+3. The central deploy workflow runs **in this repo's context** and itself mints
+   another short-lived App-installation token to check out the storefront. If
+   the App isn't installed on `<site_owner>/<site_name>`, the mint fails and
+   the deploy never starts.
+4. The central workflow then runs build + `wrangler deploy` using
+   `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` from this repo's plain
+   repo secrets.
+
+Properties this gives:
+
+- **CF credentials never leave decocms/deco-start.** The storefront repo holds
+  zero Cloudflare credentials — it only has the GitHub App credentials, which
+  can be used solely to trigger workflows on this repo.
+- **Worker naming is convention-based and not customer-controlled.** A
+  customer with push access to their own storefront cannot rename the worker
+  their deploy lands on (the central workflow always uses
+  `inputs.site_name` as the worker name; modifying the caller stub to pass a
+  different `site_name` would also require the App to be installed on that
+  other repo).
+- **Force-rollback is impossible for production.** The central deploy
+  workflow ignores any caller-supplied sha and always resolves the
+  storefront's current default-branch HEAD itself. The worst a compromised
+  storefront can do across tenants is trigger a no-op redeploy of another
+  storefront's current main.
+
+`deploy/` and `scripts/deploy/` and the central workflow files are
+CODEOWNERS-protected — only the platform team approves changes.
 
 ### Where Cloudflare credentials live
 
-`CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` live in **this repo's
-`production` GitHub Environment**, never in any storefront repo. The reusable
-workflows declare `environment: production` on the deploy / preview /
-sync-secrets jobs, which is what GitHub uses to resolve `secrets.CLOUDFLARE_*`
-against the called repo (deco-start) instead of the caller (the storefront).
-
-This is the second half of the trust property: even if a storefront repo were
-fully compromised, the attacker has no path to the Cloudflare token. The
-storefront repo only holds its own `SECRET_*` runtime secrets, which are
-inherited by `sync-secrets.yml` and pushed to its own worker as runtime
-secrets — never reaching another site's worker because the central workflow
-resolves `worker_name` from this registry, not from caller input.
-
-| Secret class | Lives in | Reaches worker via |
+| Secret class | Lives in | How it reaches the worker |
 |---|---|---|
-| `CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_ACCOUNT_ID` | this repo's `production` environment | central workflow's `environment:` binding (no caller passthrough) |
-| `SECRET_*` runtime secrets (per site) | each storefront repo | `sync-secrets.yml` inherits via `secrets: inherit` and pushes via `wrangler secret put` |
+| `CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_ACCOUNT_ID` | this repo's **repo secrets** | central workflow runs in this repo's context, env-var resolves natively |
+| `DECOCMS_DEPLOYER_APP_ID` / `DECOCMS_DEPLOYER_APP_PRIVATE_KEY` | this repo's repo secrets AND deco-sites org-level secrets | mints short-lived installation tokens for both directions of the dispatch flow |
+| `SECRET_*` runtime secrets (per site) | this repo's `<site_name>-secrets` GitHub Environment | `sync-secrets.yml` binds to that environment, reads `SECRET_*` from `${{ secrets }}`, runs `wrangler secret put` |
 
-To rotate the Cloudflare credentials, edit the environment in this repo only.
-No storefront PR needed.
+To rotate Cloudflare credentials, edit them in this repo only. To rotate a
+runtime secret for one storefront, edit the corresponding environment in this
+repo only. No storefront PR needed for either.
 
-## How wrangler.jsonc is generated
+## How `wrangler.jsonc` is generated
 
 At deploy time, the central workflow runs
 [`scripts/deploy/build-wrangler-config.mjs`](../scripts/deploy/build-wrangler-config.mjs),
 which:
 
-1. Loads `deploy/wrangler-template.jsonc` (canonical defaults).
-2. Loads `deploy/sites/<site>.jsonc` (per-site overrides).
-3. Deep-merges: site overrides win. `worker_name` becomes wrangler's `name`.
-   Arrays are replaced, not concatenated.
-4. Writes the result to `./wrangler.jsonc` in the caller checkout.
+1. Loads `deploy/wrangler-template.jsonc`.
+2. Substitutes `$WORKER_*` tokens (see below) using the worker name passed by
+   the central workflow (= storefront repo basename).
+3. Writes the result to `./wrangler.jsonc` in the storefront checkout, with
+   `name` injected as the first key.
 
 `account_id` is never written to JSON — wrangler reads it from
-`CLOUDFLARE_ACCOUNT_ID` (env var in CI; `wrangler login` locally).
+`CLOUDFLARE_ACCOUNT_ID` (env var in CI; `wrangler login` locally). This way a
+typo cannot misroute a deploy to a different Cloudflare account.
+
+### Substitution tokens
+
+Any string in the template containing one of these literals is replaced at
+build time:
+
+| Token | Replacement | Example use |
+|---|---|---|
+| `$WORKER_NAME` | worker name verbatim | rare; mostly available for parity |
+| `$WORKER_UNDERSCORE` | worker name with `-` → `_` | `analytics_engine_datasets[].dataset` (must be a valid Postgres-style identifier) |
+
+To add a new derived field, add the token wherever it makes sense in
+`wrangler-template.jsonc`. Anything not in the substitution table appears
+verbatim in the generated config.
 
 ## Adding a new site
 
-1. Open a PR to this repo adding `deploy/sites/<new-repo>.jsonc`:
-   ```jsonc
-   {
-     "worker_name": "<new-repo>"   // can differ from repo name if needed
-   }
-   ```
-2. After merge, the next `v2.x.y` semantic-release publish auto-moves the
-   `@v2` major tag (the major-tag advance step lives inline in
-   [`.github/workflows/release.yml`](../.github/workflows/release.yml)).
-3. In the new repo, add the four caller workflows from
-   [`.github/workflows/`](../.github/workflows/). **Do not** add
-   `CLOUDFLARE_*` to the storefront — those live in this repo's `production`
-   environment and reach the runner via the central workflow's `environment:`
-   binding. The storefront only needs `SECRET_*` entries for its own worker
-   runtime secrets.
-4. Push to `main` and verify the deploy lands on the right worker.
-
-## Per-site override schema
-
-```jsonc
-{
-  "worker_name": "string (required, immutable)",
-  "routes": [                          // optional
-    { "pattern": "www.example.com/*", "zone_name": "decocdn.com" }
-  ],
-  "kv_namespaces": [                   // optional
-    { "binding": "SITES_KV", "id": "<cf-kv-id>" }
-  ],
-  "analytics_engine_datasets": [       // optional
-    { "binding": "DECO_METRICS", "dataset": "deco_metrics_<site>" }
-  ],
-  "version_metadata": {                // optional
-    "binding": "CF_VERSION_METADATA"
-  }
-}
-```
-
-All other wrangler keys (compatibility flags, `main`, observability, etc.) come
-from the template — do not duplicate them per-site. If a per-site override is
-genuinely needed for one of those keys, add it to the schema and document the
-reason here.
+1. Install the `decocms-deployer` GitHub App on the new storefront repo
+   (Settings → Integrations → GitHub Apps in the deco-sites org).
+2. Add the four caller workflow stubs to the new repo (copy from any existing
+   storefront's `.github/workflows/{deploy,preview,sync-secrets,regen-blocks}.yml`).
+3. Add `wrangler.jsonc` to the new repo's `.gitignore` and add the
+   `gen:wrangler` / `predev` / `prebuild` / `types` scripts to `package.json`
+   so local dev still works (use any existing storefront as a template).
+4. If the site needs runtime secrets, create a new environment in this repo
+   named `<repo-basename>-secrets` and add the `SECRET_*` values there. Set
+   environment protection rules to grant the site team self-service access to
+   their own environment.
+5. Push to `main` and verify the deploy lands on a worker named after the repo.
+
+## Migrating an existing site whose worker name doesn't match its repo
+
+Two cases to be aware of:
+
+- **Worker rename.** The worker created by the first deploy will use the repo
+  basename. If an old worker exists with a different name (e.g.
+  `miess-01-tanstack` repo whose old worker was `miess-tanstack`), you'll need
+  a manual cutover: deploy the new worker, re-attach custom domain routes via
+  the Cloudflare dashboard, copy any wrangler secrets, then delete the old
+  worker. There is intentionally no per-site override for this — these cases
+  are rare and best resolved at the CF layer.
+- **AE dataset rename.** The dataset name is derived from worker name, so a
+  worker rename also changes the AE dataset. Old data remains queryable under
+  the old dataset name; new data goes to the new name. Update Grafana panels
+  and saved queries accordingly.

package/deploy/wrangler-template.jsonc

@@ -1,15 +1,26 @@
 // Canonical wrangler.jsonc template for every storefront on the platform.
 //
-// Per-site overrides live in `deploy/sites/<repo-name>.jsonc`. The deploy
-// workflow deep-merges site overrides on top of this template at runtime and
-// writes the result to `wrangler.jsonc` in the caller checkout. Site overrides
-// always win. Arrays are replaced (not concatenated).
+// There is no per-site registry. Worker name == storefront repo basename by
+// convention; the central deploy workflows pass `WORKER_NAME` to the build
+// script, which substitutes `$WORKER_*` tokens in this template and writes
+// the result to `wrangler.jsonc` in the caller checkout.
+//
+// Substitution tokens (see scripts/deploy/site-registry.mjs):
+//   $WORKER_NAME        -> worker name verbatim         (e.g. "als-tanstack")
+//   $WORKER_UNDERSCORE  -> worker name, `-` -> `_`      (e.g. "als_tanstack")
+//
+// To upgrade compatibility flags, observability, KV bindings, or any field
+// that should change for every site at once, change this file and tag a new
+// deco-start release.
 //
 // Notes on what is INTENTIONALLY missing here:
 //   - "name" -- always derived from the per-site `worker_name`.
 //   - "account_id" -- never lives in the JSON. Wrangler reads it from the
 //     CLOUDFLARE_ACCOUNT_ID env var in CI and from local config otherwise.
 //     This way, a typo in JSON cannot misroute a deploy.
+//   - "routes" -- production custom domains are managed in the Cloudflare
+//     dashboard, not in JSON. Avoids drift between JSON and CF reality and
+//     means a site going live doesn't need a deco-start PR.
 //
 // To upgrade compatibility flags, observability, or worker-entry path across
 // every site at once, change this file and tag a new deco-start release.
@@ -19,6 +30,13 @@
   "main": "./src/worker-entry.ts",
   "workers_dev": true,
   "preview_urls": true,
+  "kv_namespaces": [
+    { "binding": "SITES_KV", "id": "ad0b74fc4d9341c9af9149c4ab85132f" }
+  ],
+  "version_metadata": { "binding": "CF_VERSION_METADATA" },
+  "analytics_engine_datasets": [
+    { "binding": "DECO_METRICS", "dataset": "deco_metrics_$WORKER_UNDERSCORE" }
+  ],
   "observability": {
     "logs": {
       "enabled": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.30.1",
+  "version": "3.0.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/scripts/deploy/build-wrangler-config.mjs

@@ -1,19 +1,20 @@
 #!/usr/bin/env node
 // build-wrangler-config.mjs
 //
-// Materializes a `wrangler.jsonc` from the canonical template + the site's
-// per-site overrides. The output file is what `wrangler deploy` /
+// Materializes a `wrangler.jsonc` from the canonical template, with
+// $WORKER_* tokens substituted. The output file is what `wrangler deploy` /
 // `wrangler versions upload` / `wrangler secret put` will read.
 //
 // Required env:
 //   DECO_START_PATH  - path to a checked-out deco-start (e.g. ".deco-start")
-//   SITE_NAME        - the registry key (== caller repo name)
+//   WORKER_NAME      - the Cloudflare worker name (= storefront repo basename
+//                      by convention; passed by the central CI workflows)
 //   OUTPUT_PATH      - where to write the merged wrangler.jsonc
 //                      (e.g. "./wrangler.jsonc" in the caller checkout)
 
 import { writeFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { loadSiteManifest, loadTemplate, mergeWithTemplate } from "./site-registry.mjs";
+import { applyWorkerName, loadTemplate } from "./site-registry.mjs";
 
 function fail(message) {
   console.error(`::error::${message}`);
@@ -21,29 +22,26 @@ function fail(message) {
 }
 
 const decoStartPath = process.env.DECO_START_PATH;
-const siteName = process.env.SITE_NAME;
+const workerName = process.env.WORKER_NAME;
 const outputPath = process.env.OUTPUT_PATH;
 
 if (!decoStartPath) fail("DECO_START_PATH env var is required");
-if (!siteName) fail("SITE_NAME env var is required");
+if (!workerName) fail("WORKER_NAME env var is required");
 if (!outputPath) fail("OUTPUT_PATH env var is required");
 
 let merged;
 try {
-  const template = loadTemplate(decoStartPath);
-  const manifest = loadSiteManifest(decoStartPath, siteName);
-  merged = mergeWithTemplate(template, manifest);
+  merged = applyWorkerName(loadTemplate(decoStartPath), workerName);
 } catch (err) {
   fail(err instanceof Error ? err.message : String(err));
 }
 
 const header = `// AUTOGENERATED by @decocms/start at deploy time.
 // Do not edit -- changes will be overwritten on the next deploy.
-// Source: decocms/deco-start deploy/sites/${siteName}.jsonc
-//         + decocms/deco-start deploy/wrangler-template.jsonc
+// Source: decocms/deco-start deploy/wrangler-template.jsonc + worker name "${workerName}"
 `;
 
 const body = JSON.stringify(merged, null, 2);
 writeFileSync(resolve(outputPath), `${header}${body}\n`);
 
-console.log(`Wrote ${outputPath} for site "${siteName}" (worker "${merged.name}")`);
+console.log(`Wrote ${outputPath} (worker "${workerName}")`);

package/scripts/deploy/site-registry.mjs

@@ -1,36 +1,23 @@
-// Shared registry helpers for the deploy scripts.
+// Template loader + token substitution for the canonical wrangler config.
 //
-// `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.
+// There is no per-site "registry" anymore: every site's wrangler config is
+// produced from `deploy/wrangler-template.jsonc` plus the worker name (which
+// equals the storefront repo basename by convention). To accommodate fields
+// that must vary deterministically per worker, the template can use these
+// substitution tokens, which are replaced at config-build time:
 //
-// 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.
+//   $WORKER_NAME        -> worker name verbatim     (e.g. "als-tanstack")
+//   $WORKER_UNDERSCORE  -> worker name, `-` -> `_`  (e.g. "als_tanstack")
+//
+// Trust model: callers cannot pass a fabricated worker name to the central
+// CI workflows -- the deploy is gated by the `decocms-deployer` GitHub App
+// being installed on the target storefront repo. If the App isn't installed
+// there, the App-token mint fails and the deploy never starts.
 
 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}
@@ -39,56 +26,6 @@ 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>}
@@ -106,37 +43,53 @@ export function loadTemplate(decoStartPath) {
 }
 
 /**
- * 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.
+ * Recursively replace `$WORKER_*` tokens in any string value of an
+ * object/array tree. Returns a new tree.
  *
- * @template T
- * @param {T} target
- * @param {unknown} source
- * @returns {T}
+ * @param {unknown} value
+ * @param {Record<string, string>} replacements
+ * @returns {unknown}
  */
-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);
+function substituteTokens(value, replacements) {
+  if (typeof value === "string") {
+    let out = value;
+    for (const [token, repl] of Object.entries(replacements)) {
+      out = out.split(token).join(repl);
+    }
+    return out;
   }
-  return /** @type {T} */ (out);
+  if (Array.isArray(value)) {
+    return value.map((v) => substituteTokens(v, replacements));
+  }
+  if (value && typeof value === "object") {
+    const out = /** @type {Record<string, unknown>} */ ({});
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = substituteTokens(v, replacements);
+    }
+    return out;
+  }
+  return value;
 }
 
 /**
- * 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`.
+ * Produce the wrangler config object by substituting `$WORKER_*` tokens in
+ * the template and prepending `name`.
  *
  * @param {Record<string, unknown>} template
- * @param {SiteManifest} site
+ * @param {string} workerName
  * @returns {Record<string, unknown>}
  */
-export function mergeWithTemplate(template, site) {
-  const { worker_name, ...rest } = site;
-  const merged = deepMerge(template, rest);
-  return { name: worker_name, ...merged };
+export function applyWorkerName(template, workerName) {
+  if (typeof workerName !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(workerName)) {
+    throw new Error(
+      `Invalid worker name: ${JSON.stringify(workerName)}. Use lowercase, hyphen-separated.`,
+    );
+  }
+  const substituted = /** @type {Record<string, unknown>} */ (
+    substituteTokens(template, {
+      $WORKER_UNDERSCORE: workerName.replace(/-/g, "_"),
+      $WORKER_NAME: workerName,
+    })
+  );
+  return { name: workerName, ...substituted };
 }

package/scripts/deploy/wrangler-wrapper.mjs

@@ -3,7 +3,7 @@
 //
 // 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
+// `@decocms/start`'s template 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`):
@@ -16,26 +16,25 @@
 //   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
+// file is always in sync with the template 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:
+// Worker name resolves in this order:
 //
-//   1. DECO_SITE_NAME env var (explicit override)
-//   2. git remote `origin` URL parsed for the GitHub repo name
+//   1. DECO_WORKER_NAME env var (explicit override)
+//   2. git remote `origin` URL parsed for the GitHub repo basename
 //   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.
+// By convention worker name == storefront repo basename. The CI deploys use
+// the same convention. Local dev never deploys -- this wrapper is purely for
+// generating a config that matches what the central workflow will produce.
 
 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";
+import { applyWorkerName, loadTemplate } from "./site-registry.mjs";
 
 const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
 // scripts/deploy/wrangler-wrapper.mjs -> deco-start root
@@ -45,7 +44,7 @@ function eprintln(msg) {
   process.stderr.write(`[deco-wrangler] ${msg}\n`);
 }
 
-function tryGitRemoteSiteName() {
+function tryGitRemoteWorkerName() {
   try {
     const url = execSync("git remote get-url origin", {
       stdio: ["ignore", "pipe", "ignore"],
@@ -69,54 +68,47 @@ function tryPackageJsonName() {
   }
 }
 
-function resolveSiteName() {
-  const envName = process.env.DECO_SITE_NAME?.trim();
-  if (envName) return { name: envName, source: "DECO_SITE_NAME env var" };
-  const gitName = tryGitRemoteSiteName();
+function resolveWorkerName() {
+  const envName = process.env.DECO_WORKER_NAME?.trim();
+  if (envName) return { name: envName, source: "DECO_WORKER_NAME env var" };
+  const gitName = tryGitRemoteWorkerName();
   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();
+const resolved = resolveWorkerName();
 if (!resolved) {
   eprintln(
-    "Could not determine site name. Set DECO_SITE_NAME or run from a repo with a github.com 'origin' remote.",
+    "Could not determine worker name. Set DECO_WORKER_NAME or run from a repo with a github.com 'origin' remote.",
   );
   process.exit(1);
 }
 
-let manifest;
+let merged;
 try {
-  manifest = loadSiteManifest(DECO_START_PATH, resolved.name);
+  merged = applyWorkerName(loadTemplate(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.`,
-  );
+  eprintln(`Worker name "${resolved.name}" was inferred from ${resolved.source}.`);
   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
+// Source: @decocms/start deploy/wrangler-template.jsonc + worker name "${resolved.name}"
 `;
 writeFileSync(outputPath, `${header}${JSON.stringify(merged, null, 2)}\n`);
 
-eprintln(
-  `Resolved site "${resolved.name}" -> worker "${manifest.worker_name}" (via ${resolved.source})`,
-);
+eprintln(`Resolved worker name "${resolved.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.
+// template without invoking wrangler itself.
 if (argv[0] === "gen" || argv[0] === "generate") {
   process.exit(0);
 }