@supacloud/db 0.1.0

package/README.md

@@ -0,0 +1,100 @@
+# @supacloud/db
+
+SupaCloud 的数据库治理层：把 RLS 策略、RPC 函数、触发器、授权（grant）作为**一等资源**做声明式管理，并与 PostgreSQL 真实 Catalog 对账。
+
+定位：它是 Drizzle（schema/迁移）之上的治理层 —— Drizzle 负责表结构，本包负责表结构之外的安全与业务对象（策略、函数、权限）的声明、静态检查与漂移检测。**driver 无关**：所有 Catalog 读取都通过注入的 `QueryExecutor` 完成，不依赖任何数据库客户端，也不 import drizzle-orm（仅类型层兼容 drizzle Table 的内部形状）。
+
+## 目录约定示例
+
+```
+db/
+  policies/cases_select.sql      -- create policy ... + enable row level security
+  functions/case_create.sql      -- security definer set search_path = public
+  triggers/cases_updated_at.sql
+  grants/cases.sql
+  tests/cases_select.sql         -- pgTAP 或 SQL 冒烟测试
+```
+
+```ts
+import { defineDatabaseModule } from '@supacloud/db';
+import { cases } from './schema'; // drizzle 表对象
+
+export const casesModule = defineDatabaseModule({
+  name: 'cases',
+  tables: [cases], // 也接受 'public.cases' 字符串
+  policies: [
+    {
+      name: 'cases_select',
+      table: 'public.cases',
+      operation: 'select',
+      roles: ['authenticated'],
+      source: 'db/policies/cases_select.sql',
+      tests: ['db/tests/cases_select.sql'],
+    },
+  ],
+  functions: [
+    {
+      name: 'public.case_create',
+      source: 'db/functions/case_create.sql',
+      security: 'definer',
+      permission: 'case.create',
+      tests: ['db/tests/case_create.sql'],
+    },
+  ],
+  grants: [
+    { object: 'public.cases', privilege: 'SELECT', role: 'authenticated', source: 'db/grants/cases.sql' },
+  ],
+});
+```
+
+## API
+
+| 导出 | 说明 |
+| --- | --- |
+| `defineDatabaseModule(options)` | 声明一个数据库模块，归一化表名为 `schema.name` |
+| `readCatalog(executor, schemas?)` | 通过注入的查询执行器读取 PostgreSQL Catalog（默认 `['public']`，参数化 `$1`） |
+| `reconcileModule(module, catalog)` | Manifest 与 Catalog 对账，产出 `ReconcileReport` |
+| `lintSql(sql, file)` / `lintModule(module, readFile)` | 纯 SQL 文本静态分析，无需数据库 |
+| `buildDatabaseManifest(modules)` | 汇总模块为可 JSON 序列化的 `DatabaseManifest`（version 1） |
+| `explainObject(manifest, name)` | 人类可读地解释对象的所属模块、类型、源文件、权限、测试 |
+
+## 诊断码
+
+### 对账（reconcile）
+
+| code | 级别 | 含义 |
+| --- | --- | --- |
+| `missing-policy` | error | 声明的策略在 catalog 中不存在 |
+| `missing-function` | error | 声明的 RPC 函数在 catalog 中不存在 |
+| `undeclared-policy` | warn | 归属表上存在 manifest 未声明的策略（漂移） |
+| `rls-disabled` | error | 归属表 `relrowsecurity = false` |
+| `definer-without-search-path` | error | security definer 函数未设置固定 search_path（含空元素或 `pg_temp` 也算不固定） |
+| `security-mismatch` | warn | 声明的 invoker/definer 与 catalog 实际不一致 |
+| `wildcard-grant` | error | 归属表上存在授予 `PUBLIC` 的权限 |
+| `grant-drift` | warn | 声明的授权在 catalog 中不存在 |
+
+`ReconcileReport.ok = true` 当且仅当没有 error 级问题。
+
+### Lint（静态分析，正则级、大小写不敏感）
+
+| code | 级别 | 含义 |
+| --- | --- | --- |
+| `definer-no-search-path` | error | 源文件含 `security definer` 但不含 `set search_path` |
+| `grant-to-public` | error | `grant ... to public` |
+| `missing-rls-enable` | warn | 声明了策略但所有策略源文件都没有 `enable row level security` |
+| `drop-without-if-exists` | warn | `drop table/column` 缺少 `if exists` |
+| `policy-without-test` | warn | 声明的策略/函数没有 `tests` 条目 |
+
+## 与 Supabase / PostgreSQL 的关系
+
+SupaCloud 兼容 Supabase 的托管 PostgreSQL 模型：`authenticated` / `anon` / `service_role` 角色、RLS 策略、`security definer` RPC 都是治理对象。本包读取的系统目录（`pg_class` / `pg_policy` / `pg_proc` / `information_schema`）是标准 PostgreSQL 接口，因此同样适用于自托管 PostgreSQL；针对 Supabase 风格的角色与 schema 约定没有硬编码依赖。
+
+## 开发
+
+```sh
+bun install
+bun test            # bun test，同置 *.test.ts
+bun run typecheck
+bun run typecheck:test
+bun run build       # bun build --target node + tsc 声明文件
+```

package/dist/catalog.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Catalog 读取：通过注入的 QueryExecutor 从 PostgreSQL 系统目录读取真实状态。
+ * 所有 SQL 参数化（$1 = schemas 数组），默认只读 public schema。
+ */
+import type { PolicyOperation } from './module.js';
+export interface QueryExecutor {
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+}
+export interface CatalogTable {
+    schema: string;
+    name: string;
+    rlsEnabled: boolean;
+    rlsForced: boolean;
+}
+export interface CatalogPolicy {
+    schema: string;
+    table: string;
+    name: string;
+    command: PolicyOperation;
+    roles: string[];
+    usingExpr?: string;
+    checkExpr?: string;
+}
+export interface CatalogFunction {
+    schema: string;
+    name: string;
+    security: 'invoker' | 'definer';
+    searchPath: string | null;
+    language: string;
+}
+export interface CatalogGrant {
+    objectSchema: string;
+    objectName: string;
+    privilege: string;
+    grantee: string;
+}
+export interface DatabaseCatalog {
+    tables: CatalogTable[];
+    policies: CatalogPolicy[];
+    functions: CatalogFunction[];
+    grants: CatalogGrant[];
+}
+/** 从 proconfig（text[]）中提取 search_path=... 配置，无则 null */
+export declare function extractSearchPath(config: string[] | null): string | null;
+export declare function readCatalog(executor: QueryExecutor, schemas?: string[]): Promise<DatabaseCatalog>;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { defineDatabaseModule, type DatabaseModule, type DatabaseModuleOptions, type DrizzleTableLike, type FunctionDecl, type GrantDecl, type PolicyDecl, type PolicyOperation, type TableRef, type TriggerDecl, } from './module.js';
+export { extractSearchPath, readCatalog, type CatalogFunction, type CatalogGrant, type CatalogPolicy, type CatalogTable, type DatabaseCatalog, type QueryExecutor, } from './catalog.js';
+export { reconcileModule, type ReconcileIssue, type ReconcileReport, } from './reconcile.js';
+export { lintModule, lintSql, type LintIssue } from './lint.js';
+export { buildDatabaseManifest, explainObject, type DatabaseManifest, type DatabaseManifestModule, } from './manifest.js';

package/dist/index.js

@@ -0,0 +1,412 @@
+// src/module.ts
+function normalizeTable(ref) {
+  if (typeof ref === "string")
+    return ref;
+  const schema = ref._.schema ?? "public";
+  return `${schema}.${ref._.name}`;
+}
+function defineDatabaseModule(options) {
+  return {
+    name: options.name,
+    tables: (options.tables ?? []).map(normalizeTable),
+    policies: options.policies ?? [],
+    functions: options.functions ?? [],
+    triggers: options.triggers ?? [],
+    grants: options.grants ?? []
+  };
+}
+// src/catalog.ts
+var TABLES_SQL = `
+SELECT n.nspname AS schema,
+       c.relname AS name,
+       c.relrowsecurity AS rls_enabled,
+       c.relforcerowsecurity AS rls_forced
+FROM pg_class c
+JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE c.relkind = 'r'
+  AND n.nspname = ANY($1)
+ORDER BY n.nspname, c.relname
+`;
+var POLICIES_SQL = `
+SELECT n.nspname AS schema,
+       c.relname AS table,
+       p.polname AS name,
+       p.polcmd AS command,
+       ARRAY(
+         SELECT CASE WHEN r = 0 THEN 'PUBLIC' ELSE pg_get_userbyid(r) END
+         FROM unnest(p.polroles) AS r
+       ) AS roles,
+       pg_get_expr(p.polqual, p.polrelid) AS using_expr,
+       pg_get_expr(p.polwithcheck, p.polrelid) AS check_expr
+FROM pg_policy p
+JOIN pg_class c ON c.oid = p.polrelid
+JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE n.nspname = ANY($1)
+ORDER BY n.nspname, c.relname, p.polname
+`;
+var FUNCTIONS_SQL = `
+SELECT n.nspname AS schema,
+       p.proname AS name,
+       p.prosecdef AS security_definer,
+       p.proconfig AS config,
+       l.lanname AS language
+FROM pg_proc p
+JOIN pg_namespace n ON n.oid = p.pronamespace
+JOIN pg_language l ON l.oid = p.prolang
+WHERE n.nspname = ANY($1)
+ORDER BY n.nspname, p.proname
+`;
+var GRANTS_SQL = `
+SELECT table_schema AS object_schema,
+       table_name AS object_name,
+       privilege_type AS privilege,
+       grantee
+FROM information_schema.role_table_grants
+WHERE table_schema = ANY($1)
+UNION ALL
+SELECT routine_schema AS object_schema,
+       routine_name AS object_name,
+       privilege_type AS privilege,
+       grantee
+FROM information_schema.routine_privileges
+WHERE routine_schema = ANY($1)
+`;
+var POLCMD_MAP = {
+  r: "select",
+  a: "insert",
+  w: "update",
+  d: "delete",
+  "*": "all"
+};
+function extractSearchPath(config) {
+  if (!config)
+    return null;
+  const entry = config.find((item) => item.startsWith("search_path="));
+  if (!entry)
+    return null;
+  return entry.slice("search_path=".length);
+}
+async function readCatalog(executor, schemas = ["public"]) {
+  const params = [schemas];
+  const [tableRows, policyRows, functionRows, grantRows] = await Promise.all([
+    executor.query(TABLES_SQL, params),
+    executor.query(POLICIES_SQL, params),
+    executor.query(FUNCTIONS_SQL, params),
+    executor.query(GRANTS_SQL, params)
+  ]);
+  return {
+    tables: tableRows.map((row) => ({
+      schema: row.schema,
+      name: row.name,
+      rlsEnabled: row.rls_enabled,
+      rlsForced: row.rls_forced
+    })),
+    policies: policyRows.map((row) => ({
+      schema: row.schema,
+      table: row.table,
+      name: row.name,
+      command: POLCMD_MAP[row.command] ?? "all",
+      roles: row.roles ?? [],
+      usingExpr: row.using_expr ?? undefined,
+      checkExpr: row.check_expr ?? undefined
+    })),
+    functions: functionRows.map((row) => ({
+      schema: row.schema,
+      name: row.name,
+      security: row.security_definer ? "definer" : "invoker",
+      searchPath: extractSearchPath(row.config),
+      language: row.language
+    })),
+    grants: grantRows.map((row) => ({
+      objectSchema: row.object_schema,
+      objectName: row.object_name,
+      privilege: row.privilege,
+      grantee: row.grantee
+    }))
+  };
+}
+// src/reconcile.ts
+function splitQualifiedName(name) {
+  const dot = name.indexOf(".");
+  if (dot === -1)
+    return ["public", name];
+  return [name.slice(0, dot), name.slice(dot + 1)];
+}
+function isFixedSearchPath(searchPath) {
+  if (searchPath === null)
+    return false;
+  const parts = searchPath.split(",").map((part) => part.trim().replace(/^"|"$/g, ""));
+  return parts.every((part) => part !== "" && part.toLowerCase() !== "pg_temp");
+}
+function reconcileModule(module, catalog) {
+  const issues = [];
+  const ownedTables = new Set(module.tables);
+  const push = (severity, code, object, message) => issues.push({ severity, code, object, message });
+  for (const policy of module.policies) {
+    const [schema, table] = splitQualifiedName(policy.table);
+    const found = catalog.policies.some((cp) => cp.schema === schema && cp.table === table && cp.name === policy.name);
+    if (!found) {
+      push("error", "missing-policy", `${policy.table}.${policy.name}`, `声明的策略 ${policy.name} 在表 ${policy.table} 的 catalog 中不存在`);
+    }
+  }
+  const declaredPolicyKeys = new Set(module.policies.map((p) => `${p.table}::${p.name}`));
+  for (const cp of catalog.policies) {
+    const qualified = `${cp.schema}.${cp.table}`;
+    if (ownedTables.has(qualified) && !declaredPolicyKeys.has(`${qualified}::${cp.name}`)) {
+      push("warn", "undeclared-policy", `${qualified}.${cp.name}`, `归属表 ${qualified} 上存在未声明的策略 ${cp.name}，可能发生漂移`);
+    }
+  }
+  for (const fn of module.functions) {
+    const [schema, name] = splitQualifiedName(fn.name);
+    const cf = catalog.functions.find((f) => f.schema === schema && f.name === name);
+    if (!cf) {
+      push("error", "missing-function", fn.name, `声明的函数 ${fn.name} 在 catalog 中不存在`);
+      continue;
+    }
+    if (cf.security !== fn.security) {
+      push("warn", "security-mismatch", fn.name, `函数 ${fn.name} 声明为 security ${fn.security}，catalog 实际为 ${cf.security}`);
+    }
+    const effectiveDefiner = fn.security === "definer" || cf.security === "definer";
+    if (effectiveDefiner && !isFixedSearchPath(cf.searchPath)) {
+      push("error", "definer-without-search-path", fn.name, `security definer 函数 ${fn.name} 未设置固定 search_path（当前: ${cf.searchPath ?? "未设置"}）`);
+    }
+  }
+  for (const table of module.tables) {
+    const [schema, name] = splitQualifiedName(table);
+    const ct = catalog.tables.find((t) => t.schema === schema && t.name === name);
+    if (ct && !ct.rlsEnabled) {
+      push("error", "rls-disabled", table, `归属表 ${table} 未开启行级安全（relrowsecurity = false）`);
+    }
+  }
+  for (const grant of catalog.grants) {
+    const qualified = `${grant.objectSchema}.${grant.objectName}`;
+    if (ownedTables.has(qualified) && grant.grantee.toUpperCase() === "PUBLIC") {
+      push("error", "wildcard-grant", qualified, `归属表 ${qualified} 存在授予 PUBLIC 的 ${grant.privilege} 权限`);
+    }
+  }
+  for (const grant of module.grants) {
+    const [schema, name] = splitQualifiedName(grant.object);
+    const found = catalog.grants.some((cg) => cg.objectSchema === schema && cg.objectName === name && cg.privilege.toLowerCase() === grant.privilege.toLowerCase() && cg.grantee.toLowerCase() === grant.role.toLowerCase());
+    if (!found) {
+      push("warn", "grant-drift", grant.object, `声明的授权 ${grant.privilege} ON ${grant.object} TO ${grant.role} 在 catalog 中不存在`);
+    }
+  }
+  return {
+    module: module.name,
+    issues,
+    ok: !issues.some((issue) => issue.severity === "error")
+  };
+}
+// src/lint.ts
+var SECURITY_DEFINER_RE = /\bsecurity\s+definer\b/i;
+var SET_SEARCH_PATH_RE = /\bset\s+search_path\b/i;
+var GRANT_TO_PUBLIC_RE = /\bgrant\b[^;]*\bto\s+public\b/i;
+var DROP_WITHOUT_IF_EXISTS_RE = /\bdrop\s+(?:table|column)\s+(?!if\s+exists\b)/i;
+var ENABLE_RLS_RE = /\benable\s+row\s+level\s+security\b/i;
+function lineOf(sql, index) {
+  let line = 1;
+  for (let i = 0;i < index; i += 1) {
+    if (sql.charCodeAt(i) === 10)
+      line += 1;
+  }
+  return line;
+}
+function lintSql(sql, file) {
+  const issues = [];
+  const definer = SECURITY_DEFINER_RE.exec(sql);
+  if (definer && !SET_SEARCH_PATH_RE.test(sql)) {
+    issues.push({
+      severity: "error",
+      code: "definer-no-search-path",
+      message: "security definer 函数必须显式 set search_path，避免 search_path 劫持",
+      file,
+      line: lineOf(sql, definer.index)
+    });
+  }
+  const grantPublic = GRANT_TO_PUBLIC_RE.exec(sql);
+  if (grantPublic) {
+    issues.push({
+      severity: "error",
+      code: "grant-to-public",
+      message: "禁止将权限授予 PUBLIC 角色",
+      file,
+      line: lineOf(sql, grantPublic.index)
+    });
+  }
+  const drop = DROP_WITHOUT_IF_EXISTS_RE.exec(sql);
+  if (drop) {
+    issues.push({
+      severity: "warn",
+      code: "drop-without-if-exists",
+      message: "drop table/column 建议使用 if exists，保证迁移可重入",
+      file,
+      line: lineOf(sql, drop.index)
+    });
+  }
+  return issues;
+}
+async function lintModule(module, readFile) {
+  const issues = [];
+  const sources = new Set;
+  for (const decl of [
+    ...module.policies,
+    ...module.functions,
+    ...module.triggers,
+    ...module.grants
+  ]) {
+    sources.add(decl.source);
+  }
+  const contents = new Map;
+  await Promise.all([...sources].map(async (path) => {
+    contents.set(path, await readFile(path));
+  }));
+  for (const [file, sql] of contents) {
+    issues.push(...lintSql(sql, file));
+  }
+  if (module.policies.length > 0) {
+    const anyEnable = module.policies.some((policy) => ENABLE_RLS_RE.test(contents.get(policy.source) ?? ""));
+    if (!anyEnable) {
+      issues.push({
+        severity: "warn",
+        code: "missing-rls-enable",
+        message: `模块 ${module.name} 声明了 ${module.policies.length} 条策略，但所有策略源文件都没有 enable row level security`,
+        file: module.policies[0].source
+      });
+    }
+  }
+  for (const policy of module.policies) {
+    if (!policy.tests || policy.tests.length === 0) {
+      issues.push({
+        severity: "warn",
+        code: "policy-without-test",
+        message: `策略 ${policy.name} 未声明测试文件`,
+        file: policy.source
+      });
+    }
+  }
+  for (const fn of module.functions) {
+    if (!fn.tests || fn.tests.length === 0) {
+      issues.push({
+        severity: "warn",
+        code: "policy-without-test",
+        message: `函数 ${fn.name} 未声明测试文件`,
+        file: fn.source
+      });
+    }
+  }
+  return issues;
+}
+// src/manifest.ts
+function buildDatabaseManifest(modules) {
+  return {
+    version: 1,
+    modules: modules.map((module) => ({
+      name: module.name,
+      tables: module.tables,
+      policies: module.policies,
+      functions: module.functions,
+      triggers: module.triggers,
+      grants: module.grants
+    }))
+  };
+}
+function describePolicy(moduleName, policy) {
+  const lines = [
+    `对象: ${policy.table}.${policy.name}`,
+    "类型: 策略 (policy)",
+    `所属模块: ${moduleName}`,
+    `表: ${policy.table}`,
+    `操作: ${policy.operation}`,
+    `角色: ${policy.roles.join(", ")}`,
+    `源文件: ${policy.source}`
+  ];
+  if (policy.tests && policy.tests.length > 0)
+    lines.push(`测试: ${policy.tests.join(", ")}`);
+  return lines.join(`
+`);
+}
+function describeFunction(moduleName, fn) {
+  const lines = [
+    `对象: ${fn.name}`,
+    "类型: 函数 (function)",
+    `所属模块: ${moduleName}`,
+    `源文件: ${fn.source}`,
+    `安全模式: ${fn.security}`
+  ];
+  if (fn.permission)
+    lines.push(`权限: ${fn.permission}`);
+  if (fn.transaction)
+    lines.push(`事务: ${fn.transaction}`);
+  if (fn.audit)
+    lines.push(`审计: ${fn.audit}`);
+  if (fn.idempotency)
+    lines.push(`幂等: ${fn.idempotency}`);
+  if (fn.tests && fn.tests.length > 0)
+    lines.push(`测试: ${fn.tests.join(", ")}`);
+  return lines.join(`
+`);
+}
+function describeTrigger(moduleName, trigger) {
+  return [
+    `对象: ${trigger.name}`,
+    "类型: 触发器 (trigger)",
+    `所属模块: ${moduleName}`,
+    `表: ${trigger.table}`,
+    `源文件: ${trigger.source}`
+  ].join(`
+`);
+}
+function describeGrant(moduleName, grant) {
+  return [
+    `对象: ${grant.object}`,
+    "类型: 授权 (grant)",
+    `所属模块: ${moduleName}`,
+    `权限: ${grant.privilege}`,
+    `角色: ${grant.role}`,
+    `源文件: ${grant.source}`
+  ].join(`
+`);
+}
+function explainObject(manifest, name) {
+  for (const module of manifest.modules) {
+    for (const policy of module.policies) {
+      if (policy.name === name || `${policy.table}.${policy.name}` === name) {
+        return describePolicy(module.name, policy);
+      }
+    }
+    for (const fn of module.functions) {
+      if (fn.name === name)
+        return describeFunction(module.name, fn);
+    }
+    for (const trigger of module.triggers) {
+      if (trigger.name === name || `${trigger.table}.${trigger.name}` === name) {
+        return describeTrigger(module.name, trigger);
+      }
+    }
+    for (const table of module.tables) {
+      if (table === name) {
+        return [
+          `对象: ${table}`,
+          "类型: 表 (table)",
+          `所属模块: ${module.name}`
+        ].join(`
+`);
+      }
+    }
+    for (const grant of module.grants) {
+      if (grant.object === name)
+        return describeGrant(module.name, grant);
+    }
+  }
+  return `未找到对象: ${name}`;
+}
+export {
+  buildDatabaseManifest,
+  defineDatabaseModule,
+  explainObject,
+  extractSearchPath,
+  lintModule,
+  lintSql,
+  readCatalog,
+  reconcileModule
+};

package/dist/lint.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Lint：对 SQL 源文本做正则级静态分析，无需数据库连接。
+ */
+import type { DatabaseModule } from './module.js';
+export interface LintIssue {
+    severity: 'error' | 'warn';
+    code: string;
+    message: string;
+    file: string;
+    line?: number;
+}
+export declare function lintSql(sql: string, file: string): LintIssue[];
+export declare function lintModule(module: DatabaseModule, readFile: (path: string) => Promise<string>): Promise<LintIssue[]>;

package/dist/manifest.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Manifest：把若干 DatabaseModule 汇总为可序列化的数据库治理清单，
+ * 并提供 explainObject 做人类可读的对象解释。
+ */
+import type { DatabaseModule, FunctionDecl, GrantDecl, PolicyDecl, TriggerDecl } from './module.js';
+export interface DatabaseManifestModule {
+    name: string;
+    tables: string[];
+    policies: PolicyDecl[];
+    functions: FunctionDecl[];
+    triggers: TriggerDecl[];
+    grants: GrantDecl[];
+}
+export interface DatabaseManifest {
+    version: 1;
+    modules: DatabaseManifestModule[];
+}
+export declare function buildDatabaseManifest(modules: DatabaseModule[]): DatabaseManifest;
+/**
+ * 按名字解释一个对象：策略（name 或 table.name）、函数（schema.name）、
+ * 触发器（name）、归属表（schema.name）、授权对象（schema.name，最后兜底）。
+ */
+export declare function explainObject(manifest: DatabaseManifest, name: string): string;

package/dist/module.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 模块声明：数据库治理的一等资源（RLS 策略 / RPC 函数 / 触发器 / 授权）。
+ * driver 无关，纯声明层。
+ */
+export type PolicyOperation = 'select' | 'insert' | 'update' | 'delete' | 'all';
+export interface PolicyDecl {
+    /** 策略名，如 cases_select */
+    name: string;
+    /** 带 schema 的表名：public.cases */
+    table: string;
+    operation: PolicyOperation;
+    /** 适用角色，如 ['authenticated'] */
+    roles: string[];
+    /** SQL 源文件相对路径 */
+    source: string;
+    /** 测试文件相对路径 */
+    tests?: string[];
+}
+export interface FunctionDecl {
+    /** 带 schema 的函数名：public.case_create */
+    name: string;
+    source: string;
+    /** 业务权限标识，如 case.create */
+    permission?: string;
+    transaction?: 'required' | 'none';
+    security: 'invoker' | 'definer';
+    audit?: string;
+    idempotency?: string;
+    tests?: string[];
+}
+export interface TriggerDecl {
+    name: string;
+    /** 带 schema 的表名 */
+    table: string;
+    source: string;
+}
+export interface GrantDecl {
+    /** 带 schema 的对象名：public.cases */
+    object: string;
+    privilege: string;
+    role: string;
+    source: string;
+}
+/** drizzle Table 的内部结构形状（仅类型层兼容，不 import drizzle-orm） */
+export interface DrizzleTableLike {
+    _: {
+        name: string;
+        schema?: string;
+    };
+}
+export type TableRef = string | DrizzleTableLike;
+export interface DatabaseModuleOptions {
+    name: string;
+    /** 归属表：drizzle 表对象或带 schema 表名均可 */
+    tables?: TableRef[];
+    policies?: PolicyDecl[];
+    functions?: FunctionDecl[];
+    triggers?: TriggerDecl[];
+    grants?: GrantDecl[];
+}
+export interface DatabaseModule {
+    name: string;
+    /** 归一化为 'schema.name' 形式的表名 */
+    tables: string[];
+    policies: PolicyDecl[];
+    functions: FunctionDecl[];
+    triggers: TriggerDecl[];
+    grants: GrantDecl[];
+}
+export declare function defineDatabaseModule(options: DatabaseModuleOptions): DatabaseModule;

package/dist/reconcile.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 对账：声明式 Manifest（DatabaseModule）与 PostgreSQL 真实 Catalog 比对。
+ */
+import type { DatabaseCatalog } from './catalog.js';
+import type { DatabaseModule } from './module.js';
+export interface ReconcileIssue {
+    severity: 'error' | 'warn';
+    code: string;
+    message: string;
+    /** 涉及对象名 */
+    object: string;
+}
+export interface ReconcileReport {
+    module: string;
+    issues: ReconcileIssue[];
+    /** 无 error 级问题 */
+    ok: boolean;
+}
+export declare function reconcileModule(module: DatabaseModule, catalog: DatabaseCatalog): ReconcileReport;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@supacloud/db",
+  "version": "0.1.0",
+  "description": "Database governance layer for SupaCloud: RLS policies, RPC functions and grants as first-class resources, with manifest/catalog reconciliation",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun run clean && bun run build:js && bun run build:types",
+    "build:js": "bun build src/index.ts --outdir dist --target node",
+    "build:types": "tsc -p tsconfig.json --emitDeclarationOnly",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "bun run build",
+    "test": "bun test",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:test": "tsc -p tsconfig.test.json --noEmit"
+  },
+  "keywords": [
+    "supacloud",
+    "database",
+    "governance",
+    "rls",
+    "postgresql"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vibeunion/supacloud.git",
+    "directory": "packages/db"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.0",
+    "typescript": "^7.0.2"
+  }
+}