sproutboat 0.52.0 → 0.53.0

package/CHANGELOG.md

@@ -10,6 +10,36 @@ maintained going forward by the `release` skill.
 
 ## Unreleased
 
+## [0.53.0] - 2026-11-09
+
+Built on `@sproutboat/runtime` 0.43.0, `@sproutboat/wire` 0.22.3 and `@sproutboat/toolchain` 0.24.2. The runtime change is the opt-in `SB_LOG=json` log below; without it nothing an app can observe changes, so there is no new compatibility date. Every app is recompiled on its next build, since the runtime prelude changed.
+
+### Added
+
+- **`sproutboat tail --file <log|->` follows a standalone binary's request and error records (#268).** Run the binary with `SB_LOG=json` (runtime 0.43.0 writes them) and `tail --file` prints the last 10 matching records, then new ones as they are written, in pretty lines or one JSON record per line (`--format json`). `--status`, `--method` and `--search` filter; `--lines` sets the snapshot size and `--no-follow` prints it and exits; `--file -` reads a pipe such as `journalctl -f -o cat`. An error follows its request's filters, and errors from background work always show. A missing file is waited for, a rotated or truncated file is reread from its start, a line over 64 KiB is skipped and counted, control characters are replaced before printing, and only known fields are written, so output stays bounded and parseable. It needs no login or network and ends with exit 0 on Ctrl-C. The existing control plane `tail` (live stream, `--format json`, filters, `--recent`, `--sprout`) is unchanged. See "Logs" in `docs/standalone.md`.
+- **`sproutboat run` launches a standalone binary with its settings supplied at launch (#275).** `sproutboat run [project-dir] --env-file prod.env --port 80 --data-dir /var/lib/app` starts `dist/<name>` (or `--binary`) with an environment built from three layers, highest first: `--port` and `--data-dir`, the `--env-file` files (repeat the flag; a later file overrides an earlier one), then the inherited environment. Like `wrangler deploy`, it fails before the binary starts when a declared secret (the config's `secrets` plus `--require`) is unset or empty; `--check` validates and prints a summary without starting it. The summary names each secret and the layer it came from, never a value, nothing is written to disk, and the binary and its artifact metadata are untouched, so the identical binary moves between development and production. SIGINT, SIGTERM and SIGHUP are passed to the binary and its exit status is returned. `examples/vars-secrets` walks through it.
+
+### Changed
+
+- **`init` scaffolds the Workers-style handler.** New projects get compatibility date `2026-09-28` and `fetch(request, env, ctx)`, so `env` and `ctx` are available without a date bump. Existing `sproutboat.jsonc` files are never rewritten, and projects on older dates keep their behavior.
+- **`sproutboat dev` takes local secrets the way Wrangler does (#275).** `.dev.vars` or the `.env` files, never both (a warning names the ignored ones); `--env <name>` selects `.dev.vars.<name>` and the `.env.<name>` files; the `.env` files layer `.env.<name>.local`, `.env.local`, `.env.<name>`, `.env`; `CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV=false` turns them off; `--env-file <file>` (repeatable, later overrides earlier) replaces the default set. The process environment is not passed to the app, except for declared secret names when `CLOUDFLARE_INCLUDE_PROCESS_ENV=true` and no `.dev.vars` is in use, and files win over it. A declared secret with no value is a warning and `dev` still starts. Files use dotenv syntax; a line that is not an assignment is skipped with a `file:line` warning that never repeats the line.
+- **`.dev.vars` is now parsed with dotenv syntax.** It used to be a simpler format. The differences that can matter: an unquoted value ends at a `#` (it used to keep it), quotes may be single, double or backtick, double quotes expand `\n`, and the last of a repeated name wins. A line that is not an assignment is skipped with a warning instead of silently.
+- **`docs/standalone.md` no longer lists `<data>/secrets.json`**: a standalone binary has only ever read secrets from the environment.
+
+### Fixed
+
+- **The native conformance harnesses no longer hang on a stalled response (#276).** The broker and standalone kitchen-sink harnesses and the small-example smoke runner give every HTTP and raw-socket request a deadline (`SB_HARNESS_REQUEST_TIMEOUT_MS`, default 30 s) that covers the whole body, and bound readiness (`SB_HARNESS_READY_TIMEOUT_MS`) and compilation (`SB_HARNESS_BUILD_TIMEOUT_MS`) separately, so a slow build cannot look like a hung handler. A timeout, or a child that exits during a request, reports the step, backend, runtime and toolchain versions and the child's recent stderr with secret values removed. Only the run's own children are stopped and its temp dir removed, on failure and on SIGINT or SIGTERM. Fault-injection tests cover a server that never completes a body and a child that exits mid-request. This is repository tooling; the shipped CLI does not change.
+
+## [0.52.1] - 2026-11-08
+
+Built on `@sproutboat/toolchain` 0.24.2, `@sproutboat/runtime` 0.42.2 and `@sproutboat/wire` 0.22.2. The compiler output changes (four Porffor alpha 22 miscompile fixes in the toolchain), so every app is recompiled on its next build. Nothing else an app can observe changes, so there is no new compatibility date.
+
+### Fixed
+
+- **Four Porffor alpha 22 miscompiles are fixed** (toolchain 0.24.2), found with postgres.js and drizzle-orm. A method call on a receiver of unknown type evaluated its arguments in C's unspecified order, so `buf.toString("utf8", i, i += n)` returned `""`. A class declaration that is assigned to, such as TypeScript's `(SQL || (SQL = {}))` namespace merge, never stored the class in its binding and died with "Cannot get property of null". The right operand of `||`, `&&` and `??` retyped a local at compile time as if it always ran, so the same pattern inside a function still failed. `new Date(s)` returned NaN for `+HH` and `+HHmm` offsets such as Postgres' `2026-11-08 14:48:19.097+00`; they now parse, together with `+HH:mm`.
+- **A warm standalone build no longer recompiles every C unit.** The alpha 22 build cleared the units directory, object cache included, before each render, so every build paid the full C compile (about 13 s for hello on an M1). It now clears only the previous render and keeps `obj/`; a unit whose text and flags are unchanged is not compiled again.
+- **`build --standalone --target host` uses the compile cache.** An unchanged host build returns in about 0.2 s (was about 39 s for hello). The key includes the host compiler's name and `--version` banner. Dev builds still bypass it.
+
 ## [0.52.0] - 2026-11-06
 
 Built on `@sproutboat/toolchain` 0.24.1, `@sproutboat/runtime` 0.42.2 and `@sproutboat/wire` 0.22.2. The compiler changes, so every app is recompiled on its next build. Nothing an app can observe changes apart from the two fixes below, so there is no new compatibility date.

package/README.md

@@ -197,8 +197,12 @@ chunking, resume state, cleanup, and the remaining download limitation.
 `sproutboat dev` runs against a real local broker, so bindings behave like
 production without a deploy — except `secrets`, which live only in the control
 plane. Put values in a `.dev.vars` file next to `sproutboat.jsonc`
-(`API_KEY=whatever`, one per line, gitignored) and `env.API_KEY` resolves under
-`dev` only.
+(`API_KEY=whatever`, one per line, gitignored), or use the `.env` files or
+`sproutboat dev --env-file <file>`, as in Wrangler (`.dev.vars` or `.env`, never
+both), and `env.API_KEY` resolves under `dev` only. A declared secret with no
+value is a warning. The rules, the dotenv syntax, and `sproutboat run` for
+launching a standalone binary (which fails on a missing declared secret) are in
+[docs/standalone.md](docs/standalone.md#launching-with-sproutboat-run).
 
 ## Requirements
 

package/SURFACE.md

@@ -3,7 +3,7 @@
 > Generated by `src/surface.test.ts` from `src/surface.ts` + the pinned
 > toolchain constants. Do not edit by hand — run `UPDATE_SURFACE=1 bun test`.
 
-**Package:** `sproutboat` 0.52.0
+**Package:** `sproutboat` 0.53.0
 
 ## Commands
 
@@ -12,13 +12,14 @@
 | `init` | `[name]` | Scaffold sproutboat.jsonc + src/index.js in ./<name>. |
 | `check` | `[project-dir]` | Validate the config and entry point without building. |
 | `types` | `[project-dir]` | Write sproutboat-env.d.ts from the config, so an editor knows what `env` holds. `dev` and `deploy` refresh it when the config is newer. |
-| `dev` | `[project-dir] [--port <n>] [--no-watch]` | Run the project on this machine against a real broker, rebuilding on save. |
+| `dev` | `[project-dir] [--port <n>] [--no-watch] [--env <name>] [--env-file <file>]...` | Run the project on this machine against a real broker, rebuilding on save. Secrets come from .dev.vars or the .env files (never both), as in Wrangler; a declared secret with no value is a warning. |
+| `run` | `[project-dir] [--binary <file>] [--env-file <file>]... [--port <n>] [--data-dir <dir>] [--require <NAME,...>] [--check]` | Launch a standalone binary with its port, data directory and declared secrets supplied at launch, never baked in. Precedence: --port/--data-dir, then the --env-file files (later overrides earlier), then the environment. A missing declared secret fails the launch, like wrangler deploy; --check validates without starting. |
 | `build` | `[project-dir] [--target host|linux-x64|linux-arm64] [--standalone] [--deploy-files] [--with-restore] [--emit-only]` | Cross-compile the native-fetch sprout (Porffor + Zig). `--target host` builds for this machine instead, to run locally, not deployable. `--standalone` emits one executable carrying its own bindings, with SQLite compiled in (~2 MB) and no broker process; add `--target linux-arm64` for an aarch64 box (the default is `linux-x64`) and `--deploy-files` to write a Dockerfile, a systemd socket and service, a fly.toml and a push script beside it. `--with-restore` adds an offline `APP ltx-restore --generation DIR --output NEW_DB [--txid N]` startup command to a standalone executable; it runs before app initialization. `--emit-only` stops after writing `.sproutboat/porffor-units/<shape>/sprout.generated.js`, the module Porffor would compile, and prints its path: every check still runs, nothing is compiled. |
 | `toolchain` | `doctor [--json]` | Report the selected compiler inputs, cache locations, overrides, and host prerequisites without downloading or compiling anything. |
 | `deploy` | `[project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision]` | Build (unless --artifact), auto-provision id-less storage bindings and pin their ids into sproutboat.jsonc, print the report, upload, wait until the URL serves. The control plane skips an upload that matches the live artifact byte-for-byte. --dry-run stops before upload; --no-wait skips the health check; --no-provision leaves id-less bindings as ephemeral deploy-scoped stores. |
 | `versions` | `<list | view <version-id>> [project-dir]` | List the project's deployed versions, or show one version's artifact and bindings. |
 | `rollback` | `<version-id> [project-dir]` | Re-activate a previous version. |
-| `tail` | `[project-dir] [--format pretty|json] [--status ok|error|<code>|5xx] [--method GET,POST] [--sampling-rate <0..1>] [--search <text>] [--outcome <name>] [--recent] [--sprout]` | Stream live request events, console output and exceptions (like wrangler tail); --recent prints the last 100 request records, --sprout the running sprout + broker stdout/stderr. |
+| `tail` | `[project-dir] [--format pretty|json] [--status ok|error|<code>|5xx] [--method GET,POST] [--sampling-rate <0..1>] [--search <text>] [--outcome <name>] [--recent] [--sprout] [--file <log|-> [--lines <n>] [--no-follow]]` | Stream live request events, console output and exceptions (like wrangler tail); --recent prints the last 100 request records, --sprout the running sprout + broker stdout/stderr. --file follows the JSON records a standalone binary writes with SB_LOG=json (no login needed). |
 | `kv` | `<list | create <name> | info <name> | rename <name> <new> | delete <name>> | <key | bulk | export> ...` | KV namespaces. `create` prints the id to bind from sproutboat.jsonc; key and bulk operations manage contents, and export writes a restorable JSON dump. |
 | `d1` | `<list | create <name> | info <name> | rename <name> <new> | delete <name>>` | D1 databases. `create` prints the id to bind from sproutboat.jsonc. |
 | `r2` | `<list | create <name> | info <name> | rename <name> <new> | delete <name>>` | R2 buckets. `create` prints the id to bind from sproutboat.jsonc. |
@@ -32,7 +33,7 @@
 | `complete` | `[bash | zsh | fish]` | Print a shell completion script for the top-level commands (defaults to $SHELL). |
 
 ```
-usage: sproutboat <init [name] | check [project-dir] | types [project-dir] | dev [project-dir] [--port <n>] [--no-watch] | build [project-dir] [--target host|linux-x64|linux-arm64] [--standalone] [--deploy-files] [--with-restore] [--emit-only] | toolchain doctor [--json] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision] | versions <list | view <version-id>> [project-dir] | rollback <version-id> [project-dir] | tail [project-dir] [--format pretty|json] [--status ok|error|<code>|5xx] [--method GET,POST] [--sampling-rate <0..1>] [--search <text>] [--outcome <name>] [--recent] [--sprout] | kv <list | create <name> | info <name> | rename <name> <new> | delete <name>> | <key | bulk | export> ... | d1 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | r2 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | queues <list | create <name> | info <name> | rename <name> <new> | delete <name>> | domains <list | add <host> | verify <host> | delete <host>> [project-dir] | secrets <list | put <NAME> [--value <value>] | delete <NAME>> [project-dir] | delete [project-dir] [--name <project>] --yes | login [--api-url <url>] [--token <token>] | logout [--api-url <url>] | whoami | complete [bash | zsh | fish]>
+usage: sproutboat <init [name] | check [project-dir] | types [project-dir] | dev [project-dir] [--port <n>] [--no-watch] [--env <name>] [--env-file <file>]... | run [project-dir] [--binary <file>] [--env-file <file>]... [--port <n>] [--data-dir <dir>] [--require <NAME,...>] [--check] | build [project-dir] [--target host|linux-x64|linux-arm64] [--standalone] [--deploy-files] [--with-restore] [--emit-only] | toolchain doctor [--json] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] [--no-provision] | versions <list | view <version-id>> [project-dir] | rollback <version-id> [project-dir] | tail [project-dir] [--format pretty|json] [--status ok|error|<code>|5xx] [--method GET,POST] [--sampling-rate <0..1>] [--search <text>] [--outcome <name>] [--recent] [--sprout] [--file <log|-> [--lines <n>] [--no-follow]] | kv <list | create <name> | info <name> | rename <name> <new> | delete <name>> | <key | bulk | export> ... | d1 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | r2 <list | create <name> | info <name> | rename <name> <new> | delete <name>> | queues <list | create <name> | info <name> | rename <name> <new> | delete <name>> | domains <list | add <host> | verify <host> | delete <host>> [project-dir] | secrets <list | put <NAME> [--value <value>] | delete <NAME>> [project-dir] | delete [project-dir] [--name <project>] --yes | login [--api-url <url>] [--token <token>] | logout [--api-url <url>] | whoami | complete [bash | zsh | fish]>
 ```
 
 ## Environment variables

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "keywords": [
     "cli",
@@ -64,9 +64,9 @@
     "@sproutboat/artifact": "^0.3.0",
     "@sproutboat/assets": "^0.3.0",
     "@sproutboat/config": "^0.6.0",
-    "@sproutboat/runtime": "^0.42.2",
-    "@sproutboat/toolchain": "^0.24.1",
-    "@sproutboat/wire": "^0.22.2"
+    "@sproutboat/runtime": "^0.43.0",
+    "@sproutboat/toolchain": "^0.24.2",
+    "@sproutboat/wire": "^0.22.3"
   },
   "devDependencies": {
     "@oxlint/plugins": "1.85.0",
@@ -78,10 +78,10 @@
     "typescript": "7.0.2"
   },
   "optionalDependencies": {
-    "@sproutboat/cli-darwin-arm64": "0.52.0",
-    "@sproutboat/cli-darwin-x64": "0.52.0",
-    "@sproutboat/cli-linux-arm64": "0.52.0",
-    "@sproutboat/cli-linux-x64": "0.52.0"
+    "@sproutboat/cli-darwin-arm64": "0.53.0",
+    "@sproutboat/cli-darwin-x64": "0.53.0",
+    "@sproutboat/cli-linux-arm64": "0.53.0",
+    "@sproutboat/cli-linux-x64": "0.53.0"
   },
   "engines": {
     "node": ">=18"

package/src/build.ts

@@ -18,7 +18,7 @@ import {
   RUNTIME,
   type ArtifactManifest,
 } from "./manifest";
-import { ensureZig, esbuildVersion, porfforVersion, toolchainStamp } from "./toolchain";
+import { ensureZig, esbuildVersion, hostCompilerIdentity, porfforVersion, toolchainStamp } from "./toolchain";
 import { PORFFOR_ARCHIVE_SHA256, PORFFOR_COMMIT_FULL } from "./porffor-toolchain";
 import { A21_STANDALONE_FINGERPRINT } from "@sproutboat/toolchain/a21";
 import { version as toolchainPackageVersion } from "@sproutboat/toolchain/package.json" with { type: "json" };
@@ -346,6 +346,8 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
           : null,
       native: embedded ? [sqliteStamp(), bearsslStamp()] : subtle ? [bearsslStamp()] : [],
       integration: await integrationIdentity(),
+      // a host binary comes from this machine's C compiler, so a different compiler is a different binary
+      hostCompiler: host ? await hostCompilerIdentity() : null,
       nativeRestore: input.withRestore ? NATIVE_RESTORE_IDENTITY : null,
     }),
   ).slice("sha256:".length);
@@ -399,7 +401,6 @@ export async function buildArtifact(input: BuildInput): Promise<BuildOutput> {
     const compileStartedAt = performance.now();
     if (
       !input.reuseSproutPath &&
-      !host &&
       input.optimize !== "dev" &&
       !input.outputDirectory &&
       !versionMetadata &&

package/src/compile.ts

@@ -164,6 +164,23 @@ export async function loadPrelude(transport: Transport = "broker"): Promise<stri
   return core.replace(TRANSPORT_MARKER, chosen);
 }
 
+/**
+ * Drop the previous render from a units directory, keeping `obj/`.
+ *
+ * The renderer rewrites every unit, and a unit whose name changed must not linger (the build compiles every
+ * `.c` it finds). `obj/` holds the objects `buildStandaloneA21` stamps by the unit text, `porf.h` and the
+ * flags, so it has to survive a rebuild: wiping it recompiled every unit on every build, which made a warm
+ * host build as slow as a cold one (about 13 s of C compile plus the link).
+ */
+export async function clearRenderedUnits(unitsDir: string): Promise<void> {
+  const entries = await readdir(unitsDir).catch((): string[] => []);
+  await Promise.all(
+    entries
+      .filter((name) => name !== "obj")
+      .map((name) => rm(resolve(unitsDir, name), { recursive: true, force: true })),
+  );
+}
+
 let porfforBuildsPruned = false;
 /**
  * Porffor writes one build dir per entry path under ~/.cache/porffor/build and
@@ -448,7 +465,7 @@ async function compileSproutA21(
   const entry = resolve(dir, "sprout.a22.js");
   await writeFile(entry, composed.entry);
   const unitsDir = resolve(dir, "units-a22");
-  await rm(unitsDir, { recursive: true, force: true }).catch(() => {});
+  await clearRenderedUnits(unitsDir);
   // the compiler's own build cache (keyed by entry path) is not used: `c` only renders
   const render = Bun.spawn(
     [

package/src/dev.ts

@@ -18,6 +18,7 @@ import { dirname, resolve } from "node:path";
 import { buildArtifact } from "./build";
 import { createBroker, listen, listenTransfers, type Bindings, type Broker } from "./broker";
 import { jsonObject, parseJsonValue } from "./json";
+import { resolveDevVars } from "./env-file";
 import { amber, dim, leaf, ok } from "./style";
 import type { SproutboatConfig } from "./config";
 
@@ -32,6 +33,10 @@ export type DevInput = {
   source: string;
   port: number;
   watch: boolean;
+  /** #275: `--env-file` paths (absolute), in order. Default: `.dev.vars`, else the `.env` files. */
+  envFiles?: string[];
+  /** #275: `--env <name>`, which selects `.dev.vars.<name>` and the `.env.<name>` files. */
+  envName?: string;
   /** Re-read the complete project after a change; throws with a readable message. */
   rebuild: () => Promise<Pick<DevInput, "config" | "sourcePath" | "source">>;
   /** Set internally for an asset-only refresh, where recompiling is unnecessary. */
@@ -54,30 +59,25 @@ export function isAssetOnlyRefresh(
 }
 
 /**
- * Secrets for local dev, `KEY=value` per line, from `.dev.vars` beside the
- * config — the same file Wrangler uses. Deployed secrets live in the control
- * plane and are never on a developer's disk, so this is the only way a bound
- * secret can resolve here.
+ * Secrets for local dev (#275), by Wrangler's rules (env-file.ts): `.dev.vars`
+ * or the `.env` files, never both; the process environment only with
+ * CLOUDFLARE_INCLUDE_PROCESS_ENV=true. A declared secret with no value, or a
+ * skipped line, is a warning and `dev` still starts. Read on every (re)start, so
+ * an edited file is picked up.
  */
-async function readDevVars(projectDir: string): Promise<Record<string, string>> {
-  const path = resolve(projectDir, ".dev.vars");
-  if (!existsSync(path)) return {};
-  const text = await readFile(path, "utf8");
-  return Object.fromEntries(
-    text.split("\n").flatMap((line): Array<[string, string]> => {
-      const trimmed = line.trim();
-      if (trimmed === "" || trimmed.startsWith("#")) return [];
-      const eq = trimmed.indexOf("=");
-      if (eq <= 0) return [];
-      const value = trimmed.slice(eq + 1).trim();
-      // Accept quoted values, since a secret can legitimately contain spaces.
-      const unquoted =
-        (value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))
-          ? value.slice(1, -1)
-          : value;
-      return [[trimmed.slice(0, eq).trim(), unquoted]];
-    }),
-  );
+export async function devSecrets(
+  input: Pick<DevInput, "projectDir" | "envFiles" | "envName" | "config">,
+  inherited: Record<string, string | undefined> = process.env,
+): Promise<Record<string, string>> {
+  const resolved = await resolveDevVars({
+    projectDir: input.projectDir,
+    envName: input.envName,
+    envFiles: input.envFiles,
+    declared: input.config.secrets ?? [],
+    inherited,
+  });
+  for (const warning of resolved.warnings) console.warn(amber(`! ${warning}`));
+  return resolved.values;
 }
 
 /** `bindings.json` is written by the build whenever the project declares any. */
@@ -149,7 +149,7 @@ async function start(input: DevInput, port: number): Promise<Running> {
       resourceDir: resolve(stateDir, "resources"),
       token: "sproutboat-dev",
       bindings: await readBindings(artifactDir),
-      secrets: await readDevVars(input.projectDir),
+      secrets: await devSecrets(input),
       sproutUrl: `http://127.0.0.1:${port}/`,
       assetsDir: existsSync(assetsDir) ? assetsDir : undefined,
       dispatchEnabled: () => dispatchEnabled,

package/src/env-file.ts

@@ -0,0 +1,248 @@
+/**
+ * Local secret input (#275), modelled on Wrangler so the habits carry over.
+ *
+ * `sproutboat dev` takes local secrets from files, never from the process
+ * environment unless asked:
+ *
+ * - `.dev.vars` beside the config, or the `.env` files, never both. When a
+ *   `.dev.vars` exists the `.env*` files are not loaded (a warning names them).
+ *   With `--env <name>`, `.dev.vars.<name>` replaces `.dev.vars` when it exists.
+ * - The `.env` files layer, most specific first: `.env.<name>.local`,
+ *   `.env.local`, `.env.<name>`, `.env`. `CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV=false`
+ *   turns this off. Repeated `--env-file` flags replace the default set; a later
+ *   file overrides an earlier one.
+ * - The process environment reaches the app only when
+ *   `CLOUDFLARE_INCLUDE_PROCESS_ENV=true` and no `.dev.vars` is in use, and then
+ *   only for declared secret names. Files win over it.
+ * - A declared secret with no value is a warning, and `dev` still starts.
+ *
+ * `sproutboat run` (the production launch of a standalone binary) is stricter:
+ * a missing declared secret fails, like `wrangler deploy`. Its layers, highest
+ * first: `--port` and `--data-dir`, the `--env-file` files (later overrides
+ * earlier), the inherited environment.
+ *
+ * File syntax is dotenv's: `NAME=value`, an optional `export `, `#` comments
+ * (a whole line, or after an unquoted value), single, double and backtick quotes,
+ * `\n` and `\r` expanded inside double quotes only, quoted values may span lines,
+ * the last of a repeated name wins. A line that is not an assignment is skipped
+ * with a `file:line` warning. Warnings never repeat the text of a line, so a value
+ * cannot leak through one.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+export type EnvEntry = { key: string; value: string; line: number };
+export type EnvSource = "option" | "env file" | "environment";
+export type ParsedEnv = { entries: EnvEntry[]; warnings: string[] };
+
+/** A file that could not be read at all (a missing explicit file). The message is safe to print. */
+export class EnvFileError extends Error {}
+
+/** Declared secrets that are unset or empty, for a launch that must not start without them. Names only. */
+export class MissingSecretsError extends Error {
+  constructor(
+    readonly names: string[],
+    where: string,
+  ) {
+    super(
+      `missing declared secret${names.length === 1 ? "" : "s"}: ${names.join(", ")}. Set ${names.length === 1 ? "it" : "them"} in ${where} or in the environment.`,
+    );
+  }
+}
+
+const ASSIGNMENT = /^\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*|:\s+)(.*)$/;
+
+/** Parse dotenv text. Never throws: a bad line becomes a warning. */
+export function parseDotenv(text: string, label: string): ParsedEnv {
+  const source = (text.startsWith("") ? text.slice(1) : text).replace(/\r\n?/g, "\n");
+  const lines = source.split("\n");
+  const byKey = new Map<string, EnvEntry>();
+  const warnings: string[] = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) continue;
+    const match = ASSIGNMENT.exec(line);
+    if (!match) {
+      warnings.push(`${label}:${index + 1}: skipped, not a NAME=value assignment`);
+      continue;
+    }
+    const key = match[1];
+    const rest = match[2].trimStart();
+    const quote = rest[0];
+    let value: string;
+    if (quote === "'" || quote === '"' || quote === "`") {
+      let out = "";
+      let row = index;
+      let column = 0;
+      let current = rest.slice(1);
+      let closed = false;
+      for (;;) {
+        while (column < current.length) {
+          const char = current[column];
+          // As in dotenv, an escaped closing quote does not end the value (and the backslash stays).
+          if (char === "\\" && current[column + 1] === quote) {
+            out += char + quote;
+            column += 2;
+            continue;
+          }
+          if (char === quote) {
+            closed = true;
+            break;
+          }
+          out += char;
+          column += 1;
+        }
+        if (closed || row + 1 >= lines.length) break;
+        row += 1;
+        current = lines[row];
+        column = 0;
+        out += "\n";
+      }
+      if (!closed) {
+        warnings.push(`${label}:${index + 1}: skipped, unterminated ${quote} quote`);
+        break;
+      }
+      index = row;
+      value = quote === '"' ? out.replace(/\\n/g, "\n").replace(/\\r/g, "\r") : out;
+    } else {
+      const hash = rest.indexOf("#");
+      value = (hash >= 0 ? rest.slice(0, hash) : rest).trim();
+    }
+    byKey.set(key, { key, value, line: index + 1 });
+  }
+  return { entries: [...byKey.values()], warnings };
+}
+
+/** Read and parse an env file. Throws EnvFileError when it cannot be read. */
+export async function readEnvFile(path: string): Promise<ParsedEnv> {
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    const code = error instanceof Error && "code" in error ? error.code : undefined;
+    if (code === "ENOENT") throw new EnvFileError(`env file not found: ${path}`);
+    throw new EnvFileError(`could not read ${path}: ${code ?? "unknown error"}`);
+  }
+  return parseDotenv(text, path);
+}
+
+/** Later entries override earlier ones, by name. */
+export function mergeEntries(layers: EnvEntry[][]): EnvEntry[] {
+  const merged = new Map<string, EnvEntry>();
+  for (const layer of layers) for (const entry of layer) merged.set(entry.key, entry);
+  return [...merged.values()];
+}
+
+export type EnvInput = {
+  inherited: Record<string, string | undefined>;
+  file?: EnvEntry[];
+  /** Explicit launch options as environment variables: `--port` is PORT, `--data-dir` is SB_DATA_DIR. */
+  options?: Record<string, string>;
+};
+export type ResolvedEnvironment = { env: Record<string, string>; sources: Map<string, EnvSource> };
+
+/** The environment to launch with, and which layer each name came from. Values are never logged. */
+export function resolveEnvironment(input: EnvInput): ResolvedEnvironment {
+  const env: Record<string, string> = {};
+  const sources = new Map<string, EnvSource>();
+  for (const [key, value] of Object.entries(input.inherited)) {
+    if (value === undefined) continue;
+    env[key] = value;
+    sources.set(key, "environment");
+  }
+  for (const entry of input.file ?? []) {
+    env[entry.key] = entry.value;
+    sources.set(entry.key, "env file");
+  }
+  for (const [key, value] of Object.entries(input.options ?? {})) {
+    env[key] = value;
+    sources.set(key, "option");
+  }
+  return { env, sources };
+}
+
+/** Declared secrets that are unset or empty in `env`, in declaration order. */
+export function missingSecrets(declared: readonly string[], env: Record<string, string>): string[] {
+  return declared.filter((name) => (env[name] ?? "") === "");
+}
+
+export type DevVars = {
+  /** What the app sees: every name from the files, plus declared names the process environment supplies when allowed. */
+  values: Record<string, string>;
+  /** Files that were read, in order of increasing precedence. */
+  used: string[];
+  /** Everything worth telling the developer: ignored files, skipped lines, missing declared secrets. No values. */
+  warnings: string[];
+};
+
+/** Local secrets for `sproutboat dev`, by the rules in the module comment. */
+export async function resolveDevVars(input: {
+  projectDir: string;
+  /** `--env <name>`: selects `.dev.vars.<name>` and the `.env.<name>` files. */
+  envName?: string;
+  /** `--env-file` paths, absolute, in the order given. */
+  envFiles?: string[];
+  declared: readonly string[];
+  inherited: Record<string, string | undefined>;
+}): Promise<DevVars> {
+  const warnings: string[] = [];
+  const at = (name: string) => resolve(input.projectDir, name);
+  const name = input.envName;
+  const explicit = input.envFiles ?? [];
+  const devVarsPath = [name ? at(`.dev.vars.${name}`) : undefined, at(".dev.vars")].find(
+    (path) => path !== undefined && existsSync(path),
+  );
+  const loadDotEnv = input.inherited.CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV !== "false";
+  const dotEnvCandidates =
+    explicit.length > 0
+      ? explicit
+      : [
+          at(".env"),
+          ...(name ? [at(`.env.${name}`)] : []),
+          at(".env.local"),
+          ...(name ? [at(`.env.${name}.local`)] : []),
+        ];
+
+  let layers: EnvEntry[][] = [];
+  const used: string[] = [];
+  if (devVarsPath !== undefined) {
+    const present = dotEnvCandidates.filter((path) => existsSync(path));
+    if (present.length > 0)
+      warnings.push(`${devVarsPath} exists, so the .env files are not loaded (ignored: ${present.join(", ")})`);
+    const parsed = await readEnvFile(devVarsPath);
+    warnings.push(...parsed.warnings);
+    layers = [parsed.entries];
+    used.push(devVarsPath);
+  } else if (!loadDotEnv) {
+    if (explicit.length > 0)
+      warnings.push("CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV=false, so the --env-file files are not loaded");
+  } else {
+    for (const path of dotEnvCandidates) {
+      // The default files are optional; a file named with --env-file is not.
+      if (explicit.length === 0 && !existsSync(path)) continue;
+      const parsed = await readEnvFile(path);
+      warnings.push(...parsed.warnings);
+      layers.push(parsed.entries);
+      used.push(path);
+    }
+  }
+
+  const values: Record<string, string> = {};
+  for (const entry of mergeEntries(layers)) values[entry.key] = entry.value;
+  // The process environment never reaches the app by default, and not when .dev.vars is in use.
+  if (devVarsPath === undefined && input.inherited.CLOUDFLARE_INCLUDE_PROCESS_ENV === "true") {
+    for (const declaredName of input.declared) {
+      const fromProcess = input.inherited[declaredName];
+      if (values[declaredName] === undefined && fromProcess !== undefined) values[declaredName] = fromProcess;
+    }
+  }
+  const missing = input.declared.filter((declaredName) => (values[declaredName] ?? "") === "");
+  if (missing.length > 0) {
+    warnings.push(
+      `declared secret${missing.length === 1 ? "" : "s"} with no value: ${missing.join(", ")}. A handler that reads ${missing.length === 1 ? "it" : "one"} will throw. Set ${missing.length === 1 ? "it" : "them"} in .dev.vars or a .env file.`,
+    );
+  }
+  return { values, used, warnings };
+}