busa-cli 0.9.3

package/dist/chunk-C5BGRNMU.js

@@ -0,0 +1,1342 @@
+// src/format.ts
+function render(value, output) {
+  if (output === "json") {
+    return JSON.stringify(value, null, 2);
+  }
+  if (output === "text") {
+    return renderText(value);
+  }
+  if (Array.isArray(value)) {
+    return renderTable(value);
+  }
+  if (value && typeof value === "object") {
+    return renderRecord(value);
+  }
+  return String(value);
+}
+function cell(value) {
+  if (value === null || value === void 0) return "";
+  if (typeof value === "object") return compactJson(value);
+  return truncate(String(value));
+}
+function compactJson(value) {
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    if (value.every((item) => typeof item !== "object" || item === null)) {
+      return truncate(value.map((item) => String(item)).join(", "));
+    }
+    return `[${value.length} items]`;
+  }
+  if (value && typeof value === "object") {
+    const keys = Object.keys(value);
+    if (keys.length === 0) return "{}";
+    return `{${keys.slice(0, 3).join(", ")}${keys.length > 3 ? ", ..." : ""}}`;
+  }
+  return truncate(String(value));
+}
+function truncate(value, max = 72) {
+  const singleLine = value.replace(/\s+/g, " ").trim();
+  if (singleLine.length <= max) return singleLine;
+  return `${singleLine.slice(0, max - 1)}\u2026`;
+}
+function renderRecord(row) {
+  const keys = Object.keys(row);
+  const width = Math.max(0, ...keys.map((k) => k.length));
+  return keys.map((k) => `${k.padEnd(width)}  ${cell(row[k])}`).join("\n");
+}
+function renderTable(rows) {
+  if (rows.length === 0) return "(no rows)";
+  if (typeof rows[0] !== "object" || rows[0] === null) {
+    return rows.map((r) => cell(r)).join("\n");
+  }
+  const records = rows;
+  const columns = [...new Set(records.flatMap((r) => Object.keys(r)))];
+  const widths = columns.map((c2) => Math.max(c2.length, ...records.map((r) => cell(r[c2]).length)));
+  const line = (cells) => cells.map((value, i) => value.padEnd(widths[i])).join("  ").trimEnd();
+  const header = line(columns);
+  const sep = widths.map((w) => "-".repeat(w)).join("  ");
+  const body = records.map((r) => line(columns.map((c2) => cell(r[c2]))));
+  return [header, sep, ...body].join("\n");
+}
+function renderText(value) {
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "(no rows)";
+    if (isNodeTree(value)) return renderNodeTree(value);
+    if (typeof value[0] !== "object" || value[0] === null) {
+      return value.map((item) => cell(item)).join("\n");
+    }
+    return renderTable(value);
+  }
+  if (value && typeof value === "object") {
+    return renderRecord(value);
+  }
+  return String(value);
+}
+function isNodeTree(value) {
+  return value.every(isNodeLike);
+}
+function isNodeLike(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const row = value;
+  return typeof row.id === "string" && typeof row.type === "string" && typeof row.slug === "string" && typeof row.name === "string" && Array.isArray(row.children);
+}
+function renderNodeTree(nodes) {
+  const lines = [];
+  const walk = (items, prefix, isRoot) => {
+    items.forEach((node, index) => {
+      const isLast = index === items.length - 1;
+      const branch = isRoot ? "" : isLast ? "\u2514\u2500 " : "\u251C\u2500 ";
+      const childPrefix = isRoot ? "" : `${prefix}${isLast ? "   " : "\u2502  "}`;
+      lines.push(`${prefix}${branch}${formatNode(node)}`);
+      const children = Array.isArray(node.children) ? node.children.filter(isNodeLike) : [];
+      walk(children, childPrefix, false);
+    });
+  };
+  walk(nodes, "", true);
+  return lines.join("\n");
+}
+function formatNode(node) {
+  const type = String(node.type ?? "node");
+  const name = String(node.name ?? node.slug ?? node.id ?? "Untitled");
+  const slug = typeof node.slug === "string" && node.slug !== name ? ` /${node.slug}` : "";
+  const base = typeof node.baseId === "string" && node.baseId ? ` base=${node.baseId}` : "";
+  return `${nodeIcon(type)} ${name}${slug}  (${type}${base}, id=${node.id})`;
+}
+function nodeIcon(type) {
+  switch (type) {
+    case "folder":
+      return "[folder]";
+    case "base":
+      return "[base]";
+    case "doc":
+      return "[doc]";
+    case "skill":
+      return "[skill]";
+    case "drive":
+      return "[drive]";
+    default:
+      return "[node]";
+  }
+}
+
+// src/run.ts
+import { createHash as createHash2 } from "crypto";
+import { readFileSync as readFileSync2 } from "fs";
+import { basename, extname } from "path";
+import {
+  cloudContract,
+  createBusabaseClient,
+  DEFAULT_BASE_URL as DEFAULT_BASE_URL2,
+  normalizeBaseUrl as normalizeBaseUrl2
+} from "busabase-sdk";
+import {
+  Command,
+  CommanderError,
+  InvalidArgumentError,
+  Option
+} from "commander";
+
+// src/banner.ts
+var useColor = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+var paint = (code, s) => useColor ? `\x1B[${code}m${s}\x1B[0m` : s;
+var c = {
+  brand: (s) => paint("38;5;43", s),
+  // teal — Busabase accent
+  bold: (s) => paint("1", s),
+  dim: (s) => paint("2", s),
+  cyan: (s) => paint("36", s)
+};
+var LOGO = [
+  "  ____                  _                     ",
+  " | __ ) _   _ ___  __ _| |__   __ _ ___  ___  ",
+  " |  _ \\| | | / __|/ _` | '_ \\ / _` / __|/ _ \\ ",
+  " | |_) | |_| \\__ \\ (_| | |_) | (_| \\__ \\  __/ ",
+  " |____/ \\__,_|___/\\__,_|_.__/ \\__,_|___/\\___| "
+];
+function banner(baseUrl) {
+  const out = [""];
+  for (const line of LOGO) out.push(c.brand(line));
+  out.push(`${c.dim("   OpenAPI client for Busabase")} ${c.dim("\xB7")} ${c.dim("talks to /api/v1")}`);
+  out.push(`   ${c.bold("Server")}  ${c.cyan(baseUrl)}`);
+  out.push("");
+  return out.join("\n");
+}
+
+// src/config-file.ts
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var dotEnvPath = () => join(homedir(), ".busabase", ".env");
+function loadDotEnvFile() {
+  let text;
+  try {
+    text = readFileSync(dotEnvPath(), "utf8");
+  } catch {
+    return {};
+  }
+  const out = {};
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    const value = trimmed.slice(eq + 1).trim().replace(/^["']|["']$/g, "");
+    if (key) out[key] = value;
+  }
+  return out;
+}
+function writeDotEnvFile(updates) {
+  const merged = { ...loadDotEnvFile() };
+  for (const [key, value] of Object.entries(updates)) {
+    if (value === null) delete merged[key];
+    else merged[key] = value;
+  }
+  const path = dotEnvPath();
+  mkdirSync(join(homedir(), ".busabase"), { recursive: true });
+  const body = Object.entries(merged).map(([key, value]) => `${key}=${value}`).join("\n");
+  writeFileSync(path, body ? `${body}
+` : "", "utf8");
+  try {
+    chmodSync(path, 384);
+  } catch {
+  }
+}
+
+// src/login.ts
+import { spawn } from "child_process";
+import { createHash, randomBytes } from "crypto";
+import { createServer } from "http";
+import { createInterface } from "readline/promises";
+import { DEFAULT_BASE_URL, normalizeBaseUrl } from "busabase-sdk";
+var CLI_CLIENT_ID = "busabase-cli";
+var CLI_CLIENT_PLATFORM = "cli";
+var OAUTH_TIMEOUT_MS = 5 * 60 * 1e3;
+var EXPIRES_AT_KEY = "BUSABASE_TOKEN_EXPIRES_AT";
+var SESSION_TOKEN_PREFIX = "bss_";
+var AUTO_REFRESH_THRESHOLD_MS = 2 * 24 * 60 * 60 * 1e3;
+var DEFAULT_LOCAL_URL = "http://localhost:15419";
+var base64url = (buffer) => buffer.toString("base64url");
+var isInteractive = () => Boolean(process.stdin.isTTY && process.stdout.isTTY);
+var say = (message) => {
+  process.stderr.write(`${message}
+`);
+};
+var isLocalHost = (baseUrl) => {
+  try {
+    const { hostname } = new URL(baseUrl);
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+  } catch {
+    return false;
+  }
+};
+async function probeAuthRequired(baseUrl) {
+  let res;
+  try {
+    res = await fetch(`${baseUrl}/api/v1/bases`);
+  } catch {
+    throw new Error(
+      `Could not reach ${baseUrl}. Is the server running? Start a local one with \`busabase server\`, or pass a reachable --base-url.`
+    );
+  }
+  return res.status === 401 || res.status === 403;
+}
+async function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    return (await rl.question(question)).trim();
+  } finally {
+    rl.close();
+  }
+}
+function openBrowser(url) {
+  const platform = process.platform;
+  const [command, args] = platform === "darwin" ? ["open", [url]] : platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+  try {
+    spawn(command, args, { stdio: "ignore", detached: true }).unref();
+  } catch {
+  }
+}
+async function verifyAuth(baseUrl, token) {
+  const res = await fetch(`${baseUrl}/api/v1/auth`, {
+    headers: { authorization: `Bearer ${token}` }
+  });
+  if (res.status === 401) {
+    throw new Error(
+      `The credential was rejected (401) by ${baseUrl}. If it's an API key, check it in Dashboard \u2192 Settings \u2192 API Keys; if it's a login session, run \`busabase-cli login\` again.`
+    );
+  }
+  if (!res.ok) {
+    throw new Error(`Could not verify the credential (HTTP ${res.status}) from ${baseUrl}.`);
+  }
+  return await res.json();
+}
+async function oauthLogin(baseUrl, useBrowser) {
+  const codeVerifier = base64url(randomBytes(32));
+  const codeChallenge = base64url(createHash("sha256").update(codeVerifier).digest());
+  const state = base64url(randomBytes(16));
+  const { code, redirectUri } = await new Promise(
+    (resolve, reject) => {
+      const server = createServer((req, res) => {
+        const url = new URL(req.url ?? "/", "http://127.0.0.1");
+        if (url.pathname !== "/callback") {
+          res.writeHead(404).end("Not found");
+          return;
+        }
+        const respond = (title, body) => {
+          res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+          res.end(
+            `<!doctype html><meta charset="utf-8"><title>${title}</title><body style="font-family:system-ui;max-width:32rem;margin:4rem auto;text-align:center"><h2>${title}</h2><p>${body}</p></body>`
+          );
+        };
+        const error = url.searchParams.get("error");
+        const returnedState = url.searchParams.get("state");
+        const returnedCode = url.searchParams.get("code");
+        if (error) {
+          respond("Sign-in failed", "You can close this tab and return to the terminal.");
+          cleanup();
+          reject(new Error(`Authorization failed: ${error}`));
+          return;
+        }
+        if (!returnedCode || returnedState !== state) {
+          respond("Sign-in failed", "State mismatch. You can close this tab and try again.");
+          cleanup();
+          reject(new Error("OAuth state mismatch \u2014 the callback did not match this request."));
+          return;
+        }
+        respond("Signed in \u2713", "You can close this tab and return to the terminal.");
+        const address = server.address();
+        cleanup();
+        resolve({ code: returnedCode, redirectUri: `http://127.0.0.1:${address.port}/callback` });
+      });
+      const timeout = setTimeout(() => {
+        cleanup();
+        reject(new Error("Timed out waiting for the browser sign-in (5 minutes)."));
+      }, OAUTH_TIMEOUT_MS);
+      function cleanup() {
+        clearTimeout(timeout);
+        server.close();
+      }
+      server.on("error", (err) => {
+        cleanup();
+        reject(err);
+      });
+      server.listen(0, "127.0.0.1", () => {
+        const { port } = server.address();
+        const redirect = `http://127.0.0.1:${port}/callback`;
+        const authorizeUrl = new URL(`${baseUrl}/api/oauth/authorize`);
+        authorizeUrl.searchParams.set("response_type", "code");
+        authorizeUrl.searchParams.set("client_id", CLI_CLIENT_ID);
+        authorizeUrl.searchParams.set("client_platform", CLI_CLIENT_PLATFORM);
+        authorizeUrl.searchParams.set("code_challenge", codeChallenge);
+        authorizeUrl.searchParams.set("code_challenge_method", "S256");
+        authorizeUrl.searchParams.set("redirect_uri", redirect);
+        authorizeUrl.searchParams.set("state", state);
+        const href = authorizeUrl.toString();
+        say("");
+        say("Open this URL in your browser to sign in:");
+        say(`  ${href}`);
+        say("");
+        if (useBrowser) {
+          say("Opening your browser\u2026");
+          openBrowser(href);
+        }
+        say("Waiting for you to finish signing in\u2026");
+      });
+    }
+  );
+  const tokenRes = await fetch(`${baseUrl}/api/oauth/token`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      grant_type: "authorization_code",
+      client_id: CLI_CLIENT_ID,
+      client_platform: CLI_CLIENT_PLATFORM,
+      code,
+      code_verifier: codeVerifier,
+      redirect_uri: redirectUri,
+      state
+    })
+  });
+  if (!tokenRes.ok) {
+    const text = await tokenRes.text();
+    throw new Error(`Token exchange failed (HTTP ${tokenRes.status})${text ? `: ${text}` : ""}`);
+  }
+  const payload = await tokenRes.json();
+  const token = payload.token ?? payload.accessToken;
+  if (!token) throw new Error("Token exchange returned no session token.");
+  return { token, expiresAt: payload.expiresAt };
+}
+async function refreshToken(baseUrl, token) {
+  const res = await fetch(`${baseUrl}/api/oauth/refresh`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${token}` }
+  });
+  if (res.status === 401) throw new Error("SESSION_EXPIRED");
+  if (!res.ok) throw new Error(`Refresh failed (HTTP ${res.status}) from ${baseUrl}.`);
+  const payload = await res.json();
+  return { token: payload.token ?? payload.accessToken ?? token, expiresAt: payload.expiresAt };
+}
+async function pickSpaceId(verify, preselected) {
+  if (preselected) return preselected;
+  const spaces = verify.spaces ?? [];
+  if (spaces.length <= 1) return verify.space?.id ?? spaces[0]?.id;
+  if (!isInteractive()) {
+    const choices = spaces.map((space) => `${space.name} [${space.id}]`).join(", ");
+    throw new Error(
+      `You belong to ${spaces.length} spaces; pass --space-id <id> to choose one. Available spaces: ${choices}`
+    );
+  }
+  say("");
+  say("Which space should this CLI target?");
+  spaces.forEach((space, index) => {
+    const marker = space.id === verify.space?.id ? " (default)" : "";
+    say(`  ${index + 1}. ${space.name}${marker}  [${space.id}]`);
+  });
+  const answer = await ask(`Choose 1-${spaces.length} (Enter for default): `);
+  if (!answer) return verify.space?.id ?? spaces[0]?.id;
+  const choice = Number(answer);
+  if (Number.isInteger(choice) && choice >= 1 && choice <= spaces.length) {
+    return spaces[choice - 1]?.id;
+  }
+  throw new Error("Not a valid space choice. Re-run login and choose one of the listed spaces.");
+}
+async function chooseTarget() {
+  const cloud = normalizeBaseUrl(DEFAULT_BASE_URL);
+  say("Busabase is an approval-first database and knowledge base for AI agents.");
+  say("Agents propose changes; humans review and merge what becomes trusted data.");
+  say("This login connects the CLI to the Busabase instance you want to use.");
+  say("");
+  say("How should this CLI connect?");
+  say("  1. Local/Desktop on this computer \u2014 no account, no login");
+  say("     Use when you run `busabase server` or the Busabase Desktop app locally.");
+  say("  2. Busabase Cloud \u2014 browser sign-in (recommended)");
+  say("     Best for humans: opens the browser and saves a refreshable CLI session.");
+  say("  3. Busabase Cloud \u2014 paste an API key");
+  say("     Best for CI, servers, or agents where a browser is not available.");
+  say("  4. Self-hosted Busabase \u2014 browser sign-in");
+  say("     Use your team's Busabase URL when it supports OAuth login.");
+  say("  5. Self-hosted Busabase \u2014 paste an API key");
+  say("     Use your team's Busabase URL with a long-lived key for automation.");
+  const choice = await ask("Choose 1-5 [2]: ");
+  const askSelfHostedUrl = async () => {
+    const url = await ask("Self-hosted base URL (e.g. https://busabase.example.com): ");
+    if (!url) throw new Error("A self-hosted base URL is required.");
+    return url;
+  };
+  switch (choice) {
+    case "1": {
+      const url = await ask(`Local server URL [${DEFAULT_LOCAL_URL}]: `) || DEFAULT_LOCAL_URL;
+      return { baseUrl: url, method: "none" };
+    }
+    case "3":
+      return { baseUrl: cloud, method: "api-key" };
+    case "4":
+      return { baseUrl: await askSelfHostedUrl(), method: "oauth" };
+    case "5":
+      return { baseUrl: await askSelfHostedUrl(), method: "api-key" };
+    default:
+      return { baseUrl: cloud, method: "oauth" };
+  }
+}
+async function runLogin(options) {
+  let baseUrl = normalizeBaseUrl(options.baseUrl);
+  let apiKey = options.apiKey;
+  let method;
+  if (apiKey) {
+    method = "api-key";
+  } else if (options.oauth) {
+    method = "oauth";
+  } else if (isInteractive()) {
+    const target = await chooseTarget();
+    baseUrl = normalizeBaseUrl(target.baseUrl);
+    method = target.method;
+  } else {
+    method = isLocalHost(baseUrl) ? "none" : "oauth";
+  }
+  if (method === "none") {
+    if (await probeAuthRequired(baseUrl)) {
+      throw new Error(
+        `${baseUrl} requires sign-in. Re-run \`busabase-cli login\` and pick a Cloud or self-hosted option (OAuth or API key).`
+      );
+    }
+    writeDotEnvFile({
+      BUSABASE_BASE_URL: baseUrl,
+      BUSABASE_API_KEY: null,
+      BUSABASE_SPACE_ID: null,
+      [EXPIRES_AT_KEY]: null
+    });
+    say(`\u2713 Connected to ${baseUrl} \u2014 open server, no login needed.`);
+    say(`  Saved to ${dotEnvPath()}. Try: busabase-cli bases list`);
+    return { status: "connected (no auth)", baseUrl, config: dotEnvPath() };
+  }
+  let token;
+  let expiresAt;
+  if (method === "oauth") {
+    const result = await oauthLogin(baseUrl, options.browser);
+    token = result.token;
+    expiresAt = result.expiresAt;
+  } else {
+    if (!apiKey) {
+      say("Create a key in the dashboard \u2192 Settings \u2192 API Keys (shown once).");
+      apiKey = await ask("Paste your API key (sk_\u2026): ");
+    }
+    if (!apiKey) throw new Error("No API key provided.");
+    token = apiKey;
+  }
+  say("Verifying\u2026");
+  const verify = await verifyAuth(baseUrl, token);
+  const spaceId = await pickSpaceId(verify, options.spaceId);
+  writeDotEnvFile({
+    BUSABASE_BASE_URL: baseUrl,
+    BUSABASE_API_KEY: token,
+    BUSABASE_SPACE_ID: spaceId ?? null,
+    // Clear any stale expiry when switching to an API key.
+    [EXPIRES_AT_KEY]: expiresAt ?? null
+  });
+  say("");
+  say(`\u2713 Signed in and saved to ${dotEnvPath()}`);
+  return {
+    status: "signed in",
+    method,
+    user: verify.user?.email ?? verify.user?.name ?? verify.user?.id ?? "(unknown)",
+    space: spaceId ?? "(server default)",
+    expiresAt: expiresAt ?? "(no expiry \u2014 API key)",
+    baseUrl,
+    config: dotEnvPath()
+  };
+}
+async function runRefresh(options) {
+  const baseUrl = normalizeBaseUrl(options.baseUrl);
+  const token = options.apiKey;
+  if (!token) throw new Error("Not signed in \u2014 run `busabase-cli login` first.");
+  if (!token.startsWith(SESSION_TOKEN_PREFIX)) {
+    return {
+      status: "nothing to refresh",
+      detail: "This credential is an API key, which doesn't expire. Only OAuth sessions refresh."
+    };
+  }
+  let refreshed;
+  try {
+    refreshed = await refreshToken(baseUrl, token);
+  } catch (error) {
+    if (error instanceof Error && error.message === "SESSION_EXPIRED") {
+      throw new Error(
+        "Your login session has expired \u2014 run `busabase-cli login` to sign in again."
+      );
+    }
+    throw error;
+  }
+  writeDotEnvFile({
+    BUSABASE_API_KEY: refreshed.token,
+    [EXPIRES_AT_KEY]: refreshed.expiresAt ?? null
+  });
+  say(`\u2713 Session refreshed${refreshed.expiresAt ? ` \u2014 valid until ${refreshed.expiresAt}` : ""}`);
+  return {
+    status: "refreshed",
+    expiresAt: refreshed.expiresAt ?? "(unknown)",
+    config: dotEnvPath()
+  };
+}
+async function maybeAutoRefresh(baseUrl, apiKey) {
+  if (!apiKey?.startsWith(SESSION_TOKEN_PREFIX)) return;
+  const file = loadDotEnvFile();
+  if (file.BUSABASE_API_KEY !== apiKey) return;
+  const expiresRaw = file[EXPIRES_AT_KEY];
+  if (!expiresRaw) return;
+  const expiresAt = Date.parse(expiresRaw);
+  if (Number.isNaN(expiresAt)) return;
+  if (expiresAt - Date.now() > AUTO_REFRESH_THRESHOLD_MS) return;
+  try {
+    const refreshed = await refreshToken(normalizeBaseUrl(baseUrl), apiKey);
+    writeDotEnvFile({
+      BUSABASE_API_KEY: refreshed.token,
+      [EXPIRES_AT_KEY]: refreshed.expiresAt ?? null
+    });
+  } catch {
+  }
+}
+async function runLogout(options) {
+  const baseUrl = normalizeBaseUrl(options.baseUrl);
+  const token = options.apiKey;
+  let revoked = "no session to revoke";
+  if (token?.startsWith("bss_")) {
+    try {
+      const res = await fetch(`${baseUrl}/api/oauth/revoke`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}` }
+      });
+      revoked = res.ok ? "session revoked" : `revoke returned HTTP ${res.status}`;
+    } catch {
+      revoked = "revoke request failed (cleared locally anyway)";
+    }
+  } else if (token) {
+    revoked = "API key cleared locally (revoke it in the dashboard to disable it)";
+  }
+  writeDotEnvFile({ BUSABASE_API_KEY: null, BUSABASE_SPACE_ID: null, [EXPIRES_AT_KEY]: null });
+  say(`\u2713 Cleared the saved credential from ${dotEnvPath()}`);
+  return { status: "signed out", detail: revoked, config: dotEnvPath() };
+}
+
+// src/run.ts
+var DOCS_TROUBLESHOOTING = "https://busabase.com/docs/troubleshooting";
+function resolveConfig(opts) {
+  const file = loadDotEnvFile();
+  return {
+    baseUrl: opts.baseUrl ?? process.env.BUSABASE_BASE_URL ?? file.BUSABASE_BASE_URL ?? DEFAULT_BASE_URL2,
+    apiKey: opts.apiKey ?? process.env.BUSABASE_API_KEY ?? file.BUSABASE_API_KEY,
+    spaceId: opts.spaceId ?? process.env.BUSABASE_SPACE_ID ?? file.BUSABASE_SPACE_ID,
+    output: opts.output ?? "text"
+  };
+}
+var GLOBAL_LONG_FLAGS = /* @__PURE__ */ new Set(["--base-url", "--api-key", "--space-id", "--output"]);
+function addGlobalFlags(cmd) {
+  return cmd.option(
+    "--base-url <url>",
+    `server base URL (env BUSABASE_BASE_URL, default ${DEFAULT_BASE_URL2})`
+  ).option("--api-key <token>", "bearer token for cloud hosts (env BUSABASE_API_KEY)").option("--space-id <id>", "target Busabase space (env BUSABASE_SPACE_ID)").addOption(
+    new Option("--output <fmt>", "text | table | json (default text)").choices([
+      "text",
+      "table",
+      "json"
+    ])
+  );
+}
+var parseNum = (value) => {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) throw new InvalidArgumentError("expected a number");
+  return parsed;
+};
+var parseLimit = (value) => {
+  const parsed = parseNum(value);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > 100) {
+    throw new InvalidArgumentError("expected an integer from 1 to 100");
+  }
+  return parsed;
+};
+var parsePositiveInt = (value) => {
+  const parsed = parseNum(value);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new InvalidArgumentError("expected a positive integer");
+  }
+  return parsed;
+};
+var parseBoolean = (value) => {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  throw new InvalidArgumentError("expected true or false");
+};
+var collectValues = (value, previous = []) => [...previous, value];
+var MIME_BY_EXT = {
+  ".gif": "image/gif",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".md": "text/markdown",
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".txt": "text/plain",
+  ".webp": "image/webp"
+};
+var guessMimeType = (filePath) => MIME_BY_EXT[extname(filePath).toLowerCase()] ?? "application/octet-stream";
+function createAttachmentOptions(opts) {
+  const maxFiles = opts.maxFiles;
+  const maxFileSize = opts.maxFileSize;
+  const allowedMimeTypes = opts.allowedMime;
+  if (!maxFiles && !maxFileSize && (!allowedMimeTypes || allowedMimeTypes.length === 0)) {
+    return void 0;
+  }
+  return {
+    attachment: {
+      ...maxFiles ? { maxFiles } : {},
+      ...maxFileSize ? { maxFileSize } : {},
+      ...allowedMimeTypes && allowedMimeTypes.length > 0 ? { allowedMimeTypes } : {}
+    }
+  };
+}
+function mergeFieldOptions(existing, attachmentOptions) {
+  if (!attachmentOptions) return existing;
+  if (!existing || typeof existing !== "object" || Array.isArray(existing))
+    return attachmentOptions;
+  return { ...existing, ...attachmentOptions };
+}
+function parseFieldSpecs(specs) {
+  return specs.map((spec) => {
+    const [slug, name, type] = spec.split(":");
+    return {
+      slug,
+      name: name ?? slug,
+      ...type ? { type } : {}
+    };
+  });
+}
+function parseFieldDefinitions(opts) {
+  const specs = opts.field ?? [];
+  const fieldsJson = opts.fieldsJson;
+  if (specs.length > 0 && fieldsJson) {
+    throw new Error("Pass either --field or --fields-json, not both.");
+  }
+  if (fieldsJson) {
+    const parsed = parseJsonValue(fieldsJson, "fields-json");
+    if (!Array.isArray(parsed)) {
+      throw new Error(
+        '--fields-json must be a JSON array of field definitions. Example: [{"slug":"status","name":"Status","type":"select","options":{"choices":[{"id":"live","name":"Live"}]}}]'
+      );
+    }
+    return parsed;
+  }
+  if (specs.length === 0) {
+    throw new Error("Pass at least one --field or provide --fields-json @fields.json.");
+  }
+  return parseFieldSpecs(specs);
+}
+function parseFileNodeMetadata(opts) {
+  const assetId = opts.assetId;
+  if (!assetId) {
+    throw new Error("--asset-id is required with --type file.");
+  }
+  return { assetId };
+}
+function parseJsonValue(raw, flagName) {
+  const text = raw.startsWith("@") ? readFileSync2(raw.slice(1), "utf8") : raw;
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    const hint = raw.startsWith("@") ? `File ${raw.slice(1)} is not valid JSON.` : `Flag --${flagName} must be valid JSON. For complex values, write a file and pass --${flagName} @record.json.`;
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`${hint}
+  JSON parse error: ${reason}`);
+  }
+}
+async function rawFetch(config, method, path, body) {
+  const url = `${normalizeBaseUrl2(config.baseUrl)}${path}`;
+  const res = await fetch(url, {
+    method: method.toUpperCase(),
+    headers: {
+      ...body !== void 0 ? { "content-type": "application/json" } : {},
+      ...config.apiKey ? { authorization: `Bearer ${config.apiKey}` } : {},
+      ...config.spaceId ? { "x-busabase-space": config.spaceId } : {}
+    },
+    body: body !== void 0 ? JSON.stringify(body) : void 0
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} ${res.statusText}: ${text}`);
+  }
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+async function rawRequest(config, method, path, body) {
+  return rawFetch(config, method, path, body);
+}
+async function uploadAsset(config, opts) {
+  const filePath = opts.file;
+  const file = readFileSync2(filePath);
+  const fileName = opts.fileName ?? basename(filePath);
+  const mimeType = opts.mimeType ?? guessMimeType(filePath);
+  const context = opts.context ?? "record-field";
+  const contentHash = `sha256:${createHash2("sha256").update(file).digest("hex")}`;
+  const requested = await rawRequest(config, "POST", "/api/v1/assets/upload-urls", {
+    fileName,
+    mimeType,
+    sizeBytes: file.byteLength,
+    context,
+    contentHash
+  });
+  if (requested.duplicate) {
+    return {
+      id: requested.assetId ?? requested.attachmentId,
+      assetId: requested.assetId,
+      attachmentId: requested.attachmentId,
+      url: requested.publicUrl,
+      fileName,
+      mimeType,
+      size: file.byteLength
+    };
+  }
+  if (requested.uploadUrl.startsWith("/")) {
+    throw new Error(
+      `Server returned a browser-relative upload URL (${requested.uploadUrl}). Use the Busabase UI for local/dev uploads or a cloud host with a presigned absolute upload URL.`
+    );
+  }
+  const uploadResponse = await fetch(requested.uploadUrl, {
+    body: new Uint8Array(file),
+    headers: { "content-type": mimeType },
+    method: "PUT"
+  });
+  if (!uploadResponse.ok) {
+    const text = await uploadResponse.text();
+    throw new Error(
+      `Asset byte upload failed (${uploadResponse.status} ${uploadResponse.statusText})${text ? `: ${text}` : ""}`
+    );
+  }
+  const confirmed = await rawRequest(config, "POST", "/api/v1/assets/confirmations", {
+    storageKey: requested.storageKey,
+    fileName,
+    mimeType,
+    sizeBytes: file.byteLength,
+    context,
+    contentHash
+  });
+  return {
+    id: confirmed.assetId ?? confirmed.attachmentId,
+    assetId: confirmed.assetId,
+    attachmentId: confirmed.attachmentId,
+    url: confirmed.publicUrl,
+    fileName,
+    mimeType,
+    size: file.byteLength
+  };
+}
+function runAction(state, handler) {
+  return async (_opts, cmd) => {
+    const opts = cmd.optsWithGlobals();
+    const config = resolveConfig(opts);
+    state.config = config;
+    await maybeAutoRefresh(config.baseUrl, config.apiKey);
+    const client = createBusabaseClient(config);
+    const result = await handler(client, opts, config);
+    console.log(render(result, config.output));
+  };
+}
+function pkgVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync2(new URL("../package.json", import.meta.url), "utf8"));
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+var kebab = (value) => value.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+var isProcedure = (node) => typeof node === "object" && node !== null && typeof node["~orpc"]?.route?.method === "string";
+function unwrapSchema(schema) {
+  let inner = schema;
+  let optional = false;
+  for (let i = 0; i < 6 && inner?.def; i++) {
+    const type = inner.def.type;
+    if (type === "optional" || type === "default") {
+      optional = true;
+      inner = inner.def.innerType;
+    } else if (type === "nullable") {
+      inner = inner.def.innerType;
+    } else break;
+  }
+  return { inner, optional };
+}
+function classifyKind(inner) {
+  const type = inner?.def?.type;
+  if (type === "string") return { kind: "string" };
+  if (type === "number") return { kind: "number" };
+  if (type === "boolean") return { kind: "boolean" };
+  if (type === "literal") return { kind: "string" };
+  if (type === "enum") {
+    const choices = Array.isArray(inner.options) ? inner.options : Object.values(inner.def?.entries ?? {});
+    return choices.length ? { kind: "enum", choices } : { kind: "string" };
+  }
+  return { kind: "json" };
+}
+function inputFields(inputSchema) {
+  const { inner } = unwrapSchema(inputSchema);
+  const shape = inner?.shape ?? (inner?.def?.type === "object" ? inner.def.shape : void 0);
+  if (!shape || typeof shape !== "object") return [];
+  const fields = [];
+  for (const [key, sub] of Object.entries(shape)) {
+    const { inner: unwrapped, optional } = unwrapSchema(sub);
+    const { kind, choices } = classifyKind(unwrapped);
+    fields.push({ key, kind, required: !optional, choices });
+  }
+  return fields;
+}
+var GENERATED_SKIP = /* @__PURE__ */ new Set([
+  "search",
+  // top-level `search`
+  "auth.verify",
+  // `whoami`
+  "records.search",
+  // `records by-field-text`
+  "records.listChangeRequests"
+  // `records change-requests`
+]);
+function registerGeneratedCommands(program, state) {
+  const getGroup = (displayName, tag) => program.commands.find((c2) => c2.name() === displayName) ?? program.command(displayName).description(tag ?? `${displayName} endpoints`);
+  const addLeaf = (parent, navPath, procKey, proc) => {
+    const { route, inputSchema } = proc["~orpc"];
+    const name = kebab(procKey);
+    if (parent.commands.some((c2) => c2.name() === name)) return;
+    const fields = inputFields(inputSchema);
+    const leaf = parent.command(name).description(route.summary ?? `${route.method} ${route.path}`);
+    for (const f of fields) {
+      const flag = `--${kebab(f.key)}`;
+      if (GLOBAL_LONG_FLAGS.has(flag)) continue;
+      if (f.kind === "boolean") {
+        leaf.option(flag, `${f.key} (boolean)`);
+      } else if (f.kind === "json") {
+        const jsonFlag = `${flag}-json <json|@file>`;
+        const desc = `${f.key} as JSON${f.required ? "" : " (optional)"}`;
+        if (f.required) leaf.requiredOption(jsonFlag, desc);
+        else leaf.option(jsonFlag, desc);
+      } else if (f.kind === "enum") {
+        const opt = new Option(`${flag} <value>`, f.key).choices(f.choices ?? []);
+        if (f.required) opt.makeOptionMandatory();
+        leaf.addOption(opt);
+      } else if (f.kind === "number") {
+        const label = `${flag} <value>`;
+        const desc = `${f.key}${f.required ? "" : " (optional)"}`;
+        if (f.required) leaf.requiredOption(label, desc, parseNum);
+        else leaf.option(label, desc, parseNum);
+      } else {
+        const label = `${flag} <value>`;
+        const desc = `${f.key}${f.required ? "" : " (optional)"}`;
+        if (f.required) leaf.requiredOption(label, desc);
+        else leaf.option(label, desc);
+      }
+    }
+    addGlobalFlags(leaf);
+    leaf.addHelpText("after", `
+OpenAPI: ${route.method} ${route.path}`);
+    leaf.action(
+      runAction(state, (client, opts) => {
+        const input = {};
+        for (const f of fields) {
+          if (GLOBAL_LONG_FLAGS.has(`--${kebab(f.key)}`)) continue;
+          const optKey = f.kind === "json" ? `${f.key}Json` : f.key;
+          const value = opts[optKey];
+          if (value === void 0) continue;
+          input[f.key] = f.kind === "json" ? parseJsonValue(value, `${kebab(f.key)}-json`) : value;
+        }
+        let target = client;
+        for (const segment of navPath) target = target[segment];
+        return fields.length > 0 ? target[procKey](input) : target[procKey]();
+      })
+    );
+  };
+  const walk = (node, navPath) => {
+    for (const key of Object.keys(node)) {
+      if (key === "~orpc") continue;
+      const child = node[key];
+      const id = [...navPath, key].join(".");
+      if (isProcedure(child)) {
+        if (GENERATED_SKIP.has(id)) continue;
+        if (navPath.length > 1) continue;
+        const parent = navPath.length ? getGroup(kebab(navPath[0]), child["~orpc"].route.tags?.[0]) : program;
+        addLeaf(parent, navPath, key, child);
+      } else if (child && typeof child === "object") {
+        walk(child, [...navPath, key]);
+      }
+    }
+  };
+  walk(cloudContract, []);
+}
+function flagSignature(cmd) {
+  const parts = [];
+  for (const option of cmd.options) {
+    if (option.name() === "help" || GLOBAL_LONG_FLAGS.has(option.long ?? "")) continue;
+    parts.push(option.mandatory ? option.flags : `[${option.flags}]`);
+  }
+  return parts.join(" ");
+}
+var isHelpHidden = (cmd) => Boolean(cmd._noHelp);
+function commandsSection(program) {
+  const lines = ["Commands:"];
+  const entry = (prefix, cmd) => {
+    const sig = [prefix, flagSignature(cmd)].filter(Boolean).join(" ");
+    const desc = cmd.description();
+    if (!desc) return `  ${sig}`;
+    if (sig.length <= 40) return `  ${sig.padEnd(42)}${desc}`;
+    return `  ${sig}
+${" ".repeat(44)}${desc}`;
+  };
+  for (const cmd of program.commands) {
+    if (cmd.name() === "help" || isHelpHidden(cmd)) continue;
+    const leaves = cmd.commands.filter((leaf) => leaf.name() !== "help" && !isHelpHidden(leaf));
+    if (leaves.length > 0) {
+      lines.push("");
+      for (const leaf of leaves) lines.push(entry(`${cmd.name()} ${leaf.name()}`, leaf));
+    } else {
+      lines.push(entry(cmd.name(), cmd));
+    }
+  }
+  return lines.join("\n");
+}
+var HELP_FOOTER = `
+Config is read from flags, then env vars, then ~/.busabase/.env (auto-loaded \u2014 no
+need to source it). An exported env var overrides the file.
+
+Docs: https://busabase.com/docs \xB7 Troubleshooting: ${DOCS_TROUBLESHOOTING}`;
+function buildProgram(state = {}) {
+  const program = new Command("busabase-cli");
+  program.description("Client for the Busabase OpenAPI REST API \u2014 talks to `busabase server` or Cloud.").usage("[global flags] <command> [flags]").version(pkgVersion(), "-v, --version", "print busabase-cli version").exitOverride().showHelpAfterError("(run `busabase-cli --help` for the full command list)").addHelpText("beforeAll", () => banner(resolveConfig(program.opts()).baseUrl));
+  addGlobalFlags(program);
+  addGlobalFlags(program.command("health")).description("Server health check (GET /api/health)").action(runAction(state, (_client, _opts, config) => rawFetch(config, "GET", "/api/health")));
+  addGlobalFlags(program.command("openapi")).description("Fetch the OpenAPI document").action(
+    runAction(state, (_client, _opts, config) => rawFetch(config, "GET", "/api/v1/openapi.json"))
+  );
+  addGlobalFlags(program.command("whoami")).description("Active space, user, and membership").action(runAction(state, (client) => client.auth.verify()));
+  addGlobalFlags(program.command("login")).description("Connect the CLI to Busabase \u2014 Personal/local, Cloud, or self-hosted").option("--oauth", "force browser OAuth and skip the method prompt").option("--no-browser", "OAuth: print the sign-in URL instead of opening a browser").option("--refresh", "slide the saved OAuth session forward (no browser, no re-login)").addHelpText(
+    "after",
+    `
+Busabase is an approval-first database and knowledge base for AI agents: agents
+propose changes, humans review and merge what becomes trusted data.
+
+Run interactively, login explains the connection choices and writes the selected
+Busabase instance to ~/.busabase/.env:
+  1. Local/Desktop on this computer \u2014 no account, no login
+  2. Busabase Cloud \u2014 browser sign-in (recommended)
+  3. Busabase Cloud \u2014 paste an API key
+  4. Self-hosted Busabase \u2014 browser sign-in
+  5. Self-hosted Busabase \u2014 paste an API key
+The flags below skip the menu (handy for scripts / CI):
+
+  busabase-cli login                                   # pick from the menu
+  busabase-cli login --oauth                           # Cloud browser sign-in
+  busabase-cli login --api-key sk_\u2026                    # Cloud API key (headless/CI)
+  busabase-cli login --base-url http://localhost:15419 # connect to a local server (no auth)
+  busabase-cli login --refresh                         # extend the current session (auto-runs too)`
+  ).action(async (_opts, cmd) => {
+    const opts = cmd.optsWithGlobals();
+    const config = resolveConfig(opts);
+    state.config = config;
+    const summary = opts.refresh ? await runRefresh({ baseUrl: config.baseUrl, apiKey: config.apiKey }) : await runLogin({
+      baseUrl: config.baseUrl,
+      apiKey: opts.apiKey,
+      spaceId: config.spaceId,
+      oauth: Boolean(opts.oauth),
+      browser: opts.browser !== false
+    });
+    console.log(render(summary, config.output));
+  });
+  addGlobalFlags(program.command("logout")).description("Revoke the saved OAuth session (if any) and clear ~/.busabase/.env").action(async (_opts, cmd) => {
+    const opts = cmd.optsWithGlobals();
+    const config = resolveConfig(opts);
+    state.config = config;
+    const summary = await runLogout({ baseUrl: config.baseUrl, apiKey: config.apiKey });
+    console.log(render(summary, config.output));
+  });
+  const nodes = program.command("nodes").description("Workspace node tree");
+  addGlobalFlags(nodes.command("list")).description("Workspace node tree").action(runAction(state, (client) => client.nodes.list()));
+  addGlobalFlags(nodes.command("create-change-request")).description("Propose a new node via a Change Request").addOption(
+    new Option("--type <folder|base|skill|drive|file|doc>", "node type").choices(["folder", "base", "skill", "drive", "file", "doc"]).makeOptionMandatory()
+  ).requiredOption("--slug <slug>", "node slug").requiredOption("--name <name>", "node name").option("--description <text>", "optional node description").option("--parent-node-id <id>", "parent folder node id; omit for root").option("--message <text>", "reviewer-facing Change Request message").option("--submitted-by <name>", "producer label").option("--field <slug:name:type...>", "base field, repeatable (for --type base)").option("--fields-json <json|@file>", "base fields as JSON array (for --type base)").option("--asset-id <id>", "backing Asset id (required for --type file)").addHelpText(
+    "after",
+    `
+Examples:
+  busabase-cli nodes create-change-request --type folder --slug cms --name "\u5185\u5BB9\u7BA1\u7406 CMS"
+  busabase-cli nodes create-change-request --type base --slug blog --name "\u535A\u5BA2\u6587\u7AE0 Blog Posts" --field title:Title:text --field body:Body:markdown
+  busabase-cli nodes create-change-request --type base --slug products --name "\u4EA7\u54C1\u76EE\u5F55 Products" --fields-json @fields.json
+  busabase-cli nodes create-change-request --type file --slug board-plan --name "Board Plan" --asset-id ast_123`
+  ).action(
+    runAction(state, (client, opts) => {
+      const nodeType = opts.type;
+      const name = opts.name;
+      if (nodeType !== "base" && (opts.field || opts.fieldsJson)) {
+        throw new Error("--field and --fields-json are only valid with --type base.");
+      }
+      if (nodeType !== "file" && opts.assetId) {
+        throw new Error("--asset-id is only valid with --type file.");
+      }
+      return client.nodes.createChangeRequest({
+        message: opts.message ?? `Create ${nodeType} ${name}`,
+        submittedBy: opts.submittedBy,
+        operations: [
+          {
+            kind: "create",
+            nodeType,
+            slug: opts.slug,
+            name,
+            description: opts.description,
+            parentNodeId: opts.parentNodeId,
+            ...nodeType === "base" ? { fields: parseFieldDefinitions(opts) } : {},
+            ...nodeType === "file" ? { metadata: parseFileNodeMetadata(opts) } : {}
+          }
+        ]
+      });
+    })
+  );
+  const bases = program.command("bases").description("Bases (structured tables)");
+  addGlobalFlags(bases.command("list")).description("List Bases in the active space").action(runAction(state, (client) => client.bases.list()));
+  addGlobalFlags(bases.command("get")).description("Get one Base by slug").requiredOption("--slug <slug>", "Base slug").action(
+    runAction(state, async (client, opts) => {
+      const slug = opts.slug;
+      const found = (await client.bases.list()).find((base) => base.slug === slug);
+      if (!found) throw new Error(`no Base with slug "${slug}"`);
+      return found;
+    })
+  );
+  addGlobalFlags(bases.command("create")).description("Create a Base").requiredOption("--slug <slug>", "Base slug").requiredOption("--name <name>", "Base name").option("--field <slug:name:type...>", "field definition, repeatable").option("--fields-json <json|@file>", "field definitions as JSON array").option("--description <text>", "optional description").option("--parent-node-id <id>", "parent folder node id; omit for root").addHelpText(
+    "after",
+    `
+Examples:
+  busabase-cli bases create --slug products --name "\u4EA7\u54C1\u76EE\u5F55 Products" --field product_name:"Product Name":text
+  busabase-cli bases create --slug products --name "\u4EA7\u54C1\u76EE\u5F55 Products" --fields-json @fields.json`
+  ).action(
+    runAction(
+      state,
+      (client, opts) => client.bases.create({
+        slug: opts.slug,
+        name: opts.name,
+        description: opts.description,
+        parentNodeId: opts.parentNodeId,
+        fields: parseFieldDefinitions(opts)
+      })
+    )
+  );
+  addGlobalFlags(bases.command("create-field")).description("Add a field to a Base").requiredOption("--base-id <id>", "Base id").requiredOption("--slug <slug>", "field slug").requiredOption("--name <name>", "field name").option("--field-type <type>", "field type (default text)").option("--required", "mark the field as required").option("--max-files <n>", "attachment option: max files", parsePositiveInt).option("--max-file-size <bytes>", "attachment option: max size in bytes", parsePositiveInt).option(
+    "--allowed-mime <mime>",
+    "attachment option: allowed MIME type, repeatable",
+    collectValues
+  ).action(
+    runAction(
+      state,
+      (client, opts) => client.bases.createField({
+        baseId: opts.baseId,
+        slug: opts.slug,
+        name: opts.name,
+        ...opts.fieldType ? { type: opts.fieldType } : {},
+        required: Boolean(opts.required),
+        ...createAttachmentOptions(opts) ? { options: createAttachmentOptions(opts) } : {}
+      })
+    )
+  );
+  addGlobalFlags(bases.command("update-field-change-request")).description("Propose updating field metadata/options via a Change Request").requiredOption("--base-id <id>", "Base id").requiredOption("--field-id <id>", "field id").option("--name <name>", "new field name").option("--required <true|false>", "set required flag", parseBoolean).option("--options-json <json|@file>", "full field options JSON, or @file.json").option("--max-files <n>", "attachment option: max files", parsePositiveInt).option("--max-file-size <bytes>", "attachment option: max size in bytes", parsePositiveInt).option(
+    "--allowed-mime <mime>",
+    "attachment option: allowed MIME type, repeatable",
+    collectValues
+  ).option("--message <text>", "reviewer-facing Change Request message").option("--submitted-by <name>", "producer label").addHelpText(
+    "after",
+    `
+Examples:
+  busabase-cli bases update-field-change-request --base-id bse_123 --field-id bsf_123 --name "\u5C01\u9762 Cover Image" --max-files 1 --allowed-mime image/png --allowed-mime image/svg+xml
+  busabase-cli bases update-field-change-request --base-id bse_123 --field-id bsf_123 --options-json @field-options.json`
+  ).action(
+    runAction(state, (client, opts) => {
+      const patch = {};
+      if (opts.name) patch.name = opts.name;
+      if (opts.required !== void 0) patch.required = opts.required;
+      if (opts.optionsJson) {
+        patch.options = parseJsonValue(opts.optionsJson, "options-json");
+      }
+      const attachmentOptions = createAttachmentOptions(opts);
+      patch.options = mergeFieldOptions(patch.options, attachmentOptions);
+      if (Object.keys(patch).length === 0) {
+        throw new Error(
+          "No field patch supplied. Pass --name, --required, --options-json, or attachment option flags."
+        );
+      }
+      return client.bases.updateFieldChangeRequest({
+        baseId: opts.baseId,
+        fieldId: opts.fieldId,
+        patch,
+        message: opts.message,
+        submittedBy: opts.submittedBy
+      });
+    })
+  );
+  addGlobalFlags(bases.command("create-change-request")).description("Propose a new record via a Change Request").requiredOption("--base-id <id>", "target Base id").requiredOption("--fields-json <json|@file>", "record fields as JSON, or @file.json").option("--message <text>", "reviewer-facing Change Request message").option("--submitted-by <name>", "producer label").addHelpText(
+    "after",
+    `
+Examples:
+  busabase-cli bases create-change-request --base-id bse_123 --fields-json '{"title":"Hello","status":"draft"}'
+  busabase-cli bases create-change-request --base-id bse_123 --fields-json @record.json`
+  ).action(
+    runAction(
+      state,
+      (client, opts) => client.bases.createChangeRequest({
+        baseId: opts.baseId,
+        fields: parseJsonValue(opts.fieldsJson, "fields-json"),
+        message: opts.message,
+        submittedBy: opts.submittedBy
+      })
+    )
+  );
+  const records = program.command("records").description("Records");
+  addGlobalFlags(records.command("list")).description("List records").option("--limit <n>", "max results (1-100)", parseLimit).option("--base-id <id>", "restrict to one Base").option("--cursor <cursor>", "opaque nextCursor from a previous page").action(
+    runAction(state, (_client, opts, config) => {
+      const query = new URLSearchParams();
+      if (opts.limit !== void 0) query.set("limit", String(opts.limit));
+      if (opts.baseId) query.set("baseId", opts.baseId);
+      if (opts.cursor) query.set("cursor", opts.cursor);
+      const qs = query.toString();
+      return rawRequest(config, "GET", `/api/v1/records/paged${qs ? `?${qs}` : ""}`);
+    })
+  );
+  addGlobalFlags(records.command("get")).description("Get one record").requiredOption("--record-id <id>", "record id").action(
+    runAction(state, (client, opts) => client.records.get({ recordId: opts.recordId }))
+  );
+  addGlobalFlags(records.command("by-field-text")).description("Find records by text field value").requiredOption("--field-slug <slug>", "field slug to match").requiredOption("--value-text <text>", "text value to match").option("--base-id <id>", "restrict to one Base").option("--limit <n>", "max results", parseNum).action(
+    runAction(
+      state,
+      (client, opts) => client.records.search({
+        fieldSlug: opts.fieldSlug,
+        valueText: opts.valueText,
+        baseId: opts.baseId,
+        limit: opts.limit
+      })
+    )
+  );
+  addGlobalFlags(records.command("change-requests")).description("Change Requests for a record").requiredOption("--record-id <id>", "record id").action(
+    runAction(
+      state,
+      (client, opts) => client.records.listChangeRequests({ recordId: opts.recordId })
+    )
+  );
+  const changeRequests = program.command("change-requests").description("Change Requests");
+  addGlobalFlags(changeRequests.command("list")).description("List Change Requests").option("--limit <n>", "max results", parseNum).action(
+    runAction(
+      state,
+      (client, opts) => client.changeRequests.list({ limit: opts.limit })
+    )
+  );
+  addGlobalFlags(changeRequests.command("get")).description("Get a Change Request").requiredOption("--change-request-id <id>", "Change Request id").action(
+    runAction(
+      state,
+      (client, opts) => client.changeRequests.get({ changeRequestId: opts.changeRequestId })
+    )
+  );
+  addGlobalFlags(changeRequests.command("review")).description("Review a Change Request (rejected = request changes, not terminal)").requiredOption("--change-request-id <id>", "Change Request id").addOption(
+    new Option("--verdict <approved|rejected>", "review verdict").choices(["approved", "rejected"]).makeOptionMandatory()
+  ).option("--reason <text>", "review reason").action(
+    runAction(
+      state,
+      (client, opts) => client.changeRequests.review({
+        changeRequestId: opts.changeRequestId,
+        verdict: opts.verdict,
+        reason: opts.reason
+      })
+    )
+  );
+  addGlobalFlags(changeRequests.command("close")).description("Terminally abandon/reject a Change Request").requiredOption("--change-request-id <id>", "Change Request id").option("--reason <text>", "close reason").action(
+    runAction(
+      state,
+      (client, opts) => client.changeRequests.close({
+        changeRequestId: opts.changeRequestId,
+        reason: opts.reason
+      })
+    )
+  );
+  addGlobalFlags(changeRequests.command("merge")).description("Merge a Change Request into its Base").requiredOption("--change-request-id <id>", "Change Request id").action(
+    runAction(
+      state,
+      (client, opts) => client.changeRequests.merge({ changeRequestId: opts.changeRequestId })
+    )
+  );
+  addGlobalFlags(program.command("search")).description("Full-text search").requiredOption("--query <q>", "search query").option("--limit <n>", "max results", parseNum).option("--offset <n>", "results offset", parseNum).action(
+    runAction(
+      state,
+      (client, opts) => client.search({
+        query: opts.query,
+        limit: opts.limit,
+        offset: opts.offset
+      })
+    )
+  );
+  const addUploadCommand = (parent, hidden = false) => addGlobalFlags(parent.command("upload", { noHelp: hidden })).description("Upload a file and print an asset ref for record fields").requiredOption("--file <path>", "local file to upload").option("--file-name <name>", "stored file name (default: basename of --file)").option("--mime-type <mime>", "MIME type (default: inferred from extension)").option("--context <value>", "upload context (default record-field)").addHelpText(
+    "after",
+    `
+Example:
+  busabase-cli assets upload --file ./cover.png --output json
+
+Use the JSON output directly in an attachment field value, e.g. {"cover_image":[<output>]}.`
+  ).action(runAction(state, (_client, opts, config) => uploadAsset(config, opts)));
+  addUploadCommand(program.command("assets").description("Assets"));
+  addGlobalFlags(program.command("api")).description("Raw request to any /api/v1 endpoint").addOption(
+    new Option("--method <get|post|put|delete>", "HTTP method").choices(["get", "post", "put", "delete"]).makeOptionMandatory()
+  ).requiredOption("--path <p>", "path under /api/v1, e.g. /bases").option("--query <k=v...>", "query-string param, repeatable").option("--body-json <json>", "JSON request body").action(
+    runAction(state, (_client, opts, config) => {
+      const query = new URLSearchParams();
+      for (const pair of opts.query ?? []) {
+        const [key, ...rest] = pair.split("=");
+        query.set(key, rest.join("="));
+      }
+      const qs = query.toString();
+      const path = `/api/v1${opts.path}${qs ? `?${qs}` : ""}`;
+      const bodyJson = opts.bodyJson;
+      return rawFetch(
+        config,
+        opts.method,
+        path,
+        bodyJson ? parseJsonValue(bodyJson, "body-json") : void 0
+      );
+    })
+  );
+  registerGeneratedCommands(program, state);
+  for (const group of program.commands) {
+    const leaves = group.commands.length > 0 ? group.commands : [group];
+    for (const leaf of leaves) {
+      const sig = flagSignature(leaf);
+      leaf.usage(`${sig ? `${sig} ` : ""}[global flags]`);
+    }
+  }
+  program.addHelpText("after", () => `
+${commandsSection(program)}
+${HELP_FOOTER}`);
+  program.configureHelp({ visibleCommands: () => [] });
+  return program;
+}
+async function runCli(argv) {
+  const state = {};
+  const program = buildProgram(state);
+  if (argv.length === 0) {
+    program.outputHelp();
+    return 0;
+  }
+  try {
+    await program.parseAsync(argv, { from: "user" });
+    return 0;
+  } catch (error) {
+    if (error instanceof CommanderError) {
+      return error.exitCode === 0 ? 0 : 1;
+    }
+    console.error(explainError(error, state.config ?? resolveConfig({})));
+    return 1;
+  }
+}
+function renderedHelp() {
+  let out = "";
+  const program = buildProgram();
+  program.configureOutput({
+    writeOut: (str) => {
+      out += str;
+    },
+    writeErr: () => {
+    }
+  });
+  program.outputHelp();
+  return out;
+}
+var HELP = renderedHelp();
+function explainError(error, config) {
+  const base = config.baseUrl;
+  const msg = error instanceof Error ? error.message : String(error);
+  const status = error.status;
+  const lower = msg.toLowerCase();
+  let body;
+  if (status === 401 || lower.includes("401") || lower.includes("unauthorized")) {
+    body = [
+      `Unauthorized (401) from ${base}.`,
+      config.apiKey ? "  The credential was rejected or expired \u2014 run `busabase-cli login` to sign in again (browser OAuth or an API key)." : "  This host needs sign-in. Run `busabase-cli login` (browser OAuth or an API key), or pass --api-key <token> / export BUSABASE_API_KEY=\u2026.",
+      "  Meant to hit a local server? Add --base-url http://localhost:15419 (or export BUSABASE_BASE_URL=\u2026)."
+    ].join("\n");
+  } else if (lower.includes("fetch failed") || lower.includes("econnrefused") || lower.includes("enotfound") || lower.includes("getaddrinfo") || lower.includes("network")) {
+    body = [
+      `Could not reach ${base}.`,
+      "  \u2022 Cloud: check your internet connection and that the URL is correct.",
+      "  \u2022 Local: start it with `npx busabase server` (http://localhost:15419), then add --base-url http://localhost:15419 (or export BUSABASE_BASE_URL=\u2026).",
+      `  (underlying error: ${msg})`
+    ].join("\n");
+  } else {
+    body = `${msg}
+  (base URL: ${base}${config.apiKey ? ", with API key" : ", no API key"})`;
+  }
+  return `${body}
+  \u2192 Docs: ${DOCS_TROUBLESHOOTING}`;
+}
+
+export {
+  render,
+  runCli,
+  HELP
+};