@supacloud/lite 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.20.0](https://github.com/vibeunion/supacloud/compare/supacloud-lite-v0.19.0...supacloud-lite-v0.20.0) (2026-10-05)
+
+
+### Features
+
+* add agent backend authoring, runtime and observability workflows ([#1648](https://github.com/vibeunion/supacloud/issues/1648)) ([59a66d1](https://github.com/vibeunion/supacloud/commit/59a66d184a47d19c7f8895f24a6ba2c7e74e93d0))
+
 ## [0.19.0](https://github.com/vibeunion/supacloud/compare/supacloud-lite-v0.18.0...supacloud-lite-v0.19.0) (2026-10-03)
 
 

package/README.md

@@ -162,7 +162,7 @@ supacloud-lite keys [--service-role]
 supacloud-lite gen types [-o database.types.ts]
 supacloud-lite db reset
 supacloud-lite db diff [-f migration_name]
-supacloud-lite db pull [migration_name]
+supacloud-lite db pull [migration_name] [--baseline]
 supacloud-lite db check [--module-file supabase/db/modules.ts]
 supacloud-lite snapshot create [-o backup.tar.gz]
 supacloud-lite snapshot restore <backup.tar.gz> [--force]
@@ -174,6 +174,10 @@ supacloud-lite version
 
 首次初始化或 state 目录不存在/为空时，先运行 `supacloud-lite migrate`。`db reset` 只接受已经初始化且保留有效 `secrets.json` 标记的 state；它不会为 reset 创建或覆盖项目 secrets。
 
+`db diff` / `db pull` 只读检查现有数据库，不会初始化 live backend 或自动应用待执行迁移；已应用历史必须与本地迁移精确一致。生成的 DDL 先在不含 seed 的临时影子数据库中重放并核对受支持的 Catalog。检测到不能完整重建的 view/function/trigger/policy、权限、RLS 或非追加 enum 变更时拒绝生成，改用官方 Supabase pg-delta；这不是完整 PostgreSQL Catalog 覆盖。
+
+`db pull` 默认写入 `.supacloud-lite/schema-drafts`，不修改迁移账本。仅对已审核且已存在于数据库的变更使用 `--baseline`：它记录账本而不执行 DDL，提交确认后才发布到迁移目录，禁止覆盖已有文件。若失败后留下 `.sql.pending`，停止启动/迁移，保留文件并检查对应账本版本与 SQL；只有确认匹配提交后才能发布该文件。不要猜测提交结果或直接重放捕获的 DDL。库调用方在 `baseline: false` 时也应把 `migrationsDir` 指向草稿目录。恢复步骤及文件/数据库非原子边界见仓库 `docs/select-agent-backend.md`。
+
 `db check` 是只读治理命令：加载 `@supacloud/db` 的 `defineDatabaseModule` 清单（默认 `supabase/db/modules.ts`），对声明的 SQL 源做静态 lint，并把声明的表/RLS 策略/RPC/授权与 Lite 数据库的真实 Catalog 对账（pg_policy、pg_proc、grants）。存在 error 级问题（声明缺失、RLS 未启用、security definer 未固定 search_path、PUBLIC 授权）时以非零退出码结束，可接入 CI；不会修改数据库。
 
 通用参数：
@@ -562,7 +566,7 @@ supacloud-lite keys [--service-role]
 supacloud-lite gen types [-o database.types.ts]
 supacloud-lite db reset
 supacloud-lite db diff [-f migration_name]
-supacloud-lite db pull [migration_name]
+supacloud-lite db pull [migration_name] [--baseline]
 supacloud-lite db check [--module-file supabase/db/modules.ts]
 supacloud-lite snapshot create [-o backup.tar.gz]
 supacloud-lite snapshot restore <backup.tar.gz> [--force]
@@ -713,6 +717,24 @@ In-memory databases have no persistable data, so `snapshot` and `upgrade` reject
 
 ### Application Compatibility
 
+`db diff` / `db pull` inspect existing live state without backend bootstrap or
+pending migration application. Applied history must match local migrations
+exactly. Generated DDL is replayed in a disposable, seed-free shadow and checked
+against the supported catalog. Detected unsupported view/function/trigger/policy,
+ACL, RLS or non-append enum changes fail closed with pg-delta guidance; this is
+not complete PostgreSQL catalog coverage.
+
+CLI `db pull` writes to `.supacloud-lite/schema-drafts` by default and never
+implicitly updates the ledger. Use `--baseline` only for reviewed DDL already
+present in live state: it records history without executing DDL and publishes
+the migration after confirmed commit, without overwriting existing files. On an
+uncertain outcome, stop startup/migration, retain `.sql.pending`, and compare the
+ledger version and exact SQL before publishing or retrying. Never guess commit
+state or replay captured DDL against the already-changed database. Library
+callers should also use a draft `migrationsDir` when `baseline` is false. See
+repository document `docs/select-agent-backend.md` for recovery and the
+non-atomic filesystem/database boundary.
+
 Lite accepts flat SQL and timestamp folders containing `migration.sql`, validates
 duplicate versions and applied SQL drift before pending migrations, and reuses
 `@supacloud/db` for reviewed target bindings. `migrate --json` emits a hash-only

package/dist/cli.js

@@ -2,13 +2,13 @@
 // @bun
 
 // src/cli.ts
-import { existsSync as existsSync4 } from "fs";
+import { existsSync as existsSync5 } from "fs";
 import { mkdir as mkdir7, rm as rm6, writeFile as writeFile7 } from "fs/promises";
 import { dirname as dirname8, join as join10, resolve as resolve6 } from "path";
 // package.json
 var package_default = {
   name: "@supacloud/lite",
-  version: "0.19.0",
+  version: "0.20.0",
   description: "Bun-native, single-project Supabase-compatible backend powered by PGlite or native PostgreSQL",
   type: "module",
   license: "Apache-2.0",
@@ -6249,7 +6249,7 @@ begin
   perform set_config('TimeZone', configured_timezone, false);
 end $$;
 `;
-async function createPgliteEngine(dataDir) {
+async function createPgliteEngine(dataDir, options = {}) {
   const releaseLock = await acquireDataDirLock(dataDir, "PGlite");
   let PGlite, extensions;
   const standaloneAssets = getStandaloneAssets();
@@ -6304,7 +6304,8 @@ async function createPgliteEngine(dataDir) {
     });
     await pg.waitReady;
     try {
-      await pg.exec(INITIALIZE_TIMEZONE_SQL);
+      if (!options.inspectOnly)
+        await pg.exec(INITIALIZE_TIMEZONE_SQL);
     } catch (error) {
       const [cleanup] = await Promise.allSettled([pg.close()]);
       if (cleanup.status === "rejected") {
@@ -11123,9 +11124,120 @@ async function snapshotSchema(db, schema = "public") {
   const enums = new Map;
   for (const r of en.rows)
     enums.set(r.name, r.labels);
-  return { tables, constraints, indexes, enums };
+  const viewRows = await db.query(`select c.relname as name, c.relkind::text || ':' || pg_get_viewdef(c.oid, true) as definition
+     from pg_class c
+     join pg_namespace n on n.oid = c.relnamespace
+     where n.nspname = $1 and c.relkind in ('v','m')
+     order by c.relname`, [schema]);
+  const views = new Map;
+  for (const row of viewRows.rows)
+    views.set(row.name, row.definition);
+  const functionRows = await db.query(`select n.nspname || '.' || p.proname || '(' ||
+            pg_get_function_identity_arguments(p.oid) || ')' as identity,
+            pg_get_functiondef(p.oid) as definition
+     from pg_proc p
+     join pg_namespace n on n.oid = p.pronamespace
+     where n.nspname = $1 and p.prokind in ('f', 'p')
+     order by p.proname, pg_get_function_identity_arguments(p.oid)`, [schema]);
+  const functions = new Map;
+  for (const row of functionRows.rows)
+    functions.set(row.identity, row.definition);
+  const triggerRows = await db.query(`select c.relname as table, t.tgname as name, pg_get_triggerdef(t.oid, true) as definition
+     from pg_trigger t
+     join pg_class c on c.oid = t.tgrelid
+     join pg_namespace n on n.oid = c.relnamespace
+     where n.nspname = $1 and not t.tgisinternal
+     order by c.relname, t.tgname`, [schema]);
+  const triggers = new Map;
+  for (const row of triggerRows.rows)
+    triggers.set(`${row.table}.${row.name}`, row.definition);
+  const policyRows = await db.query(`select tablename as table, policyname as name, permissive,
+            roles, cmd as command, qual as using_expression,
+            with_check as check_expression
+     from pg_policies
+     where schemaname = $1
+     order by tablename, policyname`, [schema]);
+  const policies = new Map;
+  for (const row of policyRows.rows)
+    policies.set(`${row.table}.${row.name}`, renderPolicy(schema, row));
+  const attributesRows = await db.query(`select 'relation/' || c.relname as name,
+            jsonb_build_array(c.relkind, c.relpersistence, c.relrowsecurity, c.relforcerowsecurity,
+              c.relispartition, pg_get_expr(c.relpartbound, c.oid),
+              pg_get_partkeydef(c.oid), pg_get_userbyid(c.relowner),
+              c.relacl::text, c.reloptions)::text as definition
+     from pg_class c join pg_namespace n on n.oid = c.relnamespace
+     where n.nspname = $1 and c.relkind in ('r','p','v','m','S','f')
+     union all
+     select 'column/' || c.relname || '/' || a.attname,
+            jsonb_build_array(a.attidentity, a.attgenerated, a.attacl::text,
+              a.attcollation::regcollation::text)::text
+     from pg_attribute a join pg_class c on c.oid = a.attrelid
+     join pg_namespace n on n.oid = c.relnamespace
+     where n.nspname = $1 and c.relkind in ('r','p') and a.attnum > 0 and not a.attisdropped
+     union all
+     select 'function/' || p.proname || '(' || pg_get_function_identity_arguments(p.oid) || ')',
+            jsonb_build_array(pg_get_userbyid(p.proowner), p.proacl::text)::text
+     from pg_proc p join pg_namespace n on n.oid = p.pronamespace
+     where n.nspname = $1 and p.prokind in ('f','p')
+     union all
+     select 'schema/' || n.nspname,
+            jsonb_build_array(pg_get_userbyid(n.nspowner), n.nspacl::text)::text
+     from pg_namespace n where n.nspname = $1
+     union all
+     select 'sequence/' || c.relname,
+            jsonb_build_array(s.seqtypid::regtype::text, s.seqstart, s.seqincrement,
+              s.seqmax, s.seqmin, s.seqcache, s.seqcycle)::text
+     from pg_sequence s join pg_class c on c.oid = s.seqrelid
+     join pg_namespace n on n.oid = c.relnamespace where n.nspname = $1
+     union all
+     select 'trigger/' || c.relname || '/' || t.tgname, t.tgenabled::text
+     from pg_trigger t join pg_class c on c.oid = t.tgrelid
+     join pg_namespace n on n.oid = c.relnamespace
+     where n.nspname = $1 and not t.tgisinternal
+     union all
+     select 'type/' || t.typname,
+            jsonb_build_array(t.typtype, t.typbasetype::regtype::text, t.typtypmod,
+              t.typnotnull, t.typdefault, t.typacl::text,
+              (select array_agg(pg_get_constraintdef(con.oid) order by con.conname)
+               from pg_constraint con where con.contypid = t.oid))::text
+     from pg_type t join pg_namespace n on n.oid = t.typnamespace
+     where n.nspname = $1 and t.typtype in ('d','r','m')
+     union all
+     select 'defaults/' || pg_get_userbyid(d.defaclrole) || '/' || d.defaclobjtype::text,
+            d.defaclacl::text
+     from pg_default_acl d join pg_namespace n on n.oid = d.defaclnamespace where n.nspname = $1`, [schema]);
+  const attributes = new Map(attributesRows.rows.map((row) => [row.name, row.definition]));
+  return { tables, constraints, indexes, enums, views, functions, triggers, policies, attributes };
+}
+function schemasEqual(left, right) {
+  const canonical = (value) => {
+    if (value instanceof Map)
+      return [...value].sort(([a], [b]) => String(a).localeCompare(String(b))).map(([key, entry]) => [key, canonical(entry)]);
+    if (Array.isArray(value))
+      return value.map(canonical);
+    if (value !== null && typeof value === "object")
+      return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, entry]) => [key, canonical(entry)]));
+    return value;
+  };
+  return JSON.stringify(canonical(left)) === JSON.stringify(canonical(right));
 }
 function diffSchemas(from, to, schema = "public") {
+  for (const [key, value] of from.attributes) {
+    if (to.attributes.has(key) && to.attributes.get(key) !== value) {
+      throw new Error("Lite table diff cannot safely migrate catalog attributes; use the official Supabase pg-delta adapter");
+    }
+  }
+  for (const [name, labels] of from.enums) {
+    const next = to.enums.get(name);
+    if (!next || labels.some((label, index) => next[index] !== label)) {
+      throw new Error("Lite table diff only supports appending enum values; use the official Supabase pg-delta adapter");
+    }
+  }
+  for (const kind of ["views", "functions", "triggers", "policies"]) {
+    if (from[kind].size !== to[kind].size || [...from[kind]].some(([name, definition]) => to[kind].get(name) !== definition)) {
+      throw new Error(`Lite table diff cannot safely migrate ${kind}; use the official Supabase pg-delta adapter`);
+    }
+  }
   const out = [];
   const q = (n) => quoteIdent(n);
   const tbl = (t) => `${q(schema)}.${q(t)}`;
@@ -11196,6 +11308,17 @@ ${colDefs.map((c) => `  ${c}`).join(`,
   });
   return out;
 }
+function renderPolicy(schema, row) {
+  const roles = row.roles.length ? row.roles.map((role) => quoteIdent(role)).join(", ") : "public";
+  const command = row.command.toLowerCase() === "*" ? "all" : row.command.toLowerCase();
+  const mode = row.permissive.toLowerCase() === "permissive" ? "permissive" : "restrictive";
+  let sql = `create policy ${quoteIdent(row.name)} on ${quoteIdent(schema)}.${quoteIdent(row.table)} as ${mode} for ${command} to ${roles}`;
+  if (row.using_expression)
+    sql += ` using (${row.using_expression})`;
+  if (row.check_expression)
+    sql += ` with check (${row.check_expression})`;
+  return sql;
+}
 function columnClause(c, q) {
   const isSerialDefault = c.default !== null && /^nextval\(/i.test(c.default);
   if (isSerialDefault) {
@@ -11571,8 +11694,8 @@ function withCors(res) {
 }
 
 // src/runtime/node/db-diff.ts
-import { mkdtempSync as mkdtempSync2 } from "fs";
-import { mkdir as mkdir2, rm, writeFile as writeFile2 } from "fs/promises";
+import { existsSync as existsSync3, mkdtempSync as mkdtempSync2 } from "fs";
+import { link, mkdir as mkdir2, rm, writeFile as writeFile2 } from "fs/promises";
 import { tmpdir as tmpdir2 } from "os";
 import { dirname as dirname2, join as join2 } from "path";
 
@@ -12673,6 +12796,24 @@ function removeStalePidFile(pidPath) {
 
 // src/runtime/node/db-diff.ts
 async function computeDbDiff(opts) {
+  return withDelta(opts, false, async (ddl) => ddl);
+}
+async function assertHistory(tx, migrations) {
+  const exists = await tx.query("select to_regclass('supabase_migrations.schema_migrations')::text as ledger");
+  const rows = exists.rows[0]?.ledger ? (await tx.query("select version, statements from supabase_migrations.schema_migrations")).rows : [];
+  const expected = new Map;
+  for (const migration of migrations) {
+    const version = migration.name.match(/^(\d+)/)?.[1] ?? migration.name;
+    if (expected.has(version))
+      throw new Error(`duplicate migration version: ${version}`);
+    expected.set(version, migration.sql);
+  }
+  if (rows.length !== expected.size || rows.some((row) => expected.get(row.version) !== row.statements?.join(`
+`))) {
+    throw new Error("Schema authoring requires matching applied migration history; resolve pending, missing or changed migrations first");
+  }
+}
+async function withDelta(opts, baseline, action) {
   const schema = opts.schema ?? "public";
   let shadow;
   let live;
@@ -12685,18 +12826,29 @@ async function computeDbDiff(opts) {
       migrations: opts.migrations,
       startRuntimeServices: false
     });
-    const liveEngine = unclaimedLiveEngine;
+    if (!unclaimedLiveEngine && (!opts.liveDataDir || !existsSync3(opts.liveDataDir))) {
+      throw new Error("An existing live database is required for schema authoring");
+    }
+    live = unclaimedLiveEngine ?? await createPgliteEngine(opts.liveDataDir, { inspectOnly: true });
     unclaimedLiveEngine = undefined;
-    live = await createBackend({
-      runtimeMode: opts.runtimeMode,
-      engine: liveEngine,
-      dataDir: liveEngine ? undefined : opts.liveDataDir,
-      migrations: opts.migrations,
-      startRuntimeServices: false
-    });
     const shadowSnap = await snapshotSchema(shadow.db, schema);
-    const liveSnap = await snapshotSchema(live.db, schema);
-    return diffSchemas(shadowSnap, liveSnap, schema);
+    return await live.transaction(async (tx) => {
+      await tx.exec(`set transaction isolation level repeatable read${baseline ? "" : " read only"}`);
+      await assertHistory(tx, opts.migrations);
+      const liveSnap = await snapshotSchema(tx, schema);
+      const ddl = diffSchemas(shadowSnap, liveSnap, schema);
+      try {
+        if (ddl.length)
+          await shadow.db.exec(ddl.join(`
+`));
+        if (!schemasEqual(await snapshotSchema(shadow.db, schema), liveSnap)) {
+          throw new Error("Generated DDL does not reproduce the live schema");
+        }
+      } catch (cause) {
+        throw new Error("Lite schema replay validation failed; use the official Supabase pg-delta adapter", { cause });
+      }
+      return action(ddl, tx);
+    });
   } catch (error) {
     operationFailed = true;
     throw error;
@@ -12737,55 +12889,52 @@ async function createTemporaryNativeEngine(installDir) {
   };
 }
 async function pullSchema(opts) {
-  const schema = opts.schema ?? "public";
-  let shadow;
-  let live;
-  let unclaimedLiveEngine = opts.liveEngine;
-  let operationFailed = false;
+  const stamp = opts.stamp ?? new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14);
+  const name = opts.name ?? "remote_schema";
+  if (!/^\d{14}$/.test(stamp) || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,100}$/.test(name)) {
+    await opts.liveEngine?.close();
+    throw new Error("Invalid migration timestamp or name");
+  }
+  if (opts.baseline && !opts.migrationsDir) {
+    await opts.liveEngine?.close();
+    throw new Error("Baseline requires an output directory");
+  }
+  let stagedPath = null;
   try {
-    shadow = await createBackend({
-      runtimeMode: opts.runtimeMode,
-      engine: opts.makeShadowEngine ? await opts.makeShadowEngine() : undefined,
-      migrations: opts.migrations,
-      startRuntimeServices: false
-    });
-    const liveEngine = unclaimedLiveEngine;
-    unclaimedLiveEngine = undefined;
-    live = await createBackend({
-      runtimeMode: opts.runtimeMode,
-      engine: liveEngine,
-      dataDir: liveEngine ? undefined : opts.liveDataDir,
-      migrations: opts.migrations,
-      startRuntimeServices: false
-    });
-    const ddl = diffSchemas(await snapshotSchema(shadow.db, schema), await snapshotSchema(live.db, schema), schema);
-    if (ddl.length === 0)
-      return { ddl, version: null, path: null };
-    const stamp = opts.stamp ?? new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14);
-    const name = opts.name ?? "remote_schema";
-    const body = ddl.join(`
+    const result = await withDelta(opts, opts.baseline === true, async (ddl, tx) => {
+      if (ddl.length === 0)
+        return { ddl, version: null, path: null };
+      const body = ddl.join(`
 
 `) + `
 `;
-    let path = null;
-    if (opts.migrationsDir) {
-      await mkdir2(opts.migrationsDir, { recursive: true });
-      path = join2(opts.migrationsDir, `${stamp}_${name}.sql`);
-      await writeFile2(path, body);
-    }
-    await live.db.query(`insert into supabase_migrations.schema_migrations (version, name, statements)
-       values ($1, $2, $3) on conflict (version) do nothing`, [stamp, `${stamp}_${name}`, [body]]);
-    return { ddl, version: stamp, path };
+      let path = null;
+      if (opts.migrationsDir) {
+        await mkdir2(opts.migrationsDir, { recursive: true });
+        path = join2(opts.migrationsDir, `${stamp}_${name}.sql`);
+        if (existsSync3(path))
+          throw new Error("Migration file already exists");
+        if (opts.baseline) {
+          const pending = `${path}.pending`;
+          await writeFile2(pending, body, { flag: "wx" });
+          stagedPath = pending;
+          await tx.query("insert into supabase_migrations.schema_migrations(version, name, statements) values ($1, $2, $3)", [stamp, `${stamp}_${name}`, [body]]);
+        } else {
+          await writeFile2(path, body, { flag: "wx" });
+        }
+      }
+      return { ddl, version: stamp, path };
+    });
+    if (stagedPath && result.path) {
+      await link(stagedPath, result.path);
+      await rm(stagedPath);
+    }
+    return result;
   } catch (error) {
-    operationFailed = true;
-    throw error;
-  } finally {
-    try {
-      await closeResources(unclaimedLiveEngine, live, shadow);
-    } catch (error) {
-      if (!operationFailed)
-        throw error;
+    if (stagedPath) {
+      throw new Error(`Baseline outcome requires inspection; staged SQL retained at ${stagedPath}. Verify the ledger before publishing it.`, { cause: error });
     }
+    throw error;
   }
 }
 async function closeResources(...resources) {
@@ -14110,7 +14259,7 @@ function isNotFound(error) {
 }
 
 // src/project-runtime.ts
-import { chmod, link, lstat as lstat2, mkdir as mkdir5, readFile as readFile7, realpath as realpath2, unlink as unlink2, writeFile as writeFile5 } from "fs/promises";
+import { chmod, link as link2, lstat as lstat2, mkdir as mkdir5, readFile as readFile7, realpath as realpath2, unlink as unlink2, writeFile as writeFile5 } from "fs/promises";
 import { dirname as dirname6, isAbsolute, join as join8, parse, relative, resolve as resolve4 } from "path";
 import { pathToFileURL as pathToFileURL3 } from "url";
 
@@ -14219,7 +14368,7 @@ import { pathToFileURL as pathToFileURL2 } from "url";
 // src/runtime/node/bundle-function.ts
 import { createHash as createHash4 } from "crypto";
 import { mkdir as mkdir4, readFile as readFile5, rm as rm3, writeFile as writeFile4 } from "fs/promises";
-import { existsSync as existsSync3 } from "fs";
+import { existsSync as existsSync4 } from "fs";
 import { tmpdir as tmpdir3 } from "os";
 import { join as join6 } from "path";
 function rewriteRemoteSpecifier(spec) {
@@ -14233,7 +14382,7 @@ var HTTP_CACHE = join6(tmpdir3(), "supacloud-lite-fn-http");
 async function fetchModule(url) {
   const key = createHash4("sha256").update(url).digest("hex");
   const cached = join6(HTTP_CACHE, key);
-  if (existsSync3(cached))
+  if (existsSync4(cached))
     return readFile5(cached, "utf8");
   const res = await fetch(url, { redirect: "follow" });
   if (!res.ok)
@@ -14679,7 +14828,7 @@ async function ensureProjectSecrets(paths) {
     try {
       await writeFile5(temporaryFile, `${JSON.stringify(candidate, null, 2)}
 `, { mode: 384, flag: "wx" });
-      await link(temporaryFile, paths.secretsFile);
+      await link2(temporaryFile, paths.secretsFile);
       stored = candidate;
     } catch (error) {
       if (error.code !== "EEXIST")
@@ -15472,6 +15621,8 @@ function parseArgs(argv) {
       options.output = resolve6(next());
     else if (argument === "--file" || argument === "-f")
       options.diffFile = next();
+    else if (argument === "--baseline")
+      options.baseline = true;
     else if (argument === "--module-file")
       options.moduleFile = resolve6(next());
     else if (argument === "--service-role")
@@ -15580,7 +15731,7 @@ ${privilegedKey}
     if (options.identityModule ?? config.lite.identityModule) {
       report.identity = { mode: "external", verification: "unverified" };
     }
-    if (paths.dataDir && existsSync4(join10(paths.dataDir, "PG_VERSION"))) {
+    if (paths.dataDir && existsSync5(join10(paths.dataDir, "PG_VERSION"))) {
       const engine = paths.databaseEngine === "native" ? await createNativeEngine({ dataDir: paths.dataDir, installDir: options.postgresDir, log: quietLog, replication }) : await createPgliteEngine(paths.dataDir);
       try {
         report.graphql = await inspectGraphql(engine);
@@ -15720,10 +15871,12 @@ async function runDbCommand(options) {
 `)}
 `;
     if (options.diffFile) {
+      if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,100}$/.test(options.diffFile))
+        throw new Error("Invalid migration name");
       const stamp = timestamp();
       const output = join10(paths.projectDir, "supabase", "migrations", `${stamp}_${options.diffFile}.sql`);
       await mkdir7(join10(paths.projectDir, "supabase", "migrations"), { recursive: true });
-      await writeFile7(output, source);
+      await writeFile7(output, source, { flag: "wx" });
       await writeStandardOutput(`Wrote ${output}
 `);
     } else
@@ -15743,14 +15896,16 @@ async function runDbCommand(options) {
       migrations: project.migrations,
       makeShadowEngine: paths.databaseEngine === "native" ? () => createTemporaryNativeEngine(options.postgresDir) : undefined,
       runtimeMode: config.lite.runtimeMode,
-      migrationsDir: join10(paths.projectDir, "supabase", "migrations"),
+      migrationsDir: options.baseline ? join10(paths.projectDir, "supabase", "migrations") : join10(paths.projectDir, ".supacloud-lite", "schema-drafts"),
+      baseline: options.baseline,
       name: options.positionals[1] ?? "remote_schema"
     });
     if (!result.path)
       await writeStandardError(`No schema changes to pull.
 `);
     else
-      await writeStandardOutput(`Wrote ${result.path} and recorded version ${result.version} as applied.
+      await writeStandardOutput(options.baseline ? `Wrote ${result.path} and recorded the existing schema as applied; no DDL was executed.
+` : `Wrote review draft ${result.path}. Live database and migration history were not changed. Use db pull --baseline after review.
 `);
     return;
   }
@@ -15908,7 +16063,7 @@ Commands:
   gen types             emit Supabase-shaped TypeScript database types
   db reset              reset initialized database/storage and re-run migrations
   db diff               print schema changes outside migrations
-  db pull [name]        write live schema changes as an applied migration
+  db pull [name]        write live schema changes to schema-drafts for review
   db check              reconcile database module manifests (@supacloud/db) against the live catalog
   snapshot create       create a compressed database/storage/secrets snapshot
   snapshot restore <f>  restore a snapshot into an empty target
@@ -15945,6 +16100,7 @@ Options:
       --identity-module   trusted external identity bridge module
   -o, --output <p>        output file for gen types
   -f, --file <name>       migration suffix for db diff
+  --baseline             db pull: write and record already-present schema as a migration
       --module-file <p>   database module manifest for db check (default supabase/db/modules.ts)
       --force             replace non-empty restore targets and retain rollback copies
 `);

package/dist/index.js

@@ -83,7 +83,7 @@ function randomToken(bytes = 32) {
 // package.json
 var package_default = {
   name: "@supacloud/lite",
-  version: "0.19.0",
+  version: "0.20.0",
   description: "Bun-native, single-project Supabase-compatible backend powered by PGlite or native PostgreSQL",
   type: "module",
   license: "Apache-2.0",
@@ -6240,7 +6240,7 @@ begin
   perform set_config('TimeZone', configured_timezone, false);
 end $$;
 `;
-async function createPgliteEngine(dataDir) {
+async function createPgliteEngine(dataDir, options = {}) {
   const releaseLock = await acquireDataDirLock(dataDir, "PGlite");
   let PGlite, extensions;
   const standaloneAssets = getStandaloneAssets();
@@ -6295,7 +6295,8 @@ async function createPgliteEngine(dataDir) {
     });
     await pg.waitReady;
     try {
-      await pg.exec(INITIALIZE_TIMEZONE_SQL);
+      if (!options.inspectOnly)
+        await pg.exec(INITIALIZE_TIMEZONE_SQL);
     } catch (error) {
       const [cleanup] = await Promise.allSettled([pg.close()]);
       if (cleanup.status === "rejected") {

package/dist/runtime/db/pglite-engine.d.ts

@@ -5,5 +5,7 @@ import type { DbEngine } from './engine.js';
  * extensions Supabase enables by default.
  * @throws if the PGlite WASM bundle isn't available in this build (use the native engine instead).
  */
-export declare function createPgliteEngine(dataDir?: string): Promise<DbEngine>;
+export declare function createPgliteEngine(dataDir?: string, options?: {
+    inspectOnly?: boolean;
+}): Promise<DbEngine>;
 //# sourceMappingURL=pglite-engine.d.ts.map

package/dist/runtime/db/pglite-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pglite-engine.d.ts","sourceRoot":"","sources":["../../../src/runtime/db/pglite-engine.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAA8C,MAAM,aAAa,CAAA;AA2BvF;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CA8G5E"}
+{"version":3,"file":"pglite-engine.d.ts","sourceRoot":"","sources":["../../../src/runtime/db/pglite-engine.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAA8C,MAAM,aAAa,CAAA;AA2BvF;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CA8GrH"}

package/dist/runtime/db/schema-diff.d.ts

@@ -1,4 +1,4 @@
-import type { Database } from './database.js';
+import type { DbEngine } from './engine.js';
 interface ColumnSnap {
     name: string;
     /** fully-specified type from format_type (e.g. `character varying(255)`) */
@@ -13,6 +13,7 @@ interface TableSnap {
     /** column names in declaration order, so DDL is emitted deterministically */
     order: string[];
 }
+type DefinitionMap = Map<string, string>;
 /** A structured snapshot of one schema, diffable into DDL by {@link diffSchemas}. */
 export interface SchemaSnapshot {
     /** table name → its columns */
@@ -23,9 +24,20 @@ export interface SchemaSnapshot {
     indexes: Map<string, Map<string, string>>;
     /** enum type name → its labels in sort order */
     enums: Map<string, string[]>;
+    /** view name → view definition */
+    views: DefinitionMap;
+    /** function identity → function definition */
+    functions: DefinitionMap;
+    /** table/name → trigger definition */
+    triggers: DefinitionMap;
+    /** table/name → policy definition */
+    policies: DefinitionMap;
+    /** Catalog attributes which table DDL must preserve, including grants and identity. */
+    attributes: DefinitionMap;
 }
 /** Snapshot a schema's tables, columns, constraints, indexes, and enums. */
-export declare function snapshotSchema(db: Database, schema?: string): Promise<SchemaSnapshot>;
+export declare function snapshotSchema(db: Pick<DbEngine, 'query'>, schema?: string): Promise<SchemaSnapshot>;
+export declare function schemasEqual(left: SchemaSnapshot, right: SchemaSnapshot): boolean;
 /** DDL to turn `from` into `to`, scoped to one schema. Empty array = no changes. */
 export declare function diffSchemas(from: SchemaSnapshot, to: SchemaSnapshot, schema?: string): string[];
 export {};

package/dist/runtime/db/schema-diff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-diff.d.ts","sourceRoot":"","sources":["../../../src/runtime/db/schema-diff.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAE7C,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,OAAO,CAAA;IACjB,mDAAmD;IACnD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AACD,UAAU,SAAS;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAChC,6EAA6E;IAC7E,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,qFAAqF;AACrF,MAAM,WAAW,cAAc;IAC7B,+BAA+B;IAC/B,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IAC9B,uEAAuE;IACvE,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC7C,mGAAmG;IACnG,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACzC,gDAAgD;IAChD,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;CAC7B;AAED,4EAA4E;AAC5E,wBAAsB,cAAc,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,SAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAqE7F;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,cAAc,EAAE,MAAM,SAAW,GAAG,MAAM,EAAE,CAiFjG"}
+{"version":3,"file":"schema-diff.d.ts","sourceRoot":"","sources":["../../../src/runtime/db/schema-diff.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3C,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,OAAO,CAAA;IACjB,mDAAmD;IACnD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AACD,UAAU,SAAS;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IAChC,6EAA6E;IAC7E,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,KAAK,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAExC,qFAAqF;AACrF,MAAM,WAAW,cAAc;IAC7B,+BAA+B;IAC/B,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IAC9B,uEAAuE;IACvE,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC7C,mGAAmG;IACnG,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACzC,gDAAgD;IAChD,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;IAC5B,kCAAkC;IAClC,KAAK,EAAE,aAAa,CAAA;IACpB,8CAA8C;IAC9C,SAAS,EAAE,aAAa,CAAA;IACxB,sCAAsC;IACtC,QAAQ,EAAE,aAAa,CAAA;IACvB,qCAAqC;IACrC,QAAQ,EAAE,aAAa,CAAA;IACvB,uFAAuF;IACvF,UAAU,EAAE,aAAa,CAAA;CAC1B;AAED,4EAA4E;AAC5E,wBAAsB,cAAc,CAAC,EAAE,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,MAAM,SAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CA+K5G;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAWjF;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,cAAc,EAAE,MAAM,SAAW,GAAG,MAAM,EAAE,CAkGjG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/lite",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Bun-native, single-project Supabase-compatible backend powered by PGlite or native PostgreSQL",
   "type": "module",
   "license": "Apache-2.0",