@schemic/cli 0.1.0-alpha.0

package/lib/cli.js

@@ -0,0 +1,1464 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import {
+  existsSync as existsSync3,
+  watch as fsWatch,
+  mkdirSync as mkdirSync3,
+  writeFileSync as writeFileSync3
+} from "fs";
+import { dirname as dirname2, join as join2, relative as relative2 } from "path";
+import { createInterface } from "readline/promises";
+import {
+  actionLabel,
+  applyPull,
+  duplicateTables,
+  EMPTY_STORED as EMPTY_STORED2,
+  existingTables,
+  fail,
+  formatDiff,
+  formatItems as formatItems2,
+  formatPatch,
+  getDriver as getDriver4,
+  isEmptyDiff as isEmptyDiff2,
+  kindFlags,
+  lineDiff,
+  listMigrations as listMigrations2,
+  loadDefs as loadDefs3,
+  loadSchemas,
+  lowerSchema as lowerSchema3,
+  ok as ok2,
+  parseFilter as parseFilter2,
+  pipeThroughPager,
+  plural as plural2,
+  readSnapshot as readSnapshot2,
+  resolvePager,
+  snapshotObjects as snapshotObjects2,
+  style as style2,
+  summarizeKinds,
+  unifiedDiff,
+  writeSnapshot as writeSnapshot2
+} from "@schemic/core";
+import { Command, Help, Option } from "commander";
+
+// src/cli/init.ts
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { dirname, resolve } from "path";
+function initialSnapshot(driver) {
+  return `${JSON.stringify(
+    {
+      version: 3,
+      driver,
+      schema: { kinds: {} },
+      files: {}
+    },
+    null,
+    2
+  )}
+`;
+}
+function init(cwd, driver) {
+  const scaffold = driver.initScaffold?.();
+  if (!scaffold)
+    throw new Error(
+      `the "${driver.name}" driver does not support \`schemic init\` scaffolding.`
+    );
+  const files = {
+    ...scaffold,
+    "database/migrations/meta/_snapshot.json": initialSnapshot(driver.name)
+  };
+  const created = [];
+  const skipped = [];
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = resolve(cwd, rel);
+    if (existsSync(abs)) {
+      skipped.push(rel);
+      continue;
+    }
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content);
+    created.push(rel);
+  }
+  return { created, skipped };
+}
+
+// src/cli/migrate.ts
+import {
+  existsSync as existsSync2,
+  mkdirSync as mkdirSync2,
+  readFileSync,
+  rmSync,
+  writeFileSync as writeFileSync2
+} from "fs";
+import { join, relative, resolve as resolve2 } from "path";
+import {
+  buildKindDiff,
+  checksum,
+  EMPTY_STORED,
+  filterKinds,
+  getDriver,
+  intersectKinds,
+  isEmptyDiff,
+  listMigrations,
+  loadDefs,
+  lowerSchema,
+  makeJiti,
+  mergeStored,
+  parseFilter,
+  readSnapshot,
+  slug,
+  snapshotKinds,
+  snapshotObjects,
+  timestamp,
+  writeSnapshot
+} from "@schemic/core";
+function buildStored(driver, tables, defs, opts = {}) {
+  const objects = lowerSchema(driver.registry, driver.explode(tables, defs));
+  const files = {};
+  const rel = (abs) => opts.root ? relative(opts.root, abs) : abs;
+  for (const t of tables) {
+    const abs = opts.fileOf?.get(t);
+    if (abs) files[t.name] = rel(abs);
+  }
+  for (const d of defs) {
+    const abs = opts.fileOf?.get(d);
+    const key = d.kind === "event" ? d.table : d.name;
+    if (abs && key) files[key] = rel(abs);
+  }
+  return {
+    version: 3,
+    driver: driver.name,
+    schema: snapshotKinds(objects),
+    files
+  };
+}
+function migStore(config) {
+  const driver = getDriver(config.driver ?? "surrealdb");
+  if (!driver.migrations)
+    throw new Error(
+      `The "${driver.name}" driver does not support running migrations.`
+    );
+  return driver.migrations;
+}
+var migExt = (config) => getDriver(config.driver ?? "surrealdb").migrations?.extension ?? ".surql";
+function attachFiles(diff, prevFiles, nextFiles) {
+  for (const it of diff.items ?? []) {
+    const primary = it.op === "remove" ? prevFiles : nextFiles;
+    it.file = primary[it.table] ?? nextFiles[it.table] ?? prevFiles[it.table];
+  }
+}
+async function planMigration(config, filter = parseFilter({}), opts = {}) {
+  const { tables, defs, fileOf } = await loadDefs(config.schemaPath);
+  const driver = getDriver(config.driver ?? "surrealdb");
+  const reg = driver.registry;
+  const next = buildStored(driver, tables, defs, { fileOf, root: config.root });
+  const prev = opts.baseline ? EMPTY_STORED : readSnapshot(config.metaDir);
+  const diff = buildKindDiff(
+    reg,
+    filterKinds(reg, snapshotObjects(prev.schema), filter),
+    filterKinds(reg, snapshotObjects(next.schema), filter)
+  );
+  attachFiles(diff, prev.files ?? {}, next.files ?? {});
+  return { diff, next: mergeStored(reg, prev, next, filter) };
+}
+function nextTag(migrationsDir, name, ext) {
+  const s = slug(name);
+  const date = /* @__PURE__ */ new Date();
+  let tag = `${timestamp(date)}_${s}`;
+  while (existsSync2(join(migrationsDir, `${tag}${ext}`))) {
+    date.setUTCSeconds(date.getUTCSeconds() + 1);
+    tag = `${timestamp(date)}_${s}`;
+  }
+  return tag;
+}
+function prepareMigration(config, plan, name) {
+  const { diff, next } = plan;
+  if (isEmptyDiff(diff)) return null;
+  mkdirSync2(config.migrationsDir, { recursive: true });
+  const ext = migExt(config);
+  const tag = nextTag(config.migrationsDir, name ?? "migration", ext);
+  return {
+    tag,
+    file: `${tag}${ext}`,
+    content: migStore(config).render(tag, diff),
+    next,
+    up: diff.up.length,
+    down: diff.down.length
+  };
+}
+function commitMigration(config, prepared) {
+  mkdirSync2(config.migrationsDir, { recursive: true });
+  writeFileSync2(join(config.migrationsDir, prepared.file), prepared.content);
+  writeSnapshot(config.metaDir, prepared.next);
+  return {
+    created: true,
+    tag: prepared.tag,
+    file: prepared.file,
+    up: prepared.up,
+    down: prepared.down
+  };
+}
+async function recordApplied(db, config, m) {
+  await migStore(config).record(db, config.migrationsTable, {
+    tag: m.tag,
+    file: m.file,
+    checksum: checksum(m.content)
+  });
+}
+async function baseline(db, config, filter = parseFilter({})) {
+  const driver = getDriver(config.driver ?? "surrealdb");
+  const reg = driver.registry;
+  const live = await driver.introspectAll(
+    db,
+    /* @__PURE__ */ new Set([config.migrationsTable, `${config.migrationsTable}_lock`])
+  );
+  const { tables, defs, fileOf } = await loadDefs(config.schemaPath);
+  const disk = buildStored(driver, tables, defs, {
+    fileOf,
+    root: config.root
+  });
+  const pulledObjects = intersectKinds(
+    reg,
+    snapshotObjects(disk.schema),
+    live,
+    filter
+  );
+  const pulled = {
+    version: 3,
+    driver: driver.name,
+    schema: snapshotKinds(pulledObjects),
+    files: disk.files
+  };
+  const prev = readSnapshot(config.metaDir);
+  const diff = buildKindDiff(
+    reg,
+    filterKinds(reg, snapshotObjects(prev.schema), filter),
+    pulledObjects
+  );
+  attachFiles(diff, prev.files ?? {}, pulled.files ?? {});
+  const plan = {
+    diff,
+    next: mergeStored(reg, prev, pulled, filter)
+  };
+  const prepared = prepareMigration(config, plan, "baseline");
+  if (!prepared) {
+    writeSnapshot(config.metaDir, plan.next);
+    return { created: false };
+  }
+  const res = commitMigration(config, prepared);
+  await recordApplied(db, config, prepared);
+  return res;
+}
+function clearMigrationFiles(config) {
+  const migs = listMigrations(config.migrationsDir, migExt(config));
+  for (const m of migs)
+    rmSync(join(config.migrationsDir, m.file), { force: true });
+  return migs.map((m) => m.tag);
+}
+async function reconcileBaseline(db, config, prepared, drift) {
+  const mig = migStore(config);
+  await mig.ensure(db, config.migrationsTable);
+  if (drift) return "pending";
+  await mig.clear(db, config.migrationsTable);
+  await recordApplied(db, config, prepared);
+  return "applied";
+}
+function indexOfTag(migrations, tag) {
+  const i = migrations.findIndex((m) => m.tag === tag);
+  if (i < 0) throw new Error(`Unknown migration: ${tag}`);
+  return i;
+}
+async function unlock(db, config) {
+  await migStore(config).unlock(db, config.migrationsTable);
+}
+async function migrate(db, config, opts = {}) {
+  const mig = migStore(config);
+  const table = config.migrationsTable;
+  await mig.ensure(db, table);
+  const migrations = listMigrations(config.migrationsDir, migExt(config));
+  const applied = await mig.applied(db, table);
+  let pending = migrations.filter((m) => !applied.has(m.tag));
+  if (opts.to) {
+    const targetIdx = indexOfTag(migrations, opts.to);
+    const pos = new Map(migrations.map((m, i) => [m.tag, i]));
+    pending = pending.filter((m) => (pos.get(m.tag) ?? 0) <= targetIdx);
+  }
+  if (opts.count !== void 0)
+    pending = pending.slice(0, Math.max(0, opts.count));
+  await mig.lock(db, table);
+  try {
+    for (const m of pending) {
+      const content = readFileSync(join(config.migrationsDir, m.file), "utf8");
+      await mig.apply(db, table, {
+        content,
+        direction: "up",
+        record: { tag: m.tag, file: m.file, checksum: checksum(content) }
+      });
+    }
+  } finally {
+    await mig.unlock(db, table);
+  }
+  return { applied: pending };
+}
+function currentChecksum(config, m) {
+  const path = join(config.migrationsDir, m.file);
+  if (!existsSync2(path)) return "";
+  return checksum(readFileSync(path, "utf8"));
+}
+async function status(db, config) {
+  const mig = migStore(config);
+  await mig.ensure(db, config.migrationsTable);
+  const applied = await mig.applied(db, config.migrationsTable);
+  const files = listMigrations(config.migrationsDir, migExt(config));
+  const fileTags = new Set(files.map((m) => m.tag));
+  const rows = files.map((m) => {
+    const appliedSum = applied.get(m.tag);
+    return {
+      tag: m.tag,
+      applied: appliedSum !== void 0,
+      drift: appliedSum !== void 0 && appliedSum !== currentChecksum(config, m)
+    };
+  });
+  for (const tag of applied.keys())
+    if (!fileTags.has(tag)) rows.push({ tag, applied: true, missing: true });
+  return rows.sort((a, b) => a.tag.localeCompare(b.tag));
+}
+async function rollback(db, config, opts = {}) {
+  const mig = migStore(config);
+  const table = config.migrationsTable;
+  await mig.ensure(db, table);
+  const migrations = listMigrations(config.migrationsDir, migExt(config));
+  const applied = await mig.applied(db, table);
+  const appliedMigrations = migrations.filter((m) => applied.has(m.tag));
+  let toRevert;
+  if (opts.to) {
+    const targetIdx = indexOfTag(migrations, opts.to);
+    const pos = new Map(migrations.map((m, i) => [m.tag, i]));
+    toRevert = appliedMigrations.filter((m) => (pos.get(m.tag) ?? 0) > targetIdx).reverse();
+  } else {
+    toRevert = appliedMigrations.slice(-(opts.count ?? 1)).reverse();
+  }
+  await mig.lock(db, table);
+  try {
+    for (const m of toRevert) {
+      const content = readFileSync(join(config.migrationsDir, m.file), "utf8");
+      await mig.apply(db, table, {
+        content,
+        direction: "down",
+        record: { tag: m.tag, file: m.file, checksum: checksum(content) }
+      });
+    }
+  } finally {
+    await mig.unlock(db, table);
+  }
+  return toRevert;
+}
+async function seed(db, config) {
+  const path = config.seed ? resolve2(config.root, config.seed) : resolve2(config.root, "database/seed.ts");
+  if (!existsSync2(path)) throw new Error(`Seed file not found: ${path}`);
+  const mod = await makeJiti().import(path);
+  const fn = typeof mod.default === "function" ? mod.default : mod.seed;
+  if (typeof fn !== "function") {
+    throw new Error("Seed file must export a default function `(db) => \u2026`.");
+  }
+  await fn(db);
+}
+
+// src/cli/portable-diff.ts
+import {
+  buildKindDiff as buildKindDiff2,
+  formatItems,
+  getDriver as getDriver2,
+  loadDefs as loadDefs2,
+  lowerSchema as lowerSchema2,
+  ok,
+  plural,
+  style
+} from "@schemic/core";
+async function portableDiff(config, driverName, opts = {}) {
+  const driver = getDriver2(driverName);
+  const reg = driver.registry;
+  const { tables, defs } = await loadDefs2(config.schemaPath);
+  const desired = lowerSchema2(reg, driver.explode(tables, defs));
+  const conn = await driver.connect(config);
+  let live;
+  try {
+    live = await driver.introspectAll(
+      conn,
+      /* @__PURE__ */ new Set([config.migrationsTable, `${config.migrationsTable}_lock`])
+    );
+  } finally {
+    await closeQuietly(conn);
+  }
+  const diff = buildKindDiff2(reg, live, desired);
+  if (opts.json) {
+    console.log(
+      JSON.stringify({ driver: driverName, up: diff.up, down: diff.down })
+    );
+    return;
+  }
+  console.log(style.dim(`  driver: ${driverName}`));
+  if (!diff.up.length) {
+    console.log(ok("Schema is in sync with the target database."));
+    return;
+  }
+  const items = diff.items ?? [];
+  console.log(formatItems(items));
+  const n = (op) => items.filter((i) => i.op === op).length;
+  console.log(
+    style.dim(
+      `
+${plural(items.length, "change")} \u2014 ${n("add")} added, ${n("change")} changed, ${n("remove")} removed.`
+    )
+  );
+}
+async function closeQuietly(conn) {
+  const close = conn?.close;
+  if (typeof close === "function") {
+    try {
+      await close.call(conn);
+    } catch {
+    }
+  }
+}
+
+// src/cli/resolve.ts
+import {
+  driverNames,
+  getDriver as getDriver3,
+  isConnectionEntry,
+  loadProject,
+  resolveConnectionConfig
+} from "@schemic/core";
+async function ensureDriver(name) {
+  if (driverNames().includes(name)) return;
+  const pkg = `@schemic/${name}`;
+  try {
+    await import(pkg);
+  } catch (e) {
+    throw new Error(
+      `could not load the "${name}" database driver (package ${pkg}). Install it (e.g. \`bun add ${pkg}\`).
+  ${e instanceof Error ? e.message : String(e)}`
+    );
+  }
+  if (!driverNames().includes(name))
+    throw new Error(`package ${pkg} did not register a "${name}" driver.`);
+}
+function collectArg(value, prev) {
+  return [...prev, value];
+}
+function parseArgs(arg) {
+  const out = {};
+  for (const a of arg ?? []) {
+    const i = a.indexOf("=");
+    if (i < 0) throw new Error(`--arg must be key=value (got "${a}").`);
+    out[a.slice(0, i)] = a.slice(i + 1);
+  }
+  return out;
+}
+function splitAddress(address) {
+  const i = address.indexOf(":");
+  return i < 0 ? [address, void 0] : [address.slice(0, i), address.slice(i + 1)];
+}
+async function resolveTargets(opts) {
+  const { config, root } = await loadProject({ config: opts.config });
+  const args = parseArgs(opts.arg);
+  const names = Object.keys(config.connections);
+  const opened = /* @__PURE__ */ new Map();
+  const resolving = /* @__PURE__ */ new Set();
+  const entryOf = (name) => {
+    const entry = config.connections[name];
+    if (!isConnectionEntry(entry))
+      throw new Error(
+        `No connection named "${name}". Known: ${names.join(", ") || "(none)"}.`
+      );
+    return entry;
+  };
+  const resolveOneConfig = async (name, key) => {
+    const entry = entryOf(name);
+    const list = await entry.resolve(ctx);
+    const picked = key !== void 0 ? list.find((c) => c.key === key) : list.length === 1 ? list[0] : void 0;
+    if (!picked) {
+      if (key !== void 0)
+        throw new Error(`Connection "${name}" has no element with key "${key}".`);
+      throw new Error(
+        `Connection "${name}" resolved to ${list.length} connections (a collection); address one with --connection ${name}:<key> or use --all.`
+      );
+    }
+    return resolveConnectionConfig(config, name, picked, entry.driver, root);
+  };
+  const openConnection = async (name) => {
+    const cached = opened.get(name);
+    if (cached) return cached;
+    if (resolving.has(name))
+      throw new Error(`Connection cycle detected while resolving "${name}".`);
+    resolving.add(name);
+    try {
+      const resolved = await resolveOneConfig(name);
+      await ensureDriver(resolved.driver);
+      const driver = getDriver3(resolved.driver);
+      const conn = await driver.connect(resolved, opts);
+      const handle = { driver, conn, driverName: resolved.driver };
+      opened.set(name, handle);
+      return handle;
+    } finally {
+      resolving.delete(name);
+    }
+  };
+  const connections = new Proxy(
+    {},
+    {
+      get(_t, prop) {
+        if (typeof prop !== "string") return void 0;
+        return {
+          async query(sql, vars) {
+            const { driver, conn, driverName } = await openConnection(prop);
+            if (!driver.query)
+              throw new Error(
+                `the "${driverName}" driver has no \`query\` capability (needed by a connection resolver).`
+              );
+            return driver.query(conn, sql, vars);
+          }
+        };
+      }
+    }
+  );
+  const ctx = { connections, args, env: process.env };
+  const fanOut = async (name) => {
+    const entry = entryOf(name);
+    const list = await entry.resolve(ctx);
+    return list.map(
+      (conn) => resolveConnectionConfig(config, name, conn, entry.driver, root)
+    );
+  };
+  try {
+    let targets;
+    if (opts.all) {
+      targets = [];
+      for (const name of names) targets.push(...await fanOut(name));
+    } else if (opts.connection) {
+      const [name, key] = splitAddress(opts.connection);
+      targets = key !== void 0 ? [await resolveOneConfig(name, key)] : await fanOut(name);
+    } else {
+      const name = config.defaultConnection ?? (names.length === 1 ? names[0] : "default");
+      if (!config.connections[name])
+        throw new Error(
+          `No default connection. Set "defaultConnection" or pass --connection. Known: ${names.join(", ") || "(none)"}.`
+        );
+      targets = [await resolveOneConfig(name)];
+    }
+    if (!targets.length)
+      throw new Error("No connections matched \u2014 nothing to do.");
+    for (const driver of new Set(targets.map((t) => t.driver)))
+      await ensureDriver(driver);
+    return targets;
+  } finally {
+    for (const { driver, conn } of opened.values()) {
+      try {
+        await driver.close(conn);
+      } catch {
+      }
+    }
+  }
+}
+async function resolveOne(opts) {
+  if (opts.all)
+    throw new Error(
+      "--all is not supported here \u2014 this command operates on a single connection. Use --connection <name>."
+    );
+  const targets = await resolveTargets(opts);
+  if (targets.length !== 1)
+    throw new Error(
+      `--connection addressed ${targets.length} connections (a collection) \u2014 pin one with --connection <name>:<key>.`
+    );
+  return targets[0];
+}
+
+// src/cli/index.ts
+var activeDriver = (config) => getDriver4(config.driver);
+async function withDb(opts, fn) {
+  const targets = await resolveTargets(opts);
+  for (const config of targets) {
+    if (targets.length > 1) console.log(style2.bold(`
+[${config.connection}]`));
+    const driver = getDriver4(config.driver);
+    const db = await driver.connect(config, opts);
+    try {
+      await fn(db, config);
+    } finally {
+      await driver.close(db);
+    }
+  }
+}
+var errMsg = (err) => err instanceof Error ? err.message : String(err);
+function formatDuplicates(dups, root) {
+  return [...dups].map(([name, files]) => {
+    const counts = /* @__PURE__ */ new Map();
+    for (const f of files) counts.set(f, (counts.get(f) ?? 0) + 1);
+    const label = [...counts].map(([f, n]) => {
+      const rel = relative2(root, f);
+      return n > 1 ? `${rel} (\xD7${n})` : rel;
+    }).join(", ");
+    return `${name} \u2014 ${label}`;
+  });
+}
+var duplicateHeader = (n) => `${plural2(n, "table")} defined more than once (last definition silently wins):`;
+function run(action) {
+  action().then(
+    () => process.exit(process.exitCode ?? 0),
+    (err) => {
+      console.error(`
+${fail(errMsg(err))}`);
+      process.exit(1);
+    }
+  );
+}
+async function promptTitle() {
+  if (!process.stdin.isTTY) return void 0;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (await rl.question("Migration title: ")).trim();
+    return answer || void 0;
+  } finally {
+    rl.close();
+  }
+}
+async function confirmPrompt(question) {
+  if (!process.stdin.isTTY) return false;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const a = (await rl.question(`${question} [y/N] `)).trim().toLowerCase();
+    return a === "y" || a === "yes";
+  } finally {
+    rl.close();
+  }
+}
+function diffSummary(registry, diff, opts, pending) {
+  const summary = [];
+  if (!isEmptyDiff2(diff)) {
+    const kinds = summarizeKinds(registry, diff.items ?? []);
+    summary.push(
+      `${plural2(diff.up.length, "change")} ${opts.live ? "vs the live database" : "vs the snapshot"}${kinds ? ` \u2014 ${kinds}` : ""}.`
+    );
+  }
+  if (pending !== void 0)
+    summary.push(`${plural2(pending, "migration")} pending.`);
+  return summary.length ? `
+${style2.dim(summary.join("\n"))}` : "";
+}
+function reportDiff(registry, diff, opts, pending) {
+  console.log(
+    formatDiff(diff, { down: opts.down, full: opts.full, inline: opts.inline })
+  );
+  const summary = diffSummary(registry, diff, opts, pending);
+  if (summary) console.log(summary);
+}
+function watchLoop(config, task, cleanup) {
+  return new Promise(() => {
+    let timer;
+    let running = false;
+    let queued = false;
+    const fire = async () => {
+      if (running) {
+        queued = true;
+        return;
+      }
+      running = true;
+      console.log(style2.dim(`
+\u2014 ${(/* @__PURE__ */ new Date()).toLocaleTimeString()} \u2014`));
+      try {
+        await task();
+      } catch (err) {
+        console.error(fail(errMsg(err)));
+      }
+      running = false;
+      if (queued) {
+        queued = false;
+        void fire();
+      }
+    };
+    const watcher = fsWatch(
+      config.schemaPath,
+      { recursive: !config.schemaIsFile },
+      () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => void fire(), 150);
+      }
+    );
+    console.log(
+      style2.dim(
+        `Watching ${relative2(config.root, config.schemaPath)} for changes \u2014 ctrl-c to stop.`
+      )
+    );
+    void fire();
+    const stop = () => {
+      watcher.close();
+      clearTimeout(timer);
+      Promise.resolve(cleanup?.()).finally(() => process.exit(0));
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+  });
+}
+var configFlag = (cmd) => cmd.option("-c, --config <path>", "path to schemic.config.ts");
+var dbFlags = (cmd) => configFlag(cmd).option(
+  "--connection <name>",
+  "target a specific connection (or <name>:<key> within a collection)"
+).option("--all", "run against every connection (collections fanned out)").option(
+  "--arg <key=value>",
+  "value passed to connection resolvers (repeatable)",
+  collectArg,
+  []
+).option("--url <url>", "override the connection endpoint").option("--namespace <ns>", "override the namespace").option("--database <db>", "override the database").option("--username <user>", "override the auth username").option("--password <pass>", "override the auth password").addOption(
+  new Option("--auth-level <level>", "auth level").choices([
+    "root",
+    "namespace",
+    "database"
+  ])
+);
+var program = new Command();
+program.name("schemic").description(
+  "Schema-as-code migrations for any database \u2014 generate DDL, diff, and migrate via drivers"
+).version("0.1.0-alpha.0").showHelpAfterError("(run `schemic --help` for usage)").addHelpText(
+  "after",
+  `
+Examples:
+  $ schemic init                 scaffold database/ (schemas + migrations) + config
+  $ schemic gen add_users        create a migration from schema changes
+  $ schemic migrate              apply pending migrations
+  $ schemic push --watch         keep the database in sync while you edit
+  $ schemic diff --live          show how the schema differs from the live database
+`
+);
+program.configureHelp({
+  visibleOptions(cmd) {
+    const opts = Help.prototype.visibleOptions.call(this, cmd);
+    const negated = new Set(
+      opts.filter((o) => o.negate).map((o) => o.attributeName())
+    );
+    this._collapsible = new Set(
+      [...negated].filter(
+        (n) => opts.some((o) => !o.negate && o.attributeName() === n)
+      )
+    );
+    return opts.filter(
+      (o) => !(o.negate && this._collapsible?.has(o.attributeName()))
+    );
+  },
+  optionTerm(option) {
+    const term = Help.prototype.optionTerm.call(this, option);
+    if (option.negate) return term.replace("--no-", "--[no-]");
+    if (this._collapsible?.has(option.attributeName()))
+      return term.replace(`--${option.name()}`, `--[no-]${option.name()}`);
+    return term;
+  }
+});
+program.command("init").description("Scaffold database/ (schemas + migrations) and a config file").option(
+  "--driver <name>",
+  "database driver to scaffold for (default surrealdb)"
+).action((opts) => {
+  run(async () => {
+    const name = opts.driver ?? "surrealdb";
+    await ensureDriver(name);
+    const { created, skipped } = init(process.cwd(), getDriver4(name));
+    for (const f of created) console.log(`  ${style2.green("+")} ${f}`);
+    for (const f of skipped)
+      console.log(style2.dim(`  \xB7 ${f} (exists, skipped)`));
+    console.log(
+      created.length ? `
+${ok2("Initialized. Edit database/schema, then run `schemic gen`.")}` : "\nNothing to do \u2014 already initialized."
+    );
+  });
+});
+kindFlags(
+  dbFlags(
+    program.command("diff").description("Show pending schema changes without writing a migration")
+  )
+).option("--down", "also show the rollback (down) statements").option("--live", "diff against the live database instead of the snapshot").option("--ts", "show the change as TypeScript schema instead of DDL").option("--watch", "re-run on schema changes").option("--full", "show the full schema SQL, not just the changed parts").option(
+  "-p, --patch",
+  "output a unified diff (e.g. to pipe to a diff viewer)"
+).option(
+  "--pager [cmd]",
+  "page through your git diff viewer (or <cmd>); off by default"
+).option(
+  "--inline",
+  "render changes as an inline word-diff instead of separate -/+ lines"
+).option("--json", "output the diff as JSON").option(
+  "--driver <name>",
+  "target database driver (default from config, or 'surreal')"
+).action(
+  (opts) => {
+    run(async () => {
+      const config = await resolveOne(opts);
+      const driverName = opts.driver ?? config.driver ?? "surrealdb";
+      await ensureDriver(driverName);
+      const driver = getDriver4(driverName);
+      const diffLive = driver.diffLive;
+      if (!diffLive) {
+        await portableDiff(config, driverName, { json: opts.json });
+        return;
+      }
+      const filter = parseFilter2(opts);
+      const pager = opts.watch || opts.pager === void 0 || opts.pager === false ? void 0 : typeof opts.pager === "string" ? opts.pager : resolvePager();
+      const emit = async (diff, pending) => {
+        if (opts.json) {
+          console.log(
+            JSON.stringify({ up: diff.up, down: diff.down, pending })
+          );
+        } else if ((opts.patch || pager) && !isEmptyDiff2(diff)) {
+          const patch = formatPatch(diff);
+          if (pager) await pipeThroughPager(pager, patch);
+          else process.stdout.write(patch);
+          const summary = diffSummary(driver.registry, diff, opts, pending);
+          if (summary) console.log(summary);
+        } else {
+          reportDiff(driver.registry, diff, opts, pending);
+        }
+      };
+      const persistent = opts.watch && opts.live ? await driver.connect(config, opts) : void 0;
+      const once = async () => {
+        if (opts.ts) {
+          const loc = await existingTables(config.schemaPath);
+          const fileFor = (kind, name) => {
+            const abs = kind === "table" ? loc.get(name) : void 0;
+            return abs ? relative2(config.root, abs) : relative2(
+              config.root,
+              join2(
+                config.schemaPath,
+                driver.registry.display(kind).folder,
+                `${name}.ts`
+              )
+            );
+          };
+          const single = config.schemaIsFile ? relative2(config.root, config.schemaPath) : void 0;
+          const showTsDiff = async (cur, des, matchMsg) => {
+            if (opts.json) {
+              console.log(
+                JSON.stringify({
+                  current: Object.fromEntries(cur),
+                  desired: Object.fromEntries(des)
+                })
+              );
+              return;
+            }
+            const files = [.../* @__PURE__ */ new Set([...cur.keys(), ...des.keys()])].sort();
+            const changed = files.filter(
+              (f) => (cur.get(f) ?? "") !== (des.get(f) ?? "")
+            );
+            if (!changed.length) {
+              console.log(ok2(matchMsg));
+            } else if (pager || opts.patch) {
+              const patch = changed.map(
+                (f) => unifiedDiff(cur.get(f) ?? "", des.get(f) ?? "", f)
+              ).join("");
+              if (pager) await pipeThroughPager(pager, patch);
+              else process.stdout.write(patch);
+            } else {
+              console.log(
+                changed.map(
+                  (f) => `${style2.bold(f)}
+${lineDiff(cur.get(f) ?? "", des.get(f) ?? "")}`
+                ).join("\n\n")
+              );
+            }
+          };
+          if (opts.live) {
+            if (!driver.diffTsLive)
+              throw new Error(
+                `the "${driverName}" driver does not support \`diff --ts --live\`.`
+              );
+            const db = persistent ?? await driver.connect(config, opts);
+            try {
+              const { current, desired } = await driver.diffTsLive(
+                db,
+                config,
+                filter,
+                fileFor,
+                single
+              );
+              await showTsDiff(
+                current,
+                desired,
+                "Schema matches the live database."
+              );
+            } finally {
+              if (!persistent) await driver.close(db);
+            }
+          } else {
+            if (!driver.renderSchema)
+              throw new Error(
+                `the "${driverName}" driver does not support \`diff --ts\`.`
+              );
+            const prev = readSnapshot2(config.metaDir);
+            const prevObjects = snapshotObjects2(prev.schema);
+            const { tables, defs } = await loadDefs3(config.schemaPath);
+            const desiredObjects = lowerSchema3(
+              driver.registry,
+              driver.explode(tables, defs)
+            );
+            await showTsDiff(
+              driver.renderSchema(prevObjects, filter, fileFor, single),
+              driver.renderSchema(desiredObjects, filter, fileFor, single),
+              prevObjects.length ? "Schema matches the snapshot." : "No schema to render."
+            );
+          }
+          return;
+        }
+        if (opts.live) {
+          const db = persistent ?? await driver.connect(config, opts);
+          try {
+            const diff = await diffLive(db, config, filter);
+            const pending = (await status(db, config)).filter(
+              (r) => !r.applied
+            ).length;
+            await emit(diff, pending);
+          } finally {
+            if (!persistent) await driver.close(db);
+          }
+        } else {
+          await emit((await planMigration(config, filter)).diff);
+        }
+      };
+      if (!opts.watch) return once();
+      await watchLoop(
+        config,
+        once,
+        persistent ? () => driver.close(persistent) : void 0
+      );
+    });
+  }
+);
+var genAction = (name, opts) => {
+  run(async () => {
+    const config = await resolveOne(opts);
+    const filter = parseFilter2(opts);
+    let squashed = null;
+    if (opts.baseline) {
+      const existing = listMigrations2(
+        config.migrationsDir,
+        activeDriver(config).migrations?.extension ?? ".surql"
+      );
+      if (existing.length) {
+        const migDir = relative2(config.root, config.migrationsDir);
+        const proceed = opts.force || await confirmPrompt(
+          `Replace ${plural2(existing.length, "migration")} in ${migDir} with a single baseline?`
+        );
+        if (!proceed) {
+          throw new Error(
+            `${plural2(existing.length, "migration")} already exist in ${migDir} \u2014 a baseline would re-define objects they already created.
+  Re-run \`schemic gen --baseline --force\` to replace them with one fresh baseline.`
+          );
+        }
+        squashed = clearMigrationFiles(config);
+      }
+    }
+    const plan = await planMigration(config, filter, {
+      baseline: opts.baseline
+    });
+    if (isEmptyDiff2(plan.diff)) {
+      console.log(ok2("No schema changes \u2014 nothing to generate."));
+      return;
+    }
+    const kinds = summarizeKinds(
+      activeDriver(config).registry,
+      plan.diff.items ?? []
+    );
+    console.log(
+      `${plural2(plan.diff.up.length, "change")} to migrate${kinds ? ` \u2014 ${kinds}` : ""}.`
+    );
+    console.log(formatDiff(plan.diff, {}));
+    const title = name ?? (opts.baseline ? "baseline" : opts.yes ? void 0 : await promptTitle());
+    const prepared = prepareMigration(config, plan, title);
+    if (!prepared) {
+      console.log(ok2("No schema changes \u2014 nothing to generate."));
+      return;
+    }
+    const res = commitMigration(config, prepared);
+    console.log(
+      `${ok2(res.file ?? "migration written")}  ${style2.dim(`(+${res.up} up / ${res.down} down)`)}`
+    );
+    if (squashed) {
+      console.log(
+        style2.dim(`  replaced ${plural2(squashed.length, "migration")}.`)
+      );
+      try {
+        const driver = activeDriver(config);
+        const diffLive = driver.diffLive;
+        if (!diffLive)
+          throw new Error(
+            `the "${config.driver ?? "surrealdb"}" driver does not support live reconcile`
+          );
+        const db = await driver.connect(config, opts);
+        try {
+          const drift = !isEmptyDiff2(await diffLive(db, config, filter));
+          const state = await reconcileBaseline(db, config, prepared, drift);
+          console.log(
+            style2.dim(
+              state === "applied" ? "  database matched the schema \u2014 baseline recorded as applied." : "  database differs from the schema \u2014 baseline left pending; run `schemic migrate`."
+            )
+          );
+        } finally {
+          await driver.close(db);
+        }
+      } catch (e) {
+        console.log(
+          style2.dim(
+            `  database not reconciled (${errMsg(e)}) \u2014 baseline is pending; run \`schemic migrate\` to apply it.`
+          )
+        );
+      }
+    }
+  });
+};
+var addGenCommand = (cmd) => {
+  kindFlags(dbFlags(cmd)).option("-y, --yes", "use the given/default name without prompting").option(
+    "--baseline",
+    "regenerate one fresh baseline from an empty snapshot (replaces existing migrations)"
+  ).option(
+    "--force",
+    "with --baseline, replace existing migrations without confirmation"
+  ).action(genAction);
+};
+addGenCommand(
+  program.command("gen [name]").description("Diff schemas, preview the migration script, and write it")
+);
+addGenCommand(program.command("generate [name]", { hidden: true }));
+var snapshot = program.command("snapshot").description(
+  "Manage the migration snapshot (what `schemic gen`/`schemic diff` compare against)"
+);
+configFlag(
+  snapshot.command("reset").description(
+    "Clear the snapshot \u2014 the next `schemic gen` baselines the full schema"
+  )
+).action((opts) => {
+  run(async () => {
+    const config = await resolveOne(opts);
+    writeSnapshot2(config.metaDir, EMPTY_STORED2);
+    console.log(ok2("Snapshot cleared."));
+    const existing = listMigrations2(
+      config.migrationsDir,
+      activeDriver(config).migrations?.extension ?? ".surql"
+    );
+    if (existing.length) {
+      console.log(
+        style2.dim(
+          `  ${plural2(existing.length, "migration")} still on disk \u2014 run \`schemic gen --baseline --force\` to replace them with one fresh baseline. (A plain \`schemic gen\` would add a baseline alongside them.)`
+        )
+      );
+    } else {
+      console.log(
+        style2.dim("  The next `schemic gen` will baseline the full schema.")
+      );
+    }
+  });
+});
+dbFlags(
+  program.command("migrate [count]").alias("up").description(
+    "Apply pending migrations (all, the next N, or up to --to <tag>)"
+  ).option("--to <tag>", "apply up to and including this migration")
+).action((count, opts) => {
+  run(
+    () => withDb(opts, async (db, config) => {
+      const n = count === void 0 ? void 0 : Math.max(1, Number.parseInt(count, 10) || 1);
+      const { applied } = await migrate(db, config, { count: n, to: opts.to });
+      if (!applied.length) {
+        console.log(ok2("Up to date \u2014 no pending migrations."));
+        return;
+      }
+      for (const e of applied) console.log(`  ${style2.green("\u2191")} ${e.tag}`);
+      console.log(`
+${ok2(`Applied ${plural2(applied.length, "migration")}.`)}`);
+    })
+  );
+});
+dbFlags(
+  program.command("status").description("Show applied vs pending migrations")
+).option("--json", "output the status as JSON").action((opts) => {
+  run(
+    () => withDb(opts, async (db, config) => {
+      const rows = await status(db, config);
+      if (opts.json) {
+        console.log(JSON.stringify(rows));
+        return;
+      }
+      if (!rows.length) {
+        console.log("No migrations yet. Run `schemic gen`.");
+        return;
+      }
+      for (const r of rows) {
+        if (r.missing) {
+          console.log(
+            `  ${style2.yellow("\u26A0 missing")}  ${r.tag} ${style2.dim("(applied in the DB, file deleted)")}`
+          );
+        } else if (r.drift) {
+          console.log(
+            `  ${style2.yellow("\u26A0 drift")}    ${r.tag} ${style2.dim("(file changed after apply)")}`
+          );
+        } else if (r.applied) {
+          console.log(`  ${style2.green("\u2713 applied")}  ${r.tag}`);
+        } else {
+          console.log(style2.dim(`  \xB7 pending  ${r.tag}`));
+        }
+      }
+      const pending = rows.filter((r) => !r.applied).length;
+      const drifted = rows.filter((r) => r.drift).length;
+      const missing = rows.filter((r) => r.missing).length;
+      const parts = [plural2(rows.length, "migration"), `${pending} pending`];
+      if (drifted) parts.push(`${drifted} drifted`);
+      if (missing) parts.push(`${missing} missing`);
+      console.log(`
+${style2.dim(`${parts.join(", ")}.`)}`);
+      if (missing) {
+        console.log(
+          style2.dim(
+            "  Missing migrations were applied but their files are gone (e.g. after removing migrations or `snapshot reset`)."
+          )
+        );
+      }
+    })
+  );
+});
+dbFlags(
+  program.command("check").description(
+    "Validate schemas, then replay migrations to confirm they reproduce the schema"
+  ).option(
+    "--schema",
+    "validate the schema only \u2014 skip the migration replay (no database)"
+  )
+).action((opts) => {
+  run(async () => {
+    const config = await resolveOne(opts);
+    const driver = activeDriver(config);
+    const dups = await duplicateTables(config.schemaPath);
+    if (dups.size) {
+      const lines = formatDuplicates(dups, config.root).map((l) => `  ${l}`);
+      throw new Error(`${duplicateHeader(dups.size)}
+${lines.join("\n")}`);
+    }
+    const { tables, defs } = await loadDefs3(config.schemaPath);
+    const kinds = summarizeKinds(
+      driver.registry,
+      lowerSchema3(driver.registry, driver.explode(tables, defs))
+    );
+    console.log(ok2(`Schemas valid${kinds ? ` \u2014 ${kinds}` : " (no objects)"}.`));
+    if (opts.schema) return;
+    if (!driver.checkReplay) {
+      throw new Error(
+        `the "${config.driver ?? "surrealdb"}" driver does not support migration replay \u2014 run \`schemic check --schema\` to validate the schema only.`
+      );
+    }
+    const diff = await driver.checkReplay(
+      config,
+      opts,
+      parseFilter2({}),
+      (m) => console.log(style2.dim(m))
+    );
+    if (isEmptyDiff2(diff)) {
+      console.log(ok2("Migrations reproduce the schema."));
+      return;
+    }
+    console.log(
+      `
+${fail("Drift \u2014 migrations do not reproduce the schema:")}
+`
+    );
+    console.log(formatDiff(diff, {}));
+    console.log(
+      `
+${style2.dim(`${summarizeKinds(driver.registry, diff.items ?? [])} differ. \`schemic gen\` writes a migration to reconcile.`)}`
+    );
+    process.exitCode = 1;
+  });
+});
+dbFlags(
+  program.command("doctor").description("Print resolved config and test the connection")
+).action((opts) => {
+  run(async () => {
+    const config = await resolveOne(opts);
+    const row = (k, v) => console.log(style2.dim(`  ${k.padEnd(11)} ${v}`));
+    console.log(style2.bold("Project"));
+    row("root", config.root);
+    row("connection", `${config.connection} (${config.driver})`);
+    row("migrations", relative2(config.root, config.migrationsDir));
+    console.log(style2.bold("\nSchema"));
+    row(
+      "source",
+      `${relative2(config.root, config.schemaPath)} (${config.schemaIsFile ? "file" : "directory"})`
+    );
+    try {
+      const defs = await loadSchemas(config.schemaPath);
+      row(
+        "tables",
+        defs.length ? `${plural2(defs.length, "table")} \u2014 ${defs.map((t) => t.name).join(", ")}` : "(none found)"
+      );
+      const dups = await duplicateTables(config.schemaPath);
+      if (dups.size) {
+        console.log(`  ${fail(duplicateHeader(dups.size))}`);
+        for (const line of formatDuplicates(dups, config.root))
+          console.log(style2.dim(`    ${line}`));
+        process.exitCode = 1;
+      }
+    } catch (e) {
+      console.log(`  ${fail(e instanceof Error ? e.message : String(e))}`);
+    }
+    console.log(style2.bold("\nConnection"));
+    const secret = /pass|secret|token|key/i;
+    const params = Object.entries(config.params);
+    if (params.length) {
+      for (const [k, v] of params)
+        row(k, secret.test(k) ? "***" : String(v ?? ""));
+    } else {
+      row("params", "(none)");
+    }
+    console.log(style2.bold("\nVersions"));
+    row("@schemic/core", program.version() ?? "?");
+    row("node", process.version);
+    console.log(style2.bold("\nStatus"));
+    try {
+      const driver = activeDriver(config);
+      const db = await driver.connect(config, opts);
+      const info = driver.serverInfo ? await driver.serverInfo(db) : config.driver ?? "surrealdb";
+      console.log(`  ${ok2(`connected \u2014 ${info}`)}`);
+      await driver.close(db);
+    } catch (e) {
+      console.log(`  ${fail(e instanceof Error ? e.message : String(e))}`);
+      process.exitCode = 1;
+    }
+  });
+});
+dbFlags(
+  program.command("rollback [count]").alias("down").description("Roll back applied migrations (last N, or back to --to <tag>)").option("--to <tag>", "roll back everything applied after this migration")
+).action((count, opts) => {
+  run(
+    () => withDb(opts, async (db, config) => {
+      const reverted = await rollback(db, config, {
+        to: opts.to,
+        count: opts.to || count === void 0 ? void 0 : Math.max(1, Number.parseInt(count, 10) || 1)
+      });
+      if (!reverted.length) {
+        console.log(ok2("Nothing to roll back."));
+        return;
+      }
+      for (const e of reverted) console.log(`  ${style2.yellow("\u2193")} ${e.tag}`);
+      console.log(
+        `
+${ok2(`Rolled back ${plural2(reverted.length, "migration")}.`)}`
+      );
+    })
+  );
+});
+configFlag(
+  program.command("new <kind> <name>").description(
+    "Scaffold a new schema file for an entity, e.g. `sc new table user`"
+  )
+).action((kind, name, opts) => {
+  run(async () => {
+    const config = await resolveOne(opts);
+    const driver = activeDriver(config);
+    if (!driver.scaffoldEntity)
+      throw new Error(`the "${config.driver}" driver can't scaffold entities.`);
+    if (config.schemaIsFile)
+      throw new Error(
+        "`schemic new` needs a schema directory \u2014 your schema is a single file."
+      );
+    const content = driver.scaffoldEntity(kind, name);
+    const target = join2(
+      config.schemaPath,
+      driver.registry.display(kind).folder,
+      `${name}.ts`
+    );
+    if (existsSync3(target))
+      throw new Error(`${relative2(config.root, target)} already exists.`);
+    mkdirSync3(dirname2(target), { recursive: true });
+    writeFileSync3(target, content);
+    console.log(
+      `${ok2(relative2(config.root, target))}  ${style2.dim("\u2014 author its fields, then `schemic gen`")}`
+    );
+  });
+});
+dbFlags(
+  program.command("unlock").description("Clear a stale migration lock")
+).action((opts) => {
+  run(
+    () => withDb(opts, async (db, config) => {
+      await unlock(db, config);
+      console.log(ok2("Migration lock cleared."));
+    })
+  );
+});
+kindFlags(
+  dbFlags(
+    program.command("push").alias("sync").description(
+      "Reconcile the live database with your schema (no migration files)"
+    ).option("--no-prune", "keep objects that were removed from the schema").option("--dry-run", "preview the changes without applying them").option("--watch", "re-sync on schema changes")
+  )
+).action(
+  (opts) => {
+    run(async () => {
+      const config = await resolveOne(opts);
+      const driver = activeDriver(config);
+      const filter = parseFilter2(opts);
+      const diffLive = driver.diffLive;
+      const syncPlan = driver.syncPlan;
+      if (!diffLive || !syncPlan)
+        throw new Error(
+          `the "${config.driver ?? "surrealdb"}" driver does not support \`push\`.`
+        );
+      const once = async (db2) => {
+        const diff = await diffLive(db2, config, filter);
+        const stmts = syncPlan(diff, opts.prune);
+        if (!stmts.length) {
+          console.log(ok2("Database already matches the schema."));
+          return;
+        }
+        const items = (diff.items ?? []).filter(
+          (it) => opts.prune !== false || it.op !== "remove"
+        );
+        console.log(formatItems2(items));
+        const kinds = summarizeKinds(driver.registry, items);
+        if (opts.dryRun) {
+          console.log(
+            `
+${style2.dim(`${plural2(stmts.length, "change")}${kinds ? ` \u2014 ${kinds}` : ""} \u2014 run \`schemic push\` to apply.`)}`
+          );
+          return;
+        }
+        await driver.apply(db2, stmts);
+        const pruned = opts.prune === false ? 0 : (diff.items ?? []).filter((it) => it.op === "remove").length;
+        console.log(
+          `
+${ok2(`synced ${plural2(stmts.length - pruned, "object")}${pruned ? `, pruned ${pruned}` : ""}${kinds ? ` (${kinds})` : ""}.`)}`
+        );
+      };
+      if (!opts.watch) {
+        await withDb(opts, (db2) => once(db2));
+        return;
+      }
+      const db = await driver.connect(config, opts);
+      await watchLoop(
+        config,
+        () => once(db),
+        () => driver.close(db)
+      );
+    });
+  }
+);
+dbFlags(
+  program.command("seed").description("Run the project's seed script")
+).action((opts) => {
+  run(
+    () => withDb(opts, async (db, config) => {
+      await seed(db, config);
+      console.log(ok2("Seed complete."));
+    })
+  );
+});
+function printPullPlan(plan) {
+  for (const f of plan.files) {
+    if (f.action === "unchanged") continue;
+    console.log(`
+${actionLabel(f.action)} ${style2.bold(f.rel)}`);
+    if (f.action === "delete") {
+      console.log(
+        style2.dim(
+          `  whole file removed \u2014 ${f.localOnly.objects.join(", ")} not in the database`
+        )
+      );
+      continue;
+    }
+    console.log(
+      lineDiff(f.before, f.after).split("\n").map((l) => `  ${l}`).join("\n")
+    );
+  }
+}
+function printLocalOnly(files) {
+  console.log(`
+${style2.yellow("! local-only schema, not in the database:")}`);
+  for (const f of files) {
+    for (const fld of f.localOnly.fields)
+      console.log(
+        style2.dim(`    ${f.rel}: ${fld.exportName} \u2192 ${fld.fields.join(", ")}`)
+      );
+    for (const obj of f.localOnly.objects)
+      console.log(style2.dim(`    ${f.rel}: ${obj} (whole definition)`));
+  }
+  console.log(style2.dim("  keep with --merge, or drop with --discard."));
+}
+kindFlags(
+  dbFlags(
+    program.command("pull").description("Generate/update Zod schema files from the live database").option("--write", "apply the changes (default: preview only)").option(
+      "--merge",
+      "keep local-only fields/objects (default: mirror the DB)"
+    ).option(
+      "--discard",
+      "drop local-only fields/objects to mirror the DB exactly"
+    )
+  )
+).action(
+  (opts) => {
+    run(
+      () => withDb(opts, async (db, config) => {
+        const driver = activeDriver(config);
+        if (!driver.planPull)
+          throw new Error(
+            `the "${config.driver ?? "surrealdb"}" driver does not support \`pull\`.`
+          );
+        const plan = await driver.planPull(db, config, {
+          filter: parseFilter2(opts),
+          keepLocal: opts.merge
+        });
+        printPullPlan(plan);
+        const changed = plan.files.filter((f) => f.action !== "unchanged");
+        const atRisk = opts.merge ? [] : plan.files.filter(
+          (f) => f.localOnly.fields.length || f.localOnly.objects.length
+        );
+        if (!changed.length && !atRisk.length) {
+          console.log(ok2("Schema files already match the database."));
+          return;
+        }
+        if (!opts.write) {
+          if (changed.length)
+            console.log(
+              `
+${style2.dim(`${plural2(changed.length, "file")} would change \u2014 run \`schemic pull --write\` to apply.`)}`
+            );
+          if (atRisk.length) printLocalOnly(atRisk);
+          return;
+        }
+        if (atRisk.length && !opts.discard) {
+          printLocalOnly(atRisk);
+          throw new Error(
+            "pull would overwrite local-only schema \u2014 re-run with --merge to keep it or --discard to mirror the database."
+          );
+        }
+        const written = applyPull(plan);
+        const base = await baseline(db, config);
+        const removed = plan.files.filter((f) => f.action === "delete").length;
+        const kept = opts.merge ? [] : plan.files.filter(
+          (f) => f.action === "unchanged" && f.localOnly.objects.length
+        );
+        console.log(
+          `
+${ok2(`Pulled ${plural2(written.length, "file")} from the database${removed ? ` (${removed} removed)` : ""}.`)}`
+        );
+        if (base.created)
+          console.log(
+            style2.dim(
+              `  baseline ${base.tag} recorded (snapshot synced, marked applied).`
+            )
+          );
+        if (kept.length)
+          console.log(
+            style2.dim(
+              `  ${plural2(kept.length, "file")} with local-only entities mixed with other code left in place \u2014 remove those entities by hand.`
+            )
+          );
+      })
+    );
+  }
+);
+if (process.argv.length <= 2) {
+  program.outputHelp();
+  process.exit(0);
+}
+program.parse();