@switchboard.spot/cli 0.2.0

package/lib/commands/projects.js

@@ -0,0 +1,197 @@
+/**
+ * Project management commands.
+ */
+
+import { accountRequest } from "../client.js";
+import { saveConfig } from "../config.js";
+import { emit, globalFlags, printList } from "../output.js";
+
+export function registerProjectsCommands(program) {
+  const projects = program.command("projects").description("Projects");
+
+  projects
+    .command("list")
+    .description("List projects")
+    .action(async (_opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("GET", "/projects", { json: flags.json });
+      if (flags.json) {
+        emit(data, flags);
+      } else {
+        printList("Projects:", data.data || [], (p) =>
+          `  ${p.id} ${p.name} (${p.slug}) — ${p.api_key_count} keys`,
+        );
+      }
+    });
+
+  projects
+    .command("create")
+    .description("Create a project")
+    .requiredOption("--name <name>")
+    .requiredOption("--slug <slug>")
+    .action(async (opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("POST", "/projects", {
+        body: { name: opts.name, slug: opts.slug },
+        json: flags.json,
+      });
+      saveConfig({
+        projectId: String(data.id),
+        apiKey: null,
+        virtualMicroserviceUrl: data.virtual_microservice_url || null,
+        endUserSession: null,
+      });
+      emit(flags.json ? data : `Created project ${data.name} (${data.id})`, flags);
+    });
+
+  projects
+    .command("show <id>")
+    .description("Show a project")
+    .action(async (id, _opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("GET", `/projects/${id}`, { json: flags.json });
+      emit(flags.json ? data : JSON.stringify(data, null, 2), flags);
+    });
+
+  projects
+    .command("update <id>")
+    .description("Update project settings")
+    .option("--name <name>")
+    .option("--slug <slug>")
+    .option("--billing-mode <mode>")
+    .option("--embed-billing-end-user-ref <ref>")
+    .option("--end-user-terms-url <url>")
+    .option("--end-user-privacy-url <url>")
+    .option("--support-url <url>")
+    .option("--support-email <email>")
+    .option(
+      "--allowed-origins <urls>",
+      "Comma-separated browser origins for Pro-bono Embed requests",
+    )
+    .option(
+      "--allowed-ios-bundle-ids <ids>",
+      "Comma-separated iOS bundle IDs",
+    )
+    .option(
+      "--allowed-android-packages <packages>",
+      "Comma-separated Android package names",
+    )
+    .option("--virtual-microservice-enabled <boolean>")
+    .action(async (id, opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const body = buildProjectUpdateBody(opts);
+
+      const { data } = await accountRequest("PATCH", `/projects/${id}`, {
+        body,
+        json: flags.json,
+      });
+      emit(flags.json ? data : `Updated project ${data.name}`, flags);
+    });
+
+  projects
+    .command("turnstile <id>")
+    .description("Configure project-owned Turnstile keys")
+    .option("--site-key <key>")
+    .option("--secret-key <key>")
+    .option("--clear", "Remove project-owned Turnstile keys")
+    .action(async (id, opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const body = buildTurnstileBody(opts);
+      const { data } = await accountRequest("PATCH", `/projects/${id}`, {
+        body,
+        json: flags.json,
+      });
+      emit(flags.json ? data : `Updated Turnstile settings for ${data.name}`, flags);
+    });
+
+  projects
+    .command("use <id>")
+    .description("Set default project for subsequent commands")
+    .action(async (id, _opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("GET", `/projects/${id}`, { json: flags.json });
+      saveConfig({
+        projectId: String(data.id),
+        apiKey: null,
+        virtualMicroserviceUrl: data.virtual_microservice_url || null,
+        endUserSession: null,
+      });
+      emit(flags.json ? data : `Using project ${data.name} (${data.id})`, flags);
+    });
+
+  projects
+    .command("delete <id>")
+    .description("Delete a project")
+    .action(async (id, _opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("DELETE", `/projects/${id}`, {
+        json: flags.json,
+      });
+      emit(flags.json ? data : `Deleted project ${data.name}`, flags);
+    });
+
+  projects
+    .command("restore <id>")
+    .description("Restore a deleted project")
+    .action(async (id, _opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("POST", `/projects/${id}/restore`, {
+        json: flags.json,
+      });
+      emit(flags.json ? data : `Restored project ${data.name}`, flags);
+    });
+}
+
+/**
+ * Splits a comma-separated CLI option into a trimmed string array.
+ */
+function splitList(value) {
+  return value
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+export function buildProjectUpdateBody(opts) {
+  const body = {};
+  if (opts.name) body.name = opts.name;
+  if (opts.slug) body.slug = opts.slug;
+  if (opts.billingMode) body.billing_mode = opts.billingMode;
+  if (opts.embedBillingEndUserRef) {
+    body.embed_billing_end_user_ref = opts.embedBillingEndUserRef;
+  }
+  if (opts.endUserTermsUrl) body.end_user_terms_url = opts.endUserTermsUrl;
+  if (opts.endUserPrivacyUrl) body.end_user_privacy_url = opts.endUserPrivacyUrl;
+  if (opts.supportUrl) body.support_url = opts.supportUrl;
+  if (opts.supportEmail) body.support_email = opts.supportEmail;
+  if (opts.allowedOrigins != null) {
+    body.allowed_origins = splitList(opts.allowedOrigins);
+  }
+  if (opts.allowedIosBundleIds != null) {
+    body.allowed_ios_bundle_ids = splitList(opts.allowedIosBundleIds);
+  }
+  if (opts.allowedAndroidPackages != null) {
+    body.allowed_android_packages = splitList(opts.allowedAndroidPackages);
+  }
+  if (opts.virtualMicroserviceEnabled != null) {
+    body.virtual_microservice_enabled = parseBoolean(opts.virtualMicroserviceEnabled);
+  }
+  return body;
+}
+
+export function buildTurnstileBody(opts) {
+  if (opts.clear) {
+    return { turnstile_site_key: "", turnstile_secret_key: "" };
+  }
+
+  const body = {};
+  if (opts.siteKey) body.turnstile_site_key = opts.siteKey;
+  if (opts.secretKey) body.turnstile_secret_key = opts.secretKey;
+  return body;
+}
+
+function parseBoolean(value) {
+  if (value === true || value === "true") return true;
+  if (value === false || value === "false") return false;
+  throw new Error(`Expected boolean value true or false, got ${value}`);
+}

package/lib/commands/setup.js

@@ -0,0 +1,76 @@
+/**
+ * Guided Switchboard setup.
+ */
+
+import { configureEnvironment } from "./env.js";
+import { emit, fail, globalFlags } from "../output.js";
+
+export function registerSetupCommand(program) {
+  program
+    .command("setup")
+    .description("Configure Switchboard for client apps, server apps, or both")
+    .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")
+    .action(async (opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const result = await setupSwitchboard(opts, { json: flags.json });
+      emit(flags.json ? result : humanSetupMessage(result), flags);
+    });
+}
+
+export async function setupSwitchboard(opts, dependencies = {}) {
+  const target = normalizeSetupTarget(opts.target, dependencies.json);
+  const result = await configureEnvironment(
+    {
+      mode: target,
+      file: opts.file,
+      target: opts.secretTarget,
+      secretCommand: opts.secretCommand,
+      projectId: opts.projectId,
+      force: opts.force,
+    },
+    dependencies,
+  );
+
+  return {
+    ...result,
+    setup: true,
+    target,
+    smoke_check: smokeCheck(result),
+  };
+}
+
+function normalizeSetupTarget(target, json) {
+  if (target === "client" || target === "server" || target === "both") {
+    return target;
+  }
+
+  fail("--target must be client, server, or both", 1, json);
+}
+
+function smokeCheck(result) {
+  return {
+    ok: true,
+    checks: [
+      result.changed.includes("SWITCHBOARD_CLIENT_URL") ||
+        result.skipped.includes("SWITCHBOARD_CLIENT_URL")
+        ? "client_env"
+        : null,
+      result.changed.includes("SWITCHBOARD_BASE_URL") ||
+        result.skipped.includes("SWITCHBOARD_BASE_URL")
+        ? "server_env"
+        : null,
+      result.secrets.length > 0 ? "server_secret" : null,
+    ].filter(Boolean),
+  };
+}
+
+function humanSetupMessage(result) {
+  const changed = result.changed.length > 0 ? result.changed.join(", ") : "none";
+  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}`;
+}

package/lib/commands/usage.js

@@ -0,0 +1,52 @@
+/**
+ * Usage analytics commands.
+ */
+
+import { accountRequest } from "../client.js";
+import { emit, globalFlags } from "../output.js";
+
+export function registerUsageCommands(program) {
+  const usage = program
+    .command("usage")
+    .description("Usage and revenue summary")
+    .option("--mode <mode>", "all, sandbox, or live", "all")
+    .action(async (opts, cmd) => {
+      const global = globalFlags(cmd);
+      const json = global.json;
+      const { data } = await accountRequest("GET", `/usage?mode=${opts.mode}`, {
+        json,
+      });
+      if (json) {
+        emit(data, { json });
+      } else {
+        console.log(`Mode: ${data.mode}`);
+        console.log(`Requests: ${data.request_count}`);
+        console.log(`Tokens: ${data.total_tokens}`);
+        console.log(`End-user charges (micros): ${data.end_user_charge_micros}`);
+        console.log(`Dev margin (micros): ${data.dev_margin_micros}`);
+      }
+    });
+
+  usage
+    .command("requests")
+    .description("List recent gateway requests")
+    .option("--mode <mode>", "all, sandbox, or live", "all")
+    .option("--range <range>", "mtd, 7d, 30d, or all", "mtd")
+    .option("--status <status>")
+    .option("--q <query>")
+    .option("--limit <limit>", "Maximum rows", parseInt)
+    .action(async (opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const params = new URLSearchParams();
+      params.set("mode", opts.mode);
+      params.set("range", opts.range);
+      if (opts.status) params.set("status", opts.status);
+      if (opts.q) params.set("q", opts.q);
+      if (opts.limit != null) params.set("limit", String(opts.limit));
+
+      const { data } = await accountRequest("GET", `/usage/requests?${params}`, {
+        json: flags.json,
+      });
+      emit(flags.json ? data : JSON.stringify(data, null, 2), flags);
+    });
+}

package/lib/commands/verify.js

@@ -0,0 +1,143 @@
+import { accountApiUrl, resolveAccountConfig, resolveConfig } from "../config.js";
+import { emit, globalFlags } from "../output.js";
+import {
+  VerificationInputError,
+  verifySwitchboardBrowser,
+  verifySwitchboardPublish,
+  verifySwitchboardSetup,
+} from "../verify/index.js";
+
+export function registerVerifyCommands(program) {
+  const verify = program.command("verify").description("Verify a Switchboard browser integration");
+
+  addCommonOptions(
+    verify
+      .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"),
+  ).action(async (opts, cmd) => {
+    await runVerifyCommand("setup", opts, cmd);
+  });
+
+  addCommonOptions(
+    verify
+      .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("--production-origin <origin>", "Production origin that must be allowed"),
+  )
+    .option("--project-id <id>", "Switchboard project id for production safety checks")
+    .action(async (opts, cmd) => {
+      await runVerifyCommand("publish", opts, cmd);
+    });
+
+  addCommonOptions(
+    verify
+      .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"),
+  ).action(async (opts, cmd) => {
+    await runVerifyCommand("browser", opts, cmd);
+  });
+}
+
+function addCommonOptions(command) {
+  return command
+    .option("--scenario <file>", "Declarative JSON scenario file")
+    .option("--artifacts-dir <dir>", "Directory for screenshots and verification artifacts")
+    .option("--headed", "Run Chromium headed")
+    .option("--timeout-ms <milliseconds>", "Browser action timeout", parsePositiveInteger)
+    .option("--prompt <text>", "Prompt for switchboardChat scenario checks");
+}
+
+async function runVerifyCommand(mode, opts, cmd) {
+  const flags = globalFlags(cmd);
+
+  try {
+    const project = mode === "publish" ? await loadProject(opts, flags) : null;
+    const report = await verifierForMode(mode)({
+      url: opts.url,
+      clientUrl: opts.clientUrl,
+      productionOrigin: opts.productionOrigin,
+      scenarioPath: opts.scenario,
+      artifactsDir: opts.artifactsDir,
+      headed: opts.headed,
+      timeoutMs: opts.timeoutMs,
+      prompt: opts.prompt,
+      project,
+    });
+
+    emitVerifyReport(report, flags);
+    if (report.status !== "passed") process.exit(1);
+  } catch (error) {
+    const report = inputErrorReport(mode, error);
+    emitVerifyReport(report, flags);
+    process.exit(error instanceof VerificationInputError ? 1 : 3);
+  }
+}
+
+function emitVerifyReport(report, flags) {
+  emit(report, { ...flags, json: true });
+}
+
+function verifierForMode(mode) {
+  if (mode === "publish") return verifySwitchboardPublish;
+  if (mode === "browser") return verifySwitchboardBrowser;
+  return verifySwitchboardSetup;
+}
+
+async function loadProject(opts, flags) {
+  const config = resolveConfig();
+  const projectId = opts.projectId ?? config.projectId;
+
+  if (!projectId) return null;
+
+  const accountConfig = await resolveAccountConfig(config);
+  if (!accountConfig.accountToken) return null;
+
+  const url = `${accountApiUrl(accountConfig)}/projects/${encodeURIComponent(projectId)}`;
+  const response = await fetch(url, {
+    headers: {
+      Accept: "application/json",
+      Authorization: `Bearer ${accountConfig.accountToken}`,
+    },
+  });
+
+  if (!response.ok) {
+    if (!flags.quiet) {
+      console.error(`Could not load Switchboard project ${projectId}: HTTP ${response.status}`);
+    }
+    return null;
+  }
+
+  const data = await response.json();
+  return data?.data ?? data?.project ?? data;
+}
+
+function inputErrorReport(mode, error) {
+  return {
+    object: "verification_report",
+    mode,
+    status: "failed",
+    publishable: false,
+    functional: false,
+    secure: false,
+    production_safety: mode === "publish" ? "blocked" : "not_checked",
+    checks: [],
+    findings: [
+      {
+        severity: error instanceof VerificationInputError ? "critical" : "error",
+        code: error instanceof VerificationInputError ? "invalid_verification_input" : "verification_error",
+        message: error.message || String(error),
+      },
+    ],
+    artifacts: {},
+  };
+}
+
+function parsePositiveInteger(value) {
+  return value;
+}

package/lib/commands/workspaces.js

@@ -0,0 +1,92 @@
+/**
+ * Workspace management commands.
+ */
+
+import { accountRequest } from "../client.js";
+import { emit, globalFlags, printList } from "../output.js";
+
+export function registerWorkspacesCommands(program) {
+  const workspaces = program.command("workspaces").description("Workspaces");
+
+  workspaces
+    .command("list")
+    .description("List workspaces")
+    .option("--trash <filter>", "active, deleted, or all", "active")
+    .action(async (opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("GET", `/workspaces?trash=${opts.trash}`, {
+        json: flags.json,
+      });
+      if (flags.json) {
+        emit(data, flags);
+      } else {
+        printList("Workspaces:", data.data || [], (w) => `  ${w.id} ${w.name} (${w.slug})`);
+      }
+    });
+
+  workspaces
+    .command("show <id>")
+    .description("Show a workspace")
+    .option("--trash <filter>", "active, deleted, or all", "active")
+    .action(async (id, opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("GET", `/workspaces/${id}?trash=${opts.trash}`, {
+        json: flags.json,
+      });
+      emit(flags.json ? data : JSON.stringify(data, null, 2), flags);
+    });
+
+  workspaces
+    .command("create")
+    .description("Create a workspace")
+    .requiredOption("--name <name>")
+    .requiredOption("--slug <slug>")
+    .action(async (opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("POST", "/workspaces", {
+        body: { name: opts.name, slug: opts.slug },
+        json: flags.json,
+      });
+      emit(flags.json ? data : `Created workspace ${data.name} (${data.id})`, flags);
+    });
+
+  workspaces
+    .command("update <id>")
+    .description("Update a workspace")
+    .option("--name <name>")
+    .option("--slug <slug>")
+    .action(async (id, opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const body = {};
+      if (opts.name) body.name = opts.name;
+      if (opts.slug) body.slug = opts.slug;
+
+      const { data } = await accountRequest("PATCH", `/workspaces/${id}`, {
+        body,
+        json: flags.json,
+      });
+      emit(flags.json ? data : `Updated workspace ${data.name}`, flags);
+    });
+
+  workspaces
+    .command("delete <id>")
+    .description("Delete a workspace")
+    .action(async (id, _opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("DELETE", `/workspaces/${id}`, {
+        json: flags.json,
+      });
+      emit(flags.json ? data : `Deleted workspace ${data.name}`, flags);
+    });
+
+  workspaces
+    .command("restore <id>")
+    .description("Restore a deleted workspace")
+    .action(async (id, _opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("POST", `/workspaces/${id}/restore`, {
+        json: flags.json,
+      });
+      emit(flags.json ? data : `Restored workspace ${data.name}`, flags);
+    });
+}

package/lib/config.js

@@ -0,0 +1,132 @@
+/**
+ * Resolves Switchboard CLI configuration from environment, ~/.switchboard/config.json,
+ * and the OS keychain for account sessions.
+ */
+
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { getAccountToken } from "./credentialStore.js";
+
+const CONFIG_DIR =
+  process.env.SWITCHBOARD_CONFIG_DIR || path.join(os.homedir(), ".switchboard");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+const DEFAULT_BASE_URL = "https://switchboard.spot";
+
+/**
+ * Loads persisted CLI configuration from disk.
+ */
+export function loadConfig() {
+  try {
+    if (fs.existsSync(CONFIG_FILE)) {
+      const config = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+      return scrubLegacyAccountToken(config);
+    }
+  } catch {
+    /* ignore corrupt config */
+  }
+  return {};
+}
+
+function scrubLegacyAccountToken(config) {
+  if (!Object.prototype.hasOwnProperty.call(config, "accountToken")) {
+    return config;
+  }
+
+  const scrubbed = { ...config };
+  delete scrubbed.accountToken;
+
+  try {
+    fs.writeFileSync(CONFIG_FILE, `${JSON.stringify(scrubbed, null, 2)}\n`, { mode: 0o600 });
+  } catch {
+    /* ignore cleanup failures; account token is still ignored in memory */
+  }
+
+  return scrubbed;
+}
+
+/**
+ * Merges and saves CLI configuration to disk.
+ */
+export function saveConfig(updates) {
+  const current = loadConfig();
+  const next = { ...current, ...updates };
+  delete next.accountToken;
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_FILE, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+  try {
+    fs.chmodSync(CONFIG_FILE, 0o600);
+  } catch {
+    /* best effort on platforms that do not support chmod */
+  }
+  return next;
+}
+
+/**
+ * Returns effective non-secret settings with environment variable overrides.
+ *
+ * Account session tokens intentionally do not come from this config file or
+ * from environment variables. Authenticated commands call `resolveAccountConfig`
+ * so the token is read from the OS keychain only when needed.
+ */
+export function resolveConfig() {
+  const file = loadConfig();
+  return {
+    baseUrl: process.env.SWITCHBOARD_BASE_URL || file.baseUrl || DEFAULT_BASE_URL,
+    virtualMicroserviceUrl:
+      process.env.SWITCHBOARD_CLIENT_URL || file.virtualMicroserviceUrl || null,
+    accountToken: null,
+    accountTokenSource: null,
+    apiKey: process.env.SWITCHBOARD_API_KEY || null,
+    endUserSession:
+      process.env.SWITCHBOARD_END_USER_SESSION || file.endUserSession || null,
+    projectId: process.env.SWITCHBOARD_PROJECT_ID || file.projectId || null,
+    projectIdSource: projectIdSource(file),
+  };
+}
+
+function projectIdSource(file) {
+  if (process.env.SWITCHBOARD_PROJECT_ID) {
+    return "env";
+  }
+
+  if (file.projectId) {
+    return "config";
+  }
+
+  return null;
+}
+
+/**
+ * Returns effective settings plus the hidden keychain account session.
+ */
+export async function resolveAccountConfig(config) {
+  if (config?.accountToken || config?.disableKeychain) {
+    return config;
+  }
+
+  const base = config || resolveConfig();
+  const token = await getAccountToken();
+
+  return {
+    ...base,
+    accountToken: token,
+    accountTokenSource: token ? "keychain" : null,
+  };
+}
+
+/**
+ * Account API base URL (host + /v1/account).
+ */
+export function accountApiUrl(config) {
+  const base = config.baseUrl.replace(/\/$/, "");
+  return `${base}/v1/account`;
+}
+
+/**
+ * Gateway API base URL (host + /v1).
+ */
+export function gatewayApiUrl(config) {
+  const base = config.baseUrl.replace(/\/$/, "");
+  return `${base}/v1`;
+}