sproutboat 0.53.1 → 0.55.0

package/src/deployments-cli.ts

@@ -0,0 +1,184 @@
+/**
+ * `sproutboat deployments list | status | tail <id>`. On the Cloud a deployment is a build (the deploy-from-source flow):
+ * `GET /v1/apps/<app>/builds` lists them, `GET /v1/apps/<app>` says what is live, and `tail` follows one build's event
+ * stream server-side, which is what a deploy that was detached with Ctrl-C needs. On self-hosted Community a deployment is a
+ * version of the project (`/api/projects/<app>/deployments`), and there is nothing to follow: a deploy there is finished
+ * when the command returns.
+ */
+import { makeCall, parseBuildView, type BuildView, type CloudCredentials } from "./cloud-deploy";
+import { isSafeInteger, isString, jsonObject, type JsonObject } from "./json";
+import { bold, dim, ok, rose } from "./style";
+
+export type DeploymentsFlags = { json: boolean; limit: number; account?: string };
+export const LIST_LIMIT = 10;
+export const LIST_USAGE = "deployments list [--json]";
+export const STATUS_USAGE = "deployments status [--json]";
+export const TAIL_USAGE = "deployments tail <id>";
+
+export class DeploymentsUsageError extends Error {
+  constructor(
+    message: string,
+    readonly usage: string,
+  ) {
+    super(message);
+  }
+}
+
+/** Positionals and flags after `deployments <sub>`. */
+export function parseDeploymentsArgs(args: readonly string[], usage: string) {
+  const flags: DeploymentsFlags = { json: false, limit: LIST_LIMIT };
+  const positional: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]!;
+    const equals = arg.startsWith("--") ? arg.indexOf("=") : -1;
+    const name = equals > 0 ? arg.slice(0, equals) : arg;
+    if (name === "--json") {
+      if (equals > 0) throw new DeploymentsUsageError("--json takes no value", usage);
+      flags.json = true;
+    } else if (name === "--account") {
+      const value = equals > 0 ? arg.slice(equals + 1) : args[(index += 1)];
+      if (!value || (equals < 0 && value.startsWith("--")))
+        throw new DeploymentsUsageError(`${name} needs a value`, usage);
+      flags.account = value;
+    } else if (arg.startsWith("-")) throw new DeploymentsUsageError(`unknown option ${arg}`, usage);
+    else positional.push(arg);
+  }
+  return { positional, flags };
+}
+
+export type Live = {
+  recordGeneration: number | null;
+  appliedGeneration: number | null;
+  state: string | null;
+  error: string | null;
+  hosts: string[];
+};
+
+/** What the Cloud runs for an app now: the record generation, whether a host applied it, and its hostnames. */
+export function parseLive(body: JsonObject | undefined): Live {
+  const apply = jsonObject(body?.apply ?? null);
+  const spec = jsonObject(body?.spec ?? null);
+  const hosts = Array.isArray(spec?.hosts) ? spec.hosts.filter(isString) : [];
+  return {
+    recordGeneration: isSafeInteger(body?.record_generation) ? body.record_generation : null,
+    appliedGeneration: isSafeInteger(apply?.applied_generation) ? apply.applied_generation : null,
+    state: isString(apply?.state) ? apply.state : null,
+    error: isString(apply?.error) ? apply.error : null,
+    hosts,
+  };
+}
+
+export type CloudDeployment = {
+  id: string;
+  state: string;
+  generation: number | null;
+  cached: boolean;
+  createdAt: string | null;
+  finishedAt: string | null;
+  hosts: string[];
+  wallMs: number | null;
+  error: string | null;
+  /** The build whose record generation the host has applied. */
+  live: boolean;
+};
+
+export function parseDeployments(body: JsonObject | undefined, live: Live | null): CloudDeployment[] {
+  const list = Array.isArray(body?.builds) ? body.builds : [];
+  return list.flatMap((entry) => {
+    const item = jsonObject(entry);
+    if (!item || !isString(item.id) || !isString(item.state)) return [];
+    const view = parseBuildView(item);
+    const stats = jsonObject(item.stats ?? null);
+    const generation = view.recordGeneration ?? null;
+    return [
+      {
+        id: view.id,
+        state: view.state,
+        generation,
+        cached: view.cached,
+        createdAt: isString(item.queued_at) ? item.queued_at : null,
+        finishedAt: isString(item.finished_at) ? item.finished_at : null,
+        hosts: Array.isArray(item.hosts) ? item.hosts.filter(isString) : [],
+        wallMs: isSafeInteger(stats?.wall_ms) ? stats.wall_ms : null,
+        error: view.error?.message ?? null,
+        live:
+          view.state === "ready" &&
+          generation !== null &&
+          live?.appliedGeneration === generation &&
+          live.state === "applied",
+      },
+    ];
+  });
+}
+
+export async function fetchLive(credentials: CloudCredentials, project: string): Promise<Live | null> {
+  const reply = await makeCall(credentials)({ method: "GET", path: `/v1/apps/${project}`, ok: [404] });
+  return reply.status === 404 ? null : parseLive(reply.body);
+}
+
+export async function fetchDeployments(credentials: CloudCredentials, project: string, limit = LIST_LIMIT) {
+  const live = await fetchLive(credentials, project);
+  const reply = await makeCall(credentials)({ method: "GET", path: `/v1/apps/${project}/builds?limit=${limit}` });
+  return { live, deployments: parseDeployments(reply.body, live) };
+}
+
+const when = (iso: string | null) => iso ?? "unknown";
+
+export function formatDeployment(item: CloudDeployment): string {
+  const lines = [
+    `${bold("Deployment:")}  ${item.id}${item.live ? `  ${ok("live")}` : ""}`,
+    `Created:     ${when(item.createdAt)}`,
+    `State:       ${item.state}${item.wallMs !== null && !item.cached ? ` (built in ${(item.wallMs / 1000).toFixed(1)} s)` : ""}${item.cached ? " (cached build)" : ""}`,
+  ];
+  if (item.generation !== null) lines.push(`Generation:  ${item.generation}`);
+  if (item.hosts.length > 0) lines.push(`Hosts:       ${item.hosts.join(", ")}`);
+  if (item.error) lines.push(`Error:       ${rose(item.error.split("\n")[0]!)}`);
+  return lines.join("\n");
+}
+
+export function formatStatus(project: string, live: Live | null, latest: CloudDeployment | undefined): string {
+  if (!live) return `${project} is not deployed yet: run \`sproutboat deploy\` first`;
+  const applied = live.state === "applied" && live.appliedGeneration === live.recordGeneration;
+  const lines = [
+    `${bold("Application:")}  ${project}`,
+    `Generation:   ${live.recordGeneration ?? "unknown"}${applied ? ` ${ok("applied by a host")}` : ""}`,
+  ];
+  if (!applied)
+    lines.push(`Host apply:   ${live.state ?? "waiting for a host"}${live.error ? ` (${live.error})` : ""}`);
+  if (live.hosts.length > 0) lines.push(`Hosts:        ${live.hosts.join(", ")}`);
+  if (latest) lines.push(`Latest build: ${latest.id}  ${latest.state}${latest.live ? "  (live)" : ""}`);
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------- self-hosted Community
+
+export type CommunityVersion = { id: string; artifact: string; deployedAt: string; active: boolean };
+
+/** `GET /api/projects/<app>/deployments`: an array of { id, artifact, deployedAt, active }. */
+export function parseCommunityVersions(value: JsonObject[]): CommunityVersion[] {
+  return value.flatMap((item) =>
+    isString(item.id) && isString(item.artifact) && isString(item.deployedAt)
+      ? [{ id: item.id, artifact: item.artifact, deployedAt: item.deployedAt, active: item.active === true }]
+      : [],
+  );
+}
+
+export function formatCommunityVersion(item: CommunityVersion): string {
+  return [
+    `${bold("Deployment:")}  ${item.id}${item.active ? `  ${ok("active")}` : ""}`,
+    `Created:     ${item.deployedAt}`,
+    `Artifact:    ${item.artifact.slice(0, 12)}`,
+  ].join("\n");
+}
+
+export const COMMUNITY_TAIL =
+  "deployments tail is not supported on self-hosted Community: a deploy there finishes before `sproutboat deploy` returns, so there is nothing to follow (see `sproutboat versions list` for past deploys)";
+
+// ---------------------------------------------------------------- tail
+
+export function tailSummary(view: BuildView): string {
+  if (view.state === "ready")
+    return `${ok("ready")}${view.recordGeneration !== undefined ? `; record generation ${view.recordGeneration}` : ""}`;
+  if (view.state === "canceled") return `${dim("canceled")}${view.error ? `: ${view.error.message}` : ""}`;
+  return `${rose("failed")}: ${view.error?.message.split("\n").at(-1) ?? "no reason given"}`;
+}

package/src/dev.ts

@@ -32,6 +32,8 @@ export type DevInput = {
   /** The bundled module (#89) — already validated by the caller. */
   source: string;
   port: number;
+  /** `--ip`: the address the public port listens on. Default 127.0.0.1; 0.0.0.0 makes it reachable on the network. */
+  host?: string;
   watch: boolean;
   /** #275: `--env-file` paths (absolute), in order. Default: `.dev.vars`, else the `.env` files. */
   envFiles?: string[];
@@ -105,6 +107,52 @@ export type Running = {
   disableDispatch: () => void;
 };
 
+/** One browser WebSocket and the connection to the sprout that answers it. */
+type SocketRelay = {
+  url: string;
+  protocols: string[];
+  /** Frames that arrived before the sprout side finished opening. */
+  queued: Array<string | Uint8Array<ArrayBuffer>>;
+  upstream?: WebSocket;
+};
+
+const socketRelay: Bun.WebSocketHandler<SocketRelay> = {
+  open(client) {
+    const relay = client.data;
+    const upstream = new WebSocket(relay.url, relay.protocols);
+    upstream.binaryType = "arraybuffer";
+    relay.upstream = upstream;
+    upstream.addEventListener("open", () => {
+      for (const frame of relay.queued.splice(0)) upstream.send(frame);
+    });
+    upstream.addEventListener("message", (event) => {
+      if (client.readyState !== 1) return;
+      // SAFETY: binaryType is "arraybuffer", so a frame is a string or an ArrayBuffer.
+      client.send(event.data as string | ArrayBuffer);
+    });
+    upstream.addEventListener("close", (event) => {
+      // 1005 and 1006 are reserved for the receiver to report; they cannot be sent.
+      const code =
+        event.code >= 1000 && event.code < 5000 && event.code !== 1005 && event.code !== 1006 ? event.code : 1000;
+      client.close(code, event.reason);
+    });
+    upstream.addEventListener("error", () => client.close(1011, "sprout unavailable"));
+  },
+  message(client, message) {
+    const upstream = client.data.upstream;
+    const frame = message instanceof Uint8Array ? new Uint8Array(message) : message;
+    if (upstream && upstream.readyState === 1) upstream.send(frame);
+    else client.data.queued.push(frame);
+  },
+  close(client, code, reason) {
+    const upstream = client.data.upstream;
+    if (!upstream || upstream.readyState > 1) return;
+    try {
+      upstream.close(code === 1005 || code === 1006 ? 1000 : code, reason);
+    } catch {}
+  },
+};
+
 async function start(input: DevInput, port: number): Promise<Running> {
   const candidateDir = resolve(
     input.projectDir,
@@ -285,12 +333,26 @@ export async function runDev(input: DevInput): Promise<void> {
   // what lets a failed startup leave the last known-good process reachable.
   let proxy: ReturnType<typeof Bun.serve>;
   try {
-    proxy = Bun.serve({
-      hostname: "127.0.0.1",
+    proxy = Bun.serve<SocketRelay>({
+      hostname: input.host ?? "127.0.0.1",
       port: input.port,
       maxRequestBodySize: 5 * 1024 * 1024 * 1024,
+      websocket: socketRelay,
       fetch(request, server) {
         const target = new URL(request.url);
+        // A WebSocket upgrade cannot go through fetch(): relay it, frame by frame, to the sprout.
+        if (request.headers.get("upgrade")?.toLowerCase() === "websocket") {
+          target.protocol = "ws:";
+          target.host = `127.0.0.1:${activePort}`;
+          const protocols = request.headers.get("sec-websocket-protocol");
+          const data: SocketRelay = {
+            url: target.toString(),
+            protocols: protocols ? protocols.split(",").map((entry) => entry.trim()) : [],
+            queued: [],
+          };
+          if (server.upgrade(request, { data })) return undefined;
+          return new Response("WebSocket upgrade failed", { status: 400 });
+        }
         const directTransfer = /^\/__sb\/r2\/transfer\/[A-Z][A-Z0-9_]*\/[0-9a-f]{24}$/.test(target.pathname);
         if (directTransfer) server.timeout(request, 255);
         if (directTransfer && !activeTransferPort) return new Response("direct transfers unavailable", { status: 503 });
@@ -308,7 +370,7 @@ export async function runDev(input: DevInput): Promise<void> {
     throw error;
   }
   watchExit(running);
-  console.log(ok(`${input.config.name} running on ${leaf(`http://127.0.0.1:${input.port}`)}`));
+  console.log(ok(`${input.config.name} running on ${leaf(`http://${input.host ?? "127.0.0.1"}:${input.port}`)}`));
   if (input.watch) console.log(dim("  watching for changes — ctrl-c to stop"));
 
   let watchers: FSWatcher[] = [];
@@ -319,7 +381,8 @@ export async function runDev(input: DevInput): Promise<void> {
     if (shuttingDown) return;
     shuttingDown = true;
     for (const watcher of watchers) watcher.close();
-    proxy.stop();
+    // Close open sockets too: a graceful stop waits for a WebSocket the browser keeps open.
+    proxy.stop(true);
     if (pendingCandidate) stop(pendingCandidate);
     stop(running);
     resolveShutdown?.();

package/src/fake-login.ts

@@ -0,0 +1,28 @@
+/**
+ * Test helper: a config directory holding two stored logins, a decoy that is the default and the fake Cloud under a
+ * name of its own, so a test can tell `--profile` from "whatever is stored". Nothing listens at the decoy.
+ */
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { FAKE_KEY } from "./cloud-fake";
+
+export const DECOY_URL = "http://127.0.0.1:9";
+
+export function fakeLogin(cloudUrl: string) {
+  const dir = mkdtempSync(join(tmpdir(), "sb-fake-login-"));
+  mkdirSync(join(dir, "sproutboat"), { recursive: true });
+  writeFileSync(
+    join(dir, "sproutboat", "credentials.json"),
+    JSON.stringify({
+      version: 1,
+      activeApiUrl: DECOY_URL,
+      profiles: { [DECOY_URL]: { token: "nobody", kind: "community" }, [cloudUrl]: { token: FAKE_KEY, kind: "cloud" } },
+    }),
+  );
+  return {
+    dir,
+    profile: `127.0.0.1-${new URL(cloudUrl).port}`,
+    env: { SPROUTBOAT_CONFIG_DIR: dir, SPROUTBOAT_API_URL: "", SPROUTBOAT_PROFILE: "", SPROUTBOAT_API_TOKEN: "" },
+  };
+}

package/src/global-flags.ts

@@ -0,0 +1,113 @@
+/**
+ * Flags that every command accepts, parsed in one place and removed from argv before a command sees it.
+ * Semantics follow Wrangler's global flags:
+ *
+ *   -c, --config <file>   the project's config file (its directory is the project directory)
+ *       --cwd <dir>       run as if started in <dir>
+ *   -e, --env <name>      environment: selects .dev.vars.<name> and the .env.<name> files
+ *       --env-file <file> repeatable; values from later files override earlier ones
+ *       --profile <name>  the credential profile (also SPROUTBOAT_PROFILE)
+ *       --api-url <url>   the control plane (also SPROUTBOAT_API_URL); only for commands that talk to one
+ *   -v, --version         print the version
+ *
+ * They can sit anywhere on the line, before or after the command, as `--flag value` or `--flag=value`. A
+ * repeated single-value flag takes its last value (a script's fixed flags can be overridden by appending).
+ * Everything after a bare `--` is left alone, and so is the value of a flag whose value is free text.
+ * `-h/--help` stays in the arguments: the command decides what to print.
+ */
+import { dirname, resolve } from "node:path";
+
+export type GlobalFlags = {
+  config?: string;
+  cwd?: string;
+  env?: string;
+  /** Every `--env-file`, in the order given. */
+  envFiles: string[];
+  profile?: string;
+  /** `--api-url`: taken out here so every command that talks to a control plane honours it, in both forms. */
+  apiUrl?: string;
+  version: boolean;
+};
+
+export type GlobalParse = { flags: GlobalFlags; rest: string[] } | { error: string };
+
+type Spec = { names: readonly string[]; key: "config" | "cwd" | "env" | "envFiles" | "profile" | "apiUrl" };
+
+const VALUE_FLAGS: readonly Spec[] = [
+  { names: ["-c", "--config"], key: "config" },
+  { names: ["--cwd"], key: "cwd" },
+  { names: ["-e", "--env"], key: "env" },
+  { names: ["--env-file"], key: "envFiles" },
+  { names: ["--profile"], key: "profile" },
+  { names: ["--api-url"], key: "apiUrl" },
+];
+
+/** Per-command flags whose value is free text: it must never be read as a global flag (`--value -e`). */
+const FREE_TEXT_FLAGS = new Set(["--value", "--token", "--search", "--outcome", "--name", "--command"]);
+
+/** Split argv into the global flags and what is left for the command. Does not touch the filesystem. */
+export function extractGlobalFlags(argv: readonly string[]): GlobalParse {
+  const flags: GlobalFlags = { envFiles: [], version: false };
+  const rest: string[] = [];
+  for (let at = 0; at < argv.length; at += 1) {
+    const arg = argv[at];
+    if (arg === "--") {
+      rest.push(...argv.slice(at));
+      break;
+    }
+    if (FREE_TEXT_FLAGS.has(arg)) {
+      rest.push(arg);
+      if (at + 1 < argv.length) rest.push(argv[(at += 1)]);
+      continue;
+    }
+    if (arg === "-v" || arg === "--version") {
+      flags.version = true;
+      continue;
+    }
+    const eq = arg.startsWith("-") ? arg.indexOf("=") : -1;
+    const name = eq < 0 ? arg : arg.slice(0, eq);
+    const spec = VALUE_FLAGS.find((candidate) => candidate.names.includes(name));
+    if (!spec) {
+      rest.push(arg);
+      continue;
+    }
+    const value = eq < 0 ? argv[(at += 1)] : arg.slice(eq + 1);
+    if (value === undefined || value === "" || (eq < 0 && value.startsWith("-") && value !== "-"))
+      return { error: `${name} needs a value` };
+    if (spec.key === "envFiles") flags.envFiles.push(value);
+    else flags[spec.key] = value;
+  }
+  return { flags, rest };
+}
+
+/** The global flags of this run. Set once by `main.ts` before any command runs. */
+let current: GlobalFlags = { envFiles: [], version: false };
+
+export function setGlobalFlags(flags: GlobalFlags): void {
+  current = flags;
+}
+
+export function globalFlags(): GlobalFlags {
+  return current;
+}
+
+export type ProjectLocation = { directory: string; configPath: string };
+
+/** What `--config` and a positional project directory say, together. */
+export function locateProject(
+  positional: string | undefined,
+  config: string | undefined = current.config,
+  cwd: string = process.cwd(),
+): ProjectLocation {
+  if (config === undefined) {
+    const directory = resolve(cwd, positional ?? ".");
+    return { directory, configPath: resolve(directory, "sproutboat.jsonc") };
+  }
+  const configPath = resolve(cwd, config);
+  const directory = dirname(configPath);
+  if (positional !== undefined && resolve(cwd, positional) !== directory)
+    throw new Error(
+      `--config ${config} is in ${directory}, but the project directory says ${resolve(cwd, positional)}; pass one`,
+    );
+  return { directory, configPath };
+}

package/src/init-package.ts

@@ -5,7 +5,8 @@ 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.
+// package at 0.0.0, `dev`, `deploy` and `check` scripts, and the CLI as a
+// devDependency.
 export const INIT_SCRIPTS = {
   dev: "sproutboat dev",
   deploy: "sproutboat deploy",