sproutboat 0.52.0 → 0.53.0

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")))

package/src/run.ts

@@ -0,0 +1,168 @@
+/**
+ * `sproutboat run`: launch a standalone binary with the settings it takes at
+ * launch (#275), without baking any of them into it.
+ *
+ * A standalone binary reads its port, data directory and secrets from the
+ * environment and nothing from argv. This command builds that environment from
+ * three layers and starts the binary with it. Highest precedence first:
+ *
+ * 1. explicit launch options: `--port` (PORT) and `--data-dir` (SB_DATA_DIR);
+ * 2. the files given with `--env-file` (dotenv syntax, see env-file.ts; repeat
+ *    the flag and a later file overrides an earlier one);
+ * 3. the environment this command inherited, which is how a service manager
+ *    hands a production binary its settings.
+ *
+ * Unlike `dev`, which warns, a launch fails when a declared secret (the
+ * config's `secrets` plus any `--require`) is unset or empty, as
+ * `wrangler deploy` does for a missing required secret. Nothing starts. The same binary therefore moves between a
+ * laptop and a server with a different env file, port and data directory.
+ * Nothing is written to disk and no value is ever printed: the summary names
+ * secrets and the layer each came from.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parseConfig } from "./config";
+import {
+  mergeEntries,
+  MissingSecretsError,
+  missingSecrets,
+  readEnvFile,
+  resolveEnvironment,
+  type EnvEntry,
+  type EnvSource,
+} from "./env-file";
+
+export const RUN_USAGE =
+  "run [project-dir] [--binary <file>] [--env-file <file>]... [--port <n>] [--data-dir <dir>] [--require <NAME,...>] [--check]";
+
+const VALUE_FLAGS = ["--binary", "--env-file", "--port", "--data-dir", "--require"] as const;
+const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export type RunArgs = {
+  dir: string | undefined;
+  binary: string | undefined;
+  /** Every `--env-file`, in the order given. */
+  envFiles: string[];
+  port: number | undefined;
+  dataDir: string | undefined;
+  require: string[];
+  check: boolean;
+};
+
+/** Parse `run` arguments; `error` is a usage error message. */
+export function parseRunArgs(args: string[]): { args: RunArgs } | { error: string } {
+  const parsed: RunArgs = {
+    dir: undefined,
+    binary: undefined,
+    envFiles: [],
+    port: undefined,
+    dataDir: undefined,
+    require: [],
+    check: false,
+  };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--check") parsed.check = true;
+    else if (arg.startsWith("--")) {
+      const eq = arg.indexOf("=");
+      const flag = eq < 0 ? arg : arg.slice(0, eq);
+      if (!VALUE_FLAGS.some((known) => known === flag)) return { error: `run: unknown flag "${flag}"` };
+      const value = eq < 0 ? args[++index] : arg.slice(eq + 1);
+      if (value === undefined || (eq < 0 && value.startsWith("--"))) return { error: `run: ${flag} needs a value` };
+      if (flag === "--binary") parsed.binary = value;
+      else if (flag === "--env-file") parsed.envFiles.push(value);
+      else if (flag === "--data-dir") parsed.dataDir = value;
+      else if (flag === "--port") {
+        const port = Number(value);
+        if (!Number.isInteger(port) || port < 1 || port > 65_535)
+          return { error: `run: --port must be a whole number from 1 to 65535 (got "${value}")` };
+        parsed.port = port;
+      } else {
+        for (const name of value.split(",").map((part) => part.trim())) {
+          if (name === "") continue;
+          if (!NAME.test(name)) return { error: `run: --require takes variable names (letters, digits, underscore)` };
+          parsed.require.push(name);
+        }
+      }
+    } else if (parsed.dir === undefined) parsed.dir = arg;
+    else return { error: `run: unexpected argument "${arg}"` };
+  }
+  return { args: parsed };
+}
+
+/** A launch that cannot proceed for a reason the user can fix; the message is safe to print. */
+export class RunError extends Error {}
+
+export type RunPlan = {
+  binary: string;
+  /** The complete environment the binary starts with. Contains secret values: never print it. */
+  env: Record<string, string>;
+  declared: string[];
+  /** Lines naming what was resolved and from where. No values of secrets. */
+  summary: string[];
+  /** Env-file lines that were skipped, as `file:line: reason`. Never a value. */
+  warnings: string[];
+};
+
+/** Resolve what to launch and with which environment, or throw. Starts nothing. */
+export async function planRun(
+  args: RunArgs,
+  io: { cwd: string; inherited: Record<string, string | undefined> },
+): Promise<RunPlan> {
+  const directory = resolve(io.cwd, args.dir ?? ".");
+  const configPath = resolve(directory, "sproutboat.jsonc");
+  let name: string | undefined;
+  const declared: string[] = [];
+  if (existsSync(configPath)) {
+    const parsed = parseConfig(await readFile(configPath, "utf8"));
+    if (!parsed.ok) throw new RunError(parsed.errors.join("\n"));
+    name = parsed.value.name;
+    declared.push(...(parsed.value.secrets ?? []));
+  } else if (args.binary === undefined) {
+    throw new RunError(
+      `no sproutboat.jsonc found in ${directory}; pass --binary <file> to run a binary without a project`,
+    );
+  }
+  for (const required of args.require) if (!declared.includes(required)) declared.push(required);
+
+  const binary = args.binary !== undefined ? resolve(io.cwd, args.binary) : resolve(directory, "dist", name ?? "");
+  if (!existsSync(binary)) {
+    throw new RunError(
+      `no binary at ${binary}; build it first with: sproutboat build --standalone${args.dir ? ` ${args.dir}` : ""}`,
+    );
+  }
+
+  const layers: EnvEntry[][] = [];
+  const warnings: string[] = [];
+  for (const path of args.envFiles) {
+    const parsed = await readEnvFile(resolve(io.cwd, path));
+    layers.push(parsed.entries);
+    warnings.push(...parsed.warnings);
+  }
+  const file = mergeEntries(layers);
+  const options: Record<string, string> = {};
+  if (args.port !== undefined) options.PORT = String(args.port);
+  if (args.dataDir !== undefined) options.SB_DATA_DIR = resolve(io.cwd, args.dataDir);
+  const { env, sources } = resolveEnvironment({ inherited: io.inherited, file, options });
+
+  const missing = missingSecrets(declared, env);
+  if (missing.length > 0) {
+    throw new MissingSecretsError(
+      missing,
+      args.envFiles.length > 0 ? args.envFiles.join(" or ") : "an env file (--env-file)",
+    );
+  }
+
+  const origin = (key: string): EnvSource | undefined => sources.get(key);
+  const summary: string[] = [];
+  summary.push(
+    declared.length === 0
+      ? "secrets   none declared"
+      : `secrets   ${declared.map((secret) => `${secret} (${origin(secret) ?? "unset"})`).join(", ")}`,
+  );
+  if (env.PORT) summary.push(`port      ${env.PORT} (${origin("PORT")})`);
+  const dataKey = env.SB_DATA_DIR ? "SB_DATA_DIR" : env.SPROUTBOAT_DATA ? "SPROUTBOAT_DATA" : undefined;
+  if (dataKey) summary.push(`data      ${env[dataKey]} (${origin(dataKey)})`);
+  return { binary, env, declared, summary, warnings };
+}

package/src/surface.ts

@@ -89,9 +89,19 @@ export const COMMANDS: readonly Command[] = [
     name: "dev",
     group: "Develop",
     emoji: "⚡",
-    args: "[project-dir] [--port <n>] [--no-watch]",
+    args: "[project-dir] [--port <n>] [--no-watch] [--env <name>] [--env-file <file>]...",
     brief: "[project-dir] [--port <n>]",
-    summary: "Run the project on this machine against a real broker, rebuilding on save.",
+    summary:
+      "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.",
+  },
+  {
+    name: "run",
+    group: "Develop",
+    emoji: "🚀",
+    args: "[project-dir] [--binary <file>] [--env-file <file>]... [--port <n>] [--data-dir <dir>] [--require <NAME,...>] [--check]",
+    brief: "[--env-file <file>] [--port <n>]",
+    summary:
+      "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.",
   },
   {
     name: "build",
@@ -141,10 +151,10 @@ export const COMMANDS: readonly Command[] = [
     name: "tail",
     group: "Ship",
     emoji: "📡",
-    args: "[project-dir] [--format pretty|json] [--status ok|error|<code>|5xx] [--method GET,POST] [--sampling-rate <0..1>] [--search <text>] [--outcome <name>] [--recent] [--sprout]",
+    args: "[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]]",
     brief: "[--status 5xx] [--search <text>]",
     summary:
-      "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.",
+      "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).",
   },
 
   ...storageCommands,