svcloud 0.1.0-alpha.3

package/src/commands/init.ts

@@ -0,0 +1,236 @@
+/**
+ * `svcloud init` — PLANNING.md §3.1/§4 Step 3: the connect flow, covering
+ * what `cloud-web`'s NameApp → ConnectCode → FirstBuild screens do. No new
+ * `cloud-api` route — every call here already exists and is inside
+ * `svcloud-cli`'s scopes.
+ */
+import type {
+  ProjectDetail,
+  ProvisionAccepted,
+  RunDetail,
+} from "@sv/cloud-contracts";
+import { apiFetch } from "../lib/api";
+import { openBrowser } from "../lib/browser";
+import { inferRepoFromCwd } from "../lib/git";
+import { die, printJson, takeOption } from "../lib/output";
+import { choose, isInteractive, prompt } from "../lib/prompt";
+import { pollRun } from "../lib/run-poll";
+
+interface Installation {
+  id: number;
+  github_account_login: string;
+  created_at: string;
+}
+
+interface InstallationRepo {
+  name: string;
+  full_name: string;
+  empty: boolean;
+  pushed_at: string | null;
+}
+
+interface InstallationContext {
+  account_login: string;
+  repos: InstallationRepo[];
+}
+
+interface SubdomainCheck {
+  available: boolean;
+  reason?: "reserved" | "invalid" | "taken";
+}
+
+function slugify(input: string): string {
+  return input
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/-{2,}/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function slugReason(reason: SubdomainCheck["reason"]): string {
+  switch (reason) {
+    case "taken":
+      return "already in use";
+    case "reserved":
+      return "reserved";
+    case "invalid":
+      return "not a valid web address (lowercase letters, numbers, and dashes, 3-63 characters)";
+    default:
+      return "unavailable";
+  }
+}
+
+async function checkSlug(slug: string): Promise<SubdomainCheck> {
+  return apiFetch<SubdomainCheck>(`/api/v1/projects/subdomain?slug=${encodeURIComponent(slug)}`);
+}
+
+async function resolveSlug(desired: string, interactive: boolean): Promise<string> {
+  let candidate = desired;
+  for (;;) {
+    const check = await checkSlug(candidate);
+    if (check.available) return candidate;
+    if (!interactive) {
+      die(
+        `Web address "${candidate}" is ${slugReason(check.reason)}. Pass a different one with --slug.`,
+      );
+    }
+    console.log(`"${candidate}" is ${slugReason(check.reason)}.`);
+    candidate = slugify(await prompt("Try a different web address"));
+    if (!candidate) console.log("That's empty once turned into a web address — try again.");
+  }
+}
+
+async function resolveInstallation(
+  fullName: string,
+  flagValue: string | undefined,
+  interactive: boolean,
+): Promise<number> {
+  if (flagValue) {
+    const id = Number.parseInt(flagValue, 10);
+    if (!Number.isInteger(id) || id <= 0) die(`--installation must be a positive integer, got "${flagValue}".`);
+    return id;
+  }
+
+  const { installations } = await apiFetch<{ installations: Installation[] }>("/api/v1/installations");
+
+  if (installations.length === 0) {
+    return await installGitHubAppAndWait(interactive);
+  }
+
+  if (installations.length === 1) {
+    return (installations[0] as Installation).id;
+  }
+
+  // Several installations: prefer the one whose repos actually include this repo.
+  const matches: Installation[] = [];
+  for (const inst of installations) {
+    const ctx = await apiFetch<InstallationContext>(`/api/v1/installations/${inst.id}`);
+    if (ctx.repos.some((r) => r.full_name.toLowerCase() === fullName.toLowerCase())) {
+      matches.push(inst);
+    }
+  }
+  if (matches.length === 1) return (matches[0] as Installation).id;
+
+  const candidates = matches.length > 0 ? matches : installations;
+  if (!interactive) {
+    die(
+      `Multiple GitHub connections could own "${fullName}". Pass --installation with one of: ${candidates
+        .map((i) => `${i.id} (${i.github_account_login})`)
+        .join(", ")}.`,
+    );
+  }
+  const idx = await choose(
+    "Which GitHub connection has this repo?",
+    candidates.map((i) => `${i.github_account_login} (installation ${i.id})`),
+  );
+  return (candidates[idx] as Installation).id;
+}
+
+async function installGitHubAppAndWait(interactive: boolean): Promise<number> {
+  if (!interactive) {
+    die(
+      "No GitHub connection found on your account. Run `svcloud init` from a real terminal " +
+        "to install the GitHub App, or connect it first at the dashboard.",
+    );
+  }
+  const { url } = await apiFetch<{ url: string }>("/api/v1/installations/connect-url");
+  console.log("No GitHub connection found. Opening your browser to install the SV Cloud GitHub App...");
+  console.log(`If it doesn't open, visit:\n  ${url}`);
+  openBrowser(url);
+
+  console.log("Waiting for the install to finish...");
+  const timeoutMs = 5 * 60 * 1000;
+  const intervalMs = 3000;
+  const start = Date.now();
+  for (;;) {
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    const { installations } = await apiFetch<{ installations: Installation[] }>("/api/v1/installations");
+    if (installations.length > 0) return (installations[0] as Installation).id;
+    if (Date.now() - start > timeoutMs) {
+      die("Timed out waiting for the GitHub App install. Run `svcloud init` again once it's done.");
+    }
+  }
+}
+
+function isProvisionAccepted(x: ProjectDetail | ProvisionAccepted): x is ProvisionAccepted {
+  return "run_id" in x;
+}
+
+export async function initCommand(argv: string[], json: boolean): Promise<void> {
+  const repoOpt = takeOption(argv, "repo");
+  const nameOpt = takeOption(repoOpt.rest, "name");
+  const slugOpt = takeOption(nameOpt.rest, "slug");
+  const installOpt = takeOption(slugOpt.rest, "installation");
+
+  const interactive = isInteractive();
+
+  let repoFullName = repoOpt.value;
+  if (!repoFullName) {
+    const inferred = await inferRepoFromCwd();
+    if (!inferred) {
+      die(
+        "Couldn't find a GitHub remote in this directory. Run this from a repo with an " +
+          '"origin" remote, or pass --repo <owner/name>.',
+      );
+    }
+    repoFullName = inferred.fullName;
+  }
+  const repoName = (repoFullName.split("/")[1] ?? repoFullName).toLowerCase();
+
+  const name = nameOpt.value ?? repoName;
+  const desiredSlug = slugOpt.value ? slugify(slugOpt.value) : slugify(repoName);
+  const slug = await resolveSlug(desiredSlug || "my-app", interactive);
+
+  const installationId = await resolveInstallation(repoFullName, installOpt.value, interactive);
+
+  if (!json) console.log(`Connecting ${repoFullName} as "${name}" (${slug})...`);
+
+  const result = await apiFetch<ProjectDetail | ProvisionAccepted>("/api/v1/projects/connect", {
+    method: "POST",
+    body: {
+      name,
+      repo_full_name: repoFullName,
+      github_installation_id: installationId,
+      requested_subdomain: slug,
+      framework_type: "hono",
+      scheduled_cleanup_at: null,
+    },
+  });
+
+  if (!isProvisionAccepted(result)) {
+    // Already connected — nothing to provision.
+    if (json) {
+      printJson(result);
+      return;
+    }
+    console.log(`Already connected: ${result.web_address ?? "(no web address yet)"}`);
+    return;
+  }
+
+  if (!json) console.log("Provisioning...");
+  const run = await pollRun(() => apiFetch<RunDetail>(`/api/v1/runs/${result.run_id}`), {
+    resumeHint: `svcloud runs ${slug}`,
+    quiet: json,
+  });
+
+  if (run.status === "failed") {
+    if (json) {
+      printJson({ run });
+      return;
+    }
+    die(`Provisioning failed: ${run.error?.message ?? "unknown error"}`);
+  }
+
+  const project = await apiFetch<ProjectDetail>(`/api/v1/projects/${result.project_id}`);
+
+  if (json) {
+    printJson({ project, run });
+    return;
+  }
+
+  console.log("");
+  console.log(`Your app is at ${project.web_address ?? "(no web address yet)"} — not live yet.`);
+  console.log(
+    "Open the repo with a coding agent (it'll read SVAGENTS.md and get started), then push.",
+  );
+}

package/src/commands/login.ts

@@ -0,0 +1,88 @@
+/**
+ * `svcloud login` — PLANNING.md §2's flow, steps 1-7, end to end.
+ */
+import { randomBytes } from "node:crypto";
+import { openBrowser } from "../lib/browser";
+import { challengeFromVerifier, generateVerifier } from "../lib/pkce";
+import { apiFetch } from "../lib/api";
+import { CLIENT_ID } from "../lib/config";
+import { saveTokens, type TokenSet } from "../lib/credentials";
+import { getAuthServerMetadata } from "../lib/discovery";
+import { startLoopbackListener } from "../lib/loopback-server";
+import { die } from "../lib/output";
+
+interface TokenResponse {
+  access_token: string;
+  refresh_token: string;
+  expires_in: number;
+  scope: string;
+}
+
+interface Account {
+  email: string;
+  display_name: string | null;
+}
+
+const CODE_TTL_MS = 5 * 60 * 1000;
+
+export async function loginCommand(): Promise<void> {
+  const verifier = generateVerifier();
+  const challenge = challengeFromVerifier(verifier);
+  const state = randomBytes(16).toString("base64url");
+
+  const meta = await getAuthServerMetadata();
+  const listener = await startLoopbackListener();
+  const redirectUri = `http://127.0.0.1:${listener.port}/callback`;
+
+  const authorizeUrl = new URL(meta.authorization_endpoint);
+  authorizeUrl.searchParams.set("response_type", "code");
+  authorizeUrl.searchParams.set("client_id", CLIENT_ID);
+  authorizeUrl.searchParams.set("redirect_uri", redirectUri);
+  authorizeUrl.searchParams.set("code_challenge", challenge);
+  authorizeUrl.searchParams.set("code_challenge_method", "S256");
+  authorizeUrl.searchParams.set("state", state);
+
+  console.log("Opening your browser to sign in to SV Cloud...");
+  console.log(`If it doesn't open, visit:\n  ${authorizeUrl.toString()}`);
+  openBrowser(authorizeUrl.toString());
+
+  let result: Awaited<ReturnType<typeof listener.waitForCallback>>;
+  try {
+    result = await listener.waitForCallback(CODE_TTL_MS);
+  } finally {
+    listener.close();
+  }
+
+  if (result.error || !result.code) {
+    die(`Sign-in didn't finish${result.error ? `: ${result.error}` : "."}`);
+  }
+  if (result.state !== state) {
+    die("Sign-in response didn't match this request. Run `svcloud login` again.");
+  }
+
+  const tokenRes = await fetch(meta.token_endpoint, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      grant_type: "authorization_code",
+      code: result.code,
+      code_verifier: verifier,
+      client_id: CLIENT_ID,
+      redirect_uri: redirectUri,
+    }),
+  });
+  if (!tokenRes.ok) {
+    die("Could not complete sign-in. Run `svcloud login` again.");
+  }
+  const body = (await tokenRes.json()) as TokenResponse;
+  const tokens: TokenSet = {
+    accessToken: body.access_token,
+    refreshToken: body.refresh_token,
+    expiresAt: Date.now() + body.expires_in * 1000,
+    scopes: body.scope.split(" ").filter(Boolean),
+  };
+  await saveTokens(tokens);
+
+  const account = await apiFetch<Account>("/api/v1/auth/me");
+  console.log(`Signed in as ${account.email}.`);
+}

package/src/commands/logout.ts

@@ -0,0 +1,31 @@
+/**
+ * `svcloud logout` — revokes the stored refresh token (which revokes its
+ * paired access token too, per `apps/cloud/src/services/oauth.ts`'s
+ * `revokePair`), then clears local storage either way. RFC 7009: revoking
+ * an already-invalid token is a success, not an error, so a failed network
+ * call still clears local state rather than leaving the user stuck signed
+ * in locally against a session cloud-api no longer honours.
+ */
+import { CLIENT_ID } from "../lib/config";
+import { clearTokens, loadTokens } from "../lib/credentials";
+import { getAuthServerMetadata } from "../lib/discovery";
+
+export async function logoutCommand(): Promise<void> {
+  const tokens = await loadTokens();
+  if (!tokens) {
+    console.log("Already signed out.");
+    return;
+  }
+  try {
+    const meta = await getAuthServerMetadata();
+    await fetch(meta.revocation_endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ token: tokens.refreshToken, client_id: CLIENT_ID }),
+    });
+  } catch {
+    // Best-effort: local state is cleared below regardless.
+  }
+  await clearTokens();
+  console.log("Signed out.");
+}

package/src/commands/mcp.ts

@@ -0,0 +1,185 @@
+/**
+ * `svcloud mcp` — the local MCP bridge (PLANNING.md §1.5, §3.5). An MCP
+ * server toward the coding agent on stdio, an MCP client toward cloud-api's
+ * `POST /mcp` over HTTPS, signed with the session `svcloud login` already
+ * put in the OS keychain. It is a transport, not a second implementation:
+ * the tool registry stays server-side
+ * (`apps/cloud/src/services/mcp/tools.ts`), so a tool change needs no
+ * release here — this file forwards `initialize`/`tools/list`/`tools/call`
+ * and returns exactly what came back.
+ *
+ * Rules, in the order they bite (§3.5):
+ *  1. stdout is JSON-RPC only — every diagnostic goes to stderr. Enforced
+ *     below by rebinding console.log/info for this command's lifetime, so
+ *     a stray call from an imported module can't corrupt the stream too.
+ *  2. Pure pass-through — no caching/re-ordering `tools/list`, no
+ *     unwrapping `untrustedResult()`'s note, no dropping `approximate:
+ *     true`, no turning `isError: true` into a protocol error. Forwarding
+ *     is done with a raw `fetch`, not `lib/api.ts`'s `apiFetch`: `/mcp`
+ *     returns a JSON-RPC body on a 400 (malformed request) exactly as
+ *     often as on a 200 (protocol-level tool error), and `apiFetch`'s
+ *     REST error-envelope parsing would swallow that body instead of
+ *     forwarding it.
+ *  3. Notifications (no `id`) are consumed locally, never forwarded and
+ *     never answered — the remote is a stateless request/response
+ *     endpoint with nothing to notify.
+ *  4. Concurrency by id — each request is its own fetch, launched without
+ *     awaiting the previous one, so a slow `tools/call` never blocks the
+ *     next line read from stdin.
+ *  5. Auth failures do not open a browser. With no stored session, answer
+ *     the request in-band and keep serving; the moment a `svcloud login`
+ *     lands elsewhere, the next call works.
+ *  6. Refresh is shared and racy — handled once, in `lib/api.ts`
+ *     (`currentAccessToken`/`forceRefreshAccessToken`), not duplicated
+ *     here.
+ *  7. Transport failure (a timeout, a 502, a dropped connection) is a
+ *     per-request JSON-RPC error, not a crash — the process keeps serving.
+ *  8. Log metadata, never payloads — tool results carry attacker-writable
+ *     text (log lines, database rows).
+ */
+import { createInterface } from "node:readline";
+import { AuthRequiredError, currentAccessToken, forceRefreshAccessToken } from "../lib/api";
+import { apiBaseUrl } from "../lib/config";
+import { loadTokens } from "../lib/credentials";
+
+type JsonRpcId = string | number | null;
+
+const NOT_SIGNED_IN_MESSAGE = "Not signed in to SV Cloud; the owner needs to run `svcloud login`.";
+
+function stderrLine(line: string): void {
+  process.stderr.write(`${line}\n`);
+}
+
+function writeLine(payload: unknown): void {
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+
+function jsonRpcError(id: JsonRpcId, message: string): { jsonrpc: "2.0"; id: JsonRpcId; error: { code: number; message: string } } {
+  // -32000 is JSON-RPC's reserved "server error" range start — these are
+  // local bridge failures (auth, transport), distinct from the protocol
+  // errors (-326xx) the remote itself returns and that pass straight
+  // through untouched.
+  return { jsonrpc: "2.0", id, error: { code: -32000, message } };
+}
+
+/** A JSON-RPC request with no `id` is a notification. A non-object line still gets `id: null` so it can receive an error reply. */
+function readEnvelope(msg: unknown): { isNotification: boolean; id: JsonRpcId; method: string } {
+  if (typeof msg !== "object" || msg === null) return { isNotification: false, id: null, method: "?" };
+  const rec = msg as Record<string, unknown>;
+  const method = typeof rec.method === "string" ? rec.method : "?";
+  if (rec.id === undefined) return { isNotification: true, id: null, method };
+  return { isNotification: false, id: rec.id as JsonRpcId, method };
+}
+
+let warnedNotSignedIn = false;
+
+function warnNotSignedInOnce(): void {
+  if (warnedNotSignedIn) return;
+  warnedNotSignedIn = true;
+  stderrLine(NOT_SIGNED_IN_MESSAGE);
+}
+
+type RemoteResult =
+  | { ok: true; body: unknown }
+  | { ok: false; reason: "auth" }
+  | { ok: false; reason: "transport"; detail: string };
+
+/** One request to `POST /mcp`, refreshing once on a 401, whatever the eventual status. Never throws. */
+async function callRemote(msg: unknown): Promise<RemoteResult> {
+  let accessToken: string;
+  try {
+    accessToken = await currentAccessToken();
+  } catch (err) {
+    if (err instanceof AuthRequiredError) return { ok: false, reason: "auth" };
+    return { ok: false, reason: "transport", detail: err instanceof Error ? err.message : String(err) };
+  }
+
+  const post = (token: string) =>
+    fetch(`${apiBaseUrl()}/mcp`, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+      body: JSON.stringify(msg),
+    });
+
+  let res: Response;
+  try {
+    res = await post(accessToken);
+    if (res.status === 401) {
+      let refreshed: string;
+      try {
+        refreshed = await forceRefreshAccessToken();
+      } catch (err) {
+        if (err instanceof AuthRequiredError) return { ok: false, reason: "auth" };
+        return { ok: false, reason: "transport", detail: err instanceof Error ? err.message : String(err) };
+      }
+      res = await post(refreshed);
+    }
+  } catch (err) {
+    return { ok: false, reason: "transport", detail: err instanceof Error ? err.message : String(err) };
+  }
+
+  try {
+    return { ok: true, body: await res.json() };
+  } catch {
+    return { ok: false, reason: "transport", detail: `unexpected response (status ${res.status})` };
+  }
+}
+
+async function forwardToRemote(msg: unknown, id: JsonRpcId, method: string): Promise<void> {
+  const result = await callRemote(msg);
+  if (result.ok) {
+    writeLine(result.body); // rule 2 — verbatim, whatever shape it is.
+    return;
+  }
+  if (result.reason === "auth") {
+    warnNotSignedInOnce();
+    writeLine(jsonRpcError(id, NOT_SIGNED_IN_MESSAGE));
+    return;
+  }
+  stderrLine(`mcp: transport error on ${method} (id ${String(id)}): ${result.detail}`);
+  writeLine(jsonRpcError(id, "SV Cloud request failed. Try again."));
+}
+
+/** Best-effort startup diagnostic (PLANNING.md §3.6) — never blocks serving. */
+async function logStartupState(): Promise<void> {
+  const tokens = await loadTokens();
+  if (!tokens) {
+    stderrLine(`svcloud mcp: ${NOT_SIGNED_IN_MESSAGE}`);
+    return;
+  }
+  stderrLine(`svcloud mcp: signed in, ${tokens.scopes.length} scopes.`);
+  const result = await callRemote({ jsonrpc: "2.0", id: "__svcloud_mcp_startup__", method: "tools/list", params: {} });
+  if (result.ok) {
+    const body = result.body as { result?: { tools?: unknown[] } };
+    const count = body.result?.tools?.length;
+    if (typeof count === "number") stderrLine(`svcloud mcp: ${count} tools visible to this token.`);
+  }
+}
+
+export async function mcpCommand(): Promise<void> {
+  // Rule 1: stdout is JSON-RPC only. Nothing in this command's own code
+  // calls console.log, but rebinding here means an imported module doing
+  // so can't corrupt the stream either.
+  console.log = (...args: unknown[]) => stderrLine(args.map(String).join(" "));
+  console.info = console.log;
+
+  await logStartupState();
+
+  const rl = createInterface({ input: process.stdin, terminal: false });
+  rl.on("line", (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let msg: unknown;
+    try {
+      msg = JSON.parse(trimmed);
+    } catch {
+      stderrLine("mcp: dropped a non-JSON line from stdin.");
+      return;
+    }
+    const { isNotification, id, method } = readEnvelope(msg);
+    if (isNotification) return; // rule 3.
+    void forwardToRemote(msg, id, method); // rule 4 — fire and forget, matched by id.
+  });
+
+  await new Promise<void>((resolve) => rl.on("close", resolve));
+}

package/src/commands/open.ts

@@ -0,0 +1,25 @@
+/**
+ * `svcloud open <slug>` — PLANNING.md §3.1: no endpoint of its own, just
+ * `GET /projects?slug=` and the row's `web_address`.
+ */
+import { openBrowser } from "../lib/browser";
+import { findProjectBySlug } from "../lib/find-project";
+import { die, printJson } from "../lib/output";
+
+export async function openCommand(slug: string | undefined, json: boolean): Promise<void> {
+  if (!slug) {
+    die("Usage: svcloud open <app>\nRun `svcloud projects list` to see your apps.");
+  }
+
+  const project = await findProjectBySlug(slug);
+  if (!project) die(`No app named "${slug}".`);
+  if (!project.web_address) die(`"${slug}" doesn't have a web address yet.`);
+
+  if (json) {
+    printJson({ web_address: project.web_address });
+    return;
+  }
+
+  console.log(`Opening ${project.web_address}`);
+  openBrowser(project.web_address);
+}

package/src/commands/projects.ts

@@ -0,0 +1,33 @@
+/**
+ * `svcloud projects list` — PLANNING.md §3.1: "falls out of status for free."
+ */
+import type { ProjectSummary } from "@sv/cloud-contracts";
+import { apiFetch } from "../lib/api";
+import { die, printJson, printTable } from "../lib/output";
+
+export async function projectsCommand(subcommand: string | undefined, json: boolean): Promise<void> {
+  if (subcommand !== "list") {
+    die(`Usage: svcloud projects list${subcommand ? `\nUnknown subcommand: ${subcommand}` : ""}`);
+  }
+
+  const { projects } = await apiFetch<{ projects: ProjectSummary[] }>("/api/v1/projects");
+
+  if (json) {
+    printJson(projects);
+    return;
+  }
+
+  printTable(
+    projects.map((p) => ({
+      App: p.name,
+      // status and open take the SLUG, not the name shown in the App column
+      // (they resolve it via GET /projects?slug=) - without this column,
+      // "my-app" vs "My App" was a silent lookup failure the table gave no
+      // way to debug.
+      Slug: p.slug,
+      "Web address": p.web_address ?? "(none yet)",
+      Status: p.needs_initialization ? "setting up" : (p.latest_deploy_status ?? p.status),
+    })),
+    ["App", "Slug", "Web address", "Status"],
+  );
+}

package/src/commands/runs.ts

@@ -0,0 +1,69 @@
+/**
+ * `svcloud runs <app>` — PLANNING.md §3.1/§4 Step 3. Watches or reads a
+ * provision/teardown run. `--id` reads `GET /runs/:id` directly and never
+ * touches `/projects` — that route is deliberately not nested under a
+ * project, since a rolled-back connect deletes the `projects` row but the
+ * run explaining why must still be readable.
+ */
+import type { RunDetail } from "@sv/cloud-contracts";
+import { apiFetch } from "../lib/api";
+import { findProjectBySlug } from "../lib/find-project";
+import { die, hasFlag, printJson, printTable, takeOption } from "../lib/output";
+import { pollRun } from "../lib/run-poll";
+
+function printSnapshot(run: RunDetail): void {
+  console.log(`Run ${run.id} — ${run.kind} — ${run.status}`);
+  printTable(
+    run.steps.map((s) => ({ Step: s.label, Status: s.status })),
+    ["Step", "Status"],
+  );
+  if (run.status === "failed" && run.error) {
+    console.log(`Error: ${run.error.message ?? run.error.code ?? "unknown error"}`);
+  }
+}
+
+function printFinal(run: RunDetail): void {
+  if (run.status === "failed") {
+    console.log(`Run failed: ${run.error?.message ?? "unknown error"}`);
+    return;
+  }
+  console.log(`Run ${run.status}.`);
+}
+
+export async function runsCommand(argv: string[], json: boolean): Promise<void> {
+  const idOpt = takeOption(argv, "id");
+  const { present: watch, rest } = hasFlag(idOpt.rest, "watch");
+  const slug = rest[0];
+
+  let fetchRun: () => Promise<RunDetail>;
+  let resumeHint: string;
+
+  if (idOpt.value) {
+    const runId = idOpt.value;
+    fetchRun = () => apiFetch<RunDetail>(`/api/v1/runs/${runId}`);
+    resumeHint = `svcloud runs --id ${runId}`;
+  } else {
+    if (!slug) die("Usage: svcloud runs <app> [--id <run-id>] [--watch]");
+    const project = await findProjectBySlug(slug);
+    if (!project) die(`No app named "${slug}".`);
+    fetchRun = () => apiFetch<RunDetail>(`/api/v1/projects/${project.id}/runs/latest`);
+    resumeHint = `svcloud runs ${slug}`;
+  }
+
+  if (!watch) {
+    const run = await fetchRun();
+    if (json) {
+      printJson(run);
+      return;
+    }
+    printSnapshot(run);
+    return;
+  }
+
+  const run = await pollRun(fetchRun, { resumeHint, quiet: json });
+  if (json) {
+    printJson(run);
+    return;
+  }
+  printFinal(run);
+}