@switchboard.spot/cli 0.2.1 → 0.2.2

package/README.md

@@ -7,13 +7,13 @@ tests.
 ## Install
 
 ```bash
-npm install -g @switchboard.spot/cli
+npm install -g @switchboard.spot/cli@latest
 ```
 
 You can also run commands without a global install:
 
 ```bash
-npx @switchboard.spot/cli auth login
+npx @switchboard.spot/cli@latest auth login
 ```
 
 ## Build for local testing
@@ -54,21 +54,34 @@ If a first publish fails, `npm view @switchboard.spot/cli` will continue to retu
 
 ```bash
 switchboard auth login
+switchboard projects create --name "My App" --slug my-app
 switchboard setup --target client --json
-switchboard chat test --json
+switchboard projects update <project-id> --allowed-origins http://localhost:5173 --virtual-microservice-enabled true
+switchboard projects provision-turnstile <project-id>
+switchboard verify setup
+switchboard launch prepare --production-origin https://app.example.com --end-user-terms-url https://app.example.com/terms --end-user-privacy-url https://app.example.com/privacy --support-email support@example.com --contact-email owner@example.com --use-case "Browser chat for signed-in customers"
+switchboard verify publish
 ```
 
 Use `--json` for automation, CI, and coding agents.
 
-CLI account login does not create Client Gateway end-user sessions. End-user sign-up, sign-in, and refresh require a real browser/mobile challenge flow; use `@switchboard.spot/sdk` in the app, or use trusted-server/account APIs for automation.
+`setup --target client` writes public Client Gateway environment values such as `VITE_SWITCHBOARD_CLIENT_URL`; it does not prove chat or session readiness. Before SDK browser testing, configure the exact local or preview origin and provision Switchboard-managed Turnstile.
 
-Project-owned browser challenge keys are managed through the CLI:
+CLI account login does not create Client Gateway end-user sessions. End-user sign-up, sign-in, and refresh require the SDK-managed browser challenge; curl, Node scripts, CI, and CLI account login cannot mint browser sessions without running that real browser/mobile flow.
+
+For local Switchboard development, `switchboard verify setup --client-url http://localhost:4000/m/<slug>/v1` uses the built-in `dev_browser_challenge` token unless a scenario supplies an explicit `browserChallengeToken`. Hosted Switchboard should use managed Turnstile and the SDK-managed real browser challenge. A local sandbox smoke path is: configure allowed origin plus legal/support fields, create an anonymous session through the SDK or browser verification flow, then call Client Gateway chat.
+
+Model discovery is global. Use `GET /v1/models` for OpenAI-compatible discovery or `GET /v1/catalog/models` for catalog/pricing metadata; Client Gateway chat is project-scoped at `/m/<slug>/v1/chat/completions`.
+
+Switchboard-managed Turnstile is the default production path. Developers do not paste Cloudflare secrets into the CLI or repo files:
 
 ```bash
-switchboard projects turnstile <project-id> --site-key <site-key> --secret-key <secret-key>
+switchboard projects provision-turnstile <project-id>
 switchboard projects turnstile <project-id> --clear
 ```
 
+If `switchboard projects provision-turnstile --help` is missing, upgrade with `npm install -g @switchboard.spot/cli@latest` before trying dashboard automation or manual Cloudflare keys.
+
 ## Configuration
 
 The CLI stores non-secret settings in `~/.switchboard/config.json` by default.

package/bin/switchboard.js

@@ -18,11 +18,13 @@ import { registerBillingCommands } from "../lib/commands/billing.js";
 import { registerEnvCommands } from "../lib/commands/env.js";
 import { registerUsageCommands } from "../lib/commands/usage.js";
 import { registerIntegrationCommands } from "../lib/commands/integration.js";
+import { registerDocsCommands } from "../lib/commands/docs.js";
 import { registerInitCommand } from "../lib/commands/init.js";
 import { registerSetupCommand } from "../lib/commands/setup.js";
 import { registerHealthCommand } from "../lib/commands/health.js";
 import { registerDoctorCommand } from "../lib/commands/doctor.js";
 import { registerVerifyCommands } from "../lib/commands/verify.js";
+import { registerLaunchCommands } from "../lib/commands/launch.js";
 
 const program = new Command();
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -42,6 +44,7 @@ registerSetupCommand(program);
 registerHealthCommand(program);
 registerDoctorCommand(program);
 registerVerifyCommands(program);
+registerLaunchCommands(program);
 registerAuth(program);
 registerAccountCommands(program);
 registerWorkspacesCommands(program);
@@ -53,8 +56,9 @@ registerBillingCommands(program);
 registerEnvCommands(program);
 registerUsageCommands(program);
 registerIntegrationCommands(program);
+registerDocsCommands(program);
 
-program.parse();
+await program.parseAsync();
 
 if (!process.argv.slice(2).length) {
   program.outputHelp();

package/lib/commands/auth.js

@@ -317,9 +317,11 @@ function waitForCallback(callbackServer, timeoutSeconds, json) {
   });
 }
 
-function callbackPage(title, message, tone) {
-  const accent = tone === "success" ? "#28d17c" : "#ff6b6b";
-  const mark = tone === "success" ? "✓" : "!";
+export function callbackPage(title, message, tone) {
+  const success = tone === "success";
+  const accent = success ? "#14b8a6" : "#ef4444";
+  const accentSoft = success ? "#ccfbf1" : "#fee2e2";
+  const mark = success ? "✓" : "!";
 
   return `<!doctype html>
 <html lang="en">
@@ -329,74 +331,181 @@ function callbackPage(title, message, tone) {
     <title>${escapeHtml(title)}</title>
     <style>
       :root {
-        color-scheme: dark;
+        color-scheme: light dark;
         font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
-        background: #05070d;
-        color: #f7f7fb;
+        background: #ffffff;
+        color: #1f2937;
       }
+      * { box-sizing: border-box; }
       body {
         min-height: 100vh;
         margin: 0;
-        display: grid;
-        place-items: center;
+        color: #1f2937;
         background:
-          radial-gradient(circle at 20% 20%, rgba(68, 109, 255, 0.22), transparent 32rem),
-          radial-gradient(circle at 80% 10%, rgba(40, 209, 124, 0.16), transparent 26rem),
-          linear-gradient(135deg, #05070d 0%, #101526 100%);
+          repeating-linear-gradient(125deg, transparent, transparent 6px, #e8e8e8 6px, #e8e8e8 7px),
+          #ffffff;
+      }
+      .page {
+        min-height: 100vh;
+        width: min(100%, 80rem);
+        margin: 0 auto;
+        display: flex;
+        flex-direction: column;
+        border-inline: 1px solid #e5e7eb;
+        background:
+          repeating-linear-gradient(125deg, transparent, transparent 6px, #e8e8e8 6px, #e8e8e8 7px),
+          #ffffff;
+      }
+      header {
+        height: 4.5rem;
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        padding: 0 1.5rem;
+        border-bottom: 1px solid #e5e7eb;
+        background: rgba(255, 255, 255, 0.88);
+        backdrop-filter: blur(12px);
+      }
+      .logo {
+        color: #1f2937;
+        font-size: 0.95rem;
+        font-weight: 800;
+        letter-spacing: 0;
+      }
+      .pill {
+        border: 1px solid #e5e7eb;
+        border-radius: 999px;
+        padding: 0.45rem 0.8rem;
+        background: #ffffff;
+        color: #4b5563;
+        font-size: 0.82rem;
+        font-weight: 600;
       }
       main {
-        width: min(92vw, 34rem);
-        border: 1px solid rgba(255, 255, 255, 0.12);
-        border-radius: 1.5rem;
-        padding: 2rem;
-        background: rgba(10, 14, 27, 0.82);
-        box-shadow: 0 2rem 6rem rgba(0, 0, 0, 0.38);
+        flex: 1;
+        display: grid;
+        place-items: center;
+        padding: 5rem 1.5rem;
+      }
+      .panel {
+        width: min(100%, 34rem);
+        border: 1px solid #e5e7eb;
+        border-radius: 0.5rem;
+        padding: clamp(1.5rem, 5vw, 2.25rem);
+        background: rgba(255, 255, 255, 0.94);
+        box-shadow:
+          0 1.34368px 0.537473px -0.625px rgba(0, 0, 0, 0.09),
+          0 15.5969px 6.23877px -3.125px rgba(0, 0, 0, 0.07),
+          0 43.962px 17.5848px -4.375px rgba(0, 0, 0, 0.04);
         text-align: center;
-        backdrop-filter: blur(18px);
       }
-      .brand {
-        margin: 0 0 1.5rem;
-        color: rgba(247, 247, 251, 0.58);
+      .eyebrow {
+        margin: 0 0 1.25rem;
+        color: #4b5563;
         font-size: 0.78rem;
         font-weight: 700;
-        letter-spacing: 0.18em;
+        letter-spacing: 0.12em;
         text-transform: uppercase;
       }
       .mark {
-        width: 3.5rem;
-        height: 3.5rem;
+        width: 4rem;
+        height: 4rem;
         margin: 0 auto 1.25rem;
         display: grid;
         place-items: center;
-        border-radius: 999px;
+        border: 1px solid ${accent};
+        border-radius: 0.5rem;
         background: ${accent};
-        color: #05070d;
-        font-size: 1.8rem;
+        color: #111827;
+        font-size: 1.9rem;
         font-weight: 900;
-        box-shadow: 0 0 2.5rem ${accent}55;
+        box-shadow: 0 18px 40px -20px ${accent};
       }
       h1 {
         margin: 0;
-        font-size: clamp(1.75rem, 5vw, 2.45rem);
-        line-height: 1.05;
-        letter-spacing: -0.04em;
+        color: #1f2937;
+        font-size: clamp(2rem, 7vw, 3.5rem);
+        line-height: 0.98;
+        letter-spacing: 0;
       }
       p {
         margin: 1rem auto 0;
         max-width: 26rem;
-        color: rgba(247, 247, 251, 0.66);
+        color: #4b5563;
         font-size: 1rem;
         line-height: 1.65;
       }
+      .status {
+        display: inline-flex;
+        align-items: center;
+        gap: 0.5rem;
+        margin-top: 1.5rem;
+        border: 1px solid ${accent};
+        border-radius: 999px;
+        padding: 0.5rem 0.8rem;
+        background: ${accentSoft};
+        color: #1f2937;
+        font-size: 0.86rem;
+        font-weight: 700;
+      }
+      @media (prefers-color-scheme: dark) {
+        :root {
+          background: #020617;
+          color: #f3f4f6;
+        }
+        body {
+          color: #f3f4f6;
+          background:
+            repeating-linear-gradient(125deg, transparent, transparent 6px, rgba(55, 65, 81, 0.6) 6px, rgba(55, 65, 81, 0.6) 7px),
+            #020617;
+        }
+        .page {
+          border-color: #1f2937;
+          background:
+            repeating-linear-gradient(125deg, transparent, transparent 6px, rgba(55, 65, 81, 0.6) 6px, rgba(55, 65, 81, 0.6) 7px),
+            #020617;
+        }
+        header,
+        .panel {
+          border-color: #1f2937;
+          background: rgba(2, 6, 23, 0.94);
+        }
+        .logo,
+        h1 {
+          color: #f3f4f6;
+        }
+        .pill,
+        .eyebrow,
+        p {
+          color: #d1d5db;
+        }
+        .pill {
+          border-color: #1f2937;
+          background: #111827;
+        }
+        .mark,
+        .status {
+          color: #020617;
+        }
+      }
     </style>
   </head>
   <body>
-    <main>
-      <p class="brand">Switchboard CLI</p>
-      <div class="mark" aria-hidden="true">${mark}</div>
-      <h1>${escapeHtml(title)}</h1>
-      <p>${escapeHtml(message)}</p>
-    </main>
+    <div class="page">
+      <header>
+        <div class="logo">Switchboard</div>
+        <div class="pill">CLI session</div>
+      </header>
+      <main>
+        <section class="panel" aria-labelledby="callback-title">
+          <p class="eyebrow">Switchboard CLI</p>
+          <div class="mark" aria-hidden="true">${mark}</div>
+          <h1 id="callback-title">${escapeHtml(title)}</h1>
+          <p>${escapeHtml(message)}</p>
+          <div class="status">${success ? "Session approved" : "Session not approved"}</div>
+        </section>
+      </main>
+    </div>
   </body>
 </html>`;
 }

package/lib/commands/billing.js

@@ -2,6 +2,7 @@
  * Developer billing commands.
  */
 
+import { spawn } from "node:child_process";
 import { accountRequest } from "../client.js";
 import { emit, globalFlags, printList } from "../output.js";
 
@@ -51,6 +52,40 @@ export function registerBillingCommands(program) {
       emit(flags.json ? data : `Created top-up ${data.id}`, flags);
     });
 
+  billing
+    .command("checkout")
+    .description("Create a Stripe-hosted developer billing checkout URL")
+    .requiredOption("--success-url <url>")
+    .requiredOption("--cancel-url <url>")
+    .option("--open", "Open checkout URL in the default browser")
+    .action(async (opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("POST", "/billing/checkout", {
+        body: {
+          success_url: opts.successUrl,
+          cancel_url: opts.cancelUrl,
+        },
+        json: flags.json,
+      });
+      if (opts.open) openUrl(data.checkout_url);
+      emit(flags.json ? data : data.checkout_url, flags);
+    });
+
+  billing
+    .command("portal")
+    .description("Create a Stripe-hosted developer billing portal URL")
+    .requiredOption("--return-url <url>")
+    .option("--open", "Open portal URL in the default browser")
+    .action(async (opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("POST", "/billing/portal", {
+        body: { return_url: opts.returnUrl },
+        json: flags.json,
+      });
+      if (opts.open) openUrl(data.url);
+      emit(flags.json ? data : data.url, flags);
+    });
+
   billing
     .command("prepaid")
     .description("Update prepaid wallet settings")
@@ -85,3 +120,11 @@ export function registerBillingCommands(program) {
       emit(flags.json ? data : "Updated prepaid settings", flags);
     });
 }
+
+function openUrl(url) {
+  const command =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  const child = spawn(command, args, { stdio: "ignore", detached: true });
+  child.unref();
+}

package/lib/commands/docs.js

@@ -0,0 +1,176 @@
+/**
+ * Hosted docs and embedded MCP commands.
+ */
+
+import {
+  docsCapabilities,
+  listDocs,
+  readDoc,
+  searchDocs,
+  DocsClientError,
+} from "../docsClient.js";
+import { runMcpServer } from "../mcpServer.js";
+import { emit, fail, globalFlags, redactSecrets } from "../output.js";
+
+export function registerDocsCommands(program) {
+  const docs = program.command("docs").description("Public docs and MCP server");
+
+  docs
+    .command("list")
+    .description("List public Switchboard docs")
+    .option("--json", "Output JSON to stdout")
+    .action(async (_opts, cmd) => {
+      await runDocsAction(cmd, async (flags) => {
+        const result = await listDocs();
+        if (jsonMode(cmd)) return emit(result, { json: true });
+
+        for (const doc of result.data || []) {
+          emit(`${doc.id}\t${doc.title}\t${doc.url}`, flags);
+        }
+      });
+    });
+
+  docs
+    .command("read")
+    .description("Read one public Switchboard doc")
+    .argument("<id>", "Stable public doc id")
+    .option("--json", "Output JSON to stdout")
+    .action(async (id, _opts, cmd) => {
+      await runDocsAction(cmd, async (flags) => {
+        const result = await readDoc(id);
+        if (jsonMode(cmd)) return emit(result, { json: true });
+        emit(result.data?.content || "", flags);
+      });
+    });
+
+  docs
+    .command("search")
+    .description("Search public Switchboard docs")
+    .argument("<query>", "Search query")
+    .option("--limit <count>", "Maximum number of snippets", parseInteger)
+    .option("--json", "Output JSON to stdout")
+    .action(async (query, opts, cmd) => {
+      await runDocsAction(cmd, async (flags) => {
+        const result = await searchDocs(query, { limit: opts.limit });
+        if (jsonMode(cmd)) return emit(result, { json: true });
+
+        for (const match of result.data || []) {
+          emit(`${match.id}\t${match.title}\n${match.snippet}\n`, flags);
+        }
+      });
+    });
+
+  docs
+    .command("mcp")
+    .description("Start the embedded Switchboard MCP stdio server")
+    .action(async () => {
+      await runMcpServer();
+    });
+
+  docs
+    .command("mcp-config")
+    .description("Print MCP client configuration")
+    .requiredOption("--client <client>", "MCP client: codex, claude, or cursor")
+    .option("--json", "Output JSON to stdout")
+    .action(async (opts, cmd) => {
+      const client = opts.client.toLowerCase();
+      const config = mcpConfig(client);
+
+      if (!config) {
+        fail("Unsupported MCP client. Expected one of: codex, claude, cursor.", 1, jsonMode(cmd));
+      }
+
+      if (jsonMode(cmd)) {
+        emit(config, { json: true });
+      } else {
+        emit(formatConfig(client, config), globalFlags(cmd));
+      }
+    });
+
+  docs
+    .command("capabilities")
+    .description("Print hosted MCP capability metadata")
+    .option("--json", "Output JSON to stdout")
+    .action(async (_opts, cmd) => {
+      await runDocsAction(cmd, async (flags) => {
+        const result = await docsCapabilities();
+        emit(result, { json: jsonMode(cmd), quiet: flags.quiet });
+      });
+    });
+}
+
+async function runDocsAction(cmd, callback) {
+  const flags = globalFlags(cmd);
+
+  try {
+    await callback(flags);
+  } catch (error) {
+    if (error instanceof DocsClientError) {
+      fail(error.message, exitCode(error.status), jsonMode(cmd), error.type);
+    }
+
+    fail(error.message || "Switchboard docs command failed.", 1, jsonMode(cmd));
+  }
+}
+
+function jsonMode(cmd) {
+  return Boolean(cmd.opts?.().json || globalFlags(cmd).json);
+}
+
+function exitCode(status) {
+  if (status === 401 || status === 403) return 2;
+  if (status >= 500 || status === 3) return 3;
+  return 1;
+}
+
+function parseInteger(value) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed)) {
+    throw new Error("Limit must be an integer.");
+  }
+  return parsed;
+}
+
+function mcpConfig(client) {
+  const command = "switchboard";
+  const args = ["docs", "mcp"];
+
+  switch (client) {
+    case "codex":
+      return {
+        mcp_servers: {
+          switchboard: {
+            command,
+            args,
+            env: {
+              SWITCHBOARD_BASE_URL: "https://switchboard.spot",
+            },
+          },
+        },
+      };
+    case "claude":
+    case "cursor":
+      return {
+        mcpServers: {
+          switchboard: {
+            command,
+            args,
+            env: {
+              SWITCHBOARD_BASE_URL: "https://switchboard.spot",
+            },
+          },
+        },
+      };
+    default:
+      return null;
+  }
+}
+
+function formatConfig(client, config) {
+  return [
+    `# ${client} MCP config`,
+    "```json",
+    JSON.stringify(redactSecrets(config), null, 2),
+    "```",
+  ].join("\n");
+}

package/lib/commands/doctor.js

@@ -67,8 +67,57 @@ export function registerDoctorCommand(program) {
         checks.push({ name: "project", ok: false, error: "No project selected" });
       }
 
+      if (config.virtualMicroserviceUrl) {
+        checks.push(
+          await check("client_gateway_config", async () => {
+            const res = await fetch(new URL("client/config", ensureTrailingSlash(config.virtualMicroserviceUrl)).href, {
+              headers: { Accept: "application/json" },
+            });
+            const data = await readJson(res);
+            if (!res.ok) {
+              throw new Error(data?.error?.message || data?.message || `HTTP ${res.status}`);
+            }
+
+            const productionSafety = data?.production_safety ?? null;
+            const productionBlocked = productionSafety?.status === "blocked";
+
+            return {
+              status: res.status,
+              clientUrl: config.virtualMicroserviceUrl,
+              browserChallengeProvider: data?.browser_challenge?.provider ?? null,
+              production_safety: productionSafety,
+              warning: productionBlocked,
+              warningCode: productionBlocked ? "production_safety_blocked" : null,
+              warningMessage: productionBlocked
+                ? "Sandbox Client Gateway config is reachable, but production launch blockers remain."
+                : null,
+            };
+          }),
+        );
+      } else {
+        checks.push({
+          name: "client_gateway_config",
+          ok: false,
+          error: "No SWITCHBOARD_CLIENT_URL or VITE_SWITCHBOARD_CLIENT_URL configured",
+        });
+      }
+
       const ok = checks.every((item) => item.ok);
       emit({ object: "doctor_report", ok, baseUrl: config.baseUrl, checks }, flags);
       if (!ok) process.exit(1);
+      process.exit(0);
     });
 }
+
+function ensureTrailingSlash(value) {
+  return String(value).endsWith("/") ? String(value) : `${value}/`;
+}
+
+async function readJson(response) {
+  const text = await response.text();
+  try {
+    return text ? JSON.parse(text) : null;
+  } catch {
+    return { raw: text };
+  }
+}

package/lib/commands/init.js

@@ -33,10 +33,12 @@ export function agentManifest(config) {
     env: envBlock(clientUrl),
     checklist: [
       "switchboard setup --target client --json",
-      "export VITE_SWITCHBOARD_CLIENT_URL=<client_url from integrations show>",
+      "export VITE_SWITCHBOARD_CLIENT_URL=<client_url from integration kit>",
       "Use mountSwitchboardWidget({ clientUrl, target }) in browser apps",
       "Use createSwitchboardClient({ clientUrl, storage }) only for custom UI",
-      "switchboard billing top-up --amount-micros <micros>",
+      "switchboard verify setup",
+      "switchboard launch prepare --production-origin https://app.example.com --end-user-terms-url https://app.example.com/terms --end-user-privacy-url https://app.example.com/privacy --support-email support@example.com --contact-email owner@example.com --use-case \"Browser chat for signed-in customers\"",
+      "switchboard verify publish",
     ],
     browser_smoke_test: `import { mountSwitchboardWidget } from "@switchboard.spot/sdk";