svcloud 0.1.0-alpha.3

package/src/commands/secrets.ts

@@ -0,0 +1,89 @@
+/**
+ * `svcloud secrets` — PLANNING.md §4 Step 5. F10 "keys & settings" is
+ * zero-knowledge (`apps/cloud/src/routes/secrets.ts`'s file header): a value
+ * is written straight to the app's runtime and never stored or returned by
+ * `cloud-api` again. `list` therefore only ever shows names — there is no
+ * `svcloud secrets get`, by design, not an oversight.
+ */
+import { apiFetch } from "../lib/api";
+import { findProjectBySlug } from "../lib/find-project";
+import { die, printJson, printTable } from "../lib/output";
+import { isInteractive } from "../lib/prompt";
+
+const USAGE = `Usage:
+  svcloud secrets list <app>
+  svcloud secrets set <app> <key> [value]   Reads from stdin if value is omitted
+  svcloud secrets remove <app> <key>`;
+
+async function resolveProjectId(slug: string | undefined): Promise<string> {
+  if (!slug) die(USAGE);
+  const project = await findProjectBySlug(slug);
+  if (!project) die(`No app named "${slug}".`);
+  return project.id;
+}
+
+/** A value typed directly on the command line lands in shell history and `ps` output — reading from stdin avoids that. */
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+  return Buffer.concat(chunks).toString("utf8").replace(/\r?\n$/, "");
+}
+
+export async function secretsCommand(argv: string[], json: boolean): Promise<void> {
+  const [subcommand, ...rest] = argv;
+
+  switch (subcommand) {
+    case "list": {
+      const projectId = await resolveProjectId(rest[0]);
+      const { keys } = await apiFetch<{ keys: string[] }>(
+        `/api/v1/projects/${projectId}/settings`,
+      );
+      if (json) {
+        printJson(keys);
+        return;
+      }
+      printTable(
+        keys.map((key) => ({ Key: key })),
+        ["Key"],
+      );
+      return;
+    }
+    case "set": {
+      const [slug, key, inlineValue] = rest;
+      if (!key) die(USAGE);
+      const projectId = await resolveProjectId(slug);
+      let value = inlineValue;
+      if (value === undefined) {
+        if (isInteractive() && !json) console.error(`Enter value for "${key}", then press Ctrl-D:`);
+        value = await readStdin();
+      }
+      if (!value) die('Value must be a non-empty string.');
+      await apiFetch(`/api/v1/projects/${projectId}/settings/${encodeURIComponent(key)}`, {
+        method: "PUT",
+        body: { value },
+      });
+      if (json) {
+        printJson({ key, set: true });
+        return;
+      }
+      console.log(`Set "${key}".`);
+      return;
+    }
+    case "remove": {
+      const [slug, key] = rest;
+      if (!key) die(USAGE);
+      const projectId = await resolveProjectId(slug);
+      await apiFetch(`/api/v1/projects/${projectId}/settings/${encodeURIComponent(key)}`, {
+        method: "DELETE",
+      });
+      if (json) {
+        printJson({ key, removed: true });
+        return;
+      }
+      console.log(`Removed "${key}".`);
+      return;
+    }
+    default:
+      die(USAGE);
+  }
+}

package/src/commands/status.ts

@@ -0,0 +1,36 @@
+/**
+ * `svcloud status <slug>` — PLANNING.md §3.1: render the health endpoint's
+ * plain-language traffic light as-is, don't re-word it.
+ */
+import { findProjectBySlug } from "../lib/find-project";
+import { apiFetch } from "../lib/api";
+import { die, printJson } from "../lib/output";
+
+interface Health {
+  status: "green" | "yellow" | "red" | string;
+  message: string;
+  updated_at: string;
+}
+
+export async function statusCommand(slug: string | undefined, json: boolean): Promise<void> {
+  if (!slug) {
+    die("Usage: svcloud status <app>\nRun `svcloud projects list` to see your apps.");
+  }
+
+  const project = await findProjectBySlug(slug);
+  if (!project) die(`No app named "${slug}".`);
+
+  const health = await apiFetch<Health>(`/api/v1/projects/${project.id}/health`);
+
+  if (json) {
+    printJson({ ...project, health });
+    return;
+  }
+
+  console.log(project.name);
+  console.log(`  ${project.web_address ?? "(no web address yet)"}`);
+  console.log(`  ${health.message}`);
+  if (project.needs_initialization) {
+    console.log("  This app hasn't finished setting up yet.");
+  }
+}

package/src/commands/whoami.ts

@@ -0,0 +1,26 @@
+/**
+ * `svcloud whoami` — after `login`, nothing else showed which account was
+ * signed in. `GET /auth/me` already exists (cloud-web's AppShell auth guard
+ * uses it the same way); this just exposes it.
+ */
+import { apiFetch } from "../lib/api";
+import { printJson } from "../lib/output";
+
+interface Account {
+  id: string;
+  email: string;
+  display_name: string | null;
+  mode: "simple" | "advanced";
+  created_at: string;
+}
+
+export async function whoamiCommand(json: boolean): Promise<void> {
+  const account = await apiFetch<Account>("/api/v1/auth/me");
+
+  if (json) {
+    printJson(account);
+    return;
+  }
+
+  console.log(account.display_name ? `${account.display_name} <${account.email}>` : account.email);
+}

package/src/index.ts

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * Argument parsing and command dispatch — PLANNING.md §4 Step 1:
+ * `login`, `logout`, `whoami`, `status`, `open`, `projects list`.
+ * Hand-rolled rather than a dependency: six commands, one global flag, no
+ * subcommand ambiguity worth a parser library yet.
+ */
+import { dbCommand } from "./commands/db";
+import { deployCommand } from "./commands/deploy";
+import { initCommand } from "./commands/init";
+import { loginCommand } from "./commands/login";
+import { logoutCommand } from "./commands/logout";
+import { mcpCommand } from "./commands/mcp";
+import { openCommand } from "./commands/open";
+import { projectsCommand } from "./commands/projects";
+import { runsCommand } from "./commands/runs";
+import { secretsCommand } from "./commands/secrets";
+import { statusCommand } from "./commands/status";
+import { whoamiCommand } from "./commands/whoami";
+import { AuthRequiredError, ApiError } from "./lib/api";
+import { hasFlag } from "./lib/output";
+
+const USAGE = `svcloud — the SV Cloud CLI
+
+Usage:
+  svcloud login                 Sign in to SV Cloud
+  svcloud logout                Sign out
+  svcloud whoami                Show the signed-in account
+  svcloud status <app>          Show an app's health
+  svcloud open <app>            Open an app's web address in your browser
+  svcloud projects list         List your apps
+  svcloud init                  Connect a local repo as a new app
+  svcloud runs <app>            Show or watch an app's provisioning run
+  svcloud secrets <cmd>         Manage an app's keys & settings (list/set/remove)
+  svcloud db <cmd>              Browse and edit an app's database (see 'svcloud db' for subcommands)
+  svcloud deploy <app>          Push the current branch and watch the build (must be the app's default branch)
+  svcloud mcp                   Run the local MCP bridge (for a coding agent's harness config)
+
+Flags:
+  --json                        Machine-readable output, on every read command
+  --repo, --name, --slug, --installation, --id, --watch, --limit, --primary-key, --default
+                                 See each command's own usage
+`;
+
+async function main(): Promise<void> {
+  const { present: json, rest: argv } = hasFlag(process.argv.slice(2), "json");
+  const [command, ...rest] = argv;
+
+  switch (command) {
+    case "login":
+      await loginCommand();
+      return;
+    case "logout":
+      await logoutCommand();
+      return;
+    case "whoami":
+      await whoamiCommand(json);
+      return;
+    case "status":
+      await statusCommand(rest[0], json);
+      return;
+    case "open":
+      await openCommand(rest[0], json);
+      return;
+    case "projects":
+      await projectsCommand(rest[0], json);
+      return;
+    case "mcp":
+      await mcpCommand();
+      return;
+    case "init":
+      await initCommand(rest, json);
+      return;
+    case "runs":
+      await runsCommand(rest, json);
+      return;
+    case "secrets":
+      await secretsCommand(rest, json);
+      return;
+    case "db":
+      await dbCommand(rest, json);
+      return;
+    case "deploy":
+      await deployCommand(rest, json);
+      return;
+    case undefined:
+    case "-h":
+    case "--help":
+      console.log(USAGE);
+      return;
+    default:
+      console.error(`Unknown command: ${command}\n`);
+      console.log(USAGE);
+      process.exit(1);
+  }
+}
+
+main().catch((err: unknown) => {
+  if (err instanceof AuthRequiredError) {
+    console.error(err.message);
+  } else if (err instanceof ApiError) {
+    console.error(err.message);
+  } else {
+    console.error(err instanceof Error ? err.message : String(err));
+  }
+  process.exit(1);
+});

package/src/lib/api.ts

@@ -0,0 +1,183 @@
+/**
+ * The one place that talks to cloud-api over HTTP — mirrors
+ * `apps/cloud-web/src/lib/http.ts`'s shape deliberately (same error
+ * envelope, same idea of one fetch wrapper) so the two clients don't drift
+ * in how they read the same API.
+ *
+ * Adds the one thing a long-lived CLI process needs that a browser tab
+ * doesn't: transparent access-token refresh. A browser session dies with the
+ * tab; a `svcloud status` run tomorrow has to notice its access token from
+ * yesterday expired and refresh before failing.
+ *
+ * `currentAccessToken`/`forceRefreshAccessToken` are exported for
+ * `commands/mcp.ts` (PLANNING.md §3.5): the bridge talks to `/mcp` directly
+ * with a raw `fetch` rather than through `apiFetch`, since `/mcp` returns
+ * JSON-RPC bodies on non-2xx statuses that must be forwarded verbatim, not
+ * parsed as this file's REST error envelope. Both surfaces share the same
+ * token/refresh path so there is exactly one place that talks to the token
+ * endpoint.
+ */
+import { apiBaseUrl, CLIENT_ID } from "./config";
+import { clearTokens, loadTokens, saveTokens, type TokenSet } from "./credentials";
+import { getAuthServerMetadata } from "./discovery";
+
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    readonly code: string,
+    readonly status: number,
+  ) {
+    super(message);
+    this.name = "ApiError";
+  }
+}
+
+/** Thrown when there is no usable session at all — the command should tell the user to run `svcloud login`. */
+export class AuthRequiredError extends Error {
+  constructor() {
+    super("Not signed in. Run `svcloud login` first.");
+    this.name = "AuthRequiredError";
+  }
+}
+
+interface ErrorEnvelope {
+  error: { code: string; message: string; details?: Record<string, unknown> };
+  request_id: string;
+}
+
+// Refresh a little before the real expiry so a request never races it.
+const EXPIRY_SKEW_MS = 30_000;
+
+async function refreshRequest(refreshToken: string): Promise<TokenSet> {
+  const meta = await getAuthServerMetadata();
+  const res = await fetch(meta.token_endpoint, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      grant_type: "refresh_token",
+      refresh_token: refreshToken,
+      client_id: CLIENT_ID,
+    }),
+  });
+  if (!res.ok) {
+    await clearTokens();
+    throw new AuthRequiredError();
+  }
+  const body = (await res.json()) as {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+    scope: string;
+  };
+  const next: TokenSet = {
+    accessToken: body.access_token,
+    refreshToken: body.refresh_token,
+    expiresAt: Date.now() + body.expires_in * 1000,
+    scopes: body.scope.split(" ").filter(Boolean),
+  };
+  await saveTokens(next);
+  return next;
+}
+
+/**
+ * Single-flight, cross-request refresh (PLANNING.md §3.5 rule 6 — "the
+ * bridge and a human running `svcloud status` use the same keychain entry.
+ * On a 401, re-read the store before refreshing (another process may have
+ * already rotated it), refresh once, retry once, then fail"). Refresh
+ * tokens rotate server-side on every use (`services/oauth.ts`'s
+ * `refreshTokenGrant` revokes the pair it consumes), so two concurrent
+ * refreshes racing the same stored refresh token is not a slow path, it's a
+ * bug: the loser gets `OAUTH_INVALID_GRANT` and would otherwise clear a
+ * perfectly good session out from under the winner. The bridge's concurrent
+ * `tools/call`s are exactly the case that triggers this.
+ *
+ * `staleToken` is what the caller was using when it decided a refresh was
+ * needed. Re-reading disk first means a refresh already completed by
+ * another in-flight call (in this process, via the dedupe below, or in a
+ * sibling `svcloud` process) is picked up instead of triggering a second,
+ * doomed refresh.
+ */
+let refreshInFlight: Promise<TokenSet> | undefined;
+
+async function refreshOnce(staleToken: TokenSet): Promise<TokenSet> {
+  if (refreshInFlight) return refreshInFlight;
+  refreshInFlight = (async () => {
+    const onDisk = await loadTokens();
+    if (onDisk && onDisk.refreshToken !== staleToken.refreshToken) return onDisk;
+    return refreshRequest((onDisk ?? staleToken).refreshToken);
+  })();
+  try {
+    return await refreshInFlight;
+  } finally {
+    refreshInFlight = undefined;
+  }
+}
+
+/** The current access token, refreshing first if it's expired or about to be. */
+export async function currentAccessToken(): Promise<string> {
+  const tokens = await loadTokens();
+  if (!tokens) throw new AuthRequiredError();
+  if (Date.now() < tokens.expiresAt - EXPIRY_SKEW_MS) return tokens.accessToken;
+  return (await refreshOnce(tokens)).accessToken;
+}
+
+/** Forces a refresh regardless of the stored expiry — for a 401 the local clock didn't see coming. */
+export async function forceRefreshAccessToken(): Promise<string> {
+  const tokens = await loadTokens();
+  if (!tokens) throw new AuthRequiredError();
+  return (await refreshOnce(tokens)).accessToken;
+}
+
+export interface ApiFetchOptions {
+  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  body?: unknown;
+  /** Only `login`'s own calls (discovery, token exchange) need this — everything else requires a session. */
+  unauthenticated?: boolean;
+}
+
+export async function apiFetch<T>(path: string, options: ApiFetchOptions = {}): Promise<T> {
+  const headers: Record<string, string> = {};
+  if (options.body !== undefined) headers["content-type"] = "application/json";
+  if (!options.unauthenticated) {
+    headers.authorization = `Bearer ${await currentAccessToken()}`;
+  }
+
+  const doFetch = () =>
+    fetch(`${apiBaseUrl()}${path}`, {
+      method: options.method ?? "GET",
+      headers,
+      body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+    });
+
+  let res = await doFetch();
+
+  // One retry after a forced refresh: covers a token cloud-api revoked
+  // early (e.g. `svcloud logout` run from another shell) that our own
+  // expiry clock didn't yet know about.
+  if (res.status === 401 && !options.unauthenticated) {
+    headers.authorization = `Bearer ${await forceRefreshAccessToken()}`;
+    res = await doFetch();
+  }
+
+  if (res.status === 204) return undefined as T;
+
+  if (!res.ok) {
+    let envelope: ErrorEnvelope | undefined;
+    try {
+      envelope = (await res.json()) as ErrorEnvelope;
+    } catch {
+      // A non-JSON error body (e.g. a 502 in front of the Worker) still surfaces as a plain ApiError below.
+    }
+    if (res.status === 401 && !options.unauthenticated) {
+      await clearTokens();
+      throw new AuthRequiredError();
+    }
+    throw new ApiError(
+      envelope?.error.message ?? `Request failed (${res.status}).`,
+      envelope?.error.code ?? "unknown_error",
+      res.status,
+    );
+  }
+
+  return (await res.json()) as T;
+}

package/src/lib/browser.ts

@@ -0,0 +1,22 @@
+/**
+ * Best-effort "open a URL in the default browser". The CLI's audience
+ * pairs with a coding agent shelling out to it, so a failure here (no
+ * display, no default browser registered) must never block the command —
+ * the URL is always printed too, and the caller decides whether that's
+ * enough.
+ */
+import { spawn } from "node:child_process";
+
+export function openBrowser(url: string): void {
+  try {
+    if (process.platform === "darwin") {
+      spawn("open", [url], { stdio: "ignore", detached: true }).unref();
+    } else if (process.platform === "win32") {
+      spawn("cmd", ["/c", "start", '""', url], { stdio: "ignore", detached: true }).unref();
+    } else {
+      spawn("xdg-open", [url], { stdio: "ignore", detached: true }).unref();
+    }
+  } catch {
+    // The printed URL is the fallback; nothing else to do here.
+  }
+}

package/src/lib/config.ts

@@ -0,0 +1,15 @@
+/**
+ * Constants shared by every command. `SVCLOUD_API_URL` is the one env
+ * override, for pointing the CLI at a local `wrangler dev` instance while
+ * building it — production has no reason to ever set it.
+ */
+
+export const CLIENT_ID = "svcloud-cli";
+
+export function apiBaseUrl(): string {
+  return process.env.SVCLOUD_API_URL ?? "https://api.cloud.sv-academy.org";
+}
+
+/** Service/account names the credential store (lib/credentials.ts) files this CLI's token set under. */
+export const CREDENTIAL_SERVICE = "svcloud-cli";
+export const CREDENTIAL_ACCOUNT = "default";