@switchboard.spot/cli 0.2.1 → 0.2.3

package/lib/commands/setup.js

@@ -3,22 +3,53 @@
  */
 
 import { configureEnvironment } from "./env.js";
-import { emit, fail, globalFlags } from "../output.js";
+import { accountRequest } from "../client.js";
+import { emit, fail, globalFlags, redactSecrets } from "../output.js";
+import { resolveConfig } from "../config.js";
+import { runDoctorChecks } from "./doctor.js";
+import {
+  ensureProject,
+  fetchProject,
+  provisionManagedTurnstile,
+  requestAccessIfNeeded,
+  saveProjectConfig,
+  validateLaunchOptions,
+} from "./launch.js";
 
 export function registerSetupCommand(program) {
-  program
+  const setup = program
     .command("setup")
-    .description("Configure Switchboard for client apps, server apps, or both")
+    .description("Configure browser-ready Switchboard projects");
+
+  setup
+    .command("project")
+    .description("Create or configure a browser-ready Switchboard project")
+    .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("--origin <origin>", "Exact local, preview, or sandbox browser origin")
     .option("--target <target>", "client, server, or both", "client")
     .option("--file <path>", "Local env file to update", ".env.local")
     .option("--secret-target <target>", "local or exec", "local")
     .option("--secret-command <command>", "Command that stores secrets from stdin JSON")
-    .option("--project-id <id>", "Override selected project")
-    .option("--force", "Replace existing Switchboard-managed values")
+    .option("--force", "Replace existing Switchboard-managed env values and project origins")
+    .option(
+      "--production-origin <origin>",
+      "Exact HTTPS production origin, for example https://app.example.com",
+    )
+    .option("--end-user-terms-url <url>")
+    .option("--end-user-privacy-url <url>")
+    .option("--support-url <url>")
+    .option("--support-email <email>")
+    .option("--contact-email <email>")
+    .option("--use-case <text>")
+    .option("--expected-monthly-volume <volume>")
+    .option("--needed-billing-mode <mode>", "Billing mode needed for production")
+    .option("--notes <text>")
     .action(async (opts, cmd) => {
       const flags = globalFlags(cmd);
-      const result = await setupSwitchboard(opts, { json: flags.json });
-      emit(flags.json ? result : humanSetupMessage(result), flags);
+      const result = await setupProject(opts, { json: flags.json });
+      emit(flags.json ? result : humanProjectSetupMessage(result), flags);
     });
 }
 
@@ -77,3 +108,247 @@ function humanSetupMessage(result) {
   const skipped = result.skipped.length > 0 ? ` Skipped existing: ${result.skipped.join(", ")}.` : "";
   return `Configured Switchboard setup (${result.target}) for project ${result.project_id}. Changed: ${changed}.${skipped}`;
 }
+
+export async function setupProject(
+  opts,
+  {
+    request = accountRequest,
+    configureEnv = configureEnvironment,
+    doctor = runDoctorChecks,
+    saveProject = saveProjectConfig,
+    config = resolveConfig(),
+    cwd,
+    json = false,
+    getSecret,
+    setSecret,
+    runSecretCommand,
+  } = {},
+) {
+  validateProjectSetupOptions(opts, { json });
+
+  const flags = { json };
+  const project = await ensureProject(opts, flags, { request, save: saveProject });
+  saveProject(project);
+
+  const origins = configuredOrigins(project, opts);
+  const configured = await updateSetupProject(project.id, opts, origins, flags, {
+    request,
+    save: saveProject,
+  });
+
+  const env = await configureEnv(
+    {
+      mode: normalizeSetupTarget(opts.target, json),
+      file: opts.file,
+      target: opts.secretTarget,
+      secretCommand: opts.secretCommand,
+      projectId: String(configured.id),
+      force: opts.force,
+    },
+    { request, cwd, json, getSecret, setSecret, runSecretCommand },
+  );
+
+  const idempotencyKey = `setup-project-${configured.id}`;
+  const challenge = await provisionManagedTurnstile(configured.id, idempotencyKey, flags, {
+    request,
+  });
+
+  let access = null;
+  if (hasProductionOptions(opts)) {
+    access = await requestAccessIfNeeded(configured.id, configured, opts, flags, { request });
+  }
+
+  const latest = await fetchProject(configured.id, flags, { request });
+  saveProject(latest);
+
+  const doctorConfig = {
+    ...config,
+    projectId: String(latest.id),
+    virtualMicroserviceUrl: latest.virtual_microservice_url || config.virtualMicroserviceUrl,
+  };
+  const readiness = await doctor({ config: doctorConfig, request });
+
+  return projectSetupSummary({
+    project: latest,
+    env,
+    challenge,
+    readiness,
+    access,
+    origin: opts.origin,
+    origins,
+  });
+}
+
+function validateProjectSetupOptions(opts, flags) {
+  if ((opts.projectName && !opts.projectSlug) || (!opts.projectName && opts.projectSlug)) {
+    fail("--project-name and --project-slug must be provided together", 1, flags.json);
+  }
+
+  if (!exactOrigin(opts.origin)) {
+    fail("--origin must be an exact browser origin such as http://127.0.0.1:4173", 1, flags.json);
+  }
+
+  if (!hasProductionOptions(opts)) return;
+
+  validateLaunchOptions(opts, flags);
+
+  for (const name of [
+    "endUserTermsUrl",
+    "endUserPrivacyUrl",
+    "supportEmail",
+    "contactEmail",
+    "useCase",
+  ]) {
+    if (!opts[name]) {
+      fail(`--${dasherize(name)} is required when production launch fields are provided`, 1, flags.json);
+    }
+  }
+}
+
+function hasProductionOptions(opts) {
+  return [
+    "productionOrigin",
+    "endUserTermsUrl",
+    "endUserPrivacyUrl",
+    "supportUrl",
+    "supportEmail",
+    "contactEmail",
+    "useCase",
+    "expectedMonthlyVolume",
+    "neededBillingMode",
+    "notes",
+  ].some((key) => opts[key] != null);
+}
+
+function configuredOrigins(project, opts) {
+  const requested = [opts.origin];
+  if (opts.productionOrigin) requested.push(opts.productionOrigin);
+
+  if (opts.force) return uniqueStrings(requested);
+
+  const existing = Array.isArray(project.allowed_origins) ? project.allowed_origins : [];
+  return uniqueStrings([...existing, ...requested]);
+}
+
+async function updateSetupProject(projectId, opts, origins, flags, { request, save }) {
+  const body = {
+    allowed_origins: origins,
+    virtual_microservice_enabled: true,
+  };
+
+  if (hasProductionOptions(opts)) {
+    body.end_user_terms_url = opts.endUserTermsUrl;
+    body.end_user_privacy_url = opts.endUserPrivacyUrl;
+    body.support_email = opts.supportEmail;
+    if (opts.supportUrl) body.support_url = opts.supportUrl;
+  }
+
+  const { data } = await request("PATCH", `/projects/${projectId}`, {
+    body,
+    json: flags.json,
+  });
+  save(data);
+  return data;
+}
+
+function projectSetupSummary({ project, env, challenge, readiness, access, origin, origins }) {
+  const hardFailures = readiness.checks.filter((check) => !check.ok).map((check) => check.name);
+  const configured = hardFailures.length === 0;
+  const productionRequested = Boolean(access);
+
+  return {
+    object: "setup_project_result",
+    ok: configured,
+    status: !configured
+      ? "failed"
+      : productionRequested
+        ? "production_requested"
+        : "ready_for_browser_manual_check",
+    configured,
+    ready_for_browser_manual_check: configured,
+    production_requested: productionRequested,
+    project_id: project.id,
+    project_slug: project.slug,
+    client_gateway_url: project.virtual_microservice_url,
+    allowed_origins: origins,
+    local_origin: origin,
+    turnstile: challenge,
+    env_file: env.env_file,
+    env,
+    doctor: readiness,
+    hard_failures: hardFailures,
+    production_access: access,
+    next_steps: [
+      "Use the SDK-managed browser challenge in your app to confirm browser chat manually.",
+      "Run switchboard verify setup after the app integration is wired.",
+      productionRequested
+        ? "Run switchboard verify publish after approval and billing readiness are complete."
+        : "Use switchboard launch prepare when you are ready for production approval.",
+    ],
+  };
+}
+
+export function humanProjectSetupMessage(result) {
+  const lines = [
+    `Configured project ${result.project_slug || result.project_id} (${result.project_id})`,
+    `Client Gateway: ${result.client_gateway_url}`,
+    `Allowed origins: ${result.allowed_origins.join(", ")}`,
+    `Turnstile: ${turnstileStatus(result.turnstile)}`,
+    `Env file: ${result.env_file}`,
+    `Readiness: ${result.configured ? "ready for browser manual check" : "failed"}`,
+  ];
+
+  if (result.production_requested) {
+    lines.push(
+      `Production access: ${
+        result.production_access?.project_production_access_status ||
+        result.production_access?.status ||
+        "requested"
+      }`,
+    );
+  }
+
+  if (result.hard_failures.length > 0) {
+    lines.push(`Hard failures: ${result.hard_failures.join(", ")}`);
+  }
+
+  lines.push(
+    "Next: integrate the SDK browser challenge in your app, then run switchboard verify setup.",
+  );
+
+  if (result.production_requested) {
+    lines.push("Next: run switchboard verify publish after production approval and billing readiness.");
+  }
+
+  return lines.join("\n");
+}
+
+function turnstileStatus(challenge) {
+  if (!challenge) return "unknown";
+  return redactSecrets(challenge.status || challenge.provider || challenge.object || "provisioned");
+}
+
+function exactOrigin(origin) {
+  try {
+    const url = new URL(origin);
+    return (
+      (url.protocol === "http:" || url.protocol === "https:") &&
+      url.username === "" &&
+      url.password === "" &&
+      url.pathname === "/" &&
+      url.search === "" &&
+      url.hash === "" &&
+      !url.hostname.includes("*")
+    );
+  } catch {
+    return false;
+  }
+}
+
+function uniqueStrings(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+function dasherize(value) {
+  return value.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`);
+}

package/lib/commands/verify.js

@@ -15,7 +15,7 @@ export function registerVerifyCommands(program) {
       .command("setup")
       .description("Verify a local or preview Switchboard integration setup")
       .option("--url <app-url>", "Application URL to test")
-      .option("--client-url <switchboard-client-url>", "Switchboard Pro-bono Embed client URL"),
+      .option("--client-url <switchboard-client-url>", "Switchboard Client Gateway client URL"),
   ).action(async (opts, cmd) => {
     await runVerifyCommand("setup", opts, cmd);
   });
@@ -25,7 +25,7 @@ export function registerVerifyCommands(program) {
       .command("publish")
       .description("Verify an HTTPS preview is safe to publish")
       .option("--url <preview-url>", "HTTPS preview URL to test")
-      .option("--client-url <switchboard-client-url>", "Switchboard Pro-bono Embed client URL")
+      .option("--client-url <switchboard-client-url>", "Switchboard Client Gateway client URL")
       .option("--production-origin <origin>", "Production origin that must be allowed"),
   )
     .option("--project-id <id>", "Switchboard project id for production safety checks")
@@ -38,7 +38,7 @@ export function registerVerifyCommands(program) {
       .command("browser")
       .description("Run a declarative browser verification scenario")
       .option("--url <app-url>", "Application URL to test")
-      .option("--client-url <switchboard-client-url>", "Switchboard Pro-bono Embed client URL"),
+      .option("--client-url <switchboard-client-url>", "Switchboard Client Gateway client URL"),
   ).action(async (opts, cmd) => {
     await runVerifyCommand("browser", opts, cmd);
   });

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;
+  }
+}