sproutboat 0.4.0 → 0.4.2

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.0 · runs on Bun (use `bunx`, not `npx`)
+**Package:** `sproutboat` 0.4.2 · runs on Bun (use `bunx`, not `npx`)
 
 ## Commands
 
@@ -12,17 +12,17 @@
 | `init` | `[name]` | Scaffold sproutboat.jsonc + src/index.js in ./<name>. |
 | `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>]` | Build (unless --artifact), print the report, upload. --dry-run stops before upload. |
+| `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]` | Print the project's recent request logs. |
+| `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. |
 | `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` | `--yes [project-dir]` | Delete the project and every version. |
+| `delete` | `[project-dir] [--name <project>] --yes` | Delete the project, every version, and its route. |
 
 ```
-usage: sproutboat <init [name] | check [project-dir] | build [project-dir] | deploy [project-dir] [--dry-run] [--artifact <dir>] | login [--api-url <url>] [--token <token>] | tail [project-dir] | 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 --yes [project-dir]>
+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>
 ```
 
 ## Environment variables
@@ -37,6 +37,7 @@ usage: sproutboat <init [name] | check [project-dir] | build [project-dir] | dep
 | `SPROUTBOAT_VARS_JSON` | JSON object of baked `vars` (UPPER_SNAKE -> string), read by the wrapper when generating the sprout module. |
 | `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. |
 | `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.0",
+  "version": "0.4.2",
   "description": "Wrangler-shaped CLI for Sproutboat. Deploys workers to any control plane via --api-url / SPROUTBOAT_API_URL.",
   "license": "MIT",
   "type": "module",

package/src/main.ts

@@ -8,6 +8,7 @@ import { validateManifest, type ArtifactManifest } from "./manifest";
 import { printDeployReport } from "./report";
 import { activeApiUrl, savedToken, saveToken } from "./credentials";
 import { usageLine } from "./surface";
+import { amber, bold, dim, leaf, ok, rose } from "./style";
 
 const defaultApiUrl = "https://dashboard.sproutboat.com";
 
@@ -106,7 +107,7 @@ const starterHandler = `export default {
 `;
 
 function fail(message: string): never {
-  console.error(`sproutboat: ${message}`);
+  console.error(`${rose("✗")} ${message}`);
   process.exit(1);
 }
 
@@ -147,14 +148,14 @@ async function init(name = "hello") {
 
 async function check(directory?: string) {
   const project = await readProject(directory);
-  console.log(`check passed: ${project.config.name} (${project.config.main}, native-fetch)`);
+  console.log(ok(`check passed — ${project.config.name} (${project.config.main}, native-fetch)`));
 }
 
 async function build(directory?: string) {
   const project = await readProject(directory);
-  console.log("Compiling the native-fetch server with Porffor + Zig (linux-x86_64, static)...");
+  console.log(dim("Compiling the native-fetch server with Porffor + Zig (linux-x86_64, static)…"));
   const artifact = await buildArtifact({ projectDir: project.directory, config: project.config, sourcePath: project.sourcePath });
-  console.log(`Built ${project.config.name}`);
+  console.log(ok(`built ${project.config.name}`));
   console.log(artifact.artifactDir);
   return { project, artifact };
 }
@@ -201,7 +202,7 @@ async function deploy(args: string[]) {
     if (!deployments) fail("could not parse deployment list response");
     const active = deployments.find((deployment) => deployment.active && deployment.artifact === digest);
     if (active) {
-      console.log(`Nothing to deploy — artifact ${digest.slice(0, 12)} is already active`);
+      console.log(ok(`nothing to deploy — artifact ${digest.slice(0, 12)} is already active`));
       console.log(`https://${active.hostname}`);
       return;
     }
@@ -236,14 +237,40 @@ async function deploy(args: string[]) {
   const body = await responseText(response, "deployment rejected");
   const deployed = parseUrlResponse(body);
   if (!deployed) fail("deployment response did not include a URL");
-  console.log(`\nDeployed ${projectName}`);
-  console.log(`  ${deployed.url}`);
+  console.log(`\n${leaf("🌱")} ${bold(leaf(`Deployed ${projectName}`))}`);
+  console.log(`  ${bold(deployed.url)}`);
   const drift = parsePorfforDrift(body);
   if (drift) {
-    console.warn(`\n! Porffor pin changed: ${drift.from} -> ${drift.to}`);
-    console.warn(`  The previous live version stays frozen at ${drift.from}; this one is built with ${drift.to}.`);
-    console.warn(`  The alpha compiler's output can differ between pins (see COMPAT.md) — roll back if this version misbehaves.`);
+    console.warn(amber(`\n! Porffor pin changed: ${drift.from} -> ${drift.to}`));
+    console.warn(dim(`  The previous live version stays frozen at ${drift.from}; this one is built with ${drift.to}.`));
+    console.warn(dim(`  The alpha compiler's output can differ between pins (see COMPAT.md) — roll back if this version misbehaves.`));
   }
+  if (!args.includes("--no-wait")) {
+    const healthy = await waitForHealthy(deployed.url, 90_000);
+    console.log(healthy
+      ? `  ${ok("serving")}`
+      : amber("  ! not serving after 90s — Caddy may still be issuing the cert, or the sprout is crashing (`sproutboat tail`)"));
+  }
+}
+
+/**
+ * Poll the deployment URL until the edge returns any non-5xx response. Connection
+ * and TLS errors (the cert is issued on the first HTTPS request) count as "not
+ * ready yet". Returns false on timeout without failing the deploy — the artifact
+ * is already active server-side.
+ */
+async function waitForHealthy(url: string, timeoutMs: number): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  let wait = 1000;
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(url, { method: "HEAD", redirect: "manual" });
+      if (response.status < 500) return true;
+    } catch { /* DNS / TLS-not-yet-issued / connection refused — keep waiting */ }
+    await Bun.sleep(Math.min(wait, Math.max(0, deadline - Date.now())));
+    if (wait < 5000) wait += 1000;
+  }
+  return false;
 }
 
 function parseLoginArgs(args: string[]) {
@@ -290,7 +317,7 @@ async function login(args: string[]) {
     const token = parseToken(result);
     if (!token) fail("login response did not include a CLI token");
     await saveToken(apiUrl, token);
-    console.log("Login approved. Credentials were saved locally for this API endpoint.");
+    console.log(ok("login approved — credentials saved for this endpoint"));
     return;
   }
   fail("login expired before approval");
@@ -319,13 +346,16 @@ async function rollback(args: string[]) {
   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"));
   if (!deployment) fail("rollback response did not include a URL");
-  console.log(`Rolled back ${project.config.name}`);
+  console.log(ok(`rolled back ${project.config.name}`));
   console.log(deployment.url);
 }
 
 async function tail(args: string[]) {
-  const [project, { apiUrl, token }] = await Promise.all([readProject(args[0]), apiCredentials()]);
-  const response = await fetch(`${apiUrl}/api/projects/${project.config.name}/logs/recent`, { headers: { "x-api-key": token } });
+  const sproutLog = args.includes("--sprout");
+  const dir = args.find((arg) => !arg.startsWith("-"));
+  const [project, { apiUrl, token }] = await Promise.all([readProject(dir), apiCredentials()]);
+  const path = sproutLog ? "logs/sprout" : "logs/recent";
+  const response = await fetch(`${apiUrl}/api/projects/${project.config.name}/${path}`, { headers: { "x-api-key": token } });
   process.stdout.write(await responseText(response, "could not read logs"));
 }
 
@@ -366,7 +396,7 @@ async function domains(args: string[]) {
   if (sub === "rm") {
     const response = await fetch(`${base}/${host}`, { method: "DELETE", headers: auth });
     await responseText(response, "delete rejected");
-    console.log(`Removed ${host}`);
+    console.log(ok(`removed ${host}`));
     return;
   }
   const url = sub === "add" ? base : `${base}/${host}/verify`;
@@ -397,7 +427,7 @@ async function secrets(args: string[]) {
   }
   if (sub === "rm") {
     await responseText(await fetch(`${base}/${name}`, { method: "DELETE", headers: auth }), "delete rejected");
-    console.log(`Removed ${name}`);
+    console.log(ok(`removed ${name}`));
     return;
   }
   // set: value from the next arg, else stdin (keeps it out of shell history).
@@ -413,11 +443,34 @@ async function secrets(args: string[]) {
 }
 
 async function deleteProject(args: string[]) {
-  if (args[0] !== "--yes") fail("refusing to delete without --yes");
-  const [project, { apiUrl, token }] = await Promise.all([readProject(args[1]), apiCredentials()]);
-  const response = await fetch(`${apiUrl}/api/projects/${project.config.name}`, { method: "DELETE", headers: { "x-api-key": token } });
-  await responseText(response, "delete rejected");
-  console.log(`Deleted ${project.config.name}`);
+  // `sproutboat delete [project-dir] [--name <project>] --yes` — flags in any order.
+  const positional: string[] = [];
+  let confirmed = false;
+  let explicitName: string | undefined;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    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`);
+  }
+
+  const { apiUrl, token } = await apiCredentials();
+  const name = explicitName ?? (await readProject(positional[0])).config.name;
+  if (!confirmed) fail(`this permanently removes "${name}", every version, and its route — re-run with --yes`);
+
+  const url = `${apiUrl}/api/projects/${encodeURIComponent(name)}?confirm=${encodeURIComponent(name)}`;
+  const body = await responseText(await fetch(url, { method: "DELETE", headers: { "x-api-key": token } }), "delete rejected");
+
+  let result: JsonObject = {};
+  try { result = jsonObject(parseJsonValue(body)) ?? {}; } catch { /* a 2xx already confirmed the delete */ }
+  const versions = isSafeInteger(result.versionsRemoved) ? result.versionsRemoved : 0;
+  const routes = Array.isArray(result.routeRemoved) ? result.routeRemoved.filter(isString) : [];
+  const failed = Array.isArray(result.artifactCleanupFailed) ? result.artifactCleanupFailed.filter(isString) : [];
+
+  console.log(ok(`deleted ${name} — ${versions} version${versions === 1 ? "" : "s"} removed`));
+  for (const route of routes) console.log(`  released ${route}`);
+  if (failed.length) console.log(`  ! ${failed.length} artifact file(s) left on disk — remove them manually`);
 }
 
 function usage(): never {

package/src/report.ts

@@ -1,8 +1,11 @@
+import { readFileSync } from "node:fs";
 import { gzipSync } from "bun";
 import type { SproutboatConfig } from "./config";
 import type { ArtifactManifest } from "./manifest";
+import { bold, dim, leaf, sprout } from "./style";
 
-const CLI_VERSION = "0.1.0";
+// 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;
 
 function bytes(n: number): string {
   if (n < 1024) return `${n} B`;
@@ -11,55 +14,75 @@ function bytes(n: number): string {
   return `${(kib / 1024).toFixed(2)} MiB`;
 }
 
-/** Minimal box table. `align` marks columns to right-pad-left (numbers). */
+/** Minimal box table with a green frame. `align` marks columns to right-pad-left (numbers). */
 function table(headers: string[], rows: string[][], align: boolean[] = []): string {
   const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)));
-  const line = (l: string, m: string, r: string) => l + widths.map((w) => "─".repeat(w + 2)).join(m) + r;
-  const row = (cells: string[]) =>
-    "│ " + cells.map((c, i) => (align[i] ? (c ?? "").padStart(widths[i]) : (c ?? "").padEnd(widths[i]))).join(" │ ") + " │";
-  return [line("┌", "┬", "┐"), row(headers), line("├", "┼", "┤"), ...rows.map(row), line("└", "┴", "┘")].join("\n");
+  const rule = (l: string, m: string, r: string) => leaf(l + widths.map((w) => "─".repeat(w + 2)).join(m) + r);
+  const row = (cells: string[], head = false) =>
+    leaf("│ ") + cells.map((c, i) => {
+      const cell = align[i] ? (c ?? "").padStart(widths[i]) : (c ?? "").padEnd(widths[i]);
+      return head ? bold(cell) : cell;
+    }).join(leaf(" │ ")) + leaf(" │");
+  return [rule("┌", "┬", "┐"), row(headers, true), rule("├", "┼", "┤"), ...rows.map((r) => row(r)), rule("└", "┴", "┘")].join("\n");
+}
+
+/** Every binding the compiled sprout will see, flattened to (name, type, detail) rows. */
+function bindingRows(config: SproutboatConfig): string[][] {
+  const rows: string[][] = [];
+  for (const [name, value] of Object.entries(config.vars ?? {})) rows.push([`env.${name}`, "var", JSON.stringify(value)]);
+  const list = (names: string[] | undefined, type: string, detail = "") => {
+    for (const name of names ?? []) rows.push([`env.${name}`, type, detail]);
+  };
+  list(config.kv_namespaces, "kv");
+  list(config.secrets, "secret", "value withheld — set with `sproutboat secrets`");
+  list(config.d1_databases, "d1");
+  list(config.r2_buckets, "r2");
+  list(config.queues, "queue");
+  list(config.analytics_engine_datasets, "analytics");
+  for (const [name, className] of Object.entries(config.durable_objects ?? {})) rows.push([`env.${name}`, "durable object", className]);
+  for (const host of config.outbound ?? []) rows.push([`fetch()`, "outbound", host]);
+  for (const cron of config.triggers?.crons ?? []) rows.push([`scheduled()`, "cron", cron]);
+  if (config.assets?.binding) rows.push([`env.${config.assets.binding}`, "assets", config.assets.directory ?? ""]);
+  return rows;
 }
 
 /**
- * Wrangler-shaped build/deploy summary. Prints what the artifact contains, its
- * upload size, and the bindings the handler will see. Returns nothing.
+ * Wrangler-shaped build/deploy summary: what the artifact contains, its upload
+ * size, and every binding the handler will see. Returns nothing.
  */
 export function printDeployReport(
   config: SproutboatConfig,
   manifest: ArtifactManifest,
-  sprout: Uint8Array,
+  sproutBin: Uint8Array,
   manifestBytes: number,
 ): void {
-  const gz = gzipSync(Uint8Array.from(sprout)).length;
-  const total = sprout.length + manifestBytes;
+  const gz = gzipSync(Uint8Array.from(sproutBin)).length;
+  const total = sproutBin.length + manifestBytes;
 
-  console.log(`\n🌱 sproutboat ${CLI_VERSION}`);
-  console.log("─".repeat(19));
-  console.log(`Compiled ${manifest.project} with Porffor ${manifest.porfforVersion}`);
-  console.log(`  toolchain  ${manifest.buildImage}`);
-  console.log(`  compat     ${config.compatibility_date}`);
+  console.log(`\n${sprout("🌱")} ${bold(leaf(`sproutboat ${CLI_VERSION}`))}`);
+  console.log(leaf("─".repeat(19)));
+  console.log(`Compiled ${bold(manifest.project)} with Porffor ${manifest.porfforVersion}`);
+  console.log(dim(`  toolchain  ${manifest.buildImage}`));
+  console.log(dim(`  compat     ${config.compatibility_date}`));
   console.log();
 
-  console.log("Artifact:");
+  console.log(bold("Artifact"));
   console.log(table(
     ["File", "Type", "Size"],
     [
-      ["sprout", manifest.runtime, bytes(sprout.length)],
+      ["sprout", manifest.runtime, bytes(sproutBin.length)],
       ["manifest.json", "json", bytes(manifestBytes)],
     ],
     [false, false, true],
   ));
-  console.log(`Total upload: ${bytes(total)}  (sprout gzip: ${bytes(gz)})`);
+  console.log(`Total upload: ${bold(bytes(total))}  ${dim(`(sprout gzip: ${bytes(gz)})`)}`);
   console.log();
 
-  const vars = Object.entries(config.vars ?? {});
-  console.log("Bindings the handler will see:");
-  if (vars.length === 0) {
-    console.log("  (none — add [vars] to sproutboat.jsonc)");
+  const rows = bindingRows(config);
+  console.log(bold("Bindings the handler will see"));
+  if (rows.length === 0) {
+    console.log(dim("  (none — add vars / kv_namespaces / secrets / … to sproutboat.jsonc)"));
   } else {
-    console.log(table(
-      ["Binding", "Type", "Value"],
-      vars.map(([k, v]) => [`env.${k}`, "var", JSON.stringify(v)]),
-    ));
+    console.log(table(["Binding", "Type", "Detail"], rows));
   }
 }

package/src/style.ts

@@ -0,0 +1,18 @@
+/**
+ * Green/leaf terminal styling. Every helper is a no-op when stdout is not a TTY
+ * or NO_COLOR is set (https://no-color.org), so piped/CI output stays plain.
+ */
+const enabled = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+const paint = (code: string) => (text: string): string => (enabled ? `\x1b[${code}m${text}\x1b[0m` : text);
+
+export const leaf = paint("32");        // green — headings, structure, the accent
+export const sprout = paint("92");      // bright green — success
+export const dim = paint("2");          // secondary detail
+export const bold = paint("1");
+export const amber = paint("33");       // warnings
+export const rose = paint("31");        // errors
+
+/** "✓ message" with a green tick. */
+export const ok = (message: string): string => `${sprout("✓")} ${message}`;
+/** "▸ message" with a green marker — section headers. */
+export const step = (message: string): string => `${leaf("▸")} ${bold(message)}`;

package/src/surface.ts

@@ -11,14 +11,14 @@ 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>]", summary: "Build (unless --artifact), print the report, upload. --dry-run stops before upload." },
+  { 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]", summary: "Print the project's recent request logs." },
+  { 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: "--yes [project-dir]", summary: "Delete the project and every version." },
+  { name: "delete", args: "[project-dir] [--name <project>] --yes", summary: "Delete the project, every version, and its route." },
 ];
 
 export type EnvVar = { name: string; purpose: string };
@@ -32,6 +32,7 @@ export const ENV_VARS: readonly EnvVar[] = [
   { name: "SPROUTBOAT_VARS_JSON", purpose: "JSON object of baked `vars` (UPPER_SNAKE -> string), read by the wrapper when generating the sprout module." },
   { 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: "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)." },