sproutboat 0.52.1 → 0.53.0

package/CHANGELOG.md

@@ -10,6 +10,26 @@ 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.

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.1
+**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.1",
+  "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/runtime": "^0.43.0",
     "@sproutboat/toolchain": "^0.24.2",
-    "@sproutboat/wire": "^0.22.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.1",
-    "@sproutboat/cli-darwin-x64": "0.52.1",
-    "@sproutboat/cli-linux-arm64": "0.52.1",
-    "@sproutboat/cli-linux-x64": "0.52.1"
+    "@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/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 };
+}

package/src/main.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { mkdir, open, readFile, rename, writeFile } from "node:fs/promises";
-import { rmSync } from "node:fs";
+import { existsSync, rmSync } from "node:fs";
 import { basename, dirname, relative, resolve } from "node:path";
 import { isBoolean, isSafeInteger, isString, jsonObject, parseJsonValue, type JsonObject } from "./json";
 import type { AssetFiles } from "./assets";
@@ -19,10 +19,14 @@ import { notifyIfOutdated } from "./update-check";
 import { controlVersionWarning } from "./api-version";
 import { amber, bold, dim, leaf, ok, rose } from "./style";
 import { pathToFileURL } from "node:url";
+import { constants as osConstants } from "node:os";
 import { inspectToolchain } from "./toolchain";
 import { isLinuxTarget, parseTarget, TARGET_NAMES, type BuildTarget } from "./targets";
 import { writeDeployFiles } from "./standalone-deploy";
-import { parseTailArgs, runTail, TAIL_USAGE, tailQuery } from "./tail";
+import { parseTailArgs, runTail, TAIL_USAGE, tailQuery, type TailArgs } from "./tail";
+import { followLog, LogFilter, readLogStream } from "./tail-log";
+import { EnvFileError, MissingSecretsError } from "./env-file";
+import { parseRunArgs, planRun, RUN_USAGE, RunError } from "./run";
 
 // A compiled Bun executable is not a general-purpose `bun` command. Porffor
 // is acquired after installation, so run its external ESM launcher through an
@@ -168,11 +172,11 @@ const starterConfig = (name: string) => `{
   "$schema": "https://sproutboat.com/schema.json",
   "name": "${name}",
   "main": "src/index.js",
-  "compatibility_date": "2026-08-26"
+  "compatibility_date": "2026-09-28"
 }
 `;
 const starterHandler = `export default {
-  fetch() {
+  fetch(request, env, ctx) {
     return new Response("hello from Sproutboat");
   }
 };
@@ -398,13 +402,30 @@ async function emitOnly(directory: string | undefined, target: BuildTarget, stan
 }
 
 /** #62 — build for this machine, run it against a real broker, rebuild on save. */
+const DEV_USAGE = "dev [project-dir] [--port <n>] [--no-watch] [--env <name>] [--env-file <file>]...";
+
 async function dev(args: string[]) {
-  const directory = args.find((arg) => !arg.startsWith("--") && !/^\d+$/.test(arg));
-  const portIndex = args.indexOf("--port");
-  const portArg = portIndex >= 0 ? args[portIndex + 1] : undefined;
+  let directory: string | undefined;
+  let portArg: string | undefined;
+  let envName: string | undefined;
+  const envFiles: string[] = [];
+  for (let at = 0; at < args.length; at += 1) {
+    const arg = args[at];
+    if (arg === "--no-watch") continue;
+    if (arg === "--port" || arg === "--env" || arg === "--env-file") {
+      const value = args[at + 1];
+      if (value === undefined || value.startsWith("--")) usageError(`${arg} needs a value`, DEV_USAGE);
+      at += 1;
+      if (arg === "--port") portArg = value;
+      else if (arg === "--env") envName = value;
+      else envFiles.push(resolve(value));
+    } else if (!arg.startsWith("--") && directory === undefined) directory = arg;
+  }
   const port = Number(portArg ?? 8787);
-  if (!Number.isSafeInteger(port) || port < 1 || port > 65_535)
-    usageError(`invalid --port: ${portArg}`, "dev [project-dir] [--port <n>] [--no-watch]");
+  if (!Number.isSafeInteger(port) || port < 1 || port > 65_535) usageError(`invalid --port: ${portArg}`, DEV_USAGE);
+  if (envName !== undefined && !/^[A-Za-z0-9_-]+$/.test(envName))
+    usageError("--env takes a name (letters, digits, - and _)", DEV_USAGE);
+  for (const file of envFiles) if (!existsSync(file)) fail(`env file not found: ${file}`);
   const project = await readProject(directory);
   await refreshTypes(project.directory, project.config);
   console.log(dim(`Building ${project.config.name} for this machine (${hostTarget()})…`));
@@ -414,6 +435,8 @@ async function dev(args: string[]) {
     sourcePath: project.sourcePath,
     source: project.bundle.code,
     port,
+    envFiles,
+    envName,
     watch: !args.includes("--no-watch"),
     // Re-read from disk on every rebuild: the point of watching is that the
     // files changed, so the bundle captured at startup is stale by definition.
@@ -425,6 +448,33 @@ async function dev(args: string[]) {
   });
 }
 
+/** #275: start a standalone binary with its port, data directory and secrets supplied at launch. */
+async function run(args: string[]) {
+  const result = parseRunArgs(args);
+  if ("error" in result) usageError(result.error, RUN_USAGE);
+  let plan;
+  try {
+    plan = await planRun(result.args, { cwd: process.cwd(), inherited: process.env });
+  } catch (error) {
+    if (error instanceof RunError || error instanceof EnvFileError || error instanceof MissingSecretsError)
+      fail(error.message);
+    throw error;
+  }
+  for (const warning of plan.warnings) console.warn(amber(`! ${warning}`));
+  for (const line of plan.summary) console.log(dim(line));
+  if (result.args.check) {
+    console.log(ok(`ready to launch ${basename(plan.binary)} (not started: --check)`));
+    return;
+  }
+  console.log(ok(`launching ${plan.binary}`));
+  const child = Bun.spawn([plan.binary], { env: plan.env, stdin: "inherit", stdout: "inherit", stderr: "inherit" });
+  // Forward termination to the binary, which is the only process this started.
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) process.on(signal, () => child.kill(signal));
+  const code = await child.exited;
+  const signalNumber = child.signalCode ? osConstants.signals[child.signalCode] : undefined;
+  process.exit(signalNumber === undefined ? code : 128 + signalNumber);
+}
+
 const PROVISION_FIELDS = [
   ["kv_namespaces", "kv"],
   ["d1_databases", "d1"],
@@ -792,10 +842,32 @@ async function rollback(args: string[]) {
   console.log(deployment.url);
 }
 
+/** #268: follow a standalone binary's SB_LOG=json records from a file or stdin. Local only: no login. */
+async function tailLog(parsed: TailArgs, file: string) {
+  // Ctrl-C (or a terminated pipe reader) ends the stream and exits 0.
+  const controller = new AbortController();
+  for (const signal of ["SIGINT", "SIGTERM"] as const) process.once(signal, () => controller.abort());
+  process.stdout.on("error", () => controller.abort());
+  const sink = {
+    format: parsed.format,
+    filter: new LogFilter({ status: parsed.status, method: parsed.method, search: parsed.search }),
+    signal: controller.signal,
+    stdout: (text: string) => void process.stdout.write(text),
+    stderr: (text: string) => void process.stderr.write(text),
+  };
+  try {
+    if (file === "-") await readLogStream(Bun.stdin.stream(), sink);
+    else await followLog({ ...sink, path: resolve(file), lines: parsed.lines, follow: parsed.follow });
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+}
+
 async function tail(args: string[]) {
   const result = parseTailArgs(args);
   if ("error" in result) usageError(result.error, TAIL_USAGE);
   const parsed = result.args;
+  if (parsed.file !== undefined) return tailLog(parsed, parsed.file);
   const [project, { apiUrl, token }] = await Promise.all([readProjectConfig(parsed.dir), apiCredentials()]);
   const base = `${apiUrl}/api/projects/${project.config.name}`;
   if (parsed.recent || parsed.sprout) {
@@ -1359,7 +1431,9 @@ if (command === "--version" || command === "-v") {
 }
 if (args.includes("-h") || args.includes("--help")) commandHelp(command);
 
-await notifyIfOutdated(CLI_VERSION);
+// A local log needs no network: skip the version check for it (#268).
+if (!(command === "tail" && args.some((arg) => arg === "--file" || arg.startsWith("--file="))))
+  await notifyIfOutdated(CLI_VERSION);
 
 switch (command) {
   case "init":
@@ -1374,6 +1448,9 @@ switch (command) {
   case "dev":
     await dev(args);
     break;
+  case "run":
+    await run(args);
+    break;
   case "build": {
     const withRestore = args.includes("--with-restore");
     if (withRestore && (!args.includes("--standalone") || args.includes("--emit-only")))