@switchboard.spot/cli 0.2.1 → 0.2.2

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

@@ -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,21 +109,21 @@ export async function resolveAccountConfig(config) {
   }
 
   const base = config || resolveConfig();
-  const keychain = await readKeychainAccountToken();
-  if (keychain.token) {
+  const configDirToken = getConfigDirAccountToken();
+  if (configDirToken) {
     return {
       ...base,
-      accountToken: keychain.token,
-      accountTokenSource: "keychain",
+      accountToken: configDirToken,
+      accountTokenSource: "config-dir",
     };
   }
 
-  const configDirToken = getConfigDirAccountToken();
-  if (configDirToken) {
+  const keychain = await readKeychainAccountToken();
+  if (keychain.token) {
     return {
       ...base,
-      accountToken: configDirToken,
-      accountTokenSource: "config-dir",
+      accountToken: keychain.token,
+      accountTokenSource: "keychain",
     };
   }
 

package/lib/docsClient.js

@@ -0,0 +1,157 @@
+/**
+ * Public docs client used by CLI docs commands and the embedded MCP server.
+ */
+
+import { gatewayApiUrl, resolveAccountConfig, resolveConfig, accountApiUrl } from "./config.js";
+import { redactSecrets } from "./output.js";
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+export function docsBaseUrl(config = resolveConfig()) {
+  return gatewayApiUrl(config);
+}
+
+export async function listDocs({ config } = {}) {
+  const data = await publicJson("/docs", { config });
+  return redactSecrets(data);
+}
+
+export async function readDoc(id, { config } = {}) {
+  const data = await publicJson(`/docs/${encodeURIComponent(id)}`, { config });
+  return redactSecrets(data);
+}
+
+export async function searchDocs(query, { limit, config } = {}) {
+  const params = new URLSearchParams({ q: query });
+  if (limit != null) params.set("limit", String(limit));
+  const data = await publicJson(`/docs/search?${params}`, { config });
+  return redactSecrets(data);
+}
+
+export async function docsCapabilities({ config } = {}) {
+  const data = await publicJson("/docs/capabilities", { config });
+  return redactSecrets(data);
+}
+
+export async function openApi({ config } = {}) {
+  const data = await publicJson("/openapi.json", { config });
+  return redactSecrets(data);
+}
+
+export async function models({ config } = {}) {
+  const data = await publicJson("/models", { config });
+  return redactSecrets(data);
+}
+
+export async function integrationKit({ stack, config } = {}) {
+  let cfg;
+  try {
+    cfg = await resolveAccountConfig(config || resolveConfig());
+  } catch (error) {
+    return {
+      ok: false,
+      error: {
+        type: "keychain_unavailable",
+        message: error.message || "Could not read Switchboard account session from the OS keychain.",
+      },
+    };
+  }
+
+  if (!cfg.accountToken) {
+    return {
+      ok: false,
+      error: {
+        type: "authentication_required",
+        message: "Run `switchboard auth login`, then select a project with `switchboard projects use <id>`.",
+      },
+    };
+  }
+
+  if (!cfg.projectId) {
+    return {
+      ok: false,
+      error: {
+        type: "project_required",
+        message: "Select a project with `switchboard projects use <id>` or set SWITCHBOARD_PROJECT_ID.",
+      },
+    };
+  }
+
+  const params = new URLSearchParams({ project_id: cfg.projectId });
+  if (stack) params.set("stack", stack);
+
+  const url = `${accountApiUrl(cfg)}/integration_kit?${params}`;
+  const data = await fetchJson(url, {
+    headers: {
+      Authorization: `Bearer ${cfg.accountToken}`,
+      Accept: "application/json",
+    },
+  });
+
+  return redactSecrets(data);
+}
+
+export async function publicResource(name, options = {}) {
+  switch (name) {
+    case "docs":
+      return listDocs(options);
+    case "llms":
+      return readDoc("llms", options);
+    case "knowledge":
+      return readDoc("knowledge", options);
+    case "openapi":
+      return openApi(options);
+    case "integration-kit":
+      return integrationKit(options);
+    case "capabilities":
+      return docsCapabilities(options);
+    default:
+      throw new DocsClientError(`Unknown Switchboard resource: ${name}`, "not_found", 404);
+  }
+}
+
+async function publicJson(path, { config } = {}) {
+  const cfg = config || resolveConfig();
+  return fetchJson(`${docsBaseUrl(cfg)}${path}`, {
+    headers: { Accept: "application/json" },
+  });
+}
+
+async function fetchJson(url, init = {}) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+
+  let res;
+  try {
+    res = await fetch(url, { ...init, signal: controller.signal });
+  } catch (error) {
+    throw new DocsClientError(error.message || "Switchboard request failed.", "network_error", 3);
+  } finally {
+    clearTimeout(timeout);
+  }
+
+  const text = await res.text();
+  let data;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = { raw: text };
+  }
+
+  if (!res.ok) {
+    const message = data?.error?.message || text || `HTTP ${res.status}`;
+    const type = data?.error?.type || "http_error";
+    throw new DocsClientError(message, type, res.status);
+  }
+
+  return data;
+}
+
+export class DocsClientError extends Error {
+  constructor(message, type = "error", status = 1) {
+    super(message);
+    this.name = "DocsClientError";
+    this.type = type;
+    this.status = status;
+  }
+}

package/lib/mcpServer.js

@@ -0,0 +1,193 @@
+/**
+ * Embedded Switchboard MCP stdio server.
+ */
+
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import {
+  docsCapabilities,
+  integrationKit,
+  listDocs,
+  models,
+  openApi,
+  publicResource,
+  readDoc,
+  searchDocs,
+} from "./docsClient.js";
+import { redactSecrets } from "./output.js";
+
+const SERVER_VERSION = "0.1.0";
+
+export async function runMcpServer() {
+  const server = createMcpServer();
+  await server.connect(new StdioServerTransport());
+}
+
+export function createMcpServer() {
+  const server = new McpServer({
+    name: "@switchboard.spot/cli",
+    version: SERVER_VERSION,
+  });
+
+  registerResources(server);
+  registerTools(server);
+
+  return server;
+}
+
+function registerResources(server) {
+  registerJsonResource(server, "switchboard_docs", "switchboard://docs", "Public Switchboard docs catalog", () =>
+    listDocs(),
+  );
+  registerJsonResource(server, "switchboard_llms", "switchboard://llms", "Public llms.txt context", () =>
+    publicResource("llms"),
+  );
+  registerJsonResource(
+    server,
+    "switchboard_knowledge",
+    "switchboard://knowledge",
+    "Public Switchboard knowledge context",
+    () => publicResource("knowledge"),
+  );
+  registerJsonResource(server, "switchboard_openapi", "switchboard://openapi", "Switchboard OpenAPI schema", () =>
+    openApi(),
+  );
+  registerJsonResource(
+    server,
+    "switchboard_integration_kit",
+    "switchboard://integration-kit",
+    "Project Integration Kit for the selected CLI project",
+    () => integrationKit(),
+  );
+  registerJsonResource(
+    server,
+    "switchboard_capabilities",
+    "switchboard://capabilities",
+    "Switchboard hosted MCP capabilities",
+    () => docsCapabilities(),
+  );
+
+  server.registerResource(
+    "switchboard_doc",
+    new ResourceTemplate("switchboard://docs/{id}", {
+      list: async () => {
+        const catalog = await listDocs();
+        return {
+          resources: (catalog.data || []).map((doc) => ({
+            uri: `switchboard://docs/${doc.id}`,
+            name: doc.id,
+            title: doc.title,
+            description: doc.description,
+            mimeType: "text/markdown",
+          })),
+        };
+      },
+    }),
+    {
+      title: "Switchboard doc",
+      description: "Read one public Switchboard doc by stable id.",
+      mimeType: "text/markdown",
+    },
+    async (_uri, variables) => {
+      const doc = await readDoc(String(variables.id));
+      return {
+        contents: [
+          {
+            uri: `switchboard://docs/${doc.data.id}`,
+            mimeType: doc.data.content_type || "text/markdown",
+            text: redactText(doc.data.content),
+          },
+        ],
+      };
+    },
+  );
+}
+
+function registerTools(server) {
+  server.registerTool(
+    "switchboard_docs_search",
+    {
+      title: "Search Switchboard docs",
+      description: "Search public Switchboard docs and return bounded snippets.",
+      inputSchema: {
+        query: z.string().min(1),
+        limit: z.number().int().min(1).max(20).optional(),
+      },
+      annotations: { readOnlyHint: true },
+    },
+    async ({ query, limit }) => jsonTool(await searchDocs(query, { limit })),
+  );
+
+  server.registerTool(
+    "switchboard_docs_read",
+    {
+      title: "Read Switchboard doc",
+      description: "Read one public Switchboard doc by stable id.",
+      inputSchema: {
+        id: z.string().min(1),
+      },
+      annotations: { readOnlyHint: true },
+    },
+    async ({ id }) => jsonTool(await readDoc(id)),
+  );
+
+  server.registerTool(
+    "switchboard_integration_kit",
+    {
+      title: "Switchboard Integration Kit",
+      description: "Return Integration Kit data for the logged-in selected CLI project.",
+      inputSchema: {
+        stack: z.string().optional(),
+      },
+      annotations: { readOnlyHint: true },
+    },
+    async ({ stack }) => jsonTool(await integrationKit({ stack })),
+  );
+
+  server.registerTool(
+    "switchboard_models",
+    {
+      title: "Switchboard models",
+      description: "List public OpenAI-compatible Switchboard models.",
+      annotations: { readOnlyHint: true },
+    },
+    async () => jsonTool(await models()),
+  );
+}
+
+function registerJsonResource(server, name, uri, description, loader) {
+  server.registerResource(
+    name,
+    uri,
+    {
+      title: name,
+      description,
+      mimeType: "application/json",
+    },
+    async () => ({
+      contents: [
+        {
+          uri,
+          mimeType: "application/json",
+          text: JSON.stringify(redactSecrets(await loader()), null, 2),
+        },
+      ],
+    }),
+  );
+}
+
+function jsonTool(data) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(redactSecrets(data), null, 2),
+      },
+    ],
+  };
+}
+
+function redactText(text) {
+  return typeof text === "string" ? redactSecrets(text) : JSON.stringify(redactSecrets(text), null, 2);
+}