@decocms/start 2.29.0 → 2.30.1

package/.github/workflows/sync-secrets.yml

@@ -0,0 +1,180 @@
+name: sync-secrets (central)
+
+# Reusable workflow. Reconciles the caller's `SECRET_*` GitHub repo secrets
+# with the Cloudflare Worker's runtime secrets (with the prefix stripped).
+#
+# Examples:
+#   SECRET_STRIPE_KEY in GitHub  ->  STRIPE_KEY on the worker
+#
+# Defaults to dry-run; the caller must pass `mode: apply` to actually write.
+# Orphans on the worker (present on worker but not in GitHub as SECRET_*) are
+# warned about, never deleted.
+#
+# Caller usage (in customer repo, `.github/workflows/sync-secrets.yml`):
+#
+#   on:
+#     workflow_dispatch:
+#       inputs:
+#         mode:
+#           description: "dry-run | apply"
+#           required: true
+#           default: "dry-run"
+#           type: choice
+#           options: [dry-run, apply]
+#   jobs:
+#     sync:
+#       uses: decocms/deco-start/.github/workflows/sync-secrets.yml@v2
+#       with:
+#         mode: ${{ inputs.mode }}
+#       secrets: inherit
+#
+# Two distinct secret classes flow through this job:
+#   - `CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_ACCOUNT_ID` -> resolved from this
+#     repo's `production` environment (via `environment:` below). NEVER from
+#     the caller storefront. Same model as deploy.yml / preview.yml.
+#   - `SECRET_*` -> inherited from the caller storefront via `secrets: inherit`
+#     in the caller stub. These ARE site-owned and get pushed to the worker
+#     as runtime secrets (with the `SECRET_` prefix stripped).
+# `secrets: inherit` is therefore REQUIRED on the caller side for this
+# workflow specifically (unlike deploy.yml / preview.yml where it's just
+# tolerated).
+
+on:
+  workflow_call:
+    inputs:
+      mode:
+        description: "dry-run = print diff only | apply = set secrets on worker"
+        required: false
+        type: string
+        default: "dry-run"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: sync-secrets-${{ github.repository }}
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Resolve deco-start ref + site identity
+        id: meta
+        run: |
+          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"
+
+      - name: Checkout deco-start registry at the same ref
+        uses: actions/checkout@v4
+        with:
+          repository: decocms/deco-start
+          ref: ${{ steps.meta.outputs.deco_start_ref }}
+          path: .deco-start
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - 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
+        env:
+          DECO_START_PATH: .deco-start
+          SITE_NAME: ${{ steps.meta.outputs.site_name }}
+          OUTPUT_PATH: ./wrangler.jsonc
+
+      - name: Install wrangler
+        run: npm install --no-save wrangler@4
+
+      - name: Plan and (optionally) apply
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          ALL_SECRETS: ${{ toJSON(secrets) }}
+          MODE: ${{ inputs.mode }}
+        run: |
+          set -euo pipefail
+
+          # Build desired-state map from SECRET_* entries.
+          desired_json=$(printf '%s' "$ALL_SECRETS" | jq '
+            to_entries
+            | map(select(.key | startswith("SECRET_")))
+            | map({ key: (.key | sub("^SECRET_"; "")), value: .value })
+            | from_entries
+          ')
+
+          desired_names=$(printf '%s' "$desired_json" | jq -r 'keys[]' | sort)
+
+          # Validate names before any side effect.
+          while IFS= read -r name; do
+            [ -z "$name" ] && continue
+            if ! [[ "$name" =~ ^[A-Z][A-Z0-9_]{0,63}$ ]]; then
+              echo "::error::Invalid worker secret name derived from SECRET_${name}: must match ^[A-Z][A-Z0-9_]{0,63}$"
+              exit 1
+            fi
+          done <<< "$desired_names"
+
+          # Snapshot what's currently on the worker.
+          existing=$(npx wrangler secret list --format=json | jq -r '.[].name' | sort)
+
+          # Diff
+          to_set="$desired_names"
+          orphans=$(comm -23 <(printf '%s\n' "$existing") <(printf '%s\n' "$desired_names") || true)
+
+          {
+            echo "## Diff"
+            echo ""
+            echo "### Will set (from SECRET_* in GitHub):"
+            if [ -z "$to_set" ]; then
+              echo "  (none)"
+            else
+              echo "$to_set" | sed 's/^/  + /'
+            fi
+            echo ""
+            echo "### Orphans (on worker, not in GitHub as SECRET_*):"
+            if [ -z "$orphans" ]; then
+              echo "  (none)"
+            else
+              echo "$orphans" | sed 's/^/  ! /'
+              echo ""
+              echo "  These will NOT be deleted automatically. To remove manually:"
+              echo "$orphans" | sed 's|^|    npx wrangler secret delete "|; s|$|" --force|'
+            fi
+          } | tee -a "$GITHUB_STEP_SUMMARY"
+
+          if [ -n "$orphans" ]; then
+            echo "::warning::${orphans//$'\n'/, } exist on the worker but not in GitHub as SECRET_*. Not deleting."
+          fi
+
+          if [ "$MODE" = "dry-run" ]; then
+            echo "::notice::dry-run mode -- no changes applied"
+            exit 0
+          fi
+
+          # Apply
+          if [ -z "$to_set" ]; then
+            echo "Nothing to apply."
+            exit 0
+          fi
+
+          printf '%s' "$desired_json" | jq -r 'to_entries[] | "\(.key)\t\(.value)"' \
+            | while IFS=$'\t' read -r name value; do
+                echo "Setting $name..."
+                printf '%s' "$value" | npx wrangler secret put "$name"
+              done
+
+          echo "::notice::Applied $(echo "$to_set" | wc -l | tr -d ' ') secrets."

package/CODEOWNERS

@@ -0,0 +1,16 @@
+# CODEOWNERS for decocms/deco-start
+#
+# `deploy/` is the trust boundary for the central deploy pipeline. The files
+# under `deploy/sites/` immutably bind a customer repo to a Cloudflare worker;
+# `deploy/wrangler-template.jsonc` is the canonical wrangler config every site
+# inherits. A bad PR here can misroute a deploy or change every site's runtime
+# configuration in one shot. Only the platform team approves changes.
+#
+# The central reusable workflows are in the same trust boundary: they decide
+# how every site is built and deployed.
+deploy/                       @vibe-dex
+.github/workflows/deploy.yml         @vibe-dex
+.github/workflows/preview.yml        @vibe-dex
+.github/workflows/sync-secrets.yml   @vibe-dex
+.github/workflows/regen-blocks.yml   @vibe-dex
+scripts/deploy/                      @vibe-dex

package/MIGRATION_TOOLING_PLAN.md

@@ -117,6 +117,8 @@ this plan.
 | 2026-05-01 | **D3 — Stub generation: throw at runtime (Option C)** | Migration-time stubs throw with a clear pointer to the canonical replacement instead of silently identity-casting. Forces audit `--fix` to cover swap cases (no permanent detect-only state) and skills to keep up with stub generation. |
 | 2026-05-01 | **D4 — Site-local apps: local by default, promote at 3** | Site-specific apps live in `src/apps/local/` until ≥3 sites use them, then promote to `@decocms/apps`. |
 | 2026-05-01 | **D5 — Failed migrations: rm -rf and re-run** | No `--restart` mode. Half-migrated sites are throwaways. Failure modes get documented in skills, not encoded as escape hatches. |
+| 2026-05-07 | **D6 — Deploy / preview / secrets pipelines: centralize in `deco-start`** | At 6 sites the "1-minute copy" of `deploy.yml` / `preview.yml` / `wrangler.jsonc` had already produced unintended drift (lebiscuit missing 2 workflows, miess missing `account_id`, casaevideo's `loadtest:tail` worker name out of sync with its wrangler config). All sites now consume reusable workflows from `decocms/deco-start@v2` and a per-site registry under [`deploy/sites/<repo>.jsonc`](./deploy/) deep-merged on top of [`deploy/wrangler-template.jsonc`](./deploy/wrangler-template.jsonc) at deploy time. Customer repos hold only ~5-line caller workflows; `wrangler.jsonc` is generated and gitignored. The repo→worker binding is the trust boundary that prevents one site's commits from misrouting onto another site's worker (the central workflow ignores caller `inputs:` for identity and derives the site name from `${{ github.repository }}`). See [`deploy/README.md`](./deploy/README.md) for the contract. |
+| 2026-05-07 | **D6.1 — Cloudflare credentials never leave `deco-start`** | Same-day refinement of D6 after the first central deploy on `baggagio-tanstack` failed with `Secret CLOUDFLARE_API_TOKEN is required, but not provided while calling`. The original D6 design used `secrets: inherit` from the storefront stub and required `CLOUDFLARE_*` to live in the `deco-sites` org, which broke the principle that *the only secrets a storefront repo holds are the secrets that go into wrangler secrets, not the ones used to deploy*. Refinement: the central `deploy.yml` / `preview.yml` / `sync-secrets.yml` jobs declare `environment: production`, which makes `${{ secrets.CLOUDFLARE_* }}` resolve from the called repo (`decocms/deco-start`'s `production` GitHub Environment) instead of the caller's repo secrets. Storefronts now hold only their own `SECRET_*` runtime secrets; `sync-secrets` inherits those via `secrets: inherit` and pushes them as worker secrets. The trust boundary becomes two-tier: even a fully compromised storefront repo has no path to the Cloudflare credential, and even a compromised storefront cannot misroute *its own* deploy onto another site's worker because `worker_name` comes from the CODEOWNERS-protected registry, not caller input. See [`deploy/README.md`](./deploy/README.md) "Where Cloudflare credentials live" section. |
 
 The full text of the constitutional rule (loaded into every agent
 session for this repo) lives at
@@ -1669,10 +1671,21 @@ props. One broken section never takes the page down.
   release picks up the framework export — TODO is checked into
   `src/lib/http-utils.ts`.
 - **CI/CD porting from casaevideo to a new TanStack site is a 1-minute
-  copy.** `deploy.yml`, `preview.yml`, `regen-blocks.yml`, plus
-  `wrangler.jsonc` worker `name` rename, plus `account_id` paste from
-  another site. No template needed yet — three sites is too few. Will
-  template if a fourth migration needs it.
+  copy** (when this note was written, at 3 sites). By 6 sites
+  the copy-paste had drifted: lebiscuit was missing
+  `regen-blocks.yml` and `sync-secrets.yml`, miess was missing
+  `regen-blocks.yml` and its `wrangler.jsonc` lacked `account_id`,
+  lebiscuit's preview workflow swallowed `wrangler` exit codes, and
+  casaevideo's `loadtest:tail` referenced a worker name that didn't
+  match its `wrangler.jsonc`. **Resolved 2026-05-07 via D6:** all
+  workflows + wrangler config are centralized in
+  [`deco-start/.github/workflows/`](./.github/workflows/) and
+  [`deco-start/deploy/`](./deploy/). New-site onboarding is now: open a
+  PR adding `deploy/sites/<repo>.jsonc` to deco-start, then drop the
+  ~5-line caller workflows into the new site's repo. No `wrangler.jsonc`
+  is committed to the site repo — `deco-wrangler gen`
+  (a `bin` shipped from `@decocms/start`) materializes it from the
+  central registry on demand for local dev and CI alike.
 
 #### Counter-evidence the user-rule asks for
 

package/deploy/README.md

@@ -0,0 +1,111 @@
+# `deploy/` — central deploy registry
+
+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.
+
+## 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.
+
+## 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.
+
+### 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 |
+|---|---|---|
+| `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` |
+
+To rotate the Cloudflare credentials, edit the environment in this repo only.
+No storefront PR needed.
+
+## 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.
+
+`account_id` is never written to JSON — wrangler reads it from
+`CLOUDFLARE_ACCOUNT_ID` (env var in CI; `wrangler login` locally).
+
+## 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.

package/deploy/sites/als-tanstack.jsonc

@@ -0,0 +1,7 @@
+// Per-site overrides for `als-tanstack` (immutable repo->worker binding).
+// Renaming `worker_name` is a breaking change: it points the next deploy at a
+// different Cloudflare worker. Only the platform team can change this file
+// (CODEOWNERS-protected).
+{
+  "worker_name": "als-tanstack"
+}

package/deploy/sites/americanas-tanstack.jsonc

@@ -0,0 +1,4 @@
+// Per-site overrides for `americanas-tanstack`.
+{
+  "worker_name": "americanas-tanstack"
+}

package/deploy/sites/baggagio-tanstack.jsonc

@@ -0,0 +1,4 @@
+// Per-site overrides for `baggagio-tanstack`.
+{
+  "worker_name": "baggagio-tanstack"
+}

package/deploy/sites/casaevideo-storefront.jsonc

@@ -0,0 +1,11 @@
+// Per-site overrides for `casaevideo-storefront`.
+//
+// NOTE: `kv_namespaces[].id` is shared with `lebiscuit-tanstack`. Verify this
+// is intentional before promoting this registry to v1. R4 in the central-deploy
+// plan adds a CI check that flags shared KV ids as a copy-paste smell.
+{
+  "worker_name": "casaevideo-tanstack",
+  "kv_namespaces": [
+    { "binding": "SITES_KV", "id": "ad0b74fc4d9341c9af9149c4ab85132f" }
+  ]
+}

package/deploy/sites/lebiscuit-tanstack.jsonc

@@ -0,0 +1,19 @@
+// Per-site overrides for `lebiscuit-tanstack`.
+//
+// NOTE: `kv_namespaces[].id` is shared with `casaevideo-storefront`. See the
+// note in casaevideo's site file. R4 will add CI validation for this.
+//
+// `version_metadata` and `analytics_engine_datasets` are consumed by
+// @decocms/start's `instrumentWorker`:
+//   - version_metadata populates `service.version` on the OTel resource.
+//   - analytics_engine_datasets is the dual-emit metrics target.
+{
+  "worker_name": "lebiscuit-tanstack",
+  "kv_namespaces": [
+    { "binding": "SITES_KV", "id": "ad0b74fc4d9341c9af9149c4ab85132f" }
+  ],
+  "version_metadata": { "binding": "CF_VERSION_METADATA" },
+  "analytics_engine_datasets": [
+    { "binding": "DECO_METRICS", "dataset": "deco_metrics_lebiscuit" }
+  ]
+}

package/deploy/sites/miess-01-tanstack.jsonc

@@ -0,0 +1,8 @@
+// Per-site overrides for `miess-01-tanstack`.
+//
+// Worker name keeps the historical `miess-tanstack` (no "-01") so the deploy
+// continues to land on the existing Cloudflare worker. The repo name has the
+// `-01-` suffix; the worker name does not.
+{
+  "worker_name": "miess-tanstack"
+}

package/deploy/wrangler-template.jsonc

@@ -0,0 +1,28 @@
+// 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).
+//
+// 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.
+//
+// To upgrade compatibility flags, observability, or worker-entry path across
+// every site at once, change this file and tag a new deco-start release.
+{
+  "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,
+  "observability": {
+    "logs": {
+      "enabled": true,
+      "invocation_logs": true
+    }
+  }
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@decocms/start",
-  "version": "2.29.0",
+  "version": "2.30.1",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",
   "bin": {
     "deco-migrate": "./scripts/migrate.ts",
     "deco-post-cleanup": "./scripts/migrate-post-cleanup.ts",
-    "deco-htmx-analyze": "./scripts/htmx-analyze.ts"
+    "deco-htmx-analyze": "./scripts/htmx-analyze.ts",
+    "deco-wrangler": "./scripts/deploy/wrangler-wrapper.mjs"
   },
   "exports": {
     ".": "./src/index.ts",

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

@@ -0,0 +1,49 @@
+#!/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` /
+// `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)
+//   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";
+
+function fail(message) {
+  console.error(`::error::${message}`);
+  process.exit(1);
+}
+
+const decoStartPath = process.env.DECO_START_PATH;
+const siteName = process.env.SITE_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 (!outputPath) fail("OUTPUT_PATH env var is required");
+
+let merged;
+try {
+  const template = loadTemplate(decoStartPath);
+  const manifest = loadSiteManifest(decoStartPath, siteName);
+  merged = mergeWithTemplate(template, manifest);
+} 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
+`;
+
+const body = JSON.stringify(merged, null, 2);
+writeFileSync(resolve(outputPath), `${header}${body}\n`);
+
+console.log(`Wrote ${outputPath} for site "${siteName}" (worker "${merged.name}")`);

package/scripts/deploy/jsonc.mjs

@@ -0,0 +1,76 @@
+// Minimal JSONC -> JSON parser used by the deploy scripts.
+//
+// Strips // line comments and /* block comments */ outside of string literals
+// and tolerates trailing commas in objects/arrays. Dependency-free so the
+// deploy scripts can run with vanilla `node` in CI.
+
+import { readFileSync } from "node:fs";
+
+/**
+ * @param {string} input
+ * @returns {string}
+ */
+function stripComments(input) {
+  let out = "";
+  let i = 0;
+  let inStr = false;
+  let strChar = "";
+  while (i < input.length) {
+    const c = input[i];
+    const n = input[i + 1];
+    if (inStr) {
+      out += c;
+      if (c === "\\" && i + 1 < input.length) {
+        out += input[i + 1];
+        i += 2;
+        continue;
+      }
+      if (c === strChar) inStr = false;
+      i++;
+      continue;
+    }
+    if (c === '"') {
+      inStr = true;
+      strChar = c;
+      out += c;
+      i++;
+      continue;
+    }
+    if (c === "/" && n === "/") {
+      while (i < input.length && input[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && n === "*") {
+      i += 2;
+      while (i < input.length && !(input[i] === "*" && input[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
+
+/**
+ * @param {string} text
+ * @returns {unknown}
+ */
+export function parseJsonc(text) {
+  const stripped = stripComments(text).replace(/,\s*([}\]])/g, "$1");
+  return JSON.parse(stripped);
+}
+
+/**
+ * @param {string} path
+ * @returns {unknown}
+ */
+export function readJsoncFile(path) {
+  const raw = readFileSync(path, "utf8");
+  try {
+    return parseJsonc(raw);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to parse JSONC at ${path}: ${message}`);
+  }
+}

package/scripts/deploy/resolve-site.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// resolve-site.mjs
+//
+// Validates that the calling repository has a registered site manifest in
+// deco-start, and emits the resolved fields to GITHUB_OUTPUT for downstream
+// steps (wrangler tail, status comments, etc.).
+//
+// Required env:
+//   DECO_START_PATH  - path to a checked-out deco-start (e.g. ".deco-start")
+//   SITE_NAME        - typically `${GITHUB_REPOSITORY#*/}` set by the workflow
+//
+// Optional env:
+//   GITHUB_OUTPUT    - if set, emit `key=value` lines here (CI mode).
+//                      If unset, prints a human-readable summary to stdout.
+
+import { appendFileSync } from "node:fs";
+import { loadSiteManifest } from "./site-registry.mjs";
+
+function fail(message) {
+  console.error(`::error::${message}`);
+  process.exit(1);
+}
+
+const decoStartPath = process.env.DECO_START_PATH;
+const siteName = process.env.SITE_NAME;
+const ghOutput = process.env.GITHUB_OUTPUT;
+
+if (!decoStartPath) fail("DECO_START_PATH env var is required");
+if (!siteName) fail("SITE_NAME env var is required");
+
+let manifest;
+try {
+  manifest = loadSiteManifest(decoStartPath, siteName);
+} catch (err) {
+  fail(err instanceof Error ? err.message : String(err));
+}
+
+const summary = {
+  site_name: siteName,
+  worker_name: manifest.worker_name,
+  has_routes: String(Array.isArray(manifest.routes) && manifest.routes.length > 0),
+  has_kv: String(Array.isArray(manifest.kv_namespaces) && manifest.kv_namespaces.length > 0),
+  has_analytics: String(
+    Array.isArray(manifest.analytics_engine_datasets) &&
+      manifest.analytics_engine_datasets.length > 0,
+  ),
+  has_version_metadata: String(Boolean(manifest.version_metadata)),
+};
+
+if (ghOutput) {
+  const lines = Object.entries(summary).map(([k, v]) => `${k}=${v}`);
+  appendFileSync(ghOutput, `${lines.join("\n")}\n`);
+}
+
+console.log(`Resolved site "${siteName}" -> worker "${manifest.worker_name}"`);
+for (const [k, v] of Object.entries(summary)) {
+  console.log(`  ${k}: ${v}`);
+}