@headband/cli 0.1.0 → 0.2.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,18 @@ 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, {
+  parseArgv: () => parseArgv,
+  run: () => run
+});
+module.exports = __toCommonJS(index_exports);
+var import_fs8 = require("fs");
+var import_prompts2 = __toESM(require("prompts"));
+var import_picocolors3 = __toESM(require("picocolors"));
 
 // src/init.ts
 var import_prompts = __toESM(require("prompts"));
@@ -32,6 +48,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 +79,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 +93,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 +160,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 +181,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 +190,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 +209,2524 @@ 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 CliError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CliError";
+  }
+};
+var ApiError = class extends CliError {
+  constructor(message, status, code) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.code = code;
+  }
+};
+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";
+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");
+}
+function readCredentials() {
+  const path = getCredentialsPath();
+  if (!(0, import_fs2.existsSync)(path)) {
+    return { profiles: {} };
+  }
+  try {
+    const parsed = JSON.parse((0, import_fs2.readFileSync)(path, "utf-8"));
+    return {
+      profiles: parsed.profiles && typeof parsed.profiles === "object" ? parsed.profiles : {}
+    };
+  } catch {
+    throw new CliError(`Could not read credentials at ${path}`);
+  }
+}
+function writeCredentials(credentials) {
+  const path = getCredentialsPath();
+  (0, import_fs2.mkdirSync)((0, import_path3.dirname)(path), { recursive: true, mode: 448 });
+  (0, import_fs2.writeFileSync)(path, `${JSON.stringify(credentials, null, 2)}
+`, {
+    encoding: "utf-8",
+    mode: 384
+  });
+  (0, import_fs2.chmodSync)(path, 384);
+}
+function saveProfile(url, profile) {
+  const credentials = readCredentials();
+  credentials.profiles[normalizeUrl(url)] = profile;
+  writeCredentials(credentials);
+}
+function removeProfile(url) {
+  const credentials = readCredentials();
+  const normalized = normalizeUrl(url);
+  const existing = credentials.profiles[normalized];
+  delete credentials.profiles[normalized];
+  if (Object.keys(credentials.profiles).length === 0) {
+    const path = getCredentialsPath();
+    if ((0, import_fs2.existsSync)(path)) {
+      (0, import_fs2.rmSync)(path);
+    }
+    return existing;
+  }
+  writeCredentials(credentials);
+  return existing;
+}
+function resolveUrl(explicitUrl) {
+  if (explicitUrl) return normalizeUrl(explicitUrl);
+  const credentials = readCredentials();
+  const urls = Object.keys(credentials.profiles);
+  if (urls.length === 1) return urls[0];
+  return DEFAULT_URL;
+}
+function getProfile(url) {
+  const resolvedUrl = resolveUrl(url);
+  const profile = readCredentials().profiles[resolvedUrl];
+  if (!profile) {
+    throw new CliError(
+      `Not logged in for ${resolvedUrl}. Run: headband login --url ${resolvedUrl}`
+    );
+  }
+  return { url: resolvedUrl, 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, path, 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 response = await fetch(`${normalizeUrl(baseUrl)}${path}`, {
+    ...init2,
+    headers,
+    body: init2.body === void 0 || typeof init2.body === "string" ? init2.body : JSON.stringify(init2.body)
+  });
+  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
+    );
+  }
+  return body;
+}
+function createApiClient(url, profile) {
+  const request = (path, init2 = {}) => apiRequest(url, path, { ...init2, apiKey: profile.apiKey });
+  return {
+    url: normalizeUrl(url),
+    get: (path) => request(path, { method: "GET" }),
+    post: (path, body) => request(path, { method: "POST", body }),
+    patch: (path, body) => request(path, { method: "PATCH", body }),
+    delete: (path) => request(path, { 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 token = await runDeviceFlow(url, io, options);
+  saveProfile(url, {
+    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 ${normalizeUrl(url)} as ${token.orgName} (${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 path = (0, import_path4.join)(cwd, name);
+    if ((0, import_fs3.existsSync)(path)) return path;
+  }
+  return void 0;
+}
+function isSyncConfig(value) {
+  return typeof value === "object" && value !== null && Array.isArray(value.indexes);
+}
+async function loadHeadbandConfig(cwd) {
+  const path = findConfigFile(cwd);
+  if (!path) {
+    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(path);
+  } catch (err) {
+    throw new CliError(
+      `Failed to load ${path}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const candidate = mod.default ?? mod;
+  if (!isSyncConfig(candidate)) {
+    throw new CliError(`${path} does not export a valid Headband sync config (missing "indexes").`);
+  }
+  const adapter = mod.adapter;
+  return { config: candidate, adapter, path };
+}
+
+// src/docs.ts
+var import_path5 = require("path");
+var import_fs4 = require("fs");
+var DOCS_BATCH_SIZE = 1e3;
+function parseDocumentsFile(path) {
+  const content = (0, import_fs4.readFileSync)(path, "utf-8");
+  const ext = (0, import_path5.extname)(path).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;
+}
+
+// ../../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 connectSnippets(engine, 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(
-    `    3. Check the docs at ${import_picocolors.default.cyan("https://headband.dev/docs")}`
+  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/instances.ts
+var ENGINES = ["meilisearch", "elasticsearch", "typesense"];
+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> [--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 delete <id> [--yes] [--json]",
+  "  headband instances connect <id> [--client <node|curl>]"
+].join("\n");
+function parseMemory(raw) {
+  const m = /^(\d+(?:\.\d+)?)\s*(m|mb|g|gb)?$/i.exec(raw.trim());
+  if (!m) throw new CliError("--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 CliError("--memory must be a whole number of megabytes");
+  return mb;
+}
+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 CliError("--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 CliError(`${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 CliError("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.");
+    }
+    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."
+      );
+    }
+  }
+  throw err;
+}
+async function runInstances(args, flags, io, client, confirm) {
+  const action = args[0];
+  const json = flags["--json"] === true;
+  const str = (name) => typeof flags[name] === "string" ? flags[name] : void 0;
+  const path = (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 CliError("Engine must be one of: meilisearch, elasticsearch, typesense");
+      }
+      const body = { engine };
+      const name = str("--name");
+      const lane = str("--lane");
+      const memory = str("--memory");
+      const region = str("--region");
+      const idle = str("--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(path(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(path(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(path(id, "/park"));
+      if (json) return printJson(io, res);
+      io.stdout(`Engine ${id} is ${res.data.state}.`);
+      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(path(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 = str("--client");
+      if (which && !CLIENTS.includes(which)) throw new CliError("--client must be node or curl");
+      const res = await client.get(path(id));
+      const s = connectSnippets(res.data.engine, res.data.endpoint);
+      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 CliError("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 path = (0, import_path6.join)(dir, fileName);
+  const file = {
+    version: nextVersion,
+    createdAt: now().toISOString(),
+    parentHashes: meta.parentHashes,
+    ops
+  };
+  (0, import_fs5.writeFileSync)(path, JSON.stringify(file, null, 2));
+  return path;
+}
+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 path = (0, import_path6.join)(dir, entry);
+    const raw = (0, import_fs5.readFileSync)(path, "utf-8");
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new Error(`Malformed migration file: ${path}`);
+    }
+    files.push({ ...parsed, path });
+  }
+  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 isRecord(v) {
+  return typeof v === "object" && v !== null;
+}
+function parsePartialFailureItem(raw) {
+  const item = isRecord(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 isRecord(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, path, body, opts = {}) {
+    let attempt = 0;
+    for (; ; ) {
+      attempt += 1;
+      const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        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 path = (0, import_path7.join)(dir, APPLIED_MARKER_FILE);
+  if (!(0, import_fs6.existsSync)(path)) return 0;
+  try {
+    const parsed = JSON.parse((0, import_fs6.readFileSync)(path, "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 runSchemaDiff(deps) {
+  const applied = await deps.client.getSchemaState();
+  const ops = planMigration(deps.config, applied, { allowDestructive: deps.allowDestructive });
+  printOpsTable(deps.io, ops);
+  return ops.length > 0 ? 1 : 0;
+}
+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 path = generateMigrationFile(
+    deps.dir,
+    ops,
+    { parentHashes, slug: deps.slug ?? "migration" },
+    deps.now
   );
-  console.log();
+  deps.io.stdout(`Wrote ${path}`);
+  printOpsTable(deps.io, ops);
+  return path;
+}
+function isConflictError(err) {
+  if (!(err instanceof Error)) return false;
+  const shaped = err;
+  return shaped.status === 409 || shaped.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}`);
 }
 
-// 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/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 path = (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)(path, `${ddl}
 `);
+    deps.io.stdout(`Wrote ${path}`);
+  }
+  return ddl;
 }
-async function main() {
-  if (flags.has("--help") || flags.has("-h") || command === "help") {
-    printHelp();
-    process.exit(0);
+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);
   }
-  if (!command || command === "init") {
-    await init({ yes: flags.has("--yes") || flags.has("-y") });
-  } else {
-    console.error(`Unknown command: ${command}`);
-    printHelp();
-    process.exit(1);
+  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 path = (0, import_path8.join)(deps.cwd, DOCKERFILE_NAME);
+  if ((0, import_fs7.existsSync)(path) && !deps.force) {
+    throw new CliError(`${DOCKERFILE_NAME} already exists at ${path}. Pass --force to overwrite.`);
+  }
+  (0, import_fs7.writeFileSync)(path, DOCKERFILE_CONTENT);
+  deps.io.stdout(`Wrote ${path}`);
+  deps.io.stdout("Add this service to your docker-compose.yml:");
+  deps.io.stdout(COMPOSE_SNIPPET);
+  return path;
+}
+
+// src/index.ts
+var ENGINES2 = /* @__PURE__ */ new Set(["meilisearch", "typesense", "elasticsearch"]);
+var KEY_TYPES = /* @__PURE__ */ new Set(["admin", "search"]);
+var VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "--url",
+  "--engine",
+  "--primary-key",
+  "--file",
+  "--index",
+  "--limit",
+  "--filter",
+  "--type",
+  "--project",
+  "--dir",
+  "--slug",
+  "--table",
+  "--scaffold",
+  "--budget-ms",
+  "--batch-size",
+  "--reconcile-every",
+  "--name",
+  "--lane",
+  "--memory",
+  "--region",
+  "--idle-timeout",
+  "--client",
+  "--instance"
+]);
+var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
+  "--json",
+  "--yes",
+  "-y",
+  "--help",
+  "-h",
+  "--allow-destructive",
+  "--write",
+  "--force",
+  "--fix",
+  "--loop"
+]);
+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 CliError(`Missing value for ${flagName}`);
+      }
+      flags[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 CliError(`Unknown option: ${arg}`);
+  }
+  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 CliError(`Missing required option: ${name}`);
+  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 CliError("--limit must be a positive integer");
+  }
+  return limit;
+}
+function validateEngine(engine) {
+  if (!ENGINES2.has(engine)) {
+    throw new CliError("Engine must be one of: meilisearch, typesense, elasticsearch");
+  }
+  return engine;
+}
+function validateKeyType(type) {
+  if (!KEY_TYPES.has(type)) {
+    throw new CliError("Key type must be one of: admin, search");
   }
+  return type;
+}
+function encode(value) {
+  return encodeURIComponent(value);
+}
+function clientFromFlags(flags) {
+  const { url, profile } = getProfile(stringFlag(flags, "--url"));
+  return createApiClient(url, profile);
+}
+async function confirmOrSkip(message, flags) {
+  if (boolFlag(flags, "--yes")) return true;
+  const answer = await (0, import_prompts2.default)({
+    type: "confirm",
+    name: "confirmed",
+    message,
+    initial: false
+  });
+  return answer.confirmed === true;
+}
+function printHelp(io) {
+  io.stdout(`@headband/cli
+
+Usage:
+  headband <command> [options]
+
+Commands:
+  init [--yes]
+  login [--url <url>]
+  logout [--url <url>] [--yes]
+  whoami [--url <url>] [--json]
+  projects list [--json]
+  projects create <name> --engine <meilisearch|typesense|elasticsearch>
+  keys list [--json]
+  keys create <name> --type <admin|search> [--project <id>] [--json]
+  keys revoke <id> [--yes]
+  indexes list [--json]
+  indexes create <uid> [--primary-key <pk>] [--engine <engine>] [--instance <id>] [--json]
+  indexes delete <uid> [--yes]
+  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>]
+  instances show|wake|park <id> [--json]
+  instances delete <id> [--yes]
+  instances connect <id> [--client <node|curl>]
+  docs push <file> --index <uid>
+  docs delete <docId> --index <uid>
+  search <index> <query> [--limit N] [--filter <expr>] [--json]
+  tasks list [--json]
+  tasks get <id> [--json]
+  schema diff [--url <url>]
+  schema generate [--slug <slug>] [--dir <dir>] [--url <url>]
+  schema apply [--allow-destructive] [--dir <dir>] [--yes] [--url <url>]
+  schema status [--dir <dir>] [--url <url>]
+  sync init [--table <name>] [--write]
+  sync worker [--loop] [--budget-ms <ms>] [--batch-size <n>] [--reconcile-every <n>] [--url <url>]
+  sync worker --scaffold docker [--force]
+  sync reconcile [--fix] [--url <url>]
+  sync retry-dead-letters
+
+Global options:
+  --url <url>    Select profile URL (default: stored single profile, else ${DEFAULT_URL})
+  --json         Print machine-readable JSON for supported commands
+  --yes          Skip confirmation prompts
+  --help         Show help`);
+}
+function printCommandHelp(command, io) {
+  const help = {
+    login: "Usage: headband login [--url <url>]",
+    logout: "Usage: headband logout [--url <url>] [--yes]",
+    whoami: "Usage: headband whoami [--url <url>] [--json]",
+    projects: "Usage:\n  headband projects list [--json]\n  headband projects create <name> --engine <meilisearch|typesense|elasticsearch>",
+    keys: "Usage:\n  headband keys list [--json]\n  headband keys create <name> --type <admin|search> [--project <id>] [--json]\n  headband keys revoke <id> [--yes]",
+    indexes: [
+      "Usage:",
+      "  headband indexes list [--json]",
+      "  headband indexes create <uid> [--primary-key <pk>] [--engine <engine>] [--instance <id>] [--json]",
+      "  headband indexes delete <uid> [--yes]",
+      "  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>\n  headband docs delete <docId> --index <uid>",
+    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\n  headband schema generate [--slug <slug>] [--dir <dir>]\n  headband schema apply [--allow-destructive] [--dir <dir>] [--yes]\n  headband schema status [--dir <dir>]",
+    sync: "Usage:\n  headband sync init [--table <name>] [--write]\n  headband sync worker [--loop] [--budget-ms <ms>] [--batch-size <n>] [--reconcile-every <n>]\n  headband sync worker --scaffold docker [--force]\n  headband sync reconcile [--fix]\n  headband sync retry-dead-letters"
+  };
+  io.stdout(help[command] || "");
+}
+async function runLogin(flags, io) {
+  await login(stringFlag(flags, "--url") || DEFAULT_URL, io);
+}
+async function runLogout(flags, io) {
+  const { url: selectedUrl, profile } = getProfile(stringFlag(flags, "--url"));
+  io.stdout(
+    `Removing local credentials for ${selectedUrl}. Revoke this key with headband keys revoke ${profile.keyId} or in the dashboard if it should stop working.`
+  );
+  if (!boolFlag(flags, "--yes")) {
+    const shouldRevoke = await confirmOrSkip(
+      "Revoke this CLI key server-side before logging out?",
+      flags
+    );
+    if (shouldRevoke) {
+      const client = createApiClient(selectedUrl, profile);
+      await client.delete(`/v1/keys/${encode(profile.keyId)}`);
+      io.stdout("Revoked CLI key.");
+    }
+  }
+  removeProfile(selectedUrl);
+  io.stdout(`Logged out of ${selectedUrl}.`);
+}
+async function runWhoami(flags, io) {
+  const { url, profile } = getProfile(stringFlag(flags, "--url"));
+  const client = createApiClient(url, profile);
+  await client.get("/v1/indexes");
+  const info = {
+    url,
+    orgName: profile.orgName,
+    orgId: profile.orgId,
+    keyPrefix: profile.keyPrefix,
+    keyId: profile.keyId,
+    valid: true
+  };
+  if (boolFlag(flags, "--json")) {
+    printJson(io, info);
+    return;
+  }
+  printTable(io, [info], ["url", "orgName", "keyPrefix", "keyId", "valid"]);
+}
+async function runProjects(args, flags, io) {
+  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 = args[1];
+    if (!name) throw new CliError("Missing 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;
+  }
+  printCommandHelp("projects", io);
+  throw new CliError("Unknown projects command");
+}
+async function runKeys(args, flags, io) {
+  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"
+      ]);
+    return;
+  }
+  if (action === "create") {
+    const name = args[1];
+    if (!name) throw new CliError("Missing key name");
+    const body = {
+      name,
+      type: validateKeyType(requiredFlag(flags, "--type"))
+    };
+    const projectId = stringFlag(flags, "--project");
+    if (projectId) body.projectId = projectId;
+    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"]);
+    return;
+  }
+  if (action === "revoke") {
+    const id = args[1];
+    if (!id) throw new CliError("Missing key id");
+    if (!await confirmOrSkip(`Revoke key ${id}?`, flags)) {
+      io.stdout("Cancelled.");
+      return;
+    }
+    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 CliError("Unknown keys command");
+}
+async function runIndexes(args, flags, io) {
+  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 = args[1];
+    if (!uid) throw new CliError("Missing 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 = args[1];
+    if (!uid) throw new CliError("Missing index uid");
+    if (!await confirmOrSkip(`Delete index ${uid}?`, flags)) {
+      io.stdout("Cancelled.");
+      return;
+    }
+    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 = args[2];
+    if (!uid) throw new CliError("Missing 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_fs8.readFileSync)(file, "utf-8"));
+      const response = await client.patch(`/v1/indexes/${encode(uid)}/settings`, settings);
+      printJson(io, response);
+      return;
+    }
+  }
+  if (action === "stats") {
+    const uid = args[1];
+    if (!uid) throw new CliError("Missing index uid");
+    const response = await client.get(`/v1/indexes/${encode(uid)}/stats`);
+    printJson(io, response);
+    return;
+  }
+  printCommandHelp("indexes", io);
+  throw new CliError("Unknown indexes command");
+}
+async function runDocs(args, flags, io) {
+  const action = args[0];
+  const client = clientFromFlags(flags);
+  if (action === "push") {
+    const file = args[1];
+    if (!file) throw new CliError("Missing documents file");
+    const index = requiredFlag(flags, "--index");
+    const documents = parseDocumentsFile(file);
+    const count = await pushDocuments(client, index, documents, io);
+    io.stdout(`Pushed ${count} documents.`);
+    return;
+  }
+  if (action === "delete") {
+    const docId = args[1];
+    if (!docId) throw new CliError("Missing document id");
+    const index = requiredFlag(flags, "--index");
+    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 CliError("Unknown docs command");
+}
+async function runSearch(args, flags, io) {
+  const index = args[0];
+  const query = args.slice(1).join(" ");
+  if (!index) throw new CliError("Missing search index");
+  if (!query) throw new CliError("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 printJson(io, response);
+    return;
+  }
+  if (action === "get") {
+    const id = args[1];
+    if (!id) throw new CliError("Missing task id");
+    const response = await client.get(`/v1/tasks/${encode(id)}`);
+    printJson(io, response);
+    return;
+  }
+  printCommandHelp("tasks", io);
+  throw new CliError("Unknown tasks command");
+}
+async function runSchema(args, flags, io) {
+  const action = args[0];
+  const dir = stringFlag(flags, "--dir") || DEFAULT_MIGRATIONS_DIR;
+  const { url, profile } = getProfile(stringFlag(flags, "--url"));
+  const client = new HeadbandClient({ url, adminKey: profile.apiKey });
+  const { config, adapter } = await loadHeadbandConfig(process.cwd());
+  const allowDestructive = boolFlag(flags, "--allow-destructive");
+  if (action === "diff") {
+    const code = await runSchemaDiff({ config, client, io, allowDestructive });
+    if (code !== 0) process.exitCode = code;
+    return;
+  }
+  if (action === "generate") {
+    await runSchemaGenerate({
+      config,
+      client,
+      dir,
+      slug: stringFlag(flags, "--slug"),
+      io,
+      allowDestructive
+    });
+    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 confirmOrSkip("Apply pending schema migrations?", flags)) {
+      io.stdout("Cancelled.");
+      return;
+    }
+    const result = await runSchemaApply({ config, adapter, client, dir, allowDestructive, io });
+    io.stdout(
+      `Applied ${result.appliedOps} op(s) across ${result.appliedFiles} migration file(s).`
+    );
+    return;
+  }
+  if (action === "status") {
+    await runSchemaStatus({ config, client, dir, io });
+    return;
+  }
+  printCommandHelp("schema", io);
+  throw new CliError("Unknown schema command");
+}
+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 CliError(`${name} must be a positive integer`);
+  }
+  return value;
+}
+async function runSync(args, flags, io) {
+  const action = args[0];
+  if (action === "init") {
+    runSyncInit({
+      io,
+      table: stringFlag(flags, "--table"),
+      write: boolFlag(flags, "--write"),
+      cwd: process.cwd()
+    });
+    return;
+  }
+  if (action === "worker") {
+    const scaffold = stringFlag(flags, "--scaffold");
+    if (scaffold) {
+      if (scaffold !== "docker") throw new CliError(`Unknown scaffold target: ${scaffold}`);
+      runSyncScaffoldDocker({ cwd: process.cwd(), io, force: boolFlag(flags, "--force") });
+      return;
+    }
+    const { url, profile } = getProfile(stringFlag(flags, "--url"));
+    const client = new HeadbandClient({ url, adminKey: profile.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 {
+      await runSyncWorkerCmd({
+        config,
+        adapter,
+        client,
+        outbox,
+        io,
+        // 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,
+            getStats: (uid) => apiClient.get(`/v1/indexes/${encode(uid)}/stats`)
+          });
+        }
+      });
+    } finally {
+      await close();
+    }
+    return;
+  }
+  if (action === "reconcile") {
+    const { url, profile } = getProfile(stringFlag(flags, "--url"));
+    const client = new HeadbandClient({ url, adminKey: profile.apiKey });
+    const apiClient = clientFromFlags(flags);
+    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."
+      );
+    }
+    await runSyncReconcile({
+      config,
+      adapter,
+      client,
+      io,
+      fix: boolFlag(flags, "--fix"),
+      getStats: (uid) => apiClient.get(`/v1/indexes/${encode(uid)}/stats`)
+    });
+    return;
+  }
+  if (action === "retry-dead-letters") {
+    const { config } = await loadHeadbandConfig(process.cwd());
+    const { outbox, close } = buildPgOutbox(resolveDatabaseUrl(process.env), {
+      table: config.sync?.outboxTable
+    });
+    try {
+      await runSyncRetryDeadLetters({ outbox, io });
+    } finally {
+      await close();
+    }
+    return;
+  }
+  printCommandHelp("sync", io);
+  throw new CliError("Unknown sync command");
+}
+async function run(argv, context = { io: defaultIO }) {
+  const { flags, positional } = parseArgv(argv);
+  const command = positional[0];
+  const args = positional.slice(1);
+  if (boolFlag(flags, "--help") || command === "help") {
+    if (command && command !== "help") printCommandHelp(command, context.io);
+    else printHelp(context.io);
+    return;
+  }
+  switch (command || "init") {
+    case "init":
+      await init({ yes: boolFlag(flags, "--yes") });
+      return;
+    case "login":
+      await runLogin(flags, context.io);
+      return;
+    case "logout":
+      await runLogout(flags, context.io);
+      return;
+    case "whoami":
+      await runWhoami(flags, context.io);
+      return;
+    case "projects":
+      await runProjects(args, flags, context.io);
+      return;
+    case "keys":
+      await runKeys(args, flags, context.io);
+      return;
+    case "indexes":
+      await runIndexes(args, flags, context.io);
+      return;
+    case "docs":
+      await runDocs(args, flags, context.io);
+      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);
+      return;
+    case "sync":
+      await runSync(args, flags, context.io);
+      return;
+    case "instances":
+      await runInstances(
+        args,
+        flags,
+        context.io,
+        clientFromFlags(flags),
+        (message) => confirmOrSkip(message, flags)
+      );
+      return;
+    default:
+      printHelp(context.io);
+      throw new CliError(`Unknown command: ${command}`);
+  }
+}
+function isDirectRun() {
+  return typeof require !== "undefined" && typeof module !== "undefined" && require.main === module;
+}
+if (isDirectRun()) {
+  run(process.argv.slice(2)).catch((error) => {
+    const message = error instanceof ApiError || error instanceof CliError ? error.message : String(error);
+    defaultIO.stderr(message);
+    process.exit(1);
+  });
 }
-main().catch((err) => {
-  console.error(err);
-  process.exit(1);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  parseArgv,
+  run
 });