@switchboard.spot/cli 0.2.0

package/lib/commands/env.js

@@ -0,0 +1,393 @@
+/**
+ * Agent-safe environment configuration commands.
+ */
+
+import fs from "fs";
+import path from "path";
+import { spawn } from "node:child_process";
+import { accountRequest } from "../client.js";
+import { resolveAccountConfig, resolveConfig } from "../config.js";
+import {
+  getProjectSecretKey,
+  setProjectSecretKey,
+} from "../credentialStore.js";
+import { emit, fail, globalFlags } from "../output.js";
+
+const DEFAULT_ENV_FILE = ".env.local";
+const SECRET_ENV_NAMES = ["SWITCHBOARD_API_KEY"];
+const SECRET_PATTERNS = [
+  /sb_test_[A-Za-z0-9_-]+/g,
+  /sb_live_[A-Za-z0-9_-]+/g,
+  /sb_sess_[A-Za-z0-9_-]+/g,
+];
+
+export function registerEnvCommands(program) {
+  const env = program.command("env").description("Agent-safe environment setup");
+
+  env
+    .command("configure")
+    .description("Configure Switchboard environment values without printing secrets")
+    .option("--mode <mode>", "client, server, or both", "client")
+    .option("--file <path>", "Local env file to update", DEFAULT_ENV_FILE)
+    .option("--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 configureEnvironment(opts, { json: flags.json });
+      emit(flags.json ? result : humanConfigureMessage(result), flags);
+    });
+
+  env
+    .command("run")
+    .description("Run a command with Switchboard managed secrets injected")
+    .allowUnknownOption(true)
+    .argument("[command...]", "Command to run")
+    .action(async (command, _opts, cmd) => {
+      const flags = globalFlags(cmd);
+      await runWithEnvironment(command, { json: flags.json });
+    });
+}
+
+export async function configureEnvironment(
+  opts,
+  {
+    request = accountRequest,
+    getSecret = getProjectSecretKey,
+    setSecret = setProjectSecretKey,
+    cwd = process.cwd(),
+    json = false,
+    runSecretCommand = runSecretSinkCommand,
+  } = {},
+) {
+  const mode = normalizeMode(opts.mode);
+  const target = normalizeTarget(opts.target);
+  const projectId = opts.projectId;
+  const force = Boolean(opts.force);
+
+  if (target === "exec" && !opts.secretCommand) {
+    fail("--secret-command is required when --target exec is used", 1, json);
+  }
+
+  const { data: kit } = await request("GET", "/integration_kit", {
+    json,
+    projectId,
+  });
+
+  const selectedProjectId = String(projectId || kit.project_id || resolveConfig().projectId || "");
+  if (!selectedProjectId) {
+    fail("Could not determine the selected Switchboard project id", 1, json);
+  }
+
+  const changed = [];
+  const skipped = [];
+  const secrets = [];
+  const envFile = path.resolve(cwd, opts.file || DEFAULT_ENV_FILE);
+
+  const envUpdates = {};
+
+  if (mode === "client" || mode === "both") {
+    envUpdates.SWITCHBOARD_CLIENT_URL = kit.client_url || kit.virtual_microservice_url;
+  }
+
+  if (mode === "server" || mode === "both") {
+    envUpdates.SWITCHBOARD_BASE_URL = kit.server_base_url || kit.base_url;
+  }
+
+  const fileResult = updateEnvFile(envFile, envUpdates, { force });
+  changed.push(...fileResult.changed);
+  skipped.push(...fileResult.skipped);
+
+  if (mode === "server" || mode === "both") {
+    const secretResult = await ensureServerSecret({
+      projectId: selectedProjectId,
+      force,
+      request,
+      getSecret,
+      setSecret,
+      target,
+      secretCommand: opts.secretCommand,
+      runSecretCommand,
+      json,
+    });
+
+    changed.push(...secretResult.changed);
+    skipped.push(...secretResult.skipped);
+    secrets.push(secretResult.secret);
+  }
+
+  return {
+    ok: true,
+    project_id: selectedProjectId,
+    mode,
+    target,
+    env_file: envFile,
+    changed,
+    skipped,
+    secrets,
+  };
+}
+
+export async function runWithEnvironment(
+  command,
+  {
+    config,
+    getSecret = getProjectSecretKey,
+    env = process.env,
+    spawnProcess = spawn,
+    exitProcess = process.exit,
+    killProcess = process.kill,
+    json = false,
+  } = {},
+) {
+  if (!command || command.length === 0) {
+    fail("Usage: switchboard env run -- <command>", 1, json);
+  }
+
+  const cfg = await resolveAccountConfig(config || resolveConfig());
+  if (!cfg.projectId) {
+    fail(
+      "Specify a project before this command. Run: switchboard projects list, then switchboard projects use <id>.",
+      1,
+      json,
+      "project_required",
+    );
+  }
+
+  const secret = await getSecret(cfg.projectId, "sandbox");
+  if (!secret) {
+    fail(
+      "No managed Switchboard server secret found. Run: switchboard env configure --mode server",
+      1,
+      json,
+      "secret_required",
+    );
+  }
+
+  const child = spawnProcess(command[0], command.slice(1), {
+    stdio: "inherit",
+    env: {
+      ...env,
+      SWITCHBOARD_API_KEY: secret,
+      SWITCHBOARD_PROJECT_ID: cfg.projectId,
+    },
+  });
+
+  return new Promise((resolve, reject) => {
+    child.on("exit", (code, signal) => {
+      try {
+        if (signal) {
+          killProcess(process.pid, signal);
+          return;
+        }
+
+        resolve(exitProcess(code ?? 0));
+      } catch (error) {
+        reject(error);
+      }
+    });
+  });
+}
+
+function normalizeMode(mode) {
+  if (mode === "client" || mode === "server" || mode === "both") {
+    return mode;
+  }
+
+  if (mode === "virtual") {
+    return "client";
+  }
+
+  fail("--mode must be client, server, or both");
+}
+
+function normalizeTarget(target) {
+  if (target === "local" || target === "exec") {
+    return target;
+  }
+
+  fail("--target must be local or exec");
+}
+
+function updateEnvFile(file, updates, { force }) {
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  const parsed = parseEnvLines(existing);
+  const changed = [];
+  const skipped = [];
+  const nextLines = [...parsed.lines];
+
+  for (const [name, value] of Object.entries(updates)) {
+    if (!value) continue;
+
+    if (parsed.indexes.has(name)) {
+      if (!force) {
+        skipped.push(name);
+        continue;
+      }
+
+      nextLines[parsed.indexes.get(name)] = `${name}=${value}`;
+      changed.push(name);
+      continue;
+    }
+
+    nextLines.push(`${name}=${value}`);
+    changed.push(name);
+  }
+
+  if (changed.length > 0) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${trimTrailingBlankLines(nextLines).join("\n")}\n`, {
+      mode: 0o600,
+    });
+  }
+
+  return { changed, skipped };
+}
+
+function parseEnvLines(text) {
+  const lines = text ? text.replace(/\r\n/g, "\n").split("\n") : [];
+  if (lines.at(-1) === "") lines.pop();
+
+  const indexes = new Map();
+  lines.forEach((line, index) => {
+    const match = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+    if (match) indexes.set(match[1], index);
+  });
+
+  return { lines, indexes };
+}
+
+function trimTrailingBlankLines(lines) {
+  const next = [...lines];
+  while (next.length > 0 && next.at(-1) === "") {
+    next.pop();
+  }
+  return next;
+}
+
+async function ensureServerSecret({
+  projectId,
+  force,
+  request,
+  getSecret,
+  setSecret,
+  target,
+  secretCommand,
+  runSecretCommand,
+  json,
+}) {
+  const existing = await getSecret(projectId, "sandbox");
+  const changed = [];
+  const skipped = [];
+  let plaintext = existing;
+  let metadata = null;
+
+  if (!plaintext || force) {
+    const { data } = await request("POST", "/keys", {
+      body: {
+        mode: "sandbox",
+        name: "Managed server secret",
+        key_type: "secret",
+      },
+      json,
+      projectId,
+    });
+
+    plaintext = data.plaintext;
+    metadata = redactedKeyMetadata(data);
+    changed.push("SWITCHBOARD_API_KEY");
+  } else {
+    skipped.push("SWITCHBOARD_API_KEY");
+  }
+
+  if (!plaintext) {
+    fail("Switchboard did not return a one-time project secret key", 1, json);
+  }
+
+  if (target === "local") {
+    await setSecret(projectId, "sandbox", plaintext);
+  } else {
+    await runSecretCommand(secretCommand, {
+      secrets: SECRET_ENV_NAMES.map((name) => ({
+        name,
+        value: plaintext,
+        metadata: metadata || { project_id: projectId, mode: "sandbox" },
+      })),
+      redactValues: [plaintext],
+    });
+  }
+
+  return {
+    changed,
+    skipped,
+    secret: {
+      name: "SWITCHBOARD_API_KEY",
+      stored: target,
+      ...metadata,
+      redacted: true,
+    },
+  };
+}
+
+function redactedKeyMetadata(data) {
+  return {
+    key_id: data.id,
+    project_id: data.project_id != null ? String(data.project_id) : undefined,
+    mode: data.mode,
+    key_type: data.key_type,
+    last_four: data.last_four,
+  };
+}
+
+async function runSecretSinkCommand(command, { secrets, redactValues }) {
+  const redactions = [...SECRET_PATTERNS, ...redactValues.map((value) => new RegExp(escapeRegExp(value), "g"))];
+  const payload = JSON.stringify({ secrets });
+
+  await new Promise((resolve, reject) => {
+    const child = spawn(command, {
+      shell: true,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout.on("data", (chunk) => {
+      stdout += redact(String(chunk), redactions);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += redact(String(chunk), redactions);
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        const error = new Error(stderr || stdout || `Secret command exited with ${code}`);
+        error.code = code;
+        reject(error);
+      }
+    });
+
+    child.stdin.end(payload);
+  });
+}
+
+function redact(text, redactions) {
+  return redactions.reduce((acc, pattern) => acc.replace(pattern, "[REDACTED]"), text);
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function appOriginFromApiBase(baseUrl) {
+  return String(baseUrl || "").replace(/\/v1\/?$/, "");
+}
+
+function humanConfigureMessage(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 env (${result.mode}) for project ${result.project_id}. Changed: ${changed}.${skipped}`;
+}

package/lib/commands/health.js

@@ -0,0 +1,24 @@
+/**
+ * Health check command.
+ */
+
+import { healthCheck } from "../client.js";
+import { resolveConfig } from "../config.js";
+import { emit, globalFlags } from "../output.js";
+
+export function registerHealthCommand(program) {
+  program
+    .command("health")
+    .description("Check API health")
+    .action(async (_opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const result = await healthCheck(resolveConfig());
+      if (!result.ok) process.exit(3);
+
+      if (flags.json) {
+        emit(result.data, { json: true });
+      } else if (!flags.quiet) {
+        console.log(result.data?.status ?? "ok");
+      }
+    });
+}

package/lib/commands/init.js

@@ -0,0 +1,75 @@
+/**
+ * Project init and agent manifest commands.
+ */
+
+import fs from "fs";
+import path from "path";
+import { resolveConfig, gatewayApiUrl } from "../config.js";
+import { emit } from "../output.js";
+
+/**
+ * Builds default frontend environment placeholders for Pro-bono Embed apps.
+ *
+ * The generated Pro-bono Embed URL is the only value a browser app needs by default.
+ */
+function envBlock(clientUrl) {
+  return `SWITCHBOARD_CLIENT_URL=${clientUrl}
+`;
+}
+
+/**
+ * Builds the agent manifest for automated setup.
+ */
+export function agentManifest(config) {
+  const base = gatewayApiUrl(config);
+  const clientUrl = `${config.baseUrl.replace(/\/$/, "")}/m/<client-gateway-slug>/v1`;
+
+  return {
+    base_url: base,
+    client_url: clientUrl,
+    virtual_microservice_url: clientUrl,
+    account_api: `${config.baseUrl.replace(/\/$/, "")}/v1/account`,
+    env: envBlock(clientUrl),
+    checklist: [
+      "switchboard setup --target client --json",
+      "export SWITCHBOARD_CLIENT_URL=<client_url from integrations show>",
+      "Use mountSwitchboardWidget({ clientUrl, target }) in browser apps",
+      "Use createSwitchboardClient({ clientUrl, storage }) only for custom UI",
+      "switchboard billing top-up --amount-micros <micros>",
+    ],
+    browser_smoke_test: `import { mountSwitchboardWidget } from "@switchboard/sdk";
+
+mountSwitchboardWidget({
+  clientUrl: process.env.SWITCHBOARD_CLIENT_URL ?? "${clientUrl}",
+  target: "#switchboard",
+});`,
+    automation_note:
+      "Pro-bono Embed auth is browser/mobile only and requires a real browser challenge. Use account/CLI APIs only for project configuration automation.",
+  };
+}
+
+export function registerInitCommand(program) {
+  program
+    .command("init")
+    .description("Write .env.local with Switchboard placeholders")
+    .option("--agent", "Print agent manifest JSON")
+    .action((opts, cmd) => {
+      const flags = cmd.opts();
+      const config = resolveConfig();
+      const clientUrl = `${config.baseUrl.replace(/\/$/, "")}/m/<client-gateway-slug>/v1`;
+      const target = path.join(process.cwd(), ".env.local");
+
+      if (!fs.existsSync(target)) {
+        fs.writeFileSync(target, envBlock(clientUrl));
+        if (!flags.quiet && !flags.json) {
+          console.log(`Wrote ${target}`);
+        }
+      } else if (!flags.quiet && !flags.json) {
+        console.log(`${target} already exists`);
+      }
+
+      if (opts.agent || flags.json) {
+        emit(agentManifest(config), { json: true });
+      }
+    });
+}

package/lib/commands/integration.js

@@ -0,0 +1,38 @@
+/**
+ * Integration kit command.
+ */
+
+import { accountRequest } from "../client.js";
+import { emit, globalFlags } from "../output.js";
+
+export function registerIntegrationCommands(program) {
+  const integrations = program.command("integrations").description("Integration helpers");
+
+  integrations
+    .command("show")
+    .description("Fetch integration setup JSON")
+    .option("--stack <stack>", "node or python", "node")
+    .action(async (opts, cmd) => {
+      await showIntegration(opts, cmd);
+    });
+
+  const integration = program.command("integration").description("Legacy integration helpers");
+
+  integration
+    .command("kit")
+    .description("Legacy alias for integrations show")
+    .option("--stack <stack>", "node or python", "node")
+    .action(async (opts, cmd) => {
+      await showIntegration(opts, cmd);
+    });
+}
+
+async function showIntegration(opts, cmd) {
+  const flags = globalFlags(cmd);
+  const { data } = await accountRequest(
+    "GET",
+    `/integration_kit?stack=${opts.stack}`,
+    { json: flags.json },
+  );
+  emit(data, flags);
+}

package/lib/commands/keys.js

@@ -0,0 +1,106 @@
+/**
+ * API key management commands.
+ */
+
+import { accountRequest } from "../client.js";
+import { saveConfig } from "../config.js";
+import { emit, globalFlags, printList } from "../output.js";
+
+function saveProjectContext(data) {
+  const updates = {};
+
+  if (data.project_id != null) {
+    updates.projectId = String(data.project_id);
+  }
+
+  updates.apiKey = null;
+
+  if (Object.keys(updates).length > 0) {
+    saveConfig(updates);
+  }
+}
+
+export function registerKeysCommands(program) {
+  const keys = program.command("keys").description("Project API keys");
+
+  keys
+    .command("list")
+    .description("List API keys for the selected project")
+    .action(async (_opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("GET", "/keys", { json: flags.json });
+      if (flags.json) {
+        emit(data, flags);
+      } else {
+        printList("API keys:", data.data || [], (k) =>
+          `  ${k.id} ${k.mode} ${k.key_type || "secret"} ${k.name} …${k.last_four}${k.revoked_at ? " (revoked)" : ""}`,
+        );
+      }
+    });
+
+  keys
+    .command("create")
+    .description("Create a new API key")
+    .option("--mode <mode>", "sandbox or live", "sandbox")
+    .option("--name <name>", "Key label")
+    .action(async (opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const body = { mode: opts.mode, name: opts.name };
+
+      const { data } = await accountRequest("POST", "/keys", {
+        body,
+        json: flags.json,
+      });
+
+      saveProjectContext(data);
+      emit(
+        flags.json
+          ? data
+          : `Created ${data.mode} key. Plaintext (shown once): ${data.plaintext}`,
+        flags,
+      );
+    });
+
+  keys
+    .command("regenerate-sandbox")
+    .description("Revoke sandbox secret keys and create a new one")
+    .action(async (_opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("POST", "/keys/sandbox/regenerate", {
+        json: flags.json,
+      });
+      saveProjectContext(data);
+      emit(
+        flags.json
+          ? data
+          : `New sandbox key: ${data.plaintext}`,
+        flags,
+      );
+    });
+
+  keys
+    .command("revoke <id>")
+    .description("Revoke an API key")
+    .action(async (id, _opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("POST", `/keys/${id}/revoke`, {
+        json: flags.json,
+      });
+      emit(flags.json ? data : `Revoked key ${id}`, flags);
+    });
+
+  keys
+    .command("rotate <id>")
+    .description("Rotate an API key")
+    .action(async (id, _opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("POST", `/keys/${id}/rotate`, {
+        json: flags.json,
+      });
+      saveProjectContext(data);
+      emit(
+        flags.json ? data : `Rotated key ${id}. New plaintext: ${data.plaintext}`,
+        flags,
+      );
+    });
+}

package/lib/commands/org.js

@@ -0,0 +1,55 @@
+/**
+ * Organization invitation commands.
+ */
+
+import { accountRequest } from "../client.js";
+import { emit, globalFlags, printList } from "../output.js";
+
+export function registerOrgCommands(program) {
+  const org = program.command("org").description("Organization and team");
+
+  org
+    .command("invitations")
+    .description("List pending invitations")
+    .action(async (_opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("GET", "/invitations", { json: flags.json });
+      if (flags.json) {
+        emit(data, flags);
+      } else {
+        printList("Pending invitations:", data.data || [], (i) =>
+          `  ${i.email} (${i.role}) token=${i.token}`,
+        );
+      }
+    });
+
+  org
+    .command("invite")
+    .description("Invite a member by email")
+    .requiredOption("--email <email>")
+    .action(async (opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("POST", "/invitations", {
+        body: { email: opts.email },
+        json: flags.json,
+      });
+      emit(
+        flags.json ? data : `Invited ${data.email}. Token: ${data.token}`,
+        flags,
+      );
+    });
+
+  org
+    .command("accept <token>")
+    .description("Accept an invitation")
+    .action(async (token, _opts, cmd) => {
+      const flags = globalFlags(cmd);
+      const { data } = await accountRequest("POST", `/invitations/${token}/accept`, {
+        json: flags.json,
+      });
+      emit(
+        flags.json ? data : `Joined organization ${data.name}`,
+        flags,
+      );
+    });
+}