@switchboard.spot/cli 0.2.0 → 0.2.2

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/env.js

@@ -88,7 +88,9 @@ export async function configureEnvironment(
   const envUpdates = {};
 
   if (mode === "client" || mode === "both") {
-    envUpdates.SWITCHBOARD_CLIENT_URL = kit.client_url || kit.virtual_microservice_url;
+    const clientUrl = kit.client_url || kit.virtual_microservice_url;
+    envUpdates.SWITCHBOARD_CLIENT_URL = clientUrl;
+    envUpdates.VITE_SWITCHBOARD_CLIENT_URL = clientUrl;
   }
 
   if (mode === "server" || mode === "both") {

package/lib/commands/init.js

@@ -14,6 +14,7 @@ import { emit } from "../output.js";
  */
 function envBlock(clientUrl) {
   return `SWITCHBOARD_CLIENT_URL=${clientUrl}
+VITE_SWITCHBOARD_CLIENT_URL=${clientUrl}
 `;
 }
 
@@ -32,15 +33,17 @@ export function agentManifest(config) {
     env: envBlock(clientUrl),
     checklist: [
       "switchboard setup --target client --json",
-      "export 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/sdk";
+    browser_smoke_test: `import { mountSwitchboardWidget } from "@switchboard.spot/sdk";
 
 mountSwitchboardWidget({
-  clientUrl: process.env.SWITCHBOARD_CLIENT_URL ?? "${clientUrl}",
+  clientUrl: import.meta.env.VITE_SWITCHBOARD_CLIENT_URL ?? "${clientUrl}",
   target: "#switchboard",
 });`,
     automation_note:

package/lib/commands/launch.js

@@ -0,0 +1,192 @@
+/**
+ * Production launch orchestration commands.
+ */
+
+import { accountRequest } from "../client.js";
+import { saveConfig } from "../config.js";
+import { emit, fail, globalFlags } from "../output.js";
+import { buildProductionAccessRequestBody } from "./projects.js";
+
+export function registerLaunchCommands(program) {
+  const launch = program.command("launch").description("Production launch workflows");
+
+  launch
+    .command("prepare")
+    .description("Prepare a project for production Client Gateway launch")
+    .option("--project-id <id>", "Existing project id")
+    .option("--project-name <name>", "Create a project when no project id is provided")
+    .option("--project-slug <slug>", "Slug for a project created by this command")
+    .requiredOption(
+      "--production-origin <origin>",
+      "Exact HTTPS production origin, for example https://app.example.com",
+    )
+    .requiredOption("--end-user-terms-url <url>")
+    .requiredOption("--end-user-privacy-url <url>")
+    .option("--support-url <url>")
+    .requiredOption("--support-email <email>")
+    .requiredOption("--contact-email <email>")
+    .requiredOption("--use-case <text>")
+    .option("--expected-monthly-volume <volume>")
+    .option("--needed-billing-mode <mode>", "Billing mode needed for production", "developer_paid")
+    .option("--notes <text>")
+    .option("--idempotency-key <key>")
+    .action(async (opts, cmd) => {
+      const flags = globalFlags(cmd);
+      validateLaunchOptions(opts, flags);
+
+      const project = await ensureProject(opts, flags);
+      const idempotencyKey = opts.idempotencyKey || `launch-prepare-project-${project.id}`;
+
+      const configured = await updateLaunchProject(project.id, opts, flags);
+      const challenge = await provisionManagedTurnstile(project.id, idempotencyKey, flags);
+      const access = await requestAccessIfNeeded(project.id, configured, opts, flags);
+      const readiness = await fetchProject(project.id, flags);
+
+      emit(
+        flags.json
+          ? launchSummary(readiness, challenge, access)
+          : humanLaunchSummary(readiness, access),
+        flags,
+      );
+    });
+}
+
+function validateLaunchOptions(opts, flags) {
+  if (!productionHttpsOrigin(opts.productionOrigin)) {
+    fail("--production-origin must be an exact HTTPS production origin", 1, flags.json);
+  }
+  if ((opts.projectName && !opts.projectSlug) || (!opts.projectName && opts.projectSlug)) {
+    fail("--project-name and --project-slug must be provided together", 1, flags.json);
+  }
+}
+
+async function ensureProject(opts, flags) {
+  if (opts.projectId) return fetchProject(opts.projectId, flags);
+
+  if (opts.projectName) {
+    const { data } = await accountRequest("POST", "/projects", {
+      body: { name: opts.projectName, slug: opts.projectSlug },
+      json: flags.json,
+    });
+    saveProjectConfig(data);
+    return data;
+  }
+
+  const { data } = await accountRequest("GET", "/me", { json: flags.json });
+  if (!data.project?.id) {
+    fail(
+      "No default project is selected. Use --project-id or --project-name with --project-slug.",
+      1,
+      flags.json,
+    );
+  }
+  return data.project;
+}
+
+async function updateLaunchProject(projectId, opts, flags) {
+  const body = {
+    allowed_origins: [opts.productionOrigin],
+    end_user_terms_url: opts.endUserTermsUrl,
+    end_user_privacy_url: opts.endUserPrivacyUrl,
+    support_email: opts.supportEmail,
+    virtual_microservice_enabled: true,
+  };
+
+  if (opts.supportUrl) body.support_url = opts.supportUrl;
+
+  const { data } = await accountRequest("PATCH", `/projects/${projectId}`, {
+    body,
+    json: flags.json,
+  });
+  saveProjectConfig(data);
+  return data;
+}
+
+async function provisionManagedTurnstile(projectId, idempotencyKey, flags) {
+  const { data } = await accountRequest("POST", `/projects/${projectId}/turnstile/provision`, {
+    body: { idempotency_key: `${idempotencyKey}:turnstile` },
+    json: flags.json,
+  });
+  return data;
+}
+
+async function requestAccessIfNeeded(projectId, project, opts, flags) {
+  if (project.production_access_status === "approved") {
+    return {
+      object: "production_access_request",
+      project_id: project.id,
+      project_production_access_status: "approved",
+      status: "approved",
+    };
+  }
+
+  const { data } = await accountRequest("POST", `/projects/${projectId}/production_access_request`, {
+    body: buildProductionAccessRequestBody(opts),
+    json: flags.json,
+  });
+  return data;
+}
+
+async function fetchProject(projectId, flags) {
+  const { data } = await accountRequest("GET", `/projects/${projectId}`, { json: flags.json });
+  return data;
+}
+
+function saveProjectConfig(project) {
+  saveConfig({
+    projectId: String(project.id),
+    apiKey: null,
+    virtualMicroserviceUrl: project.virtual_microservice_url || null,
+    endUserSession: null,
+  });
+}
+
+function launchSummary(project, challenge, access) {
+  return {
+    object: "launch_prepare_result",
+    project_id: project.id,
+    project_slug: project.slug,
+    virtual_microservice_url: project.virtual_microservice_url,
+    browser_challenge: challenge,
+    production_access: access,
+    production_safety: project.production_safety,
+    next_steps: [
+      "Run switchboard verify setup.",
+      "Use the SDK-managed browser challenge to mint browser sessions.",
+      "Run switchboard verify publish after approval and billing readiness are complete.",
+    ],
+  };
+}
+
+function humanLaunchSummary(project, access) {
+  const blocked = (project.production_safety?.checks || [])
+    .filter((check) => check.status !== "ready")
+    .map((check) => check.id);
+
+  return [
+    `Prepared project ${project.name} (${project.id})`,
+    `Client Gateway: ${project.virtual_microservice_url}`,
+    `Production access: ${access.project_production_access_status || access.status}`,
+    `Readiness: ${project.production_safety?.status || "unknown"}`,
+    blocked.length ? `Blocked checks: ${blocked.join(", ")}` : "Blocked checks: none",
+    "Next: run switchboard verify setup, then switchboard verify publish after approval and billing readiness.",
+  ].join("\n");
+}
+
+function productionHttpsOrigin(origin) {
+  try {
+    const url = new URL(origin);
+    return (
+      url.protocol === "https:" &&
+      url.username === "" &&
+      url.password === "" &&
+      url.pathname === "/" &&
+      url.search === "" &&
+      url.hash === "" &&
+      !["localhost", "127.0.0.1", "::1"].includes(url.hostname) &&
+      !url.hostname.includes("*")
+    );
+  } catch {
+    return false;
+  }
+}

package/lib/commands/projects.js

@@ -90,10 +90,9 @@ export function registerProjectsCommands(program) {
 
   projects
     .command("turnstile <id>")
-    .description("Configure project-owned Turnstile keys")
+    .description("Configure project-owned public Turnstile metadata")
     .option("--site-key <key>")
-    .option("--secret-key <key>")
-    .option("--clear", "Remove project-owned Turnstile keys")
+    .option("--clear", "Remove project-owned Turnstile metadata")
     .action(async (id, opts, cmd) => {
       const flags = globalFlags(cmd);
       const body = buildTurnstileBody(opts);
@@ -104,6 +103,39 @@ export function registerProjectsCommands(program) {
       emit(flags.json ? data : `Updated Turnstile settings for ${data.name}`, flags);
     });
 
+  projects
+    .command("provision-turnstile <id>")
+    .description("Provision Switchboard-managed Turnstile for a project")
+    .option("--idempotency-key <key>")
+    .action(async (id, opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const body = {};
+      if (opts.idempotencyKey) body.idempotency_key = opts.idempotencyKey;
+
+      const { data } = await accountRequest("POST", `/projects/${id}/turnstile/provision`, {
+        body,
+        json: flags.json,
+      });
+      emit(flags.json ? data : `Provisioned managed Turnstile for project ${id}`, flags);
+    });
+
+  projects
+    .command("request-production-access <id>")
+    .description("Submit a production access request")
+    .requiredOption("--contact-email <email>")
+    .requiredOption("--use-case <text>")
+    .option("--expected-monthly-volume <volume>")
+    .option("--needed-billing-mode <mode>", "Billing mode needed for production", "developer_paid")
+    .option("--notes <text>")
+    .action(async (id, opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("POST", `/projects/${id}/production_access_request`, {
+        body: buildProductionAccessRequestBody(opts),
+        json: flags.json,
+      });
+      emit(flags.json ? data : `Submitted production access request for project ${id}`, flags);
+    });
+
   projects
     .command("use <id>")
     .description("Set default project for subsequent commands")
@@ -186,7 +218,21 @@ export function buildTurnstileBody(opts) {
 
   const body = {};
   if (opts.siteKey) body.turnstile_site_key = opts.siteKey;
-  if (opts.secretKey) body.turnstile_secret_key = opts.secretKey;
+  return body;
+}
+
+export function buildProductionAccessRequestBody(opts) {
+  const body = {
+    contact_email: opts.contactEmail,
+    use_case: opts.useCase,
+    needed_billing_mode: opts.neededBillingMode || "developer_paid",
+  };
+
+  if (opts.expectedMonthlyVolume) {
+    body.expected_monthly_volume = opts.expectedMonthlyVolume;
+  }
+  if (opts.notes) body.notes = opts.notes;
+
   return body;
 }
 

package/lib/commands/setup.js

@@ -53,13 +53,16 @@ function normalizeSetupTarget(target, json) {
 }
 
 function smokeCheck(result) {
+  const clientEnvConfigured =
+    result.changed.includes("VITE_SWITCHBOARD_CLIENT_URL") ||
+    result.skipped.includes("VITE_SWITCHBOARD_CLIENT_URL") ||
+    result.changed.includes("SWITCHBOARD_CLIENT_URL") ||
+    result.skipped.includes("SWITCHBOARD_CLIENT_URL");
+
   return {
     ok: true,
     checks: [
-      result.changed.includes("SWITCHBOARD_CLIENT_URL") ||
-        result.skipped.includes("SWITCHBOARD_CLIENT_URL")
-        ? "client_env"
-        : null,
+      clientEnvConfigured ? "client_env" : null,
       result.changed.includes("SWITCHBOARD_BASE_URL") ||
         result.skipped.includes("SWITCHBOARD_BASE_URL")
         ? "server_env"

package/lib/config.js

@@ -6,7 +6,7 @@
 import fs from "fs";
 import os from "os";
 import path from "path";
-import { getAccountToken } from "./credentialStore.js";
+import { getAccountToken, getConfigDirAccountToken } from "./credentialStore.js";
 
 const CONFIG_DIR =
   process.env.SWITCHBOARD_CONFIG_DIR || path.join(os.homedir(), ".switchboard");
@@ -74,7 +74,10 @@ export function resolveConfig() {
   return {
     baseUrl: process.env.SWITCHBOARD_BASE_URL || file.baseUrl || DEFAULT_BASE_URL,
     virtualMicroserviceUrl:
-      process.env.SWITCHBOARD_CLIENT_URL || file.virtualMicroserviceUrl || null,
+      process.env.SWITCHBOARD_CLIENT_URL ||
+      process.env.VITE_SWITCHBOARD_CLIENT_URL ||
+      file.virtualMicroserviceUrl ||
+      null,
     accountToken: null,
     accountTokenSource: null,
     apiKey: process.env.SWITCHBOARD_API_KEY || null,
@@ -106,15 +109,43 @@ export async function resolveAccountConfig(config) {
   }
 
   const base = config || resolveConfig();
-  const token = await getAccountToken();
+  const configDirToken = getConfigDirAccountToken();
+  if (configDirToken) {
+    return {
+      ...base,
+      accountToken: configDirToken,
+      accountTokenSource: "config-dir",
+    };
+  }
+
+  const keychain = await readKeychainAccountToken();
+  if (keychain.token) {
+    return {
+      ...base,
+      accountToken: keychain.token,
+      accountTokenSource: "keychain",
+    };
+  }
+
+  if (keychain.error) {
+    throw keychain.error;
+  }
 
   return {
     ...base,
-    accountToken: token,
-    accountTokenSource: token ? "keychain" : null,
+    accountToken: null,
+    accountTokenSource: null,
   };
 }
 
+async function readKeychainAccountToken() {
+  try {
+    return { token: await getAccountToken(), error: null };
+  } catch (error) {
+    return { token: null, error };
+  }
+}
+
 /**
  * Account API base URL (host + /v1/account).
  */