svcloud 0.1.0-alpha.3

package/README.md

@@ -0,0 +1,181 @@
+# svcloud
+
+The command-line interface for [SV Cloud](https://cloud.sv-academy.org) — and
+the way an AI coding agent reaches the platform.
+
+> **Alpha.** Sign-in, status, app listing, the `mcp` bridge, and `init`
+> (below) are built — see Commands for the full current list. `logs`,
+> `deploy`, `secrets`, `db`, and `dev` are still on the way. Published under
+> the `alpha` dist-tag, not `latest`.
+
+## Install
+
+```bash
+npx svcloud@alpha login
+```
+
+Or install it:
+
+```bash
+npm install -g svcloud@alpha
+svcloud login
+```
+
+`login` opens your browser to sign in, then stores your session in your
+system's keychain (Keychain on macOS; Secret Service on Linux; Credential
+Manager on Windows — falling back to a local file, with a warning, if none
+of those is available).
+
+## Commands
+
+```
+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 repo (defaults to the one in your working directory) as a new app
+svcloud runs <app>            Show or watch an app's provisioning run
+svcloud mcp                   Run the local MCP bridge (for a coding agent's harness config)
+
+Flags:
+  --json                      Machine-readable output, on every read command
+```
+
+`init` reads `--repo <owner/name>`, `--name`, `--slug`, and `--installation`
+to skip what it would otherwise infer or ask about; `runs` reads `--id
+<run-id>` (read a specific run instead of an app's latest) and `--watch`
+(follow it to completion). Neither needs any of that in the common case:
+`cd` into your repo and run `svcloud init`.
+
+More commands (`logs`, `deploy`, `secrets`, `db`, `dev`) are on the way.
+
+## Connect your coding agent
+
+`svcloud mcp` runs a local MCP server that your coding agent — Antigravity,
+Gemini CLI, Cursor, Claude Code, OpenCode, Codex, or anything else that speaks
+MCP — connects to over stdio. It signs every request with the session you
+created with `svcloud login` and forwards it to SV Cloud, so your agent can list
+your apps, read errors, check a deploy, and work with your database without you
+pasting anything into it.
+
+First, sign in on your machine:
+
+```bash
+svcloud login
+```
+
+Then configure your agent:
+
+### Antigravity
+Add to `~/.gemini/config/mcp_config.json` (global) or `.agents/mcp_config.json` (workspace):
+
+```json
+{
+  "mcpServers": {
+    "svcloud": {
+      "command": "npx",
+      "args": ["-y", "svcloud@alpha", "mcp"]
+    }
+  }
+}
+```
+
+### Gemini CLI
+```bash
+gemini mcp add svcloud -- npx -y svcloud@alpha mcp
+```
+Or add the `svcloud` block under `mcpServers` in `~/.gemini/config.json` or `~/.gemini/mcp_config.json`.
+
+### Cursor
+Go to **Settings** > **Features** > **MCP** > **Add New MCP Server**:
+- **Name:** `svcloud`
+- **Type:** `command`
+- **Command:** `npx -y svcloud@alpha mcp`
+
+Or add directly to `.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "svcloud": {
+      "command": "npx",
+      "args": ["-y", "svcloud@alpha", "mcp"]
+    }
+  }
+}
+```
+
+### OpenCode
+In `~/.config/opencode/mcp.json` or your OpenCode configuration:
+```json
+{
+  "mcpServers": {
+    "svcloud": {
+      "command": "npx",
+      "args": ["-y", "svcloud@alpha", "mcp"]
+    }
+  }
+}
+```
+
+### Claude Code
+```bash
+claude mcp add svcloud -- npx -y svcloud@alpha mcp
+```
+
+### Codex
+In `~/.codex/config.json` or your Codex MCP settings:
+```json
+{
+  "mcpServers": {
+    "svcloud": {
+      "command": "npx",
+      "args": ["-y", "svcloud@alpha", "mcp"]
+    }
+  }
+}
+```
+
+### Other MCP harnesses
+In any harness or configuration file that accepts an `mcpServers` block:
+
+```jsonc
+{ "svcloud": { "command": "npx", "args": ["-y", "svcloud@alpha", "mcp"] } }
+```
+
+Your agent never sees your token and never has to sign in on its own. Signing
+out (`svcloud logout`) cuts its access off too.
+
+For an agent you use every day, install it rather than running it through
+`npx`: an installed `svcloud` starts instantly, works offline, and only changes
+version when you ask it to.
+
+```jsonc
+{ "svcloud": { "command": "svcloud", "args": ["mcp"] } }
+```
+
+### Upgrading
+
+```bash
+npm install -g svcloud@alpha
+```
+
+Your agent picks up the new version the next time it starts — restart the MCP
+server (or the harness) after upgrading.
+
+You will rarely need to. What SV Cloud can do for your agent is decided on our
+side, not by your installed version, so new capabilities show up without an
+upgrade. If a version ever *is* required, the error message will say so.
+
+One thing an upgrade does not change: what your agent is allowed to do is fixed
+at the moment you sign in. If we widen what the CLI can be granted, run
+`svcloud login` again to pick it up — a stale session keeps the narrower tool
+list no matter how new your CLI is, since scopes are frozen at sign-in, not
+re-checked against the current defaults. (**2026-08-25:** we just did this —
+run `svcloud login` again to see the full tool list, including database and
+settings tools that were previously invisible to the bridge.)
+
+A harness that can run its own OAuth flow (a hosted agent, not one running on
+your machine) can also talk to SV Cloud directly at
+`https://api.cloud.sv-academy.org/mcp` instead of through this bridge.

package/bin/svcloud.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * `npx svcloud`'s actual entry point. Plain JS, no type stripping needed for
+ * this file itself: its only job is to run `src/index.ts` under `tsx`
+ * (a real dependency, not dev-only, since this is what a consumer with no
+ * build step runs). PLANNING.md §5 leaves a compiled/bundled build for
+ * later ("the option of a single-file binary later") — this is what makes
+ * `npx svcloud` work without one in the meantime.
+ *
+ * `--import` takes a bare specifier ("tsx") Node resolves as if requiring
+ * it from the CURRENT WORKING DIRECTORY — not from this file's own
+ * location. Found while building `init` (PLANNING.md §4 Step 3), the first
+ * command whose whole point is running from the owner's own project
+ * directory rather than from inside this package: from anywhere without a
+ * `tsx` reachable via cwd-based resolution (i.e. almost anywhere a real
+ * user runs `svcloud`), every command failed with `ERR_MODULE_NOT_FOUND`.
+ * `import.meta.resolve` fixes it by resolving `tsx` against THIS file's own
+ * location instead, since it ships as a real (non-dev) dependency right
+ * next to it. The child process's own `cwd` is left alone — commands like
+ * `init` read `process.cwd()` themselves and must see the owner's real
+ * working directory, not this package's.
+ */
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const entry = path.join(here, "..", "src", "index.ts");
+const tsxLoader = import.meta.resolve("tsx");
+
+const child = spawn(process.execPath, ["--import", tsxLoader, entry, ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+child.on("exit", (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 0);
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "svcloud",
+  "version": "0.1.0-alpha.3",
+  "description": "The SV Cloud CLI. Alpha: login, logout, status, open, projects list, mcp, init, and runs are built; see PLANNING.md for what's still missing.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "bin": {
+    "svcloud": "./bin/svcloud.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "dependencies": {
+    "tsx": "^4.20.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.0",
+    "typescript": "^5.9.3",
+    "@sv/cloud-contracts": "0.0.0"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts"
+  }
+}

package/src/commands/db.ts

@@ -0,0 +1,243 @@
+/**
+ * `svcloud db` — PLANNING.md §4 Step 5. Mirrors F8's row editor
+ * (`apps/cloud/src/routes/database.ts`) plus the two DDL routes added
+ * alongside this command (`create_table`/`run_migration`, previously
+ * MCP-tool-only — see that file's header). Cell/column payloads are taken as
+ * JSON on the command line rather than a flag-per-field grammar: the primary
+ * caller for structured data like this is a coding agent, and it goes
+ * through `svcloud mcp`'s tools directly (`lib/prompt.ts`'s header), not this
+ * command — this path exists for a human or a script at a real terminal.
+ */
+import { apiFetch } from "../lib/api";
+import { findProjectBySlug } from "../lib/find-project";
+import { die, printJson, printTable, takeOption } from "../lib/output";
+
+const USAGE = `Usage:
+  svcloud db tables <app>
+  svcloud db rows <app> <table> [--limit N]
+  svcloud db insert <app> <table> <cells-json>
+  svcloud db update <app> <table> <row-id> <cells-json>
+  svcloud db delete <app> <table> <row-id>
+  svcloud db create-table <app> <table> <columns-json> --primary-key <name>
+  svcloud db migrate <app> <table> <column-json> [--default <value>]
+
+<cells-json> is a JSON object, e.g. '{"title":"Hello"}'
+<columns-json> is a JSON array, e.g. '[{"name":"id","type":"uuid","nullable":false},{"name":"title","type":"text"}]'
+<column-json> is a single column, e.g. '{"name":"count","type":"number","nullable":false}'
+Column types: text, number, boolean, timestamp, json, uuid`;
+
+interface DbColumn {
+  name: string;
+  type: string;
+  nullable: boolean;
+  primary_key: boolean;
+}
+
+interface DbTable {
+  name: string;
+  row_count: number;
+  editable: boolean;
+  not_editable_reason: string | null;
+}
+
+interface DbRow {
+  id: string;
+  cells: Record<string, unknown>;
+}
+
+interface RowsPage {
+  columns: DbColumn[];
+  rows: DbRow[];
+  truncated: boolean;
+  editable: boolean;
+  not_editable_reason: string | null;
+}
+
+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;
+}
+
+function parseJsonArg<T>(raw: string | undefined, label: string): T {
+  if (raw === undefined) die(USAGE);
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    die(`${label} must be valid JSON.`);
+  }
+}
+
+function parseDefaultValue(raw: string): string | number | boolean | null {
+  try {
+    const parsed = JSON.parse(raw);
+    if (
+      parsed === null ||
+      typeof parsed === "string" ||
+      typeof parsed === "number" ||
+      typeof parsed === "boolean"
+    ) {
+      return parsed;
+    }
+  } catch {
+    // Not JSON — treat the raw text itself as the string default.
+  }
+  return raw;
+}
+
+function stringifyCell(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") return value;
+  return JSON.stringify(value);
+}
+
+async function dbTables(argv: string[], json: boolean): Promise<void> {
+  const [slug] = argv;
+  const projectId = await resolveProjectId(slug);
+  const { tables } = await apiFetch<{ tables: DbTable[] }>(
+    `/api/v1/projects/${projectId}/database/tables`,
+  );
+  if (json) {
+    printJson(tables);
+    return;
+  }
+  printTable(
+    tables.map((t) => ({
+      Table: t.name,
+      Rows: String(t.row_count),
+      Editable: t.editable ? "yes" : `no (${t.not_editable_reason ?? "unknown reason"})`,
+    })),
+    ["Table", "Rows", "Editable"],
+  );
+}
+
+async function dbRows(argv: string[], json: boolean): Promise<void> {
+  const limitOpt = takeOption(argv, "limit");
+  const [slug, table] = limitOpt.rest;
+  if (!table) die(USAGE);
+  const projectId = await resolveProjectId(slug);
+  const query = limitOpt.value ? `?limit=${encodeURIComponent(limitOpt.value)}` : "";
+  const page = await apiFetch<RowsPage>(
+    `/api/v1/projects/${projectId}/database/tables/${encodeURIComponent(table)}/rows${query}`,
+  );
+  if (json) {
+    printJson(page);
+    return;
+  }
+  printTable(
+    page.rows.map((r) => ({
+      id: r.id,
+      ...Object.fromEntries(page.columns.map((c) => [c.name, stringifyCell(r.cells[c.name])])),
+    })),
+    ["id", ...page.columns.map((c) => c.name)],
+  );
+  if (page.truncated) console.log(`(showing the first ${page.rows.length} rows — more exist)`);
+  if (!page.editable) {
+    console.log(`Not editable: ${page.not_editable_reason ?? "unknown reason"}`);
+  }
+}
+
+async function dbInsert(argv: string[], json: boolean): Promise<void> {
+  const [slug, table, cellsJson] = argv;
+  if (!table) die(USAGE);
+  const projectId = await resolveProjectId(slug);
+  const cells = parseJsonArg<Record<string, unknown>>(cellsJson, "<cells-json>");
+  const { row } = await apiFetch<{ row: DbRow }>(
+    `/api/v1/projects/${projectId}/database/tables/${encodeURIComponent(table)}/rows`,
+    { method: "POST", body: { cells } },
+  );
+  if (json) {
+    printJson(row);
+    return;
+  }
+  console.log(`Inserted row ${row.id}.`);
+}
+
+async function dbUpdate(argv: string[], json: boolean): Promise<void> {
+  const [slug, table, rowId, cellsJson] = argv;
+  if (!table || !rowId) die(USAGE);
+  const projectId = await resolveProjectId(slug);
+  const cells = parseJsonArg<Record<string, unknown>>(cellsJson, "<cells-json>");
+  const { row } = await apiFetch<{ row: DbRow }>(
+    `/api/v1/projects/${projectId}/database/tables/${encodeURIComponent(table)}/rows/${encodeURIComponent(rowId)}`,
+    { method: "PATCH", body: { cells } },
+  );
+  if (json) {
+    printJson(row);
+    return;
+  }
+  console.log(`Updated row ${row.id}.`);
+}
+
+async function dbDelete(argv: string[], json: boolean): Promise<void> {
+  const [slug, table, rowId] = argv;
+  if (!table || !rowId) die(USAGE);
+  const projectId = await resolveProjectId(slug);
+  await apiFetch(
+    `/api/v1/projects/${projectId}/database/tables/${encodeURIComponent(table)}/rows/${encodeURIComponent(rowId)}`,
+    { method: "DELETE" },
+  );
+  if (json) {
+    printJson({ row_id: rowId, deleted: true });
+    return;
+  }
+  console.log(`Deleted row ${rowId}.`);
+}
+
+async function dbCreateTable(argv: string[], json: boolean): Promise<void> {
+  const pkOpt = takeOption(argv, "primary-key");
+  const [slug, table, columnsJson] = pkOpt.rest;
+  if (!table || !pkOpt.value) die(USAGE);
+  const projectId = await resolveProjectId(slug);
+  const columns = parseJsonArg<unknown[]>(columnsJson, "<columns-json>");
+  const result = await apiFetch<{ table: string; created: boolean }>(
+    `/api/v1/projects/${projectId}/database/tables`,
+    { method: "POST", body: { name: table, columns, primary_key: pkOpt.value } },
+  );
+  if (json) {
+    printJson(result);
+    return;
+  }
+  console.log(`Created table "${result.table}".`);
+}
+
+async function dbMigrate(argv: string[], json: boolean): Promise<void> {
+  const defaultOpt = takeOption(argv, "default");
+  const [slug, table, columnJson] = defaultOpt.rest;
+  if (!table) die(USAGE);
+  const projectId = await resolveProjectId(slug);
+  const column = parseJsonArg<Record<string, unknown>>(columnJson, "<column-json>");
+  const defaultValue = defaultOpt.value === undefined ? null : parseDefaultValue(defaultOpt.value);
+  const result = await apiFetch<{ table: string; column: string; added: boolean }>(
+    `/api/v1/projects/${projectId}/database/tables/${encodeURIComponent(table)}/columns`,
+    { method: "POST", body: { ...column, default_value: defaultValue } },
+  );
+  if (json) {
+    printJson(result);
+    return;
+  }
+  console.log(`Added column "${result.column}" to "${result.table}".`);
+}
+
+export async function dbCommand(argv: string[], json: boolean): Promise<void> {
+  const [subcommand, ...rest] = argv;
+  switch (subcommand) {
+    case "tables":
+      return dbTables(rest, json);
+    case "rows":
+      return dbRows(rest, json);
+    case "insert":
+      return dbInsert(rest, json);
+    case "update":
+      return dbUpdate(rest, json);
+    case "delete":
+      return dbDelete(rest, json);
+    case "create-table":
+      return dbCreateTable(rest, json);
+    case "migrate":
+      return dbMigrate(rest, json);
+    default:
+      die(USAGE);
+  }
+}

package/src/commands/deploy.ts

@@ -0,0 +1,101 @@
+/**
+ * `svcloud deploy <app>` — PLANNING.md §3.3/§4 Step 6, option (a): trigger
+ * the existing push-triggered pipeline and poll, rather than building
+ * locally and uploading an artifact (option (b), deliberately not built —
+ * see this file's closing note). No `cloud-api` change: `git push` plus
+ * `GET /:id/deploys` already existed.
+ *
+ * This command never claims to have deployed anything itself — it pushes,
+ * then watches the deploy row GitHub Actions' own OIDC-authenticated call
+ * creates, and reports whatever status that row settles on (or hasn't, by
+ * the time it gives up watching).
+ */
+import type { DeploySummary, ProjectDetail } from "@sv/cloud-contracts";
+import { apiFetch } from "../lib/api";
+import { pollForNewDeploy } from "../lib/deploy-poll";
+import { findProjectBySlug } from "../lib/find-project";
+import { gitWorkingState, pushCurrentBranch } from "../lib/git";
+import { die, printJson } from "../lib/output";
+
+async function fetchDeploys(projectId: string): Promise<DeploySummary[]> {
+  const { deploys } = await apiFetch<{ deploys: DeploySummary[] }>(
+    `/api/v1/projects/${projectId}/deploys`,
+  );
+  return deploys;
+}
+
+export async function deployCommand(argv: string[], json: boolean): Promise<void> {
+  const [slug] = argv;
+  if (!slug) die("Usage: svcloud deploy <app>");
+
+  const project = await findProjectBySlug(slug);
+  if (!project) die(`No app named "${slug}".`);
+
+  const detail = await apiFetch<ProjectDetail>(`/api/v1/projects/${project.id}?advanced=1`);
+  const defaultBranch = detail.advanced?.default_branch;
+  if (!defaultBranch) die("Couldn't determine this app's default branch. Try again.");
+
+  const state = await gitWorkingState();
+  if (!state) {
+    die("Run this from the app's local git repository (no repo found, or `git` isn't on PATH).");
+  }
+  if (state.dirty) {
+    die("Working tree has uncommitted changes. Commit or stash them, then run `svcloud deploy` again.");
+  }
+  if (state.branch !== defaultBranch) {
+    die(
+      `On branch "${state.branch}", but this app deploys from "${defaultBranch}". ` +
+        `Switch branches, or push "${defaultBranch}" directly with git.`,
+    );
+  }
+
+  const baselineId = (await fetchDeploys(project.id))[0]?.id;
+
+  if (!json) console.log(`Pushing ${state.branch}...`);
+  try {
+    await pushCurrentBranch();
+  } catch (err) {
+    die(`git push failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  if (!json) console.log("Waiting for the build...");
+  const { deploy, timedOut } = await pollForNewDeploy(() => fetchDeploys(project.id), baselineId, {
+    quiet: json,
+  });
+
+  if (json) {
+    printJson({ deploy: deploy ?? null, timed_out: timedOut });
+    return;
+  }
+
+  if (!deploy) {
+    console.log(
+      `No build detected yet. Check \`svcloud status ${slug}\` shortly — the pipeline may still be starting.`,
+    );
+    return;
+  }
+  if (deploy.status === "failed") {
+    die(`Deploy failed.${deploy.log_url ? ` Logs: ${deploy.log_url}` : ""}`);
+  }
+  if (timedOut) {
+    console.log(`Still building. Check \`svcloud status ${slug}\` shortly.`);
+    return;
+  }
+  console.log(`Deployed. ${detail.web_address ?? ""}`.trim());
+}
+
+/**
+ * Option (b) — build locally, upload the artifact to a new user-token
+ * endpoint — is deliberately NOT built. Besides the refactor PLANNING.md
+ * §3.3 already scoped (`deployProject()` lifted off `GitHubOidcClaims`),
+ * there's an open security question flagged 2026-08-25, not yet
+ * investigated: today, only GitHub Actions running the repo's *own* checked-
+ * in workflow can ever produce a deploy — the artifact is whatever that CI
+ * job built from a specific commit. A user-token upload endpoint accepts
+ * whatever bytes the caller sends, built wherever they built it — no
+ * required correspondence to any commit in the repo at all. Whether that's
+ * actually a meaningful new risk for this product (small blast radius per
+ * project? already-authenticated owner deploying to their own app?) or a
+ * non-issue is unresolved. Investigate and record the answer here before (b)
+ * is designed further, let alone built.
+ */