svcloud 0.1.0-alpha.3 → 0.1.0

package/README.md

@@ -3,24 +3,26 @@
 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`.
+> **Alpha.** Published under the `alpha` dist-tag, not `latest` — see
+> Commands below for what's built. `logs` and `dev` are still on the way.
 
 ## Install
 
 ```bash
-npx svcloud@alpha login
+npm install -g svcloud
+svcloud login
 ```
 
-Or install it:
+Or try it once without installing:
 
 ```bash
-npm install -g svcloud@alpha
-svcloud login
+npx svcloud login
 ```
 
+An installed `svcloud` is what every example below uses, and is what a
+coding agent's harness config should point at too — see [Connect your coding
+agent](#connect-your-coding-agent).
+
 `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
@@ -37,7 +39,12 @@ 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 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)
+svcloud mcp setup <harness>   Write a coding agent harness's MCP config for svcloud
+svcloud mcp check             Diagnose sign-in state, harness configs, and live tool visibility
 
 Flags:
   --json                      Machine-readable output, on every read command
@@ -49,7 +56,7 @@ to skip what it would otherwise infer or ask about; `runs` reads `--id
 (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.
+`logs` and `dev` are still on the way.
 
 ## Connect your coding agent
 
@@ -66,7 +73,19 @@ First, sign in on your machine:
 svcloud login
 ```
 
-Then configure your agent:
+Then let the CLI write your harness's config for you:
+
+```bash
+svcloud mcp setup claude-code   # or: cursor | opencode | antigravity | gemini-cli | codex
+```
+
+That writes the one file each harness actually reads, in the shape it
+actually expects — the config blocks below are the same data, by hand, for a
+harness that isn't in the list yet, or if you'd rather see exactly what gets
+written first. If something still doesn't work after setup, run
+`svcloud mcp check` — it reports sign-in state, a live count of tools your
+token can see, and whether each known harness's config file exists and has
+the right shape.
 
 ### Antigravity
 Add to `~/.gemini/config/mcp_config.json` (global) or `.agents/mcp_config.json` (workspace):
@@ -75,8 +94,8 @@ Add to `~/.gemini/config/mcp_config.json` (global) or `.agents/mcp_config.json`
 {
   "mcpServers": {
     "svcloud": {
-      "command": "npx",
-      "args": ["-y", "svcloud@alpha", "mcp"]
+      "command": "svcloud",
+      "args": ["mcp"]
     }
   }
 }
@@ -84,7 +103,7 @@ Add to `~/.gemini/config/mcp_config.json` (global) or `.agents/mcp_config.json`
 
 ### Gemini CLI
 ```bash
-gemini mcp add svcloud -- npx -y svcloud@alpha mcp
+gemini mcp add svcloud -- svcloud mcp
 ```
 Or add the `svcloud` block under `mcpServers` in `~/.gemini/config.json` or `~/.gemini/mcp_config.json`.
 
@@ -92,36 +111,56 @@ Or add the `svcloud` block under `mcpServers` in `~/.gemini/config.json` or `~/.
 Go to **Settings** > **Features** > **MCP** > **Add New MCP Server**:
 - **Name:** `svcloud`
 - **Type:** `command`
-- **Command:** `npx -y svcloud@alpha mcp`
+- **Command:** `svcloud mcp`
 
 Or add directly to `.cursor/mcp.json`:
 ```json
 {
   "mcpServers": {
     "svcloud": {
-      "command": "npx",
-      "args": ["-y", "svcloud@alpha", "mcp"]
+      "command": "svcloud",
+      "args": ["mcp"]
     }
   }
 }
 ```
 
 ### OpenCode
-In `~/.config/opencode/mcp.json` or your OpenCode configuration:
+OpenCode does **not** read `mcpServers` — that's the Claude-style shape every
+other harness here uses, and writing it to OpenCode's config produces a file
+that looks installed but does nothing. OpenCode reads a top-level `mcp` key,
+in `~/.config/opencode/opencode.json` (global) or `opencode.json`/
+`opencode.jsonc` at your project root, and each server needs `"type":
+"local"` with `command` as an array:
+
 ```json
 {
-  "mcpServers": {
+  "mcp": {
     "svcloud": {
-      "command": "npx",
-      "args": ["-y", "svcloud@alpha", "mcp"]
+      "type": "local",
+      "command": ["svcloud", "mcp"]
     }
   }
 }
 ```
 
+`svcloud mcp setup opencode` writes exactly this, to the right file — the
+safest way to get it right by hand is still to run that.
+
 ### Claude Code
 ```bash
-claude mcp add svcloud -- npx -y svcloud@alpha mcp
+claude mcp add svcloud -- svcloud mcp
+```
+Or add directly to `.mcp.json` at your project root:
+```json
+{
+  "mcpServers": {
+    "svcloud": {
+      "command": "svcloud",
+      "args": ["mcp"]
+    }
+  }
+}
 ```
 
 ### Codex
@@ -130,8 +169,8 @@ In `~/.codex/config.json` or your Codex MCP settings:
 {
   "mcpServers": {
     "svcloud": {
-      "command": "npx",
-      "args": ["-y", "svcloud@alpha", "mcp"]
+      "command": "svcloud",
+      "args": ["mcp"]
     }
   }
 }
@@ -141,24 +180,21 @@ In `~/.codex/config.json` or your Codex MCP settings:
 In any harness or configuration file that accepts an `mcpServers` block:
 
 ```jsonc
-{ "svcloud": { "command": "npx", "args": ["-y", "svcloud@alpha", "mcp"] } }
+{ "svcloud": { "command": "svcloud", "args": ["mcp"] } }
 ```
 
+Running it through `npx` instead works too (`{ "command": "npx", "args":
+["-y", "svcloud", "mcp"] }`), but costs a network round-trip on every
+start and depends on the npm registry being up — prefer an installed
+`svcloud` for anything you use daily.
+
 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
+npm install -g svcloud
 ```
 
 Your agent picks up the new version the next time it starts — restart the MCP
@@ -174,7 +210,9 @@ at the moment you sign in. If we widen what the CLI can be granted, run
 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.)
+settings tools that were previously invisible to the bridge.) `svcloud mcp
+check` flags this for you — it warns when your session has fewer scopes than
+SV Cloud currently grants by default.
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svcloud",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0",
   "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",
@@ -15,17 +15,17 @@
   "engines": {
     "node": ">=22.18.0"
   },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts"
+  },
   "dependencies": {
     "tsx": "^4.20.0"
   },
   "devDependencies": {
+    "@sv/cloud-contracts": "workspace:*",
     "@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"
+    "typescript": "^5.9.3"
   }
-}
+}

package/src/commands/db.ts

@@ -1,7 +1,7 @@
 /**
  * `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
+ * alongside this command (`db_create_table`/`db_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
@@ -125,12 +125,18 @@ async function dbRows(argv: string[], json: boolean): Promise<void> {
     printJson(page);
     return;
   }
+  const hasIdColumn = page.columns.some((c) => c.name === "id");
+  const headers = hasIdColumn
+    ? page.columns.map((c) => c.name)
+    : ["id", ...page.columns.map((c) => c.name)];
   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)],
+    page.rows.map((r) => {
+      const cells = Object.fromEntries(
+        page.columns.map((c) => [c.name, stringifyCell(r.cells[c.name])]),
+      );
+      return hasIdColumn ? cells : { id: r.id, ...cells };
+    }),
+    headers,
   );
   if (page.truncated) console.log(`(showing the first ${page.rows.length} rows — more exist)`);
   if (!page.editable) {

package/src/commands/mcp-check.ts

@@ -0,0 +1,110 @@
+/**
+ * `svcloud mcp check` — one-command diagnosis for "the harness doesn't see
+ * my tools." Exists because the actual field failure (2026-08-26 report)
+ * was a config that *looked* installed — a file existed at a path that
+ * seemed right — but was the wrong shape for the harness reading it, and
+ * finding that took digging. This prints sign-in state, a live `tools/list`
+ * probe (same request the bridge itself makes — `callRemote` from
+ * `mcp.ts`), and every known harness's config file: found or not, and if
+ * found, right shape or wrong.
+ */
+import { callRemote } from "./mcp";
+import { CLI_VERSION, apiBaseUrl } from "../lib/config";
+import { loadTokens } from "../lib/credentials";
+import { HARNESSES, inspectHarness, type HarnessStatus } from "../lib/harnesses";
+import { printJson } from "../lib/output";
+
+// The scope vocabulary svcloud-cli/svcloud-mcp currently grant by default
+// (apps/cloud/src/services/oauth.ts's OAUTH_CLIENTS, widened 2026-08-25 to
+// every OAUTH_SCOPES entry except database:sql). A session with fewer
+// scopes than this predates that widening — scopes are frozen at sign-in
+// and only refreshed by signing in again, never silently upgraded.
+const EXPECTED_SCOPE_COUNT = 6;
+
+function describeStatus(status: HarnessStatus): string {
+  switch (status.state) {
+    case "not_found":
+      return "not found";
+    case "unreadable":
+      return `exists but isn't valid JSON (${status.detail})`;
+    case "missing_entry":
+      return "found, but has no svcloud entry";
+    case "wrong_shape":
+      return "found, but the svcloud entry is the wrong shape for this harness";
+    case "ok":
+      return "configured correctly";
+  }
+}
+
+export async function mcpCheckCommand(json: boolean): Promise<void> {
+  const tokens = await loadTokens();
+  const cwd = process.cwd();
+
+  const harnessResults = await Promise.all(
+    HARNESSES.map(async (h) => ({ harness: h, status: await inspectHarness(h, cwd) })),
+  );
+
+  let toolCount: number | undefined;
+  let toolsListError: string | undefined;
+  if (tokens) {
+    const result = await callRemote({
+      jsonrpc: "2.0",
+      id: "__svcloud_mcp_check__",
+      method: "tools/list",
+      params: {},
+    });
+    if (result.ok) {
+      const body = result.body as { result?: { tools?: unknown[] } };
+      toolCount = body.result?.tools?.length;
+    } else {
+      toolsListError = result.reason === "auth" ? "not signed in" : result.detail;
+    }
+  }
+
+  const scopeStale = tokens !== undefined && tokens.scopes.length < EXPECTED_SCOPE_COUNT;
+
+  if (json) {
+    printJson({
+      version: CLI_VERSION,
+      api_base_url: apiBaseUrl(),
+      signed_in: tokens !== undefined,
+      scopes: tokens?.scopes ?? [],
+      scopes_possibly_stale: scopeStale,
+      tools_visible: toolCount,
+      tools_list_error: toolsListError,
+      harnesses: harnessResults.map(({ harness, status }) => ({
+        id: harness.id,
+        path: status.path,
+        state: status.state,
+      })),
+    });
+    return;
+  }
+
+  console.log(`svcloud ${CLI_VERSION} (API: ${apiBaseUrl()})`);
+  console.log("");
+  if (!tokens) {
+    console.log("Sign-in: not signed in. Run `svcloud login`.");
+  } else {
+    console.log(`Sign-in: signed in, ${tokens.scopes.length} scopes (${tokens.scopes.join(", ")}).`);
+    if (scopeStale) {
+      console.log(
+        "  Fewer scopes than SV Cloud currently grants by default — if a tool you expect is missing, " +
+          "run `svcloud login` again. Scopes are frozen at sign-in and don't update on their own.",
+      );
+    }
+    if (toolCount !== undefined) {
+      console.log(`Live tools/list: ${toolCount} tools visible to this token.`);
+    } else if (toolsListError) {
+      console.log(`Live tools/list: failed (${toolsListError}).`);
+    }
+  }
+  console.log("");
+  console.log("Harness configs:");
+  for (const { harness, status } of harnessResults) {
+    console.log(`  ${harness.label.padEnd(14)} ${status.path}`);
+    console.log(`  ${"".padEnd(14)} ${describeStatus(status)}`);
+  }
+  console.log("");
+  console.log("Fix a missing or wrong-shaped one with: svcloud mcp setup <harness>");
+}

package/src/commands/mcp-setup.ts

@@ -0,0 +1,86 @@
+/**
+ * `svcloud mcp setup <harness>` — writes or merges the correct MCP config
+ * block for one harness, from the single table in `lib/harnesses.ts`. Exists
+ * because README.md's prose config blocks are what actually broke: an
+ * OpenCode reader followed a Claude-style `mcpServers` block written to the
+ * wrong file, ended up with a config that looked installed but was inert,
+ * and only found the mismatch by digging (2026-08-26 field report). Writing
+ * the file directly, from data instead of prose, is the fix.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { findHarness, HARNESSES, type Harness } from "../lib/harnesses";
+import { die, hasFlag } from "../lib/output";
+
+function usage(): string {
+  const ids = HARNESSES.map((h) => h.id).join(" | ");
+  return `Usage: svcloud mcp setup <harness> [--force]\n\nHarnesses: ${ids}`;
+}
+
+async function readExistingConfig(path: string, force: boolean): Promise<Record<string, unknown>> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch {
+    return {};
+  }
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error("not a JSON object");
+    }
+    return parsed as Record<string, unknown>;
+  } catch (err) {
+    if (!force) {
+      die(
+        `${path} exists but isn't valid JSON (${err instanceof Error ? err.message : String(err)}).\n` +
+          `Fix it by hand, or rerun with --force to overwrite it.`,
+      );
+    }
+    return {};
+  }
+}
+
+export async function mcpSetupCommand(argv: string[], json: boolean): Promise<void> {
+  const { present: force, rest } = hasFlag(argv, "force");
+  const id = rest[0];
+  if (!id) die(usage());
+  const harness: Harness | undefined = findHarness(id);
+  if (!harness) die(`Unknown harness "${id}".\n\n${usage()}`);
+
+  const path = harness.configPath(process.cwd());
+  const config = await readExistingConfig(path, force);
+
+  const servers = (config[harness.serversKey] ?? {}) as Record<string, unknown>;
+  const existing = servers.svcloud;
+  const entry = harness.buildEntry("svcloud", ["mcp"]);
+
+  if (existing !== undefined && !force) {
+    if (harness.isWellFormed(existing)) {
+      if (json) {
+        console.log(JSON.stringify({ harness: harness.id, path, status: "already_configured" }));
+      } else {
+        console.log(`${harness.label} is already configured at ${path}.`);
+      }
+      return;
+    }
+    die(
+      `${path} already has a "svcloud" entry under "${harness.serversKey}", but it doesn't look right for ${harness.label}.\n` +
+        `Rerun with --force to overwrite it.`,
+    );
+  }
+
+  servers.svcloud = entry;
+  config[harness.serversKey] = servers;
+
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+
+  if (json) {
+    console.log(JSON.stringify({ harness: harness.id, path, status: "written" }));
+    return;
+  }
+  console.log(`Wrote ${harness.label}'s MCP config to ${path}.`);
+  console.log(`Sign in first if you haven't: svcloud login`);
+  console.log(`Then restart ${harness.label} (or start a new session) to pick it up.`);
+}

package/src/commands/mcp.ts

@@ -41,6 +41,9 @@ import { createInterface } from "node:readline";
 import { AuthRequiredError, currentAccessToken, forceRefreshAccessToken } from "../lib/api";
 import { apiBaseUrl } from "../lib/config";
 import { loadTokens } from "../lib/credentials";
+import { die } from "../lib/output";
+import { mcpCheckCommand } from "./mcp-check";
+import { mcpSetupCommand } from "./mcp-setup";
 
 type JsonRpcId = string | number | null;
 
@@ -79,13 +82,18 @@ function warnNotSignedInOnce(): void {
   stderrLine(NOT_SIGNED_IN_MESSAGE);
 }
 
-type RemoteResult =
+export 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> {
+/**
+ * One request to `POST /mcp`, refreshing once on a 401, whatever the
+ * eventual status. Never throws. Exported for `mcp-check.ts`'s live
+ * `tools/list` probe — same request the bridge itself makes, not a second
+ * implementation.
+ */
+export async function callRemote(msg: unknown): Promise<RemoteResult> {
   let accessToken: string;
   try {
     accessToken = await currentAccessToken();
@@ -156,16 +164,18 @@ async function logStartupState(): Promise<void> {
   }
 }
 
-export async function mcpCommand(): Promise<void> {
+/** The stdio bridge itself — everything rules 1-8 above govern. Only reachable as bare `svcloud mcp`. */
+export async function mcpBridgeCommand(): 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();
-
+  // Attach to stdin synchronously before any async work so the harness's
+  // initialize handshake is never delayed or dropped on session start.
   const rl = createInterface({ input: process.stdin, terminal: false });
+  void logStartupState();
   rl.on("line", (line) => {
     const trimmed = line.trim();
     if (!trimmed) return;
@@ -183,3 +193,35 @@ export async function mcpCommand(): Promise<void> {
 
   await new Promise<void>((resolve) => rl.on("close", resolve));
 }
+
+const USAGE = `Usage:
+  svcloud mcp                    Run the local MCP bridge (for a coding agent's harness config)
+  svcloud mcp setup <harness>    Write this harness's MCP config for svcloud
+  svcloud mcp check              Diagnose sign-in state, harness configs, and live tool visibility`;
+
+/**
+ * `svcloud mcp [setup|check]` — bare `mcp` must stay the stdio bridge since
+ * every documented harness config invokes it exactly that way
+ * (`claude mcp add svcloud -- svcloud mcp`, etc.), so it's the default when
+ * `argv` has no subcommand — not a subcommand of its own.
+ */
+export async function mcpCommand(argv: string[], json: boolean): Promise<void> {
+  const [subcommand, ...rest] = argv;
+  switch (subcommand) {
+    case undefined:
+      await mcpBridgeCommand();
+      return;
+    case "setup":
+      await mcpSetupCommand(rest, json);
+      return;
+    case "check":
+      await mcpCheckCommand(json);
+      return;
+    case "-h":
+    case "--help":
+      console.log(USAGE);
+      return;
+    default:
+      die(`Unknown "svcloud mcp" subcommand: ${subcommand}\n\n${USAGE}`);
+  }
+}

package/src/index.ts

@@ -1,9 +1,9 @@
 #!/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.
+ * Argument parsing and command dispatch. Hand-rolled rather than a
+ * dependency: a handful of top-level commands, one global flag, and the
+ * few that need subcommands (`secrets`, `db`, `mcp`) do their own
+ * second-level switch — no subcommand ambiguity worth a parser library yet.
  */
 import { dbCommand } from "./commands/db";
 import { deployCommand } from "./commands/deploy";
@@ -35,6 +35,8 @@ Usage:
   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)
+  svcloud mcp setup <harness>   Write a coding agent harness's MCP config for svcloud
+  svcloud mcp check             Diagnose sign-in state, harness configs, and live tool visibility
 
 Flags:
   --json                        Machine-readable output, on every read command
@@ -66,7 +68,7 @@ async function main(): Promise<void> {
       await projectsCommand(rest[0], json);
       return;
     case "mcp":
-      await mcpCommand();
+      await mcpCommand(rest, json);
       return;
     case "init":
       await initCommand(rest, json);

package/src/lib/config.ts

@@ -3,6 +3,7 @@
  * override, for pointing the CLI at a local `wrangler dev` instance while
  * building it — production has no reason to ever set it.
  */
+import { createRequire } from "node:module";
 
 export const CLIENT_ID = "svcloud-cli";
 
@@ -13,3 +14,6 @@ export function apiBaseUrl(): string {
 /** 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";
+
+/** This installed CLI's own version, from package.json — surfaced by `svcloud mcp check`. */
+export const CLI_VERSION: string = createRequire(import.meta.url)("../../package.json").version;

package/src/lib/harnesses.ts

@@ -0,0 +1,148 @@
+/**
+ * The harness table `svcloud mcp setup <harness>` and `svcloud mcp check`
+ * both read — previously this was six prose blocks in README.md, hand-kept
+ * in sync with nothing. That's how the OpenCode block drifted wrong
+ * (2026-08-26 field report): it told a reader to write a Claude-style
+ * `mcpServers` object to `~/.config/opencode/mcp.json`, which OpenCode
+ * never reads — OpenCode's actual config is `~/.config/opencode/opencode.json`
+ * with a `mcp` key whose entries are `{ type: "local", command: [...] }`,
+ * verified against https://opencode.ai/docs/mcp-servers/ and
+ * https://opencode.ai/docs/config/ while fixing this. One table now backs
+ * the README, `mcp setup`, and `mcp check`, so they cannot drift apart
+ * again the same way.
+ *
+ * Codex's entry is carried over from the README as it stood before this
+ * change (`~/.codex/config.json`, `mcpServers`) — not independently
+ * re-verified here; only OpenCode's shape was reported wrong.
+ */
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export type HarnessId = "claude-code" | "cursor" | "opencode" | "antigravity" | "gemini-cli" | "codex";
+
+export interface HarnessEntry {
+  command: string | string[];
+  args?: string[];
+  type?: string;
+}
+
+export interface Harness {
+  id: HarnessId;
+  label: string;
+  /** Where the config file lives. "project" is relative to the current working directory. */
+  scope: "project" | "global";
+  configPath: (cwd: string) => string;
+  /** The top-level object key an entry for svcloud lives under. */
+  serversKey: string;
+  /** Build this harness's shape of the svcloud server entry. */
+  buildEntry: (command: string, args: string[]) => HarnessEntry;
+  /** True if an existing entry (already parsed as JSON) has this harness's expected shape. */
+  isWellFormed: (entry: unknown) => boolean;
+}
+
+function isStringArray(v: unknown): v is string[] {
+  return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+
+const claudeStyleEntry = (command: string, args: string[]): HarnessEntry => ({ command, args });
+const claudeStyleWellFormed = (entry: unknown): boolean =>
+  typeof entry === "object" &&
+  entry !== null &&
+  typeof (entry as Record<string, unknown>).command === "string" &&
+  isStringArray((entry as Record<string, unknown>).args ?? []);
+
+export const HARNESSES: Harness[] = [
+  {
+    id: "claude-code",
+    label: "Claude Code",
+    scope: "project",
+    configPath: (cwd) => join(cwd, ".mcp.json"),
+    serversKey: "mcpServers",
+    buildEntry: claudeStyleEntry,
+    isWellFormed: claudeStyleWellFormed,
+  },
+  {
+    id: "cursor",
+    label: "Cursor",
+    scope: "project",
+    configPath: (cwd) => join(cwd, ".cursor", "mcp.json"),
+    serversKey: "mcpServers",
+    buildEntry: claudeStyleEntry,
+    isWellFormed: claudeStyleWellFormed,
+  },
+  {
+    id: "antigravity",
+    label: "Antigravity",
+    scope: "global",
+    configPath: () => join(homedir(), ".gemini", "config", "mcp_config.json"),
+    serversKey: "mcpServers",
+    buildEntry: claudeStyleEntry,
+    isWellFormed: claudeStyleWellFormed,
+  },
+  {
+    id: "gemini-cli",
+    label: "Gemini CLI",
+    scope: "global",
+    configPath: () => join(homedir(), ".gemini", "mcp_config.json"),
+    serversKey: "mcpServers",
+    buildEntry: claudeStyleEntry,
+    isWellFormed: claudeStyleWellFormed,
+  },
+  {
+    id: "codex",
+    label: "Codex",
+    scope: "global",
+    configPath: () => join(homedir(), ".codex", "config.json"),
+    serversKey: "mcpServers",
+    buildEntry: claudeStyleEntry,
+    isWellFormed: claudeStyleWellFormed,
+  },
+  {
+    id: "opencode",
+    label: "OpenCode",
+    scope: "global",
+    configPath: () => join(homedir(), ".config", "opencode", "opencode.json"),
+    serversKey: "mcp",
+    buildEntry: (command, args) => ({ type: "local", command: [command, ...args] }),
+    isWellFormed: (entry: unknown): boolean =>
+      typeof entry === "object" &&
+      entry !== null &&
+      (entry as Record<string, unknown>).type === "local" &&
+      isStringArray((entry as Record<string, unknown>).command) &&
+      ((entry as Record<string, unknown>).command as string[]).length > 0,
+  },
+];
+
+export function findHarness(id: string): Harness | undefined {
+  return HARNESSES.find((h) => h.id === id);
+}
+
+export type HarnessStatus =
+  | { state: "not_found"; path: string }
+  | { state: "unreadable"; path: string; detail: string }
+  | { state: "missing_entry"; path: string }
+  | { state: "wrong_shape"; path: string }
+  | { state: "ok"; path: string };
+
+/** Reads and inspects a harness's config file — never throws. */
+export async function inspectHarness(harness: Harness, cwd: string): Promise<HarnessStatus> {
+  const path = harness.configPath(cwd);
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch {
+    return { state: "not_found", path };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return { state: "unreadable", path, detail: err instanceof Error ? err.message : String(err) };
+  }
+  const servers = (parsed as Record<string, unknown> | null)?.[harness.serversKey];
+  const entry = (servers as Record<string, unknown> | undefined)?.svcloud;
+  if (entry === undefined) return { state: "missing_entry", path };
+  if (!harness.isWellFormed(entry)) return { state: "wrong_shape", path };
+  return { state: "ok", path };
+}

package/src/lib/loopback-server.ts

@@ -21,11 +21,218 @@ export interface LoopbackListener {
 }
 
 const CALLBACK_PAGE = (ok: boolean) => `<!doctype html>
-<html><head><title>SV Cloud</title></head>
-<body style="font-family:system-ui;padding:2rem;color:#111">
-<h1>${ok ? "You're signed in." : "Sign-in didn't finish."}</h1>
-<p>You can close this tab and go back to your terminal.</p>
-</body></html>`;
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>SV Cloud</title>
+  <style>
+    :root {
+      --bg-canvas: #0b0c0e;
+      --bg-surface: #131519;
+      --bg-raised: #1b1e24;
+      --border-quiet: #23272e;
+      --border-loud: #343a44;
+      --text-1: #e9ebef;
+      --text-2: #a7aeba;
+      --text-3: #6e7684;
+      --accent: #8e6bff;
+      --state-live: #34c77b;
+      --state-failed: #e8a33d;
+      --font-sans: 'Outfit', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
+      --font-mono: 'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+      --shadow: 0 8px 32px rgba(0, 0, 0, 0.4);
+    }
+    @media (prefers-color-scheme: light) {
+      :root {
+        --bg-canvas: #fafbfc;
+        --bg-surface: #ffffff;
+        --bg-raised: #f2f4f7;
+        --border-quiet: #e1e4ea;
+        --border-loud: #cdd2dc;
+        --text-1: #111318;
+        --text-2: #4a5160;
+        --text-3: #7d8594;
+        --accent: #7c5cfc;
+        --state-live: #1da462;
+        --state-failed: #d97706;
+        --shadow: 0 8px 32px rgba(0, 0, 0, 0.08);
+      }
+    }
+    * {
+      box-sizing: border-box;
+      margin: 0;
+      padding: 0;
+    }
+    body {
+      min-height: 100vh;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      background-color: var(--bg-canvas);
+      background-image: radial-gradient(circle at 50% 15%, color-mix(in srgb, var(--accent) 12%, transparent), transparent 60%);
+      color: var(--text-1);
+      font-family: var(--font-sans);
+      padding: 24px;
+      -webkit-font-smoothing: antialiased;
+    }
+    .auth-container {
+      width: min(420px, 100%);
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      gap: 24px;
+      animation: fadeIn 0.3s ease-out;
+    }
+    @keyframes fadeIn {
+      from { opacity: 0; transform: translateY(6px); }
+      to { opacity: 1; transform: translateY(0); }
+    }
+    .lockup {
+      display: inline-flex;
+      align-items: center;
+      gap: 10px;
+      font-size: 15px;
+      font-weight: 500;
+      letter-spacing: -0.01em;
+      color: var(--text-1);
+      text-decoration: none;
+    }
+    .mark {
+      width: 24px;
+      height: 24px;
+      display: grid;
+      place-items: center;
+      border-radius: 5px;
+      border: 1px solid var(--border-loud);
+      background: var(--bg-raised);
+      color: var(--text-2);
+      font-family: var(--font-mono);
+      font-size: 10px;
+      font-weight: 600;
+      letter-spacing: 0.05em;
+    }
+    .card {
+      width: 100%;
+      background: var(--bg-surface);
+      border: 1px solid var(--border-quiet);
+      border-radius: 12px;
+      padding: 28px 24px;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      text-align: center;
+      gap: 16px;
+      box-shadow: var(--shadow);
+    }
+    .status-icon {
+      width: 44px;
+      height: 44px;
+      border-radius: 50%;
+      display: grid;
+      place-items: center;
+      flex-shrink: 0;
+    }
+    .status-icon--ok {
+      background: color-mix(in srgb, var(--state-live) 15%, transparent);
+      color: var(--state-live);
+      border: 1px solid color-mix(in srgb, var(--state-live) 30%, transparent);
+    }
+    .status-icon--error {
+      background: color-mix(in srgb, var(--state-failed) 15%, transparent);
+      color: var(--state-failed);
+      border: 1px solid color-mix(in srgb, var(--state-failed) 30%, transparent);
+    }
+    h1 {
+      font-size: 20px;
+      font-weight: 600;
+      letter-spacing: -0.02em;
+      color: var(--text-1);
+      line-height: 1.3;
+    }
+    p.desc {
+      font-size: 14px;
+      color: var(--text-2);
+      line-height: 1.5;
+    }
+    .terminal-box {
+      width: 100%;
+      margin-top: 6px;
+      background: var(--bg-raised);
+      border: 1px solid var(--border-quiet);
+      border-radius: 8px;
+      padding: 12px 14px;
+      font-family: var(--font-mono);
+      font-size: 12px;
+      color: var(--text-2);
+      text-align: left;
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 8px;
+    }
+    .terminal-box .cmd {
+      color: var(--text-1);
+      display: flex;
+      align-items: center;
+      gap: 6px;
+    }
+    .terminal-box .prompt {
+      color: var(--accent);
+      user-select: none;
+    }
+    .terminal-box .status-pill {
+      font-size: 11px;
+      padding: 2px 8px;
+      border-radius: 9999px;
+      font-family: var(--font-sans);
+      font-weight: 500;
+    }
+    .status-pill--ok {
+      background: color-mix(in srgb, var(--state-live) 15%, transparent);
+      color: var(--state-live);
+    }
+    .status-pill--error {
+      background: color-mix(in srgb, var(--state-failed) 15%, transparent);
+      color: var(--state-failed);
+    }
+    .foot {
+      font-size: 12px;
+      color: var(--text-3);
+    }
+  </style>
+</head>
+<body>
+  <div class="auth-container">
+    <div class="lockup">
+      <span class="mark">SV</span>
+      <span>SV Cloud</span>
+    </div>
+    <div class="card">
+      <div class="status-icon \${ok ? 'status-icon--ok' : 'status-icon--error'}">
+        \${ok
+          ? '<svg width="20" height="20" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 8.5 6.5 12 13 4.5"/></svg>'
+          : '<svg width="20" height="20" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M8 2.2 15 14H1Z"/><path d="M8 6.6v3.2"/><circle cx="8" cy="11.9" r="0.9" fill="currentColor"/></svg>'}
+      </div>
+      <div>
+        <h1>\${ok ? "You're signed in" : "Sign-in didn't finish"}</h1>
+        <p class="desc">\${ok ? "You can close this tab and return to your terminal." : "The sign-in request was not completed. Nothing changed on your account."}</p>
+      </div>
+      <div class="terminal-box">
+        <div class="cmd">
+          <span class="prompt">$</span>
+          <span>\${ok ? "svcloud" : "svcloud login"}</span>
+        </div>
+        <span class="status-pill \${ok ? 'status-pill--ok' : 'status-pill--error'}">
+          \${ok ? "Ready" : "Retry"}
+        </span>
+      </div>
+    </div>
+    <p class="foot">SV Cloud CLI</p>
+  </div>
+</body>
+</html>`;
 
 export function startLoopbackListener(): Promise<LoopbackListener> {
   return new Promise((resolve, reject) => {