Skip to content

Release Version 1 - #1

Open
Refzlund wants to merge 433 commits into
mainfrom
next
Open

Refzlund wants to merge 433 commits into
mainfrom
next

Conversation

@Refzlund

Copy link
Copy Markdown
Owner

No description provided.

@changeset-bot

changeset-bot Bot commented Apr 11, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: feaabea

The changes in this PR will be included in the next version bump.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@github-actions

github-actions Bot commented Apr 14, 2026 •

Copy link
Copy Markdown

✅ Documentation PR preview deployed successfully

This pull request gets a stable PR-scoped preview link that is updated in place on every preview run.

Logs and details
.svelte-kit/output/server/entries/pages/_layout.svelte.js              18.47 kB │ gzip:   4.60 kB
.svelte-kit/output/server/chunks/internal.js                           19.02 kB │ gzip:   5.77 kB
.svelte-kit/output/server/chunks/shared.js                             23.90 kB │ gzip:   6.44 kB
.svelte-kit/output/server/chunks/utils.js                              29.10 kB │ gzip:   8.39 kB
.svelte-kit/output/server/remote-entry.js                              35.60 kB │ gzip:   8.02 kB
.svelte-kit/output/server/chunks/runtime.js                            43.37 kB │ gzip:  10.59 kB
.svelte-kit/output/server/chunks/messages.js                           87.43 kB │ gzip:  16.42 kB
.svelte-kit/output/server/index.js                                    130.59 kB │ gzip:  33.53 kB
.svelte-kit/output/server/entries/pages/docs/_slug_/_page.svelte.js   134.93 kB │ gzip:  27.06 kB
.svelte-kit/output/server/chunks/dev.js                               142.87 kB │ gzip:  36.83 kB
.svelte-kit/output/server/entries/hooks.server.js                     170.11 kB │ gzip:  35.52 kB
.svelte-kit/output/server/chunks/content.js                           525.11 kB │ gzip: 133.91 kB

�[33m�[33m[PLUGIN_TIMINGS] Warning:�[0m Your build spent significant time in plugins. Here is a breakdown:
  - devflare (48%)
  - vite-plugin-sveltekit-guard (35%)
  - vite-plugin-sveltekit-virtual-modules (9%)
  - vite-plugin-sveltekit-compile (4%)
See https://rolldown.rs/options/checks#plugintimings for more details.
�[39m
�[32m✓ built in 9.75s�[39m

Run npm run preview to preview your production build locally.

> Using @sveltejs/adapter-cloudflare
  ✔ done
[log] Generated deploy Wrangler config: .devflare/build/wrangler.jsonc
[log] Generated deploy redirect: .wrangler/deploy/config.json
[log] worker devflare-docs-pr-1
[log] Deploying with Wrangler…

 ⛅️ wrangler 4.81.1 (update available 4.82.2)
─────────────────────────────────────────────
Using redirected Wrangler configuration.
 - Configuration being used: ".devflare/build/wrangler.jsonc"
 - Original user's configuration: "<no user config found>"
 - Deploy configuration file: ".wrangler/deploy/config.json"
[success] Preview URL: https://devflare-docs-pr-1.refz.workers.dev
[warn] Deployment verification note: Wrangler completed the named preview-scope deploy for Worker "devflare-docs-pr-1" and exposed https://devflare-docs-pr-1.refz.workers.dev, but Cloudflare did not return a Worker version id. Devflare is treating this branch-scoped preview deploy as successful because named preview workers can lag in control-plane version metadata.
[success] Deployed successfully!

@github-actions

github-actions Bot commented Apr 14, 2026 •

Copy link
Copy Markdown

✅ Testing branch preview deployed successfully

This workflow publishes a branch-scoped testing preview on every qualifying push, even when no pull request exists. When the branch belongs to an open pull request, the same run also refreshes the stable PR preview comment.

Logs and details
Using deploy command: bunx --bun devflare deploy
Deploy target: preview scope (next)
Bun version: 1.3.12
Node version: v20.20.2
[log]
[log] deploy Shipping to Cloudflare
[log] Reused preview-scoped resources: KV 2 · D1 3 · R2 2 · Queues 4 · Vectorize 2
[warn] Workers Analytics Engine datasets are created automatically on first write, so Devflare does not provision or delete preview-scoped analytics datasets.
[warn] Browser Rendering bindings do not own account-scoped resources, so Devflare does not provision or delete preview-scoped browser bindings.
[warn] Preview Hyperdrive "devflare-testing-next" is not auto-provisioned because Cloudflare does not expose stored Hyperdrive credentials for cloning. Devflare will reuse the base Hyperdrive "devflare-testing" for binding POSTGRES.
[log] Building: devflare-testing-binding-matrix-next
[log] Branch-scoped preview deploy detected (next); omitting shared queue consumers and cron triggers from the deployed Wrangler config to avoid singleton Cloudflare resource conflicts.
[log] Generated bundled worker entry: .devflare/worker-entrypoints/main.js
[log] Skipping Vite build (no effective Vite config found for this package)
[log] Generated deploy artifact: .devflare/build/worker.js
[log] Generated deploy Wrangler config: .devflare/build/wrangler.jsonc
[log] Generated deploy redirect: .wrangler/deploy/config.json
[log] worker devflare-testing-binding-matrix-next
[log] Deploying with Wrangler…

 ⛅️ wrangler 4.81.1 (update available 4.82.2)
─────────────────────────────────────────────
Using redirected Wrangler configuration.
 - Configuration being used: ".devflare/build/wrangler.jsonc"
 - Original user's configuration: "<no user config found>"
 - Deploy configuration file: ".wrangler/deploy/config.json"
[success] Preview URL: https://devflare-testing-binding-matrix-next.refz.workers.dev
[warn] Deployment verification note: Wrangler completed the named preview-scope deploy for Worker "devflare-testing-binding-matrix-next" and exposed https://devflare-testing-binding-matrix-next.refz.workers.dev, but Cloudflare did not return a Worker version id. Devflare is treating this branch-scoped preview deploy as successful because named preview workers can lag in control-plane version metadata.
[warn] Devflare preview registry sync failed: This Worker does not exist on your account.
[success] Deployed successfully!
  • Auth impact: deploy (workspace dependency "devflare" changed)
  • Auth service version: not available
  • Search impact: deploy (workspace dependency "devflare" changed)
  • Search service version: not available
  • Main preview impact: deploy (workspace dependency "devflare" changed)
  • Deployed binding verification: passed
  • Verification mode: CI inspects deployed preview Worker metadata directly when Cloudflare exposes it, and otherwise falls back to the successful named-preview deploy output plus resolved preview config because the testing preview URL is protected by Cloudflare Access.
  • Preview strategy: named preview scope via --preview <branch> so the testing worker family deploys to the same explicit branch target.
  • Auth deploy status: success
  • Auth failure stage: n/a
  • Search deploy status: success
  • Search failure stage: n/a
  • Main preview deploy status: success
  • Main preview failure stage: n/a

@github-actions
github-actions Bot had a problem deploying to testing branch preview / next April 14, 2026 12:06 Failure
@github-actions
github-actions Bot had a problem deploying to testing branch preview / next April 14, 2026 13:21 Failure
@github-actions
github-actions Bot had a problem deploying to documentation branch preview / next April 14, 2026 17:21 Failure
@github-actions
github-actions Bot had a problem deploying to testing branch preview / next April 14, 2026 17:28 Failure
Refzlund and others added 30 commits October 12, 2026 22:15
… root, and the built CLI

Two gaps the next.100 review named:

- server.ts handed each Vite child `generatedRoot: app.generatedRoot`, and deleting that line left
  every test green. The launcher now comes through WorkspaceDevServerDeps (as loadMiniflare and
  acquireCoordinatorLock already do); workspace-vite-generated-root.test.ts records each child's
  options for two Vite apps and asserts each is handed the directory its own generated config was
  written to, with an in-app relative override as the control. Deleting the line now fails by name.
- Nothing ran the built package. A smoke case now runs the built CLI (dist/cli/index.js imported in
  place under Bun; the bin would run src under Bun) as `workspace dev --no-persist` with two apps
  under an absolute DEVFLARE_DIR, and checks each answers with its own code. It is armed (built from
  an unscoped server it answers I_AM_B on both ports), but that mutant kills the src cases too, so it
  shows no kill unique to dist; the test header says so.

QA round 1 (opus): 0 🔴, PASS; its two 🟡 (changeset wording, the built case's evidence) and two 🟢
(try/finally in afterEach, a coordinator that does not exit now fails afterAll) are applied here.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…dy" only once it is

A cold SvelteKit Vite printed its banner at 25.9 s against devflare's 15 s
wait. waitForViteReady resolved null at the bound and stopped caring, so the
log said the URL "could not be confirmed" (warn level, reads as a fault),
never reported the URL that then arrived, never reported an exit after the
bound, and the workspace printed "Workspace ready" ~10 s before the app served.

Design: keep the 15 s startup wait bounded. Both callers (devflare dev's
server.ts and the workspace server) register the child for teardown only once
startViteProcess returns, so an unbounded wait would leak a never-ready Vite
past Ctrl+C. Instead the watch continues past the bound:

- waitForViteReady gains onLateOutcome, called once with a ready URL or a
  failure that arrives after it resolved null; it also stops buffering output
  once decided (it re-scanned the whole session's output on every chunk).
- startViteProcess = spawn + new watchViteStartup, which returns a handle
  { child, ready, outcome } and logs: info "still starting" at the bound,
  success with the late URL, error on a late exit, warn at 60 s if neither.
  Late failures and the stall warning are muted while the caller is stopping.
- The workspace announces via announceWorkspaceReady: "Workspace ready" at
  once if every Vite app serves, else "Workspace started — …; waiting for
  Vite: …" then "Workspace ready" (or a warning naming apps that exited).

An exit or error within the bound still rejects, failing startup as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… the ready announcement

- red: nothing tested that workspace/server.ts USES announceWorkspaceReady;
  restoring the old unconditional "Workspace ready" line, or snapshotting the
  handle's `outcome` getter into a plain property, survived the suite. The
  announcement now takes the handle itself (`startup`), so there is no getter
  to copy, and a new integration test drives the server through its
  startViteProcess seam with one app serving and one that fails late. It
  kills both mutants plus dropping `appName` or `isStopping` from the spawn.
- yellow: the stall warning's stop guard was ungraded; a test now keeps the
  child alive past a stop and asserts no "may be stuck" line.
- yellow: the workspace spawn loop checks for a stop before each app, so a
  Ctrl+C during one slow Vite no longer spawns the next.
- yellow: two changeset sentences overclaimed (teardown reasoning, and
  "nothing is reported" for an exit during a stop within the first 15 s).

Not changed: `createDevServer.stop()` (single-app) does not await an
in-flight start(), so a stop during the startup wait can miss the Vite child.
That predates this change and is reported, not fixed here.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…irst end closed with

The BROWSER binding's workerd relay closed one end when the other closed by
copying the peer's code onto it. The two codes every session produces are
reserved: workerd reports 1006 when Chrome exits and drops its DevTools socket,
and 1005 for @cloudflare/puppeteer's disconnect (a bare ws.close()). workerd
refuses to SEND either. The copy threw, closeSocket() logged
`Failed to close socket: Invalid WebSocket close code: 1005.` and the other end
stayed open. A client with a CDP command in flight when Chrome went down — the
client's own Browser.close when Chrome exits before its reply flushes, or any
command when Chrome crashes — was never told, and waited out puppeteer's
180 s protocolTimeout. That is uidini's `browser close finished 174994ms after
its 5000ms budget`: 5000 + 174994 ≈ 180000.

workerd's rule, measured on workerd 1.20261006.1 (WebSocketPair end and
fetch-upgraded socket alike, compatibility dates 2024-01-01 and 2026-06-28):
close() with no code is sent and reported as 1005; 1000–1003, 1007–1014 and
3000–4999 are sent; 1004, 1005, 1006, 1015, <1000 and >4999 throw; 1016–2999
are sent but an RFC 6455 peer (the `ws` library, Chrome) fails the connection
on them; a reason over 123 UTF-8 bytes throws at 2026-06-28. relayedClose()
in the new close-codes.ts maps a report onto that: no status → no status, a
wire-valid code → itself, anything else → 1011 naming the original code, the
reason cut to 123 bytes on a character boundary. closeSocket() falls back to
an uncoded close if workerd refuses a coded one anyway (DEBUG-logged: the
socket did close), and reports only a socket that cannot be closed at all.
The function is injected into the workerd script by its source; a unit test
evaluates the rolldown output to hold it self-contained, because Bun inlines
module constants and would hide a broken copy that node ships.

The shim's own websocket relay in server.ts had the same 1000–4999 check and
the same defect under `ws`, and uses the same translation.

Why the tests missed it: the binding worker's socket double accepted every
code. It now enforces workerd's rule (tests/helpers/workerd-websocket-close.ts),
and the integration lane checks that model against real workerd.
tests/integration/shims/browser-binding-close.test.ts runs the generated script
in Miniflare between a client worker and a raw-socket stand-in Chrome (not the
`ws` package: Bun replaces it, and its close() sends 1000, not "no status").
Against the old relay it reads `hung` for a Chrome that drops mid-command,
1011 instead of 1005 for the no-status paths, and five `Failed to close socket`
lines; all six cases pass after.

E2E, real Chrome + @cloudflare/puppeteer 1.4.0, 20 sessions each: launch →
newPage → goto → close printed 20 `Failed to close socket` lines before and 0
after; a command in flight when Chrome crashed (CDP Browser.crash) was still
pending at 10 s in 20/20 sessions before and rejected in 44–184 ms in 20/20
after.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… through puppeteer's taskkill

The session registry ends a session on puppeteer's `disconnected`, which on the
dev path almost always means the client's own Browser.close already reached
Chrome and Chrome is exiting. It answered with browser.close(). puppeteer-core
25.13.0's BrowserLauncher.closeBrowser then tried a CDP close over the
connection that had just dropped, failed, and fell back to
@puppeteer/browsers 3.2.4's Process.kill(), which on Windows runs
`childProcess.execSync('taskkill /pid <pid> /T /F')` (lib/launch.js:275,
src/launch.ts:473) with no `stdio`. execSync inherits stderr, so taskkill's
complaints about the half-exited tree — `ERROR: The process "X" not found.`,
`… could not be terminated. Reason: There is no running instance of the task.`
— went straight to the dev log. Reproduced with the real shim launch and
registry and real chrome-headless-shell 155: 10 of 10 sessions closed over CDP
called taskkill (stack: kill ← close ← closeBrowser ← browserCloseCallback),
18 stderr lines. The same versions resolve under uidini's devflare@next.100.

A `disconnected` session is now REAPED, not closed: SessionBrowser gains
reap(), and chrome-process.ts gives a Chrome DEFAULT_EXIT_GRACE_MS (5 s) to
exit by itself — it took 6–91 ms in the reproduction — and kills it only if it
does not, with devflare's own killProcessTree (taskkill via execFile, output
captured; SIGKILL to the process group on POSIX), treating "already gone" as
success. A Chrome still running after its kill is a ChromeReapError, reported
once by the registry's existing boundary. The idle reaper, closeAll() and the
connection-timeout path meet a Chrome that is still running and keep the CDP
close; the registry passes the teardown to one end() so those paths and the
re-entrant `disconnected` a close fires stay a single code path. The puppeteer
launch moved into chrome-process.ts as launchChromeSession(), so a test can
drive the real launch without the shim's Chrome download.

Tests: sessions.test.ts grades which teardown each ending uses with a fake
browser that counts both; chrome-process.test.ts grades the reaper against a
fake process (exits by itself → never killed; still running → killed; survives
the kill → error naming the pid and the kill's output) and the real killer
against a real process (a kill of a dead pid hands back "not found" instead of
printing it). browser-shim-chrome.test.ts drives real Chrome when one is
already in ~/.devflare/chrome or DEVFLARE_TEST_CHROME_PATH, and skips, naming
why, otherwise (CI): with the pre-fix teardown it fails on three taskkill calls
whose errors print during the run; with the fix it sees none, and the idle and
shutdown paths still close cleanly.

Reproduction after the fix: 0 execSync calls, 0 stderr lines over 10 sessions;
E2E (20 sessions, @cloudflare/puppeteer 1.4.0): taskkill lines 25 → 0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…y leaves a Chrome that went away to the registry, and now relays at all

Round 1 (quality-reviewer, opus) returned PASS with 0 red. Its yellows, and
what was done with each:

1. Defect B was incomplete on a second path: the shim's own websocket relay
   (server.ts) still called registry.close() when Chrome's socket closed or
   errored — a CDP close aimed at a Chrome already exiting, and puppeteer's
   taskkill behind it. Those calls are gone: each edge of that relay now only
   releases, and the registry's `disconnected` reaps a Chrome that went away,
   so `disconnected` is again the one place that notices. The relay moved to
   devtools-relay.ts (relayDevtools) so it can be driven with socket
   stand-ins; its unit test kills the restored registry.close() by name.
   `/v1/history` therefore records such sessions as ChromeDisconnected (or
   BrowserIdle) rather than ChromeError. This also corrects commit 80df905's
   list of paths, which named only the registry's own.
2. binding-worker.ts said a CLOSING socket "has been closed by its own peer, so
   there is nothing left to do". False on older compatibility dates: measured
   at 2024-01-01, a socket whose peer sent Close stays CLOSING until the worker
   replies, and the relay never replies to the end that closed first. The
   comment now says so; the invariant (the OTHER end is closed) is unaffected,
   and uidini's 2026-06-28 date has workerd reply itself.
3. The 123-byte reason cut was graded only from below; a `> 124` mutant
   survived. A 124-byte reason must now come back as 123.
4. Nothing graded that a reap kills a live Chrome: `reap: async () => {}` and
   a null process both passed, because a Chrome asked to close exits by
   itself. The real-Chrome test now reaps a running Chrome with a 100 ms grace
   and requires its DevTools port gone inside the 5 s grace (both mutants now
   fail), and bounds the ordinary close inside the grace too.
5. The shim's own relay had no test — and probing it with real Chrome showed
   it never relayed anything: it forwarded the Buffer `ws` delivers, `ws`
   sends a Buffer as a BINARY frame, and Chrome dropped the connection, so no
   command got a reply (reproduced at dcb283c too). It also dropped what a
   client said before the relay's own Chrome socket opened. Text now goes on
   as text, early messages wait for Chrome (bounded by the connect timeout),
   and a socket closed before it opened no longer leaves the connect timeout
   to fire later. Real Chrome under Bun, 3 sessions: every command answered,
   each session ended ChromeDisconnected in 43–108 ms, nothing printed.
6. Overclaims narrowed: changeset A no longer says a close "can no longer hang"
   — a Chrome that stays up and never answers still waits out
   protocolTimeout; "Chrome fails the connection on 1016–2999" was measured
   only against `ws`, and close-codes.ts, the test helper and commit ba6bc18's
   message overstated it; sessions.ts no longer says exactly two things end a
   session.

Greens taken: contract docs on waitForExit, killPosixTree, end(), the
ChromeReapError constructor and the test helpers; a reap that had to kill
logs a debug line; the registry reports a teardown failure to the console
when it was given no logger (graded), rather than dropping it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`getDevflareDotenvPaths`, `parseDevflareEnvFile` and `loadDevflareDotenv` (with its result type)
are public now. Every command that loads a config runs this layer first, `deploy --prod`
included, so a script that must know what a deploy will see had to mirror the parser and the walk.
The internal barrel's types declared two of these already, with no entrypoint behind them.

The root entry re-exports the env-vars functions themselves rather than wrappers (asserted by
identity). The browser entry refuses them by name with a Node-only hint, and a new check pins that
it carries every root export, with the two gaps that predate it named. The mutating
`loadDevflareDotenvIntoProcess` stays internal. The docs gain the readers and a warning that
`.env.dev` reaches production deploys.

Fix: on Windows the walk climbed past a drive root to `/`, which pathe resolves against the
process's drive, so it read the wrong drive's root files or listed one root twice. It now ends
at the drive root.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
createRuntimeLogForwarder sent workerd's `warn` lines to logger.error with the
`error` ones — the split workerd's stdout and stderr once made — and
RuntimeLogLogger had no `warn`, so every console.warn a worker made printed
with an ` ERROR ` badge in the dev log (seen in uidini as
` ERROR  [uidini/share] browser close resolved 66ms after …`, a console.warn).

`warn` now goes to logger.warn, falling back to console.warn; `error` is
unchanged. All three callers (dev-server/server.ts ×2, workspace/server.ts)
pass a ConsolaInstance, which has `warn`.

The test that asserted warn → logger.error is replaced by one asserting warn →
logger.warn and error → logger.error, plus the console.warn fallback; both
failed before this change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…still running

reapExitingChrome decided "exited" by the runtime's `exit` event (or an exit
code) alone. On Windows that event can trail Chrome's exit by seconds: it
tracks the root's conhost.exe child going away, not the root. Measured with a
real chrome-headless-shell 156 closed over CDP `Browser.close`, under Bun 1.4.2
AND Node 25.9.0 (so not a Bun bug): process.kill(pid, 0) answered ESRCH first,
and `exit` came more than 1 s later in 10 of 65 Bun and 3 of 15 Node sessions,
17.6 s at worst; one Bun session saw none in 14 s. Past the 5 s grace the reap
killed a Chrome that had exited, waited 5 s more for the event, and threw
ChromeReapError "was still running … and it was killed" — while taskkill said
"There is no running instance of the task" for the root's pid.

waitForExit now also polls a liveness probe (new ReapOptions.isRunning,
default processIsRunning = process.kill(pid, 0); ESRCH gone, EPERM running,
anything else rejects the reap), at once, every 100 ms and at the deadline.
An `exit` still ends the wait at once. A Chrome the probe still reports
running after the kill is still a ChromeReapError.

Tests: fake processes whose `exit` never comes while the probe reports them
gone — before the grace, already gone, and after the kill — resolve
`exited`/`killed` without a kill or a throw (red before: they killed and threw);
one the probe reports running after the kill still throws and was probed after
the kill; a throwing probe rejects; processIsRunning answers for a real process
before and after it exits. Existing tests now inject the fake's probe, since
their made-up pids would otherwise be probed for real.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…eanup, EPERM and probe failure are graded

Round 1 (quality-reviewer, opus) returned PASS with 0 red. Its yellows, and
what was done with each:

1. The 100 ms liveness poll was ungraded (removed, all tests passed: the
   deadline probe answered 2 s later). The two "OS reports gone" cases now
   require the reap inside 500 ms of a 2 s grace, and the already-gone case
   inside 50 ms, which grades the probe asked at once.
2. Timer cleanup was ungraded: without clearInterval(poll) in stop() a 100 ms
   kill(pid, 0) loop ran on per reap, forever. A case per deciding path (the
   event, the OS) counts probe calls, waits 350 ms after the reap resolved,
   and requires the count not to move.
3. EPERM -> running was ungraded. processIsRunning takes the kill call as a
   second parameter (default process.kill); ESRCH, EPERM, another errno and a
   call that returns are each graded with a stand-in, no protected pid needed.
4. A probe that threw rejected the reap with its raw error, before any grace
   or kill, and the session's report named no Chrome. It is now a
   ChromeLivenessError naming the pid, saying whether the kill had run ("so it
   was not killed" before it), with the probe's error as `cause`. Chosen over
   falling back to an event-only wait: the probe failing at all is unexpected,
   and guessing on in that state is what produced the false report this lane
   exists to remove.
5. The changeset and the file header asserted a mechanism (`exit` follows the
   conhost.exe child going away) that was correlation, not measurement. Cut;
   the header now says why the event lags is not established. A new
   ReapOptions.onExitSeenByOs is told when the probe rather than the event
   decided, and toSessionBrowser writes it as a debug line, so a session
   whose `exit` never came leaves a trace.

Also: the real-Chrome test's answers(port) had no fetch timeout, and a reap
can now finish before Windows has closed Chrome's sockets; it is bounded at
2 s and a timeout reads as "not answering". Ran 6 times on Windows (18
sessions): 3 pass each time. And the processIsRunning real-process test now
probes in a loop that never yields on Windows, so the pid cannot be released
for reuse before the probe answers; POSIX still probes after `exit`, since a
zombie answers as running until the runtime reaps it.

Every new grade was checked against a mutant of the fixed source: no poll,
stop() leaving the poll, EPERM -> gone, the probe error unwrapped, no
onExitSeenByOs call, no probe at once, and no default trace in
toSessionBrowser — each is killed by the named cases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…is public

A predeploy check grading a config under a controlled environment had two bad choices. Running
`loadConfig` let the dotenv layer copy every ancestor `.env.public`, `.env.dev` and `.env` into
`process.env` first, so an untracked file on the checking machine decided the answer. Importing
the config module itself meant reading only its top-level `vars`, which misses `env.production`,
`extends`, `wrangler.passthrough.vars` and a sibling `devflare.config.js`, which c12 loads ahead of
the `.ts`. And `compileConfig` refuses a binding configured by name until `loadResolvedConfig` has
looked its id up over the network.

`loadConfig({ dotenv: false })` skips the layer and nothing else; the option guards that one call.
`compileBuildConfig`, the offline compile `devflare build` and `deploy --dry-run` already use, is
exported from `devflare` (the root entry re-exports the compiler's own function, asserted by
identity; the browser entry refuses it by name with a Node-only hint). Its doc-comment and the docs
say what it does NOT cover: an `env.X` descriptor stays a descriptor until a deploy resolves it,
preview-scoped names read `DEVFLARE_PREVIEW_*`, which `deploy --prod` clears, and Bun's own `.env`
loading needs `bun --no-env-file`. `LoadConfigOptions.environment` now says `loadConfig` ignores it.

Tests: the layer off and on for one fixture holding an ancestor `.env.public` and a `.env` beside
the config; `extends` and the schema still applied with it off; the compile contract, including a
name-only D1. Three mutants each die to exactly one case: the option ignored, c12's own dotenv
loader switched on, and an early return that skips the schema.

`resolveConfigEnvVars` stays internal: in build mode it throws on a required `env.X` descriptor
with no value, so a check under a controlled environment could not use it without failing correct
configs.

QA round 1 (one fresh reviewer, opus, xhigh): 1 🔴 (the docs said the compiled vars are what a
deploy ships, which is false for descriptors and inherited preview variables; deleted and replaced
by the caveats above) and 5 🟡, all fixed. No second round owed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…y off a config's vars

In dev the app directory's .dev.vars (or wrangler's .env fallback) is laid over vars and beats what
the config computed, so a launcher deciding those values itself could not hold them. With the switch
off, applyLocalDevVarsToConfig returns the config itself and reads no file. The name is exported as
LOCAL_DEV_VARS_ENV.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… the browser entry, an unknown value is refused, and "reads no file" is graded

The root export had no browser.ts mirror, which package-surface.test.ts caught; the name now lives in a
module that imports nothing and both entries re-export it. A value outside the two lists throws rather
than quietly keeping the overlay on. An unreadable .dev.vars (a directory) is opened with the switch
on and never with it off, which kills a guard moved after the read. Both test files start every case
with the switch unset. The docs name the @cloudflare/vite-plugin path the switch does not reach.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…f() evaluates what it imports

Every function satisfied DevflareConfigInput on its own (its `name` is a string, the rest is
optional), so the object overload of defineConfig took every factory: `defineConfig(async () => …)`
typed as TypedConfig, and no factory's body was checked against the schema. The object overload
now refuses functions through a `[Symbol.hasInstance]?: never` member, which a symbol key keeps out
of the literal's completions.

ref() read the referenced module's default raw, so an async config threw `Referenced config must
have a "name" property` and a named factory resolved to the function's own name. It now awaits the
default and calls it when it is a factory, as c12 does for loadConfig, and its types accept such
modules.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nts> declares

ExtractEntrypoints matched against TypedConfig<infer E> with the default vars,
Record<string, unknown>. Explicit entrypoints leave a config's vars `unknown`, which that refuses,
so every such config's accessor widened to `string`. Match with `unknown` vars instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… compiles again, and factory errors name the field

A value typed as the exported DefineConfigInput union matched none of the three overloads once the
object overload refused functions. A fourth overload takes it, its object arm guarded by the same
NotAFunction, and types the result as maybe-a-Promise. With four overloads TypeScript reports only
the last, so its single factory arm returns either form: two arms made one kind of factory's error
elaborate against the wrong one.

The probe now asserts each marked line's reason, not just its line, and grades ref().config for a
module exporting a raw factory. The changeset no longer claims parity with loadConfig (only with
c12's await-then-call step) or that ref()'s types newly accept such modules, and it names the two
type changes a consumer can hit: a factory that declares a parameter, and a DefineConfigInput value.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The child re-resolves its platform.env through resolveDevConfig, which reads the switch from its own
process.env, so buildViteChildEnv must not strip it with the two DEVFLARE_ channels it does strip.
Nothing graded that; stripping inherited DEVFLARE_* names now fails this case.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…, as build and dry run resolve them

`prepareDeployConfig` called `resolveConfigEnvVars` on the loaded config, which reads `config.vars`
alone, and `prepareConfigResourcesForDeploy` merged `env.<environment>` over it afterwards. A
descriptor in `env.production.vars` or `env.preview.vars` therefore reached
`.devflare/deploy/wrangler.jsonc` as the descriptor object, while `devflare build` and
`deploy --dry-run` (both merge, then resolve) printed its value. A required base descriptor that the
environment replaces failed the deploy and nothing else.

All three now resolve through `resolveConfigEnvVarsForEnvironment`, which merges and then resolves.
The deploy resolves before provisioning anything, then puts those `vars` back onto the config that
resource preparation re-merged. Preparation must keep taking the loaded config, because preview
prep finds preview-scoped resources by the unmaterialised binding strings.

Fixed by the same change:
- The drift check hashed the unmerged config while the build hashed the merged one, so every
  deploy of a config with an `env` section for its target warned "source config changed since
  build" about the artefact it had just built.
- The dry run's "Resolved view" re-merged the environment from the merged config's leftover
  `env` section and printed its descriptors.

Tests (`deploy-env-vars.test.ts`) drive the real deploy against a mocked Wrangler for `--prod`,
`--preview` and a shadowed base descriptor. Each case asserts the deployed `vars`, and that both
dry-run views print the same `vars`. A fourth case asserts the deploy reports no drift. Before the
fix, the three new resolution cases failed. Four mutants were each killed: dropping the `vars`
carry-over, resolving the unmerged config again, hashing the loaded config, and keeping the
re-merged `vars` in the resolved view.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e control, and the remark names a public call

- `resolveConfigEnvVars`'s `@remarks` pointed public readers at `resolveConfigEnvVarsForEnvironment`,
  which `devflare/config` does not export. It now names the public merge,
  `resolveResources(config, { phase: 'build', environment })`.
- The "no drift" deploy test matched a literal heading, so a reworded warning would have let it pass
  on any output. The heading now comes from `formatDriftWarning`. A positive control also deploys
  with `--build` after the config changed and expects drift. With drift reporting disabled, only
  that control fails; the no-drift case cannot see it.

Left for the owner (reported, not changed here):
- Nothing checks that preview prep receives the loaded, unmaterialised config. Passing it the
  materialised `targetConfig` survives every deploy suite, and `--preview` would then provision no
  preview resources. This gap predates the commit. Closing it takes a `--preview` deploy with a
  preview-scoped binding against a stubbed Cloudflare API.
- `mergeEnvironmentValue` deep-merges two env descriptors that share a key, because descriptors are
  plain objects. The environment's descriptor then inherits the base's `.parse()`. This predates the
  commit, but build, dry run and deploy now all share it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ble instead of throwing

A predeploy check could not see what an `env.X` descriptor's `.default()` ships. `loadConfig({ dotenv:
false })` and `compileBuildConfig` leave each descriptor as the object it is, so a check reading `vars`
as strings passed `env.SHARE_ORIGIN.default('http://localhost:5991')` while a deploy shipped the
localhost address. The resolvers devflare uses were no substitute: `resolveConfigEnvVars` reads the
dotenv files, and both it and `resolveVarsFromSources` throw in build mode on a required variable with
no value, which fails a correct config that nobody has provisioned in the check's environment.

`resolveConfigEnvVarsFromSources(config, { environment, sources, mode })` is exported from `devflare`.
It merges the environment, then resolves every descriptor in the merged `vars`, the order
`resolveConfigEnvVarsForEnvironment` uses for build, dry run and deploy. `mode` defaults to `build`.
A descriptor reads `sources` alone (preview-scoped names still materialise from `DEVFLARE_PREVIEW_*`
in `process.env`, as a build does). It returns `{ config, missing }`: a required variable with no
value is listed with its path and left out of `config.vars`, a parser refusing a value still throws,
and the config carries no `env` sections, so compiling it again for the environment cannot merge an
unresolved descriptor back in. The browser entry refuses it by name. The throwing resolvers stay internal and now share its core,
`resolveVarsReportingMissing`, so all of them resolve one way.

Tests: `tests/unit/config/env-vars-from-sources.test.ts` (11 cases) — a default ships and a source
wins over it; a missing required variable is reported and dropped, an absent optional one only
dropped; build is the default mode (`.dev()` and `.absentInDev()` off, with dev as the control); the
environment merges first; `process.env` is not read; a parser refusal throws; the documented
`compileBuildConfig(…, { alreadyResolved: true })` recipe emits the resolved values; and two agreement
cases run the build's own resolver over the same values; the result has no `env` section, so a
second compile for the environment agrees; and preview names materialise, from `process.env`. `package-surface.test.ts` asserts the root
export by identity, the throwing resolvers' absence, and the browser refusal. Seven mutants each died:
mode defaulting to dev (2 cases), the merge skipped (3), `process.env` read (1), `missing` emptied (3),
a throw on a missing variable (3), the `env` section kept (1), and the merge without preview
materialisation (1). The unit lane on this commit: 2159 pass, 2 skip, 0 fail.

Docs: the configuration page, `LLM.md`, the README export table, `API_STABILITY.md`, and
`compileBuildConfig`'s doc-comment, which now names the resolution step instead of only warning.

QA round 1 (one fresh reviewer, opus, xhigh): PASS, 0 🔴, five 🟡, all fixed — the returned config
kept its `env` section; "reads `sources` and nothing else" was false for preview names; preview
materialisation was untested; `EnvVarParseError` was documented as importable and is not (its `code`
is documented instead, and `EnvResolutionMode` is exported); and a test comment overclaimed what the
agreement cases detect. Two 🟢 taken: `missing` is in walk order, not declaration order, and a plain
object rather than `process.env` itself is advised, since win32 matches its names case-insensitively.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch was successfully deployed

2 active (outdated) deployments
testing branch preview / next — a414c8bd Deployed Oct 23, 2026 by github-actions[bot]
documentation branch preview / next — a414c8bd Deployed Oct 23, 2026 by github-actions[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant