[pull] main from cloudflare:main

.changeset/fix-vitest-pool-workers-external-list.md

@@ -0,0 +1,11 @@
+---
+"@cloudflare/vitest-pool-workers": patch
+---
+
+Derive bundler externals from `package.json` and shrink the published bundle
+
+The bundler's `external` list was previously hand-maintained and out of sync with `package.json` — `undici` and `semver` were both listed as external despite being only `devDependencies`. The published `dist/pool/index.mjs` consequently contained a top-level `import { fetch } from "undici"` that was only resolvable because pnpm happened to hoist `undici` from other packages' devDependencies during local development.
+
+The bundler now derives its `external` list from `dependencies` + `peerDependencies` in `package.json`, making it impossible for a `devDependency` to silently end up externalized.
+
+Combined with the new `"sideEffects": false` declaration in `@cloudflare/workers-utils`, the unused `cloudflared` / `tunnel` exports (and their transitive `undici` import) are now tree-shaken out of the pool entirely. `dist/pool/index.mjs` no longer references `undici` at all, and shrinks from ~489 KB to ~125 KB.

.changeset/fix-workers-utils-sideeffects-undici.md

@@ -0,0 +1,11 @@
+---
+"@cloudflare/workers-utils": patch
+---
+
+Mark `@cloudflare/workers-utils` as side-effect-free and properly declare `undici` as a runtime dependency
+
+The package now declares `"sideEffects": false` in its `package.json` so that downstream bundlers can tree-shake unused exports. In particular, consumers that only use a subset of the package (for example, `getTodaysCompatDate` from the main entry) will no longer carry the `cloudflared` / `tunnel` exports — or their transitive dependencies — in their final bundle.
+
+`undici` has been moved from `devDependencies` to `dependencies`. Previously it was incorrectly listed as a devDependency while the bundler config marked it as external, leaving the published `dist/index.mjs` with an unresolved `import { fetch } from "undici"` for anyone installing the package directly. `undici` is deliberately kept external (rather than bundled) so that downstream consumers don't end up with two copies of `undici` in their bundle — which would break `instanceof Request`/`Response`/`Headers` checks across the boundary and prevent `setGlobalDispatcher` / proxy configuration from applying to the bundled copy.
+
+`vitest` has been added as an optional `peerDependency` because the `./test-helpers` sub-export uses `vitest`'s `vi`, `beforeEach`, and `afterEach` APIs at runtime; consumers that import from `./test-helpers` must have `vitest` installed themselves.

.github/workflows/prerelease.yml

@@ -36,8 +36,6 @@ jobs:
         with:
           disable-cache: "true"
 
-      - run: echo ${{ github.head_ref }}
-
       - name: Build
         run: pnpm build --filter="./packages/*"
         env:

.opencode/skills/local-explorer/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: local-explorer
+description: How to add products/resources to the local explorer or local API. Use when implementing new local APIs, or UI routes under packages/miniflare/src/workers/local-explorer or packages/local-explorer-ui.
+---
+
+# Cloudflare Local Explorer Products
+
+Use this skill when adding a new product or resource type to the local API and/or local explorer.
+
+## Start Here
+
+Read these files before editing:
+
+- `packages/miniflare/src/workers/local-explorer/explorer.worker.ts`
+- `packages/miniflare/src/plugins/core/explorer.ts`
+- `packages/miniflare/src/plugins/core/types.ts`
+- One existing resource implementation in `packages/miniflare/src/workers/local-explorer/resources/`, preferably the product most similar to the new one
+- One matching test in `packages/miniflare/test/plugins/local-explorer/`
+
+If there are UI changes, also read:
+
+- `packages/local-explorer-ui/src/components/Sidebar.tsx`
+- Existing route files under `packages/local-explorer-ui/src/routes/`
+- Existing product e2e tests under `packages/local-explorer-ui/src/__e2e__/`
+
+## Workflow
+
+1. Add the API surface to `packages/miniflare/scripts/openapi-filter-config.ts`.
+2. Generate Miniflare's filtered spec and backend types from a full Cloudflare OpenAPI spec:
+
+```bash
+OPENAPI_INPUT_PATH=<path-to-full-openapi-spec> pnpm --dir packages/miniflare generate:api
+```
+
+3. Inspect `packages/miniflare/src/workers/local-explorer/openapi.local.json` and generated types. If the generated schemas include fields local explorer will not support, add ignores in `openapi-filter-config.ts` and regenerate.
+4. The explorer worker should have access to all user resource bindings. Ensure `proxyBindings` include bindings to the new product and that `getExplorerServices()` exposes any extra bindings the explorer worker needs. Wire product bindings through `constructExplorerBindingMap()` and `constructExplorerWorkerOpts()` in `packages/miniflare/src/plugins/core/explorer.ts`.
+5. Add or extend resource binding metadata in `packages/miniflare/src/plugins/core/types.ts`.
+6. Implement handlers in `packages/miniflare/src/workers/local-explorer/resources/<product>.ts`. Make sure to account for cross-instance aggregation, if applicable.
+7. Register Hono routes in `packages/miniflare/src/workers/local-explorer/explorer.worker.ts`.
+8. Validate request bodies and query params with generated Zod schemas from `generated/zod.gen.ts` using `validateRequestBody()` and `validateQuery()`.
+9. Return Cloudflare API envelope responses using `wrapResponse()` and `errorResponse()` from `common.ts` unless an existing endpoint for that product uses a different response shape.
+10. Add Miniflare tests in `packages/miniflare/test/plugins/local-explorer/<product>.spec.ts`.
+11. Regenerate the UI API client:
+
+```bash
+pnpm --dir packages/local-explorer-ui build
+```
+
+12. Add UI routes/components. Use Kumo components for new UI. See https://github.com/cloudflare/kumo/blob/main/AGENTS.md.
+13. Add Playwright e2e tests under `packages/local-explorer-ui/src/__e2e__/<product>/` for new visible product flows.
+
+## OpenAPI Rules
+
+- Do not edit generated files like `packages/miniflare/src/workers/local-explorer/openapi.local.json` or `packages/miniflare/src/workers/local-explorer/generated/` directly.
+- Prefer upstream Cloudflare API paths when a public API exists.
+- Use `extensions.paths` in `openapi-filter-config.ts` only for local-only APIs or APIs that do not exist in the public Cloudflare API.
+- Add ignores for unsupported params, headers, request body properties, and response fields rather than pretending to support them.
+
+## Backend Patterns
+
+- Local list endpoints such as listing KV namespaces should not implement pagination as this may require cross-instance aggregation. Pagination should be supported when targeting individual resources, such as listing KV keys within a specific namespace.
+- For cross-worker aggregation, use `aggregateListResults()`, `getPeerUrlsIfAggregating()`, and `fetchFromPeer()` from `aggregation.ts`; do not hand-roll peer discovery. Add tests for both local-only behavior and aggregated behavior when the product can span multiple instances.
+- If an API needs direct filesystem access, call through the loopback service (`c.env.MINIFLARE_LOOPBACK`) to a Node.js endpoint. The local explorer API runs inside workerd, so it cannot access the host filesystem directly.
+- If an endpoint needs metadata that is not available on the runtime binding itself, put that metadata in `BindingIdMap` and pass it through `CoreBindings.JSON_LOCAL_EXPLORER_BINDING_MAP`.
+- If a product should appear in `/api/local/workers`, add it to `WorkerResourceBindings` and populate it in `constructExplorerWorkerOpts()`.
+
+## UI Patterns
+
+- The UI API client is generated from `packages/miniflare/src/workers/local-explorer/openapi.local.json` into `packages/local-explorer-ui/src/api/generated/`.
+- Sidebar resources come from `/api/local/workers`; update `LocalExplorerWorkerBindings` usage and `Sidebar.tsx` when the product should appear in navigation.
+- Add route files under `packages/local-explorer-ui/src/routes/`. TanStack Router regenerates `src/routeTree.gen.ts` during UI build/dev.
+- Preserve worker selection by carrying the `worker` search param through product links when following sidebar patterns.
+- Use Kumo for new UI components wherever possible. Do not introduce a parallel component system.
+- Do not use tailwindCSS color tokens, use Kumo color tokens instead.

.opencode/skills/local-explorer/assets/local-explorer-diagram.md

@@ -0,0 +1,57 @@
+```mermaid
+flowchart TB
+	Client["client"] --> Incoming["incoming request"]
+	Incoming --> EntryA["entry worker"]
+	EntryA -->|/cdn-cgi/explorer| ExplorerA["explorer worker<br/>(Hono)"]
+
+	subgraph Runtime["running Miniflare instances"]
+		direction LR
+
+		subgraph A["miniflare A"]
+			direction TB
+			EntryA
+			ExplorerA
+			Frontend["frontend<br/>(TanStack Router + React)"]
+			UserWorker["user worker"]
+			KV["KV, R2, D1"]
+			Wrapper["wrapped<br/>DO/Workflow class"]
+
+			EntryA --> UserWorker
+			ExplorerA -->|disk service to serve assets| Frontend
+			ExplorerA -->|binding| KV
+			ExplorerA -->|binding| Wrapper
+			UserWorker -->|binding| KV
+			UserWorker -->|binding| Wrapper
+		end
+
+		subgraph B["miniflare B"]
+			direction TB
+			EntryB["entry worker"]
+			ExplorerB["explorer worker"]
+			Etc["etc."]
+
+			EntryB --> ExplorerB
+			ExplorerB --> Etc
+		end
+	end
+
+	Frontend -->|fetch /cdn-cgi/explorer/api| Incoming
+	ExplorerA -->|fetch /cdn-cgi/explorer/api/resource with NO_AGGREGATE_HEADER| EntryB
+
+	subgraph FS["filesystem"]
+		Registry["dev registry"]
+		DOState[".wrangler/state/durable-objects<br/>(list DOs, delete workflows, etc.)"]
+	end
+
+	ExplorerA -->|node loopback binding| FS
+
+	classDef miniflareA stroke:#f08c00,fill:#fff7ed,color:#1e1e1e;
+	classDef userResource stroke:#1971c2,fill:#eff6ff,color:#1e1e1e;
+	classDef entry stroke:#e03131,fill:#fff5f5,color:#1e1e1e;
+	classDef neutral stroke:#1e1e1e,fill:#ffffff,color:#1e1e1e;
+
+	class EntryA entry;
+	class ExplorerA,Frontend,Wrapper miniflareA;
+	class UserWorker,KV userResource;
+	class Client,Incoming,Runtime,FS,Registry,DOState,EntryB,ExplorerB,Etc neutral;
+```