Brooooooklyn · Jul 23, 2026 · Jul 22, 2026 · Jul 22, 2026 · Jul 22, 2026 · Jul 22, 2026
@@ -20,6 +20,9 @@ jobs:
     runs-on: ${{ matrix.os }}
     permissions:
       contents: read
+    # No Cloudflare creds in this job. The credentialed live deploy e2e runs in the separate
+    # `live-e2e` job (below), whose secrets are bound to the `cloudflare-e2e` environment. Here the
+    # live suite (part of `vp run test:all`) sees empty creds and self-skips on every event.
     strategy:
       fail-fast: false
       matrix:
@@ -43,11 +46,52 @@ jobs:
 
       - run: vp run test:all
 
+  # Credentialed live Cloudflare deploy e2e, ISOLATED from `test` so the account token exists ONLY in
+  # a job bound to the `cloudflare-e2e` GitHub Environment. That environment's deployment branch policy
+  # allows `main` ONLY and the ref is enforced server-side, so a `pull_request` run (ref
+  # refs/pull/<n>/merge) can never reach the secret — even a PR that edits this file — and a modified
+  # workflow cannot exfiltrate it. The `if` also keeps the job off everything except a direct push to
+  # the `main` branch: tag pushes and `workflow_call` (release) carry a non-main ref, so they are
+  # skipped — which both avoids a branch-policy failure and matches where the secret is allowed, and
+  # it is scoped to the canonical repo so forks don't run it. It deploys a UNIQUELY-named worker
+  # (VOID_E2E_RUN_ID) to a throwaway account and tears it down. A preflight step fails the job when a
+  # credential is empty (unset / deleted / not-yet-rotated token), so a missing secret can never turn
+  # the live-deploy gate into a silent green no-op (the `test` job's uncredentialed run still skips).
+  live-e2e:
+    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' && github.repository == 'voidzero-dev/void' }}
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    permissions:
+      contents: read
+    environment: cloudflare-e2e
+    env:
+      VOID_E2E_CF_TOKEN: ${{ secrets.VOID_E2E_CF_TOKEN }}
+      VOID_E2E_CF_ACCOUNT_ID: ${{ secrets.VOID_E2E_CF_ACCOUNT_ID }}
+      VOID_E2E_RUN_ID: ${{ github.run_id }}-${{ github.run_attempt }}
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+      - uses: voidzero-dev/setup-vp@2dec1e33f4ab2c6d5bce1b0c4607961bb1a3f7a1 # v1.12.0
+        with:
+          node-version-file: .node-version
+          cache: true
+      # Fail closed BEFORE the build: a missing/empty credential must fail this job, not self-skip. The
+      # `${VAR:?}` expansion exits nonzero when the secret is unset OR empty (GitHub resolves an unset
+      # secret to '').
+      - name: Require live Cloudflare credentials
+        run: |
+          : "${VOID_E2E_CF_TOKEN:?empty — set it as a cloudflare-e2e environment secret}"
+          : "${VOID_E2E_CF_ACCOUNT_ID:?empty — set it as a cloudflare-e2e environment secret}"
+      # build:core produces dist/cli/cli.mjs + the built `void` plugin the deploy uses to build the app.
+      - run: vp run build:core
+      - run: vp test run packages/void/test/e2e/cloudflare-deploy-live.test.ts
+
   done:
     runs-on: ubuntu-latest
     if: always()
     needs:
       - test
+      - live-e2e
     steps:
       - run: exit 1
         if: ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}
diff --git a/packages/void/src/cli/deploy.ts b/packages/void/src/cli/deploy.ts
@@ -2094,7 +2094,7 @@ function isCleanWranglerExit(result: DeployWranglerRunResult): boolean {
  * unreadable — callers then treat every field as unset (safe: a genuinely broken
  * config fails later in wrangler with a clear error).
  */
-function parseRootWranglerConfig(configPath: string): Record<string, unknown> {
+export function parseRootWranglerConfig(configPath: string): Record<string, unknown> {
   if (!existsSync(configPath)) {
     return {};
   }

diff --git a/packages/void/test/e2e/README.md b/packages/void/test/e2e/README.md
@@ -0,0 +1,85 @@
+# `packages/void/test/e2e`
+
+Gated live-account end-to-end tests. These run REAL Cloudflare operations against a REAL account, so
+they **skip unless credentials are present**. Locally that means exporting the env vars below; in CI
+they run on **pushes to `main`** (see [In CI](#in-ci)).
+
+## `cloudflare-deploy-live.test.ts`
+
+Deploys `playground/spa` (D1 + KV + cron) to the target account via `void deploy --backend cloudflare`,
+verifies the live worker answers HTTP 200, then deletes the worker and every resource it created.
+
+It does **not** drive `--provision`: that path fails closed in non-interactive shells by design (a
+spawned CLI has no TTY, and CI cannot commit back the ids a create would mint). So the test plays the
+provisioner's role itself — it creates the id-bearing D1 + KV directly with `wrangler … create`,
+writes their real ids into the app's root config exactly as `--provision` would, then runs the
+CI-safe `void deploy --backend cloudflare` (no `--provision`). That exercises the real
+build → tamper-guard → remote-migrations → `wrangler deploy` pipeline end to end.
+
+### Prerequisites
+
+The suite is skipped unless BOTH env vars are set:
+
+| Env var                  | Purpose                                                                    |
+| ------------------------ | -------------------------------------------------------------------------- |
+| `VOID_E2E_CF_TOKEN`      | Cloudflare API token that can create + delete Workers Scripts, D1, and KV. |
+| `VOID_E2E_CF_ACCOUNT_ID` | Cloudflare account id to deploy into.                                      |
+
+The token needs, on that account, **Workers Scripts: Edit**, **D1: Edit**, and **Workers KV Storage:
+Edit** (Edit implies read, covering the ownership/teardown list calls). Cron triggers ride along with
+the worker deploy — no extra permission.
+
+The account must also have a **workers.dev subdomain** already registered (with its wildcard TLS cert
+provisioned). Without one, `wrangler deploy` uploads the worker but cannot publish a public URL, and
+the HTTP-200 assertion has nothing to hit. Opening the Workers & Pages dashboard once registers a
+subdomain automatically; a freshly-registered subdomain takes a few minutes for its cert to go live,
+during which the first run may see a TLS handshake failure — rerun once the cert is ready.
+
+With no env vars the suite SKIPS cleanly (0 run, N skipped).
+
+### Running it
+
+```sh
+# Ensure the CLI is built first (dist/cli/cli.mjs):
+vp run build:core
+
+VOID_E2E_CF_TOKEN=... VOID_E2E_CF_ACCOUNT_ID=... vp test run packages/void/test/e2e
+```
+
+### In CI
+
+`VOID_E2E_CF_TOKEN` and `VOID_E2E_CF_ACCOUNT_ID` are **environment secrets** on the `cloudflare-e2e`
+GitHub Environment (not repo secrets), and a dedicated `live-e2e` job in `.github/workflows/ci.yml`
+consumes them — the main `test` job carries no creds at all. Two layers keep the account token off
+untrusted code:
+
+- The `live-e2e` job runs only on a direct push to `main` (`github.event_name == 'push' && github.ref
+== 'refs/heads/main'`), so `pull_request` runs, tag pushes, and `workflow_call` (release) skip it.
+- The `cloudflare-e2e` environment's deployment branch policy allows `main` **only**, enforced by
+  GitHub server-side on the run's ref. A `pull_request` run's ref is `refs/pull/<n>/merge`, so it can
+  never reach the secret **even if a PR edits this workflow** — the expression-level gate alone would
+  be bypassable that way; the environment ref-check is the real boundary.
+
+So the credentialed live deploy runs on every merge to `main`; everywhere else the creds are empty and
+the suite SKIPS (the `test` job still imports the file and skips it). The `live-e2e` job itself is
+fail-closed — a preflight step errors if either credential is empty (a missing, deleted, or
+not-yet-rotated secret), so a misconfigured gate is loud instead of a silent green skip. Each
+`live-e2e` run also gets `VOID_E2E_RUN_ID = <run-id>-<attempt>` for the unique per-run resource names
+below.
+
+### Resource naming & cleanup
+
+Each run derives a UNIQUE resource name — `void-e2e-cf-deploy-<suffix>` — so overlapping runs never
+collide on remote resources. The suffix is `VOID_E2E_RUN_ID` (CI: `<run-id>-<attempt>`) or, locally, a
+timestamp + random. Derived names mirror the provisioner: `<name>-db` (D1), `<name>-kv` (KV). The
+shared `void-e2e-cf-deploy-` prefix keeps every resource greppable, so an orphan from a hard-killed run
+is easy to find and `wrangler delete`. A pre-run ownership gate refuses to start if the run's names
+already exist (failing closed on any lookup it cannot confirm), so the test never adopts or deletes a
+resource it does not own. Teardown runs even when the deploy or an assertion fails.
+
+> **Local concurrency:** unique names isolate _remote_ resources, but a run also snapshots and
+> overwrites the shared `playground/spa/wrangler.jsonc` and builds in place. Do **not** run two live
+> e2e invocations against the same checkout at once — they would race that file. CI is unaffected (each
+> runner is an isolated checkout, and only the single `main`-push `live-e2e` job deploys). The deploy
+> test also asserts the returned host's worker label equals this run's `WORKER_NAME`, so a clobbered
+> overlay fails loudly instead of validating another run's worker.