sproutboat 0.52.1 → 0.53.1

package/CHANGELOG.md

@@ -10,6 +10,34 @@ maintained going forward by the `release` skill.
 
 ## Unreleased
 
+## [0.53.1] - 2026-11-09
+
+Built on `@sproutboat/runtime` 0.43.0, `@sproutboat/wire` 0.22.3 and `@sproutboat/toolchain` 0.24.2, unchanged from 0.53.0. No runtime or wire change, so there is no new compatibility date and no recompile.
+
+### Changed
+
+- **`init` adds `sproutboat` to the project's devDependencies and the `dev`, `deploy` and `check` scripts,** the way Cloudflare's templates do for Wrangler, so a project pins the CLI version that compiles it and `npm run deploy` works after `npm install`. The range is a caret on the running CLI's version. A missing `package.json` is created (`private`, version `0.0.0`); an existing one keeps its fields and indentation, a script with the same name is never overwritten (init prints a warning naming it), and a `sproutboat` already declared in any dependency section is left as is. An unreadable `package.json` stops init before any file is written. The next step it prints follows the project's package manager (a lockfile, then the launching tool, then npm), for example `cd hello && pnpm install && pnpm run dev` (`pnpm run`, because `pnpm deploy` is pnpm's own command).
+
+## [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

@@ -25,7 +25,7 @@ for agents: [sproutboat.com/llms.txt](https://sproutboat.com/llms.txt)).
 ## Using
 
 The npm package installs a small Node launcher and the matching native
-platform package, so `npm install -g sproutboat` and `npm exec sproutboat` work
+platform package, so `npm i -D sproutboat`, `npm i -g sproutboat` and `npx sproutboat` work
 without Bun on `darwin` and `linux` for `arm64` and `x64`. The self-hosted
 runtime exports remain in the root package for Bun-based platform integrations.
 Nothing is needed on the machine that *runs* a sprout: that gets a static
@@ -37,23 +37,35 @@ patches there, and publishes the cache entry atomically. Installation itself
 does not clone Porffor or invoke Git, Make, or a compiler. Warm-cache builds can
 run offline.
 
+Install it in each project, as you would Wrangler. The CLI is the compiler, so
+a project that pins its version builds the same way on every machine and in CI:
+
+```sh
+npm i -D sproutboat       # pnpm add -D sproutboat, bun add -d sproutboat, yarn add -D sproutboat
+```
+
+`sproutboat init` does this for you: it writes a `package.json` with
+`sproutboat` in `devDependencies` and `dev`, `deploy` and `check` scripts.
+
 ```sh
-npm exec sproutboat init hello
+npx sproutboat init hello  # or: pnpm dlx sproutboat init hello, bunx sproutboat init hello
 cd hello
-npm exec sproutboat dev    # runs it right here, no control plane needed
+npm install
+npm run dev                # runs it right here, no control plane needed
 ```
 
-Happy with it? Ship it:
+Happy with it? Log in once, then ship it:
 
 ```sh
-bunx sproutboat login --api-url https://control.example.com   # one browser approval
-bunx sproutboat deploy
+npx sproutboat login --api-url https://control.example.com   # one browser approval
+npm run deploy             # or: npx sproutboat deploy
 ```
 
-Or install it once and drop the `npm exec`:
+For quick commands outside a project, install it globally. A global install is
+not pinned to anything, so keep it for `init`, `login` and `whoami`:
 
 ```sh
-npm install -g sproutboat # then: sproutboat deploy, sproutboat tail, ...
+npm i -g sproutboat       # then: sproutboat init, sproutboat whoami, ...
 ```
 
 `login` is one-time. It writes a long-lived token to
@@ -67,7 +79,7 @@ The everyday loop:
 
 | Command | What it does |
 | --- | --- |
-| `init [name]` | Scaffold `sproutboat.jsonc` + `src/index.js` |
+| `init [name]` | Scaffold `sproutboat.jsonc`, `src/index.js` and a `package.json` that pins `sproutboat` |
 | `dev [--port <n>]` | Run it here against a real broker, rebuilding on save |
 | `deploy` | Build, provision bindings, upload, wait until the URL serves |
 | `tail [filters]` | Live request events, console output and exceptions, like `wrangler tail` |
@@ -197,8 +209,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,22 +3,23 @@
 > 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.1
 
 ## Commands
 
 | Command | Arguments | Summary |
 | --- | --- | --- |
-| `init` | `[name]` | Scaffold sproutboat.jsonc + src/index.js in ./<name>. |
+| `init` | `[name]` | Scaffold sproutboat.jsonc, src/index.js and package.json (sproutboat devDependency, dev and deploy scripts) 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.1",
   "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.1",
+    "@sproutboat/cli-darwin-x64": "0.53.1",
+    "@sproutboat/cli-linux-arm64": "0.53.1",
+    "@sproutboat/cli-linux-x64": "0.53.1"
   },
   "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/init-package.ts

@@ -0,0 +1,99 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { jsonObject, parseJsonValue, type JsonObject } from "./json";
+
+export type PackageManager = "npm" | "pnpm" | "yarn" | "bun";
+
+// Same conventions as Wrangler's create-cloudflare templates: a private
+// package at 0.0.0, `dev` and `deploy` scripts, and the CLI as a devDependency.
+export const INIT_SCRIPTS = {
+  dev: "sproutboat dev",
+  deploy: "sproutboat deploy",
+  check: "sproutboat check",
+} as const satisfies Record<string, string>;
+
+const LOCKFILES: ReadonlyArray<readonly [string, PackageManager]> = [
+  ["bun.lock", "bun"],
+  ["bun.lockb", "bun"],
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["package-lock.json", "npm"],
+];
+
+/** A lockfile in the project wins; otherwise the tool that launched the CLI; otherwise npm. */
+export function detectPackageManager(directory: string, userAgent = process.env.npm_config_user_agent): PackageManager {
+  for (const [file, manager] of LOCKFILES) if (existsSync(join(directory, file))) return manager;
+  const agent = /^(npm|pnpm|yarn|bun)\//.exec(userAgent ?? "")?.[1];
+  return agent === "pnpm" || agent === "yarn" || agent === "bun" ? agent : "npm";
+}
+
+export function installCommand(manager: PackageManager): string {
+  return `${manager} install`;
+}
+
+export function runScriptCommand(manager: PackageManager, script: string): string {
+  // Only yarn can drop `run` for every script. `pnpm deploy` is pnpm's own
+  // workspace command, so the script has to be `pnpm run deploy`.
+  return manager === "yarn" ? `yarn ${script}` : `${manager} run ${script}`;
+}
+
+export type PackagePlan = {
+  /** Serialized package.json to write. */
+  text: string;
+  created: boolean;
+  addedDependency: boolean;
+  addedScripts: string[];
+  /** Existing scripts left alone because the name was taken. */
+  skippedScripts: string[];
+};
+
+/** Throws on a package.json that is not a JSON object, before anything is written. */
+export function planPackageJson(name: string, existing: string | undefined, cliVersion: string): PackagePlan {
+  const range = `^${cliVersion}`;
+  let pkg: JsonObject;
+  let indent: string | number = 2;
+  let created = false;
+  if (existing === undefined) {
+    created = true;
+    pkg = { name, version: "0.0.0", private: true };
+  } else {
+    let parsed: JsonObject | undefined;
+    try {
+      parsed = jsonObject(parseJsonValue(existing));
+    } catch {
+      parsed = undefined;
+    }
+    if (!parsed) throw new Error("package.json is not a valid JSON object, so init did not touch it");
+    pkg = parsed;
+    indent = /^[ \t]+(?=")/m.exec(existing)?.[0] ?? 2;
+  }
+
+  const scripts: JsonObject = jsonObject(pkg.scripts) ?? {};
+  const addedScripts: string[] = [];
+  const skippedScripts: string[] = [];
+  for (const [script, command] of Object.entries(INIT_SCRIPTS)) {
+    if (!(script in scripts)) {
+      scripts[script] = command;
+      addedScripts.push(script);
+    } else if (scripts[script] !== command) skippedScripts.push(script);
+  }
+  if (addedScripts.length > 0) pkg.scripts = scripts;
+
+  const devDependencies: JsonObject = jsonObject(pkg.devDependencies) ?? {};
+  // Already declared anywhere: the project chose its own range.
+  const declared = [pkg.dependencies, pkg.devDependencies, pkg.peerDependencies, pkg.optionalDependencies].some(
+    (section) => jsonObject(section)?.sproutboat !== undefined,
+  );
+  const addedDependency = !declared;
+  if (addedDependency) {
+    devDependencies.sproutboat = range;
+    pkg.devDependencies = Object.fromEntries(Object.entries(devDependencies).sort(([a], [b]) => a.localeCompare(b)));
+  }
+  return {
+    text: `${JSON.stringify(pkg, null, indent)}\n`,
+    created,
+    addedDependency,
+    addedScripts,
+    skippedScripts,
+  };
+}