busa-cli 0.9.6 → 0.9.8

package/dist/chunk-37OV7S7G.js

@@ -0,0 +1,4596 @@
+// 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 walk2 = (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) : [];
+      walk2(children, childPrefix, false);
+    });
+  };
+  walk2(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 createHash3 } from "crypto";
+import { readFileSync as readFileSync2 } from "fs";
+import { basename, extname as extname2 } from "path";
+import {
+  CREATABLE_NODE_TYPES as CREATABLE_NODE_TYPES2,
+  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);
+        authorizeUrl.searchParams.set("prompt", "login");
+        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.apiKey ?? payload.token ?? payload.accessToken;
+  if (!token) throw new Error("Token exchange returned no credential.");
+  return { token, expiresAt: payload.expiresAt ?? void 0 };
+}
+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/package/commands.ts
+import { readFile } from "fs/promises";
+import { join as join3 } from "path";
+
+// ../../packages/busabase-contract/src/domains/package/types.ts
+import { z as z6 } from "zod";
+
+// ../../packages/openlib/i18n/i-string.ts
+import { z as z2 } from "zod";
+
+// ../../packages/openlib/i18n/i18n.ts
+import { z } from "zod";
+var i18n = {
+  defaultLocale: "en",
+  locales: ["en", "zh-CN", "zh-TW", "ja", "ko", "de", "fr", "es", "pt"],
+  extendLocales: ["en", "zh-CN", "zh-TW", "ja", "ko", "fr", "de", "es", "ru", "it", "vi", "pt"]
+};
+var LocaleSchema = z.enum(i18n.locales);
+
+// ../../packages/openlib/i18n/i-string.ts
+var iStringRecordSchema = z2.partialRecord(LocaleSchema, z2.string());
+var iStringSchema = z2.union([z2.string(), iStringRecordSchema]).describe("i18n string");
+
+// ../../packages/busabase-contract/src/domains/base/contract/base-schemas.ts
+import { z as z3 } from "zod";
+var fieldNameSchema = z3.union([
+  z3.string().min(1),
+  iStringRecordSchema.refine(
+    (record) => Object.values(record).some((value) => value && value.trim().length > 0),
+    "field name must have at least one non-empty locale value"
+  )
+]);
+var fieldTypeSchema = z3.enum([
+  "text",
+  "longtext",
+  "markdown",
+  "html",
+  "attachment",
+  "relation",
+  "number",
+  "date",
+  "checkbox",
+  "select",
+  "multiselect",
+  "url",
+  "embed",
+  "email",
+  "phone",
+  "created_time",
+  "updated_time",
+  "created_by",
+  "updated_by",
+  "auto_number",
+  "ai_summary",
+  "ai_tags",
+  "code",
+  "json",
+  "yaml"
+]);
+var fieldOptionsSchema = z3.object({
+  ai: z3.object({
+    model: z3.string().optional(),
+    prompt: z3.string().optional(),
+    reviewRequired: z3.boolean().optional(),
+    sourceFieldIds: z3.array(z3.string()).optional()
+  }).optional(),
+  // Per-field config for `attachment` columns (all optional; logic enforces a
+  // 25MB ceiling regardless).
+  attachment: z3.object({
+    maxFiles: z3.number().int().positive().optional(),
+    allowedMimeTypes: z3.array(z3.string()).optional(),
+    maxFileSize: z3.number().int().positive().optional()
+  }).optional(),
+  choices: z3.array(
+    z3.object({
+      color: z3.string().optional(),
+      id: z3.string(),
+      name: z3.string()
+    })
+  ).optional(),
+  code: z3.object({
+    language: z3.string().optional()
+  }).optional(),
+  embed: z3.object({
+    aspectRatio: z3.enum(["16:9", "4:3", "1:1"]).optional(),
+    height: z3.number().int().positive().max(1200).optional(),
+    providers: z3.array(z3.string()).optional()
+  }).optional(),
+  inverseFieldId: z3.string().optional(),
+  multiple: z3.boolean().optional(),
+  // Display formatting for `number` columns (Notion-style: one number type,
+  // a format option). `currency` renders via Intl.NumberFormat.
+  number: z3.object({
+    format: z3.enum(["plain", "currency"]).optional(),
+    currency: z3.string().optional(),
+    locale: z3.string().optional()
+  }).optional(),
+  targetBaseId: z3.string().optional().describe("Relation target Base id (bse_\u2026). Or pass targetBaseSlug to name it by slug."),
+  targetBaseSlug: z3.string().optional().describe(
+    "Relation target Base by slug \u2014 a convenience alias for targetBaseId, resolved server-side (active bases in the current space). If both are given, targetBaseId wins."
+  )
+}).default({});
+var baseFieldSchema = z3.object({
+  id: z3.string(),
+  baseId: z3.string(),
+  slug: z3.string(),
+  name: fieldNameSchema,
+  type: fieldTypeSchema,
+  required: z3.boolean(),
+  position: z3.number(),
+  options: fieldOptionsSchema
+});
+var baseSchema = z3.object({
+  id: z3.string(),
+  nodeId: z3.string(),
+  slug: z3.string(),
+  name: z3.string(),
+  description: z3.string(),
+  reviewPolicy: z3.object({
+    kind: z3.literal("single"),
+    requiredApprovals: z3.number()
+  }),
+  createdAt: z3.string(),
+  fields: z3.array(baseFieldSchema)
+});
+var createBaseInputSchema = z3.object({
+  parentNodeId: z3.string().optional().describe(
+    "Parent node id. Must be a folder or the space root; container-incapable node types (Base, Doc, AirApp, etc.) cannot hold children."
+  ),
+  slug: z3.string().min(1).regex(/^[a-z0-9-]+$/),
+  name: z3.string().min(1),
+  description: z3.string().optional().default(""),
+  fields: z3.array(
+    z3.object({
+      slug: z3.string().min(1),
+      name: fieldNameSchema,
+      type: fieldTypeSchema.default("text"),
+      required: z3.boolean().default(false),
+      options: fieldOptionsSchema.optional().default({})
+    })
+  ).default([]),
+  // Review-first by default: without `autoMerge: true`, this proposes the Base
+  // as a pending ChangeRequest (status "in_review") instead of creating it
+  // immediately. Pass `autoMerge: true` only for callers that don't need human
+  // review (seed/migration scripts, an explicit no-review agent task).
+  autoMerge: z3.boolean().optional().default(false)
+});
+var createBaseFieldInputSchema = z3.object({
+  name: fieldNameSchema,
+  // Field slugs are snake_case identifiers (e.g. `cover_image`, `publish_date`) — the
+  // seed and the inline-fields path on `POST /bases` already allow underscores, so the
+  // add-field endpoint must too. (Base/folder/view slugs stay kebab-case: they go in URLs.)
+  slug: z3.string().min(1).regex(/^[a-z0-9_-]+$/),
+  type: fieldTypeSchema.default("text"),
+  required: z3.boolean().optional().default(false),
+  options: fieldOptionsSchema.optional().default({})
+});
+var createFieldChangeRequestInputSchema = createBaseFieldInputSchema.extend({
+  message: z3.string().optional().default("Add field"),
+  submittedBy: z3.string().optional().default("local-editor")
+});
+var deleteFieldChangeRequestInputSchema = z3.object({
+  fieldId: z3.string().min(1),
+  message: z3.string().optional(),
+  submittedBy: z3.string().optional().default("local-editor")
+});
+var updateFieldChangeRequestInputSchema = z3.object({
+  fieldId: z3.string().min(1),
+  patch: z3.object({
+    name: fieldNameSchema.optional(),
+    required: z3.boolean().optional(),
+    options: fieldOptionsSchema.optional()
+  }),
+  message: z3.string().optional(),
+  submittedBy: z3.string().optional().default("local-editor")
+});
+var previewFieldConversionInputSchema = z3.object({
+  fieldId: z3.string().min(1),
+  newType: fieldTypeSchema
+});
+var previewFieldConversionOutputSchema = z3.object({
+  totalCount: z3.number(),
+  convertibleCount: z3.number(),
+  nullCount: z3.number(),
+  conflicts: z3.array(z3.object({ recordId: z3.string(), currentValue: z3.unknown() }))
+});
+var convertFieldChangeRequestInputSchema = z3.object({
+  fieldId: z3.string().min(1),
+  newType: fieldTypeSchema,
+  selectChoiceMode: z3.enum(["auto_create", "null_on_missing"]).default("null_on_missing"),
+  message: z3.string().optional(),
+  submittedBy: z3.string().optional().default("local-editor")
+});
+var reorderFieldsChangeRequestInputSchema = z3.object({
+  fieldIds: z3.array(z3.string()).min(1),
+  message: z3.string().optional(),
+  submittedBy: z3.string().optional().default("local-editor")
+});
+var archiveBaseInputSchema = z3.object({
+  message: z3.string().optional(),
+  submittedBy: z3.string().optional().default("local-editor")
+});
+var restoreBaseInputSchema = z3.object({
+  message: z3.string().optional(),
+  submittedBy: z3.string().optional().default("local-editor")
+});
+var restoreFieldChangeRequestInputSchema = z3.object({
+  fieldId: z3.string().min(1),
+  message: z3.string().optional(),
+  submittedBy: z3.string().optional().default("local-editor")
+});
+
+// ../../packages/busabase-contract/src/domains/base/contract/view-schemas.ts
+import { z as z5 } from "zod";
+
+// ../../packages/busabase-contract/src/contract/schemas.ts
+import { z as z4 } from "zod";
+
+// ../../packages/busabase-contract/src/domains/filetree/definition.ts
+var fileTreeOperations = (type) => [
+  {
+    kind: `${type}_file_create`,
+    label: "Create file",
+    tone: "border-emerald-200 bg-emerald-50 text-emerald-800"
+  },
+  {
+    kind: `${type}_file_update`,
+    label: "Update file",
+    tone: "border-blue-200 bg-blue-50 text-blue-800"
+  },
+  {
+    kind: `${type}_file_delete`,
+    label: "Delete file",
+    tone: "border-rose-200 bg-rose-50 text-rose-800"
+  },
+  {
+    kind: `${type}_metadata_update`,
+    label: `Update ${type}`,
+    tone: "border-violet-200 bg-violet-50 text-violet-800"
+  }
+];
+var makeFileTreeNodeType = (config) => ({
+  type: config.type,
+  label: config.label,
+  icon: config.icon,
+  capabilities: { hasDetail: true, creatable: true },
+  operations: fileTreeOperations(config.type)
+});
+
+// ../../packages/busabase-contract/src/domains/airapp/definition.ts
+var airappNodeType = makeFileTreeNodeType({
+  type: "airapp",
+  label: "AirApp",
+  icon: "app-window",
+  routeBase: "airapps",
+  tag: "AirApps",
+  entryFile: "package.json"
+});
+
+// ../../packages/busabase-contract/src/domains/base/definition.ts
+var baseNodeType = {
+  type: "base",
+  label: "Base",
+  icon: "table",
+  capabilities: { hasDetail: true, creatable: true },
+  operations: [
+    {
+      kind: "record_create",
+      label: "Create",
+      tone: "border-emerald-200 bg-emerald-50 text-emerald-800"
+    },
+    { kind: "record_update", label: "Update", tone: "border-sky-200 bg-sky-50 text-sky-800" },
+    { kind: "record_delete", label: "Delete", tone: "border-red-200 bg-red-50 text-red-800" },
+    {
+      kind: "record_variant",
+      label: "Variant",
+      tone: "border-violet-200 bg-violet-50 text-violet-800"
+    },
+    {
+      kind: "view_create",
+      label: "Create view",
+      tone: "border-indigo-200 bg-indigo-50 text-indigo-800"
+    },
+    { kind: "view_update", label: "Update view", tone: "border-blue-200 bg-blue-50 text-blue-800" },
+    { kind: "view_delete", label: "Delete view", tone: "border-rose-200 bg-rose-50 text-rose-800" },
+    {
+      kind: "view_restore",
+      label: "Restore view",
+      tone: "border-emerald-200 bg-emerald-50 text-emerald-800"
+    },
+    {
+      kind: "base_add_field",
+      label: "Add field",
+      tone: "border-emerald-200 bg-emerald-50 text-emerald-800"
+    },
+    {
+      kind: "base_delete_field",
+      label: "Delete field",
+      tone: "border-red-200 bg-red-50 text-red-800"
+    },
+    {
+      kind: "base_update_field",
+      label: "Update field",
+      tone: "border-sky-200 bg-sky-50 text-sky-800"
+    },
+    {
+      kind: "base_convert_field",
+      label: "Convert field",
+      tone: "border-violet-200 bg-violet-50 text-violet-800"
+    },
+    {
+      kind: "base_reorder_fields",
+      label: "Reorder fields",
+      tone: "border-indigo-200 bg-indigo-50 text-indigo-800"
+    },
+    {
+      kind: "base_restore_field",
+      label: "Restore field",
+      tone: "border-teal-200 bg-teal-50 text-teal-800"
+    },
+    {
+      kind: "base_archive",
+      label: "Archive base",
+      tone: "border-orange-200 bg-orange-50 text-orange-800"
+    },
+    {
+      kind: "base_restore",
+      label: "Restore base",
+      tone: "border-teal-200 bg-teal-50 text-teal-800"
+    },
+    {
+      kind: "record_restore",
+      label: "Restore record",
+      tone: "border-teal-200 bg-teal-50 text-teal-800"
+    }
+  ]
+};
+
+// ../../packages/busabase-contract/src/domains/doc/definition.ts
+var docNodeType = {
+  type: "doc",
+  label: "Doc",
+  icon: "file-text",
+  capabilities: { hasDetail: true, creatable: true },
+  operations: [
+    {
+      kind: "doc_update",
+      label: "Update doc",
+      tone: "border-blue-200 bg-blue-50 text-blue-800"
+    }
+  ]
+};
+
+// ../../packages/busabase-contract/src/domains/drive/definition.ts
+var driveNodeType = makeFileTreeNodeType({
+  type: "drive",
+  label: "Drive",
+  icon: "hard-drive",
+  routeBase: "drives",
+  tag: "Drives",
+  entryFile: "README.md"
+});
+
+// ../../packages/busabase-contract/src/domains/file-node/definition.ts
+var fileNodeType = {
+  type: "file",
+  label: "File",
+  icon: "file",
+  capabilities: { hasDetail: true, creatable: true },
+  operations: []
+};
+
+// ../../packages/busabase-contract/src/domains/folder/definition.ts
+var folderNodeType = {
+  type: "folder",
+  label: "Folder",
+  icon: "folder",
+  capabilities: { container: true, creatable: true, hasDetail: true },
+  operations: []
+};
+
+// ../../packages/busabase-contract/src/domains/skill/definition.ts
+var skillNodeType = makeFileTreeNodeType({
+  type: "skill",
+  label: "Skill",
+  icon: "sparkles",
+  routeBase: "skills",
+  tag: "Skills",
+  entryFile: "SKILL.md"
+});
+
+// ../../packages/busabase-contract/src/domains/registry.ts
+var GENERIC_NODE_OPERATIONS = [
+  {
+    kind: "node_create",
+    label: "Create node",
+    tone: "border-emerald-200 bg-emerald-50 text-emerald-800"
+  },
+  { kind: "node_rename", label: "Rename node", tone: "border-sky-200 bg-sky-50 text-sky-800" },
+  { kind: "node_delete", label: "Delete node", tone: "border-red-200 bg-red-50 text-red-800" },
+  {
+    kind: "node_restore",
+    label: "Restore node",
+    tone: "border-emerald-200 bg-emerald-50 text-emerald-800"
+  },
+  { kind: "node_move", label: "Move node", tone: "border-indigo-200 bg-indigo-50 text-indigo-800" }
+];
+var registry = /* @__PURE__ */ new Map();
+function registerNodeType(definition) {
+  registry.set(definition.type, definition);
+}
+var BUILTIN_NODE_TYPES = [
+  folderNodeType,
+  baseNodeType,
+  skillNodeType,
+  driveNodeType,
+  airappNodeType,
+  fileNodeType,
+  docNodeType
+];
+for (const definition of BUILTIN_NODE_TYPES) {
+  registerNodeType(definition);
+}
+var NODE_TYPES = BUILTIN_NODE_TYPES.map((definition) => definition.type);
+var CREATABLE_NODE_TYPES = BUILTIN_NODE_TYPES.filter(
+  (definition) => Boolean(definition.capabilities.creatable)
+).map((definition) => definition.type);
+var ALL_OPERATIONS = [
+  ...GENERIC_NODE_OPERATIONS,
+  ...BUILTIN_NODE_TYPES.flatMap(
+    (definition) => definition.operations
+  )
+];
+var OPERATION_KINDS = ALL_OPERATIONS.map((operation) => operation.kind);
+var GENERIC_NODE_OPERATION_KINDS = GENERIC_NODE_OPERATIONS.map(
+  (operation) => operation.kind
+);
+var OPERATION_META = Object.fromEntries(
+  ALL_OPERATIONS.map((operation) => [
+    operation.kind,
+    { label: operation.label, tone: operation.tone }
+  ])
+);
+
+// ../../packages/busabase-contract/src/contract/schemas.ts
+var nodeSchema = z4.lazy(
+  () => z4.object({
+    id: z4.string(),
+    parentId: z4.string().nullable(),
+    type: z4.enum(NODE_TYPES),
+    slug: z4.string(),
+    name: z4.string(),
+    description: z4.string(),
+    metadata: z4.object({
+      entryFile: z4.string().optional(),
+      visibility: z4.enum(["private", "workspace", "public"]).optional(),
+      version: z4.string().optional(),
+      assetId: z4.string().optional()
+    }).default({}),
+    position: z4.number(),
+    createdAt: z4.string(),
+    updatedAt: z4.string(),
+    baseId: z4.string().nullable(),
+    children: z4.array(nodeSchema),
+    hasChildren: z4.boolean().optional()
+  })
+);
+var nodePrincipalSchema = z4.object({
+  id: z4.string(),
+  nodeId: z4.string(),
+  principalType: z4.enum(["user", "team", "space"]),
+  principalId: z4.string(),
+  role: z4.enum(["read", "changeRequest", "write", "manage"]),
+  grantedBy: z4.string(),
+  createdAt: z4.string(),
+  updatedAt: z4.string()
+});
+var listNodesInputSchema = z4.object({
+  parentId: z4.string().nullable().optional().describe("Node to start from. Omit or null to start from the space root."),
+  depth: z4.coerce.number().int().min(1).max(5).optional().describe(
+    "How many levels beneath the start point to eagerly include (default 2 once either field is set). Capped at 5."
+  )
+}).optional();
+var isDescendantInputSchema = z4.object({
+  nodeId: z4.string(),
+  potentialAncestorId: z4.string()
+});
+var isDescendantOutputSchema = z4.object({
+  isDescendant: z4.boolean()
+});
+var userRefSchema = z4.object({
+  id: z4.string(),
+  name: z4.string().nullable(),
+  email: z4.string().nullable(),
+  image: z4.string().nullable(),
+  role: z4.string().nullable().optional()
+});
+var commitSchema = z4.object({
+  id: z4.string(),
+  baseId: z4.string().nullable(),
+  targetType: z4.enum(["base", "node"]),
+  nodeId: z4.string().nullable(),
+  operationId: z4.string().nullable(),
+  parentCommitId: z4.string().nullable(),
+  fields: z4.record(z4.string(), z4.unknown()),
+  operation: z4.enum(OPERATION_KINDS),
+  message: z4.string(),
+  author: z4.string(),
+  authorUser: userRefSchema.nullable().optional().default(null),
+  createdAt: z4.string()
+});
+var operationSchema = z4.object({
+  id: z4.string(),
+  changeRequestId: z4.string(),
+  baseId: z4.string().nullable(),
+  targetType: z4.enum(["base", "node"]),
+  nodeId: z4.string().nullable(),
+  operation: z4.enum(OPERATION_KINDS),
+  status: z4.enum(["pending", "merged", "archived", "failed"]),
+  targetRecordId: z4.string().nullable(),
+  targetViewId: z4.string().nullable(),
+  filePath: z4.string().nullable(),
+  sourceRecordId: z4.string().nullable(),
+  sourceCommitId: z4.string().nullable(),
+  baseCommitId: z4.string().nullable(),
+  headCommitId: z4.string(),
+  deleteMode: z4.enum(["archive"]),
+  mergedRecordId: z4.string().nullable(),
+  mergedViewId: z4.string().nullable(),
+  position: z4.number(),
+  createdAt: z4.string(),
+  updatedAt: z4.string(),
+  headCommit: commitSchema,
+  // Resolved canonical "before" values for the operation's target, so the UI can
+  // render a true before → after field diff. Null for creations (no prior state)
+  // and for kinds whose prior state isn't a field map (e.g. skill files, whose
+  // previous content lives in storage). Records resolve from the base commit;
+  // views resolve from the current view row ({ name, description, config }).
+  baseFields: z4.record(z4.string(), z4.unknown()).nullable()
+});
+var reviewSchema = z4.object({
+  id: z4.string(),
+  changeRequestId: z4.string(),
+  reviewerId: z4.string(),
+  reviewer: userRefSchema.nullable().optional().default(null),
+  verdict: z4.enum(["approved", "rejected"]),
+  reason: z4.string().nullable(),
+  visibleOperationHeads: z4.record(z4.string(), z4.string()),
+  createdAt: z4.string()
+});
+var commentSubjectTypeSchema = z4.enum(["record", "change_request", "operation", "commit"]);
+var commentSchema = z4.object({
+  id: z4.string(),
+  subjectType: commentSubjectTypeSchema,
+  subjectId: z4.string(),
+  recordId: z4.string().nullable(),
+  changeRequestId: z4.string().nullable(),
+  operationId: z4.string().nullable(),
+  commitId: z4.string().nullable(),
+  authorId: z4.string(),
+  author: userRefSchema.nullable().optional().default(null),
+  body: z4.string(),
+  mentionsAi: z4.boolean(),
+  createdAt: z4.string(),
+  updatedAt: z4.string()
+});
+var changeRequestStatusSchema = z4.enum([
+  "in_review",
+  "changes_requested",
+  "approved",
+  "rejected",
+  "merged",
+  "abandoned",
+  "conflict"
+]);
+var changeRequestSchema = z4.object({
+  id: z4.string(),
+  baseId: z4.string().nullable(),
+  targetType: z4.enum(["base", "node"]),
+  nodeId: z4.string().nullable(),
+  status: changeRequestStatusSchema,
+  submittedBy: z4.string(),
+  submittedByUser: userRefSchema.nullable().optional().default(null),
+  sourceMeta: z4.record(z4.string(), z4.unknown()),
+  reviewPolicySnapshot: z4.record(z4.string(), z4.unknown()),
+  mergeSummary: z4.record(z4.string(), z4.unknown()),
+  rejectedReason: z4.string().nullable(),
+  reviewedAt: z4.string().nullable(),
+  mergedAt: z4.string().nullable(),
+  createdAt: z4.string(),
+  updatedAt: z4.string(),
+  base: baseSchema.nullable(),
+  node: nodeSchema.nullable(),
+  operations: z4.array(operationSchema),
+  primaryOperation: operationSchema.nullable(),
+  operationCount: z4.number(),
+  reviews: z4.array(reviewSchema)
+});
+var agentTaskSchema = z4.object({
+  changeRequest: changeRequestSchema,
+  trigger: z4.enum(["changes_requested", "ai_mention"]),
+  reviewReason: z4.string().nullable(),
+  aiComments: z4.array(commentSchema)
+});
+var searchResultSchema = z4.object({
+  id: z4.string(),
+  kind: z4.enum(["record", "change_request", "base", "file"]),
+  title: z4.string(),
+  body: z4.string(),
+  eyebrow: z4.string(),
+  href: z4.string(),
+  updatedAt: z4.string().nullable()
+});
+var searchResponseSchema = z4.object({
+  query: z4.string(),
+  limit: z4.number(),
+  offset: z4.number(),
+  hasMore: z4.boolean(),
+  results: z4.array(searchResultSchema)
+});
+var liveEventSchema = z4.object({
+  kind: z4.enum([
+    "change_request.created",
+    "change_request.updated",
+    "change_request.deleted",
+    "change_request.reviewed",
+    "change_request.merged",
+    // Fired only when a CONTENT change request freshly enters human review
+    // (record_* ops created via record-ops.ts) — never for structural ops
+    // that auto-merge instantly (those still fire "change_request.created"
+    // via the audit funnel, but nothing needs reviewing). Consumed by
+    // `use-live-sync.ts` to pop a desktop Notification, and by
+    // busabase-cloud's host hook to persist an inbox notification row.
+    "change_request.pending_review"
+  ]),
+  spaceId: z4.string(),
+  actorId: z4.string(),
+  changeRequestId: z4.string(),
+  baseId: z4.string().nullable(),
+  nodeIds: z4.array(z4.string()),
+  recordIds: z4.array(z4.string()),
+  viewIds: z4.array(z4.string()),
+  operationCount: z4.number()
+});
+var auditActionSchema = z4.enum([
+  "record.viewed",
+  "change_request.created",
+  "change_request.updated",
+  "change_request.deleted",
+  "change_request.reviewed",
+  "change_request.merged",
+  // Direct (non-change-request) mutations — recorded so the audit trail stays
+  // complete even for operations that bypass the propose → review → merge flow
+  // (container bootstrap, direct edits, library/asset deletes, trash purge).
+  "base.created",
+  "field.created",
+  "doc.created",
+  "doc.updated",
+  "file.created",
+  "skill.created",
+  "drive.created",
+  "airapp.created",
+  "asset.deleted",
+  "asset.metadata_updated",
+  "asset.text_written",
+  "asset.text_marked_none",
+  "node.purged"
+]);
+var auditEventSchema = z4.object({
+  id: z4.string(),
+  action: auditActionSchema,
+  actorId: z4.string(),
+  actor: userRefSchema.nullable().optional().default(null),
+  baseId: z4.string().nullable(),
+  recordId: z4.string().nullable(),
+  changeRequestId: z4.string().nullable(),
+  operationId: z4.string().nullable(),
+  commitId: z4.string().nullable(),
+  metadata: z4.record(z4.string(), z4.unknown()),
+  createdAt: z4.string()
+});
+var createAuditEventInputSchema = z4.object({
+  action: auditActionSchema,
+  actorId: z4.string().optional().default("local-viewer"),
+  baseId: z4.string().optional().nullable(),
+  recordId: z4.string().optional().nullable(),
+  changeRequestId: z4.string().optional().nullable(),
+  operationId: z4.string().optional().nullable(),
+  commitId: z4.string().optional().nullable(),
+  metadata: z4.record(z4.string(), z4.unknown()).optional().default({})
+});
+var nodeOperationInputSchema = z4.discriminatedUnion("kind", [
+  z4.object({
+    kind: z4.literal("create"),
+    ref: z4.string().min(1).optional().describe(
+      'Optional in-change-request temp id for this node. A later operation can set parentNodeRef to this value to nest under it \u2014 e.g. create a folder with ref "growth", then create Bases with parentNodeRef "growth", all in one change request.'
+    ),
+    parentNodeId: z4.string().optional(),
+    parentNodeRef: z4.string().min(1).optional().describe(
+      "Parent this node under a node an EARLIER operation in the same change request created (matched by its ref). Mutually exclusive with parentNodeId."
+    ),
+    nodeType: z4.enum(CREATABLE_NODE_TYPES),
+    slug: z4.string().min(1).regex(/^[a-z0-9-]+$/),
+    name: z4.string().min(1),
+    description: z4.string().optional().default(""),
+    metadata: z4.record(z4.string(), z4.unknown()).optional().default({}),
+    // Base fields (nodeType "base" only); a base needs at least one field.
+    fields: z4.array(
+      z4.object({
+        slug: z4.string().min(1).regex(/^[a-z0-9-]+$/),
+        name: fieldNameSchema,
+        type: fieldTypeSchema.default("text"),
+        required: z4.boolean().optional().default(false),
+        options: fieldOptionsSchema.optional().default({})
+      })
+    ).optional()
+  }),
+  z4.object({
+    kind: z4.literal("rename"),
+    nodeId: z4.string(),
+    slug: z4.string().min(1).regex(/^[a-z0-9-]+$/).optional(),
+    name: z4.string().min(1).optional(),
+    description: z4.string().optional()
+  }),
+  z4.object({
+    kind: z4.literal("delete"),
+    nodeId: z4.string()
+  }),
+  z4.object({
+    kind: z4.literal("restore"),
+    nodeId: z4.string()
+  }),
+  z4.object({
+    kind: z4.literal("move"),
+    nodeId: z4.string(),
+    // Exactly one of parentNodeId / parentNodeRef (a ref created earlier in this CR).
+    parentNodeId: z4.string().optional(),
+    parentNodeRef: z4.string().min(1).optional(),
+    position: z4.number().int().optional()
+  })
+]);
+var createNodeChangeRequestInputSchema = z4.object({
+  message: z4.string().optional().default("Update node tree").describe(
+    'Explanation shown to the human reviewer. Write a conventional-commit style subject \u2014 imperative verb + what + why, e.g. "Reorganize marketing docs under a Campaigns folder".'
+  ),
+  submittedBy: z4.string().optional().default("local-producer"),
+  autoMerge: z4.boolean().optional().default(false).describe(
+    "Whether to approve and merge this structural node change immediately. Defaults to false so node Change Request creation is review-first unless explicitly requested."
+  ),
+  operations: z4.array(nodeOperationInputSchema).min(1)
+});
+var moveNodeInputSchema = z4.object({
+  nodeId: z4.string(),
+  parentNodeId: z4.string().optional().describe("New parent folder node id. Omit to keep the current parent and only reorder."),
+  position: z4.number().int().optional().describe("New position among the target parent's children."),
+  message: z4.string().optional().describe("Reviewer-facing Change Request message."),
+  submittedBy: z4.string().optional()
+});
+var createDeleteChangeRequestInputSchema = z4.object({
+  message: z4.string().optional().default("Delete record").describe(
+    'Explanation shown to the human reviewer. Say what is being removed and why, e.g. "Archive duplicate contact \u2014 merged into Acme Corp".'
+  ),
+  submittedBy: z4.string().optional().default("local-producer"),
+  // Only "archive" is supported — hard delete after retention was never
+  // implemented, so the API no longer accepts it (breaking change).
+  deleteMode: z4.enum(["archive"]).optional().default("archive")
+});
+var reviseOperationInputSchema = z4.object({
+  fields: z4.record(z4.string(), z4.unknown()).describe(
+    "Updated field values keyed by field slug. If you set the base's PRIMARY field (its first field), keep it a short human-readable name \u2014 it is the record's display title everywhere."
+  ),
+  message: z4.string().optional().default("Revise operation").describe(
+    'Explanation shown to the human reviewer. Write a conventional-commit style subject \u2014 imperative verb + what + why, e.g. "Update deal stage to qualified \u2014 demo booked for July 8".'
+  ),
+  author: z4.string().optional().default("local-producer"),
+  baseCommitId: z4.string().optional()
+});
+var reviewChangeRequestInputSchema = z4.object({
+  verdict: z4.enum(["approved", "rejected"]),
+  reason: z4.string().optional()
+});
+var commentSubjectInputSchema = z4.object({
+  subjectType: commentSubjectTypeSchema,
+  subjectId: z4.string().min(1)
+});
+var createCommentInputSchema = commentSubjectInputSchema.extend({
+  authorId: z4.string().optional().default("local-admin"),
+  body: z4.string().trim().min(1),
+  mentionsAi: z4.boolean().optional().default(false)
+});
+var listInputSchema = z4.object({
+  limit: z4.coerce.number().int().min(1).max(100).optional().default(50)
+}).optional().default({ limit: 50 });
+var listChangeRequestsPagedInputSchema = z4.object({
+  limit: z4.coerce.number().int().min(1).max(100).optional().default(50),
+  /** Opaque base64 cursor (`createdAt|id`) for keyset pagination. */
+  cursor: z4.string().optional(),
+  status: z4.array(changeRequestStatusSchema).optional(),
+  mine: z4.boolean().optional()
+}).optional().default({ limit: 50 });
+var listChangeRequestsResponseSchema = z4.object({
+  changeRequests: z4.array(changeRequestSchema),
+  nextCursor: z4.string().nullable()
+});
+var changeRequestCountsSchema = z4.object({
+  review: z4.number().int().nonnegative(),
+  changes: z4.number().int().nonnegative(),
+  created: z4.number().int().nonnegative(),
+  approved: z4.number().int().nonnegative(),
+  merged: z4.number().int().nonnegative(),
+  rejected: z4.number().int().nonnegative()
+});
+var SEARCH_SOURCES = ["records", "files", "names"];
+var searchInputSchema = z4.object({
+  query: z4.string().default(""),
+  limit: z4.coerce.number().int().min(1).max(100).optional().default(20),
+  offset: z4.coerce.number().int().min(0).optional().default(0),
+  /**
+   * Restrict which content this call searches. Omitted means all three
+   * (unchanged behavior for every caller before this parameter existed).
+   *
+   * A GET query param that occurs exactly once (`?sources=records`) arrives
+   * as a bare string, not a 1-element array — only a REPEATED occurrence
+   * (`?sources=records&sources=files`) becomes an array. Accept both shapes
+   * and normalize to an array.
+   */
+  sources: z4.union([z4.array(z4.enum(SEARCH_SOURCES)), z4.enum(SEARCH_SOURCES)]).transform((value) => Array.isArray(value) ? value : [value]).optional()
+});
+var authSpaceSchema = z4.object({
+  id: z4.string(),
+  name: z4.string(),
+  slug: z4.string().nullable(),
+  plan: z4.string().nullable()
+});
+var authUserSchema = z4.object({
+  id: z4.string(),
+  name: z4.string(),
+  email: z4.string().nullable(),
+  image: z4.string().nullable()
+});
+var authMemberSchema = z4.object({
+  userId: z4.string(),
+  spaceId: z4.string(),
+  role: z4.string()
+});
+var authInfoSchema = z4.object({
+  /** The space this request is scoped to (explicit `x-busabase-space` header, else the default). */
+  space: authSpaceSchema,
+  user: authUserSchema,
+  member: authMemberSchema,
+  /**
+   * Every space the authenticated user belongs to. An API key is user-scoped, not
+   * space-scoped — when this has more than one entry, callers should confirm the
+   * intended space and target it explicitly via the `x-busabase-space` header.
+   */
+  spaces: z4.array(authSpaceSchema)
+});
+
+// ../../packages/busabase-contract/src/domains/base/contract/view-schemas.ts
+var viewFilterOperatorSchema = z5.enum([
+  "contains",
+  "equals",
+  "not_empty",
+  "is_empty",
+  "is_true",
+  "is_false"
+]);
+var viewFilterSchema = z5.object({
+  fieldSlug: z5.string(),
+  // Stable field identity — survives slug reuse; populated on merge.
+  fieldId: z5.string().optional(),
+  operator: viewFilterOperatorSchema,
+  value: z5.unknown().optional()
+});
+var viewSortSchema = z5.object({
+  direction: z5.enum(["asc", "desc"]),
+  fieldSlug: z5.string(),
+  fieldId: z5.string().optional()
+});
+var viewTypeSchema = z5.enum(["table", "gallery", "kanban", "calendar", "gantt"]);
+var ganttScaleSchema = z5.enum(["week", "month"]);
+var galleryCoverFitSchema = z5.enum(["cover", "fit"]);
+var galleryCardSizeSchema = z5.enum(["small", "medium", "large"]);
+var viewConfigSchema = z5.object({
+  filters: z5.array(viewFilterSchema).default([]),
+  sorts: z5.array(viewSortSchema).default([]),
+  visibleFieldSlugs: z5.array(z5.string()).nullable().optional(),
+  // ── Gallery-only presentation config (ignored by table views) ──
+  // Which attachment field supplies the cover image (null = no cover).
+  coverFieldSlug: z5.string().nullable().optional(),
+  coverFit: galleryCoverFitSchema.optional(),
+  cardSize: galleryCardSizeSchema.optional(),
+  // Whether to render the field label above each value on a card.
+  showFieldLabels: z5.boolean().optional(),
+  // ── Kanban-only: which single-select field stacks records into columns.
+  stackByFieldSlug: z5.string().nullable().optional(),
+  // ── Calendar-only: which date field positions records on the month grid.
+  dateFieldSlug: z5.string().nullable().optional(),
+  // ── Gantt-only: the start/end date fields bounding each record's bar, plus
+  // the time-axis granularity.
+  startFieldSlug: z5.string().nullable().optional(),
+  endFieldSlug: z5.string().nullable().optional(),
+  ganttScale: ganttScaleSchema.optional()
+});
+var viewSchema = z5.object({
+  id: z5.string(),
+  baseId: z5.string(),
+  slug: z5.string(),
+  name: z5.string(),
+  description: z5.string(),
+  type: viewTypeSchema,
+  config: viewConfigSchema,
+  status: z5.enum(["active", "archived"]),
+  createdBy: z5.string(),
+  createdByUser: userRefSchema.nullable().optional().default(null),
+  archivedAt: z5.string().nullable(),
+  createdAt: z5.string(),
+  updatedAt: z5.string()
+});
+var createViewInputSchema = z5.object({
+  config: viewConfigSchema.optional().default({ filters: [], sorts: [] }),
+  description: z5.string().optional().default(""),
+  message: z5.string().optional().default("Create view"),
+  name: z5.string().min(1),
+  type: viewTypeSchema.optional().default("table"),
+  slug: z5.string().min(1).regex(/^[a-z0-9-]+$/).optional(),
+  submittedBy: z5.string().optional().default("local-producer")
+});
+var updateViewInputSchema = z5.object({
+  config: viewConfigSchema.optional(),
+  description: z5.string().optional(),
+  message: z5.string().optional().default("Update view"),
+  name: z5.string().min(1).optional(),
+  type: viewTypeSchema.optional(),
+  submittedBy: z5.string().optional().default("local-producer")
+});
+var deleteViewInputSchema = z5.object({
+  message: z5.string().optional().default("Delete view"),
+  submittedBy: z5.string().optional().default("local-producer")
+});
+var restoreViewInputSchema = z5.object({
+  message: z5.string().optional().default("Restore view"),
+  submittedBy: z5.string().optional().default("local-producer")
+});
+
+// ../../packages/busabase-contract/src/domains/package/types.ts
+var PACKAGE_FORMAT = "busabase-package@1";
+var PACKAGE_MANIFEST_FILENAME = "busabase.json";
+var PACKAGE_CONTENT_DIRNAME = "content";
+var PACKAGE_NODE_META_FILENAME = "_node.json";
+var PACKAGE_FOLDER_META_FILENAME = "_folder.json";
+var PACKAGE_BASE_FILENAME = "base.json";
+var PACKAGE_RECORDS_FILENAME = "records.ndjson";
+var PACKAGE_NODE_META_SUFFIX = ".node.json";
+var PACKAGE_FILE_TREE_NODE_TYPES = ["skill", "airapp", "drive"];
+var PACKAGE_AI_FIELD_TYPES = ["ai_summary", "ai_tags"];
+var PACKAGE_COMPUTED_FIELD_TYPES = [
+  "created_time",
+  "updated_time",
+  "created_by",
+  "updated_by",
+  "auto_number",
+  ...PACKAGE_AI_FIELD_TYPES
+];
+var PACKAGE_DEFERRED_FIELD_TYPES = [
+  "relation",
+  ...PACKAGE_AI_FIELD_TYPES
+];
+var PACKAGE_MAX_FILE_BYTES = 25 * 1024 * 1024;
+var PACKAGE_MAX_TOTAL_BYTES = 250 * 1024 * 1024;
+var PACKAGE_MAX_FILE_COUNT = 5e3;
+var PACKAGE_MAX_RECORDS_PER_BASE = 5e4;
+var PackageManifestSchema = z6.object({
+  format: z6.literal(PACKAGE_FORMAT),
+  /** Default `--into-folder` name. Not the repo name — a repo can host many packages. */
+  name: z6.string().min(1),
+  description: z6.string().default(""),
+  /**
+   * Informational / reserved for a future marketplace index. The real version pin
+   * is always the git ref in the install URL.
+   */
+  version: z6.string().optional(),
+  author: z6.string().optional(),
+  license: z6.string().optional(),
+  homepage: z6.string().url().optional(),
+  tags: z6.array(z6.string()).default([])
+});
+var PackageFileTreeNodeMetaSchema = z6.object({
+  type: z6.enum(PACKAGE_FILE_TREE_NODE_TYPES),
+  name: z6.string().min(1),
+  description: z6.string().default(""),
+  position: z6.number().int().optional()
+});
+var PackageFolderMetaSchema = z6.object({
+  /** Defaults to the humanized slug when absent. */
+  name: z6.string().optional(),
+  description: z6.string().default(""),
+  position: z6.number().int().optional()
+});
+var PackageFileNodeMetaSchema = PackageFolderMetaSchema;
+var PackageDocFrontmatterSchema = z6.object({
+  name: z6.string().min(1),
+  description: z6.string().default(""),
+  position: z6.number().int().optional()
+});
+var PackageFieldOptionsSchema = z6.object({
+  ai: z6.object({
+    model: z6.string().optional(),
+    prompt: z6.string().optional(),
+    reviewRequired: z6.boolean().optional(),
+    /** Package-only — replaces `ai.sourceFieldIds`. */
+    sourceFieldSlugs: z6.array(z6.string()).optional()
+  }).optional(),
+  attachment: z6.object({
+    maxFiles: z6.number().int().positive().optional(),
+    allowedMimeTypes: z6.array(z6.string()).optional(),
+    maxFileSize: z6.number().int().positive().optional()
+  }).optional(),
+  choices: z6.array(
+    z6.object({
+      color: z6.string().optional(),
+      id: z6.string(),
+      name: z6.string()
+    })
+  ).optional(),
+  code: z6.object({
+    language: z6.string().optional()
+  }).optional(),
+  embed: z6.object({
+    aspectRatio: z6.enum(["16:9", "4:3", "1:1"]).optional(),
+    height: z6.number().int().positive().max(1200).optional(),
+    providers: z6.array(z6.string()).optional()
+  }).optional(),
+  /** Package-only — replaces `inverseFieldId`. */
+  inverseFieldSlug: z6.string().optional(),
+  multiple: z6.boolean().optional(),
+  number: z6.object({
+    format: z6.enum(["plain", "currency"]).optional(),
+    currency: z6.string().optional(),
+    locale: z6.string().optional()
+  }).optional(),
+  /** Native API alias — the server resolves it to `targetBaseId`. */
+  targetBaseSlug: z6.string().optional()
+}).default({});
+var PackageBaseFieldSchema = z6.object({
+  slug: z6.string().min(1),
+  name: fieldNameSchema,
+  type: fieldTypeSchema,
+  required: z6.boolean().default(false),
+  position: z6.number().int(),
+  options: PackageFieldOptionsSchema
+});
+var PackageViewFilterSchema = z6.object({
+  fieldSlug: z6.string().min(1),
+  operator: viewFilterOperatorSchema,
+  value: z6.unknown().optional()
+});
+var PackageViewSortSchema = z6.object({
+  direction: z6.enum(["asc", "desc"]),
+  fieldSlug: z6.string().min(1)
+});
+var PackageViewConfigSchema = z6.object({
+  filters: z6.array(PackageViewFilterSchema).default([]),
+  sorts: z6.array(PackageViewSortSchema).default([]),
+  visibleFieldSlugs: z6.array(z6.string()).nullable().optional()
+});
+var PackageViewSchema = z6.object({
+  slug: z6.string().min(1),
+  name: z6.string().min(1),
+  description: z6.string().default(""),
+  type: z6.literal("table").default("table"),
+  config: PackageViewConfigSchema.default({ filters: [], sorts: [] })
+});
+var PackageBaseSchema = z6.object({
+  name: z6.string().min(1),
+  description: z6.string().default(""),
+  position: z6.number().int().optional(),
+  /**
+   * Informational only — `reviewPolicy` is NOT settable via `bases.create`, so
+   * install cannot apply it and warns when it differs from the target's default.
+   */
+  reviewPolicy: z6.object({
+    kind: z6.literal("single"),
+    requiredApprovals: z6.number()
+  }).optional(),
+  fields: z6.array(PackageBaseFieldSchema).default([]),
+  views: z6.array(PackageViewSchema).default([])
+});
+var PackageRecordLineSchema = z6.object({
+  key: z6.string().min(1),
+  fields: z6.record(z6.string(), z6.unknown()).default({})
+});
+
+// src/package/apply.ts
+import { createHash as createHash2 } from "crypto";
+
+// src/package/tree.ts
+import { extname } from "path";
+var NODE_SLUG_PATTERN = /^[a-z0-9-]+$/;
+var assertSafeNodeSlug = (slug, context) => {
+  if (!NODE_SLUG_PATTERN.test(slug)) {
+    throw new Error(
+      `Invalid slug "${slug}" (${context}). Slugs must be lowercase letters, digits, and hyphens only (a-z, 0-9, -) \u2014 that keeps them safe as file names on every OS and valid for the Busabase API. Rename it, e.g. "${suggestSlug(slug)}".`
+    );
+  }
+};
+var suggestSlug = (value) => {
+  const suggestion = value.normalize("NFKD").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return suggestion || "renamed";
+};
+var UNSAFE_PATH_CHARS = /[/\\:*?"<>|]/;
+var assertSafeFilePath = (filePath, context) => {
+  for (const segment of filePath.split("/")) {
+    if (!segment) {
+      throw new Error(`Invalid file path "${filePath}" (${context}): empty path segment.`);
+    }
+    if (UNSAFE_PATH_CHARS.test(segment)) {
+      throw new Error(
+        `Invalid file path "${filePath}" (${context}): the segment "${segment}" contains a character that is illegal in a file name on Windows or macOS (/ \\ : * ? " < > |). Rename the file.`
+      );
+    }
+    if (/^[. ]|[. ]$/.test(segment)) {
+      throw new Error(
+        `Invalid file path "${filePath}" (${context}): the segment "${segment}" starts or ends with a dot or space, which does not survive a checkout on every OS. Rename the file.`
+      );
+    }
+  }
+};
+var assertNoSiblingCaseCollisions = (names, context) => {
+  const seenByLower = /* @__PURE__ */ new Map();
+  for (const name of names) {
+    const lower = name.toLowerCase();
+    const existing = seenByLower.get(lower);
+    if (existing !== void 0 && existing !== name) {
+      throw new Error(
+        `Sibling name collision (${context}): "${existing}" and "${name}" differ only by case. macOS and Windows treat them as the same file, so one would silently overwrite the other on checkout. Rename one.`
+      );
+    }
+    seenByLower.set(lower, name);
+  }
+};
+var isReservedPackageFilename = (name) => name === PACKAGE_MANIFEST_FILENAME || name === PACKAGE_NODE_META_FILENAME || name === PACKAGE_FOLDER_META_FILENAME || name === PACKAGE_BASE_FILENAME || name === PACKAGE_RECORDS_FILENAME || name.endsWith(PACKAGE_NODE_META_SUFFIX);
+var assertNoReservedNames = (filePaths, context) => {
+  for (const filePath of filePaths) {
+    const [rootName, ...rest] = filePath.split("/");
+    if (rest.length === 0 && isReservedPackageFilename(rootName)) {
+      throw new Error(
+        `Reserved file name at the root of ${context}: "${rootName}" is part of the package format, so it cannot also be this node's own content. Rename it (e.g. "${renameReserved(rootName)}"), or move it into a subdirectory \u2014 names are only interpreted at the node's root.`
+      );
+    }
+  }
+};
+var renameReserved = (name) => {
+  const ext = extname(name);
+  return ext ? `${name.slice(0, -ext.length)}-file${ext}` : `${name}-file`;
+};
+var compareNodes = (a, b) => {
+  if (a.position !== void 0 && b.position !== void 0 && a.position !== b.position) {
+    return a.position - b.position;
+  }
+  if (a.position !== void 0 && b.position === void 0) return -1;
+  if (a.position === void 0 && b.position !== void 0) return 1;
+  return a.slug.localeCompare(b.slug, "en");
+};
+var sortNodes = (nodes) => [...nodes].sort(compareNodes);
+var humanizeSlug = (slug) => slug.split("-").filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+var MIME_BY_EXT = {
+  ".css": "text/css",
+  ".csv": "text/csv",
+  ".gif": "image/gif",
+  ".htm": "text/html",
+  ".html": "text/html",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".js": "text/javascript",
+  ".json": "application/json",
+  ".md": "text/markdown",
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".py": "text/x-python",
+  ".svg": "image/svg+xml",
+  ".ts": "text/typescript",
+  ".txt": "text/plain",
+  ".webp": "image/webp",
+  ".yaml": "text/yaml",
+  ".yml": "text/yaml"
+};
+var guessMimeType = (filePath) => MIME_BY_EXT[extname(filePath).toLowerCase()] ?? "application/octet-stream";
+var isTextMimeType = (mimeType) => mimeType.startsWith("text/") || mimeType === "application/json" || mimeType === "image/svg+xml";
+var walkNodes = function* (nodes) {
+  for (const node of nodes) {
+    yield node;
+    if (node.type === "folder") yield* walkNodes(node.children);
+  }
+};
+var collectBaseNodes = (nodes) => [...walkNodes(nodes)].filter((node) => node.type === "base");
+
+// src/package/apply.ts
+var RECORD_BATCH_SIZE = 200;
+var fieldKey = (baseSlug, fieldSlug) => `${baseSlug}\0${fieldSlug}`;
+var applyInstall = async (client, plan, options) => {
+  const state = {
+    targetFolderNodeId: "",
+    created: { folders: 0, docs: 0, bases: 0, views: 0, records: 0, fileTreeNodes: 0, files: 0 },
+    pendingChangeRequests: 0,
+    warnings: [...plan.warnings]
+  };
+  const fieldIds = /* @__PURE__ */ new Map();
+  const bases = [];
+  const progress = options.onProgress ?? (() => {
+  });
+  progress("Pass 1/5: creating the node tree\u2026");
+  state.targetFolderNodeId = await createFolderNode(client, {
+    parentNodeId: void 0,
+    slug: plan.targetFolderSlug,
+    name: plan.tree.manifest.name,
+    description: plan.tree.manifest.description,
+    submittedBy: options.submittedBy
+  });
+  state.created.folders++;
+  await createStructure(
+    client,
+    plan.tree.nodes,
+    state.targetFolderNodeId,
+    options,
+    state,
+    bases,
+    fieldIds
+  );
+  const deferred = bases.filter((base) => base.node.base.fields.some(isDeferredField));
+  if (deferred.length > 0) {
+    progress("Pass 2/5: adding relation and AI fields\u2026");
+    for (const base of deferred) {
+      for (const field of base.node.base.fields.filter(isDeferredField)) {
+        const updated = await client.bases.createField({
+          baseId: base.baseId,
+          slug: field.slug,
+          name: field.name,
+          type: field.type,
+          required: field.required,
+          options: toApiFieldOptions(field.options)
+        });
+        indexFields(fieldIds, base.node.slug, updated.fields);
+      }
+    }
+  }
+  const patchable = bases.flatMap(
+    (base) => base.node.base.fields.filter(needsFieldIdPatch).map((field) => ({ base, field }))
+  );
+  if (patchable.length > 0) {
+    progress("Pass 3/5: resolving inverse and AI source field references\u2026");
+    for (const { base, field } of patchable) {
+      const fieldId = fieldIds.get(fieldKey(base.node.slug, field.slug));
+      if (!fieldId) {
+        throw new Error(
+          `Internal error: no field id for ${base.node.slug}.${field.slug} in pass 3.`
+        );
+      }
+      const patched = resolveFieldIdOptions(field, base.node.slug, fieldIds, state.warnings);
+      if (!patched) continue;
+      const changeRequest = await client.bases.updateFieldChangeRequest({
+        baseId: base.baseId,
+        fieldId,
+        patch: { options: patched },
+        message: `Wire up ${base.node.slug}.${field.slug} references`,
+        submittedBy: options.submittedBy
+      });
+      await approveAndMerge(client, changeRequest.id);
+    }
+  }
+  const recordIdsByKey = /* @__PURE__ */ new Map();
+  const withRecords = bases.filter((base) => base.node.records.length > 0);
+  if (withRecords.length > 0) {
+    progress("Pass 4/5: creating records\u2026");
+    for (const base of withRecords) {
+      await createRecords(client, base, plan, options, state, recordIdsByKey);
+    }
+  }
+  const relationFieldSlugs = /* @__PURE__ */ new Map();
+  for (const base of bases) {
+    const slugs = base.node.base.fields.filter((field) => field.type === "relation").map((field) => field.slug);
+    if (slugs.length > 0) relationFieldSlugs.set(base.node.slug, slugs);
+  }
+  if (relationFieldSlugs.size > 0) {
+    progress("Pass 5/5: linking relations\u2026");
+    for (const base of bases) {
+      const slugs = relationFieldSlugs.get(base.node.slug);
+      if (!slugs) continue;
+      await linkRelations(client, base, slugs, recordIdsByKey, options, state);
+    }
+  }
+  return state;
+};
+var createStructure = async (client, nodes, parentNodeId, options, state, bases, fieldIds) => {
+  for (const node of nodes) {
+    switch (node.type) {
+      case "folder": {
+        const nodeId = await createFolderNode(client, {
+          parentNodeId,
+          slug: node.slug,
+          name: node.name,
+          description: node.description,
+          submittedBy: options.submittedBy
+        });
+        state.created.folders++;
+        await createStructure(client, node.children, nodeId, options, state, bases, fieldIds);
+        break;
+      }
+      case "doc": {
+        const result = await client.docs.create({
+          parentNodeId,
+          slug: node.slug,
+          name: node.name,
+          description: node.description,
+          body: node.body,
+          autoMerge: options.autoMerge
+        });
+        if (result.materialized) state.created.docs++;
+        else state.pendingChangeRequests++;
+        break;
+      }
+      case "base": {
+        await createBase(client, node, parentNodeId, options, state, bases, fieldIds);
+        break;
+      }
+      case "skill":
+      case "airapp":
+      case "drive": {
+        await createFileTreeNode(client, node, parentNodeId, options, state);
+        break;
+      }
+      case "file": {
+        let asset;
+        try {
+          asset = await uploadAsset(client, node.fileName, node.mimeType, node.bytes);
+        } catch (error) {
+          state.warnings.push(asSkippableUpload(error, node.fileName));
+          break;
+        }
+        const result = await client.files.create({
+          parentNodeId,
+          slug: node.slug,
+          name: node.name,
+          description: node.description,
+          assetId: asset.assetId,
+          autoMerge: options.autoMerge
+        });
+        if (result.materialized) state.created.files++;
+        else state.pendingChangeRequests++;
+        break;
+      }
+    }
+  }
+};
+var createFolderNode = async (client, input) => {
+  const changeRequest = await client.nodes.createChangeRequest({
+    message: `Install folder ${input.slug}`,
+    submittedBy: input.submittedBy,
+    autoMerge: true,
+    operations: [
+      {
+        kind: "create",
+        nodeType: "folder",
+        slug: input.slug,
+        name: input.name,
+        description: input.description,
+        parentNodeId: input.parentNodeId
+      }
+    ]
+  });
+  const nodeId = changeRequest.operations[0]?.nodeId;
+  if (!nodeId) {
+    throw new Error(
+      `Folder "${input.slug}" was created but the server returned no node id, so nothing could be installed inside it.`
+    );
+  }
+  return nodeId;
+};
+var createBase = async (client, node, parentNodeId, options, state, bases, fieldIds) => {
+  const immediateFields = node.base.fields.filter((field) => !isDeferredField(field)).map((field) => ({
+    slug: field.slug,
+    name: field.name,
+    type: field.type,
+    required: field.required,
+    options: toApiFieldOptions(field.options)
+  }));
+  const result = await client.bases.create({
+    parentNodeId,
+    slug: node.slug,
+    name: node.name,
+    description: node.description,
+    fields: immediateFields,
+    // A Base's schema is structure, so it is created immediately even on a
+    // review-first install — the same reasoning as folders (see createFolderNode).
+    // This is load-bearing, not a shortcut: a PENDING Base has no id, and without
+    // an id there is nothing to hang views, field patches, or records on. When the
+    // base was left pending, its records were dropped on the floor with no error —
+    // the user merged the change request and got an empty Base. Materializing the
+    // container is what lets the CONTENT (records, below) be proposed for review at
+    // all, which is the part a reviewer actually wants to see.
+    autoMerge: true
+  });
+  if (!result.materialized) {
+    throw new Error(
+      `Base "${node.slug}" was requested immediately but the server returned a pending change request; install cannot attach its views or records to it.`
+    );
+  }
+  state.created.bases++;
+  bases.push({ node, baseId: result.id });
+  indexFields(fieldIds, node.slug, result.fields);
+  for (const view of node.base.views) {
+    const changeRequest = await client.bases.createViewChangeRequest({
+      baseId: result.id,
+      slug: view.slug,
+      name: view.name,
+      description: view.description,
+      config: view.config,
+      submittedBy: options.submittedBy
+    });
+    await approveAndMerge(client, changeRequest.id);
+    state.created.views++;
+  }
+};
+var createFileTreeNode = async (client, node, parentNodeId, options, state) => {
+  const uploaded = await Promise.all(
+    node.files.map(async (entry) => {
+      const mimeType = guessMimeType(entry.path);
+      if (isTextMimeType(mimeType)) {
+        return { path: entry.path, content: entry.bytes.toString("utf8"), mimeType };
+      }
+      try {
+        const asset = await uploadAsset(
+          client,
+          entry.path.split("/").at(-1) ?? entry.path,
+          mimeType,
+          entry.bytes
+        );
+        return { path: entry.path, assetId: asset.assetId, mimeType };
+      } catch (error) {
+        state.warnings.push(asSkippableUpload(error, `${node.slug}/${entry.path}`));
+        return void 0;
+      }
+    })
+  );
+  const files = uploaded.filter((entry) => entry !== void 0);
+  const api = node.type === "skill" ? client.skills : node.type === "airapp" ? client.airapps : client.drives;
+  const result = await api.create({
+    parentNodeId,
+    slug: node.slug,
+    name: node.name,
+    description: node.description,
+    files,
+    // The package hands over a complete, self-contained node; "merge" would layer the
+    // default scaffold underneath and leave stray unrelated files behind.
+    mergeMode: "replace",
+    autoMerge: options.autoMerge
+  });
+  if (result.materialized) {
+    state.created.fileTreeNodes++;
+    state.created.files += node.files.length;
+  } else {
+    state.pendingChangeRequests++;
+  }
+};
+var UploadTargetUnsupportedError = class extends Error {
+};
+var uploadAsset = async (client, fileName, mimeType, bytes) => {
+  const contentHash = `sha256:${createHash2("sha256").update(bytes).digest("hex")}`;
+  const requested = await client.assets.createUploadUrl({
+    fileName,
+    mimeType,
+    sizeBytes: bytes.byteLength,
+    context: "record-field",
+    contentHash
+  });
+  if (requested.duplicate) {
+    const assetId2 = requested.assetId ?? requested.attachmentId;
+    if (!assetId2)
+      throw new Error(`Server reported "${fileName}" as a duplicate but returned no asset id.`);
+    return { assetId: assetId2 };
+  }
+  if (!/^https?:\/\//.test(requested.uploadUrl)) {
+    throw new UploadTargetUnsupportedError(
+      `this server issued a non-absolute upload url (${requested.uploadUrl}), which only its own web UI knows how to use`
+    );
+  }
+  const uploaded = await fetch(requested.uploadUrl, {
+    method: "PUT",
+    body: new Uint8Array(bytes),
+    headers: { "content-type": mimeType }
+  });
+  if (!uploaded.ok) {
+    throw new Error(`Upload of "${fileName}" failed (${uploaded.status} ${uploaded.statusText}).`);
+  }
+  const confirmed = await client.assets.confirm({
+    storageKey: requested.storageKey,
+    fileName,
+    mimeType,
+    sizeBytes: bytes.byteLength,
+    context: "record-field",
+    contentHash
+  });
+  const assetId = confirmed.assetId ?? confirmed.attachmentId;
+  if (!assetId) throw new Error(`Upload of "${fileName}" was confirmed but returned no asset id.`);
+  return { assetId };
+};
+var asSkippableUpload = (error, label) => {
+  if (error instanceof UploadTargetUnsupportedError) {
+    return `Skipped binary file "${label}": ${error.message}. Everything else in the package was installed.`;
+  }
+  throw error;
+};
+var isDeferredField = (field) => PACKAGE_DEFERRED_FIELD_TYPES.includes(field.type);
+var needsFieldIdPatch = (field) => Boolean(field.options.inverseFieldSlug) || Boolean(field.options.ai?.sourceFieldSlugs && field.options.ai.sourceFieldSlugs.length > 0);
+var toApiFieldOptions = (options) => {
+  const { inverseFieldSlug: _inverseFieldSlug, ai, ...rest } = options;
+  const apiOptions = { ...rest };
+  if (ai) {
+    const { sourceFieldSlugs: _sourceFieldSlugs, ...aiRest } = ai;
+    apiOptions.ai = aiRest;
+  }
+  return apiOptions;
+};
+var resolveFieldIdOptions = (field, baseSlug, fieldIds, warnings) => {
+  const options = toApiFieldOptions(field.options);
+  let resolvedAny = false;
+  const inverseFieldSlug = field.options.inverseFieldSlug;
+  if (inverseFieldSlug) {
+    const targetBaseSlug = field.options.targetBaseSlug;
+    const inverseId = targetBaseSlug ? fieldIds.get(fieldKey(targetBaseSlug, inverseFieldSlug)) : void 0;
+    if (inverseId) {
+      options.inverseFieldId = inverseId;
+      resolvedAny = true;
+    } else {
+      warnings.push(
+        `Could not resolve the inverse field "${inverseFieldSlug}" of ${baseSlug}.${field.slug} in base "${targetBaseSlug ?? "?"}" \u2014 the relation is installed, but its inverse link is not set.`
+      );
+    }
+  }
+  const sourceFieldSlugs = field.options.ai?.sourceFieldSlugs;
+  if (sourceFieldSlugs && sourceFieldSlugs.length > 0) {
+    const sourceFieldIds = sourceFieldSlugs.map((slug) => fieldIds.get(fieldKey(baseSlug, slug)));
+    const missing = sourceFieldSlugs.filter((_, index) => !sourceFieldIds[index]);
+    if (missing.length > 0) {
+      warnings.push(
+        `Could not resolve AI source field(s) ${missing.map((slug) => `"${slug}"`).join(", ")} for ${baseSlug}.${field.slug} \u2014 the field is installed without them.`
+      );
+    }
+    const resolved = sourceFieldIds.filter((id) => Boolean(id));
+    if (resolved.length > 0) {
+      const ai = options.ai ?? {};
+      options.ai = { ...ai, sourceFieldIds: resolved };
+      resolvedAny = true;
+    }
+  }
+  return resolvedAny ? options : void 0;
+};
+var indexFields = (fieldIds, baseSlug, fields) => {
+  for (const field of fields) fieldIds.set(fieldKey(baseSlug, field.slug), field.id);
+};
+var toCreatableFields = (node, fields) => {
+  const typeBySlug = new Map(node.base.fields.map((field) => [field.slug, field.type]));
+  const result = {};
+  for (const [slug, value] of Object.entries(fields)) {
+    const type = typeBySlug.get(slug);
+    if (!type) continue;
+    if (type === "relation") continue;
+    if (PACKAGE_COMPUTED_FIELD_TYPES.includes(type)) continue;
+    if (type === "attachment") continue;
+    result[slug] = value;
+  }
+  return result;
+};
+var createRecords = async (client, base, plan, options, state, recordIdsByKey) => {
+  const records = [...base.node.records].sort((a, b) => a.key.localeCompare(b.key, "en"));
+  for (let offset = 0; offset < records.length; offset += RECORD_BATCH_SIZE) {
+    const batch = records.slice(offset, offset + RECORD_BATCH_SIZE);
+    const changeRequest = await client.bases.createBulkChangeRequest({
+      baseId: base.baseId,
+      records: batch.map((record) => toCreatableFields(base.node, record.fields)),
+      message: `Install ${batch.length} record(s) into ${base.node.slug}`,
+      submittedBy: options.submittedBy,
+      idempotencyKey: batchIdempotencyKey(plan.tree.manifest.name, batch[0].key)
+    });
+    if (!options.autoMerge) {
+      state.pendingChangeRequests++;
+      continue;
+    }
+    const merged = await approveAndMerge(client, changeRequest.id);
+    const created = merged.changeRequest.operations.filter((operation) => operation.operation === "record_create").sort((a, b) => a.position - b.position);
+    for (const [index, record] of batch.entries()) {
+      const recordId = created[index]?.mergedRecordId;
+      if (recordId) recordIdsByKey.set(record.key, recordId);
+    }
+    state.created.records += batch.length;
+  }
+};
+var batchIdempotencyKey = (packageName, firstRecordKey) => `pkg:${packageName}:${firstRecordKey}`;
+var linkRelations = async (client, base, relationFieldSlugs, recordIdsByKey, options, state) => {
+  for (const record of base.node.records) {
+    const relationValues = {};
+    let hasRelation = false;
+    for (const slug of relationFieldSlugs) {
+      const value = record.fields[slug];
+      const keys = toKeyArray(value);
+      if (keys.length === 0) continue;
+      const targetIds = keys.map((key) => recordIdsByKey.get(key)).filter((id) => Boolean(id));
+      const unresolved = keys.filter((key) => !recordIdsByKey.has(key));
+      if (unresolved.length > 0) {
+        state.warnings.push(
+          `Record "${record.key}" in base "${base.node.slug}" links field "${slug}" to ${unresolved.length} record(s) that are not in this package \u2014 those links were skipped.`
+        );
+      }
+      if (targetIds.length > 0) {
+        relationValues[slug] = targetIds;
+        hasRelation = true;
+      }
+    }
+    if (!hasRelation) continue;
+    const recordId = recordIdsByKey.get(record.key);
+    if (!recordId) continue;
+    const changeRequest = await client.records.updateChangeRequest({
+      recordId,
+      fields: { ...toCreatableFields(base.node, record.fields), ...relationValues },
+      message: `Link relations for ${base.node.slug}`,
+      author: options.submittedBy
+    });
+    await approveAndMerge(client, changeRequest.id);
+  }
+};
+var toKeyArray = (value) => {
+  if (Array.isArray(value))
+    return value.filter((item) => typeof item === "string" && item.length > 0);
+  if (typeof value === "string" && value.length > 0) return [value];
+  return [];
+};
+var approveAndMerge = async (client, changeRequestId) => {
+  await client.changeRequests.review({ changeRequestId, verdict: "approved" });
+  return client.changeRequests.merge({ changeRequestId });
+};
+
+// src/package/collect.ts
+var findSourceNode = (nodes, slugOrId) => {
+  const stack = [...nodes];
+  while (stack.length > 0) {
+    const node = stack.shift();
+    if (!node) continue;
+    if (node.id === slugOrId || node.slug === slugOrId) return node;
+    if (node.children) stack.push(...node.children);
+  }
+  throw new Error(
+    `No node found with slug or id "${slugOrId}" in this space. Run \`busabase-cli nodes list\` to see the tree.`
+  );
+};
+var collectPackageTree = async (client, root, options) => {
+  const children = root.children ?? [];
+  const nodes = await collectNodes(client, children, options);
+  const tree = { manifest: { ...options.manifest, format: PACKAGE_FORMAT }, nodes };
+  assertSelfContained(tree, options);
+  return tree;
+};
+var collectNodes = async (client, sources, options) => {
+  const nodes = [];
+  for (const source of sources) {
+    const node = await collectNode(client, source, options);
+    if (node) nodes.push(node);
+  }
+  return sortNodes(nodes);
+};
+var collectNode = async (client, source, options) => {
+  const common = {
+    slug: source.slug,
+    name: source.name,
+    description: source.description ?? "",
+    // `publish` always writes position, so round trips preserve sibling order exactly.
+    position: source.position
+  };
+  switch (source.type) {
+    case "folder":
+      return {
+        ...common,
+        type: "folder",
+        children: await collectNodes(client, source.children ?? [], options)
+      };
+    case "doc": {
+      const doc = await client.docs.get({ nodeId: source.id });
+      return { ...common, type: "doc", body: doc.body };
+    }
+    case "base":
+      return collectBase(client, source, common, options);
+    case "skill":
+    case "airapp":
+    case "drive":
+      return collectFileTree(client, source, common, options);
+    case "file":
+      return collectFile(client, source, common, options);
+    default:
+      options.warn(`Skipped node "${source.slug}": unsupported node type "${source.type}".`);
+      return void 0;
+  }
+};
+var collectBase = async (client, source, common, options) => {
+  const baseId = source.baseId ?? source.slug;
+  const base = await client.bases.get({ baseId });
+  if (!base) {
+    throw new Error(
+      `Base node "${source.slug}" has no Base behind it (looked up ${baseId}). The space may be mid-migration; re-run publish.`
+    );
+  }
+  const views = await client.bases.listViews({ baseId: base.id });
+  const { baseSlugById, fieldSlugById } = await buildIndexes(client);
+  const fields = [...base.fields].sort((a, b) => a.position - b.position).map(
+    (field) => toPackageField(field, {
+      fieldSlugById,
+      baseSlugById,
+      baseSlug: base.slug,
+      warn: options.warn
+    })
+  );
+  const records = await collectRecords(client, base.id, base.fields, options);
+  return {
+    ...common,
+    type: "base",
+    base: {
+      name: base.name,
+      description: base.description ?? "",
+      position: common.position,
+      reviewPolicy: base.reviewPolicy,
+      fields,
+      views: views.map(toPackageView)
+    },
+    records
+  };
+};
+var buildIndexes = async (client) => {
+  const bases = await client.bases.list();
+  const baseSlugById = /* @__PURE__ */ new Map();
+  const fieldSlugById = /* @__PURE__ */ new Map();
+  for (const base of bases) {
+    baseSlugById.set(base.id, base.slug);
+    for (const field of base.fields ?? []) fieldSlugById.set(field.id, field.slug);
+  }
+  return { baseSlugById, fieldSlugById };
+};
+var toPackageField = (field, context) => {
+  const {
+    targetBaseId,
+    inverseFieldId,
+    ai,
+    targetBaseSlug: existingTargetBaseSlug,
+    ...rest
+  } = field.options;
+  const options = { ...rest };
+  if (typeof targetBaseId === "string") {
+    const targetSlug = context.baseSlugById.get(targetBaseId);
+    if (!targetSlug) {
+      throw new Error(
+        `Field "${context.baseSlug}.${field.slug}" relates to a Base that no longer exists (${targetBaseId}). Fix the field before publishing.`
+      );
+    }
+    options.targetBaseSlug = targetSlug;
+  } else if (typeof existingTargetBaseSlug === "string") {
+    options.targetBaseSlug = existingTargetBaseSlug;
+  }
+  if (typeof inverseFieldId === "string") {
+    const inverseSlug = context.fieldSlugById.get(inverseFieldId);
+    if (inverseSlug) {
+      options.inverseFieldSlug = inverseSlug;
+    } else {
+      context.warn(
+        `Field "${context.baseSlug}.${field.slug}" names an inverse field (${inverseFieldId}) that no longer exists; the package ships the relation without its inverse link.`
+      );
+    }
+  }
+  if (ai) {
+    const { sourceFieldIds, ...aiRest } = ai;
+    const aiOptions = { ...aiRest };
+    if (Array.isArray(sourceFieldIds) && sourceFieldIds.length > 0) {
+      const slugs = sourceFieldIds.map((id) => context.fieldSlugById.get(id)).filter((slug) => Boolean(slug));
+      if (slugs.length !== sourceFieldIds.length) {
+        context.warn(
+          `Field "${context.baseSlug}.${field.slug}" references AI source field(s) that no longer exist \u2014 they were dropped from the package.`
+        );
+      }
+      if (slugs.length > 0) aiOptions.sourceFieldSlugs = slugs;
+    }
+    options.ai = aiOptions;
+  }
+  return {
+    slug: field.slug,
+    name: field.name,
+    type: field.type,
+    required: field.required,
+    position: field.position,
+    options
+  };
+};
+var toPackageView = (view) => ({
+  slug: view.slug,
+  name: view.name,
+  description: view.description ?? "",
+  type: "table",
+  config: {
+    filters: view.config.filters.map((filter) => ({
+      fieldSlug: filter.fieldSlug,
+      operator: filter.operator,
+      value: filter.value
+    })),
+    sorts: view.config.sorts.map((sort) => ({
+      direction: sort.direction,
+      fieldSlug: sort.fieldSlug
+    })),
+    visibleFieldSlugs: view.config.visibleFieldSlugs ?? void 0
+  }
+});
+var collectRecords = async (client, baseId, fields, options) => {
+  const typeBySlug = new Map(fields.map((field) => [field.slug, field.type]));
+  const records = [];
+  let droppedAttachments = 0;
+  let cursor;
+  do {
+    const page = await client.records.listPaged({ baseId, limit: 100, cursor });
+    for (const record of page.records) {
+      if (record.status !== "active") continue;
+      const values = {};
+      for (const [slug, value] of Object.entries(record.headCommit.fields ?? {})) {
+        const type = typeBySlug.get(slug);
+        if (!type) continue;
+        if (PACKAGE_COMPUTED_FIELD_TYPES.includes(type)) continue;
+        if (type === "attachment") {
+          if (value !== null && value !== void 0) droppedAttachments++;
+          continue;
+        }
+        if (value === null || value === void 0) continue;
+        values[slug] = value;
+      }
+      records.push({ key: record.id, fields: values });
+    }
+    cursor = page.nextCursor ?? void 0;
+  } while (cursor);
+  if (droppedAttachments > 0) {
+    options.warn(
+      `Dropped ${droppedAttachments} attachment value(s) from this Base \u2014 attachment values are not carried by ${PACKAGE_FORMAT} (the field definitions are kept).`
+    );
+  }
+  return records.sort((a, b) => a.key.localeCompare(b.key, "en"));
+};
+var collectFileTree = async (client, source, common, options) => {
+  const api = source.type === "skill" ? client.skills : source.type === "airapp" ? client.airapps : client.drives;
+  const listed = await api.listFiles({ nodeId: source.id });
+  const files = [];
+  for (const file of listed) {
+    const read = await api.readFile({ nodeId: source.id, filePath: file.path });
+    files.push({
+      path: file.path,
+      bytes: read.encoding === "url" ? await downloadBytes(read.content, file.path, options) : Buffer.from(read.content, "utf8")
+    });
+  }
+  return {
+    ...common,
+    type: source.type,
+    files
+  };
+};
+var collectFile = async (client, source, common, options) => {
+  const fileNode = await client.files.get({ nodeId: source.id });
+  const asset = fileNode.asset;
+  if (!asset?.url) {
+    options.warn(`Skipped file node "${source.slug}": it has no downloadable asset.`);
+    return void 0;
+  }
+  const fileName = asset.fileName ?? source.slug;
+  return {
+    ...common,
+    type: "file",
+    fileName,
+    mimeType: asset.mimeType ?? guessMimeType(fileName),
+    bytes: await downloadBytes(asset.url, fileName, options)
+  };
+};
+var downloadBytes = async (url, label, options) => {
+  const resolved = new URL(url, options.baseUrl).toString();
+  const response = await fetch(resolved);
+  if (!response.ok) {
+    throw new Error(`Failed to download "${label}" (${response.status} ${response.statusText}).`);
+  }
+  return Buffer.from(await response.arrayBuffer());
+};
+var assertSelfContained = (tree, options) => {
+  const baseNodes = [...walk(tree.nodes)].filter((node) => node.type === "base");
+  const packagedBaseSlugs = new Set(baseNodes.map((node) => node.slug));
+  const packagedRecordKeys = new Set(
+    baseNodes.flatMap(
+      (node) => node.type === "base" ? node.records.map((record) => record.key) : []
+    )
+  );
+  for (const node of baseNodes) {
+    if (node.type !== "base") continue;
+    for (const field of node.base.fields) {
+      const targetBaseSlug = field.options.targetBaseSlug;
+      if (field.type !== "relation" || !targetBaseSlug) continue;
+      if (!packagedBaseSlugs.has(targetBaseSlug)) {
+        throw new Error(
+          `Field "${node.slug}.${field.slug}" relates to Base "${targetBaseSlug}", which is outside the subtree being published. A package must be self-contained \u2014 publish a subtree that includes both Bases, or remove the field.`
+        );
+      }
+    }
+    let dangling = 0;
+    for (const record of node.records) {
+      for (const field of node.base.fields) {
+        if (field.type !== "relation") continue;
+        const value = record.fields[field.slug];
+        const keys = Array.isArray(value) ? value : typeof value === "string" ? [value] : [];
+        for (const key of keys) {
+          if (typeof key === "string" && !packagedRecordKeys.has(key)) dangling++;
+        }
+      }
+    }
+    if (dangling > 0) {
+      options.warn(
+        `Base "${node.slug}" has ${dangling} relation value(s) pointing at records outside the published subtree \u2014 they were dropped.`
+      );
+    }
+  }
+};
+var walk = function* (nodes) {
+  for (const node of nodes) {
+    yield node;
+    if (node.type === "folder") yield* walk(node.children);
+  }
+};
+
+// src/package/github.ts
+import { Uint8ArrayReader, ZipReader } from "@zip.js/zip.js";
+var GITHUB_ALLOWED_HOSTS = [
+  "github.com",
+  "api.github.com",
+  "codeload.github.com"
+];
+var GITHUB_URL_HOSTS = ["github.com", "www.github.com"];
+var isAllowedGithubHost = (hostname) => GITHUB_ALLOWED_HOSTS.includes(hostname.toLowerCase());
+var parseGithubUrl = (rawUrl) => {
+  let url;
+  try {
+    url = new URL(rawUrl.trim());
+  } catch {
+    throw new Error(
+      `Not a valid URL: "${rawUrl}". Expected a GitHub repo URL, e.g. https://github.com/acme/support-kb-template`
+    );
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new Error(`Unsupported URL scheme "${url.protocol}" \u2014 expected an https:// GitHub URL.`);
+  }
+  if (!GITHUB_URL_HOSTS.includes(url.hostname.toLowerCase())) {
+    throw new Error(
+      `Not a GitHub URL: host "${url.hostname}" is not github.com. Only GitHub packages can be installed.`
+    );
+  }
+  const segments = url.pathname.split("/").filter(Boolean);
+  const [owner, rawRepo, marker, ref, ...rest] = segments;
+  if (!owner || !rawRepo) {
+    throw new Error(
+      `GitHub URL is missing owner/repo: "${rawUrl}". Expected https://github.com/<owner>/<repo>[/tree/<ref>[/<subdir>]]`
+    );
+  }
+  const repo = rawRepo.replace(/\.git$/, "");
+  if (!marker) {
+    return { owner, repo, ref: void 0, subdir: void 0 };
+  }
+  if (marker !== "tree") {
+    throw new Error(
+      `Unsupported GitHub URL form "/${marker}/" in "${rawUrl}". Expected https://github.com/<owner>/<repo>[/tree/<ref>[/<subdir>]]`
+    );
+  }
+  if (!ref) {
+    throw new Error(`GitHub URL has "/tree/" but no ref: "${rawUrl}".`);
+  }
+  return {
+    owner,
+    repo,
+    ref: decodeURIComponent(ref),
+    subdir: rest.length > 0 ? rest.map((segment) => decodeURIComponent(segment)).join("/") : void 0
+  };
+};
+var encodeRefPath = (ref) => ref.split("/").map(encodeURIComponent).join("/");
+var downloadGithubZip = async (source, options = {}) => {
+  const fetcher = options.fetcher ?? fetch;
+  const { owner, repo, ref } = source;
+  const slug = `${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`;
+  const label = `${owner}/${repo}${ref ? `@${ref}` : ""}`;
+  const publicUrl = `https://codeload.github.com/${slug}/zip/${ref ? encodeRefPath(ref) : "HEAD"}`;
+  assertAllowedUrl(publicUrl);
+  const publicResponse = await fetcher(publicUrl);
+  if (publicResponse.ok) return Buffer.from(await publicResponse.arrayBuffer());
+  if (!options.githubToken) {
+    throw new Error(
+      publicResponse.status === 404 ? `GitHub repo or ref not found: ${label} (HTTP 404).
+  \u2022 Check the URL, and that the branch/tag exists.
+  \u2022 Private repo? Set GITHUB_TOKEN=<a token with repo read access> and re-run.` : `Failed to download ${label} from GitHub (HTTP ${publicResponse.status} ${publicResponse.statusText}).`
+    );
+  }
+  const apiUrl = `https://api.github.com/repos/${slug}/zipball${ref ? `/${encodeRefPath(ref)}` : ""}`;
+  assertAllowedUrl(apiUrl);
+  const authedResponse = await fetcher(apiUrl, {
+    headers: {
+      Accept: "application/vnd.github+json",
+      Authorization: `Bearer ${options.githubToken}`,
+      "X-GitHub-Api-Version": "2022-11-28"
+    }
+  });
+  if (authedResponse.ok) return Buffer.from(await authedResponse.arrayBuffer());
+  if (authedResponse.status === 401 || authedResponse.status === 403) {
+    throw new Error(
+      `GitHub rejected GITHUB_TOKEN for ${label} (HTTP ${authedResponse.status}). The token is invalid, expired, or lacks read access to this repo.`
+    );
+  }
+  throw new Error(
+    `GitHub repo or ref not found: ${label} (HTTP ${authedResponse.status}), even with GITHUB_TOKEN. Check the owner, repo, and ref.`
+  );
+};
+var assertAllowedUrl = (rawUrl) => {
+  const url = new URL(rawUrl);
+  if (url.protocol !== "https:" || !isAllowedGithubHost(url.hostname)) {
+    throw new Error(
+      `Refusing to fetch ${rawUrl} \u2014 only https on ${GITHUB_ALLOWED_HOSTS.join(", ")} is allowed.`
+    );
+  }
+};
+var normalizeArchivePath = (value) => {
+  const normalized = value.replaceAll("\\", "/").replace(/^\/+|\/+$/g, "");
+  const segments = normalized.split("/");
+  if (!normalized || segments.some((segment) => segment === "." || segment === ".." || /^[a-zA-Z]:$/.test(segment))) {
+    throw new Error(`Unsafe archive path rejected: ${value}`);
+  }
+  return normalized;
+};
+var extractZip = async (zipBuffer, options = {}) => {
+  const maxFiles = options.maxFiles ?? PACKAGE_MAX_FILE_COUNT;
+  const maxTotalBytes = options.maxTotalBytes ?? PACKAGE_MAX_TOTAL_BYTES;
+  const maxFileBytes = options.maxFileBytes ?? PACKAGE_MAX_FILE_BYTES;
+  const reader = new ZipReader(new Uint8ArrayReader(new Uint8Array(zipBuffer)));
+  try {
+    const entries = await reader.getEntries();
+    const files = entries.filter((entry) => !entry.directory);
+    const archiveRoot = files[0]?.filename.split("/")[0];
+    if (!archiveRoot) throw new Error("The downloaded repository archive is empty.");
+    const subdir = options.subdir ? normalizeArchivePath(options.subdir) : void 0;
+    const prefix = `${archiveRoot}/${subdir ? `${subdir}/` : ""}`;
+    for (const entry of files) normalizeArchivePath(entry.filename);
+    const selected = files.filter((entry) => entry.filename.startsWith(prefix));
+    if (selected.length > maxFiles) {
+      throw new Error(
+        `Package has ${selected.length} files, above the ${maxFiles}-file limit. Nothing was installed.`
+      );
+    }
+    let totalBytes = 0;
+    for (const entry of selected) {
+      const size = entry.uncompressedSize ?? 0;
+      const relativePath = entry.filename.slice(prefix.length);
+      if (size > maxFileBytes) {
+        throw new Error(
+          `File "${relativePath}" is ${formatBytes(size)}, above the ${formatBytes(maxFileBytes)} per-file limit. Nothing was installed.`
+        );
+      }
+      totalBytes += size;
+      if (totalBytes > maxTotalBytes) {
+        throw new Error(
+          `Package unpacks to more than the ${formatBytes(maxTotalBytes)} total limit. Nothing was installed.`
+        );
+      }
+    }
+    const result = /* @__PURE__ */ new Map();
+    for (const entry of selected) {
+      const relativePath = normalizeArchivePath(entry.filename.slice(prefix.length));
+      if (!entry.getData) continue;
+      const data = await entry.arrayBuffer();
+      result.set(relativePath, Buffer.from(data));
+    }
+    return result;
+  } finally {
+    await reader.close();
+  }
+};
+var formatBytes = (bytes) => bytes >= 1024 * 1024 ? `${Math.round(bytes / (1024 * 1024))}MB` : `${Math.round(bytes / 1024)}KB`;
+var fetchGithubPackageFiles = async (repoUrl, options = {}) => {
+  const source = parseGithubUrl(repoUrl);
+  const zipBuffer = await downloadGithubZip(source, options);
+  const files = await extractZip(zipBuffer, { subdir: source.subdir });
+  return { source, files };
+};
+
+// src/package/frontmatter.ts
+import { parse, stringify } from "yaml";
+var DELIMITER = "---";
+var normalizeDocBody = (body) => body.replaceAll("\r\n", "\n").replace(/^\n+/, "").replace(/\n+$/, "");
+var parseFrontmatter = (text, filePath) => {
+  const normalized = text.replaceAll("\r\n", "\n");
+  if (!normalized.startsWith(`${DELIMITER}
+`)) {
+    return { data: {}, body: normalizeDocBody(normalized) };
+  }
+  const end = normalized.indexOf(`
+${DELIMITER}`, DELIMITER.length);
+  if (end === -1) {
+    throw new Error(
+      `${filePath} opens YAML frontmatter with "---" but never closes it. Add a closing "---" line.`
+    );
+  }
+  const rawYaml = normalized.slice(DELIMITER.length + 1, end);
+  const body = normalizeDocBody(normalized.slice(end + 1 + DELIMITER.length));
+  let data;
+  try {
+    data = parse(rawYaml);
+  } catch (error) {
+    throw new Error(`${filePath} has invalid YAML frontmatter: ${error.message}`);
+  }
+  if (data === null || data === void 0) return { data: {}, body };
+  if (typeof data !== "object" || Array.isArray(data)) {
+    throw new Error(`${filePath} frontmatter must be a YAML mapping (key: value pairs).`);
+  }
+  return { data, body };
+};
+var serializeDoc = (fields, body) => {
+  const data = { name: fields.name };
+  if (fields.description) data.description = fields.description;
+  if (fields.position !== void 0) data.position = fields.position;
+  const yaml = stringify(data, { lineWidth: 0 }).replace(/\n$/, "");
+  return `${DELIMITER}
+${yaml}
+${DELIMITER}
+
+${normalizeDocBody(body)}
+`;
+};
+
+// src/package/layout-read.ts
+var decodeText = (bytes, filePath) => {
+  const text = bytes.toString("utf8");
+  if (text.includes("\uFFFD")) {
+    throw new Error(`${filePath} is not valid UTF-8 text.`);
+  }
+  return text;
+};
+var parseJsonFile = (files, filePath) => {
+  const bytes = files.get(filePath);
+  if (!bytes) throw new Error(`Missing ${filePath}`);
+  try {
+    return JSON.parse(decodeText(bytes, filePath));
+  } catch (error) {
+    throw new Error(`${filePath} is not valid JSON: ${error.message}`);
+  }
+};
+var zodParse = (schema, value, filePath) => {
+  const result = schema.safeParse(value);
+  if (!result.success) {
+    const issues = result.error.issues.map((issue) => `  - ${issue.path.join(".") || "(root)"}: ${issue.message}`).join("\n");
+    throw new Error(`${filePath} does not match the ${PACKAGE_FORMAT} schema:
+${issues}`);
+  }
+  return result.data;
+};
+var listDir = (files, dir) => {
+  const fileNames = /* @__PURE__ */ new Set();
+  const dirNames = /* @__PURE__ */ new Set();
+  for (const filePath of files.keys()) {
+    if (!filePath.startsWith(dir)) continue;
+    const rest = filePath.slice(dir.length);
+    if (!rest) continue;
+    const slash = rest.indexOf("/");
+    if (slash === -1) fileNames.add(rest);
+    else dirNames.add(rest.slice(0, slash));
+  }
+  return { files: [...fileNames].sort(), dirs: [...dirNames].sort() };
+};
+var collectSubtree = (files, dir) => {
+  const entries = [];
+  for (const [filePath, bytes] of files) {
+    if (!filePath.startsWith(dir)) continue;
+    const relativePath = filePath.slice(dir.length);
+    if (relativePath) entries.push({ path: relativePath, bytes });
+  }
+  return entries.sort((a, b) => a.path.localeCompare(b.path, "en"));
+};
+var readPackageTree = (files, options = {}) => {
+  const root = options.root ? `${options.root.replace(/\/+$/, "")}/` : "";
+  const manifestPath = `${root}${PACKAGE_MANIFEST_FILENAME}`;
+  if (!files.has(manifestPath)) {
+    throw new Error(buildMissingManifestError(files, root));
+  }
+  const rawManifest = parseJsonFile(files, manifestPath);
+  assertKnownFormat(rawManifest, manifestPath);
+  const manifest = zodParse(PackageManifestSchema, rawManifest, manifestPath);
+  const contentDir = `${root}${PACKAGE_CONTENT_DIRNAME}/`;
+  const nodes = readNodes(files, contentDir);
+  return { manifest, nodes };
+};
+var assertKnownFormat = (rawManifest, manifestPath) => {
+  const format = typeof rawManifest === "object" && rawManifest !== null ? rawManifest.format : void 0;
+  if (typeof format === "string" && format !== PACKAGE_FORMAT) {
+    throw new Error(
+      `${manifestPath} declares format "${format}", but this busabase-cli only understands "${PACKAGE_FORMAT}". Upgrade busabase-cli (npm i -g busabase-cli@latest) and try again.`
+    );
+  }
+};
+var buildMissingManifestError = (files, root) => {
+  const at = root || "the repository root";
+  const nested = [...files.keys()].filter((filePath) => filePath.endsWith(`/${PACKAGE_MANIFEST_FILENAME}`)).map((filePath) => filePath.slice(0, -PACKAGE_MANIFEST_FILENAME.length - 1)).filter((dir) => dir && dir !== root.replace(/\/+$/, "")).sort();
+  const base = `Not a Busabase package \u2014 expected ${PACKAGE_MANIFEST_FILENAME} at ${at}.`;
+  if (nested.length === 0) return base;
+  const suggestions = nested.slice(0, 10).map((dir) => `  \u2022 .../tree/<ref>/${dir}`).join("\n");
+  return `${base}
+
+This repo does contain packages in subdirectories \u2014 install one of them by URL:
+${suggestions}`;
+};
+var readNodes = (files, dir) => {
+  const { files: fileNames, dirs } = listDir(files, dir);
+  assertNoSiblingCaseCollisions([...fileNames, ...dirs], `in ${dir || "content/"}`);
+  const nodes = [];
+  for (const dirName of dirs) nodes.push(readDirNode(files, `${dir}${dirName}/`, dirName));
+  for (const fileName of fileNames) {
+    const node = readFileNode(files, dir, fileName);
+    if (node) nodes.push(node);
+  }
+  return sortNodes(nodes);
+};
+var readDirNode = (files, dir, slug) => {
+  assertSafeNodeSlug(slug, `directory ${dir}`);
+  if (files.has(`${dir}${PACKAGE_NODE_META_FILENAME}`)) {
+    const metaPath2 = `${dir}${PACKAGE_NODE_META_FILENAME}`;
+    const meta2 = zodParse(PackageFileTreeNodeMetaSchema, parseJsonFile(files, metaPath2), metaPath2);
+    const entries = collectSubtree(files, dir).filter(
+      (entry) => entry.path !== PACKAGE_NODE_META_FILENAME
+    );
+    assertNoReservedNames(
+      entries.map((entry) => entry.path),
+      `${meta2.type} "${slug}"`
+    );
+    return {
+      type: meta2.type,
+      slug,
+      name: meta2.name,
+      description: meta2.description,
+      position: meta2.position,
+      files: entries
+    };
+  }
+  if (files.has(`${dir}${PACKAGE_BASE_FILENAME}`)) {
+    const basePath = `${dir}${PACKAGE_BASE_FILENAME}`;
+    const base = zodParse(PackageBaseSchema, parseJsonFile(files, basePath), basePath);
+    const records = readRecords(files, dir, slug);
+    return {
+      type: "base",
+      slug,
+      name: base.name,
+      description: base.description,
+      position: base.position,
+      base,
+      records
+    };
+  }
+  const metaPath = `${dir}${PACKAGE_FOLDER_META_FILENAME}`;
+  const meta = files.has(metaPath) ? zodParse(PackageFolderMetaSchema, parseJsonFile(files, metaPath), metaPath) : { name: void 0, description: "", position: void 0 };
+  return {
+    type: "folder",
+    slug,
+    name: meta.name ?? humanizeSlug(slug),
+    description: meta.description,
+    position: meta.position,
+    children: readNodes(files, dir)
+  };
+};
+var readRecords = (files, dir, slug) => {
+  const recordsPath = `${dir}${PACKAGE_RECORDS_FILENAME}`;
+  const bytes = files.get(recordsPath);
+  if (!bytes) return [];
+  return parseRecordLines(decodeText(bytes, recordsPath), recordsPath, slug);
+};
+var parseRecordLines = (text, recordsPath, slug) => {
+  const lines = text.split("\n").filter((line) => line.trim().length > 0);
+  if (lines.length > PACKAGE_MAX_RECORDS_PER_BASE) {
+    throw new Error(
+      `Base "${slug}" has ${lines.length} records, above the ${PACKAGE_MAX_RECORDS_PER_BASE} per-base limit. Nothing was installed.`
+    );
+  }
+  const seenKeys = /* @__PURE__ */ new Set();
+  return lines.map((line, index) => {
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch (error) {
+      throw new Error(
+        `${recordsPath} line ${index + 1} is not valid JSON: ${error.message}`
+      );
+    }
+    const record = zodParse(PackageRecordLineSchema, parsed, `${recordsPath} line ${index + 1}`);
+    if (seenKeys.has(record.key)) {
+      throw new Error(
+        `${recordsPath} has a duplicate record key "${record.key}" on line ${index + 1}.`
+      );
+    }
+    seenKeys.add(record.key);
+    return record;
+  });
+};
+var readFileNode = (files, dir, fileName) => {
+  if (fileName === PACKAGE_MANIFEST_FILENAME || fileName === PACKAGE_FOLDER_META_FILENAME || fileName === PACKAGE_NODE_META_FILENAME || fileName.endsWith(PACKAGE_NODE_META_SUFFIX)) {
+    return void 0;
+  }
+  const bytes = files.get(`${dir}${fileName}`);
+  if (!bytes) return void 0;
+  if (fileName.toLowerCase().endsWith(".md")) {
+    return readDocNode(bytes, dir, fileName);
+  }
+  const slug = stripExtension(fileName);
+  assertSafeNodeSlug(slug, `file ${dir}${fileName}`);
+  const sidecarPath = `${dir}${fileName}${PACKAGE_NODE_META_SUFFIX}`;
+  const meta = files.has(sidecarPath) ? zodParse(PackageFileNodeMetaSchema, parseJsonFile(files, sidecarPath), sidecarPath) : { name: void 0, description: "", position: void 0 };
+  return {
+    type: "file",
+    slug,
+    name: meta.name ?? fileName,
+    description: meta.description,
+    position: meta.position,
+    fileName,
+    mimeType: guessMimeType(fileName),
+    bytes
+  };
+};
+var readDocNode = (bytes, dir, fileName) => {
+  const filePath = `${dir}${fileName}`;
+  const slug = fileName.slice(0, -".md".length);
+  assertSafeNodeSlug(slug, `doc ${filePath}`);
+  const { data, body } = parseFrontmatter(decodeText(bytes, filePath), filePath);
+  const frontmatter = zodParse(
+    PackageDocFrontmatterSchema,
+    { name: humanizeSlug(slug), ...data },
+    `${filePath} frontmatter`
+  );
+  return {
+    type: "doc",
+    slug,
+    name: frontmatter.name,
+    description: frontmatter.description,
+    position: frontmatter.position,
+    body
+  };
+};
+var stripExtension = (fileName) => {
+  const dot = fileName.lastIndexOf(".");
+  return dot > 0 ? fileName.slice(0, dot) : fileName;
+};
+
+// src/package/layout-write.ts
+import { mkdir, rm, writeFile } from "fs/promises";
+import { dirname, join as join2 } from "path";
+var sortKeysDeep = (value) => {
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  if (value === null || typeof value !== "object") return value;
+  const entries = Object.entries(value).filter(([, item]) => item !== void 0).sort(([a], [b]) => a.localeCompare(b, "en"));
+  return Object.fromEntries(entries.map(([key, item]) => [key, sortKeysDeep(item)]));
+};
+var toJsonFile = (value) => Buffer.from(`${JSON.stringify(value, null, 2)}
+`, "utf8");
+var compact = (value) => Object.fromEntries(Object.entries(value).filter(([, item]) => item !== void 0));
+var serializeManifest = (manifest) => toJsonFile(
+  compact({
+    format: manifest.format,
+    name: manifest.name,
+    description: manifest.description || void 0,
+    version: manifest.version,
+    author: manifest.author,
+    license: manifest.license,
+    homepage: manifest.homepage,
+    tags: manifest.tags.length > 0 ? manifest.tags : void 0
+  })
+);
+var serializeField = (field) => compact({
+  slug: field.slug,
+  name: field.name,
+  type: field.type,
+  required: field.required,
+  position: field.position,
+  options: sortKeysDeep(field.options)
+});
+var serializeView = (view) => compact({
+  slug: view.slug,
+  name: view.name,
+  description: view.description || void 0,
+  type: view.type,
+  config: compact({
+    filters: view.config.filters.map(
+      (filter) => compact({
+        fieldSlug: filter.fieldSlug,
+        operator: filter.operator,
+        value: filter.value
+      })
+    ),
+    sorts: view.config.sorts.map((sort) => ({
+      direction: sort.direction,
+      fieldSlug: sort.fieldSlug
+    })),
+    visibleFieldSlugs: view.config.visibleFieldSlugs ?? void 0
+  })
+});
+var serializeBase = (base, position) => toJsonFile(
+  compact({
+    name: base.name,
+    description: base.description || void 0,
+    position,
+    reviewPolicy: base.reviewPolicy,
+    fields: base.fields.map(serializeField),
+    views: base.views.map(serializeView)
+  })
+);
+var serializeRecords = (records) => {
+  const sorted = [...records].sort((a, b) => a.key.localeCompare(b.key, "en"));
+  const lines = sorted.map((record) => JSON.stringify({ key: record.key, fields: record.fields }));
+  return Buffer.from(lines.length > 0 ? `${lines.join("\n")}
+` : "", "utf8");
+};
+var renderPackageTree = (tree) => {
+  const files = /* @__PURE__ */ new Map();
+  files.set(PACKAGE_MANIFEST_FILENAME, serializeManifest(tree.manifest));
+  renderNodes(tree.nodes, `${PACKAGE_CONTENT_DIRNAME}/`, files);
+  return files;
+};
+var renderNodes = (nodes, dir, files) => {
+  const ordered = sortNodes(nodes);
+  assertNoSiblingCaseCollisions(
+    ordered.map((node) => node.slug),
+    `in ${dir}`
+  );
+  const seen = /* @__PURE__ */ new Set();
+  for (const node of ordered) {
+    assertSafeNodeSlug(node.slug, `${node.type} node`);
+    if (seen.has(node.slug)) {
+      throw new Error(
+        `Two nodes in ${dir} would be written as "${node.slug}". Sibling slugs must be unique.`
+      );
+    }
+    seen.add(node.slug);
+    renderNode(node, dir, files);
+  }
+};
+var renderNode = (node, dir, files) => {
+  switch (node.type) {
+    case "folder": {
+      const needsMeta = node.children.length === 0 || node.description !== "" || node.position !== void 0 || node.name !== void 0;
+      if (needsMeta) {
+        files.set(
+          `${dir}${node.slug}/${PACKAGE_FOLDER_META_FILENAME}`,
+          toJsonFile(
+            compact({
+              name: node.name,
+              description: node.description || void 0,
+              position: node.position
+            })
+          )
+        );
+      }
+      renderNodes(node.children, `${dir}${node.slug}/`, files);
+      return;
+    }
+    case "doc": {
+      files.set(
+        `${dir}${node.slug}.md`,
+        Buffer.from(
+          serializeDoc(
+            { name: node.name, description: node.description, position: node.position },
+            node.body
+          ),
+          "utf8"
+        )
+      );
+      return;
+    }
+    case "base": {
+      files.set(
+        `${dir}${node.slug}/${PACKAGE_BASE_FILENAME}`,
+        serializeBase(node.base, node.position)
+      );
+      const records = serializeRecords(node.records);
+      if (records.byteLength > 0)
+        files.set(`${dir}${node.slug}/${PACKAGE_RECORDS_FILENAME}`, records);
+      return;
+    }
+    case "skill":
+    case "airapp":
+    case "drive": {
+      const nodeDir = `${dir}${node.slug}/`;
+      assertNoReservedNames(
+        node.files.map((entry) => entry.path),
+        `${node.type} "${node.slug}"`
+      );
+      files.set(
+        `${nodeDir}${PACKAGE_NODE_META_FILENAME}`,
+        toJsonFile(
+          compact({
+            type: node.type,
+            name: node.name,
+            description: node.description || void 0,
+            position: node.position
+          })
+        )
+      );
+      for (const entry of [...node.files].sort((a, b) => a.path.localeCompare(b.path, "en"))) {
+        assertSafeFilePath(entry.path, `${node.type} "${node.slug}"`);
+        files.set(`${nodeDir}${entry.path}`, entry.bytes);
+      }
+      return;
+    }
+    case "file": {
+      assertSafeFilePath(node.fileName, `file node "${node.slug}"`);
+      files.set(`${dir}${node.fileName}`, node.bytes);
+      const hasMeta = node.name !== node.fileName || node.description !== "" || node.position !== void 0;
+      if (hasMeta) {
+        files.set(
+          `${dir}${node.fileName}${PACKAGE_NODE_META_SUFFIX}`,
+          toJsonFile(
+            compact({
+              name: node.name,
+              description: node.description || void 0,
+              position: node.position
+            })
+          )
+        );
+      }
+      return;
+    }
+  }
+};
+var writePackageFiles = async (files, outDir, options = {}) => {
+  if (options.clean) {
+    await rm(join2(outDir, PACKAGE_CONTENT_DIRNAME), { recursive: true, force: true });
+    await rm(join2(outDir, PACKAGE_MANIFEST_FILENAME), { force: true });
+  }
+  for (const [filePath, bytes] of [...files].sort(([a], [b]) => a.localeCompare(b, "en"))) {
+    const target = join2(outDir, filePath);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, bytes);
+  }
+};
+
+// src/package/plan.ts
+var buildInstallPlan = (tree, target, options = {}) => {
+  const targetFolderSlug = options.intoFolder ?? tree.manifest.name;
+  const warnings = [];
+  const existingChildSlugs = new Set(
+    (target.targetFolder?.children ?? []).map((child) => child.slug)
+  );
+  const collisions = findCollisions(tree, targetFolderSlug, existingChildSlugs, target);
+  let planned = tree;
+  if (options.rename && collisions.length > 0) {
+    planned = applyRenames(tree, collisions, existingChildSlugs, target.existingBaseSlugs);
+  }
+  collectWarnings(planned, warnings);
+  const counts = countTree(planned);
+  if (counts.files > PACKAGE_MAX_FILE_COUNT) {
+    throw new Error(
+      `Package has ${counts.files} files, above the ${PACKAGE_MAX_FILE_COUNT}-file limit. Nothing was installed.`
+    );
+  }
+  return {
+    targetFolderSlug,
+    tree: planned,
+    collisions,
+    warnings,
+    counts,
+    requiresAutoMerge: collectBaseNodes(planned.nodes).some(hasUnlinkableRelationValues)
+  };
+};
+var hasUnlinkableRelationValues = (node) => {
+  const relationSlugs = node.base.fields.filter((field) => field.type === "relation").map((field) => field.slug);
+  if (relationSlugs.length === 0) return false;
+  return node.records.some(
+    (record) => relationSlugs.some((slug) => {
+      const value = record.fields[slug];
+      return Array.isArray(value) ? value.length > 0 : Boolean(value);
+    })
+  );
+};
+var findCollisions = (tree, targetFolderSlug, existingChildSlugs, target) => {
+  const collisions = [];
+  for (const node of tree.nodes) {
+    if (existingChildSlugs.has(node.slug)) {
+      collisions.push({ kind: "node", slug: node.slug, path: `${targetFolderSlug}/${node.slug}` });
+    }
+  }
+  for (const baseNode of collectBaseNodes(tree.nodes)) {
+    if (target.existingBaseSlugs.has(baseNode.slug)) {
+      collisions.push({
+        kind: "base",
+        slug: baseNode.slug,
+        path: `${targetFolderSlug}/\u2026 /${baseNode.slug} (base slugs are unique per space)`
+      });
+    }
+  }
+  return collisions;
+};
+var nextFreeSlug = (slug, taken) => {
+  for (let suffix = 2; suffix < 1e3; suffix++) {
+    const candidate = `${slug}-${suffix}`;
+    if (!taken.has(candidate)) return candidate;
+  }
+  throw new Error(`Could not find a free slug for "${slug}" after 999 attempts.`);
+};
+var applyRenames = (tree, collisions, existingChildSlugs, existingBaseSlugs) => {
+  const packageBaseSlugs = new Set(collectBaseNodes(tree.nodes).map((node) => node.slug));
+  const takenNodeSlugs = /* @__PURE__ */ new Set([...existingChildSlugs, ...tree.nodes.map((node) => node.slug)]);
+  const takenBaseSlugs = /* @__PURE__ */ new Set([...existingBaseSlugs, ...packageBaseSlugs]);
+  const nodeRenames = /* @__PURE__ */ new Map();
+  const baseRenames = /* @__PURE__ */ new Map();
+  for (const collision of collisions) {
+    if (collision.kind === "node") {
+      const renamed = nextFreeSlug(collision.slug, takenNodeSlugs);
+      takenNodeSlugs.add(renamed);
+      nodeRenames.set(collision.slug, renamed);
+      collision.renamedTo = renamed;
+    } else {
+      const renamed = nextFreeSlug(collision.slug, takenBaseSlugs);
+      takenBaseSlugs.add(renamed);
+      baseRenames.set(collision.slug, renamed);
+      collision.renamedTo = renamed;
+    }
+  }
+  const rewriteNode = (node, isTopLevel) => {
+    if (node.type === "base") {
+      const renamed = baseRenames.get(node.slug) ?? (isTopLevel ? nodeRenames.get(node.slug) : void 0);
+      const slug2 = renamed ?? node.slug;
+      return {
+        ...node,
+        slug: slug2,
+        base: { ...node.base, fields: node.base.fields.map(rewriteFieldTarget) }
+      };
+    }
+    const slug = (isTopLevel ? nodeRenames.get(node.slug) : void 0) ?? node.slug;
+    if (node.type === "folder") {
+      return { ...node, slug, children: node.children.map((child) => rewriteNode(child, false)) };
+    }
+    return { ...node, slug };
+  };
+  const rewriteFieldTarget = (field) => {
+    const targetBaseSlug = field.options.targetBaseSlug;
+    if (!targetBaseSlug) return field;
+    const renamed = baseRenames.get(targetBaseSlug);
+    if (!renamed) return field;
+    return { ...field, options: { ...field.options, targetBaseSlug: renamed } };
+  };
+  return { ...tree, nodes: tree.nodes.map((node) => rewriteNode(node, true)) };
+};
+var collectWarnings = (tree, warnings) => {
+  for (const baseNode of collectBaseNodes(tree.nodes)) {
+    if (baseNode.base.reviewPolicy) {
+      warnings.push(
+        `Base "${baseNode.slug}" declares a reviewPolicy (${baseNode.base.reviewPolicy.kind}, ${baseNode.base.reviewPolicy.requiredApprovals} approval(s)), but reviewPolicy cannot be set when creating a Base \u2014 the target's default applies. Adjust it in the UI afterwards if needed.`
+      );
+    }
+  }
+};
+var countTree = (tree) => {
+  const counts = {
+    folders: 0,
+    docs: 0,
+    bases: 0,
+    records: 0,
+    skills: 0,
+    airapps: 0,
+    drives: 0,
+    files: 0
+  };
+  for (const node of walkNodes(tree.nodes)) {
+    switch (node.type) {
+      case "folder":
+        counts.folders++;
+        break;
+      case "doc":
+        counts.docs++;
+        break;
+      case "base":
+        counts.bases++;
+        counts.records += node.records.length;
+        break;
+      case "skill":
+        counts.skills++;
+        counts.files += node.files.length;
+        break;
+      case "airapp":
+        counts.airapps++;
+        counts.files += node.files.length;
+        break;
+      case "drive":
+        counts.drives++;
+        counts.files += node.files.length;
+        break;
+      case "file":
+        counts.files++;
+        break;
+    }
+  }
+  return counts;
+};
+var renderPlan = (plan) => {
+  const lines = [];
+  lines.push(`Package: ${plan.tree.manifest.name}`);
+  if (plan.tree.manifest.description) lines.push(`  ${plan.tree.manifest.description}`);
+  lines.push("");
+  lines.push(`Target folder: ${plan.targetFolderSlug}`);
+  lines.push("");
+  lines.push("Node tree:");
+  for (const line of renderNodeTree2(plan.tree.nodes, "  ")) lines.push(line);
+  lines.push("");
+  lines.push(
+    `Totals: ${plan.counts.folders} folder(s), ${plan.counts.docs} doc(s), ${plan.counts.bases} base(s) with ${plan.counts.records} record(s), ${plan.counts.skills} skill(s), ${plan.counts.airapps} airapp(s), ${plan.counts.drives} drive(s), ${plan.counts.files} file(s)`
+  );
+  if (plan.collisions.length > 0) {
+    lines.push("");
+    lines.push("Collisions:");
+    for (const collision of plan.collisions) {
+      lines.push(
+        collision.renamedTo ? `  \u2022 ${collision.kind} "${collision.slug}" already exists \u2192 will be created as "${collision.renamedTo}"` : `  \u2022 ${collision.kind} "${collision.slug}" already exists (${collision.path})`
+      );
+    }
+  }
+  if (plan.warnings.length > 0) {
+    lines.push("");
+    lines.push("Warnings:");
+    for (const warning of plan.warnings) lines.push(`  \u2022 ${warning}`);
+  }
+  return lines.join("\n");
+};
+var renderNodeTree2 = (nodes, indent) => {
+  const lines = [];
+  for (const node of nodes) {
+    const detail = node.type === "base" ? ` (base, ${node.base.fields.length} field(s), ${node.records.length} record(s))` : node.type === "folder" ? " (folder)" : node.type === "doc" ? " (doc)" : node.type === "file" ? " (file)" : ` (${node.type}, ${node.files.length} file(s))`;
+    lines.push(`${indent}${node.slug}${detail}`);
+    if (node.type === "folder") lines.push(...renderNodeTree2(node.children, `${indent}  `));
+  }
+  return lines;
+};
+var assertPlanIsApplicable = (plan, autoMerge) => {
+  if (plan.collisions.some((collision) => !collision.renamedTo)) {
+    const list = plan.collisions.filter((collision) => !collision.renamedTo).map((collision) => `  \u2022 ${collision.kind} "${collision.slug}" (${collision.path})`).join("\n");
+    throw new Error(
+      `Install would collide with content that already exists:
+${list}
+
+Nothing was created. Re-run with --rename to install the colliding items under suffixed slugs (e.g. "-2"), or pick a different --into-folder.`
+    );
+  }
+  if (plan.requiresAutoMerge && !autoMerge) {
+    throw new Error(
+      "This package's records carry relation values, and a relation stores the ids of the records it points at \u2014 which only exist once the records are merged. Installing review-first would leave every relation empty.\n\nRe-run with --auto-merge to install it (this trusts the package author: records are created immediately instead of landing as change requests you review first)."
+    );
+  }
+};
+
+// src/package/commands.ts
+var reportProgress = (message) => {
+  console.error(message);
+};
+var runInstall = async (client, repoUrl, options) => {
+  reportProgress(`Fetching ${repoUrl} \u2026`);
+  const { source, files } = await fetchGithubPackageFiles(repoUrl, {
+    githubToken: options.githubToken
+  });
+  reportProgress(`Downloaded ${files.size} file(s) from ${source.owner}/${source.repo}.`);
+  const tree = readPackageTree(files);
+  const [nodes, bases] = await Promise.all([client.nodes.list(), client.bases.list()]);
+  const targetFolderSlug = options.intoFolder ?? tree.manifest.name;
+  const plan = buildInstallPlan(
+    tree,
+    {
+      targetFolder: findTargetFolder(nodes, targetFolderSlug),
+      existingBaseSlugs: new Set(bases.map((base) => base.slug))
+    },
+    { intoFolder: options.intoFolder, rename: options.rename }
+  );
+  if (options.dryRun) {
+    const report = `${renderPlan(plan)}
+
+Dry run \u2014 nothing was created.`;
+    return options.json ? { dryRun: true, ...toPlanSummary(plan) } : report;
+  }
+  assertPlanIsApplicable(plan, Boolean(options.autoMerge));
+  const result = await applyInstall(client, plan, {
+    autoMerge: Boolean(options.autoMerge),
+    submittedBy: `busabase-cli install (${tree.manifest.name})`,
+    onProgress: reportProgress
+  });
+  if (options.json) return { installed: true, ...result };
+  return renderInstallReport(plan.targetFolderSlug, result);
+};
+var findTargetFolder = (nodes, slug) => {
+  const roots = nodes.length === 1 && nodes[0].children ? nodes[0].children : nodes;
+  return roots.find((node) => node.slug === slug && node.type === "folder");
+};
+var toPlanSummary = (plan) => ({
+  targetFolder: plan.targetFolderSlug,
+  package: plan.tree.manifest.name,
+  counts: plan.counts,
+  collisions: plan.collisions,
+  warnings: plan.warnings,
+  requiresAutoMerge: plan.requiresAutoMerge
+});
+var renderInstallReport = (targetFolderSlug, result) => {
+  const lines = [];
+  lines.push(`Installed into folder "${targetFolderSlug}".`);
+  lines.push("");
+  lines.push("Created:");
+  for (const [label, count] of Object.entries(result.created)) {
+    if (count > 0) lines.push(`  ${count} ${label}`);
+  }
+  if (result.pendingChangeRequests > 0) {
+    lines.push("");
+    lines.push(
+      `${result.pendingChangeRequests} change request(s) are pending your review \u2014 nothing is live until you merge them:`
+    );
+    lines.push("  busabase-cli change-requests list");
+  }
+  if (result.warnings.length > 0) {
+    lines.push("");
+    lines.push("Warnings:");
+    for (const warning of result.warnings) lines.push(`  \u2022 ${warning}`);
+  }
+  return lines.join("\n");
+};
+var runPublish = async (client, nodeSlugOrId, options) => {
+  const nodes = await client.nodes.list();
+  const source = findSourceNode(nodes, nodeSlugOrId);
+  const warnings = [];
+  const manifest = await resolveManifest(options.outDir, options.name, source.name, source.slug);
+  reportProgress(`Reading "${source.slug}" \u2026`);
+  const tree = await collectPackageTree(client, source, {
+    manifest,
+    warn: (message) => warnings.push(message),
+    baseUrl: options.baseUrl
+  });
+  const files = renderPackageTree(tree);
+  if (!options.dryRun) {
+    await writePackageFiles(files, options.outDir, { clean: true });
+  }
+  if (options.json) {
+    return {
+      published: !options.dryRun,
+      package: manifest.name,
+      outDir: options.outDir,
+      files: [...files.keys()].sort(),
+      warnings
+    };
+  }
+  return renderPublishReport(options, manifest, files, warnings);
+};
+var resolveManifest = async (outDir, nameFlag, nodeName, nodeSlug) => {
+  const existing = await readExistingManifest(outDir);
+  if (existing) {
+    return { ...existing, name: nameFlag ?? existing.name };
+  }
+  return PackageManifestSchema.parse({
+    format: PACKAGE_FORMAT,
+    name: nameFlag ?? nodeSlug,
+    description: nodeName === nodeSlug ? "" : nodeName
+  });
+};
+var readExistingManifest = async (outDir) => {
+  try {
+    const raw = await readFile(join3(outDir, PACKAGE_MANIFEST_FILENAME), "utf8");
+    const parsed = PackageManifestSchema.safeParse(JSON.parse(raw));
+    return parsed.success ? parsed.data : void 0;
+  } catch {
+    return void 0;
+  }
+};
+var renderPublishReport = (options, manifest, files, warnings) => {
+  const lines = [];
+  lines.push(
+    options.dryRun ? `Dry run \u2014 would write ${files.size} file(s) to ${options.outDir}:` : `Wrote ${files.size} file(s) to ${options.outDir}:`
+  );
+  for (const filePath of [...files.keys()].sort()) lines.push(`  ${filePath}`);
+  if (warnings.length > 0) {
+    lines.push("");
+    lines.push("Warnings:");
+    for (const warning of warnings) lines.push(`  \u2022 ${warning}`);
+  }
+  if (!options.dryRun) {
+    lines.push("");
+    lines.push("Now publish it to GitHub:");
+    lines.push(`  cd ${options.outDir}`);
+    lines.push(
+      '  git init && git add . && git commit -m "Add ${name} package"'.replace(
+        "${name}",
+        manifest.name
+      )
+    );
+    lines.push(
+      "  git remote add origin https://github.com/<you>/<repo>.git && git push -u origin main"
+    );
+    lines.push("");
+    lines.push("Then anyone can install it:");
+    lines.push("  busabase-cli install https://github.com/<you>/<repo>");
+  }
+  return lines.join("\n");
+};
+
+// 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_EXT2 = {
+  ".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 guessMimeType2 = (filePath) => MIME_BY_EXT2[extname2(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}`);
+  }
+}
+function formatRawErrorBody(status, statusText, text) {
+  try {
+    const parsed = JSON.parse(text);
+    if (typeof parsed.error === "string") {
+      const issues = parsed.data?.issues;
+      let message = parsed.error;
+      if (Array.isArray(issues) && issues.length > 0) {
+        const details = issues.map((issue) => {
+          if (!issue || typeof issue !== "object") return String(issue);
+          const { path, message: issueMessage } = issue;
+          const pathLabel = Array.isArray(path) ? path.join(".") : void 0;
+          return pathLabel ? `${pathLabel}: ${issueMessage}` : String(issueMessage ?? issue);
+        }).join("; ");
+        message = `${message} \u2014 ${details}`;
+      }
+      return `HTTP ${status} ${statusText}: ${message}`;
+    }
+  } catch {
+  }
+  return `HTTP ${status} ${statusText}: ${text}`;
+}
+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(formatRawErrorBody(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 uploadAsset2(config, opts) {
+  const filePath = opts.file;
+  const file = readFileSync2(filePath);
+  const fileName = opts.fileName ?? basename(filePath);
+  const mimeType = opts.mimeType ?? guessMimeType2(filePath);
+  const context = opts.context ?? "record-field";
+  const contentHash = `sha256:${createHash3("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
+  };
+}
+var INLINE_TEXT_MAX_BYTES = 1024 * 1024;
+async function putTextCommand(client, opts) {
+  const assetId = opts.assetId;
+  const text = opts.file ? readFileSync2(opts.file, "utf8") : opts.text;
+  if (opts.none) {
+    return client.assets.putText({ assetId, none: true });
+  }
+  if (text === void 0) {
+    throw new Error("Provide --text <string>, --file <path>, or --none.");
+  }
+  const sizeBytes = Buffer.byteLength(text, "utf8");
+  if (sizeBytes <= INLINE_TEXT_MAX_BYTES) {
+    return client.assets.putText({ assetId, text });
+  }
+  const upload = await client.assets.createTextUploadUrl({ assetId, sizeBytes });
+  const uploadResponse = await fetch(upload.uploadUrl, {
+    method: "PUT",
+    headers: { "content-type": "text/plain; charset=utf-8" },
+    body: text
+  });
+  if (!uploadResponse.ok) {
+    const body = await uploadResponse.text();
+    throw new Error(
+      `Text byte upload failed (${uploadResponse.status} ${uploadResponse.statusText})${body ? `: ${body}` : ""}`
+    );
+  }
+  return client.assets.putText({ assetId, storageKey: upload.storageKey });
+}
+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 runArgAction(state, handler) {
+  return async (arg, _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(arg, 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) {
+  if (inputSchema === void 0) return [];
+  const { inner } = unwrapSchema(inputSchema);
+  const shape = inner?.shape ?? (inner?.def?.type === "object" ? inner.def.shape : void 0);
+  if (!shape || typeof shape !== "object") {
+    return [{ key: "input", kind: "json", required: true, root: true }];
+  }
+  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`
+  "airapps.listFiles"
+  // `airapps files`
+]);
+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) => {
+        let 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;
+          const parsed = f.kind === "json" ? parseJsonValue(value, `${kebab(f.key)}-json`) : value;
+          if (f.root) input = parsed;
+          else input[f.key] = parsed;
+        }
+        let target = client;
+        for (const segment of navPath) target = target[segment];
+        return fields.length > 0 ? target[procKey](input) : target[procKey]();
+      })
+    );
+  };
+  const walk2 = (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") {
+        walk2(child, [...navPath, key]);
+      }
+    }
+  };
+  walk2(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 <${CREATABLE_NODE_TYPES2.join("|")}>`, "node type").choices(CREATABLE_NODE_TYPES2).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) } : {}
+          }
+        ]
+      });
+    })
+  );
+  addGlobalFlags(nodes.command("archive")).description(
+    "Propose archiving a node via a Change Request (review-first by default) \u2014 the only way to move a node into the archived state; DELETE /nodes/{nodeId} (`nodes purge`) only permanently removes a node that is ALREADY archived"
+  ).requiredOption("--node-id <id>", "node id to archive").option("--message <text>", "reviewer-facing Change Request message").option("--submitted-by <name>", "producer label").option(
+    "--auto-merge",
+    "skip review and archive immediately (default: propose a pending Change Request)"
+  ).addHelpText(
+    "after",
+    `
+Examples:
+  busabase-cli nodes archive --node-id nod_123
+  busabase-cli nodes archive --node-id nod_123 --auto-merge   # skip review, archive immediately`
+  ).action(
+    runAction(
+      state,
+      (client, opts) => client.nodes.createChangeRequest({
+        message: opts.message ?? "Archive node",
+        submittedBy: opts.submittedBy,
+        autoMerge: Boolean(opts.autoMerge),
+        operations: [{ kind: "delete", nodeId: opts.nodeId }]
+      })
+    )
+  );
+  addGlobalFlags(nodes.command("list-archived")).description(
+    "List archived (soft-deleted) nodes \u2014 folders, Docs, Skills, etc. (the Trash view)"
+  ).action(runAction(state, (client) => client.nodes.listArchived()));
+  addGlobalFlags(nodes.command("purge")).description(
+    "Permanently delete an ALREADY-archived node and its subtree (irreversible). Archive it first with `nodes archive` if it isn't archived yet."
+  ).requiredOption("--node-id <id>", "archived node id to purge").action(
+    runAction(state, (client, opts) => client.nodes.purge({ nodeId: opts.nodeId }))
+  );
+  addGlobalFlags(nodes.command("move")).description("Move or reorder a node (applied immediately, no review needed)").requiredOption("--node-id <id>", "node id to move").option("--parent-node-id <id>", "new parent folder node id; omit to keep the current parent").option(
+    "--position <n>",
+    "new position among the target parent's children",
+    (v) => Number.parseInt(v, 10)
+  ).option("--message <text>", "Change Request message").option("--submitted-by <name>", "producer label").addHelpText(
+    "after",
+    `
+Examples:
+  busabase-cli nodes move --node-id nod_123 --position 0
+  busabase-cli nodes move --node-id nod_123 --parent-node-id nod_456 --position 2`
+  ).action(
+    runAction(
+      state,
+      (client, opts) => client.nodes.move({
+        nodeId: opts.nodeId,
+        parentNodeId: opts.parentNodeId,
+        position: opts.position,
+        message: opts.message,
+        submittedBy: opts.submittedBy
+      })
+    )
+  );
+  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 \u2014 review-first by default: returns a pending Change Request").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").option(
+    "--auto-merge",
+    "skip review and create the Base immediately (default: propose a pending Change Request)"
+  ).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
+  busabase-cli bases create --slug products --name "Products" --auto-merge   # skip review, create immediately`
+  ).action(
+    runAction(
+      state,
+      (client, opts) => client.bases.create({
+        slug: opts.slug,
+        name: opts.name,
+        description: opts.description,
+        parentNodeId: opts.parentNodeId,
+        fields: parseFieldDefinitions(opts),
+        ...opts.autoMerge ? { autoMerge: true } : {}
+      })
+    )
+  );
+  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 \u2014 review-first by default").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").option(
+    "--auto-merge",
+    "skip review and create the record immediately (default: propose a pending Change Request)"
+  ).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
+  busabase-cli bases create-change-request --base-id bse_123 --fields-json '{"title":"Hello"}' --auto-merge   # skip review, create immediately`
+  ).action(
+    runAction(
+      state,
+      (client, opts) => client.bases.createChangeRequest({
+        baseId: opts.baseId,
+        fields: parseJsonValue(opts.fieldsJson, "fields-json"),
+        message: opts.message,
+        submittedBy: opts.submittedBy,
+        ...opts.autoMerge ? { autoMerge: true } : {}
+      })
+    )
+  );
+  const airapps = program.command("airapps").description("AirApps (sandboxed mini-apps)");
+  addGlobalFlags(airapps.command("list")).description("List AirApps in the active space").action(runAction(state, (client) => client.airapps.list()));
+  addGlobalFlags(airapps.command("get")).description("Get one AirApp by node id").requiredOption("--node-id <id>", "AirApp node id").action(
+    runAction(state, (client, opts) => client.airapps.get({ nodeId: opts.nodeId }))
+  );
+  addGlobalFlags(airapps.command("create")).description("Create an AirApp \u2014 review-first by default: returns a pending Change Request").requiredOption("--slug <slug>", "AirApp slug").requiredOption("--name <name>", "AirApp name").option("--description <text>", "optional description").option("--parent-node-id <id>", "parent folder node id; omit for root").addOption(
+    new Option(
+      "--visibility <private|workspace|public>",
+      "AirApp visibility (default private)"
+    ).choices(["private", "workspace", "public"])
+  ).option("--version <semver>", "AirApp version (default 0.1.0)").option(
+    "--files-json <json|@file>",
+    'files as a JSON array, or @file.json \u2014 text files {"path","content","mimeType?"} or asset-backed files {"path","assetId","displayName?","mimeType?"}'
+  ).addOption(
+    new Option(
+      "--merge-mode <merge|replace>",
+      "how --files-json combines with the default scaffold (default merge)"
+    ).choices(["merge", "replace"])
+  ).option(
+    "--auto-merge",
+    "skip review and create the AirApp immediately (default: propose a pending Change Request)"
+  ).addHelpText(
+    "after",
+    `
+mergeMode explains how --files-json combines with the AirApp's default scaffold:
+  merge (default) \u2014 your files are layered on top of the default Hono-template
+                     scaffold by path; supply just a few files (e.g. one custom
+                     route) and still get the rest of the scaffold for any path
+                     you didn't provide yourself.
+  replace          \u2014 your files replace the scaffold entirely; use this when
+                     handing over a complete, self-contained project (e.g. a Vite
+                     app) so you don't end up with stray unrelated default files
+                     mixed in.
+
+Examples:
+  busabase-cli airapps create --slug hello-app --name "Hello App" --files-json @files.json
+  busabase-cli airapps create --slug vite-app --name "Vite App" --files-json @files.json --merge-mode replace
+  busabase-cli airapps create --slug hello-app --name "Hello App" --files-json @files.json --auto-merge   # skip review, create immediately`
+  ).action(
+    runAction(
+      state,
+      (client, opts) => client.airapps.create({
+        slug: opts.slug,
+        name: opts.name,
+        description: opts.description,
+        parentNodeId: opts.parentNodeId,
+        visibility: opts.visibility,
+        version: opts.version,
+        files: opts.filesJson ? parseJsonValue(opts.filesJson, "files-json") : void 0,
+        mergeMode: opts.mergeMode,
+        ...opts.autoMerge ? { autoMerge: true } : {}
+      })
+    )
+  );
+  addGlobalFlags(airapps.command("files")).description("List an AirApp's files").requiredOption("--node-id <id>", "AirApp node id").action(
+    runAction(
+      state,
+      (client, opts) => client.airapps.listFiles({ nodeId: opts.nodeId })
+    )
+  );
+  addGlobalFlags(airapps.command("read-file")).description("Read one AirApp file's content").requiredOption("--node-id <id>", "AirApp node id").requiredOption("--path <path>", "file path within the AirApp").action(
+    runAction(
+      state,
+      (client, opts) => client.airapps.readFile({ nodeId: opts.nodeId, filePath: opts.path })
+    )
+  );
+  addGlobalFlags(airapps.command("create-change-request")).description("Propose file changes to an existing AirApp via a Change Request").requiredOption("--node-id <id>", "AirApp node id").requiredOption(
+    "--operations-json <json|@file>",
+    'file operations as a JSON array, or @file.json \u2014 "create"/"update" (text {"kind","path","content","mimeType?"} or asset-backed {"kind","path","assetId","displayName?","mimeType?"}), "delete" {"kind","path"}, or "metadata_update" {"kind","metadata":{"entryFile?","visibility?","version?"}}'
+  ).option("--message <text>", "reviewer-facing Change Request message").option("--submitted-by <name>", "producer label").addHelpText(
+    "after",
+    `
+Examples:
+  busabase-cli airapps create-change-request --node-id nod_123 --operations-json @operations.json
+  busabase-cli airapps create-change-request --node-id nod_123 --operations-json '[{"kind":"update","path":"index.js","content":"..."}]' --message "Fix handler bug"`
+  ).action(
+    runAction(
+      state,
+      (client, opts) => client.airapps.createChangeRequest({
+        nodeId: opts.nodeId,
+        message: opts.message,
+        submittedBy: opts.submittedBy,
+        operations: parseJsonValue(
+          opts.operationsJson,
+          "operations-json"
+        )
+      })
+    )
+  );
+  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).option(
+    "--sources <sources...>",
+    'restrict which content to search: "records", "files", and/or "names" (default: all three)'
+  ).action(
+    runAction(
+      state,
+      (client, opts) => client.search({
+        query: opts.query,
+        limit: opts.limit,
+        offset: opts.offset,
+        sources: opts.sources
+      })
+    )
+  );
+  addGlobalFlags(program.command("grep")).description(
+    "Search files, Docs, and Base records with one pattern (unified grep; use `assets grep` for files-only)"
+  ).requiredOption("--pattern <regex>", "literal or regex pattern").option("--flags <flags>", 'RegExp flags, e.g. "i" for case-insensitive').option(
+    "--sources <sources...>",
+    'sources to scan: "files", "docs", and/or "records" (default: all three)'
+  ).option("--asset-ids <ids...>", "files scope: specific asset ids").option("--drive-path <path>", "files scope: Drive/Skill mounted path prefix").option("--mime-types <types...>", "files scope: MIME types").option("--node-ids <ids...>", "docs scope: specific Doc node ids").option("--base-ids <ids...>", "records scope: specific Base ids").option("--base-slugs <slugs...>", "records scope: specific Base slugs").option(
+    "--max-matches <n>",
+    "max matches, shared across sources (default 100, cap 1000)",
+    parsePositiveInt
+  ).option("--context-lines <n>", "lines of before/after context (default 0, cap 10)", parseNum).action(
+    runAction(state, (client, opts) => {
+      const filesScope = opts.assetIds || opts.drivePath || opts.mimeTypes ? {
+        assetIds: opts.assetIds,
+        drivePath: opts.drivePath,
+        mimeTypes: opts.mimeTypes
+      } : void 0;
+      const docsScope = opts.nodeIds ? { nodeIds: opts.nodeIds } : void 0;
+      const recordsScope = opts.baseIds || opts.baseSlugs ? {
+        baseIds: opts.baseIds,
+        baseSlugs: opts.baseSlugs
+      } : void 0;
+      return client.grep({
+        pattern: opts.pattern,
+        flags: opts.flags,
+        sources: opts.sources,
+        scope: filesScope || docsScope || recordsScope ? { files: filesScope, docs: docsScope, records: recordsScope } : void 0,
+        maxMatches: opts.maxMatches,
+        contextLines: opts.contextLines
+      });
+    })
+  );
+  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) => uploadAsset2(config, opts)));
+  const assetsCommand = program.command("assets").description("Assets");
+  addUploadCommand(assetsCommand);
+  addGlobalFlags(assetsCommand.command("put-text")).description("Write (or mark none) an asset's Drive Grep Retrieval text slot").requiredOption("--asset-id <id>", "asset id").option("--text <string>", "inline text (\u22641MB)").option("--file <path>", "read text from a local file instead of --text").option("--none", "mark as having no extractable text (e.g. a scanned, image-only PDF)").addHelpText(
+    "after",
+    `
+Examples:
+  busabase-cli assets put-text --asset-id ast_123 --file ./extracted.txt
+  busabase-cli assets put-text --asset-id ast_123 --text "plain text"
+  busabase-cli assets put-text --asset-id ast_123 --none`
+  ).action(runAction(state, (client, opts) => putTextCommand(client, opts)));
+  addGlobalFlags(assetsCommand.command("grep")).description("Search every text-bearing asset in scope").requiredOption("--pattern <regex>", "literal or regex pattern").option("--flags <flags>", 'RegExp flags, e.g. "i" for case-insensitive').option("--asset-ids <ids...>", "scope: specific asset ids").option("--drive-path <path>", "scope: Drive/Skill mounted path prefix").option("--mime-types <types...>", "scope: MIME types").option("--max-matches <n>", "max matches (default 100, cap 1000)", parsePositiveInt).option("--context-lines <n>", "lines of before/after context (default 0, cap 10)", parseNum).action(
+    runAction(
+      state,
+      (client, opts) => client.assets.grep({
+        pattern: opts.pattern,
+        flags: opts.flags,
+        scope: opts.assetIds || opts.drivePath || opts.mimeTypes ? {
+          assetIds: opts.assetIds,
+          drivePath: opts.drivePath,
+          mimeTypes: opts.mimeTypes
+        } : void 0,
+        maxMatches: opts.maxMatches,
+        contextLines: opts.contextLines
+      })
+    )
+  );
+  addGlobalFlags(assetsCommand.command("read-lines")).description("Read an exact line range from an asset's text (range capped at 2000 lines)").requiredOption("--asset-id <id>", "asset id").requiredOption("--start-line <n>", "first line (1-based)", parsePositiveInt).requiredOption("--end-line <n>", "last line (1-based)", parsePositiveInt).action(
+    runAction(
+      state,
+      (client, opts) => client.assets.readTextLines({
+        assetId: opts.assetId,
+        startLine: opts.startLine,
+        endLine: opts.endLine
+      })
+    )
+  );
+  addGlobalFlags(program.command("install")).description("Install a Busabase package from a GitHub repo into this space").argument("<github-url>", "GitHub repo URL, optionally /tree/<ref>[/<subdir>]").option("--into-folder <name>", "target folder slug (default: the package's manifest name)").option("--dry-run", "print the plan (tree, record counts, collisions) and create nothing").option(
+    "--auto-merge",
+    "merge the package's records and docs on the spot instead of leaving them as change requests to review \u2014 this TRUSTS THE PACKAGE AUTHOR, since skills and AirApps carry code your agents will run (default: review first)"
+  ).option(
+    "--rename",
+    "install colliding items under suffixed slugs (-2, -3, \u2026) instead of failing"
+  ).addHelpText(
+    "after",
+    `
+The URL's git ref is the version pin \u2014 a tag installs that tag's content forever,
+even after the branch moves on. GITHUB_TOKEN is honored for private repos.
+
+Examples:
+  busabase-cli install https://github.com/acme/support-kb-template
+  busabase-cli install https://github.com/acme/packages/tree/v1.2.0/skills/pdf-summarizer
+  busabase-cli install https://github.com/acme/support-kb-template --dry-run
+  busabase-cli install https://github.com/acme/support-kb-template --into-folder support --auto-merge
+
+Folders, Bases, their fields and their views are structure and are always created
+immediately. Records are content: by default they land as change requests for you
+to review, and --auto-merge merges them on the spot instead.
+
+A package whose records carry relation values requires --auto-merge \u2014 a relation
+stores the ids of the records it points at, and those exist only once the records
+are merged, so review-first would install every relation empty. Defining a relation
+field with nothing linked yet does not trigger this.`
+  ).action(
+    runArgAction(
+      state,
+      (repoUrl, client, opts, config) => runInstall(client, repoUrl, {
+        intoFolder: opts.intoFolder,
+        dryRun: Boolean(opts.dryRun),
+        autoMerge: Boolean(opts.autoMerge),
+        rename: Boolean(opts.rename),
+        json: config.output === "json",
+        githubToken: process.env.GITHUB_TOKEN
+      })
+    )
+  );
+  addGlobalFlags(program.command("publish")).description("Export a node subtree as a Busabase package directory you can push to GitHub").argument("<node-slug-or-id>", "the folder/node to publish").requiredOption("-o, --out-dir <dir>", "output directory for the package").option("--name <name>", "package name (default: reuse busabase.json, else the node slug)").option("--dry-run", "list the files that would be written and write nothing").addHelpText(
+    "after",
+    `
+Output is deterministic: publishing twice from an unchanged space produces
+byte-identical files, so a GitHub diff shows exactly what changed.
+
+Examples:
+  busabase-cli publish support-kb -o ./support-kb-template
+  busabase-cli publish support-kb -o ./support-kb-template --name "Support KB" --dry-run`
+  ).action(
+    runArgAction(
+      state,
+      (nodeSlugOrId, client, opts, config) => runPublish(client, nodeSlugOrId, {
+        outDir: opts.outDir,
+        name: opts.name,
+        dryRun: Boolean(opts.dryRun),
+        json: config.output === "json",
+        baseUrl: config.baseUrl
+      })
+    )
+  );
+  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
+};