sproutboat 0.4.2 → 0.4.4

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.4.2 · runs on Bun (use `bunx`, not `npx`)
+**Package:** `sproutboat` 0.4.4 · runs on Bun (use `bunx`, not `npx`)
 
 ## Commands
 
@@ -13,16 +13,16 @@
 | `check` | `[project-dir]` | Validate the config and entry point without building. |
 | `build` | `[project-dir]` | Cross-compile the native-fetch sprout (Porffor + Zig). |
 | `deploy` | `[project-dir] [--dry-run] [--artifact <dir>] [--no-wait]` | Build (unless --artifact), print the report, upload, wait until the URL serves. --dry-run stops before upload; --no-wait skips the health check. |
-| `login` | `[--api-url <url>] [--token <token>]` | Device-code browser flow, or store <token> for <url> directly. |
-| `tail` | `[project-dir] [--sprout]` | Print recent request logs; --sprout prints the running sprout + broker stdout/stderr instead. |
 | `versions` | `list [project-dir]` | List the project's deployed versions. |
 | `rollback` | `<version-id> [project-dir]` | Re-activate a previous version. |
+| `tail` | `[project-dir] [--sprout]` | Print recent request logs; --sprout prints the running sprout + broker stdout/stderr instead. |
 | `domains` | `[list | add <host> | verify <host> | rm <host>] [project-dir]` | Attach a custom domain to the project (TXT-verified). No sub-command lists. |
 | `secrets` | `[list | set <NAME> [value] | rm <NAME>] [project-dir]` | Manage encrypted project secrets (read as env.NAME). `set` takes the value from the arg or stdin; applies on next deploy. |
 | `delete` | `[project-dir] [--name <project>] --yes` | Delete the project, every version, and its route. |
+| `login` | `[--api-url <url>] [--token <token>]` | Device-code browser flow, or store <token> for <url> directly. |
 
 ```
-usage: sproutboat <init [name] | check [project-dir] | build [project-dir] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] | login [--api-url <url>] [--token <token>] | tail [project-dir] [--sprout] | versions list [project-dir] | rollback <version-id> [project-dir] | domains [list | add <host> | verify <host> | rm <host>] [project-dir] | secrets [list | set <NAME> [value] | rm <NAME>] [project-dir] | delete [project-dir] [--name <project>] --yes>
+usage: sproutboat <init [name] | check [project-dir] | build [project-dir] | deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait] | versions list [project-dir] | rollback <version-id> [project-dir] | tail [project-dir] [--sprout] | domains [list | add <host> | verify <host> | rm <host>] [project-dir] | secrets [list | set <NAME> [value] | rm <NAME>] [project-dir] | delete [project-dir] [--name <project>] --yes | login [--api-url <url>] [--token <token>]>
 ```
 
 ## Environment variables
@@ -38,6 +38,7 @@ usage: sproutboat <init [name] | check [project-dir] | build [project-dir] | dep
 | `SPROUTBOAT_BINDINGS_JSON` | The artifact's bindings.json, read by the wrapper to emit the `__sbInstallBindings` line. |
 | `SPROUTBOAT_CONFIG_DIR` | Directory for credentials.json (default ~/.config/sproutboat). |
 | `NO_COLOR` | When set, disables coloured terminal output (https://no-color.org). Output is also plain whenever stdout is not a TTY. |
+| `SPROUTBOAT_NO_UPDATE_CHECK` | When set, skips the once-a-day npm check for a newer `sproutboat` release (also skipped when CI is set). |
 | `XDG_CONFIG_HOME` | Base for the default credentials dir when SPROUTBOAT_CONFIG_DIR is unset. |
 | `PORFFOR_VERSION` | Override the Porffor identity string recorded in the manifest. |
 | `SB_BROKER_PORT` | Loopback port of the binding broker, read by the compiled sprout at runtime (set by the control plane, or by `src/broker.ts` for local runs). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sproutboat",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "license": "MIT",
   "type": "module",

package/src/credentials.ts

@@ -28,7 +28,7 @@ function parseCredentials(value: JsonValue): Credentials | undefined {
   return { version: 1, activeApiUrl: isString(input.activeApiUrl) ? input.activeApiUrl : undefined, profiles };
 }
 
-function configDirectory(): string {
+export function configDirectory(): string {
   const configured = process.env.SPROUTBOAT_CONFIG_DIR || process.env.XDG_CONFIG_HOME;
   if (configured && isAbsolute(configured)) return resolve(configured, "sproutboat");
   return resolve(homedir(), ".config", "sproutboat");

package/src/main.ts

@@ -5,9 +5,10 @@ import { parseConfig, type SproutboatConfig } from "./config";
 import { validateHttpSyncSource } from "./source";
 import { buildArtifact } from "./build";
 import { validateManifest, type ArtifactManifest } from "./manifest";
-import { printDeployReport } from "./report";
+import { CLI_VERSION, printDeployReport } from "./report";
 import { activeApiUrl, savedToken, saveToken } from "./credentials";
-import { usageLine } from "./surface";
+import { helpText } from "./surface";
+import { notifyIfOutdated } from "./update-check";
 import { amber, bold, dim, leaf, ok, rose } from "./style";
 
 const defaultApiUrl = "https://dashboard.sproutboat.com";
@@ -66,9 +67,14 @@ function parseVersionList(source: string): VersionSummary[] | undefined {
   return deployments;
 }
 
-function parseUrlResponse(source: string): { url: string } | undefined {
+function parseUrlResponse(source: string): { url: string; id?: string; artifact?: string } | undefined {
   const record = jsonObject(parseJsonValue(source));
-  return record && isString(record.url) ? { url: record.url } : undefined;
+  if (!record || !isString(record.url)) return undefined;
+  return {
+    url: record.url,
+    id: isString(record.id) ? record.id : undefined,
+    artifact: isString(record.artifact) ? record.artifact : undefined,
+  };
 }
 
 /** #55: `{ from, to }` when this deploy moves the live version onto a different
@@ -106,11 +112,22 @@ const starterHandler = `export default {
 };
 `;
 
+/** An operational failure — the command was invoked correctly but could not complete. Exit 1. */
 function fail(message: string): never {
   console.error(`${rose("✗")} ${message}`);
   process.exit(1);
 }
 
+/**
+ * The command was invoked wrong (missing/unknown arg). Exit 2, the getopt/argparse
+ * convention, so scripts can tell "you typed it wrong" apart from "it broke".
+ * `usage` is the grammar line without the `usage: ` prefix.
+ */
+function usageError(what: string, usage: string): never {
+  console.error(`${rose("✗")} ${what}\n  ${dim(`usage: sproutboat ${usage}`)}`);
+  process.exit(2);
+}
+
 async function readProject(directory = process.cwd()) {
   const projectDirectory = resolve(directory);
   const configPath = resolve(projectDirectory, "sproutboat.jsonc");
@@ -168,7 +185,9 @@ async function deploy(args: string[]) {
   let artifactDir: string;
   let config: SproutboatConfig | undefined;
   if (artifactIndex >= 0) {
-    artifactDir = args[artifactIndex + 1] ? resolve(args[artifactIndex + 1]) : fail("--artifact requires a directory");
+    artifactDir = args[artifactIndex + 1]
+      ? resolve(args[artifactIndex + 1])
+      : usageError("deploy: --artifact needs a directory", "deploy [project-dir] [--dry-run] [--artifact <dir>] [--no-wait]");
     projectName = "";
   } else {
     const built = await build(directory);
@@ -239,6 +258,8 @@ async function deploy(args: string[]) {
   if (!deployed) fail("deployment response did not include a URL");
   console.log(`\n${leaf("🌱")} ${bold(leaf(`Deployed ${projectName}`))}`);
   console.log(`  ${bold(deployed.url)}`);
+  if (deployed.id) console.log(dim(`  version ${deployed.id}${deployed.artifact ? `  ·  artifact ${deployed.artifact.slice(0, 12)}` : ""}`));
+  for (const cron of config?.triggers?.crons ?? []) console.log(dim(`  schedule ${cron}`));
   const drift = parsePorfforDrift(body);
   if (drift) {
     console.warn(amber(`\n! Porffor pin changed: ${drift.from} -> ${drift.to}`));
@@ -280,7 +301,7 @@ function parseLoginArgs(args: string[]) {
     const value = args[index + 1];
     if (args[index] === "--api-url" && value) apiUrl = value;
     else if (args[index] === "--token" && value) token = value;
-    else fail("usage: sproutboat login [--api-url <url>] [--token <token>]");
+    else usageError(`login: unexpected argument "${args[index]}"`, "login [--api-url <url>] [--token <token>]");
   }
   return { apiUrl: apiUrl.replace(/\/$/, ""), token };
 }
@@ -331,7 +352,7 @@ async function apiCredentials() {
 }
 
 async function versions(args: string[]) {
-  if (args[0] !== "list") fail("usage: sproutboat versions list [project-directory]");
+  if (args[0] !== "list") usageError(args[0] ? `versions: unknown subcommand "${args[0]}"` : "versions: missing subcommand", "versions list [project-dir]");
   const [project, { apiUrl, token }] = await Promise.all([readProject(args[1]), apiCredentials()]);
   const response = await fetch(`${apiUrl}/api/projects/${project.config.name}/deployments`, { headers: { "x-api-key": token } });
   const deployments = parseVersionList(await responseText(response, "could not list versions"));
@@ -341,7 +362,7 @@ async function versions(args: string[]) {
 
 async function rollback(args: string[]) {
   const id = args[0];
-  if (!id) fail("usage: sproutboat rollback <version-id> [project-directory]");
+  if (!id) usageError("rollback: missing <version-id>", "rollback <version-id> [project-dir]");
   const [project, { apiUrl, token }] = await Promise.all([readProject(args[1]), apiCredentials()]);
   const response = await fetch(`${apiUrl}/api/projects/${project.config.name}/deployments/${id}/activate`, { method: "POST", headers: { "x-api-key": token } });
   const deployment = parseUrlResponse(await responseText(response, "rollback rejected"));
@@ -379,7 +400,7 @@ function printDomain(domain: DomainView) {
 async function domains(args: string[]) {
   const sub = args[0] && !args[0].startsWith("-") && ["list", "add", "verify", "rm"].includes(args[0]) ? args.shift()! : "list";
   const host = sub === "list" ? undefined : args.shift();
-  if (sub !== "list" && !host) fail(`usage: sproutboat domains ${sub} <hostname> [project-dir]`);
+  if (sub !== "list" && !host) usageError(`domains ${sub}: missing <hostname>`, `domains ${sub} <hostname> [project-dir]`);
   const [project, { apiUrl, token }] = await Promise.all([readProject(args[0]), apiCredentials()]);
   const base = `${apiUrl}/api/projects/${project.config.name}/domains`;
   const auth = { "x-api-key": token };
@@ -412,7 +433,7 @@ async function domains(args: string[]) {
 async function secrets(args: string[]) {
   const sub = args[0] && ["list", "set", "rm"].includes(args[0]) ? args.shift()! : "list";
   const name = sub === "list" ? undefined : args.shift();
-  if (sub !== "list" && !name) fail(`usage: sproutboat secrets ${sub} <NAME> [project-dir]`);
+  if (sub !== "list" && !name) usageError(`secrets ${sub}: missing <NAME>`, `secrets ${sub} <NAME> [project-dir]`);
   if (name && !/^[A-Z][A-Z0-9_]*$/.test(name)) fail("secret name must be UPPER_SNAKE_CASE");
   const [project, { apiUrl, token }] = await Promise.all([readProject(args[0]), apiCredentials()]);
   const base = `${apiUrl}/api/projects/${project.config.name}/secrets`;
@@ -452,7 +473,7 @@ async function deleteProject(args: string[]) {
     if (arg === "--yes" || arg === "-y") confirmed = true;
     else if (arg === "--name") explicitName = args[(index += 1)];
     else if (!arg.startsWith("-")) positional.push(arg);
-    else fail(`unknown flag ${arg}\nusage: sproutboat delete [project-dir] [--name <project>] --yes`);
+    else usageError(`delete: unknown flag "${arg}"`, "delete [project-dir] [--name <project>] --yes");
   }
 
   const { apiUrl, token } = await apiCredentials();
@@ -473,12 +494,24 @@ async function deleteProject(args: string[]) {
   if (failed.length) console.log(`  ! ${failed.length} artifact file(s) left on disk — remove them manually`);
 }
 
+/** `sproutboat` alone or with -h/--help/help: the friendly grouped list, exit 0. */
+function help(): never {
+  console.log(helpText());
+  process.exit(0);
+}
+
+/** An unrecognised command: a short pointer on stderr, exit 2 (misuse, not failure). */
 function usage(): never {
-  console.error(usageLine());
-  process.exit(1);
+  console.error(`${rose("✗")} unknown command "${command}"\n  ${dim("run `sproutboat` for the list of commands")}`);
+  process.exit(2);
 }
 
 const [command, ...args] = process.argv.slice(2);
+if (command === undefined || command === "help" || command === "-h" || command === "--help") help();
+if (command === "--version" || command === "-v") { console.log(`sproutboat ${CLI_VERSION}`); process.exit(0); }
+
+await notifyIfOutdated(CLI_VERSION);
+
 switch (command) {
   case "init": await init(args[0]); break;
   case "check": await check(args[0]); break;

package/src/report.ts

@@ -5,7 +5,7 @@ import type { ArtifactManifest } from "./manifest";
 import { bold, dim, leaf, sprout } from "./style";
 
 // Read from package.json so the banner never drifts from the published version.
-const CLI_VERSION = (JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string }).version;
+export const CLI_VERSION = (JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string }).version;
 
 function bytes(n: number): string {
   if (n < 1024) return `${n} B`;

package/src/surface.ts

@@ -1,24 +1,57 @@
 /**
- * The CLI's public surface, as data. `main.ts` builds its usage string from
- * this, and `surface.test.ts` renders it to `SURFACE.md` and checks that the
- * command switch, the referenced env vars, and the doc can't drift apart.
+ * The CLI's public surface, as data. `main.ts` builds its help + usage strings
+ * from this, and `surface.test.ts` renders it to `SURFACE.md` and checks that
+ * the command switch, the referenced env vars, and the doc can't drift apart.
  */
+import { bold, dim, leaf } from "./style";
+
 export const CLI_NAME = "sproutboat";
+export const TAGLINE = "Deploy JavaScript handlers as tiny native binaries on your own VPS.";
+export const REPO_URL = "https://github.com/baronunread/sproutboat";
+
+export type Group = "Develop" | "Ship" | "Configure" | "Account";
 
-export type Command = { name: string; args: string; summary: string };
+export type Command = {
+  name: string;
+  /** Full argument grammar — used by SURFACE.md and the one-line usage string. */
+  args: string;
+  /** Short argument hint shown in the grouped help list (falls back to `args`). */
+  brief?: string;
+  group: Group;
+  emoji: string;
+  summary: string;
+};
 
 export const COMMANDS: readonly Command[] = [
-  { name: "init", args: "[name]", summary: "Scaffold sproutboat.jsonc + src/index.js in ./<name>." },
-  { name: "check", args: "[project-dir]", summary: "Validate the config and entry point without building." },
-  { name: "build", args: "[project-dir]", summary: "Cross-compile the native-fetch sprout (Porffor + Zig)." },
-  { name: "deploy", args: "[project-dir] [--dry-run] [--artifact <dir>] [--no-wait]", summary: "Build (unless --artifact), print the report, upload, wait until the URL serves. --dry-run stops before upload; --no-wait skips the health check." },
-  { name: "login", args: "[--api-url <url>] [--token <token>]", summary: "Device-code browser flow, or store <token> for <url> directly." },
-  { name: "tail", args: "[project-dir] [--sprout]", summary: "Print recent request logs; --sprout prints the running sprout + broker stdout/stderr instead." },
-  { name: "versions", args: "list [project-dir]", summary: "List the project's deployed versions." },
-  { name: "rollback", args: "<version-id> [project-dir]", summary: "Re-activate a previous version." },
-  { name: "domains", args: "[list | add <host> | verify <host> | rm <host>] [project-dir]", summary: "Attach a custom domain to the project (TXT-verified). No sub-command lists." },
-  { name: "secrets", args: "[list | set <NAME> [value] | rm <NAME>] [project-dir]", summary: "Manage encrypted project secrets (read as env.NAME). `set` takes the value from the arg or stdin; applies on next deploy." },
-  { name: "delete", args: "[project-dir] [--name <project>] --yes", summary: "Delete the project, every version, and its route." },
+  { name: "init", group: "Develop", emoji: "🌱", args: "[name]",
+    summary: "Scaffold sproutboat.jsonc + src/index.js in ./<name>." },
+  { name: "check", group: "Develop", emoji: "🔍", args: "[project-dir]",
+    summary: "Validate the config and entry point without building." },
+  { name: "build", group: "Develop", emoji: "🔨", args: "[project-dir]",
+    summary: "Cross-compile the native-fetch sprout (Porffor + Zig)." },
+
+  { name: "deploy", group: "Ship", emoji: "🚀",
+    args: "[project-dir] [--dry-run] [--artifact <dir>] [--no-wait]", brief: "[project-dir] [--dry-run]",
+    summary: "Build (unless --artifact), print the report, upload, wait until the URL serves. --dry-run stops before upload; --no-wait skips the health check." },
+  { name: "versions", group: "Ship", emoji: "📜", args: "list [project-dir]",
+    summary: "List the project's deployed versions." },
+  { name: "rollback", group: "Ship", emoji: "⏮", args: "<version-id> [project-dir]", brief: "<version-id>",
+    summary: "Re-activate a previous version." },
+  { name: "tail", group: "Ship", emoji: "📡", args: "[project-dir] [--sprout]",
+    summary: "Print recent request logs; --sprout prints the running sprout + broker stdout/stderr instead." },
+
+  { name: "domains", group: "Configure", emoji: "🌐",
+    args: "[list | add <host> | verify <host> | rm <host>] [project-dir]", brief: "[list | add | verify | rm]",
+    summary: "Attach a custom domain to the project (TXT-verified). No sub-command lists." },
+  { name: "secrets", group: "Configure", emoji: "🔑",
+    args: "[list | set <NAME> [value] | rm <NAME>] [project-dir]", brief: "[list | set | rm]",
+    summary: "Manage encrypted project secrets (read as env.NAME). `set` takes the value from the arg or stdin; applies on next deploy." },
+  { name: "delete", group: "Configure", emoji: "🗑",
+    args: "[project-dir] [--name <project>] --yes", brief: "[project-dir] --yes",
+    summary: "Delete the project, every version, and its route." },
+
+  { name: "login", group: "Account", emoji: "🔓", args: "[--api-url <url>] [--token <token>]", brief: "[--token <token>]",
+    summary: "Device-code browser flow, or store <token> for <url> directly." },
 ];
 
 export type EnvVar = { name: string; purpose: string };
@@ -33,6 +66,7 @@ export const ENV_VARS: readonly EnvVar[] = [
   { name: "SPROUTBOAT_BINDINGS_JSON", purpose: "The artifact's bindings.json, read by the wrapper to emit the `__sbInstallBindings` line." },
   { name: "SPROUTBOAT_CONFIG_DIR", purpose: "Directory for credentials.json (default ~/.config/sproutboat)." },
   { name: "NO_COLOR", purpose: "When set, disables coloured terminal output (https://no-color.org). Output is also plain whenever stdout is not a TTY." },
+  { name: "SPROUTBOAT_NO_UPDATE_CHECK", purpose: "When set, skips the once-a-day npm check for a newer `sproutboat` release (also skipped when CI is set)." },
   { name: "XDG_CONFIG_HOME", purpose: "Base for the default credentials dir when SPROUTBOAT_CONFIG_DIR is unset." },
   { name: "PORFFOR_VERSION", purpose: "Override the Porffor identity string recorded in the manifest." },
   { name: "SB_BROKER_PORT", purpose: "Loopback port of the binding broker, read by the compiled sprout at runtime (set by the control plane, or by `src/broker.ts` for local runs)." },
@@ -40,8 +74,38 @@ export const ENV_VARS: readonly EnvVar[] = [
   { name: "SB_SPROUT_URL", purpose: "http://127.0.0.1:<PORT> of the sprout; when set, `src/broker.ts` runs the cron scheduler and queue consumer and delivers triggers to it." },
 ];
 
-/** One-line usage string, e.g. for `usage()` and `--help`. */
+const GROUP_ORDER: readonly Group[] = ["Develop", "Ship", "Configure", "Account"];
+
+/** One-line usage string, e.g. for `usage()` and SURFACE.md. */
 export function usageLine(): string {
   const parts = COMMANDS.map((c) => (c.args ? `${c.name} ${c.args}` : c.name));
   return `usage: ${CLI_NAME} <${parts.join(" | ")}>`;
 }
+
+/** First sentence of a summary — enough for the at-a-glance command list. */
+function firstSentence(text: string): string {
+  const end = text.indexOf(". ");
+  return end === -1 ? text.replace(/\.$/, "") : text.slice(0, end);
+}
+
+/** Wrangler-style grouped help: `sproutboat` with no command, or `--help`. */
+export function helpText(): string {
+  const invocations = COMMANDS.map((c) => `${c.name} ${c.brief ?? c.args}`.trim());
+  const width = Math.max(...invocations.map((s) => s.length));
+  const lines: string[] = [`${bold(CLI_NAME)} — ${TAGLINE}`, "", leaf("USAGE"), `  ${CLI_NAME} <command> [options]`];
+
+  for (const group of GROUP_ORDER) {
+    lines.push("", leaf(group.toUpperCase()));
+    for (const command of COMMANDS.filter((c) => c.group === group)) {
+      const invocation = `${command.name} ${command.brief ?? command.args}`.trim();
+      lines.push(`  ${invocation.padEnd(width)}  ${command.emoji}  ${firstSentence(command.summary)}`);
+    }
+  }
+
+  lines.push(
+    "",
+    dim(`Run \`${CLI_NAME} <command>\` with no/invalid args to see that command's full usage.`),
+    dim(`Docs: ${REPO_URL}  ·  runs on Bun — use \`bunx\`, not \`npx\`.`),
+  );
+  return lines.join("\n");
+}

package/src/update-check.ts

@@ -0,0 +1,55 @@
+/**
+ * "update available 0.4.4" notice, wrangler-style. Checks npm at most once a
+ * day, caches the answer next to the credentials, and never fails or blocks the
+ * command for more than a second. Silent when up to date, offline, in CI, or
+ * when SPROUTBOAT_NO_UPDATE_CHECK is set.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { configDirectory } from "./credentials";
+import { dim } from "./style";
+
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const REGISTRY = "https://registry.npmjs.org/sproutboat/latest";
+
+type Cache = { checkedAt: number; latest: string };
+
+function cachePath(): string {
+  return resolve(configDirectory(), "update-check.json");
+}
+
+/** Numeric x.y.z compare; a trailing `-tag` (prerelease) sorts before its release. */
+function isNewer(latest: string, current: string): boolean {
+  const parts = (v: string) => v.split("-")[0].split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const [a, b] = [parts(latest), parts(current)];
+  for (let i = 0; i < 3; i++) {
+    if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) > (b[i] ?? 0);
+  }
+  return false;
+}
+
+async function latestVersion(): Promise<string | undefined> {
+  try {
+    const cached = JSON.parse(await readFile(cachePath(), "utf8")) as Cache;
+    if (Date.now() - cached.checkedAt < CACHE_TTL_MS && typeof cached.latest === "string") return cached.latest;
+  } catch { /* no cache yet, or unreadable — fetch below */ }
+
+  try {
+    const response = await fetch(REGISTRY, { signal: AbortSignal.timeout(1000), headers: { accept: "application/json" } });
+    if (!response.ok) return undefined;
+    const latest = ((await response.json()) as { version?: string }).version;
+    if (typeof latest !== "string") return undefined;
+    await writeFile(cachePath(), JSON.stringify({ checkedAt: Date.now(), latest } satisfies Cache)).catch(() => {});
+    return latest;
+  } catch { /* offline / slow / DNS — skip silently */ }
+  return undefined;
+}
+
+/** Print one dim line to stderr if a newer `sproutboat` is on npm. Never throws. */
+export async function notifyIfOutdated(current: string): Promise<void> {
+  if (process.env.SPROUTBOAT_NO_UPDATE_CHECK || process.env.CI) return;
+  const latest = await latestVersion();
+  if (latest && isNewer(latest, current)) {
+    console.error(dim(`  update available: sproutboat ${current} → ${latest}  ·  bump the dependency or run \`bunx sproutboat@latest\``));
+  }
+}