@headband/cli 0.1.0 → 0.3.0

package/dist/index.js

@@ -6,6 +6,10 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -22,6 +26,25 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
   mod
 ));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CLI_VERSION: () => CLI_VERSION,
+  main: () => main,
+  parseArgv: () => parseArgv,
+  parseExpires: () => parseExpires,
+  parsePermissions: () => parsePermissions,
+  run: () => run,
+  stdinIsInteractive: () => stdinIsInteractive
+});
+module.exports = __toCommonJS(index_exports);
+var import_fs10 = require("fs");
+var import_fs11 = require("fs");
+var import_path9 = require("path");
+var import_prompts2 = __toESM(require("prompts"));
+var import_picocolors3 = __toESM(require("picocolors"));
 
 // src/init.ts
 var import_prompts = __toESM(require("prompts"));
@@ -32,6 +55,19 @@ var import_path2 = require("path");
 var import_fs = require("fs");
 var import_child_process = require("child_process");
 var import_path = require("path");
+function isPublicSearchKey(value) {
+  return /^hb_src_[A-Za-z0-9_-]+$/.test(value.trim());
+}
+function validatePublicSearchKey(value) {
+  if (!value.trim()) return "Search API key is required";
+  if (value.startsWith("hb_adm_")) {
+    return "Admin keys must stay server-side. Create or paste an hb_src_ search key for browser config.";
+  }
+  if (!isPublicSearchKey(value)) {
+    return "Search key must start with hb_src_";
+  }
+  return true;
+}
 function detectPackageManager(cwd) {
   if ((0, import_fs.existsSync)((0, import_path.join)(cwd, "pnpm-lock.yaml"))) return "pnpm";
   if ((0, import_fs.existsSync)((0, import_path.join)(cwd, "yarn.lock"))) return "yarn";
@@ -50,8 +86,8 @@ function getInstallCommand(pm, pkg) {
       return `npm install ${pkg}`;
   }
 }
-function runCommand(command2, cwd) {
-  (0, import_child_process.execSync)(command2, { cwd, stdio: "inherit" });
+function runCommand(command, cwd) {
+  (0, import_child_process.execSync)(command, { cwd, stdio: "inherit" });
 }
 function hasSrcDir(cwd) {
   return (0, import_fs.existsSync)((0, import_path.join)(cwd, "src"));
@@ -64,6 +100,10 @@ function writeFileSafe(filePath, content) {
   (0, import_fs.writeFileSync)(filePath, content, "utf-8");
 }
 function generateConfig(opts) {
+  const keyValidation = validatePublicSearchKey(opts.searchKey);
+  if (keyValidation !== true) {
+    throw new Error(keyValidation);
+  }
   return `export const headbandConfig = {
   url: "${opts.url}",
   searchKey: process.env.NEXT_PUBLIC_HEADBAND_KEY || "${opts.searchKey}",
@@ -127,15 +167,9 @@ async function init(options = {}) {
         {
           type: "text",
           name: "searchKey",
-          message: "Paste your search API key",
-          hint: "hb_src_... or hb_adm_...",
-          validate: (v) => {
-            if (!v) return "API key is required";
-            if (!v.startsWith("hb_src_") && !v.startsWith("hb_adm_")) {
-              return "Key must start with hb_src_ or hb_adm_";
-            }
-            return true;
-          }
+          message: "Paste your browser-safe search API key",
+          hint: "hb_src_... only. Keep hb_adm_ admin keys server-side.",
+          validate: validatePublicSearchKey
         },
         {
           type: "text",
@@ -154,9 +188,7 @@ async function init(options = {}) {
   }
   const pm = detectPackageManager(cwd);
   console.log();
-  console.log(
-    import_picocolors.default.dim(`  Detected package manager: ${import_picocolors.default.bold(pm)}`)
-  );
+  console.log(import_picocolors.default.dim(`  Detected package manager: ${import_picocolors.default.bold(pm)}`));
   console.log();
   console.log(import_picocolors.default.cyan("  Installing @headband/react..."));
   console.log();
@@ -165,21 +197,13 @@ async function init(options = {}) {
     runCommand(installCmd, cwd);
   } catch {
     console.log();
-    console.log(
-      import_picocolors.default.yellow(
-        "  Could not install @headband/react automatically."
-      )
-    );
-    console.log(
-      import_picocolors.default.dim(
-        `  Run manually: ${getInstallCommand(pm, "@headband/react")}`
-      )
-    );
+    console.log(import_picocolors.default.yellow("  Could not install @headband/react automatically."));
+    console.log(import_picocolors.default.dim(`  Run manually: ${getInstallCommand(pm, "@headband/react")}`));
   }
   const useSrc = hasSrcDir(cwd);
   const componentsDir = useSrc ? (0, import_path2.join)(cwd, "src", "components") : (0, import_path2.join)(cwd, "components");
   const configImportPath = useSrc ? "../headband.config" : "../headband.config";
-  const configPath = (0, import_path2.join)(cwd, "headband.config.ts");
+  const configPath = useSrc ? (0, import_path2.join)(cwd, "src", "headband.config.ts") : (0, import_path2.join)(cwd, "headband.config.ts");
   const configContent = generateConfig({ url, searchKey, defaultIndex });
   writeFileSafe(configPath, configContent);
   const componentPath = (0, import_path2.join)(componentsDir, "headband-search.tsx");
@@ -192,68 +216,4252 @@ async function init(options = {}) {
   console.log(import_picocolors.default.green(import_picocolors.default.bold("  Headband is ready!")));
   console.log();
   console.log(import_picocolors.default.dim("  Created files:"));
-  console.log(`    ${import_picocolors.default.cyan("headband.config.ts")} \u2014 search configuration`);
+  console.log(
+    `    ${import_picocolors.default.cyan(useSrc ? "src/headband.config.ts" : "headband.config.ts")} \u2014 search configuration`
+  );
   console.log(
     `    ${import_picocolors.default.cyan(
       useSrc ? "src/components/headband-search.tsx" : "components/headband-search.tsx"
     )} \u2014 example search component`
   );
   console.log();
-  console.log(import_picocolors.default.dim("  Recommended: add your API key to .env.local:"));
+  console.log(import_picocolors.default.dim("  Recommended: add your browser-safe search key to .env.local:"));
   console.log();
-  console.log(
-    import_picocolors.default.yellow(`    NEXT_PUBLIC_HEADBAND_KEY=${searchKey}`)
-  );
+  console.log(import_picocolors.default.yellow(`    NEXT_PUBLIC_HEADBAND_KEY=${searchKey}`));
   console.log();
   console.log(import_picocolors.default.dim("  Next steps:"));
   console.log(`    1. Import ${import_picocolors.default.cyan("<HeadbandSearch />")} into a page`);
-  console.log(
-    `    2. Move your API key to ${import_picocolors.default.cyan(".env.local")} for safety`
+  console.log(`    2. Keep admin keys server-side; only expose ${import_picocolors.default.cyan("hb_src_")} keys here`);
+  console.log(`    3. Check the docs at ${import_picocolors.default.cyan("https://headband.dev/docs")}`);
+  console.log();
+}
+
+// src/auth.ts
+var import_child_process2 = require("child_process");
+var import_os2 = require("os");
+var import_picocolors2 = __toESM(require("picocolors"));
+
+// src/errors.ts
+var EXIT_CODES = {
+  ok: 0,
+  generic: 1,
+  usage: 2,
+  auth: 3,
+  permission: 4,
+  notFound: 5,
+  conflict: 6,
+  rateLimited: 7,
+  server: 8,
+  interrupted: 130
+};
+function exitCodeForStatus(status) {
+  if (status === 400 || status === 413 || status === 422) return EXIT_CODES.usage;
+  if (status === 401) return EXIT_CODES.auth;
+  if (status === 402 || status === 403) return EXIT_CODES.permission;
+  if (status === 404 || status === 410) return EXIT_CODES.notFound;
+  if (status === 409) return EXIT_CODES.conflict;
+  if (status === 429) return EXIT_CODES.rateLimited;
+  if (status >= 500) return EXIT_CODES.server;
+  return EXIT_CODES.generic;
+}
+var CliError = class extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = options.exitCode ?? EXIT_CODES.generic;
+    this.code = options.code;
+  }
+};
+var UsageError = class extends CliError {
+  constructor(message, code = "usage_error") {
+    super(message, { exitCode: EXIT_CODES.usage, code });
+    this.name = "UsageError";
+  }
+};
+var AuthError = class extends CliError {
+  constructor(message) {
+    super(message, { exitCode: EXIT_CODES.auth, code: "not_authenticated" });
+    this.name = "AuthError";
+  }
+};
+var ApiError = class extends CliError {
+  constructor(message, status, code, details) {
+    super(message, { exitCode: exitCodeForStatus(status), code });
+    this.name = "ApiError";
+    this.status = status;
+    this.details = details;
+  }
+};
+var DEFAULT_CODES = {
+  [EXIT_CODES.generic]: "error",
+  [EXIT_CODES.usage]: "usage_error",
+  [EXIT_CODES.auth]: "not_authenticated",
+  [EXIT_CODES.permission]: "permission_denied",
+  [EXIT_CODES.notFound]: "not_found",
+  [EXIT_CODES.conflict]: "conflict",
+  [EXIT_CODES.rateLimited]: "rate_limited",
+  [EXIT_CODES.server]: "server_error",
+  [EXIT_CODES.interrupted]: "interrupted"
+};
+function errorExitCode(error) {
+  return error instanceof CliError ? error.exitCode : EXIT_CODES.generic;
+}
+function errorPayload(error) {
+  const exitCode = errorExitCode(error);
+  return {
+    error: error instanceof Error ? error.message : String(error),
+    code: error instanceof CliError && error.code || DEFAULT_CODES[exitCode] || "error",
+    status: error instanceof ApiError ? error.status : null,
+    exitCode
+  };
+}
+function partialFailureSummary(failure) {
+  const first = failure.errors[0];
+  if (!first) return failure.message;
+  const id = first.id === null ? "a document" : `document "${first.id}"`;
+  return `${failure.message} (first: ${id}${first.reason ? `: ${first.reason}` : ""})`;
+}
+
+// src/config-store.ts
+var import_fs2 = require("fs");
+var import_path3 = require("path");
+var import_os = require("os");
+var DEFAULT_URL = "https://headband.dev";
+var DEFAULT_PROFILE = "default";
+function normalizeUrl(url) {
+  return url.replace(/\/+$/, "");
+}
+function getConfigDir() {
+  return process.env.XDG_CONFIG_HOME ? (0, import_path3.join)(process.env.XDG_CONFIG_HOME, "headband") : (0, import_path3.join)((0, import_os.homedir)(), ".config", "headband");
+}
+function getCredentialsPath() {
+  return (0, import_path3.join)(getConfigDir(), "credentials.json");
+}
+var PROFILE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+function validateProfileName(name) {
+  if (!PROFILE_NAME.test(name)) {
+    throw new UsageError(
+      "Profile names use letters, digits, dot, dash and underscore (max 64 characters)."
+    );
+  }
+  return name;
+}
+function profileNameForUrl(url) {
+  const normalized = normalizeUrl(url);
+  if (normalized === DEFAULT_URL) return DEFAULT_PROFILE;
+  try {
+    const { host } = new URL(normalized);
+    const slug = host.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^[^A-Za-z0-9]+/, "");
+    return slug || DEFAULT_PROFILE;
+  } catch {
+    return DEFAULT_PROFILE;
+  }
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function migrateCredentials(raw) {
+  const parsed = isRecord(raw) ? raw : {};
+  const rawProfiles = isRecord(parsed.profiles) ? parsed.profiles : {};
+  const profiles = {};
+  let migratedDefault;
+  let migratedCount = 0;
+  for (const [key, value] of Object.entries(rawProfiles)) {
+    if (!isRecord(value)) continue;
+    if (typeof value.url === "string") {
+      profiles[key] = value;
+      continue;
+    }
+    const url = normalizeUrl(key);
+    const base = profileNameForUrl(url);
+    let name = base;
+    for (let n = 2; profiles[name] || rawProfiles[name]; n += 1) name = `${base}-${n}`;
+    profiles[name] = { ...value, url };
+    migratedCount += 1;
+    if (url === DEFAULT_URL) migratedDefault = name;
+  }
+  let current = typeof parsed.current === "string" ? parsed.current : void 0;
+  if (current && !profiles[current]) current = void 0;
+  if (!current && migratedCount > 0) {
+    const names = Object.keys(profiles);
+    current = names.length === 1 ? names[0] : migratedDefault;
+  }
+  return { version: 2, ...current ? { current } : {}, profiles };
+}
+function readCredentials() {
+  const path2 = getCredentialsPath();
+  if (!(0, import_fs2.existsSync)(path2)) {
+    return { version: 2, profiles: {} };
+  }
+  try {
+    return migrateCredentials(JSON.parse((0, import_fs2.readFileSync)(path2, "utf-8")));
+  } catch {
+    throw new CliError(`Could not read credentials at ${path2}`);
+  }
+}
+function writeCredentials(credentials) {
+  const path2 = getCredentialsPath();
+  if (Object.keys(credentials.profiles).length === 0) {
+    if ((0, import_fs2.existsSync)(path2)) (0, import_fs2.rmSync)(path2);
+    return;
+  }
+  (0, import_fs2.mkdirSync)((0, import_path3.dirname)(path2), { recursive: true, mode: 448 });
+  (0, import_fs2.writeFileSync)(path2, `${JSON.stringify(credentials, null, 2)}
+`, {
+    encoding: "utf-8",
+    mode: 384
+  });
+  (0, import_fs2.chmodSync)(path2, 384);
+}
+function saveProfile(name, profile) {
+  validateProfileName(name);
+  const credentials = readCredentials();
+  credentials.profiles[name] = { ...profile, url: normalizeUrl(profile.url) };
+  credentials.current = name;
+  writeCredentials(credentials);
+}
+function removeProfile(name) {
+  const credentials = readCredentials();
+  const existing = credentials.profiles[name];
+  delete credentials.profiles[name];
+  if (credentials.current === name) delete credentials.current;
+  writeCredentials(credentials);
+  return existing;
+}
+function setCurrentProfile(name) {
+  const credentials = readCredentials();
+  const profile = credentials.profiles[name];
+  if (!profile) {
+    throw new CliError(`No profile named ${name}. Run: headband profiles list`, {
+      exitCode: 5,
+      code: "profile_not_found"
+    });
+  }
+  credentials.current = name;
+  writeCredentials(credentials);
+  return profile;
+}
+function selectProfile(selectors = {}) {
+  const env = selectors.env ?? process.env;
+  const credentials = readCredentials();
+  const urlOverride = selectors.url || env.HEADBAND_URL;
+  const wantedUrl = urlOverride ? normalizeUrl(urlOverride) : void 0;
+  const explicit = selectors.profile || env.HEADBAND_PROFILE;
+  if (explicit) {
+    const profile = credentials.profiles[explicit];
+    if (!profile) {
+      throw new AuthError(`No profile named ${explicit}. Run: headband profiles list`);
+    }
+    if (wantedUrl && normalizeUrl(profile.url) !== wantedUrl) {
+      throw new UsageError(
+        `Profile ${explicit} is for ${profile.url}, not ${wantedUrl}. Drop --url, or log in to that URL with: headband login --url ${wantedUrl} --profile <name>`
+      );
+    }
+    return { name: explicit, profile };
+  }
+  const entries = Object.entries(credentials.profiles);
+  const matches = (p) => !wantedUrl || normalizeUrl(p.url) === wantedUrl;
+  const current = credentials.current ? credentials.profiles[credentials.current] : void 0;
+  if (current && credentials.current && matches(current)) {
+    return { name: credentials.current, profile: current };
+  }
+  if (wantedUrl) {
+    const found = entries.find(([, p]) => matches(p));
+    return found ? { name: found[0], profile: found[1] } : void 0;
+  }
+  if (entries.length === 1) return { name: entries[0][0], profile: entries[0][1] };
+  return void 0;
+}
+function resolveAuth(selectors = {}) {
+  const env = selectors.env ?? process.env;
+  const urlOverride = selectors.url || env.HEADBAND_URL;
+  const token = selectors.token || env.HEADBAND_API_KEY;
+  if (token) {
+    const explicitProfile = selectors.profile || env.HEADBAND_PROFILE;
+    const fromProfile = explicitProfile && !urlOverride ? selectProfile(selectors) : void 0;
+    return {
+      url: normalizeUrl(urlOverride || fromProfile?.profile.url || DEFAULT_URL),
+      apiKey: token.trim(),
+      source: selectors.token ? "flag" : "env"
+    };
+  }
+  const selected = selectProfile(selectors);
+  if (!selected) {
+    const target = urlOverride ? normalizeUrl(urlOverride) : DEFAULT_URL;
+    throw new AuthError(
+      `Not logged in for ${target}. Run: headband login --url ${target}, or set HEADBAND_API_KEY.`
+    );
+  }
+  return {
+    url: normalizeUrl(selected.profile.url),
+    apiKey: selected.profile.apiKey,
+    source: "profile",
+    profileName: selected.name,
+    profile: selected.profile
+  };
+}
+
+// src/api.ts
+async function readJson(response) {
+  const text = await response.text();
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+async function apiRequest(baseUrl, path2, init2 = {}) {
+  const headers = new Headers(init2.headers);
+  headers.set("accept", "application/json");
+  if (init2.body !== void 0 && !headers.has("content-type")) {
+    headers.set("content-type", "application/json");
+  }
+  if (init2.apiKey) {
+    headers.set("authorization", `Bearer ${init2.apiKey}`);
+  }
+  const base = normalizeUrl(baseUrl);
+  let response;
+  try {
+    response = await fetch(`${base}${path2}`, {
+      ...init2,
+      headers,
+      body: init2.body === void 0 || typeof init2.body === "string" ? init2.body : JSON.stringify(init2.body)
+    });
+  } catch (error) {
+    const cause = error?.cause;
+    const detail = cause?.code || cause?.message || (error instanceof Error ? error.message : "");
+    throw new CliError(`Could not reach ${base}${detail ? ` (${detail})` : ""}.`, {
+      exitCode: EXIT_CODES.server,
+      code: "network_error"
+    });
+  }
+  const body = await readJson(response);
+  if (!response.ok) {
+    const errorBody = body && typeof body === "object" ? body : {};
+    throw new ApiError(
+      errorBody.error || `Request failed with status ${response.status}`,
+      response.status,
+      errorBody.code,
+      body
+    );
+  }
+  return body;
+}
+function createApiClient(url, profile) {
+  const request = (path2, init2 = {}) => apiRequest(url, path2, { ...init2, apiKey: profile.apiKey });
+  return {
+    url: normalizeUrl(url),
+    get: (path2) => request(path2, { method: "GET" }),
+    post: (path2, body) => request(path2, { method: "POST", body }),
+    patch: (path2, body) => request(path2, { method: "PATCH", body }),
+    delete: (path2) => request(path2, { method: "DELETE" })
+  };
+}
+
+// src/auth.ts
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function openBrowser(url) {
+  try {
+    if (process.platform === "darwin") {
+      (0, import_child_process2.spawn)("open", [url], { detached: true, stdio: "ignore" }).unref();
+    } else if (process.platform === "win32") {
+      (0, import_child_process2.spawn)("cmd", ["/c", "start", "", url], { detached: true, stdio: "ignore" }).unref();
+    } else {
+      (0, import_child_process2.spawn)("xdg-open", [url], { detached: true, stdio: "ignore" }).unref();
+    }
+  } catch {
+  }
+}
+async function runDeviceFlow(url, io, options = {}) {
+  const baseUrl = normalizeUrl(url);
+  const sleep = options.sleep || defaultSleep;
+  const now = options.now || Date.now;
+  const device = await apiRequest(baseUrl, "/api/cli/device", {
+    method: "POST",
+    body: { name: options.deviceName || (0, import_os2.hostname)() }
+  });
+  io.stdout();
+  io.stdout(import_picocolors2.default.bold("Headband login"));
+  io.stdout(`Code: ${import_picocolors2.default.bold(import_picocolors2.default.cyan(device.data.userCode))}`);
+  io.stdout(`Open: ${device.data.verificationUriComplete}`);
+  io.stdout();
+  (options.openBrowser || openBrowser)(device.data.verificationUriComplete);
+  let interval = device.data.interval;
+  const deadline = now() + device.data.expiresIn * 1e3;
+  while (now() < deadline) {
+    await sleep(interval * 1e3);
+    try {
+      const token = await apiRequest(baseUrl, "/api/cli/token", {
+        method: "POST",
+        body: { deviceCode: device.data.deviceCode }
+      });
+      return token.data;
+    } catch (error) {
+      if (!(error instanceof ApiError)) throw error;
+      if (error.code === "authorization_pending") continue;
+      if (error.code === "slow_down") {
+        interval += 5;
+        continue;
+      }
+      if (error.code === "access_denied") {
+        throw new CliError("Login denied.");
+      }
+      if (error.code === "expired_token") {
+        throw new CliError("Login expired. Re-run headband login.");
+      }
+      if (error.code === "invalid_device_code") {
+        throw new CliError("Invalid device code. Re-run headband login.");
+      }
+      throw error;
+    }
+  }
+  throw new CliError("Login expired. Re-run headband login.");
+}
+async function login(url, io, options = {}) {
+  const baseUrl = normalizeUrl(url);
+  const profile = validateProfileName(options.profileName || profileNameForUrl(baseUrl));
+  const token = await runDeviceFlow(baseUrl, io, options);
+  saveProfile(profile, {
+    url: baseUrl,
+    apiKey: token.apiKey,
+    keyId: token.keyId,
+    keyPrefix: token.keyPrefix,
+    orgId: token.orgId,
+    orgName: token.orgName,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  io.stdout(
+    import_picocolors2.default.green(`Logged in to ${baseUrl} as ${token.orgName} (${token.keyPrefix}), profile ${profile}`)
   );
-  console.log(
-    `    3. Check the docs at ${import_picocolors.default.cyan("https://headband.dev/docs")}`
+  return {
+    profile,
+    url: baseUrl,
+    orgId: token.orgId,
+    orgName: token.orgName,
+    keyId: token.keyId,
+    keyPrefix: token.keyPrefix
+  };
+}
+
+// src/config-load.ts
+var import_fs3 = require("fs");
+var import_path4 = require("path");
+var import_url = require("url");
+var import_jiti = require("jiti");
+var CONFIG_FILENAMES = [
+  "headband.config.ts",
+  "headband.config.mts",
+  "headband.config.js",
+  "headband.config.mjs",
+  "headband.config.cjs"
+];
+function findConfigFile(cwd) {
+  for (const name of CONFIG_FILENAMES) {
+    const path2 = (0, import_path4.join)(cwd, name);
+    if ((0, import_fs3.existsSync)(path2)) return path2;
+  }
+  return void 0;
+}
+function isSyncConfig(value) {
+  return typeof value === "object" && value !== null && Array.isArray(value.indexes);
+}
+async function loadHeadbandConfig(cwd) {
+  const path2 = findConfigFile(cwd);
+  if (!path2) {
+    throw new CliError(
+      `No headband.config.ts found in ${cwd}. Run "headband init" or create one that exports a Headband sync config.`
+    );
+  }
+  const jiti = (0, import_jiti.createJiti)((0, import_url.pathToFileURL)((0, import_path4.join)(cwd, "headband-cli.js")).href, {
+    interopDefault: true,
+    moduleCache: false,
+    fsCache: false
+  });
+  let mod;
+  try {
+    mod = await jiti.import(path2);
+  } catch (err) {
+    throw new CliError(
+      `Failed to load ${path2}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const candidate = mod.default ?? mod;
+  if (!isSyncConfig(candidate)) {
+    throw new CliError(`${path2} does not export a valid Headband sync config (missing "indexes").`);
+  }
+  const adapter = mod.adapter;
+  return { config: candidate, adapter, path: path2 };
+}
+
+// src/docs.ts
+var import_path5 = require("path");
+var import_fs4 = require("fs");
+var DOCS_BATCH_SIZE = 1e3;
+function parseDocumentsFile(path2) {
+  const content = (0, import_fs4.readFileSync)(path2, "utf-8");
+  const ext = (0, import_path5.extname)(path2).toLowerCase();
+  if (ext === ".jsonl") {
+    return content.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).map((line) => JSON.parse(line));
+  }
+  if (ext === ".json") {
+    const parsed = JSON.parse(content);
+    if (!Array.isArray(parsed)) {
+      throw new CliError("JSON document file must contain an array.");
+    }
+    return parsed;
+  }
+  throw new CliError("Document file must be .json or .jsonl.");
+}
+async function pushDocuments(client, index, documents, io) {
+  let pushed = 0;
+  for (let offset = 0; offset < documents.length; offset += DOCS_BATCH_SIZE) {
+    const batch = documents.slice(offset, offset + DOCS_BATCH_SIZE);
+    await client.post("/v1/bulk", { index, documents: batch });
+    pushed += batch.length;
+    io.stdout(`Pushed ${pushed}/${documents.length} documents`);
+  }
+  return pushed;
+}
+var EXPORT_BATCH_SIZE = 1e3;
+var TYPESENSE_MAX_PAGE = 250;
+async function defaultExportBatchSize(client, index) {
+  try {
+    const list = await client.get("/v1/indexes");
+    const row = list.results?.find((r) => r.uid === index);
+    return row?.engine === "typesense" ? TYPESENSE_MAX_PAGE : EXPORT_BATCH_SIZE;
+  } catch {
+    return EXPORT_BATCH_SIZE;
+  }
+}
+async function exportDocuments(client, options) {
+  const { index, format, batchSize, write } = options;
+  let offset = 0;
+  let exported = 0;
+  let pending;
+  if (format === "json") await write("[");
+  for (; ; ) {
+    const page = await client.get(
+      `/v1/documents?index=${encodeURIComponent(index)}&limit=${batchSize}&offset=${offset}`
+    );
+    const results = Array.isArray(page.results) ? page.results : [];
+    for (const doc of results) {
+      const line = JSON.stringify(doc);
+      if (format === "jsonl") {
+        await write(line);
+      } else {
+        if (pending !== void 0) await write(`  ${pending},`);
+        pending = line;
+      }
+    }
+    exported += results.length;
+    offset += results.length;
+    options.onPage?.(exported, typeof page.total === "number" ? page.total : null);
+    if (results.length < batchSize) break;
+    if (typeof page.total === "number" && offset >= page.total) break;
+  }
+  if (format === "json") {
+    if (pending !== void 0) await write(`  ${pending}`);
+    await write("]");
+  }
+  return exported;
+}
+
+// ../../src/lib/density/catalog-constants.ts
+function formatMemory(mb) {
+  return mb >= 1024 ? `${mb / 1024} GB` : `${mb} MB`;
+}
+
+// ../../src/lib/density/snippets.ts
+var ADMIN_NOTE = "Creating an index and adding a document need an admin key. A search key can only search.";
+function visorSnippets(endpoint) {
+  return {
+    packageName: "built-in fetch",
+    install: "# Nothing to install. Node 20 and later have fetch built in.",
+    node: [
+      `const base = "${endpoint}";`,
+      "const headers = {",
+      "  Authorization: `Bearer ${process.env.HEADBAND_API_KEY}`,",
+      '  "Content-Type": "application/json",',
+      "};",
+      "",
+      `// ${ADMIN_NOTE}`,
+      "// Creating the index is safe to repeat: an existing index is kept as it is.",
+      'await fetch(`${base}/v1/indexes/movies`, { method: "PUT", headers, body: JSON.stringify({ primaryKey: "id" }) });',
+      'await fetch(`${base}/v1/indexes/movies/documents`, { method: "POST", headers, body: JSON.stringify([{ id: 1, title: "The Matrix" }]) });',
+      "",
+      'const res = await fetch(`${base}/v1/indexes/movies/search`, { method: "POST", headers, body: JSON.stringify({ q: "matrix" }) });',
+      "console.log((await res.json()).hits);"
+    ].join("\n"),
+    curl: [
+      `# ${ADMIN_NOTE}`,
+      "# On a second run the index already exists and PUT keeps it. That is fine.",
+      `curl -X PUT "${endpoint}/v1/indexes/movies" \\`,
+      '  -H "Authorization: Bearer $HEADBAND_API_KEY" \\',
+      '  -H "Content-Type: application/json" \\',
+      `  -d '{"primaryKey":"id"}'`,
+      "",
+      "# Writes are searchable when they return. There is nothing to wait for.",
+      `curl "${endpoint}/v1/indexes/movies/documents" \\`,
+      '  -H "Authorization: Bearer $HEADBAND_API_KEY" \\',
+      '  -H "Content-Type: application/json" \\',
+      `  -d '[{"id":1,"title":"The Matrix"}]'`,
+      "",
+      `curl "${endpoint}/v1/indexes/movies/search" \\`,
+      '  -H "Authorization: Bearer $HEADBAND_API_KEY" \\',
+      '  -H "Content-Type: application/json" \\',
+      `  -d '{"q":"matrix"}'`
+    ].join("\n")
+  };
+}
+function connectSnippets(engine, endpoint) {
+  if (engine === "visor") return visorSnippets(endpoint);
+  if (engine === "elasticsearch") {
+    return {
+      packageName: "@elastic/elasticsearch",
+      // Client 9 sends a version 9 Accept header, which an 8.x server refuses.
+      install: "npm install @elastic/elasticsearch@8",
+      node: [
+        'import { Client } from "@elastic/elasticsearch";',
+        "",
+        "const client = new Client({",
+        `  node: "${endpoint}",`,
+        "  auth: { apiKey: process.env.HEADBAND_API_KEY },",
+        "});",
+        "",
+        `// ${ADMIN_NOTE}`,
+        'if (!(await client.indices.exists({ index: "movies" }))) {',
+        '  await client.indices.create({ index: "movies" });',
+        "}",
+        'await client.index({ index: "movies", id: "1", document: { title: "The Matrix" }, refresh: true });',
+        "",
+        'const results = await client.search({ index: "movies", query: { match: { title: "matrix" } } });',
+        "console.log(results.hits.hits);"
+      ].join("\n"),
+      curl: [
+        `# ${ADMIN_NOTE}`,
+        "# On a second run this answers that the index already exists. That is fine.",
+        `curl -X PUT "${endpoint}/movies" \\`,
+        '  -H "Authorization: ApiKey $HEADBAND_API_KEY"',
+        "",
+        `curl -X PUT "${endpoint}/movies/_doc/1?refresh=true" \\`,
+        '  -H "Authorization: ApiKey $HEADBAND_API_KEY" \\',
+        '  -H "Content-Type: application/json" \\',
+        `  -d '{"title":"The Matrix"}'`,
+        "",
+        `curl "${endpoint}/movies/_search" \\`,
+        '  -H "Authorization: ApiKey $HEADBAND_API_KEY" \\',
+        '  -H "Content-Type: application/json" \\',
+        `  -d '{"query":{"match":{"title":"matrix"}}}'`
+      ].join("\n")
+    };
+  }
+  if (engine === "typesense") {
+    let url;
+    try {
+      url = new URL(endpoint);
+    } catch {
+      url = { hostname: endpoint, protocol: "https:", port: "" };
+    }
+    const protocol = url.protocol.replace(":", "");
+    const port = url.port ? Number(url.port) : protocol === "https" ? 443 : 80;
+    return {
+      packageName: "typesense",
+      install: "npm install typesense",
+      node: [
+        'import Typesense from "typesense";',
+        "",
+        "const client = new Typesense.Client({",
+        `  nodes: [{ host: "${url.hostname}", port: ${port}, protocol: "${protocol}" }],`,
+        "  apiKey: process.env.HEADBAND_API_KEY,",
+        "});",
+        "",
+        `// ${ADMIN_NOTE}`,
+        "// A 409 means the collection exists from an earlier run.",
+        "await client.collections().create({",
+        '  name: "movies",',
+        '  fields: [{ name: "title", type: "string" }],',
+        "}).catch((err) => {",
+        "  if (err.httpStatus !== 409) throw err;",
+        "});",
+        'await client.collections("movies").documents().upsert({ id: "1", title: "The Matrix" });',
+        "",
+        'const results = await client.collections("movies").documents().search({ q: "matrix", query_by: "title" });',
+        "console.log(results.hits);"
+      ].join("\n"),
+      curl: [
+        `# ${ADMIN_NOTE}`,
+        "# On a second run this answers that the collection already exists. That is fine.",
+        `curl "${endpoint}/collections" \\`,
+        '  -H "X-TYPESENSE-API-KEY: $HEADBAND_API_KEY" \\',
+        '  -H "Content-Type: application/json" \\',
+        `  -d '{"name":"movies","fields":[{"name":"title","type":"string"}]}'`,
+        "",
+        `curl "${endpoint}/collections/movies/documents?action=upsert" \\`,
+        '  -H "X-TYPESENSE-API-KEY: $HEADBAND_API_KEY" \\',
+        '  -H "Content-Type: application/json" \\',
+        `  -d '{"id":"1","title":"The Matrix"}'`,
+        "",
+        `curl "${endpoint}/collections/movies/documents/search?q=matrix&query_by=title" \\`,
+        '  -H "X-TYPESENSE-API-KEY: $HEADBAND_API_KEY"'
+      ].join("\n")
+    };
+  }
+  return {
+    packageName: "meilisearch",
+    install: "npm install meilisearch",
+    node: [
+      'import { Meilisearch } from "meilisearch";',
+      "",
+      "const client = new Meilisearch({",
+      `  host: "${endpoint}",`,
+      "  apiKey: process.env.HEADBAND_API_KEY,",
+      "});",
+      "",
+      `// ${ADMIN_NOTE}`,
+      "// waitTask() waits until Meilisearch has applied the change. On a second run",
+      "// the create task fails because the index exists, which is fine.",
+      'await client.createIndex("movies", { primaryKey: "id" }).waitTask();',
+      'await client.index("movies").addDocuments([{ id: 1, title: "The Matrix" }]).waitTask();',
+      "",
+      'const results = await client.index("movies").search("matrix");',
+      "console.log(results.hits);"
+    ].join("\n"),
+    curl: [
+      `# ${ADMIN_NOTE}`,
+      "# On a second run this task fails because the index already exists. That is fine.",
+      `curl "${endpoint}/indexes" \\`,
+      '  -H "Authorization: Bearer $HEADBAND_API_KEY" \\',
+      '  -H "Content-Type: application/json" \\',
+      `  -d '{"uid":"movies","primaryKey":"id"}'`,
+      "",
+      `curl "${endpoint}/indexes/movies/documents" \\`,
+      '  -H "Authorization: Bearer $HEADBAND_API_KEY" \\',
+      '  -H "Content-Type: application/json" \\',
+      `  -d '[{"id":1,"title":"The Matrix"}]'`,
+      "",
+      "# Meilisearch applies writes in the background. Give it a moment.",
+      "sleep 1",
+      "",
+      `curl "${endpoint}/indexes/movies/search" \\`,
+      '  -H "Authorization: Bearer $HEADBAND_API_KEY" \\',
+      '  -H "Content-Type: application/json" \\',
+      `  -d '{"q":"matrix"}'`
+    ].join("\n")
+  };
+}
+
+// src/output.ts
+var defaultIO = {
+  stdout: (message = "") => console.log(message),
+  stderr: (message = "") => console.error(message)
+};
+function printJson(io, value) {
+  io.stdout(JSON.stringify(value, null, 2));
+}
+function formatTable(rows, columns) {
+  if (rows.length === 0) return "No results.";
+  const selectedColumns = columns || Object.keys(rows[0]);
+  const widths = selectedColumns.map(
+    (column) => Math.max(
+      column.length,
+      ...rows.map(
+        (row) => String(row[column] === null || row[column] === void 0 ? "" : row[column]).length
+      )
+    )
   );
-  console.log();
+  const renderRow = (values) => values.map((value, index) => value.padEnd(widths[index])).join("  ").trimEnd();
+  return [
+    renderRow(selectedColumns),
+    renderRow(widths.map((width) => "-".repeat(width))),
+    ...rows.map(
+      (row) => renderRow(
+        selectedColumns.map(
+          (column) => String(row[column] === null || row[column] === void 0 ? "" : row[column])
+        )
+      )
+    )
+  ].join("\n");
+}
+function printTable(io, rows, columns) {
+  io.stdout(formatTable(rows, columns));
+}
+function summarizeHit(hit) {
+  const result = {};
+  for (const key of Object.keys(hit).slice(0, 5)) {
+    const value = hit[key];
+    result[key] = value && typeof value === "object" ? JSON.stringify(value) : value;
+  }
+  return result;
 }
 
-// src/index.ts
-var args = process.argv.slice(2);
-var flags = new Set(args.filter((a) => a.startsWith("-")));
-var positional = args.filter((a) => !a.startsWith("-"));
-var command = positional[0];
-function printHelp() {
-  console.log(`
-  @headband/cli \u2014 Set up Headband search in your project
-
-  Usage:
-    npx @headband/cli init [options]
-
-  Commands:
-    init        Set up Headband in the current project
-
-  Options:
-    --yes       Skip prompts and use defaults
-    --help      Show this help message
-
-  Examples:
-    npx @headband/cli init
-    npx @headband/cli init --yes
-`);
+// src/instances.ts
+var ENGINES = ["meilisearch", "elasticsearch", "typesense", "visor"];
+var CLIENTS = ["node", "curl"];
+var COLUMNS = ["id", "name", "engine", "lane", "memory", "region", "state"];
+var INSTANCES_USAGE = [
+  "Usage:",
+  "  headband instances list [--json]",
+  "  headband instances create <meilisearch|elasticsearch|typesense|visor> [--name <name>] [--lane <serverless|always_on>]",
+  "                            [--memory <512m|1g|...>] [--region <region>] [--idle-timeout <seconds>] [--json]",
+  "  headband instances show <id> [--json]",
+  "  headband instances wake <id> [--json]",
+  "  headband instances park <id> [--json]",
+  "  headband instances update <id> [--name <name>] [--lane <serverless|always_on>] [--memory <512m|1g|...>]",
+  "                               [--idle-timeout <seconds>] [--json]   (--size is an alias for --memory)",
+  "  headband instances wakes <id> [--limit <n>] [--json]",
+  "  headband instances delete <id> [--yes] [--json]",
+  "  headband instances connect <id> [--client <node|curl>] [--json]"
+].join("\n");
+function parseMemory(raw) {
+  const m = /^(\d+(?:\.\d+)?)\s*(m|mb|g|gb)?$/i.exec(raw.trim());
+  if (!m) throw new UsageError("--memory must look like 512m, 1g or 2048");
+  const value = Number(m[1]);
+  const mb = (m[2] ?? "m").toLowerCase().startsWith("g") ? value * 1024 : value;
+  if (!Number.isInteger(mb) || mb <= 0)
+    throw new UsageError("--memory must be a whole number of megabytes");
+  return mb;
 }
-async function main() {
-  if (flags.has("--help") || flags.has("-h") || command === "help") {
-    printHelp();
-    process.exit(0);
+function formatMemoryMb(mb) {
+  return mb % 512 === 0 ? formatMemory(mb) : `${mb} MB`;
+}
+function parseLane(raw) {
+  const lane = raw.replace(/-/g, "_");
+  if (lane !== "serverless" && lane !== "always_on")
+    throw new UsageError("--lane must be serverless or always_on");
+  return lane;
+}
+function parsePositiveInt(raw, name) {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value <= 0)
+    throw new UsageError(`${name} must be a positive integer`);
+  return value;
+}
+function stateLabel(i) {
+  if (i.changeRejected) return `${i.state} (change rejected)`;
+  return i.pendingChanges ? `${i.state} (applying changes)` : i.state;
+}
+function summaryRow(i) {
+  return {
+    id: i.id,
+    name: i.name,
+    engine: i.engine,
+    lane: i.lane,
+    memory: formatMemoryMb(i.memoryMb),
+    region: i.region,
+    state: stateLabel(i)
+  };
+}
+function requireId(args) {
+  const id = args[1];
+  if (!id) throw new UsageError("Missing engine id");
+  return id;
+}
+function friendly(err) {
+  if (err instanceof ApiError) {
+    if (err.status === 404 && err.code === "not_found") {
+      throw new CliError("Dedicated engines are not enabled for this organization yet.", {
+        exitCode: 5,
+        code: "not_found"
+      });
+    }
+    if (err.status === 403 && err.code === "permission_denied") {
+      throw new CliError(
+        "This CLI key cannot manage engines. Run headband login again to get a key that can.",
+        { exitCode: 4, code: "permission_denied" }
+      );
+    }
   }
-  if (!command || command === "init") {
-    await init({ yes: flags.has("--yes") || flags.has("-y") });
-  } else {
-    console.error(`Unknown command: ${command}`);
-    printHelp();
-    process.exit(1);
+  throw err;
+}
+async function runInstances(args, flags, io, client, confirm) {
+  const action = args[0];
+  const json = flags["--json"] === true;
+  const str2 = (name) => typeof flags[name] === "string" ? flags[name] : void 0;
+  const path2 = (id, suffix = "") => `/v1/instances/${encodeURIComponent(id)}${suffix}`;
+  try {
+    if (action === "list") {
+      const res = await client.get("/v1/instances");
+      if (json) return printJson(io, res);
+      if (res.data.length === 0) {
+        io.stdout("No engines yet. Create one with: headband instances create meilisearch");
+        return;
+      }
+      printTable(
+        io,
+        res.data.map((i) => ({
+          ...summaryRow(i),
+          "wake p95": i.wakeP95Ms === null || i.wakeP95Ms === void 0 ? "" : `${Math.round(i.wakeP95Ms)} ms`
+        })),
+        [...COLUMNS, "wake p95"]
+      );
+      return;
+    }
+    if (action === "create") {
+      const engine = args[1];
+      if (!engine || !ENGINES.includes(engine)) {
+        throw new UsageError("Engine must be one of: meilisearch, elasticsearch, typesense, visor");
+      }
+      const body = { engine };
+      const name = str2("--name");
+      const lane = str2("--lane");
+      const memory = str2("--memory");
+      const region = str2("--region");
+      const idle = str2("--idle-timeout");
+      if (name) body.name = name;
+      if (lane) body.lane = parseLane(lane);
+      if (memory) body.memoryMb = parseMemory(memory);
+      if (region) body.region = region;
+      if (idle) body.idleTimeoutS = parsePositiveInt(idle, "--idle-timeout");
+      const res = await client.post("/v1/instances", body);
+      if (json) return printJson(io, res);
+      printTable(io, [summaryRow(res.data)], COLUMNS);
+      io.stdout(`Endpoint: ${res.data.endpoint}`);
+      io.stdout(`Connect a client: headband instances connect ${res.data.id}`);
+      return;
+    }
+    if (action === "show") {
+      const id = requireId(args);
+      const res = await client.get(path2(id));
+      if (json) return printJson(io, res);
+      const i = res.data;
+      const lines = [
+        ["id", i.id],
+        ["name", i.name],
+        ["engine", `${i.engine} ${i.engineVersion}`],
+        ["lane", i.lane],
+        ["memory", formatMemoryMb(i.memoryMb)],
+        ["region", i.region],
+        ["state", stateLabel(i)],
+        ["endpoint", i.endpoint],
+        ["idle timeout", i.lane === "serverless" ? `${i.idleTimeoutS} s` : "n/a"],
+        ["default", i.isDefault ? "yes" : "no"],
+        ["last backup", i.lastBackupAt ?? "never"],
+        ["last wake", i.lastWakeAt ?? "never"]
+      ];
+      const width = Math.max(...lines.map(([k]) => k.length));
+      for (const [k, v] of lines) io.stdout(`${k.padEnd(width)}  ${v}`);
+      return;
+    }
+    if (action === "wake") {
+      const id = requireId(args);
+      const res = await client.post(path2(id, "/wake"));
+      if (json) return printJson(io, res);
+      const { wake } = res.data;
+      io.stdout(
+        wake.via === "running" ? `Engine ${id} is already running.` : `Engine ${id} is ${wake.state} (woke via ${wake.via.replace(/_/g, " ")} in ${wake.ms} ms).`
+      );
+      return;
+    }
+    if (action === "park") {
+      const id = requireId(args);
+      const res = await client.post(path2(id, "/park"));
+      if (json) return printJson(io, res);
+      io.stdout(`Engine ${id} is ${res.data.state}.`);
+      return;
+    }
+    if (action === "update") {
+      const id = requireId(args);
+      const body = {};
+      const name = str2("--name");
+      const lane = str2("--lane");
+      const memory = str2("--memory") ?? str2("--size");
+      const idle = str2("--idle-timeout");
+      if (name) body.name = name;
+      if (lane) body.lane = parseLane(lane);
+      if (memory) body.memoryMb = parseMemory(memory);
+      if (idle) body.idleTimeoutS = parsePositiveInt(idle, "--idle-timeout");
+      if (Object.keys(body).length === 0) {
+        throw new UsageError(
+          "Nothing to update. Pass at least one of --name, --lane, --memory (or --size), --idle-timeout."
+        );
+      }
+      const res = await client.patch(path2(id), body);
+      if (json) return printJson(io, res);
+      printTable(io, [summaryRow(res.data)], COLUMNS);
+      if (res.data.pendingChanges) {
+        io.stdout(
+          "The engine applies the change in the background. Check it with: headband instances show " + id
+        );
+      }
+      return;
+    }
+    if (action === "wakes") {
+      const id = requireId(args);
+      const limit = str2("--limit");
+      const query = limit ? `?limit=${parsePositiveInt(limit, "--limit")}` : "";
+      const res = await client.get(path2(id, `/wakes${query}`));
+      if (json) return printJson(io, res);
+      if (res.data.length === 0) {
+        io.stdout(`No wakes recorded for engine ${id}.`);
+        return;
+      }
+      printTable(
+        io,
+        res.data.map((w) => ({
+          requestedAt: w.requestedAt,
+          via: w.via,
+          outcome: w.outcome,
+          ready: w.readyMs === null ? "" : `${w.readyMs} ms`
+        })),
+        ["requestedAt", "via", "outcome", "ready"]
+      );
+      return;
+    }
+    if (action === "delete") {
+      const id = requireId(args);
+      if (!await confirm(`Delete engine ${id}? This removes its data and backups.`)) {
+        io.stdout("Cancelled.");
+        return;
+      }
+      const res = await client.delete(path2(id));
+      if (json) return printJson(io, res);
+      io.stdout(
+        res.data.deleted ? `Deleted engine ${id}.` : `Engine ${id} is being deleted. It finishes in the background.`
+      );
+      return;
+    }
+    if (action === "connect") {
+      const id = requireId(args);
+      const which = str2("--client");
+      if (which && !CLIENTS.includes(which)) throw new UsageError("--client must be node or curl");
+      const res = await client.get(path2(id));
+      const s = connectSnippets(res.data.engine, res.data.endpoint);
+      if (json) {
+        return printJson(io, {
+          id: res.data.id,
+          engine: res.data.engine,
+          endpoint: res.data.endpoint,
+          install: s.install,
+          ...!which || which === "node" ? { node: s.node } : {},
+          ...!which || which === "curl" ? { curl: s.curl } : {}
+        });
+      }
+      io.stdout(`Endpoint: ${res.data.endpoint}`);
+      io.stdout("");
+      io.stdout(
+        "Set HEADBAND_API_KEY to an organization-wide key. The snippets create an index and add a document, which needs an admin key (headband keys create <name> --type admin). A search key can only search. Project keys do not work on engine endpoints."
+      );
+      if (!which || which === "node") {
+        io.stdout("");
+        io.stdout(`Node (${s.install}):`);
+        io.stdout(s.node);
+      }
+      if (!which || which === "curl") {
+        io.stdout("");
+        io.stdout("curl:");
+        io.stdout(s.curl);
+      }
+      return;
+    }
+    io.stdout(INSTANCES_USAGE);
+    throw new UsageError("Unknown instances command");
+  } catch (err) {
+    friendly(err);
+  }
+}
+
+// src/schema.ts
+var import_fs6 = require("fs");
+var import_path7 = require("path");
+
+// ../sync/src/hash.ts
+var import_node_crypto = require("crypto");
+function stableStringify(value) {
+  return JSON.stringify(normalize(value));
+}
+function normalize(value) {
+  if (Array.isArray(value)) {
+    return value.map(normalize);
+  }
+  if (value !== null && typeof value === "object") {
+    const sortedKeys = Object.keys(value).sort();
+    const result = {};
+    for (const key of sortedKeys) {
+      result[key] = normalize(value[key]);
+    }
+    return result;
+  }
+  return value;
+}
+function normalizeFieldSpec(spec) {
+  if (typeof spec === "function") {
+    return spec.toString();
+  }
+  return spec;
+}
+function docShapeHash(def) {
+  const normalizedFields = {};
+  for (const [name, spec] of Object.entries(def.fields)) {
+    normalizedFields[name] = normalizeFieldSpec(spec);
+  }
+  const shape = {
+    source: def.source,
+    primaryKey: def.primaryKey,
+    shouldIndex: def.shouldIndex?.toString() ?? null,
+    fields: normalizedFields
+  };
+  return (0, import_node_crypto.createHash)("sha256").update(stableStringify(shape)).digest("hex");
+}
+function settingsHash(def) {
+  const settings = def.settings ?? {};
+  return (0, import_node_crypto.createHash)("sha256").update(stableStringify(settings)).digest("hex");
+}
+
+// ../sync/src/migrations.ts
+var import_fs5 = require("fs");
+var import_path6 = require("path");
+var FILE_NAME_RE = /^(\d{4})_(.+)\.json$/;
+function sanitizeSlug(slug) {
+  const sanitized = slug.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/-{2,}/g, "-").replace(/^-+|-+$/g, "");
+  return sanitized || "migration";
+}
+function generateMigrationFile(dir, ops, meta, now = () => /* @__PURE__ */ new Date()) {
+  (0, import_fs5.mkdirSync)(dir, { recursive: true });
+  const existing = readMigrations(dir);
+  const nextVersion = existing.length === 0 ? 1 : existing[existing.length - 1].version + 1;
+  const safeSlug = sanitizeSlug(meta.slug);
+  const fileName = `${String(nextVersion).padStart(4, "0")}_${safeSlug}.json`;
+  const path2 = (0, import_path6.join)(dir, fileName);
+  const file = {
+    version: nextVersion,
+    createdAt: now().toISOString(),
+    parentHashes: meta.parentHashes,
+    ops
+  };
+  (0, import_fs5.writeFileSync)(path2, JSON.stringify(file, null, 2));
+  return path2;
+}
+function readMigrations(dir) {
+  let entries;
+  try {
+    entries = (0, import_fs5.readdirSync)(dir);
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    const match = FILE_NAME_RE.exec(entry);
+    if (!match) continue;
+    const path2 = (0, import_path6.join)(dir, entry);
+    const raw = (0, import_fs5.readFileSync)(path2, "utf-8");
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new Error(`Malformed migration file: ${path2}`);
+    }
+    files.push({ ...parsed, path: path2 });
+  }
+  files.sort((a, b) => a.version - b.version);
+  for (let i = 0; i < files.length; i++) {
+    const expected = i + 1;
+    if (files[i].version === expected) continue;
+    if (files.some((f, idx) => idx !== i && f.version === files[i].version)) {
+      throw new Error(`Duplicate migration version: ${files[i].version}`);
+    }
+    throw new Error(
+      `Migration version gap: expected version ${expected}, found ${files[i].version}`
+    );
+  }
+  return files;
+}
+function pendingMigrations(files, appliedVersion) {
+  return files.filter((f) => f.version > appliedVersion);
+}
+
+// ../sync/src/planner.ts
+function planMigration(config, applied, opts) {
+  const ops = [];
+  const appliedByUid = new Map(applied.map((a) => [a.indexUid, a]));
+  for (const def of config.indexes) {
+    const existing = appliedByUid.get(def.name);
+    const settings = def.settings ?? {};
+    if (!existing) {
+      ops.push({
+        type: "create-index",
+        index: def.name,
+        physicalUid: def.name,
+        settings
+      });
+      continue;
+    }
+    if (existing.status === "failed") {
+      ops.push({
+        type: "reindex",
+        index: def.name,
+        fromPhysicalUid: existing.physicalUid,
+        toPhysicalUid: `${def.name}__v${existing.version + 1}`,
+        settings
+      });
+      continue;
+    }
+    const schemaDrifted = docShapeHash(def) !== existing.schemaHash;
+    const settingsDrifted = settingsHash(def) !== existing.settingsHash;
+    if (schemaDrifted) {
+      ops.push({
+        type: "reindex",
+        index: def.name,
+        fromPhysicalUid: existing.physicalUid,
+        toPhysicalUid: `${def.name}__v${existing.version + 1}`,
+        settings
+      });
+    } else if (settingsDrifted) {
+      ops.push({
+        type: "patch-settings",
+        index: def.name,
+        settings
+      });
+    }
+  }
+  if (opts?.allowDestructive) {
+    const configuredNames = new Set(config.indexes.map((def) => def.name));
+    for (const state of applied) {
+      if (!configuredNames.has(state.indexUid)) {
+        ops.push({ type: "remove-index", index: state.indexUid });
+      }
+    }
+  }
+  return ops;
+}
+
+// ../sync/src/client.ts
+var BASE_BACKOFF_MS = 500;
+var DEFAULT_MAX_RETRIES = 5;
+function defaultSleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var SchemaCasError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SchemaCasError";
+  }
+};
+var HttpError = class extends Error {
+  constructor(message, status, code) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "HttpError";
   }
+};
+function isRecord2(v) {
+  return typeof v === "object" && v !== null;
+}
+function parsePartialFailureItem(raw) {
+  const item = isRecord2(raw) ? raw : {};
+  const status = typeof item.status === "number" ? item.status : void 0;
+  return {
+    id: typeof item.id === "string" || typeof item.id === "number" ? String(item.id) : null,
+    ...status !== void 0 ? { status } : {},
+    ...typeof item.type === "string" ? { type: item.type } : {},
+    ...typeof item.reason === "string" ? { reason: item.reason } : {},
+    // Servers before per-item `retryable` still sent the status.
+    retryable: typeof item.retryable === "boolean" ? item.retryable : status !== void 0 && (status === 429 || status >= 500)
+  };
+}
+function parsePartialFailure(payload, message) {
+  const errors = Array.isArray(payload.errors) ? payload.errors.map(parsePartialFailureItem) : [];
+  const failed = typeof payload.failed === "number" ? payload.failed : errors.length;
+  const everyListedRetryable = failed > 0 && errors.length === failed && errors.every((e) => e.retryable);
+  return { message, failed, errors, retryable: payload.retryable === true || everyListedRetryable };
+}
+var HeadbandClient = class {
+  constructor(opts) {
+    this.baseUrl = opts.url.replace(/\/+$/, "");
+    this.adminKey = opts.adminKey;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.sleep = opts.sleep ?? defaultSleep2;
+  }
+  async bulkPush(index, documents, primaryKey) {
+    const body = { index, documents };
+    if (primaryKey !== void 0) body.primaryKey = primaryKey;
+    const result = await this.request("POST", "/v1/bulk", body, {
+      allowPartialFailure: true
+    });
+    if ("partialFailure" in result) return { tasks: [], partialFailure: result.partialFailure };
+    return { ...result, tasks: result.tasks ?? [] };
+  }
+  async deleteDocs(index, ids) {
+    const result = await this.request(
+      "DELETE",
+      `/v1/documents?index=${encodeURIComponent(index)}`,
+      { ids },
+      { allowPartialFailure: true }
+    );
+    return isRecord2(result) && "partialFailure" in result ? { partialFailure: result.partialFailure } : {};
+  }
+  async createIndex(uid, opts) {
+    const body = { uid };
+    if (opts?.primaryKey !== void 0) body.primaryKey = opts.primaryKey;
+    await this.request("POST", "/v1/indexes", body);
+  }
+  async patchSettings(uid, settings) {
+    await this.request("PATCH", `/v1/indexes/${uid}/settings`, settings);
+  }
+  async getSchemaState() {
+    return this.request("GET", "/v1/schema/state");
+  }
+  async postSchemaState(state) {
+    await this.request("POST", "/v1/schema/state", state, { mapConflictToCasError: true });
+  }
+  async patchAlias(index, physicalUid) {
+    await this.request("PATCH", "/v1/schema/alias", { indexUid: index, physicalUid });
+  }
+  async reportRun(run2) {
+    await this.request("POST", "/v1/connectors/runs", run2);
+  }
+  async request(method, path2, body, opts = {}) {
+    let attempt = 0;
+    for (; ; ) {
+      attempt += 1;
+      const response = await this.fetchImpl(`${this.baseUrl}${path2}`, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.adminKey}`,
+          "Content-Type": "application/json"
+        },
+        ...body !== void 0 ? { body: JSON.stringify(body) } : {}
+      });
+      if (response.ok) {
+        if (response.status === 204) return void 0;
+        return await response.json();
+      }
+      const payload = await response.json().catch(() => ({ error: `Request failed with status ${response.status}` }));
+      const message = payload?.error ?? `Request failed with status ${response.status}`;
+      const code = payload?.code;
+      if (opts.mapConflictToCasError && response.status === 409) {
+        throw new SchemaCasError(message);
+      }
+      if (opts.allowPartialFailure && response.status === 422 && code === "partial_failure") {
+        return { partialFailure: parsePartialFailure(payload, message) };
+      }
+      const retryable = response.status === 429 || response.status >= 500;
+      if (!retryable || attempt >= this.maxRetries) {
+        throw new HttpError(message, response.status, code);
+      }
+      const delay = BASE_BACKOFF_MS * 2 ** (attempt - 1);
+      await this.sleep(delay);
+    }
+  }
+};
+
+// src/schema.ts
+var DEFAULT_BACKFILL_BATCH_SIZE = 500;
+var APPLIED_MARKER_FILE = ".applied.json";
+function opDetail(op) {
+  switch (op.type) {
+    case "create-index":
+      return `physicalUid=${op.physicalUid}`;
+    case "patch-settings":
+      return "settings drift";
+    case "reindex":
+      return `${op.fromPhysicalUid} -> ${op.toPhysicalUid}`;
+    case "remove-index":
+      return "not present in config";
+  }
+}
+function opRows(ops) {
+  return ops.map((op) => ({ op: op.type, index: op.index, detail: opDetail(op) }));
+}
+function printOpsTable(io, ops) {
+  if (ops.length === 0) {
+    io.stdout("Schema is up to date. No pending changes.");
+    return;
+  }
+  printTable(io, opRows(ops), ["op", "index", "detail"]);
+}
+function readAppliedMarker(dir) {
+  const path2 = (0, import_path7.join)(dir, APPLIED_MARKER_FILE);
+  if (!(0, import_fs6.existsSync)(path2)) return 0;
+  try {
+    const parsed = JSON.parse((0, import_fs6.readFileSync)(path2, "utf-8"));
+    return typeof parsed.version === "number" ? parsed.version : 0;
+  } catch {
+    return 0;
+  }
+}
+function writeAppliedMarker(dir, version) {
+  (0, import_fs6.mkdirSync)(dir, { recursive: true });
+  (0, import_fs6.writeFileSync)((0, import_path7.join)(dir, APPLIED_MARKER_FILE), JSON.stringify({ version }, null, 2));
+}
+async function planSchemaDiff(deps) {
+  const applied = await deps.client.getSchemaState();
+  return planMigration(deps.config, applied, { allowDestructive: deps.allowDestructive });
+}
+async function runSchemaGenerate(deps) {
+  const applied = await deps.client.getSchemaState();
+  const ops = planMigration(deps.config, applied, { allowDestructive: deps.allowDestructive });
+  if (ops.length === 0) {
+    deps.io.stdout("No schema changes to generate.");
+    return void 0;
+  }
+  const appliedByUid = new Map(applied.map((a) => [a.indexUid, a]));
+  const parentHashes = {};
+  for (const op of ops) {
+    parentHashes[op.index] = appliedByUid.get(op.index)?.schemaHash ?? "";
+  }
+  const path2 = generateMigrationFile(
+    deps.dir,
+    ops,
+    { parentHashes, slug: deps.slug ?? "migration" },
+    deps.now
+  );
+  deps.io.stdout(`Wrote ${path2}`);
+  printOpsTable(deps.io, ops);
+  return path2;
+}
+function isConflictError(err) {
+  if (!(err instanceof Error)) return false;
+  return err.code === "index_already_exists";
+}
+async function createIndexIdempotent(ctx, uid, opts) {
+  try {
+    await ctx.client.createIndex(uid, opts);
+  } catch (err) {
+    if (!isConflictError(err)) throw err;
+    ctx.io.stdout(`Index "${uid}" already exists \u2014 continuing.`);
+  }
+}
+function postState(client, state) {
+  return client.postSchemaState(state);
+}
+async function applyReindex(op, ctx, existing, expectedParentHash) {
+  const def = ctx.config.indexes.find((d) => d.name === op.index);
+  if (!def) {
+    throw new CliError(`Cannot reindex "${op.index}": no matching index in the loaded config.`);
+  }
+  await createIndexIdempotent(ctx, op.toPhysicalUid, { primaryKey: def.primaryKey });
+  await ctx.client.patchSettings(op.toPhysicalUid, op.settings);
+  const version = (existing?.version ?? 0) + 1;
+  const schemaHashValue = docShapeHash(def);
+  const settingsHashValue = settingsHash(def);
+  let parentHash = expectedParentHash;
+  const writeState = async (status, cursor2) => {
+    await postState(ctx.client, {
+      indexUid: op.index,
+      version,
+      schemaHash: schemaHashValue,
+      settingsHash: settingsHashValue,
+      physicalUid: op.toPhysicalUid,
+      status,
+      // The `/v1/schema/state` route only accepts a string|null
+      // backfillCursor (see route.ts) — `Id` can be numeric, so it must be
+      // stringified before crossing the wire.
+      backfillCursor: cursor2 === null ? null : String(cursor2),
+      expectedParentHash: parentHash
+    });
+    parentHash = schemaHashValue;
+  };
+  await writeState("migrating", null);
+  let cursor = null;
+  let pushed = 0;
+  let excluded = 0;
+  let total = 0;
+  for (; ; ) {
+    const page = await ctx.adapter.listIds(def.source, cursor, ctx.backfillBatchSize);
+    if (page.ids.length === 0) break;
+    total += page.ids.length;
+    const docs = await ctx.adapter.resolveDocs(def.name, page.ids);
+    const toPush = [];
+    for (const doc of docs) {
+      const sourceRow = doc.__source ?? doc;
+      delete doc.__source;
+      if (def.shouldIndex && !def.shouldIndex(sourceRow)) {
+        excluded += 1;
+        continue;
+      }
+      toPush.push(doc);
+    }
+    if (toPush.length > 0) {
+      const result = await ctx.client.bulkPush(op.toPhysicalUid, toPush, def.primaryKey);
+      if (result?.partialFailure) {
+        throw new CliError(
+          `Backfill of "${op.index}" stopped: ${partialFailureSummary(result.partialFailure)}. Aborting before the alias flip. Fix the rejected documents, then re-run "headband schema apply".`
+        );
+      }
+      pushed += toPush.length;
+    }
+    cursor = page.nextCursor;
+    await writeState("migrating", cursor);
+    if (cursor === null || page.ids.length < ctx.backfillBatchSize) break;
+  }
+  if (pushed + excluded !== total) {
+    throw new CliError(
+      `Backfill count mismatch for "${op.index}": listed ${total} source row(s) but accounted for ${pushed + excluded} (${pushed} pushed, ${excluded} excluded by shouldIndex). Aborting before the alias flip \u2014 re-run "headband schema apply" once resolved.`
+    );
+  }
+  await ctx.client.patchAlias(op.index, op.toPhysicalUid);
+  await writeState("applied", null);
+  return {
+    indexUid: op.index,
+    version,
+    schemaHash: schemaHashValue,
+    settingsHash: settingsHashValue,
+    physicalUid: op.toPhysicalUid,
+    status: "applied"
+  };
+}
+async function applyOp(op, ctx, existing, expectedParentHash) {
+  if (op.type === "create-index") {
+    const def = ctx.config.indexes.find((d) => d.name === op.index);
+    await createIndexIdempotent(
+      ctx,
+      op.index,
+      def?.primaryKey ? { primaryKey: def.primaryKey } : void 0
+    );
+    await ctx.client.patchSettings(op.index, op.settings);
+    const next = {
+      indexUid: op.index,
+      version: 1,
+      schemaHash: def ? docShapeHash(def) : "",
+      settingsHash: def ? settingsHash(def) : "",
+      physicalUid: op.physicalUid,
+      status: "applied"
+    };
+    await postState(ctx.client, { ...next, expectedParentHash });
+    return next;
+  }
+  if (op.type === "patch-settings") {
+    if (!existing) {
+      throw new CliError(`Cannot patch settings for "${op.index}": no applied schema state found.`);
+    }
+    await ctx.client.patchSettings(op.index, op.settings);
+    const def = ctx.config.indexes.find((d) => d.name === op.index);
+    const next = {
+      ...existing,
+      settingsHash: def ? settingsHash(def) : existing.settingsHash,
+      status: "applied"
+    };
+    await postState(ctx.client, { ...next, expectedParentHash });
+    return next;
+  }
+  if (op.type === "reindex") {
+    return applyReindex(op, ctx, existing, expectedParentHash);
+  }
+  ctx.io.stdout(
+    `Skipping engine deletion for index "${op.index}" \u2014 not yet supported by the API. Remove it manually with "headband indexes delete ${op.index}" if needed.`
+  );
+  return void 0;
+}
+async function runSchemaApply(deps) {
+  const files = readMigrations(deps.dir);
+  const appliedVersion = readAppliedMarker(deps.dir);
+  const pending = pendingMigrations(files, appliedVersion);
+  if (pending.length === 0) {
+    deps.io.stdout("No pending migrations to apply.");
+    return { appliedFiles: 0, appliedOps: 0 };
+  }
+  const applied = await deps.client.getSchemaState();
+  const existingByIndex = new Map(applied.map((a) => [a.indexUid, a]));
+  const ctx = {
+    config: deps.config,
+    adapter: deps.adapter,
+    client: deps.client,
+    backfillBatchSize: deps.backfillBatchSize ?? DEFAULT_BACKFILL_BATCH_SIZE,
+    io: deps.io
+  };
+  let appliedOps = 0;
+  let appliedFiles = 0;
+  for (const file of pending) {
+    for (const op of file.ops) {
+      if (op.type === "remove-index" && !deps.allowDestructive) {
+        throw new CliError(
+          `Migration ${file.version} contains a destructive "remove-index" op for "${op.index}". Re-run with --allow-destructive to proceed.`
+        );
+      }
+      const existing = existingByIndex.get(op.index);
+      const hasParentHash = Object.prototype.hasOwnProperty.call(file.parentHashes, op.index);
+      const rawParentHash = hasParentHash ? file.parentHashes[op.index] : null;
+      const currentServerHash = existing?.schemaHash ?? "";
+      if (hasParentHash && currentServerHash !== rawParentHash) {
+        throw new CliError(
+          `Migration ${file.version} is stale for index "${op.index}": the server schema state has changed since this migration file was generated. Regenerate with "headband schema generate" before applying.`
+        );
+      }
+      const expectedParentHash = rawParentHash === "" ? null : rawParentHash;
+      try {
+        const next = await applyOp(op, ctx, existing, expectedParentHash);
+        if (next) existingByIndex.set(op.index, next);
+        appliedOps += 1;
+      } catch (err) {
+        if (err instanceof SchemaCasError) {
+          throw new CliError(
+            `Schema state for "${op.index}" was changed by another machine since this migration was generated \u2014 re-run "headband schema diff" and regenerate before retrying. (${err.message})`
+          );
+        }
+        throw err;
+      }
+    }
+    writeAppliedMarker(deps.dir, file.version);
+    appliedFiles += 1;
+    deps.io.stdout(`Applied migration ${file.version}${file.path ? ` (${file.path})` : ""}.`);
+  }
+  return { appliedFiles, appliedOps };
+}
+async function runSchemaStatus(deps) {
+  const applied = await deps.client.getSchemaState();
+  const appliedByUid = new Map(applied.map((a) => [a.indexUid, a]));
+  const rows = deps.config.indexes.map((def) => {
+    const existing = appliedByUid.get(def.name);
+    if (!existing) {
+      return { index: def.name, status: "missing", version: 0, drift: "missing" };
+    }
+    const schemaDrifted = docShapeHash(def) !== existing.schemaHash;
+    const settingsDrifted = settingsHash(def) !== existing.settingsHash;
+    return {
+      index: def.name,
+      status: existing.status,
+      version: existing.version,
+      drift: schemaDrifted ? "schema" : settingsDrifted ? "settings" : "none"
+    };
+  });
+  printTable(deps.io, rows, ["index", "status", "version", "drift"]);
+  const files = readMigrations(deps.dir);
+  const localVersion = readAppliedMarker(deps.dir);
+  const localHead = files.length > 0 ? files[files.length - 1].version : 0;
+  deps.io.stdout(`Local migrations applied: ${localVersion}/${localHead}`);
+  return { indexes: rows, localApplied: localVersion, localHead };
+}
+
+// src/sync.ts
+var import_fs7 = require("fs");
+var import_path8 = require("path");
+var import_crypto = require("crypto");
+var import_pg = require("pg");
+
+// ../sync/src/outbox.ts
+var SAFE_IDENTIFIER = /^[a-zA-Z0-9_]+$/;
+function assertSafeTable(table) {
+  if (!SAFE_IDENTIFIER.test(table)) {
+    throw new Error(`Invalid outbox table name "${table}": must match ${SAFE_IDENTIFIER.source}`);
+  }
+}
+function outboxDDL(table = "headband_outbox") {
+  assertSafeTable(table);
+  return `
+CREATE TABLE IF NOT EXISTS ${table} (
+  id BIGSERIAL PRIMARY KEY,
+  model TEXT NOT NULL,
+  op TEXT NOT NULL,
+  doc_ids JSONB NOT NULL,
+  snapshot JSONB,
+  status TEXT NOT NULL DEFAULT 'pending',
+  attempts INTEGER NOT NULL DEFAULT 0,
+  claimed_at TIMESTAMPTZ,
+  last_error TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS ${table}_status_idx ON ${table} (status);
+`.trim();
+}
+function mapRow(row) {
+  const docIds = typeof row.doc_ids === "string" ? JSON.parse(row.doc_ids) : row.doc_ids;
+  const snapshot = row.snapshot == null ? void 0 : typeof row.snapshot === "string" ? JSON.parse(row.snapshot) : row.snapshot;
+  return {
+    id: row.id,
+    model: row.model,
+    op: row.op,
+    docIds,
+    attempts: row.attempts,
+    snapshot
+  };
+}
+function pgOutboxDriver(exec, opts) {
+  const table = opts?.table ?? "headband_outbox";
+  assertSafeTable(table);
+  const maxAttempts = opts?.maxAttempts ?? 5;
+  return {
+    async claim(limit) {
+      const { rows } = await exec(
+        `UPDATE ${table} SET claimed_at = now() WHERE id IN (SELECT id FROM ${table} WHERE status='pending' AND (claimed_at IS NULL OR claimed_at < now() - interval '5 minutes') ORDER BY id LIMIT $1 FOR UPDATE SKIP LOCKED) RETURNING *`,
+        [limit]
+      );
+      return rows.map(mapRow);
+    },
+    async markDone(ids) {
+      await exec(`UPDATE ${table} SET status = 'done' WHERE id = ANY($1)`, [ids]);
+    },
+    async deadLetter(id, error) {
+      await exec(
+        `UPDATE ${table} SET attempts = attempts + 1, last_error = $2, status = 'dead_letter', claimed_at = NULL WHERE id = $1`,
+        [id, error]
+      );
+    },
+    async markFailed(id, error) {
+      await exec(
+        `UPDATE ${table} SET attempts = attempts + 1, last_error = $2, status = CASE WHEN attempts + 1 >= $3 THEN 'dead_letter' ELSE 'pending' END, claimed_at = NULL WHERE id = $1`,
+        [id, error, maxAttempts]
+      );
+    },
+    async deadLetters(limit) {
+      const { rows } = await exec(
+        `SELECT * FROM ${table} WHERE status = 'dead_letter' ORDER BY id LIMIT $1`,
+        [limit]
+      );
+      return rows.map(mapRow);
+    },
+    async requeue(ids) {
+      await exec(`UPDATE ${table} SET status = 'pending', claimed_at = NULL WHERE id = ANY($1)`, [
+        ids
+      ]);
+    },
+    async depth() {
+      const { rows } = await exec(
+        `SELECT count(*) AS count FROM ${table} WHERE status = 'pending'`
+      );
+      return Number(rows[0]?.count ?? 0);
+    }
+  };
+}
+
+// ../sync/src/resolver.ts
+var toKey = (id) => String(id);
+var idKey = toKey;
+async function resolveDirtyDocs(adapter, config, changes) {
+  const upserts = /* @__PURE__ */ new Map();
+  const deletes = /* @__PURE__ */ new Map();
+  const origins = /* @__PURE__ */ new Map();
+  const addOrigin = (index, id, changeIndex) => {
+    let byId = origins.get(index);
+    if (!byId) {
+      byId = /* @__PURE__ */ new Map();
+      origins.set(index, byId);
+    }
+    const key = toKey(id);
+    const set = byId.get(key);
+    if (set) set.add(changeIndex);
+    else byId.set(key, /* @__PURE__ */ new Set([changeIndex]));
+  };
+  const indexByName = new Map(config.indexes.map((def) => [def.name, def]));
+  const toResolve = /* @__PURE__ */ new Map();
+  const addDelete = (index, id) => {
+    const list = deletes.get(index);
+    if (list) {
+      if (!list.some((x) => toKey(x) === toKey(id))) list.push(id);
+    } else {
+      deletes.set(index, [id]);
+    }
+  };
+  for (const [changeIndex, change] of changes.entries()) {
+    const dirtyDocs = await adapter.fanOut(change);
+    for (const doc of dirtyDocs) {
+      addOrigin(doc.index, doc.id, changeIndex);
+      const def = indexByName.get(doc.index);
+      const isSourceModelDelete = change.op === "delete" && def !== void 0 && def.source === change.model;
+      if (isSourceModelDelete) {
+        addDelete(doc.index, doc.id);
+        continue;
+      }
+      let ids = toResolve.get(doc.index);
+      if (!ids) {
+        ids = /* @__PURE__ */ new Map();
+        toResolve.set(doc.index, ids);
+      }
+      if (!ids.has(toKey(doc.id))) ids.set(toKey(doc.id), doc.id);
+    }
+  }
+  for (const [index, idSet] of toResolve) {
+    const ids = [...idSet.values()];
+    const def = indexByName.get(index);
+    const primaryKey = def?.primaryKey ?? "id";
+    const rows = await adapter.resolveDocs(index, ids);
+    const resolvedKeys = /* @__PURE__ */ new Set();
+    rows.forEach((row, i) => {
+      const rawId = row[primaryKey];
+      if (rawId === void 0) {
+        const contextId = ids[i];
+        throw new Error(
+          `resolveDocs for index '${index}' returned a doc missing primaryKey '${primaryKey}' (id: ${String(contextId)})`
+        );
+      }
+      const id = rawId;
+      resolvedKeys.add(toKey(id));
+      const sourceRow = row.__source ?? row;
+      delete row.__source;
+      if (def?.shouldIndex && !def.shouldIndex(sourceRow)) {
+        addDelete(index, id);
+        return;
+      }
+      const list = upserts.get(index);
+      if (list) {
+        list.push(row);
+      } else {
+        upserts.set(index, [row]);
+      }
+    });
+    for (const id of ids) {
+      if (!resolvedKeys.has(toKey(id))) {
+        addDelete(index, id);
+      }
+    }
+  }
+  return { upserts, deletes, origins };
+}
+
+// ../sync/src/worker.ts
+var DEFAULT_BATCH_SIZE = 100;
+var DEFAULT_IDLE_DELAY_MS = 1e3;
+var MAX_FAILURE_DELAY_MS = 3e4;
+var MAX_PARTIAL_RETRIES = 3;
+async function writeWithPartialRetries(items, keyOf, send, backoff) {
+  const failures = /* @__PURE__ */ new Map();
+  let pending = items;
+  for (let attempt = 0; pending.length > 0; attempt++) {
+    const partial = await send(pending);
+    if (!partial) return failures;
+    const named = new Map(
+      partial.errors.flatMap((e) => e.id === null ? [] : [[e.id, e]])
+    );
+    const pendingKeys = new Set(pending.map(keyOf));
+    const namedHere = [...named.keys()].filter((k) => pendingKeys.has(k)).length;
+    const complete = namedHere >= partial.failed;
+    const retry = [];
+    for (const item of pending) {
+      const key = keyOf(item);
+      const err = named.get(key);
+      if (err) {
+        const message = err.reason ?? partial.message;
+        if (err.retryable && attempt < MAX_PARTIAL_RETRIES) retry.push(item);
+        else failures.set(key, { retryable: err.retryable, message });
+      } else if (!complete) {
+        failures.set(key, {
+          retryable: true,
+          message: `${partial.message} (this document's outcome was not reported)`
+        });
+      }
+    }
+    if (retry.length === 0) return failures;
+    await backoff(attempt + 1);
+    pending = retry;
+  }
+  return failures;
+}
+async function pushResolved(resolved, client, primaryKeyByIndex, backoff) {
+  const failures = /* @__PURE__ */ new Map();
+  let pushed = 0;
+  let deleted = 0;
+  const record = (index, failed) => {
+    if (failed.size === 0) return;
+    const existing = failures.get(index) ?? /* @__PURE__ */ new Map();
+    for (const [key, f] of failed) existing.set(key, f);
+    failures.set(index, existing);
+  };
+  for (const [index, docs] of resolved.upserts) {
+    const primaryKey = primaryKeyByIndex.get(index);
+    const failed = await writeWithPartialRetries(
+      docs,
+      (doc) => idKey(doc[primaryKey ?? "id"]),
+      async (batch) => (await client.bulkPush(index, batch, primaryKey))?.partialFailure,
+      backoff
+    );
+    record(index, failed);
+    pushed += docs.length - failed.size;
+  }
+  for (const [index, ids] of resolved.deletes) {
+    const failed = await writeWithPartialRetries(
+      ids,
+      idKey,
+      async (batch) => (await client.deleteDocs(index, batch))?.partialFailure,
+      backoff
+    );
+    record(index, failed);
+    deleted += ids.length - failed.size;
+  }
+  return { failures, pushed, deleted };
+}
+function rowOutcomes(rows, resolved, failures) {
+  const failuresByRow = /* @__PURE__ */ new Map();
+  for (const [index, failed] of failures) {
+    for (const [key, failure] of failed) {
+      for (const changeIndex of resolved.origins.get(index)?.get(key) ?? []) {
+        const list = failuresByRow.get(changeIndex) ?? [];
+        list.push(failure);
+        failuresByRow.set(changeIndex, list);
+      }
+    }
+  }
+  const done = [];
+  const retry = [];
+  const deadLetter = [];
+  rows.forEach((row, changeIndex) => {
+    const rowFailures = failuresByRow.get(changeIndex);
+    if (!rowFailures) {
+      done.push(row.id);
+      return;
+    }
+    const permanent = rowFailures.find((f) => !f.retryable);
+    if (permanent) deadLetter.push([row.id, permanent.message]);
+    else retry.push([row.id, rowFailures[0].message]);
+  });
+  return { done, retry, deadLetter };
+}
+function defaultSleep3(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function runSyncWorker(opts) {
+  const {
+    config,
+    adapter,
+    client,
+    outbox,
+    budgetMs,
+    loop = false,
+    idleDelayMs = DEFAULT_IDLE_DELAY_MS,
+    failureDelayMs = idleDelayMs,
+    batchSize = DEFAULT_BATCH_SIZE,
+    stopSignal,
+    now = Date.now,
+    sleep = defaultSleep3,
+    onHeartbeat
+  } = opts;
+  const primaryKeyByIndex = new Map(config.indexes.map((def) => [def.name, def.primaryKey]));
+  const report = {
+    drained: 0,
+    pushed: 0,
+    deleted: 0,
+    deadLettered: 0,
+    outboxDepth: 0
+  };
+  const start = now();
+  const budgetExceeded = () => budgetMs !== void 0 && now() - start >= budgetMs;
+  let consecutiveFailures = 0;
+  for (; ; ) {
+    if (budgetExceeded()) break;
+    if (stopSignal && stopSignal()) break;
+    const rows = await outbox.claim(batchSize);
+    if (rows.length === 0) {
+      if (!loop) break;
+      await sleep(idleDelayMs);
+      continue;
+    }
+    const changes = rows.map((row) => ({
+      model: row.model,
+      op: row.op,
+      ids: row.docIds,
+      snapshot: row.snapshot
+    }));
+    try {
+      const resolved = await resolveDirtyDocs(adapter, config, changes);
+      const { failures, pushed, deleted } = await pushResolved(
+        resolved,
+        client,
+        primaryKeyByIndex,
+        (attempt) => sleep(Math.min(failureDelayMs * 2 ** (attempt - 1), MAX_FAILURE_DELAY_MS))
+      );
+      report.pushed += pushed;
+      report.deleted += deleted;
+      const outcome = rowOutcomes(rows, resolved, failures);
+      if (outcome.done.length > 0) await outbox.markDone(outcome.done);
+      for (const [id, message] of outcome.deadLetter) {
+        if (outbox.deadLetter) await outbox.deadLetter(id, message);
+        else await outbox.markFailed(id, message);
+      }
+      for (const [id, message] of outcome.retry) {
+        await outbox.markFailed(id, message);
+      }
+      report.drained += outcome.done.length;
+      report.deadLettered += outcome.deadLetter.length + outcome.retry.length;
+      if (outcome.retry.length > 0) {
+        consecutiveFailures += 1;
+        await sleep(
+          Math.min(failureDelayMs * 2 ** (consecutiveFailures - 1), MAX_FAILURE_DELAY_MS)
+        );
+      } else {
+        consecutiveFailures = 0;
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      for (const row of rows) {
+        await outbox.markFailed(row.id, message);
+      }
+      report.deadLettered += rows.length;
+      consecutiveFailures += 1;
+      const delay = Math.min(failureDelayMs * 2 ** (consecutiveFailures - 1), MAX_FAILURE_DELAY_MS);
+      await sleep(delay);
+    }
+    if (onHeartbeat) {
+      try {
+        await onHeartbeat({ ...report });
+      } catch (err) {
+        console.error("[headband] heartbeat failed:", err);
+      }
+    }
+  }
+  report.outboxDepth = await outbox.depth();
+  if (onHeartbeat) {
+    try {
+      await onHeartbeat({ ...report });
+    } catch (err) {
+      console.error("[headband] heartbeat failed:", err);
+    }
+  }
+  return report;
+}
+
+// src/sync.ts
+var WORKER_VERSION = "1";
+var DEFAULT_DEAD_LETTER_LIMIT = 1e3;
+var RECONCILE_PAGE_SIZE = 500;
+var OUTBOX_SQL_RELATIVE_PATH = (0, import_path8.join)("headband", "outbox.sql");
+var DOCKERFILE_NAME = "Dockerfile.headband-sync";
+var DOCKERFILE_CONTENT = `FROM node:22-slim
+WORKDIR /app
+COPY . .
+RUN npm ci
+CMD ["npx", "headband", "sync", "worker"]
+`;
+var COMPOSE_SNIPPET = `services:
+  headband-sync:
+    build:
+      context: .
+      dockerfile: ${DOCKERFILE_NAME}
+    env_file: .env
+    restart: unless-stopped
+`;
+function resolveDatabaseUrl(env = process.env) {
+  const url = env.DATABASE_URL || env.HEADBAND_DATABASE_URL;
+  if (!url) {
+    throw new CliError(
+      "No database connection found for the sync outbox. Set DATABASE_URL (or HEADBAND_DATABASE_URL) in your environment."
+    );
+  }
+  return url;
+}
+function buildPgOutbox(connectionString, opts) {
+  const pool = new import_pg.Pool({ connectionString });
+  const exec = async (sqlText, params) => {
+    const result = await pool.query(sqlText, params);
+    return { rows: result.rows };
+  };
+  return { outbox: pgOutboxDriver(exec, opts), close: () => pool.end() };
+}
+function runSyncInit(deps) {
+  const ddl = outboxDDL(deps.table);
+  deps.io.stdout(ddl);
+  if (deps.write) {
+    const path2 = (0, import_path8.join)(deps.cwd ?? process.cwd(), OUTBOX_SQL_RELATIVE_PATH);
+    (0, import_fs7.mkdirSync)((0, import_path8.join)(deps.cwd ?? process.cwd(), "headband"), { recursive: true });
+    (0, import_fs7.writeFileSync)(path2, `${ddl}
+`);
+    deps.io.stdout(`Wrote ${path2}`);
+  }
+  return ddl;
+}
+var SHUTDOWN_SIGNALS = ["SIGINT", "SIGTERM"];
+async function runSyncWorkerCmd(deps) {
+  const schemaHashes = Object.fromEntries(
+    deps.config.indexes.map((def) => [def.name, docShapeHash(def)])
+  );
+  const workerVersion = deps.workerVersion ?? WORKER_VERSION;
+  let heartbeats = 0;
+  const proc = deps.process ?? process;
+  let stopRequested = false;
+  const handleShutdown = () => {
+    if (stopRequested) return;
+    stopRequested = true;
+    deps.io.stderr("shutting down after current batch\u2026");
+  };
+  for (const signal of SHUTDOWN_SIGNALS) {
+    proc.once(signal, handleShutdown);
+  }
+  try {
+    const report = await runSyncWorker({
+      config: deps.config,
+      adapter: deps.adapter,
+      client: deps.client,
+      outbox: deps.outbox,
+      loop: deps.loop ?? !deps.budgetMs,
+      budgetMs: deps.budgetMs,
+      batchSize: deps.batchSize,
+      idleDelayMs: deps.idleDelayMs,
+      failureDelayMs: deps.failureDelayMs,
+      now: deps.now,
+      sleep: deps.sleep,
+      stopSignal: () => stopRequested,
+      onHeartbeat: async (r) => {
+        heartbeats += 1;
+        await deps.client.reportRun({
+          connectorSlug: "orm-sync",
+          status: r.deadLettered > 0 ? "error" : "success",
+          count: r.pushed + r.deleted,
+          externalRunId: (0, import_crypto.randomUUID)(),
+          details: { outboxDepth: r.outboxDepth, workerVersion, schemaHashes }
+        });
+        if (deps.reconcileEvery && deps.onReconcileTick && heartbeats % deps.reconcileEvery === 0) {
+          await deps.onReconcileTick();
+        }
+      }
+    });
+    deps.io.stdout(
+      `Drained ${report.drained} row(s): pushed ${report.pushed}, deleted ${report.deleted}, dead-lettered ${report.deadLettered}. Outbox depth: ${report.outboxDepth}.`
+    );
+    return report;
+  } finally {
+    for (const signal of SHUTDOWN_SIGNALS) {
+      proc.removeListener(signal, handleShutdown);
+    }
+  }
+}
+async function collectAllIds(adapter, model) {
+  const ids = [];
+  let cursor = null;
+  for (; ; ) {
+    const page = await adapter.listIds(model, cursor, RECONCILE_PAGE_SIZE);
+    ids.push(...page.ids);
+    if (page.nextCursor === null || page.ids.length === 0) break;
+    cursor = page.nextCursor;
+  }
+  return ids;
+}
+async function runSyncReconcile(deps) {
+  const ormSchema = deps.adapter.introspect();
+  const rows = [];
+  for (const def of deps.config.indexes) {
+    const ids = await collectAllIds(deps.adapter, def.source);
+    const sourceCount = ids.length;
+    let remoteCount = -1;
+    try {
+      const stats = await deps.getStats(def.name);
+      remoteCount = stats.numDocuments ?? 0;
+    } catch (err) {
+      deps.io.stderr(
+        `Could not fetch stats for "${def.name}": ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    const cursorAware = Boolean(ormSchema.models[def.source]?.columns?.updatedAt);
+    const drift = remoteCount === -1 ? 0 : sourceCount - remoteCount;
+    rows.push({ index: def.name, sourceCount, remoteCount, drift, cursorAware });
+    if (deps.fix && drift !== 0) {
+      const docs = await deps.adapter.resolveDocs(def.name, ids);
+      const toPush = docs.filter((doc) => {
+        const sourceRow = doc.__source ?? doc;
+        return !def.shouldIndex || def.shouldIndex(sourceRow);
+      });
+      for (const doc of toPush) delete doc.__source;
+      if (toPush.length > 0) {
+        const result = await deps.client.bulkPush(def.name, toPush, def.primaryKey);
+        if (result?.partialFailure) {
+          throw new CliError(
+            `Repair push for "${def.name}" was incomplete: ${partialFailureSummary(result.partialFailure)}.`
+          );
+        }
+      }
+    }
+  }
+  printTable(
+    deps.io,
+    rows.map((r) => ({ ...r, remoteCount: r.remoteCount === -1 ? "unknown" : r.remoteCount })),
+    ["index", "sourceCount", "remoteCount", "drift", "cursorAware"]
+  );
+  return rows;
+}
+async function runSyncRetryDeadLetters(deps) {
+  const rows = await deps.outbox.deadLetters(deps.limit ?? DEFAULT_DEAD_LETTER_LIMIT);
+  if (rows.length === 0) {
+    deps.io.stdout("No dead-lettered rows to retry.");
+    return 0;
+  }
+  await deps.outbox.requeue(rows.map((row) => row.id));
+  deps.io.stdout(`Requeued ${rows.length} dead-lettered row(s).`);
+  return rows.length;
+}
+function runSyncScaffoldDocker(deps) {
+  const path2 = (0, import_path8.join)(deps.cwd, DOCKERFILE_NAME);
+  if ((0, import_fs7.existsSync)(path2) && !deps.force) {
+    throw new CliError(`${DOCKERFILE_NAME} already exists at ${path2}. Pass --force to overwrite.`);
+  }
+  (0, import_fs7.writeFileSync)(path2, DOCKERFILE_CONTENT);
+  deps.io.stdout(`Wrote ${path2}`);
+  deps.io.stdout("Add this service to your docker-compose.yml:");
+  deps.io.stdout(COMPOSE_SNIPPET);
+  return path2;
+}
+
+// src/sync-indexes.ts
+var import_fs9 = require("fs");
+
+// src/sync-sources.ts
+var import_fs8 = require("fs");
+var import_pg2 = require("pg");
+
+// ../../src/lib/sync/copy.ts
+var BROAD_ROLE_CONSENT = "BataDB sources currently use a broad role: it can read and write every table in this database. Sync only reads, inside read-only transactions, but the role itself is not limited. A narrower replication role replaces it when BataDB ships one.";
+
+// src/scram.ts
+var import_node_crypto2 = require("crypto");
+var SCRAM_ITERATIONS = 4096;
+var TOKEN = ":'sync_password'";
+var VERIFIER_RE = /^SCRAM-SHA-256\$[1-9][0-9]*:[A-Za-z0-9+/]+={0,2}\$[A-Za-z0-9+/]+={0,2}:[A-Za-z0-9+/]+={0,2}$/;
+function scramVerifier(password, salt = (0, import_node_crypto2.randomBytes)(16), iterations = SCRAM_ITERATIONS) {
+  if (!/^[\x20-\x7e]{1,1024}$/.test(password))
+    throw new Error("The password must be printable ASCII.");
+  const salted = (0, import_node_crypto2.pbkdf2Sync)(password, salt, iterations, 32, "sha256");
+  const clientKey = (0, import_node_crypto2.createHmac)("sha256", salted).update("Client Key").digest();
+  const storedKey = (0, import_node_crypto2.createHash)("sha256").update(clientKey).digest();
+  const serverKey = (0, import_node_crypto2.createHmac)("sha256", salted).update("Server Key").digest();
+  return `SCRAM-SHA-256$${iterations}:${salt.toString("base64")}$${storedKey.toString("base64")}:${serverKey.toString("base64")}`;
+}
+function newSyncPassword() {
+  return (0, import_node_crypto2.randomBytes)(24).toString("base64url");
+}
+function replaceToken(sql, value) {
+  const parts = sql.split(TOKEN);
+  if (parts.length !== 2)
+    throw new Error("The setup SQL must contain the password token exactly once.");
+  return `${parts[0]}'${value}'${parts[1]}`;
+}
+function withVerifier(sql, verifier) {
+  if (!VERIFIER_RE.test(verifier))
+    throw new Error("withVerifier takes a SCRAM-SHA-256 verifier, never a plain password.");
+  return replaceToken(sql, verifier);
+}
+function withoutPasswordChange(sql) {
+  return replaceToken(sql, "");
+}
+
+// src/sync-sources.ts
+var SOURCE_USAGE = [
+  "Usage:",
+  "  headband sync source add <name> [--db-url <url>] [--tls-mode verify-full|require] [--ca-file <pem>] [--json]",
+  "  headband sync source add <name> --kind batadb --batadb-project <id> --batadb-branch <id> --batadb-compute <id> --accept-broad-role",
+  "  headband sync source list [--json]",
+  "  headband sync source show <id> [--json]",
+  "  headband sync source test <id> [--json]",
+  "  headband sync source setup-sql <id> [--provider generic|rds|batadb] [--json]",
+  "  headband sync source setup <id> [--owner-url <url>] [--provider generic|rds|batadb] [--yes] [--json]",
+  "  headband sync source set-ca <id> (--ca-file <pem> | --none) [--tls-mode verify-full|require] [--json]",
+  "  headband sync source remove <id> [--yes] [--json]",
+  "",
+  "The source URL can come from HEADBAND_SYNC_DB_URL and the owner URL from HEADBAND_SYNC_OWNER_URL,",
+  "which keeps them out of your shell history. Leave the password out of the source URL: setup makes one.",
+  "A BataDB API key is read from HEADBAND_BATADB_API_KEY only.",
+  "",
+  "--ca-file names a PEM file of CA certificates the source's certificate is verified against, for a",
+  "provider whose CA is not in the system roots. It needs --tls-mode verify-full, the default. On a",
+  "require source, set-ca --ca-file <pem> --tls-mode verify-full changes both in one step.",
+  "",
+  "setup runs the SQL on your machine as the tables' owner, in one transaction. The owner URL never",
+  "leaves this machine. When the SQL creates or changes the Sync role, the owner URL's user must be",
+  "another role. Without sslmode in the owner URL, setup uses TLS and verifies the server's",
+  "certificate, except on localhost."
+].join("\n");
+function readCaFile(deps, file) {
+  let text;
+  try {
+    text = (deps.readFile ?? ((p) => (0, import_fs8.readFileSync)(p, "utf8")))(file);
+  } catch {
+    throw new CliError("Cannot read the --ca-file.");
+  }
+  if (/PRIVATE KEY/.test(text)) {
+    throw new CliError(
+      "The --ca-file holds a private key. Give only the CA certificates. Nothing was sent."
+    );
+  }
+  return text;
+}
+var MIN_SERVER_VERSION_NUM = 14e4;
+var OwnerSqlError = class extends CliError {
+  constructor(message, opts) {
+    super(message);
+    this.name = "OwnerSqlError";
+    this.sqlstate = opts.sqlstate;
+    this.hint = opts.hint;
+    this.stage = opts.stage;
+    this.nothingChanged = opts.nothingChanged;
+  }
+};
+var SESSION_PARAMS = [
+  "options",
+  "statement_timeout",
+  "lock_timeout",
+  "idle_in_transaction_session_timeout",
+  "replication"
+];
+var TLS_PARAMS = ["ssl", "sslmode", "sslcert", "sslkey", "sslrootcert", "sslnegotiation"];
+var POOLER_HOST_RE = /pooler|pgbouncer|\.proxy-/;
+var POOLER_PORTS = /* @__PURE__ */ new Set([6543, 6432, 25061]);
+var LOOPBACK = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1"]);
+var URL_IN_TEXT_RE = /postgres(?:ql)?:\/\/\S*/gi;
+var VERIFIER_IN_TEXT_RE = /SCRAM-SHA-256\$\S*/g;
+function decodePart(part) {
+  try {
+    return decodeURIComponent(part);
+  } catch {
+    return part;
+  }
+}
+function parseOwnerUrl(ownerUrl, env) {
+  let url;
+  try {
+    url = new URL(ownerUrl);
+  } catch {
+    throw new CliError("The owner URL is not a valid postgres:// URL.");
+  }
+  if (url.protocol !== "postgres:" && url.protocol !== "postgresql:") {
+    throw new CliError("The owner URL must start with postgres:// or postgresql://.");
+  }
+  for (const name of SESSION_PARAMS) {
+    if (url.searchParams.has(name)) {
+      throw new CliError(
+        `Remove ${name} from the owner URL: setup sets nothing on the session, and poolers refuse it.`
+      );
+    }
+  }
+  const host = (url.searchParams.get("host") || decodePart(url.hostname)).replace(/^\[|\]$/g, "").toLowerCase() || "localhost";
+  const port = Number(url.searchParams.get("port") || url.port || 5432);
+  const database = decodePart(url.pathname.replace(/^\//, "")) || null;
+  const user = url.searchParams.get("user") || decodePart(url.username) || env.PGUSER || env.USER || env.USERNAME || null;
+  return { url, host, port, database, user };
+}
+function ownerClientConfig(ownerUrl, env = process.env) {
+  const target = parseOwnerUrl(ownerUrl, env);
+  for (const name of ["PGOPTIONS", "PGREPLICATION"]) {
+    if (env[name]) {
+      throw new CliError(
+        `${name} is set in your environment. Unset it: setup sets nothing on the session.`
+      );
+    }
+  }
+  const urlChoosesTls = TLS_PARAMS.some((p) => target.url.searchParams.has(p)) || Boolean(env.PGSSLMODE);
+  const local = target.host.startsWith("/") || LOOPBACK.has(target.host);
+  return {
+    connectionString: ownerUrl,
+    connectionTimeoutMillis: 15e3,
+    keepAlive: true,
+    ...urlChoosesTls || local ? {} : { ssl: true }
+  };
+}
+function looksLikePooler(host, port) {
+  return POOLER_HOST_RE.test(host) || POOLER_PORTS.has(port);
+}
+function scrubSecrets(text, secrets) {
+  let out = text;
+  const known = secrets.filter((s) => Boolean(s)).sort((a, b) => b.length - a.length);
+  for (const s of known) out = out.split(s).join("[hidden]");
+  return out.replace(URL_IN_TEXT_RE, "[connection URL]").replace(VERIFIER_IN_TEXT_RE, "[verifier]");
+}
+function ownerSecrets(ownerUrl, env) {
+  const out = [ownerUrl, env.PGPASSWORD ?? ""];
+  try {
+    const u = new URL(ownerUrl);
+    out.push(u.password, decodePart(u.password), u.searchParams.get("password") ?? "");
+  } catch {
+  }
+  return out;
+}
+function checkServerVersion(versionNum) {
+  if (!Number.isInteger(versionNum) || versionNum < MIN_SERVER_VERSION_NUM) {
+    const major = Number.isInteger(versionNum) ? Math.floor(versionNum / 1e4) : "unknown";
+    throw new OwnerSqlError(
+      `This server runs Postgres ${major}. Sync needs Postgres 14 or later.`,
+      { stage: "connect", nothingChanged: true }
+    );
+  }
+}
+function connectHint(message) {
+  if (/certificate|self[- ]signed|altnames/i.test(message)) {
+    return "Setup verifies the server's certificate, as sslmode=verify-full does. Trust your provider's CA with NODE_EXTRA_CA_CERTS=<file>, or add sslrootcert=<file> to the owner URL.";
+  }
+  if (/does not support SSL/i.test(message)) {
+    return "Add sslmode=disable to the owner URL only if this connection runs on a network you trust.";
+  }
+  return void 0;
+}
+function toOwnerSqlError(err, stage, secrets) {
+  const e = typeof err === "object" && err !== null ? err : {};
+  const fromServer = typeof e.code === "string" && /^[0-9A-Z]{5}$/.test(e.code) && typeof e.severity === "string";
+  const message = scrubSecrets(
+    // Node's AggregateError (both addresses of localhost refused) has an empty message.
+    typeof e.message === "string" && e.message ? e.message : String(e.errors?.[0]?.message ?? (typeof e.code === "string" ? e.code : err)),
+    secrets
+  );
+  const serverHint = typeof e.hint === "string" && e.hint ? scrubSecrets(e.hint, secrets) : void 0;
+  return new OwnerSqlError(message, {
+    sqlstate: fromServer ? e.code : void 0,
+    hint: serverHint ?? (stage === "connect" ? connectHint(message) : void 0),
+    stage,
+    // An ERROR aborts the transaction, and the rollback follows. A FATAL or a dropped connection
+    // mid-run is unknown: a FATAL (57P01 waiting for a synchronous standby) can follow a local commit.
+    nothingChanged: stage === "connect" || fromServer && e.severity === "ERROR"
+  });
+}
+async function runOwnerSqlWithPg(ownerUrl, sqlText) {
+  const config = ownerClientConfig(ownerUrl);
+  const secrets = ownerSecrets(ownerUrl, process.env);
+  let client;
+  try {
+    client = new import_pg2.Client(config);
+  } catch (err) {
+    throw toOwnerSqlError(err, "connect", secrets);
+  }
+  client.on("error", () => void 0);
+  let connected = false;
+  let stage = "connect";
+  try {
+    await client.connect();
+    connected = true;
+    await client.query("BEGIN");
+    await client.query("SET LOCAL statement_timeout = '60s'");
+    const version = await client.query(
+      "SELECT current_setting('server_version_num')::int AS num"
+    );
+    checkServerVersion(Number(version.rows[0]?.num));
+    stage = "run";
+    await client.query(sqlText);
+    await client.query("COMMIT");
+  } catch (err) {
+    if (connected) await client.query("ROLLBACK").catch(() => void 0);
+    throw err instanceof OwnerSqlError ? err : toOwnerSqlError(err, stage, secrets);
+  } finally {
+    await client.end().catch(() => void 0);
+  }
+}
+function friendlySyncError(err) {
+  if (err instanceof ApiError) {
+    if (err.status === 404 && err.code === "not_found") {
+      throw new CliError("Sync is not enabled for this organization yet.");
+    }
+    if (err.status === 403 && err.code === "permission_denied") {
+      throw new CliError(
+        "This CLI key cannot manage Sync. Run headband login again to get a key that can."
+      );
+    }
+  }
+  throw err;
+}
+var SOURCE_ID_RE = /^src_[a-z0-9]{12}$/;
+var SOURCE_NAME_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+var PROVIDERS = ["generic", "rds", "batadb"];
+var TLS_MODES = ["verify-full", "require"];
+var str = (flags, name) => typeof flags[name] === "string" ? flags[name] : void 0;
+var sourcePath = (id, suffix = "") => `/v1/sync/sources/${encodeURIComponent(id)}${suffix}`;
+var setupSqlPath = (id, provider) => sourcePath(id, `/setup-sql${provider ? `?provider=${encodeURIComponent(provider)}` : ""}`);
+var mark = (ok) => ok ? "ok  " : "FAIL";
+var plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+function choiceFlag(flags, name, choices) {
+  const value = str(flags, name);
+  if (value !== void 0 && !choices.includes(value)) {
+    throw new CliError(
+      `${name} must be ${choices.slice(0, -1).join(", ")} or ${choices[choices.length - 1]}.`
+    );
+  }
+  return value;
+}
+function checkedId(value, re, shape, listCommand) {
+  if (!re.test(value)) {
+    throw new CliError(
+      `Expected ${shape}, and got something else. Run ${listCommand} to see them.`
+    );
+  }
+  return value;
+}
+var SOURCE_ID_SHAPE = "a source id like src_ followed by 12 lowercase letters or digits";
+var SOURCE_ID_PATTERN = SOURCE_ID_RE;
+function requireSourceId(args) {
+  const id = args[1];
+  if (!id) throw new CliError("Missing source id (headband sync source list shows them).");
+  return checkedId(id, SOURCE_ID_RE, SOURCE_ID_SHAPE, "headband sync source list");
+}
+function printChecks(io, checks) {
+  const width = Math.max(4, ...checks.map((c) => c.name.length));
+  for (const c of checks) io.stdout(`${mark(c.ok)}  ${c.name.padEnd(width)}  ${c.detail}`);
+}
+function lastTested(s) {
+  if (!s.lastTest) return "never";
+  const failed = s.lastTest.checks.filter((c) => !c.ok).length;
+  return failed === 0 ? `passed ${s.lastTest.at}` : `${failed} failed ${s.lastTest.at}`;
+}
+function roleKey(url) {
+  try {
+    const u = new URL(url);
+    const port = u.port ? Number(u.port) : 5432;
+    return {
+      host: u.hostname.toLowerCase().replace(/^\[|\]$/g, ""),
+      port,
+      username: decodeURIComponent(u.username)
+    };
+  } catch {
+    return null;
+  }
+}
+async function runAdd(args, flags, deps, env) {
+  const { io, client } = deps;
+  const name = args[1];
+  if (!name) throw new CliError("Missing source name.");
+  if (!SOURCE_NAME_RE.test(name)) {
+    throw new CliError(
+      "A source name is 1 to 64 lowercase letters, digits, _ or -, starting with a letter or digit."
+    );
+  }
+  const url = str(flags, "--db-url") ?? env.HEADBAND_SYNC_DB_URL;
+  if (!url) {
+    throw new CliError("Give the source's connection URL with --db-url or HEADBAND_SYNC_DB_URL.");
+  }
+  const kind = str(flags, "--kind") ?? "postgres";
+  if (kind !== "postgres" && kind !== "batadb")
+    throw new CliError("--kind must be postgres or batadb.");
+  const ids = {
+    projectId: str(flags, "--batadb-project"),
+    branchId: str(flags, "--batadb-branch"),
+    computeId: str(flags, "--batadb-compute")
+  };
+  const body = { name, url };
+  const tlsMode = choiceFlag(flags, "--tls-mode", TLS_MODES);
+  if (tlsMode) body.tlsMode = tlsMode;
+  const caFile = str(flags, "--ca-file");
+  if (caFile) body.tlsCaPem = readCaFile(deps, caFile);
+  if (kind === "batadb") {
+    if (flags["--accept-broad-role"] !== true) {
+      io.stderr(BROAD_ROLE_CONSENT);
+      throw new CliError(
+        "A BataDB source needs your consent to that role: add --accept-broad-role."
+      );
+    }
+    if (!ids.projectId || !ids.branchId || !ids.computeId) {
+      throw new CliError(
+        "A BataDB source needs --batadb-project, --batadb-branch and --batadb-compute."
+      );
+    }
+    body.kind = "batadb";
+    body.batadb = {
+      ...ids,
+      acceptBroadRole: true,
+      ...env.HEADBAND_BATADB_API_KEY ? { apiKey: env.HEADBAND_BATADB_API_KEY } : {}
+    };
+  } else {
+    if (ids.projectId || ids.branchId || ids.computeId) {
+      throw new CliError("The --batadb-* options are for --kind batadb.");
+    }
+    const key = roleKey(url);
+    if (key) {
+      const existing = (await client.get("/v1/sync/sources")).data;
+      const other = existing.find(
+        (s2) => s2.kind === "postgres" && s2.host === key.host && s2.port === key.port && s2.username === key.username
+      );
+      if (other) {
+        throw new CliError(
+          `Source ${other.id} (${other.name}) already uses the user ${key.username} on ${key.host}:${key.port}. Each source needs its own role, and setup never changes a role made for another source: give this source a user name no other source uses on that server.`
+        );
+      }
+    }
+  }
+  const res = await client.post("/v1/sync/sources", body);
+  if (flags["--json"] === true) return printJson(io, res);
+  const s = res.data;
+  io.stdout(
+    `Created source ${s.id} (${s.name}): ${s.host}:${s.port}/${s.database} as ${s.username}.`
+  );
+  if (s.kind === "postgres" && s.hasPassword) {
+    io.stderr(
+      `Note: the URL has a password, so setup keeps it and makes no new one. The setup SQL creates a missing role only with a password, so ${s.username} must already be Headband's role for this source. Otherwise run the setup SQL yourself with that password (headband sync source setup-sql ${s.id} shows the psql command), or add the source again without a password.`
+    );
+  }
+  io.stdout("Next: create the role and publication as the tables' owner:");
+  io.stdout(`  headband sync source setup ${s.id} --owner-url <owner URL>`);
+  io.stdout(`or print the SQL to run yourself: headband sync source setup-sql ${s.id}`);
+}
+function roleEffect(user, provider, mode) {
+  const attrs = provider === "rds" ? "LOGIN and membership in rds_replication" : "LOGIN REPLICATION";
+  if (mode === "none") return `creates and changes no role: BataDB manages ${user}.`;
+  const guard = `Any other role named ${user} stops the SQL, and nothing changes.`;
+  if (mode === "new") {
+    return `creates the role ${user} (${attrs}) with a new password, or, when ${user} exists and Headband Sync created it for this source, gives it that new password and ${attrs}. ${guard}`;
+  }
+  return `creates no role and keeps the password Headband has: it gives ${user} ${attrs} only when Headband Sync created ${user} for this source. A missing role stops the SQL too. ${guard}`;
+}
+function confirmQuestion(owner, user, pub, mode) {
+  const as = `Run it now as ${owner}?`;
+  if (mode === "none")
+    return `${as} It creates or updates the publication ${pub} and changes no role.`;
+  if (mode === "new") {
+    return `${as} It creates the role ${user}, or updates ${user} only if Headband Sync created it for this source.`;
+  }
+  return `${as} It creates no role, and updates ${user} only if Headband Sync created it for this source.`;
+}
+function ownerFailure(err, ctx, secrets) {
+  const info = err instanceof OwnerSqlError ? err : void 0;
+  const reason = scrubSecrets(err instanceof Error ? err.message : String(err), secrets);
+  const lines = [
+    info?.stage === "connect" ? `Could not run the setup SQL as the owner: ${reason}` : `The setup SQL failed on your database: ${reason}`
+  ];
+  let advice;
+  const state = info?.sqlstate;
+  if (state === "42710" && reason.includes("was not created by Headband Sync")) {
+    advice = `Sync changes only a role it created for this source, so ${ctx.user} stays as it is. Each source needs its own role: use a user name that does not exist on this server yet (add a new source with it), then run its setup.`;
+  } else if (state === "42710" && reason.includes("carries the Headband Sync marker")) {
+    advice = `${ctx.user} is Headband's role for this source, but another role is its member or admin, or it has SUPERUSER, CREATEROLE or BYPASSRLS. It needs none of these: remove them, then run setup again.`;
+  } else if (state === "22023" && reason.includes("does not exist yet") && ctx.mode === "keep") {
+    advice = `This source's URL has a password, so setup keeps it and makes no new one, and the SQL creates a missing role only with a password. Run the setup SQL yourself with psql and that password (headband sync source setup-sql ${ctx.id} shows the command), or add the source again without a password so setup makes one.`;
+  } else if (state === "42501") {
+    advice = "Run setup as the tables' owner, a role that can also create roles and publications.";
+  } else if (state === "55P03") {
+    advice = "Another transaction held a lock on one of these tables for over 5 seconds. Run setup again when it is quiet.";
+  }
+  if (advice) lines.push(advice);
+  else if (info?.hint) lines.push(`Hint: ${scrubSecrets(info.hint, secrets)}`);
+  if (info && !info.nothingChanged) {
+    lines.push(
+      "The connection failed while the SQL ran. Postgres rolls back a transaction that does not commit, and Headband was not updated. Run setup again: it is safe to repeat."
+    );
+  } else if (info?.stage === "connect") {
+    lines.push("Nothing changed on your database or in Headband.");
+  } else {
+    lines.push("Nothing changed: the transaction rolled back, and Headband was not updated.");
+  }
+  return new CliError(lines.join("\n"));
+}
+async function runSetup(args, flags, deps, env) {
+  const { client } = deps;
+  const json = flags["--json"] === true;
+  const io = json ? { stdout: deps.io.stderr, stderr: deps.io.stderr } : deps.io;
+  const id = requireSourceId(args);
+  const ownerUrl = str(flags, "--owner-url") ?? env.HEADBAND_SYNC_OWNER_URL;
+  if (!ownerUrl) {
+    throw new CliError(
+      "Give the tables' owner URL with --owner-url or HEADBAND_SYNC_OWNER_URL. It never leaves this machine."
+    );
+  }
+  ownerClientConfig(ownerUrl, env);
+  const owner = parseOwnerUrl(ownerUrl, env);
+  const provider = choiceFlag(flags, "--provider", PROVIDERS);
+  const source = (await client.get(sourcePath(id))).data;
+  if (source.state === "deleting") throw new CliError(`Source ${id} is being removed.`);
+  const setup = (await client.get(setupSqlPath(id, provider))).data;
+  if (setup.needsPassword && owner.user === source.username) {
+    throw new CliError(
+      `The owner URL logs in as ${source.username}, the user Sync reads with. The setup SQL creates or updates that role, so run it as the tables' owner, a different role.`
+    );
+  }
+  if (looksLikePooler(owner.host, owner.port)) {
+    io.stderr(
+      `Warning: the owner host (${owner.host}:${owner.port}) looks like a connection pooler. Setup runs one transaction and sets nothing on the session, but if the pooler refuses it, use the database's direct host.`
+    );
+  }
+  if (owner.host !== source.host) {
+    io.stderr(
+      `Note: the owner URL's host (${owner.host}) differs from the source's (${source.host}). Make sure both reach the same database.`
+    );
+  }
+  let password = null;
+  let verifier = null;
+  let mode;
+  let sqlText;
+  try {
+    if (!setup.needsPassword) {
+      mode = "none";
+      sqlText = setup.sql;
+    } else if (source.hasPassword) {
+      mode = "keep";
+      sqlText = withoutPasswordChange(setup.sql);
+    } else {
+      mode = "new";
+      password = (deps.newPassword ?? newSyncPassword)();
+      verifier = scramVerifier(password);
+      sqlText = withVerifier(setup.sql, verifier);
+    }
+  } catch {
+    throw new CliError(
+      "Headband's setup SQL is not in the shape this CLI expects. Update @headband/cli and try again."
+    );
+  }
+  const ownerName = owner.user ?? "the owner URL's user";
+  const where = `${owner.host}:${owner.port}${owner.database ? `/${owner.database}` : ""}`;
+  io.stdout(`Setup runs Headband's SQL on ${where} as ${ownerName}, in one transaction. It:`);
+  io.stdout(`  - ${roleEffect(source.username, setup.provider, mode)}`);
+  if (setup.needsPassword && setup.tables.length > 0) {
+    io.stdout(
+      `  - grants ${source.username} SELECT on ${setup.tables.join(", ")}, and USAGE on their schemas.`
+    );
+  }
+  io.stdout(
+    setup.tables.length > 0 ? `  - creates the publication ${source.publicationName} when it is missing, and sets it to exactly these tables: ${setup.tables.join(", ")}.` : `  - creates the publication ${source.publicationName} when it is missing. No synced index reads a table yet, so it lists none.`
+  );
+  io.stdout(
+    mode === "new" ? "Only the new password goes to Headband. The owner URL stays on this machine." : "Nothing goes to Headband but the test that follows. The owner URL stays on this machine."
+  );
+  for (const n of setup.notes) io.stderr(`Note: ${n}`);
+  if (!await deps.confirm(confirmQuestion(ownerName, source.username, source.publicationName, mode))) {
+    throw new CliError("Cancelled. Nothing changed.");
+  }
+  const secrets = [
+    ...ownerSecrets(ownerUrl, env),
+    password,
+    verifier,
+    env.HEADBAND_SYNC_DB_URL,
+    env.HEADBAND_BATADB_API_KEY
+  ];
+  try {
+    await (deps.runOwnerSql ?? runOwnerSqlWithPg)(ownerUrl, sqlText);
+  } catch (err) {
+    throw ownerFailure(err, { id, user: source.username, mode }, secrets);
+  }
+  io.stdout("Setup SQL applied.");
+  if (password) {
+    try {
+      await client.patch(sourcePath(id), { password });
+    } catch (err) {
+      io.stderr(
+        "The role is set up, but Headband did not take its password. Run this setup again: it is safe to repeat."
+      );
+      throw err;
+    }
+  }
+  let res;
+  try {
+    res = await client.post(sourcePath(id, "/test"), {});
+  } catch (err) {
+    io.stderr(
+      `Setup is done, but the source test did not run. Run it with: headband sync source test ${id}`
+    );
+    throw err;
+  }
+  io.stdout(`Tested from ${res.data.boxId}:`);
+  printChecks(io, res.data.checks);
+  const failed = res.data.checks.filter((c) => !c.ok).length;
+  if (failed > 0) {
+    throw new CliError(
+      `${plural(failed, "check")} failed. Fix them, then run headband sync source test ${id}.`
+    );
+  }
+  io.stdout(
+    res.data.activated ? "The source is ready and active. Its synced indexes start backfilling." : "The source is ready."
+  );
+  if (json) {
+    printJson(deps.io, {
+      data: {
+        id,
+        provider: setup.provider,
+        password: mode,
+        boxId: res.data.boxId,
+        activated: res.data.activated,
+        checks: res.data.checks
+      }
+    });
+  }
+}
+async function runSyncSource(args, flags, deps) {
+  const { io, client } = deps;
+  const env = deps.env ?? process.env;
+  const json = flags["--json"] === true;
+  const action = args[0];
+  try {
+    if (action === "add") return await runAdd(args, flags, deps, env);
+    if (action === "setup") return await runSetup(args, flags, deps, env);
+    if (action === "list") {
+      const res = await client.get("/v1/sync/sources");
+      if (json) return printJson(io, res);
+      if (res.data.length === 0) {
+        io.stdout("No sources yet. Add one with: headband sync source add <name> --db-url <url>");
+        return;
+      }
+      printTable(
+        io,
+        res.data.map((s) => ({
+          id: s.id,
+          name: s.name,
+          kind: s.kind,
+          host: s.host,
+          state: s.state,
+          "last test": lastTested(s)
+        })),
+        ["id", "name", "kind", "host", "state", "last test"]
+      );
+      return;
+    }
+    if (action === "show") {
+      const res = await client.get(sourcePath(requireSourceId(args)));
+      if (json) return printJson(io, res);
+      const s = res.data;
+      const lines = [
+        ["id", s.id],
+        ["name", s.name],
+        ["kind", s.kind],
+        ["host", `${s.host}:${s.port}`],
+        ["database", s.database],
+        ["user", `${s.username}${s.hasPassword ? "" : " (no password yet)"}`],
+        ["tls", s.tlsMode],
+        ["ca bundle", s.tlsCaPem ? "set" : "system roots"],
+        ["capture", s.captureMode],
+        ["publication", s.publicationName],
+        ["state", s.error ? `${s.state}: ${s.error}` : s.state],
+        ["postgres", s.serverVersion === null ? "unknown" : String(s.serverVersion)],
+        ["last test", lastTested(s)]
+      ];
+      const width = Math.max(...lines.map(([k]) => k.length));
+      for (const [k, v] of lines) io.stdout(`${k.padEnd(width)}  ${v}`);
+      if (s.lastTest) printChecks(io, s.lastTest.checks);
+      return;
+    }
+    if (action === "test") {
+      const id = requireSourceId(args);
+      const res = await client.post(sourcePath(id, "/test"), {});
+      const failed = res.data.checks.filter((c) => !c.ok).length;
+      if (json) {
+        printJson(io, res);
+        if (failed > 0) throw new CliError(`${plural(failed, "check")} failed.`);
+        return;
+      }
+      io.stdout(`Tested from ${res.data.boxId}:`);
+      printChecks(io, res.data.checks);
+      if (failed > 0) {
+        io.stdout(
+          `Fix the failed checks, then test again. The setup SQL: headband sync source setup-sql ${id}`
+        );
+        throw new CliError(`${plural(failed, "check")} failed.`);
+      }
+      io.stdout(
+        res.data.activated ? "All checks passed. The source is active, and its synced indexes start backfilling." : "All checks passed."
+      );
+      return;
+    }
+    if (action === "setup-sql") {
+      const id = requireSourceId(args);
+      const res = await client.get(
+        setupSqlPath(id, choiceFlag(flags, "--provider", PROVIDERS))
+      );
+      if (json) return printJson(io, res);
+      io.stdout(res.data.sql.trimEnd());
+      for (const n of res.data.notes) io.stderr(`Note: ${n}`);
+      return;
+    }
+    if (action === "set-ca") {
+      const id = requireSourceId(args);
+      const caFile = str(flags, "--ca-file");
+      const none = flags["--none"] === true;
+      if (Boolean(caFile) === none)
+        throw new CliError("Give exactly one of --ca-file <pem> or --none.");
+      const tlsMode = choiceFlag(flags, "--tls-mode", TLS_MODES);
+      if (caFile && tlsMode === "require") {
+        throw new CliError(
+          "A CA bundle verifies the source's certificate, so it needs --tls-mode verify-full."
+        );
+      }
+      const body = {
+        tlsCaPem: none ? null : readCaFile(deps, caFile)
+      };
+      if (tlsMode) body.tlsMode = tlsMode;
+      const res = await client.patch(sourcePath(id), body);
+      if (json) return printJson(io, res);
+      const mode = tlsMode ? `, and set its TLS mode to ${tlsMode}` : "";
+      io.stdout(
+        !none ? `Set the CA bundle of ${id}${mode}. The box reconnects with it.` : tlsMode === "require" ? `Cleared the CA bundle of ${id}${mode}. The box reconnects encrypted, without verifying the certificate.` : `Cleared the CA bundle of ${id}${mode}. The box verifies against the system roots.`
+      );
+      return;
+    }
+    if (action === "remove") {
+      const id = requireSourceId(args);
+      if (!await deps.confirm(`Remove source ${id}? Sync drops its replication slots.`)) {
+        throw new CliError("Cancelled. Nothing changed.");
+      }
+      const res = await client.delete(sourcePath(id));
+      if (json) return printJson(io, res);
+      io.stdout(
+        res.data.deleted ? `Removed source ${id}.` : `Removing source ${id}: its pipelines are stopping.`
+      );
+      io.stdout("Run this as the tables' owner to finish:");
+      io.stdout(res.dropPublicationSql.trimEnd());
+      return;
+    }
+    io.stdout(SOURCE_USAGE);
+    throw new CliError("Unknown sync source command");
+  } catch (err) {
+    friendlySyncError(err);
+  }
+}
+
+// src/sync-indexes.ts
+var INDEX_USAGE = [
+  "Usage:",
+  "  headband sync index create -f <file.sync.json> [--json]",
+  "  headband sync index list [--source <id>] [--instance <id>] [--json]",
+  "  headband sync index show <id> [--version <n>] [--json]",
+  "  headband sync index update <id> -f <file.sync.json> [--rebuild] [--json]",
+  "  headband sync index validate -f <file.sync.json> [--index <id>] [--json]",
+  "  headband sync index preview <id> [--ids <id,id,...>] [-f <file.sync.json>] [--json]",
+  "  headband sync index rebuild|pause|resume|check <id> [--yes] [--json]",
+  "  headband sync index remove <id> [--drop-index] [--yes] [--json]",
+  "  headband sync status [--json]"
+].join("\n");
+var SYNC_INDEX_ID_RE = /^sx_[a-z0-9]{12}$/;
+var INSTANCE_ID_RE = /^i[a-z0-9]{12}$/;
+var PREVIEW_MAX_IDS = 20;
+var ATTENTION_INDEX = /* @__PURE__ */ new Set(["error", "needs_rebuild", "awaiting_setup", "degraded"]);
+var ATTENTION_SOURCE = /* @__PURE__ */ new Set(["error", "awaiting_setup"]);
+var path = (id, suffix = "") => `/v1/sync/indexes/${encodeURIComponent(id)}${suffix}`;
+function readDefinition(file, readFile = (p) => (0, import_fs9.readFileSync)(p, "utf8")) {
+  let text;
+  try {
+    text = readFile(file);
+  } catch {
+    throw new CliError(`Cannot read ${file}.`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new CliError(`${file} is not valid JSON.`);
+  }
+}
+function printIssues(io, issues) {
+  for (const i of issues) io.stderr(`${i.path ? `${i.path}: ` : ""}${i.message} (${i.code})`);
+}
+function issuesOf(err) {
+  if (!(err instanceof ApiError) || typeof err.details !== "object" || err.details === null)
+    return [];
+  const issues = err.details.issues;
+  return Array.isArray(issues) ? issues : [];
+}
+var INDEX_ID_SHAPE = "a synced index id like sx_ followed by 12 lowercase letters or digits";
+var LIST_INDEXES = "headband sync index list";
+function requireIndexId(args) {
+  const id = args[1];
+  if (!id) throw new CliError(`Missing synced index id (${LIST_INDEXES} shows them).`);
+  return checkedId(id, SYNC_INDEX_ID_RE, INDEX_ID_SHAPE, LIST_INDEXES);
+}
+function idFlag(flags, name, re, shape, listCommand) {
+  const value = str(flags, name);
+  return value === void 0 ? void 0 : checkedId(value, re, shape, listCommand);
+}
+function indexApiError(err, id) {
+  if (err instanceof ApiError) {
+    if (err.status === 409 && err.code === "index_managed_by_sync") {
+      throw new CliError(
+        `${err.message} Change its definition with headband sync index update <id> -f <file>.`
+      );
+    }
+    if (err.status === 409 && err.code === "index_dropping" && id) {
+      throw new CliError(
+        `${err.message} Finish with: headband sync index remove ${id} --drop-index`
+      );
+    }
+    if (err.status === 409 && err.code === "not_on_box_yet" && id) {
+      throw new CliError(`${err.message} Watch it start with: headband sync index show ${id}`);
+    }
+  }
+  return friendlySyncError(err);
+}
+function fileFlag(flags, deps, required) {
+  const file = str(flags, "--file");
+  if (!file) {
+    if (required) throw new CliError("Give the definition file with -f <file.sync.json>.");
+    return void 0;
+  }
+  return readDefinition(file, deps.readFile);
+}
+function stateLine(i) {
+  if (i.error) return `${i.state}: ${i.errorCode ?? "error"}: ${i.error}`;
+  if (i.build) return `${i.state} (${i.build.phase}, ${i.build.rendered} rendered)`;
+  return i.state;
+}
+function lag(i) {
+  return i.lagMs === null ? "" : i.lagMs < 1e3 ? `${i.lagMs} ms` : `${Math.round(i.lagMs / 100) / 10} s`;
+}
+function printClassification(io, c) {
+  if (!c) return;
+  io.stdout(`Change: ${c.class}${c.reasons.length ? ` (${c.reasons.join("; ")})` : ""}`);
+}
+async function runSyncIndex(args, flags, deps) {
+  const { io, client } = deps;
+  const json = flags["--json"] === true;
+  const action = args[0];
+  try {
+    if (action === "create") {
+      const definition = fileFlag(flags, deps, true);
+      const res = await client.post("/v1/sync/indexes", definition);
+      if (json) return printJson(io, res);
+      io.stdout(`Created synced index ${res.data.id} (${res.data.name}): ${stateLine(res.data)}.`);
+      if (res.data.state === "awaiting_setup") {
+        io.stdout(
+          `Its tables are not published yet. Run the setup again: headband sync source setup ${res.data.sourceId}`
+        );
+      } else {
+        io.stdout(`Watch it with: headband sync index show ${res.data.id}`);
+      }
+      return;
+    }
+    if (action === "list") {
+      const q = new URLSearchParams();
+      const source = idFlag(
+        flags,
+        "--source",
+        SOURCE_ID_PATTERN,
+        SOURCE_ID_SHAPE,
+        "headband sync source list"
+      );
+      const instance = idFlag(
+        flags,
+        "--instance",
+        INSTANCE_ID_RE,
+        "an engine id like i followed by 12 lowercase letters or digits",
+        "headband instances list"
+      );
+      if (source) q.set("source", source);
+      if (instance) q.set("instance", instance);
+      const qs = q.toString();
+      const res = await client.get(
+        `/v1/sync/indexes${qs ? `?${qs}` : ""}`
+      );
+      if (json) return printJson(io, res);
+      if (res.data.length === 0) {
+        io.stdout(
+          "No synced indexes yet. Create one with: headband sync index create -f <file.sync.json>"
+        );
+        return;
+      }
+      printTable(
+        io,
+        res.data.map((i) => ({
+          id: i.id,
+          name: i.name,
+          source: i.sourceId,
+          instance: i.instanceId,
+          state: stateLine(i),
+          lag: lag(i),
+          documents: i.documents ?? "",
+          pending: i.pendingChanges || i.definitionPending ? "yes" : ""
+        })),
+        ["id", "name", "source", "instance", "state", "lag", "documents", "pending"]
+      );
+      return;
+    }
+    if (action === "show") {
+      const id = requireIndexId(args);
+      const version = str(flags, "--version");
+      if (version !== void 0) {
+        if (!/^[1-9]\d{0,8}$/.test(version))
+          throw new CliError("--version must be a positive whole number.");
+        const res2 = await client.get(
+          path(id, `?version=${version}`)
+        );
+        if (json) return printJson(io, res2);
+        io.stdout(JSON.stringify(res2.data.definition, null, 2));
+        return;
+      }
+      const res = await client.get(path(id));
+      const jobs = await client.get(path(id, "/jobs?limit=5"));
+      if (json) return printJson(io, { data: res.data, jobs: jobs.data });
+      const i = res.data;
+      const lines = [
+        ["id", i.id],
+        ["name", i.name],
+        ["source", i.sourceId],
+        ["instance", i.instanceId],
+        ["state", stateLine(i)],
+        ["desired", i.desired],
+        [
+          "definition",
+          `version ${i.definitionVersion}${i.servingDefinitionVersion !== null && i.servingDefinitionVersion !== i.definitionVersion ? `, serving ${i.servingDefinitionVersion}` : ""}${i.definitionPending ? " (waits for a rebuild)" : ""}`
+        ],
+        ["physical", i.physicalName],
+        ["documents", i.documents === null ? "unknown" : String(i.documents)],
+        ["lag", lag(i) || "unknown"],
+        ["dead letters", String(i.deadLetters)],
+        ["last applied", i.lastAppliedAt ?? "never"],
+        ["pending", i.pendingChanges ? "a change has not reached the box yet" : "no"]
+      ];
+      const width = Math.max(...lines.map(([k]) => k.length));
+      for (const [k, v] of lines) io.stdout(`${k.padEnd(width)}  ${v}`);
+      if (jobs.data.length > 0) {
+        io.stdout("");
+        printTable(
+          io,
+          jobs.data.map((j) => ({
+            job: j.id,
+            kind: j.kind,
+            trigger: j.trigger,
+            state: j.state,
+            started: j.startedAt,
+            error: j.error ?? ""
+          })),
+          ["job", "kind", "trigger", "state", "started", "error"]
+        );
+      }
+      return;
+    }
+    if (action === "update") {
+      const id = requireIndexId(args);
+      const definition = fileFlag(flags, deps, true);
+      const rebuild = flags["--rebuild"] === true;
+      const res = await client.patch(path(id), {
+        definition,
+        ...rebuild ? { rebuild: true } : {}
+      });
+      if (json) return printJson(io, res);
+      if (res.saved) io.stdout(`Saved version ${res.data.definitionVersion}.`);
+      else io.stdout(`No definition change${rebuild ? "; rebuild requested." : "."}`);
+      printClassification(io, res.classification);
+      if (res.saved && rebuild)
+        io.stdout("Rebuild requested: the new version serves once it finishes.");
+      if (res.saved && !rebuild)
+        io.stdout(`It takes effect at the next rebuild: headband sync index rebuild ${id}`);
+      return;
+    }
+    if (action === "validate") {
+      const definition = fileFlag(flags, deps, true);
+      const syncIndexId = idFlag(flags, "--index", SYNC_INDEX_ID_RE, INDEX_ID_SHAPE, LIST_INDEXES);
+      const res = await client.post("/v1/sync/indexes/validate", { definition, ...syncIndexId ? { syncIndexId } : {} });
+      if (json) return printJson(io, res);
+      printIssues(io, res.data.errors);
+      for (const w of res.data.warnings)
+        io.stderr(`Warning: ${w.path ? `${w.path}: ` : ""}${w.message} (${w.code})`);
+      if (!res.data.valid) throw new CliError("The definition is not valid.");
+      io.stdout(`Valid${res.data.checkedOnBox ? ", checked against the source" : ""}.`);
+      printClassification(io, res.data.classification);
+      return;
+    }
+    if (action === "preview") {
+      const id = requireIndexId(args);
+      const rawIds = str(flags, "--ids");
+      const ids = rawIds?.split(",").map((s) => s.trim()).filter(Boolean);
+      if (ids && ids.length > PREVIEW_MAX_IDS)
+        throw new CliError(`Preview renders at most ${PREVIEW_MAX_IDS} ids.`);
+      const definition = fileFlag(flags, deps, false);
+      const res = await client.post(path(id, "/preview"), {
+        ...ids ? { ids } : {},
+        ...definition !== void 0 ? { definition } : {}
+      });
+      const previewFailed = () => new CliError(
+        `The preview has ${res.data.errors.length} error${res.data.errors.length === 1 ? "" : "s"}.`
+      );
+      if (json) {
+        printJson(io, res);
+        if (res.data.errors.length > 0) throw previewFailed();
+        return;
+      }
+      printIssues(io, res.data.errors);
+      for (const w of res.data.warnings) io.stderr(`Warning: ${w.message} (${w.code})`);
+      io.stdout(JSON.stringify(res.data.documents, null, 2));
+      if (res.data.errors.length > 0) throw previewFailed();
+      return;
+    }
+    if (action === "rebuild") {
+      const id = requireIndexId(args);
+      if (!await deps.confirm(
+        `Rebuild ${id}? It renders every row again into a new index, then swaps.`
+      )) {
+        throw new CliError("Cancelled. Nothing changed.");
+      }
+      const res = await client.post(path(id, "/rebuild"), {});
+      if (json) return printJson(io, res);
+      io.stdout(
+        `Rebuild requested for ${id}. Searches keep using the current index until the swap.`
+      );
+      return;
+    }
+    if (action === "pause" || action === "resume" || action === "check") {
+      const id = requireIndexId(args);
+      const res = await client.post(path(id, `/${action}`), {});
+      if (json) return printJson(io, res);
+      io.stdout(
+        action === "pause" ? `Paused ${id}. Changes wait on the source until you resume.` : action === "resume" ? `Resumed ${id}.` : `Check started for ${id}.`
+      );
+      return;
+    }
+    if (action === "remove") {
+      const id = requireIndexId(args);
+      const drop = flags["--drop-index"] === true;
+      const prompt = drop ? `Remove ${id} and delete its engine index? Searches against it stop working.` : `Remove ${id}? Sync stops; the engine index stays and becomes writable.`;
+      if (!await deps.confirm(prompt)) throw new CliError("Cancelled. Nothing changed.");
+      const res = await client.delete(path(id, drop ? "?dropIndex=1" : ""));
+      if (json) return printJson(io, res);
+      io.stdout(
+        res.data.indexDropped ? `Removed ${id} and its engine index.` : drop && res.data.claimed === true ? `Removed ${id}. Deleting its engine index started and did not finish: run this command again to finish.` : drop ? `Removed ${id}. Its engine index is not deleted yet: run this command again to finish, or run it without --drop-index to keep the engine index.` : `Removed ${id}. Its engine index stays.`
+      );
+      return;
+    }
+    io.stdout(INDEX_USAGE);
+    throw new CliError("Unknown sync index command");
+  } catch (err) {
+    const issues = issuesOf(err);
+    if (issues.length > 0) printIssues(io, issues);
+    indexApiError(err, SYNC_INDEX_ID_RE.test(args[1] ?? "") ? args[1] : void 0);
+  }
+}
+async function runSyncStatus(flags, deps) {
+  const { io, client } = deps;
+  try {
+    const sources = await client.get("/v1/sync/sources");
+    const indexes = await client.get("/v1/sync/indexes");
+    if (flags["--json"] === true)
+      return printJson(io, { sources: sources.data, indexes: indexes.data });
+    if (sources.data.length === 0) {
+      io.stdout("No sources yet. Start with: headband sync source add <name> --db-url <url>");
+      return;
+    }
+    printTable(
+      io,
+      sources.data.map((s) => ({ source: s.id, name: s.name, host: s.host, state: s.state })),
+      ["source", "name", "host", "state"]
+    );
+    if (indexes.data.length > 0) {
+      io.stdout("");
+      printTable(
+        io,
+        indexes.data.map((i) => ({
+          index: i.id,
+          name: i.name,
+          source: i.sourceId,
+          state: i.state,
+          lag: lag(i),
+          documents: i.documents ?? ""
+        })),
+        ["index", "name", "source", "state", "lag", "documents"]
+      );
+    }
+    const attention = [];
+    for (const s of sources.data) {
+      if (s.state === "awaiting_setup")
+        attention.push(`${s.id} waits for setup: headband sync source setup ${s.id}`);
+      else if (ATTENTION_SOURCE.has(s.state))
+        attention.push(
+          `${s.id} ${s.state}${s.error ? `: ${s.error}` : ""}. Test it: headband sync source test ${s.id}`
+        );
+    }
+    for (const i of indexes.data) {
+      if (i.state === "awaiting_setup")
+        attention.push(
+          `${i.id} waits for its tables to be published: headband sync source setup ${i.sourceId}`
+        );
+      else if (i.state === "needs_rebuild")
+        attention.push(`${i.id} needs a rebuild: headband sync index rebuild ${i.id}`);
+      else if (ATTENTION_INDEX.has(i.state))
+        attention.push(
+          `${i.id} ${i.state}${i.error ? `: ${i.errorCode ?? "error"}: ${i.error}` : ""}. Details: headband sync index show ${i.id}`
+        );
+    }
+    io.stdout("");
+    if (attention.length === 0) io.stdout("Everything is running.");
+    else {
+      io.stdout("Needs attention:");
+      for (const line of attention) io.stdout(`  ${line}`);
+    }
+  } catch (err) {
+    friendlySyncError(err);
+  }
+}
+
+// src/index.ts
+async function askWithPrompts(message) {
+  let aborted = false;
+  const answer = await (0, import_prompts2.default)(
+    { type: "confirm", name: "confirmed", message, initial: false },
+    {
+      onCancel: () => {
+        aborted = true;
+        return false;
+      }
+    }
+  );
+  return aborted ? void 0 : answer.confirmed === true;
+}
+var ENGINES2 = /* @__PURE__ */ new Set(["meilisearch", "typesense", "elasticsearch", "visor"]);
+var KEY_TYPES = /* @__PURE__ */ new Set(["admin", "search"]);
+var EXPORT_FORMATS = /* @__PURE__ */ new Set(["jsonl", "json"]);
+var VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "--url",
+  "--token",
+  "--profile",
+  "--engine",
+  "--primary-key",
+  "--file",
+  "--index",
+  "--limit",
+  "--filter",
+  "--type",
+  "--project",
+  "--dir",
+  "--slug",
+  "--table",
+  "--scaffold",
+  "--budget-ms",
+  "--batch-size",
+  "--reconcile-every",
+  "--name",
+  "--lane",
+  "--memory",
+  "--size",
+  "--region",
+  "--idle-timeout",
+  "--client",
+  "--instance",
+  "--db-url",
+  "--owner-url",
+  "--tls-mode",
+  "--ca-file",
+  "--kind",
+  "--batadb-project",
+  "--batadb-branch",
+  "--batadb-compute",
+  "--provider",
+  "-f",
+  "--source",
+  "--ids",
+  "--version",
+  "--out",
+  "--format",
+  "--batch",
+  "--permissions",
+  "--expires"
+]);
+var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
+  "--json",
+  "--yes",
+  "-y",
+  "--help",
+  "-h",
+  "--allow-destructive",
+  "--write",
+  "--force",
+  "--fix",
+  "--loop",
+  "--accept-broad-role",
+  "--rebuild",
+  "--drop-index",
+  "--none",
+  "--no-revoke"
+]);
+var DEFAULT_MIGRATIONS_DIR = "headband/migrations";
+function parseArgv(argv) {
+  const flags = {};
+  const positional = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith("-")) {
+      positional.push(arg);
+      continue;
+    }
+    const equalsIndex = arg.indexOf("=");
+    const flagName = equalsIndex === -1 ? arg : arg.slice(0, equalsIndex);
+    const inlineValue = equalsIndex === -1 ? void 0 : arg.slice(equalsIndex + 1);
+    if (VALUE_FLAGS.has(flagName)) {
+      const value = inlineValue ?? argv[index + 1];
+      if (!value || value.startsWith("-")) {
+        throw new UsageError(`Missing value for ${flagName}`);
+      }
+      flags[flagName === "-f" ? "--file" : flagName] = value;
+      if (inlineValue === void 0) index += 1;
+      continue;
+    }
+    if (BOOLEAN_FLAGS.has(flagName)) {
+      flags[flagName === "-y" ? "--yes" : flagName === "-h" ? "--help" : flagName] = true;
+      continue;
+    }
+    throw new UsageError(
+      /^--?[a-z][a-z0-9-]{0,40}$/.test(flagName) ? `Unknown option: ${flagName}` : "Unknown option."
+    );
+  }
+  return { flags, positional };
+}
+function stringFlag(flags, name) {
+  const value = flags[name];
+  return typeof value === "string" ? value : void 0;
+}
+function boolFlag(flags, name) {
+  return flags[name] === true;
+}
+function requiredFlag(flags, name) {
+  const value = stringFlag(flags, name);
+  if (!value) throw new UsageError(`Missing required option: ${name}`);
+  return value;
+}
+function requiredArg(value, what) {
+  if (!value) throw new UsageError(`Missing ${what}`);
+  return value;
+}
+function parseLimit(flags) {
+  const raw = stringFlag(flags, "--limit");
+  if (!raw) return void 0;
+  const limit = Number(raw);
+  if (!Number.isInteger(limit) || limit <= 0) {
+    throw new UsageError("--limit must be a positive integer");
+  }
+  return limit;
+}
+function validateEngine(engine) {
+  if (!ENGINES2.has(engine)) {
+    throw new UsageError("Engine must be one of: meilisearch, typesense, elasticsearch, visor");
+  }
+  return engine;
+}
+function validateKeyType(type) {
+  if (!KEY_TYPES.has(type)) {
+    throw new UsageError("Key type must be one of: admin, search");
+  }
+  return type;
+}
+function encode(value) {
+  return encodeURIComponent(value);
+}
+function chatterIO(io, flags) {
+  return boolFlag(flags, "--json") ? { stdout: io.stderr, stderr: io.stderr } : io;
+}
+function authFromFlags(flags) {
+  return resolveAuth({
+    token: stringFlag(flags, "--token"),
+    url: stringFlag(flags, "--url"),
+    profile: stringFlag(flags, "--profile")
+  });
+}
+function clientFromFlags(flags) {
+  const auth = authFromFlags(flags);
+  return createApiClient(auth.url, { apiKey: auth.apiKey });
+}
+function stdinIsInteractive() {
+  return process.stdin.isTTY === true;
+}
+async function confirmOrSkip(message, flags, ask = askWithPrompts) {
+  if (boolFlag(flags, "--yes")) return true;
+  if (!stdinIsInteractive()) {
+    throw new UsageError(
+      `Confirmation required: ${message} stdin is not a terminal, so re-run with --yes to confirm.`,
+      "confirmation_required"
+    );
+  }
+  const answer = await ask(message);
+  if (answer === void 0) {
+    throw new CliError("Interrupted.", { exitCode: EXIT_CODES.interrupted, code: "interrupted" });
+  }
+  return answer;
+}
+function cancelled(io, flags) {
+  if (boolFlag(flags, "--json")) printJson(io, { cancelled: true });
+  else io.stdout("Cancelled.");
+}
+function printHelp(io) {
+  io.stdout(`@headband/cli
+
+Usage:
+  headband <command> [options]
+
+Commands:
+  init [--yes]
+  login [--url <url>] [--profile <name>] [--json]
+  logout [--profile <name>] [--yes] [--no-revoke] [--json]
+  whoami [--json]
+  profiles list [--json]
+  profiles use <name>
+  projects list [--json]
+  projects create <name> --engine <meilisearch|typesense|elasticsearch|visor> [--json]
+  projects delete <id> [--force] [--yes] [--json]
+  keys list [--json]
+  keys create <name> --type <admin|search> [--project <id>] [--permissions <a,b>] [--expires <30d|ISO date>] [--json]
+  keys revoke <id> [--yes] [--json]
+  indexes list [--json]
+  indexes create <uid> [--primary-key <pk>] [--engine <engine>] [--instance <id>] [--json]
+  indexes delete <uid> [--yes] [--json]
+  indexes settings get <uid> [--json]
+  indexes settings set <uid> --file <settings.json> [--json]
+  indexes stats <uid> [--json]
+  instances list [--json]
+  instances create <engine> [--name <name>] [--lane <lane>] [--memory <size>] [--region <region>] [--idle-timeout <s>] [--json]
+  instances update <id> [--name <name>] [--lane <lane>] [--memory <size>] [--idle-timeout <s>] [--json]
+  instances show|wake|park <id> [--json]
+  instances wakes <id> [--limit <n>] [--json]
+  instances delete <id> [--yes] [--json]
+  instances connect <id> [--client <node|curl>] [--json]
+  docs push <file> --index <uid> [--json]
+  docs export --index <uid> [--out <file>] [--format <jsonl|json>] [--batch <n>]
+  docs delete <docId> --index <uid> [--json]
+  search <index> <query> [--limit N] [--filter <expr>] [--json]
+  tasks list [--json]
+  tasks get <id> [--json]
+  schema diff [--allow-destructive] [--json]
+  schema generate [--slug <slug>] [--dir <dir>] [--allow-destructive] [--json]
+  schema apply [--allow-destructive] [--dir <dir>] [--yes] [--json]
+  schema status [--dir <dir>] [--json]
+  sync init [--table <name>] [--write] [--json]
+  sync worker [--loop] [--budget-ms <ms>] [--batch-size <n>] [--reconcile-every <n>] [--json]
+  sync worker --scaffold docker [--force] [--json]
+  sync reconcile [--fix] [--json]
+  sync retry-dead-letters [--json]
+  sync source add|list|show|test|setup|setup-sql|set-ca|remove (see headband sync source --help)
+  sync index create|list|show|update|validate|preview|rebuild|pause|resume|check|remove (see headband sync index --help)
+  sync status [--json]
+
+Global options:
+  --token <key>      API key for this call. Wins over HEADBAND_API_KEY and stored logins.
+  --profile <name>   Stored login to use (else HEADBAND_PROFILE, else the current profile)
+  --url <url>        Headband URL (else HEADBAND_URL, else the profile's, else ${DEFAULT_URL})
+  --json             Print one JSON document on stdout; errors print one JSON object on stderr
+  --yes              Answer yes to confirmations (required when stdin is not a terminal)
+  --help             Show help
+  --version          Show the CLI version
+
+Exit codes: 0 ok, 1 error, 2 usage, 3 auth, 4 permission, 5 not found, 6 conflict,
+7 rate limited, 8 server or engine, 130 interrupted.`);
+}
+function printCommandHelp(command, io) {
+  const help = {
+    login: "Usage: headband login [--url <url>] [--profile <name>] [--json]",
+    logout: "Usage: headband logout [--profile <name>] [--yes] [--no-revoke] [--json]",
+    whoami: "Usage: headband whoami [--json]",
+    profiles: "Usage:\n  headband profiles list [--json]\n  headband profiles use <name>",
+    projects: "Usage:\n  headband projects list [--json]\n  headband projects create <name> --engine <meilisearch|typesense|elasticsearch|visor> [--json]\n  headband projects delete <id> [--force] [--yes] [--json]\n\n  delete refuses a project that still has indexes; --force deletes its indexes with it.",
+    keys: "Usage:\n  headband keys list [--json]\n  headband keys create <name> --type <admin|search> [--project <id>] [--permissions <a,b>] [--expires <30d|ISO date>] [--json]\n  headband keys revoke <id> [--yes] [--json]",
+    indexes: [
+      "Usage:",
+      "  headband indexes list [--json]",
+      "  headband indexes create <uid> [--primary-key <pk>] [--engine <engine>] [--instance <id>] [--json]",
+      "  headband indexes delete <uid> [--yes] [--json]",
+      "  headband indexes settings get <uid> [--json]",
+      "  headband indexes settings set <uid> --file <settings.json> [--json]",
+      "  headband indexes stats <uid> [--json]",
+      "",
+      "Options for create:",
+      "  --instance <id>  Create the index on one of your dedicated engines (ids from headband instances list).",
+      "                   The index takes that engine's type; --engine, if given, must match it."
+    ].join("\n"),
+    instances: INSTANCES_USAGE,
+    docs: "Usage:\n  headband docs push <file> --index <uid> [--json]\n  headband docs export --index <uid> [--out <file>] [--format <jsonl|json>] [--batch <n>] [--json]\n  headband docs delete <docId> --index <uid> [--json]",
+    search: "Usage: headband search <index> <query> [--limit N] [--filter <expr>] [--json]",
+    tasks: "Usage:\n  headband tasks list [--json]\n  headband tasks get <id> [--json]",
+    schema: "Usage:\n  headband schema diff [--allow-destructive] [--json]\n  headband schema generate [--slug <slug>] [--dir <dir>] [--allow-destructive] [--json]\n  headband schema apply [--allow-destructive] [--dir <dir>] [--yes] [--json]\n  headband schema status [--dir <dir>] [--json]",
+    sync: "Usage:\n  headband sync init [--table <name>] [--write] [--json]\n  headband sync worker [--loop] [--budget-ms <ms>] [--batch-size <n>] [--reconcile-every <n>] [--json]\n  headband sync worker --scaffold docker [--force] [--json]\n  headband sync reconcile [--fix] [--json]\n  headband sync retry-dead-letters [--json]\n  headband sync source add|list|show|test|setup|setup-sql|set-ca|remove (see headband sync source --help)\n  headband sync index create|list|show|update|validate|preview|rebuild|pause|resume|check|remove (see headband sync index --help)\n  headband sync status [--json]"
+  };
+  io.stdout(help[command] || "");
+}
+async function runLogin(flags, io) {
+  const url = stringFlag(flags, "--url") || process.env.HEADBAND_URL || DEFAULT_URL;
+  const result = await login(url, chatterIO(io, flags), {
+    profileName: stringFlag(flags, "--profile")
+  });
+  if (boolFlag(flags, "--json")) printJson(io, result);
+}
+async function runLogout(flags, io, confirm) {
+  const json = boolFlag(flags, "--json");
+  const chatter = chatterIO(io, flags);
+  const selected = selectProfile({
+    url: stringFlag(flags, "--url"),
+    profile: stringFlag(flags, "--profile")
+  });
+  if (!selected) {
+    throw new AuthError("No stored login to log out of. Run: headband profiles list");
+  }
+  const { name, profile } = selected;
+  let revoked = false;
+  const noRevoke = boolFlag(flags, "--no-revoke");
+  if (!noRevoke) {
+    if (!boolFlag(flags, "--yes")) {
+      chatter.stdout(
+        `Removing local credentials for profile ${name} (${profile.url}). Pass --no-revoke to keep the key working.`
+      );
+    }
+    if (await confirm("Revoke this CLI key server-side before logging out?")) {
+      const client = createApiClient(profile.url, profile);
+      try {
+        await client.delete(`/v1/keys/${encode(profile.keyId)}`);
+        revoked = true;
+        chatter.stdout("Revoked CLI key.");
+      } catch (error) {
+        if (!(error instanceof ApiError && (error.status === 401 || error.status === 404))) {
+          throw error;
+        }
+        chatter.stderr("The key was already revoked or no longer exists.");
+      }
+    }
+  }
+  removeProfile(name);
+  if (json) printJson(io, { profile: name, url: profile.url, revoked, loggedOut: true });
+  else io.stdout(`Logged out of ${profile.url} (profile ${name}).`);
+}
+async function runWhoami(flags, io) {
+  const auth = authFromFlags(flags);
+  const client = createApiClient(auth.url, auth);
+  await client.get("/v1/indexes");
+  const info = {
+    url: auth.url,
+    source: auth.source,
+    profile: auth.profileName ?? null,
+    orgName: auth.profile?.orgName ?? null,
+    orgId: auth.profile?.orgId ?? null,
+    keyPrefix: auth.profile?.keyPrefix ?? auth.apiKey.slice(0, 12),
+    keyId: auth.profile?.keyId ?? null,
+    valid: true
+  };
+  if (boolFlag(flags, "--json")) {
+    printJson(io, info);
+    return;
+  }
+  printTable(
+    io,
+    [info],
+    auth.profile ? ["url", "profile", "orgName", "keyPrefix", "keyId", "valid"] : ["url", "source", "keyPrefix", "valid"]
+  );
+}
+async function runProfiles(args, flags, io) {
+  const action = args[0];
+  if (action === "list") {
+    const credentials = readCredentials();
+    const profiles = Object.entries(credentials.profiles).map(([name, p]) => ({
+      name,
+      current: credentials.current === name,
+      url: p.url,
+      orgName: p.orgName,
+      orgId: p.orgId,
+      keyPrefix: p.keyPrefix,
+      keyId: p.keyId
+    }));
+    if (boolFlag(flags, "--json")) {
+      printJson(io, { data: { current: credentials.current ?? null, profiles } });
+      return;
+    }
+    if (profiles.length === 0) {
+      io.stdout("No stored logins. Run: headband login");
+      return;
+    }
+    printTable(
+      io,
+      profiles.map((p) => ({ ...p, current: p.current ? "*" : "" })),
+      ["current", "name", "url", "orgName", "keyPrefix"]
+    );
+    return;
+  }
+  if (action === "use") {
+    const name = requiredArg(args[1], "profile name");
+    const profile = setCurrentProfile(name);
+    if (boolFlag(flags, "--json")) printJson(io, { current: name, url: profile.url });
+    else io.stdout(`Now using profile ${name} (${profile.url}).`);
+    return;
+  }
+  printCommandHelp("profiles", io);
+  throw new UsageError("Unknown profiles command");
+}
+async function runProjects(args, flags, io, confirm) {
+  const action = args[0];
+  const client = clientFromFlags(flags);
+  if (action === "list") {
+    const response = await client.get(
+      "/v1/projects"
+    );
+    if (boolFlag(flags, "--json")) printJson(io, response);
+    else printTable(io, response.data.projects, ["id", "name", "engine", "prefix", "createdAt"]);
+    return;
+  }
+  if (action === "create") {
+    const name = requiredArg(args[1], "project name");
+    const engine = validateEngine(requiredFlag(flags, "--engine"));
+    const response = await client.post(
+      "/v1/projects",
+      {
+        name,
+        engine
+      }
+    );
+    if (boolFlag(flags, "--json")) printJson(io, response);
+    else printTable(io, [response.data.project], ["id", "name", "engine", "prefix", "createdAt"]);
+    return;
+  }
+  if (action === "delete") {
+    const id = requiredArg(args[1], "project id");
+    const force = boolFlag(flags, "--force");
+    const question = force ? `Delete project ${id} and every index in it?` : `Delete project ${id}?`;
+    if (!await confirm(question)) return cancelled(io, flags);
+    const response = await client.delete(`/v1/projects/${encode(id)}${force ? "?force=true" : ""}`);
+    if (boolFlag(flags, "--json")) printJson(io, response);
+    else io.stdout(`Deleted project ${id}.`);
+    return;
+  }
+  printCommandHelp("projects", io);
+  throw new UsageError("Unknown projects command");
+}
+var DURATION = /^(\d+)\s*(h|d|w|y)$/i;
+var DURATION_MS = {
+  h: 60 * 60 * 1e3,
+  d: 24 * 60 * 60 * 1e3,
+  w: 7 * 24 * 60 * 60 * 1e3,
+  y: 365 * 24 * 60 * 60 * 1e3
+};
+function parseExpires(raw, now = Date.now()) {
+  const duration = DURATION.exec(raw.trim());
+  if (duration) {
+    const amount = Number(duration[1]);
+    if (amount <= 0) throw new UsageError("--expires must be in the future");
+    return new Date(now + amount * DURATION_MS[duration[2].toLowerCase()]).toISOString();
+  }
+  if (/^\d{4}-\d{2}-\d{2}/.test(raw.trim())) {
+    const at = Date.parse(raw.trim());
+    if (!Number.isNaN(at)) {
+      if (at <= now) throw new UsageError("--expires must be in the future");
+      return new Date(at).toISOString();
+    }
+  }
+  throw new UsageError(
+    "--expires must be a duration (12h, 30d, 2w, 1y) or an ISO date (2027-01-31)"
+  );
+}
+function parsePermissions(raw) {
+  const permissions = [
+    ...new Set(
+      raw.split(",").map((p) => p.trim()).filter(Boolean)
+    )
+  ];
+  if (permissions.length === 0) {
+    throw new UsageError(
+      "--permissions needs at least one permission, such as search,documents.read"
+    );
+  }
+  return permissions;
+}
+async function runKeys(args, flags, io, confirm) {
+  const action = args[0];
+  const client = clientFromFlags(flags);
+  if (action === "list") {
+    const response = await client.get("/v1/keys");
+    if (boolFlag(flags, "--json")) printJson(io, response);
+    else
+      printTable(io, response.data.keys, [
+        "id",
+        "name",
+        "type",
+        "keyPrefix",
+        "projectId",
+        "lastUsedAt",
+        "expiresAt"
+      ]);
+    return;
+  }
+  if (action === "create") {
+    const name = requiredArg(args[1], "key name");
+    const body = {
+      name,
+      type: validateKeyType(requiredFlag(flags, "--type"))
+    };
+    const projectId = stringFlag(flags, "--project");
+    if (projectId) body.projectId = projectId;
+    const permissions = stringFlag(flags, "--permissions");
+    if (permissions) body.permissions = parsePermissions(permissions);
+    const expires = stringFlag(flags, "--expires");
+    if (expires) body.expiresAt = parseExpires(expires);
+    const response = await client.post("/v1/keys", body);
+    if (boolFlag(flags, "--json")) {
+      printJson(io, response);
+      return;
+    }
+    io.stdout(import_picocolors3.default.yellow("Store this API key now. It will not be shown again."));
+    io.stdout(response.data.apiKey);
+    printTable(io, [response.data.key], ["id", "name", "type", "keyPrefix", "expiresAt"]);
+    return;
+  }
+  if (action === "revoke") {
+    const id = requiredArg(args[1], "key id");
+    if (!await confirm(`Revoke key ${id}?`)) return cancelled(io, flags);
+    const response = await client.delete(`/v1/keys/${encode(id)}`);
+    if (boolFlag(flags, "--json")) printJson(io, response);
+    else io.stdout(`Revoked key ${id}.`);
+    return;
+  }
+  printCommandHelp("keys", io);
+  throw new UsageError("Unknown keys command");
+}
+async function runIndexes(args, flags, io, confirm) {
+  const action = args[0];
+  const client = clientFromFlags(flags);
+  if (action === "list") {
+    const response = await client.get("/v1/indexes");
+    if (boolFlag(flags, "--json")) printJson(io, response);
+    else {
+      const onInstance = response.results.some((r) => r.engineIndexUid);
+      printTable(io, response.results, [
+        "uid",
+        "primaryKey",
+        "engine",
+        ...onInstance ? ["instanceId", "engineIndexUid"] : [],
+        "createdAt",
+        "updatedAt"
+      ]);
+    }
+    return;
+  }
+  if (action === "create") {
+    const uid = requiredArg(args[1], "index uid");
+    const body = { uid };
+    const primaryKey = stringFlag(flags, "--primary-key");
+    const engine = stringFlag(flags, "--engine");
+    const instanceId = stringFlag(flags, "--instance");
+    if (primaryKey) body.primaryKey = primaryKey;
+    if (engine) body.engine = validateEngine(engine);
+    if (instanceId) body.instanceId = instanceId;
+    const response = await client.post("/v1/indexes", body);
+    if (boolFlag(flags, "--json")) {
+      printJson(io, response);
+      return;
+    }
+    printTable(
+      io,
+      [response],
+      response.instanceId ? ["indexUid", "engine", "instanceId", "engineIndexUid", "status"] : ["indexUid", "engine", "status"]
+    );
+    if (typeof response.engineIndexUid === "string") {
+      io.stdout(
+        `On the instance endpoint this index is named ${response.engineIndexUid}. Use that name with the engine's own client.`
+      );
+    }
+    return;
+  }
+  if (action === "delete") {
+    const uid = requiredArg(args[1], "index uid");
+    if (!await confirm(`Delete index ${uid}?`)) return cancelled(io, flags);
+    const response = await client.delete(`/v1/indexes/${encode(uid)}`);
+    if (boolFlag(flags, "--json")) printJson(io, response);
+    else io.stdout(`Deleted index ${uid}.`);
+    return;
+  }
+  if (action === "settings") {
+    const settingsAction = args[1];
+    const uid = requiredArg(args[2], "index uid");
+    if (settingsAction === "get") {
+      const response = await client.get(`/v1/indexes/${encode(uid)}/settings`);
+      printJson(io, response);
+      return;
+    }
+    if (settingsAction === "set") {
+      const file = requiredFlag(flags, "--file");
+      const settings = JSON.parse((0, import_fs11.readFileSync)(file, "utf-8"));
+      const response = await client.patch(`/v1/indexes/${encode(uid)}/settings`, settings);
+      printJson(io, response);
+      return;
+    }
+  }
+  if (action === "stats") {
+    const uid = requiredArg(args[1], "index uid");
+    const response = await client.get(`/v1/indexes/${encode(uid)}/stats`);
+    printJson(io, response);
+    return;
+  }
+  printCommandHelp("indexes", io);
+  throw new UsageError("Unknown indexes command");
+}
+function exportFormat(flags, out) {
+  const raw = stringFlag(flags, "--format") ?? (out?.toLowerCase().endsWith(".json") ? "json" : "jsonl");
+  if (!EXPORT_FORMATS.has(raw)) throw new UsageError("--format must be jsonl or json");
+  return raw;
+}
+async function runDocsExport(flags, context) {
+  const { io } = context;
+  const index = requiredFlag(flags, "--index");
+  const out = stringFlag(flags, "--out");
+  const format = exportFormat(flags, out);
+  const client = clientFromFlags(flags);
+  const batchSize = parseIntFlag(flags, "--batch") ?? await defaultExportBatchSize(client, index);
+  if (!out) {
+    const writeLine = context.writeLine ?? ((line) => io.stdout(line));
+    await exportDocuments(client, { index, format, batchSize, write: writeLine });
+    return;
+  }
+  const partial = `${out}.partial`;
+  const fd = (0, import_fs10.openSync)(partial, "w", 384);
+  let exported;
+  try {
+    exported = await exportDocuments(client, {
+      index,
+      format,
+      batchSize,
+      write: (line) => {
+        (0, import_fs10.writeSync)(fd, `${line}
+`);
+      },
+      onPage: (count, total) => io.stderr(`Exported ${count}${total === null ? "" : `/${total}`} documents`)
+    });
+    (0, import_fs10.closeSync)(fd);
+  } catch (error) {
+    (0, import_fs10.closeSync)(fd);
+    (0, import_fs10.rmSync)(partial, { force: true });
+    throw error;
+  }
+  (0, import_fs10.renameSync)(partial, out);
+  if (boolFlag(flags, "--json")) printJson(io, { index, out, format, exported });
+  else io.stdout(`Exported ${exported} documents to ${out}.`);
+}
+async function runDocs(args, flags, context) {
+  const { io } = context;
+  const action = args[0];
+  if (action === "export") {
+    await runDocsExport(flags, context);
+    return;
+  }
+  if (action === "push") {
+    const file = requiredArg(args[1], "documents file");
+    const index = requiredFlag(flags, "--index");
+    const client = clientFromFlags(flags);
+    const documents = parseDocumentsFile(file);
+    const count = await pushDocuments(client, index, documents, chatterIO(io, flags));
+    if (boolFlag(flags, "--json")) printJson(io, { index, pushed: count });
+    else io.stdout(`Pushed ${count} documents.`);
+    return;
+  }
+  if (action === "delete") {
+    const docId = requiredArg(args[1], "document id");
+    const index = requiredFlag(flags, "--index");
+    const client = clientFromFlags(flags);
+    const response = await client.delete(`/v1/documents/${encode(docId)}?index=${encode(index)}`);
+    if (boolFlag(flags, "--json")) printJson(io, response);
+    else io.stdout(`Deleted document ${docId}.`);
+    return;
+  }
+  printCommandHelp("docs", io);
+  throw new UsageError("Unknown docs command");
+}
+async function runSearch(args, flags, io) {
+  const index = requiredArg(args[0], "search index");
+  const query = args.slice(1).join(" ");
+  if (!query) throw new UsageError("Missing search query");
+  const client = clientFromFlags(flags);
+  const body = {
+    index,
+    q: query
+  };
+  const limit = parseLimit(flags);
+  const filter = stringFlag(flags, "--filter");
+  if (limit) body.limit = limit;
+  if (filter) body.filter = filter;
+  const response = await client.post("/v1/search", body);
+  if (boolFlag(flags, "--json")) {
+    printJson(io, response);
+    return;
+  }
+  const total = response.estimatedTotalHits ?? response.nbHits ?? response.hits?.length ?? 0;
+  io.stdout(`${total} hits in ${response.processingTimeMs ?? 0}ms`);
+  printTable(io, (response.hits || []).map(summarizeHit));
+}
+async function runTasks(args, flags, io) {
+  const action = args[0];
+  const client = clientFromFlags(flags);
+  if (action === "list") {
+    const response = await client.get("/v1/tasks");
+    if (boolFlag(flags, "--json")) printJson(io, response);
+    else
+      printTable(io, response.results ?? [], [
+        "uid",
+        "indexUid",
+        "type",
+        "status",
+        "enqueuedAt",
+        "finishedAt"
+      ]);
+    return;
+  }
+  if (action === "get") {
+    const id = requiredArg(args[1], "task id");
+    const response = await client.get(`/v1/tasks/${encode(id)}`);
+    printJson(io, response);
+    return;
+  }
+  printCommandHelp("tasks", io);
+  throw new UsageError("Unknown tasks command");
+}
+async function runSchema(args, flags, io, confirm) {
+  const action = args[0];
+  if (!["diff", "generate", "apply", "status"].includes(action)) {
+    printCommandHelp("schema", io);
+    throw new UsageError("Unknown schema command");
+  }
+  const json = boolFlag(flags, "--json");
+  const chatter = chatterIO(io, flags);
+  const dir = stringFlag(flags, "--dir") || DEFAULT_MIGRATIONS_DIR;
+  const auth = authFromFlags(flags);
+  const client = new HeadbandClient({ url: auth.url, adminKey: auth.apiKey });
+  const { config, adapter } = await loadHeadbandConfig(process.cwd());
+  const allowDestructive = boolFlag(flags, "--allow-destructive");
+  if (action === "diff") {
+    const ops = await planSchemaDiff({ config, client, allowDestructive });
+    if (json) printJson(io, { inSync: ops.length === 0, ops: opRows(ops) });
+    else printOpsTable(io, ops);
+    if (ops.length > 0) process.exitCode = 1;
+    return;
+  }
+  if (action === "generate") {
+    const path2 = await runSchemaGenerate({
+      config,
+      client,
+      dir,
+      slug: stringFlag(flags, "--slug"),
+      io: chatter,
+      allowDestructive
+    });
+    if (json) printJson(io, { path: path2 ?? null });
+    return;
+  }
+  if (action === "apply") {
+    if (!adapter) {
+      throw new CliError(
+        "headband.config.ts must export an `adapter` (e.g. drizzleAdapter(...)) for schema apply \u2014 it's needed to backfill documents during a reindex."
+      );
+    }
+    if (!await confirm("Apply pending schema migrations?")) {
+      return cancelled(io, flags);
+    }
+    const result = await runSchemaApply({
+      config,
+      adapter,
+      client,
+      dir,
+      allowDestructive,
+      io: chatter
+    });
+    if (json) printJson(io, result);
+    else
+      io.stdout(
+        `Applied ${result.appliedOps} op(s) across ${result.appliedFiles} migration file(s).`
+      );
+    return;
+  }
+  const status = await runSchemaStatus({ config, client, dir, io: chatter });
+  if (json) printJson(io, status);
+}
+function parseIntFlag(flags, name) {
+  const raw = stringFlag(flags, name);
+  if (!raw) return void 0;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new UsageError(`${name} must be a positive integer`);
+  }
+  return value;
+}
+async function runSync(args, flags, io, confirm) {
+  const action = args[0];
+  const json = boolFlag(flags, "--json");
+  const chatter = chatterIO(io, flags);
+  if (action === "source") {
+    await runSyncSource(args.slice(1), flags, {
+      io,
+      client: clientFromFlags(flags),
+      confirm
+    });
+    return;
+  }
+  if (action === "index") {
+    await runSyncIndex(args.slice(1), flags, {
+      io,
+      client: clientFromFlags(flags),
+      confirm
+    });
+    return;
+  }
+  if (action === "status") {
+    await runSyncStatus(flags, {
+      io,
+      client: clientFromFlags(flags),
+      confirm
+    });
+    return;
+  }
+  if (action === "init") {
+    const cwd = process.cwd();
+    const write = boolFlag(flags, "--write");
+    const ddl = runSyncInit({
+      io: json ? { stdout: () => void 0, stderr: io.stderr } : io,
+      table: stringFlag(flags, "--table"),
+      write,
+      cwd
+    });
+    if (json) printJson(io, { ddl, path: write ? (0, import_path9.join)(cwd, OUTBOX_SQL_RELATIVE_PATH) : null });
+    return;
+  }
+  if (action === "worker") {
+    const scaffold = stringFlag(flags, "--scaffold");
+    if (scaffold) {
+      if (scaffold !== "docker") throw new UsageError(`Unknown scaffold target: ${scaffold}`);
+      const path2 = runSyncScaffoldDocker({
+        cwd: process.cwd(),
+        io: chatter,
+        force: boolFlag(flags, "--force")
+      });
+      if (json) printJson(io, { path: path2 });
+      return;
+    }
+    const auth = authFromFlags(flags);
+    const client = new HeadbandClient({ url: auth.url, adminKey: auth.apiKey });
+    const { config, adapter } = await loadHeadbandConfig(process.cwd());
+    if (!adapter) {
+      throw new CliError(
+        "headband.config.ts must export an `adapter` (e.g. drizzleAdapter(...)) for sync worker."
+      );
+    }
+    const { outbox, close } = buildPgOutbox(resolveDatabaseUrl(process.env), {
+      table: config.sync?.outboxTable
+    });
+    try {
+      const report = await runSyncWorkerCmd({
+        config,
+        adapter,
+        client,
+        outbox,
+        io: chatter,
+        // Only override runSyncWorkerCmd's own default (loop unless
+        // --budget-ms is set) when the caller explicitly passed --loop —
+        // omitting it here keeps the bare `sync worker` default unchanged.
+        loop: boolFlag(flags, "--loop") ? true : void 0,
+        budgetMs: parseIntFlag(flags, "--budget-ms"),
+        batchSize: parseIntFlag(flags, "--batch-size"),
+        reconcileEvery: parseIntFlag(flags, "--reconcile-every"),
+        onReconcileTick: async () => {
+          const apiClient = clientFromFlags(flags);
+          await runSyncReconcile({
+            config,
+            adapter,
+            client,
+            io: chatter,
+            getStats: (uid) => apiClient.get(`/v1/indexes/${encode(uid)}/stats`)
+          });
+        }
+      });
+      if (json) printJson(io, report);
+    } finally {
+      await close();
+    }
+    return;
+  }
+  if (action === "reconcile") {
+    const auth = authFromFlags(flags);
+    const client = new HeadbandClient({ url: auth.url, adminKey: auth.apiKey });
+    const apiClient = createApiClient(auth.url, auth);
+    const { config, adapter } = await loadHeadbandConfig(process.cwd());
+    if (!adapter) {
+      throw new CliError(
+        "headband.config.ts must export an `adapter` (e.g. drizzleAdapter(...)) for sync reconcile."
+      );
+    }
+    const rows = await runSyncReconcile({
+      config,
+      adapter,
+      client,
+      io: chatter,
+      fix: boolFlag(flags, "--fix"),
+      getStats: (uid) => apiClient.get(`/v1/indexes/${encode(uid)}/stats`)
+    });
+    if (json) printJson(io, { indexes: rows });
+    return;
+  }
+  if (action === "retry-dead-letters") {
+    const { config } = await loadHeadbandConfig(process.cwd());
+    const { outbox, close } = buildPgOutbox(resolveDatabaseUrl(process.env), {
+      table: config.sync?.outboxTable
+    });
+    try {
+      const requeued = await runSyncRetryDeadLetters({ outbox, io: chatter });
+      if (json) printJson(io, { requeued });
+    } finally {
+      await close();
+    }
+    return;
+  }
+  printCommandHelp("sync", io);
+  throw new UsageError("Unknown sync command");
+}
+var CLI_VERSION = true ? "0.3.0" : "dev";
+async function run(argv, context = { io: defaultIO }) {
+  if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "-v" || argv[0] === "version")) {
+    context.io.stdout(CLI_VERSION);
+    return;
+  }
+  const { flags, positional } = parseArgv(argv);
+  const command = positional[0];
+  const args = positional.slice(1);
+  if (boolFlag(flags, "--help") || command === "help") {
+    if (command === "sync" && args[0] === "source") context.io.stdout(SOURCE_USAGE);
+    else if (command === "sync" && args[0] === "index") context.io.stdout(INDEX_USAGE);
+    else if (command && command !== "help") printCommandHelp(command, context.io);
+    else printHelp(context.io);
+    return;
+  }
+  const confirm = (message) => confirmOrSkip(message, flags, context.ask);
+  switch (command || "init") {
+    case "init":
+      if (!boolFlag(flags, "--yes") && !stdinIsInteractive()) {
+        throw new UsageError(
+          "headband init asks questions, and stdin is not a terminal. Pass --yes to use the defaults.",
+          "confirmation_required"
+        );
+      }
+      await init({ yes: boolFlag(flags, "--yes") });
+      return;
+    case "login":
+      await runLogin(flags, context.io);
+      return;
+    case "logout":
+      await runLogout(flags, context.io, confirm);
+      return;
+    case "whoami":
+      await runWhoami(flags, context.io);
+      return;
+    case "profiles":
+      await runProfiles(args, flags, context.io);
+      return;
+    case "projects":
+      await runProjects(args, flags, context.io, confirm);
+      return;
+    case "keys":
+      await runKeys(args, flags, context.io, confirm);
+      return;
+    case "indexes":
+      await runIndexes(args, flags, context.io, confirm);
+      return;
+    case "docs":
+      await runDocs(args, flags, context);
+      return;
+    case "search":
+      await runSearch(args, flags, context.io);
+      return;
+    case "tasks":
+      await runTasks(args, flags, context.io);
+      return;
+    case "schema":
+      await runSchema(args, flags, context.io, confirm);
+      return;
+    case "sync":
+      await runSync(args, flags, context.io, confirm);
+      return;
+    case "instances":
+      await runInstances(args, flags, context.io, clientFromFlags(flags), confirm);
+      return;
+    default:
+      printHelp(context.io);
+      throw new UsageError(
+        /^[a-z][a-z-]{0,31}$/.test(command) ? `Unknown command: ${command}` : "Unknown command."
+      );
+  }
+}
+async function main(argv, context = { io: defaultIO }) {
+  const json = argv.includes("--json");
+  try {
+    await run(argv, context);
+    return EXIT_CODES.ok;
+  } catch (error) {
+    if (json) context.io.stderr(JSON.stringify(errorPayload(error)));
+    else
+      context.io.stderr(
+        error instanceof CliError ? error.message : error instanceof Error ? error.message : String(error)
+      );
+    return errorExitCode(error);
+  }
+}
+function stdoutLineWriter(line) {
+  if (process.stdout.write(`${line}
+`)) return;
+  return new Promise((resolve) => process.stdout.once("drain", () => resolve()));
+}
+function isDirectRun() {
+  return typeof require !== "undefined" && typeof module !== "undefined" && require.main === module;
+}
+if (isDirectRun()) {
+  process.stdout.on("error", (error) => {
+    if (error.code === "EPIPE") process.exit(EXIT_CODES.ok);
+    throw error;
+  });
+  void main(process.argv.slice(2), { io: defaultIO, writeLine: stdoutLineWriter }).then((code) => {
+    if (code === EXIT_CODES.ok) return;
+    process.exitCode = code;
+    setTimeout(() => process.exit(code), 2e3).unref();
+  });
 }
-main().catch((err) => {
-  console.error(err);
-  process.exit(1);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CLI_VERSION,
+  main,
+  parseArgv,
+  parseExpires,
+  parsePermissions,
+  run,
+  stdinIsInteractive
 });