sproutboat 0.53.0 → 0.53.1

package/CHANGELOG.md

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

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` |

package/SURFACE.md

@@ -3,13 +3,13 @@
 > 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.53.0
+**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] [--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. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.53.0",
+  "version": "0.53.1",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "keywords": [
     "cli",
@@ -78,10 +78,10 @@
     "typescript": "7.0.2"
   },
   "optionalDependencies": {
-    "@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"
+    "@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/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,
+  };
+}

package/src/main.ts

@@ -18,6 +18,7 @@ import { CLI_NAME, COMMANDS, helpText, STORAGE_PRODUCTS, STORAGE_VERBS, type Sto
 import { notifyIfOutdated } from "./update-check";
 import { controlVersionWarning } from "./api-version";
 import { amber, bold, dim, leaf, ok, rose } from "./style";
+import { detectPackageManager, installCommand, planPackageJson, runScriptCommand } from "./init-package";
 import { pathToFileURL } from "node:url";
 import { constants as osConstants } from "node:os";
 import { inspectToolchain } from "./toolchain";
@@ -265,6 +266,21 @@ async function init(name = "hello") {
   ] as const) {
     if (await Bun.file(path).exists()) fail(`${basename(directory)} already contains ${label}`);
   }
+  // Plan package.json before writing anything, so an unreadable one stops init
+  // instead of leaving a half-scaffolded project.
+  const packagePath = resolve(directory, "package.json");
+  let existingPackage: string | undefined;
+  try {
+    existingPackage = await readFile(packagePath, "utf8");
+  } catch {
+    existingPackage = undefined;
+  }
+  let packagePlan: ReturnType<typeof planPackageJson>;
+  try {
+    packagePlan = planPackageJson(name, existingPackage, CLI_VERSION);
+  } catch (cause) {
+    fail(`${basename(directory)}: ${cause instanceof Error ? cause.message : String(cause)}`);
+  }
   await mkdir(resolve(directory, "src"), { recursive: true });
   await writeFile(configPath, starterConfig(name), { flag: "wx" });
   await writeFile(handlerPath, starterHandler, { flag: "wx" });
@@ -278,6 +294,19 @@ async function init(name = "hello") {
     await writeFile(gitignorePath, starterGitignore, { flag: "wx" });
     console.log(`Created ${basename(directory)}/.gitignore`);
   }
+  if (packagePlan.created || packagePlan.addedDependency || packagePlan.addedScripts.length > 0) {
+    await writeFile(packagePath, packagePlan.text);
+    console.log(`${packagePlan.created ? "Created" : "Updated"} ${basename(directory)}/package.json`);
+  }
+  for (const script of packagePlan.skippedScripts)
+    console.log(
+      amber(
+        `  ! package.json already has a "${script}" script; left it as is (sproutboat's would be "sproutboat ${script}")`,
+      ),
+    );
+  const manager = detectPackageManager(directory);
+  console.log(`\nNext: cd ${basename(directory)} && ${installCommand(manager)} && ${runScriptCommand(manager, "dev")}`);
+  console.log(dim(`After "sproutboat login", ship it with ${runScriptCommand(manager, "deploy")}.`));
 }
 
 async function check(directory?: string) {

package/src/surface.ts

@@ -68,7 +68,8 @@ export const COMMANDS: readonly Command[] = [
     group: "Develop",
     emoji: "🌱",
     args: "[name]",
-    summary: "Scaffold sproutboat.jsonc + src/index.js in ./<name>.",
+    summary:
+      "Scaffold sproutboat.jsonc, src/index.js and package.json (sproutboat devDependency, dev and deploy scripts) in ./<name>.",
   },
   {
     name: "check",