@decocms/start 2.30.0 → 3.0.0

package/.agents/skills/deco-to-tanstack-migration/references/worker-cloudflare.md

@@ -58,9 +58,10 @@ export default createDecoWorkerEntry(serverEntry, {
 ```
 
 The `main` field is set centrally so a future migration of the entry path
-applies to every site at once (single PR to the template). If you ever need to
-override `main` for a single site, add it under `deploy/sites/<repo>.jsonc` —
-never to a per-site `wrangler.jsonc` (sites don't commit one; see D6).
+applies to every site at once (single PR to the template). There is no
+per-site override file (D6.2 Pure C); if a single site truly needs a different
+entry path, change the template (and accept that all sites get it) or add a
+substitution token like `$WORKER_ENTRY_PATH` and feed it from a per-site env.
 
 This ensures admin route interception AND edge caching survive the build because they're in the Worker's own fetch handler, outside of TanStack's build pipeline.
 
@@ -211,22 +212,26 @@ Or in project `.npmrc` with an env var (for CI):
 **Tradeoff with `github:` syntax**: No semver resolution — `npm update` is meaningless. Pin to a tag for stability: `github:decocms/deco-start#v0.14.2`. Without a tag, you get HEAD of the default branch.
 
 
-## 46. Central Deploy / Wrangler Config (D6)
+## 46. Central Deploy / Wrangler Config (D6.2)
 
-**Severity**: HIGH — site repos must NOT commit `wrangler.jsonc` or per-site deploy logic. Doing so reintroduces drift.
+**Severity**: HIGH — site repos must NOT commit `wrangler.jsonc`, must NOT hold
+Cloudflare credentials, and must NOT have per-site deploy logic. Doing so
+reintroduces drift and breaks the trust model.
 
-Per [D6](../../../../.cursor/rules/migration-tooling-policy.mdc), all
+Per [D6.2](../../../../.cursor/rules/migration-tooling-policy.mdc), all
 storefronts deploy via reusable workflows shipped from
-`decocms/deco-start/.github/workflows/{deploy,preview,sync-secrets,regen-blocks}.yml@v2`.
-The canonical `wrangler.jsonc` lives at
-`decocms/deco-start/deploy/wrangler-template.jsonc`; per-site overrides live at
-`decocms/deco-start/deploy/sites/<repo-name>.jsonc`. The two are deep-merged at
-deploy time and written to a generated `wrangler.jsonc` in the runner; site
-repos gitignore the file.
+`decocms/deco-start/.github/workflows/{deploy,preview,sync-secrets,regen-blocks}.yml@v3`.
+There is no per-site registry: worker name == storefront repo basename by
+convention. The canonical `wrangler.jsonc` lives at
+`decocms/deco-start/deploy/wrangler-template.jsonc`; the build script
+substitutes `$WORKER_NAME` / `$WORKER_UNDERSCORE` tokens at deploy time and
+writes a generated `wrangler.jsonc` in the runner. Site repos gitignore the
+file.
 
 ### What goes in the site repo
 
-Four ~5-line caller workflow stubs and nothing else:
+Four caller workflow stubs that mint a `decocms-deployer` GitHub App
+installation token and call `gh workflow run` on `decocms/deco-start@v3`:
 
 ```yaml
 # .github/workflows/deploy.yml
@@ -235,31 +240,48 @@ on:
   push:
     branches: [main]
 permissions:
-  contents: write
+  contents: read
 jobs:
-  deploy:
-    uses: decocms/deco-start/.github/workflows/deploy.yml@v2
-    secrets: inherit
+  trigger:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/create-github-app-token@v1
+        id: app-token
+        with:
+          app-id: ${{ secrets.DECOCMS_DEPLOYER_APP_ID }}
+          private-key: ${{ secrets.DECOCMS_DEPLOYER_APP_PRIVATE_KEY }}
+          owner: decocms
+          repositories: deco-start
+      - env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          gh workflow run deploy.yml \
+            --repo decocms/deco-start \
+            --ref v3 \
+            -f site_owner=${GITHUB_REPOSITORY%%/*} \
+            -f site_name=${GITHUB_REPOSITORY##*/}
 ```
 
 (Plus equivalent `preview.yml`, `regen-blocks.yml`, `sync-secrets.yml` —
 see `scripts/migrate/templates/github-workflows.ts` for the canonical text.)
-The migration script generates these for new sites; the same stubs are
-hand-applied to existing sites.
-
-### What goes in `decocms/deco-start/deploy/sites/<repo>.jsonc`
-
-The minimum:
-
-```jsonc
-{
-  "worker_name": "<repo-name>"
-}
-```
-
-Plus optional `routes`, `kv_namespaces`, `analytics_engine_datasets`,
-`version_metadata` for the few sites that need them. Adding a new site is a
-PR to deco-start, not a change to the site repo.
+The migration script generates these for new sites.
+
+### App + secrets setup (one-time, per org)
+
+1. Create a `decocms-deployer` GitHub App with permissions
+   `Actions: Write`, `Contents: Read`, `Pull requests: Write` (the last
+   only needed if you want preview URLs commented on PRs),
+   `Metadata: Read`. Install it on `decocms/deco-start` and on each
+   storefront repo (or whole-org install on `deco-sites`).
+2. Store the App ID and private key as `deco-sites` org-level secrets
+   `DECOCMS_DEPLOYER_APP_ID` and `DECOCMS_DEPLOYER_APP_PRIVATE_KEY` so every
+   storefront workflow can mint installation tokens without per-repo setup.
+3. Store `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` as plain repo
+   secrets in `decocms/deco-start` (NOT in any storefront).
+4. For each storefront that has runtime secrets: create a GitHub Environment
+   in `decocms/deco-start` named `<storefront-repo-basename>-secrets`, add
+   the `SECRET_*` values there, and configure protection rules to grant the
+   site team self-service access to that environment only.
 
 ### Local dev
 
@@ -277,16 +299,31 @@ Site repos add three package.json hooks so vite picks up the generated
 ```
 
 `deco-wrangler` is a `bin` shipped from `@decocms/start` that materializes the
-canonical config from the central registry, then either exits (`gen` mode) or
-execs the real `wrangler` with that config in cwd.
+canonical config from the central template (worker name inferred from git
+remote / package.json), then either exits (`gen` mode) or execs the real
+`wrangler` with that config in cwd.
 
 ### Trust model
 
-- The central workflow ignores all caller `inputs:` for site identity.
-- Site name is derived from `${{ github.repository }}` (set by GitHub,
-  untamperable by user code) and looked up in `deploy/sites/<repo>.jsonc`.
-- A customer cannot misroute their deploy onto another site's worker
-  because they can't write to `decocms/deco-start` (CODEOWNERS-protected).
+- **Authorization gate**: the deploy can only start if the
+  `decocms-deployer` App is installed on the target storefront repo. The
+  central workflow's App-token mint step fails with a clear error otherwise.
+- **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 uses `inputs.site_name` as the
+  worker name; modifying their stub to pass a different `site_name` would
+  also require the App to be installed on that other repo).
+- **Cloudflare credentials never leave `decocms/deco-start`.** The central
+  workflow runs in deco-start's context, so the env-var resolves natively
+  from repo secrets.
+- **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.
+- **Per-site runtime secrets** (`SECRET_*`) live in deco-start environments,
+  not storefront repos. The storefront caller stub for `sync-secrets.yml`
+  triggers a workflow that binds to the matching env and runs
+  `wrangler secret put`. The storefront repo holds zero secrets beyond the
+  `decocms-deployer` App credentials.
 
 ### Common mistakes (do not do these)
 
@@ -295,12 +332,17 @@ execs the real `wrangler` with that config in cwd.
 - **Adding a site-local `deploy.yml` step** (e.g. cache purge after deploy).
   Add it to `deco-start/.github/workflows/deploy.yml` instead so every site
   picks it up at once.
+- **Adding `CLOUDFLARE_*` to a storefront repo's secrets.** They never
+  belong there. The central workflow runs in deco-start's context.
+- **Adding `SECRET_*` to a storefront repo's secrets.** They live in the
+  matching `<site_name>-secrets` environment in deco-start.
 - **Hard-coding `account_id` in a site's wrangler config.** It comes from
-  `CLOUDFLARE_ACCOUNT_ID` (org-level GitHub secret in CI; `wrangler login`
-  locally). Removing it from JSON is the one-way protection against
-  accidentally deploying to the wrong account.
-- **Setting `worker_name` to anything other than the repo name** without
-  a strong reason. The 1:1 binding makes audit (and incident response)
-  trivial. Exceptions today: `casaevideo-storefront` -> `casaevideo-tanstack`
-  and `miess-01-tanstack` -> `miess-tanstack` (both for historical
-  Cloudflare worker names that predate the repo).
+  `CLOUDFLARE_ACCOUNT_ID` (in CI; `wrangler login` locally) — keeping
+  it out of JSON is the one-way protection against accidentally deploying
+  to the wrong account.
+- **Trying to override the worker name** for one site. There is no
+  per-site override mechanism in D6.2. If the worker MUST be named
+  differently from the repo, the right answer is either to rename the
+  repo to match (cleanest) or to do a CF-side migration (deploy a new
+  worker with the repo-name and re-attach routes). This trade-off was
+  taken intentionally in exchange for the registry-free architecture.

package/.cursor/rules/migration-tooling-policy.mdc

@@ -76,24 +76,51 @@ Failure modes get documented in skills, not encoded as escape hatches.
 **Agent behavior**: when a migration goes sideways, propose deletion +
 re-run, not in-place repair. Add the failure mode to the skill.
 
-### D6 — Deploy / preview / secrets pipelines: centralize in `deco-start` (signed off 2026-05-07)
+### D6.2 — App-mediated dispatch + no per-site registry (signed off 2026-05-07; supersedes D6 + D6.1)
 All storefronts deploy via reusable workflows under
-`decocms/deco-start/.github/workflows/{deploy,preview,sync-secrets,regen-blocks}.yml@v2`.
-Per-site overrides live in [`deploy/sites/<repo>.jsonc`](../../deploy/) and
-are deep-merged on top of [`deploy/wrangler-template.jsonc`](../../deploy/wrangler-template.jsonc)
-at deploy time. **Customer repos do not commit `wrangler.jsonc`** — it is
-generated locally by `deco-wrangler gen` (a `bin` shipped from
-`@decocms/start`) and gitignored. The repo→worker binding is the trust
-boundary: the central workflow ignores caller `inputs:` for identity and
-derives the site name from `${{ github.repository }}`. `deploy/**` is
+`decocms/deco-start/.github/workflows/{deploy,preview,sync-secrets,regen-blocks}.yml@v3`.
+Storefront caller stubs mint a short-lived **`decocms-deployer` GitHub App**
+installation token (App ID + private key live as `deco-sites` org-level
+secrets) and call `gh workflow run deploy.yml --repo decocms/deco-start --ref v3
+-f site_owner=… -f site_name=…`. The central workflow runs in
+**`decocms/deco-start`'s context**, so `CLOUDFLARE_API_TOKEN` and
+`CLOUDFLARE_ACCOUNT_ID` are ordinary repo secrets in `decocms/deco-start`
+and never leave it.
+
+There is **no per-site registry under `deploy/sites/`**. Worker name == storefront
+repo basename by convention. Per-worker derived fields use `$WORKER_NAME` /
+`$WORKER_UNDERSCORE` substitution tokens in
+[`deploy/wrangler-template.jsonc`](../../deploy/wrangler-template.jsonc).
+The deploy authorization gate is the App being installed on the storefront
+repo — if it isn't, the App-token mint inside the central workflow fails and
+the deploy never starts. **Customer repos do not commit `wrangler.jsonc`** —
+it is generated locally by `deco-wrangler gen` (a `bin` shipped from
+`@decocms/start`) and gitignored.
+
+Production deploys are **force-rollback proof**: the central workflow ignores
+any caller-supplied `site_sha` and 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.
+
+`SECRET_*` runtime secrets live in **`decocms/deco-start`** as well, in
+per-storefront GitHub Environments named `<site_name>-secrets`. `sync-secrets.yml`
+binds to the matching environment and runs `wrangler secret put`. Site teams
+get edit/approve permission on their own environment via Environment
+protection rules. **The storefront repo holds zero secrets** beyond the
+App credentials (which only grant the ability to trigger workflows on
+`decocms/deco-start`).
+
+`deploy/`, `scripts/deploy/`, and the central workflow files are
 CODEOWNERS-protected.
 
 **Agent behavior**: when adding or migrating a site, do **not** generate a
-per-site `wrangler.jsonc` or per-site `deploy.yml` / `preview.yml` /
-`sync-secrets.yml` / `regen-blocks.yml`. The site repo gets the four
-~5-line caller stubs only. Per-site config goes in a PR to
-`decocms/deco-start` adding `deploy/sites/<repo>.jsonc`. Do not commit
-`wrangler.jsonc` or any wrangler config to a site repo.
+per-site `wrangler.jsonc`, do **not** generate a `deploy/sites/<repo>.jsonc`
+file (that whole directory was removed in D6.2), and do **not** add
+`CLOUDFLARE_*` or `SECRET_*` to a storefront repo's secrets. The site repo
+gets four ~15-line caller stubs that mint a `decocms-deployer` App token and
+fire `workflow_dispatch` at `decocms/deco-start@v3`; the App ID + private key
+live as `deco-sites` org-level secrets `DECOCMS_DEPLOYER_APP_ID` and
+`DECOCMS_DEPLOYER_APP_PRIVATE_KEY`.
 
 ## Priority order
 

package/.github/workflows/deploy.yml

@@ -1,115 +1,141 @@
 name: deploy (central)
 
-# Reusable workflow that drives `wrangler deploy` for any storefront repo
-# registered under `deploy/sites/<repo-name>.jsonc`.
+# Reusable workflow that drives `wrangler deploy` for any storefront repo.
+# Worker name is the storefront repo basename by convention; there is no
+# per-site registry. The deploy is gated by the `decocms-deployer` GitHub App
+# being installed on the target storefront repo -- the App-token mint fails
+# (and the deploy never starts) if the App isn't installed there.
 #
-# Site identity (worker name, KV bindings, routes, ...) is derived ONLY from
-# `${{ github.repository }}` and the registry checked in to deco-start. The
-# caller cannot pass an `inputs:` block to override the worker name -- this is
-# the trust boundary that prevents one site's commits from deploying on top of
-# another site's worker.
+# v3 architecture (D6.2): triggered via `workflow_dispatch` from the storefront,
+# authenticated as the `decocms-deployer` GitHub App. The deploy runs IN THIS
+# REPO'S CONTEXT, so `CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_ACCOUNT_ID` resolve
+# from this repo's plain repo secrets and never leave decocms/deco-start.
 #
-# Caller usage (in customer repo, `.github/workflows/deploy.yml`):
+# Caller usage (in the storefront repo, `.github/workflows/deploy.yml`):
 #
 #   on:
 #     push:
 #       branches: [main]
 #   permissions:
-#     contents: write
+#     contents: read
 #   jobs:
-#     deploy:
-#       uses: decocms/deco-start/.github/workflows/deploy.yml@v2
-#       secrets: inherit
+#     trigger:
+#       runs-on: ubuntu-latest
+#       steps:
+#         - uses: actions/create-github-app-token@v1
+#           id: app-token
+#           with:
+#             app-id: ${{ secrets.DECOCMS_DEPLOYER_APP_ID }}
+#             private-key: ${{ secrets.DECOCMS_DEPLOYER_APP_PRIVATE_KEY }}
+#             owner: decocms
+#             repositories: deco-start
+#         - env:
+#             GH_TOKEN: ${{ steps.app-token.outputs.token }}
+#           run: |
+#             gh workflow run deploy.yml \
+#               --repo decocms/deco-start \
+#               --ref v3 \
+#               -f site_owner=${GITHUB_REPOSITORY%%/*} \
+#               -f site_name=${GITHUB_REPOSITORY##*/}
 
 on:
-  workflow_call:
-    secrets:
-      CLOUDFLARE_API_TOKEN:
-        required: true
-      CLOUDFLARE_ACCOUNT_ID:
+  workflow_dispatch:
+    inputs:
+      site_owner:
+        description: "GitHub org of the storefront (e.g. deco-sites). Defaults to deco-sites."
+        type: string
+        required: false
+        default: deco-sites
+      site_name:
+        description: "Storefront repo basename. Becomes the Cloudflare worker name."
+        type: string
         required: true
 
 permissions:
-  contents: write
+  contents: read
 
 concurrency:
-  group: deploy-${{ github.repository }}
+  group: deploy-${{ inputs.site_owner }}-${{ inputs.site_name }}
   cancel-in-progress: false
 
 jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout caller repo
+      - name: Checkout deco-start (template + scripts)
         uses: actions/checkout@v4
 
-      - name: Resolve deco-start ref + site identity
-        id: meta
+      - name: Mint App token for storefront checkout
+        id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ secrets.DECOCMS_DEPLOYER_APP_ID }}
+          private-key: ${{ secrets.DECOCMS_DEPLOYER_APP_PRIVATE_KEY }}
+          owner: ${{ inputs.site_owner }}
+          repositories: ${{ inputs.site_name }}
+
+      # SECURITY: production deploys IGNORE any caller-supplied sha. The deploy
+      # always targets the storefront's CURRENT default-branch HEAD. This means
+      # an attacker with push to repo A who triggers a deploy of repo B can
+      # only force a no-op redeploy of B's current main -- they cannot select
+      # an arbitrary historical commit (no force-rollback attack).
+      - name: Resolve target sha (storefront default branch HEAD)
+        id: target
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          SITE_REPO: ${{ inputs.site_owner }}/${{ inputs.site_name }}
         run: |
-          # github.workflow_ref looks like
-          #   decocms/deco-start/.github/workflows/deploy.yml@refs/tags/v1
-          # or
-          #   decocms/deco-start/.github/workflows/deploy.yml@refs/heads/main
-          WF_REF="${{ github.workflow_ref }}"
-          REF="${WF_REF##*@}"
-          REF="${REF#refs/tags/}"
-          REF="${REF#refs/heads/}"
-          echo "deco_start_ref=$REF" >> "$GITHUB_OUTPUT"
-          echo "site_name=${GITHUB_REPOSITORY#*/}" >> "$GITHUB_OUTPUT"
+          set -euo pipefail
+          DEFAULT_BRANCH=$(gh api "repos/$SITE_REPO" --jq .default_branch)
+          SHA=$(gh api "repos/$SITE_REPO/branches/$DEFAULT_BRANCH" --jq .commit.sha)
+          echo "ref=$DEFAULT_BRANCH" >> "$GITHUB_OUTPUT"
+          echo "sha=$SHA" >> "$GITHUB_OUTPUT"
+          echo "::notice::Deploying $SITE_REPO @ $DEFAULT_BRANCH ($SHA)"
 
-      - name: Checkout deco-start registry at the same ref
+      - name: Checkout storefront at default-branch HEAD
         uses: actions/checkout@v4
         with:
-          repository: decocms/deco-start
-          ref: ${{ steps.meta.outputs.deco_start_ref }}
-          path: .deco-start
+          repository: ${{ inputs.site_owner }}/${{ inputs.site_name }}
+          ref: ${{ steps.target.outputs.sha }}
+          token: ${{ steps.app-token.outputs.token }}
+          path: site
+          fetch-depth: 1
 
       - uses: actions/setup-node@v4
         with:
           node-version: 22
 
-      - name: Generate lockfile if missing
-        if: hashFiles('package-lock.json') == ''
-        run: npm install --package-lock-only
-
       - name: Restore npm cache
         uses: actions/cache@v4
         with:
           path: ~/.npm
-          key: npm-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+          key: npm-${{ runner.os }}-${{ hashFiles('site/package-lock.json') }}
           restore-keys: npm-${{ runner.os }}-
 
-      - name: Sync lockfile and install
+      - name: Install dependencies
+        working-directory: site
         run: |
-          npm install --package-lock-only
-          if ! git diff --quiet package-lock.json 2>/dev/null; then
-            git config user.name "github-actions[bot]"
-            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-            git add package-lock.json
-            git commit -m "chore: sync package-lock.json"
-            git push || echo "Lockfile push failed (remote ahead); proceeding with deploy"
+          if [ ! -f package-lock.json ]; then
+            npm install --package-lock-only
           fi
           npm ci
 
       - name: Build
+        working-directory: site
         run: npm run build
 
-      - name: Resolve site manifest
-        id: site
-        run: node .deco-start/scripts/deploy/resolve-site.mjs
-        env:
-          DECO_START_PATH: .deco-start
-          SITE_NAME: ${{ steps.meta.outputs.site_name }}
-
-      - name: Generate wrangler.jsonc
-        run: node .deco-start/scripts/deploy/build-wrangler-config.mjs
+      - name: Generate wrangler.jsonc from template
+        working-directory: site
         env:
-          DECO_START_PATH: .deco-start
-          SITE_NAME: ${{ steps.meta.outputs.site_name }}
-          OUTPUT_PATH: ./wrangler.jsonc
+          DECO_START_PATH: "${{ github.workspace }}"
+          WORKER_NAME: ${{ inputs.site_name }}
+          OUTPUT_PATH: "./wrangler.jsonc"
+        run: node "$DECO_START_PATH/scripts/deploy/build-wrangler-config.mjs"
 
       - name: Deploy to Cloudflare Workers
-        run: npx wrangler deploy --var BUILD_HASH:$(git rev-parse --short HEAD)
+        working-directory: site
         env:
           CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          BUILD_HASH: ${{ steps.target.outputs.sha }}
+        run: npx wrangler deploy --var "BUILD_HASH:${BUILD_HASH:0:7}"