better-supabase 0.7.1 → 0.9.0

package/dist/codegen-DeoSt1mi.d.ts

@@ -0,0 +1,1571 @@
+/// <reference lib="esnext.temporal" />
+import { G as BucketLifecycle, P as SchemaMeta, c as Casing, s as BucketPolicyName, t as AccessBucketPolicy } from "./types-YfwpIE-d.js";
+import { _ as BlocksConfig, a as AuthorizationProvider, g as BlockScope, p as AnyBlocksConfig, x as SqlNaming } from "./authorization-DpRfs6Wx.js";
+import { n as SubjectsConfig } from "./subjects-z8VWA_lF.js";
+import { i as FIELD_FORMAT_NAMES, s as FieldFormatName } from "./field-formats-DCvOQlOy.js";
+//#region src/config/types/app-tables.d.ts
+/**
+ * The column types an app table may use. Money is a `bigint` of minor units
+ * next to a `text` currency column (ADR 0024 and 0037), never `numeric`.
+ */
+declare const APP_COLUMN_TYPES: readonly ["text", "uuid", "integer", "bigint", "numeric", "boolean", "timestamptz", "date", "jsonb", "text[]"];
+type AppColumnType = (typeof APP_COLUMN_TYPES)[number];
+/** What a reference does when the row it points at is deleted (`references.onDelete`). */
+declare const APP_ON_DELETE_ACTIONS: readonly ["cascade", "restrict", "set null", "no action"];
+type AppOnDeleteAction = (typeof APP_ON_DELETE_ACTIONS)[number];
+/**
+ * What a column references: another app table, `auth.users`
+ * (`{ table: "auth.users" }`), or a logical table of an installed block
+ * (`{ block: "crm", table: "contacts" }`), which follows the block's
+ * renames.
+ */
+type AppReferenceTarget = {
+  readonly table: string;
+} | {
+  readonly block: string;
+  readonly table: string;
+};
+type AppReference = AppReferenceTarget & {
+  /** Defaults to `no action`. */
+  readonly onDelete?: AppOnDeleteAction;
+};
+/**
+ * What a column holds, beyond its Postgres type. `email`, `url`, `rating`
+ * and `percent` add a check; the others tell the UI and `gen` how to show
+ * the value. `FIELD_FORMATS` lists the types each fits and its input.
+ */
+declare const APP_COLUMN_FORMATS: typeof FIELD_FORMAT_NAMES;
+type AppColumnFormat = FieldFormatName;
+interface AppColumnConfig {
+  readonly type: AppColumnType;
+  /** Defaults to true. */
+  readonly nullable?: boolean;
+  /**
+   * The column default, from an allowlist: `now()`, `gen_random_uuid()`,
+   * `auth.uid()`, `true`, `false`, a number, a `'quoted'` text literal,
+   * and `'{}'` or `'[]'` for `jsonb` and `text[]`.
+   */
+  readonly default?: string;
+  readonly unique?: boolean;
+  readonly references?: AppReference;
+  /** What the column holds; see `APP_COLUMN_FORMATS`. */
+  readonly format?: AppColumnFormat;
+  /**
+   * The values a `text` column (single select) or each element of a
+   * `text[]` column (multi-select) may take, checked by the database.
+   */
+  readonly options?: readonly string[];
+  /** The smallest value of a number column, or the shortest `text`. */
+  readonly min?: number;
+  /** The largest value of a number column, or the longest `text`. */
+  readonly max?: number;
+  /** Rendered as `comment on column`. */
+  readonly comment?: string;
+  /** An `integer` or `bigint` the database numbers (`generated by default as identity`). */
+  readonly identity?: boolean;
+}
+/**
+ * A table the app owns, created in `public` by `better-supabase sql sync`
+ * next to the block files. Every table gets `id`, the scope column and
+ * (unless `timestamps: false`) `created_at` and `updated_at`.
+ */
+interface AppTableConfig {
+  /** The table's own columns, keyed by lower snake name. */
+  readonly columns?: Readonly<Record<string, AppColumnConfig>>;
+  /**
+   * Who reaches a row. `inherit` (the default) follows `sql.scope`: per
+   * tenant, members of the row's tenant; per user, the row's user. `user`
+   * keeps rows per user in any scope, and `none` lets signed-in users read
+   * every row while only the service role writes.
+   */
+  readonly scope?: "inherit" | "user" | "none";
+  /** `created_at` and `updated_at`. Defaults to true. */
+  readonly timestamps?: boolean;
+  /**
+   * The id's type: `uuid` (the default, `gen_random_uuid()`) or `bigint`
+   * (an identity). A reference to the table needs a column of the same type.
+   */
+  readonly id?: "uuid" | "bigint";
+  /** Sets of columns that are unique together, each a unique constraint. */
+  readonly unique?: readonly (readonly string[])[];
+  /** Sets of columns to index, in order. Reference and scope columns already have one. */
+  readonly indexes?: readonly (readonly string[])[];
+  /** Rendered as `comment on table`. */
+  readonly comment?: string;
+  /**
+   * Registers the table as a subject (ADR 0043), so blocks that attach rows
+   * to subjects (comments, attachments, tags, versions, search and others)
+   * reach its rows without a `subjects` entry.
+   */
+  readonly subject?: AppTableSubject;
+  /**
+   * Values computed from the rows of another app table that references this
+   * one, keyed by the column name they get in `public.<table>_view`
+   * (ADR 0044).
+   */
+  readonly rollups?: Readonly<Record<string, AppRollupConfig>>;
+  /**
+   * Columns of the row a reference points at, keyed by the column name they
+   * get in `public.<table>_view` (ADR 0044).
+   */
+  readonly lookups?: Readonly<Record<string, AppLookupConfig>>;
+}
+declare const APP_ROLLUP_AGGREGATES: readonly ["count", "sum", "min", "max", "avg"];
+type AppRollupAggregate = (typeof APP_ROLLUP_AGGREGATES)[number];
+/**
+ * An aggregate over the rows of `table` whose `via` column references this
+ * table: `{ table: "tasks", via: "project_id", aggregate: "count" }`.
+ */
+interface AppRollupConfig {
+  /** The app table whose rows are aggregated. */
+  readonly table: string;
+  /** The column of `table` that references this table. */
+  readonly via: string;
+  /** `sum` of no rows is 0; `min`, `max` and `avg` of no rows are null. */
+  readonly aggregate: AppRollupAggregate;
+  /**
+   * The column of `table` the aggregate reads: a number for `sum` and
+   * `avg`, a number, date, time or text for `min` and `max`. `count` takes
+   * none and counts rows.
+   */
+  readonly column?: string;
+  /** Only the rows whose select column (a `text` column with `options`) holds `equals`. */
+  readonly where?: {
+    readonly column: string;
+    readonly equals: string;
+  };
+}
+/** The `column` of the app table row that this table's `via` column references. */
+interface AppLookupConfig {
+  /** A column of this table that references another app table. */
+  readonly via: string;
+  /** A column of the referenced table. */
+  readonly column: string;
+}
+/**
+ * The subject an app table registers. The table, id type and tenant column
+ * come from the table itself.
+ */
+interface AppTableSubject {
+  /** The subject type, lowercase letters, digits and underscores. */
+  readonly type: string;
+  /** The column `subject_title` returns. */
+  readonly title?: string;
+  /** The path `subject_url` returns, with `{column}` placeholders: `/projects/{id}`. */
+  readonly url?: string;
+  /** The columns a search index reads. */
+  readonly search?: {
+    readonly title?: string;
+    readonly body?: readonly string[];
+  };
+  /** A permission key per action that `can_subject` checks; see `SubjectConfig.permissions`. */
+  readonly permissions?: Readonly<Record<string, string>>;
+  /**
+   * Adds a `rank text collate "C"` column for `move()` (ADR 0021), ordered
+   * within `group` when set.
+   */
+  readonly rank?: true | {
+    readonly group?: string;
+  };
+  /** Adds a `deleted_at timestamptz` column that blocks treat as the soft-delete time. */
+  readonly softDelete?: boolean;
+}
+type AppTablesConfig = Readonly<Record<string, AppTableConfig>>;
+//#endregion
+//#region src/config/names.d.ts
+/** The steps `better-supabase gen` runs, in the order it runs them. */
+declare const GEN_TASKS: readonly ["types", "sql", "spec", "seed", "scaffold", "env"];
+/** Glue `better-supabase init` and `add` write for a framework or runtime. */
+declare const INTEGRATION_NAMES: readonly ["next", "hono", "orpc", "edge", "expo", "mcp", "client", "react"];
+/** An integration as `init`, `add` and `/create` show it, and the integrations it needs. */
+interface IntegrationInfo {
+  readonly title: string;
+  /** What `init` or `add` writes, one sentence. */
+  readonly description: string;
+  readonly requires: readonly (typeof INTEGRATION_NAMES)[number][];
+}
+declare const INTEGRATION_INFO: Readonly<Record<(typeof INTEGRATION_NAMES)[number], IntegrationInfo>>;
+/** The agent folders `better-supabase skills install` writes to. */
+declare const SKILLS_AGENTS: readonly ["cursor", "claude", "agents"];
+//#endregion
+//#region src/config/generator-metadata.d.ts
+/**
+ * A copy of `@supabase/postgrest-typegen`'s `GeneratorMetadata` contract
+ * (version 1), so the published types don't reference the package: it is an
+ * optional peer that only the CLI loads. `tests/config/generator-metadata.test-d.ts`
+ * checks the copy against the pinned version.
+ */
+interface PostgresColumn {
+  table_id: number;
+  schema: string;
+  table: string;
+  id: string;
+  ordinal_position: number;
+  name: string;
+  default_value: unknown;
+  data_type: string;
+  format: string;
+  type_schema: string;
+  is_identity: boolean;
+  identity_generation: "ALWAYS" | "BY DEFAULT" | null;
+  is_generated: boolean;
+  is_nullable: boolean;
+  is_updatable: boolean;
+  is_unique: boolean;
+  enums: string[];
+  check: string | null;
+  comment: string | null;
+}
+interface PostgresFunctionArg {
+  mode: "in" | "inout" | "out" | "table" | "variadic";
+  name: string;
+  type_id: number;
+  has_default: boolean | null;
+}
+interface PostgresFunction {
+  id: number;
+  schema: string;
+  name: string;
+  language: string;
+  definition: string;
+  complete_statement: string;
+  args: PostgresFunctionArg[];
+  argument_types: string;
+  identity_argument_types: string;
+  return_type_id: number;
+  return_type: string;
+  return_type_relation_id: number | null;
+  is_set_returning_function: boolean;
+  prorows: number | null;
+  behavior: "IMMUTABLE" | "STABLE" | "VOLATILE";
+  security_definer: boolean;
+  config_params: {
+    [x: string]: string;
+  } | null;
+}
+/** A reference to a `types` entry by oid; `null` names when it is not in `types`. */
+interface RpcTypeReference {
+  type_id: number;
+  format: string | null;
+  type_schema: string | null;
+}
+interface RpcFunctionArg extends RpcTypeReference {
+  name: string;
+  mode: "in" | "inout" | "variadic";
+  has_default: boolean;
+  relation_id: number | null;
+}
+interface RpcReturnColumn extends RpcTypeReference {
+  name: string;
+}
+interface RpcFunctionReturns extends RpcTypeReference {
+  relation_id: number | null;
+  columns: RpcReturnColumn[] | null;
+}
+interface RpcFunctionOverload {
+  function_id: number;
+  args: RpcFunctionArg[];
+  returns: RpcFunctionReturns;
+  is_set_returning: boolean;
+  rows_estimate: number | null;
+  setof_options: {
+    from: string;
+    to: string;
+    is_one_to_one: boolean;
+    is_setof_return: boolean;
+  } | null;
+  computed_field_of: number | null;
+  error: string | null;
+}
+/** A function PostgREST exposes under `/rpc`, with its overloads resolved. */
+interface RpcFunction {
+  schema: string;
+  name: string;
+  overloads: RpcFunctionOverload[];
+}
+interface GeneratorMetadata {
+  version: 1;
+  schemas: {
+    id: number;
+    name: string;
+    owner: string;
+  }[];
+  tables: {
+    bytes: number;
+    comment: string | null;
+    dead_rows_estimate: number;
+    id: number;
+    live_rows_estimate: number;
+    name: string;
+    replica_identity: "DEFAULT" | "FULL" | "INDEX" | "NOTHING";
+    rls_enabled: boolean;
+    rls_forced: boolean;
+    schema: string;
+    size: string;
+  }[];
+  foreignTables: {
+    comment: string | null;
+    id: number;
+    name: string;
+    schema: string;
+  }[];
+  views: {
+    comment: string | null;
+    id: number;
+    is_insert_enabled?: boolean | undefined;
+    is_updatable: boolean;
+    is_update_enabled?: boolean | undefined;
+    name: string;
+    schema: string;
+  }[];
+  materializedViews: {
+    comment: string | null;
+    id: number;
+    is_populated: boolean;
+    name: string;
+    schema: string;
+  }[];
+  columns: PostgresColumn[];
+  primaryKeys: {
+    schema: string;
+    table_name: string;
+    name: string;
+    table_id: number;
+  }[];
+  relationships: {
+    foreign_key_name: string;
+    schema: string;
+    relation: string;
+    columns: string[];
+    is_one_to_one: boolean;
+    referenced_schema: string;
+    referenced_relation: string;
+    referenced_columns: string[];
+  }[];
+  functions: PostgresFunction[];
+  types: {
+    id: number;
+    name: string;
+    schema: string;
+    format: string;
+    enums: string[];
+    attributes: {
+      name: string;
+      type_id: number;
+    }[];
+    comment: string | null;
+    type_relation_id: number | null;
+  }[];
+  /**
+   * Derived from `functions`; generators resolve it themselves when it is
+   * absent, which is how better-supabase stores metadata.
+   */
+  rpcFunctions?: RpcFunction[] | undefined;
+}
+//#endregion
+//#region src/config/snapshot.d.ts
+/**
+ * What `better-supabase introspect` reads from Postgres. `generator` is the
+ * `@supabase/postgrest-typegen` contract (the same metadata behind
+ * `supabase gen types`); `extras` holds what that contract leaves out.
+ * Codegen and doctor both work from this snapshot, so either can run offline
+ * from a saved file.
+ */
+interface Snapshot {
+  readonly $schema?: string;
+  readonly version: 2;
+  /** Every schema that was read, including helper schemas for doctor. */
+  readonly schemas: readonly string[];
+  readonly generator: GeneratorMetadata;
+  readonly extras: SnapshotExtras;
+}
+/** Catalog details `GeneratorMetadata` does not carry. */
+interface SnapshotExtras {
+  readonly tables: readonly ExtrasTable[];
+  readonly buckets: readonly SnapshotBucket[];
+  /** Tables in the `supabase_realtime` publication, as `schema.table`. */
+  readonly realtime: readonly string[];
+  /**
+   * `alter role ... set` values for the Data API roles (`authenticator`),
+   * such as `pgrst.db_aggregates_enabled`. Absent in older snapshots.
+   */
+  readonly roleSettings?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+  /**
+   * Functions that policies in the read schemas call, plus functions in
+   * those schemas with `set` options. Absent in older snapshots.
+   */
+  readonly functions?: readonly ExtrasFunction[];
+  /**
+   * The Postgres functions `supabase/config.toml` configures as Auth hooks,
+   * in any schema. Absent in older snapshots and without a `config.toml`.
+   */
+  readonly hooks?: readonly ExtrasHook[];
+  /**
+   * Comments of the functions in the read schemas that carry a gen tag
+   * (`@notNull`), keyed by `schema.name(signature)`. Absent when none do.
+   */
+  readonly functionComments?: Readonly<Record<string, string>>;
+  /**
+   * Set when the snapshot comes from a `GeneratorMetadata` document alone
+   * (`gen --metadata`): unique keys, checks and foreign keys are inferred from
+   * the columns and relationships, and the rest is empty, so doctor skips
+   * the rules that read it.
+   */
+  readonly fromMetadata?: true;
+}
+/** An `[auth.hook.<name>]` with a `pg-functions://` URI. */
+interface ExtrasHook {
+  /** `custom_access_token`, `send_email`, ... */
+  readonly hook: string;
+  readonly schema: string;
+  readonly name: string;
+  /** Every overload with that name; empty when the function does not exist. */
+  readonly functions: readonly ExtrasHookFunction[];
+}
+interface ExtrasHookFunction extends ExtrasFunction {
+  /**
+   * Of `supabase_auth_admin`, `authenticated` and `anon`, the roles that may
+   * execute it (directly or through `public`).
+   */
+  readonly execute: readonly string[];
+  /** Whether `public` may execute it (the default until revoked). */
+  readonly publicExecute: boolean;
+  /** Of the same roles, those with `usage` on its schema. */
+  readonly schemaUsage: readonly string[];
+  /** The function body (`pg_proc.prosrc`). Absent in snapshots that predate it. */
+  readonly source?: string;
+}
+/** A function as doctor needs it for RLS checks, in any schema. */
+interface ExtrasFunction {
+  readonly schema: string;
+  readonly name: string;
+  /** Identity arguments, e.g. `organization uuid`. */
+  readonly signature: string;
+  /** `sql`, `plpgsql`, `c`, ... */
+  readonly language: string;
+  readonly volatility: "immutable" | "stable" | "volatile";
+  readonly securityDefiner: boolean;
+  /** `set` options, e.g. `{ statement_timeout: '5s' }`. */
+  readonly settings: Readonly<Record<string, string>>;
+  /** Which of `anon` and `authenticated` may execute it. Absent in older snapshots. */
+  readonly execute?: readonly string[];
+}
+interface ExtrasTable {
+  /** Table oid, matching `GeneratorMetadata.tables[].id`. */
+  readonly id: number;
+  readonly schema: string;
+  readonly name: string;
+  /** Primary key columns in key order. */
+  readonly primaryKey: readonly string[];
+  readonly uniques: readonly CatalogUnique[];
+  readonly foreignKeys: readonly {
+    readonly name: string;
+    readonly onDelete: ForeignKeyAction;
+    readonly onUpdate: ForeignKeyAction;
+  }[];
+  readonly checks: readonly CatalogCheck[];
+  readonly indexes: readonly CatalogIndex[];
+  readonly policies: readonly CatalogPolicy[];
+  readonly triggers: readonly CatalogTrigger[];
+  readonly grants: readonly CatalogGrant[];
+  /** Absent in snapshots taken before column grants were introspected. */
+  readonly columnGrants?: readonly CatalogColumnGrant[];
+  /** Postgres estimates at least `LARGE_TABLE_ROWS` rows; the `unbounded-read` lint reads it. */
+  readonly large?: true;
+}
+type ForeignKeyAction = "no action" | "restrict" | "cascade" | "set null" | "set default";
+interface CatalogUnique {
+  readonly name: string;
+  readonly columns: readonly string[];
+}
+interface CatalogCheck {
+  readonly name: string;
+  readonly definition: string;
+}
+interface CatalogIndex {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly unique: boolean;
+  readonly primary: boolean;
+  readonly partial: boolean;
+  /** Access method (`btree`, `gin`, `gist`, ...). Absent in older snapshots. */
+  readonly method?: string;
+  /** The `where` of a partial index, as Postgres prints it. Absent in older snapshots. */
+  readonly predicate?: string | null;
+}
+interface CatalogPolicy {
+  readonly name: string;
+  readonly command: "all" | "select" | "insert" | "update" | "delete";
+  readonly roles: readonly string[];
+  readonly permissive: boolean;
+  readonly using: string | null;
+  readonly check: string | null;
+  /**
+   * Functions the policy expressions call, as `schema.name`, from
+   * `pg_depend`. Absent in older snapshots.
+   */
+  readonly functions?: readonly string[];
+}
+interface CatalogTrigger {
+  readonly name: string;
+  readonly timing: "before" | "after" | "instead of";
+  readonly events: readonly ("insert" | "update" | "delete" | "truncate")[];
+  readonly level: "row" | "statement";
+  readonly function: string;
+  /** The `create trigger` arguments, when there are any. */
+  readonly args?: readonly string[];
+  /**
+   * The function's body, only for functions that call `realtime.send()` or
+   * `realtime.broadcast_changes()`, other than `broadcast_topic()`.
+   */
+  readonly source?: string;
+  /** The function's comment, for the same functions as `source`. */
+  readonly comment?: string;
+}
+interface CatalogGrant {
+  readonly role: string;
+  readonly privileges: readonly string[];
+}
+/** A column-level `insert` or `update` grant to `anon` or `authenticated`. */
+interface CatalogColumnGrant {
+  readonly column: string;
+  readonly role: string;
+  readonly privileges: readonly string[];
+}
+interface SnapshotBucket {
+  readonly id: string;
+  readonly public: boolean;
+  readonly fileSizeLimit: number | null;
+  readonly allowedMimeTypes: readonly string[] | null;
+  /** `versioning_status`; absent when Storage has no versioning. */
+  readonly versioning?: "DISABLED" | "ENABLED" | "SUSPENDED" | null;
+  /** `lifecycle_configuration`; absent when Storage has no lifecycles. */
+  readonly lifecycle?: unknown;
+}
+/**
+ * The snapshot joined into one record per table, function and enum. Codegen
+ * and doctor read this view rather than the raw snapshot.
+ */
+interface Catalog {
+  readonly schemas: readonly string[];
+  readonly tables: readonly CatalogTable[];
+  readonly enums: readonly CatalogEnum[];
+  readonly functions: readonly CatalogFunction[];
+  readonly buckets: readonly SnapshotBucket[];
+  readonly realtime: readonly string[];
+}
+interface CatalogTable {
+  readonly id: number;
+  readonly schema: string;
+  readonly name: string;
+  /** Materialized views count as views; foreign tables as tables. */
+  readonly kind: "table" | "view";
+  readonly rls: boolean;
+  readonly forceRls: boolean;
+  readonly replicaIdentity: "DEFAULT" | "INDEX" | "FULL" | "NOTHING" | null;
+  /** Inserts work (always true for tables). */
+  readonly insertable: boolean;
+  /** Updates work (always true for tables). */
+  readonly updatable: boolean;
+  readonly comment: string | null;
+  readonly columns: readonly CatalogColumn[];
+  readonly primaryKey: readonly string[];
+  readonly uniques: readonly CatalogUnique[];
+  readonly foreignKeys: readonly CatalogForeignKey[];
+  readonly checks: readonly CatalogCheck[];
+  readonly indexes: readonly CatalogIndex[];
+  readonly policies: readonly CatalogPolicy[];
+  readonly triggers: readonly CatalogTrigger[];
+  readonly grants: readonly CatalogGrant[];
+  /** Absent in snapshots taken before column grants were introspected. */
+  readonly columnGrants?: readonly CatalogColumnGrant[];
+}
+interface CatalogColumn {
+  readonly name: string;
+  /** Type name; the element type for arrays (`uuid`, `int8`, `note_kind`). */
+  readonly udt: string;
+  /** Raw type name as Postgres reports it (`_text` for `text[]`). */
+  readonly format: string;
+  readonly typeSchema: string;
+  readonly isArray: boolean;
+  readonly isEnum: boolean;
+  readonly nullable: boolean;
+  readonly hasDefault: boolean;
+  readonly default: string | null;
+  readonly identity: "always" | "by default" | null;
+  readonly generated: boolean;
+  readonly updatable: boolean;
+  readonly comment: string | null;
+}
+interface CatalogForeignKey {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly refSchema: string;
+  readonly refTable: string;
+  readonly refColumns: readonly string[];
+  readonly oneToOne: boolean;
+  readonly onDelete: ForeignKeyAction;
+  readonly onUpdate: ForeignKeyAction;
+}
+interface CatalogEnum {
+  readonly schema: string;
+  readonly name: string;
+  readonly values: readonly string[];
+}
+interface CatalogFunction {
+  readonly schema: string;
+  readonly name: string;
+  /** Signature that tells overloads apart, e.g. `a integer, b text`. */
+  readonly signature: string;
+  readonly args: readonly CatalogFunctionArg[];
+  /** Columns for `returns table (...)` functions. */
+  readonly returnsTable: readonly {
+    readonly name: string;
+    readonly udt: string;
+    /** Schema of the column's type, when typegen knows it. */
+    readonly typeSchema?: string;
+  }[] | null;
+  /** Return type name (`int4`, `_text`, a table's row type). */
+  readonly returns: string;
+  /** Schema of the return type, when typegen knows it. */
+  readonly returnsSchema?: string;
+  /** `schema.table` when the function returns rows of a table or view. */
+  readonly returnsRelation: string | null;
+  readonly returnsSet: boolean;
+  readonly volatility: "immutable" | "stable" | "volatile";
+  readonly securityDefiner: boolean;
+  readonly language: string;
+  /** `search_path` from `SET search_path`, or `null` when unset. */
+  readonly searchPath: string | null;
+  /** The function's comment, when it carries a gen tag such as `@notNull`. */
+  readonly comment?: string;
+}
+interface CatalogFunctionArg {
+  readonly name: string;
+  readonly udt: string;
+  /** Schema of the argument's type, when typegen knows it. */
+  readonly typeSchema?: string;
+  readonly isArray: boolean;
+  readonly hasDefault: boolean;
+}
+//#endregion
+//#region src/config/types/tooling.d.ts
+interface OpenApiConfig {
+  /** Module exporting the document (or a function returning it) as `openapi` or default. */
+  readonly entry?: string;
+  /** JSON file `better-supabase spec emit openapi` writes. */
+  readonly output?: string;
+}
+/** A docs UI `spec emit --ui` writes next to an OpenAPI document. */
+type SpecUiName = "scalar" | "swagger" | "redoc" | "elements" | "rapidoc";
+/** One document `better-supabase spec emit` writes. */
+interface SpecOutputConfig {
+  /** A format id: `openapi`, `asyncapi` or `arazzo`. */
+  readonly format: string;
+  /** Defaults to the format's default version, e.g. `3.1` for OpenAPI. */
+  readonly version?: string;
+  /** File to write, relative to the root. Defaults to the format's file name. */
+  readonly output?: string;
+  /** Overlay files (JSON or YAML), applied in order. */
+  readonly overlays?: readonly string[];
+  /** Defaults to `yaml` when `output` ends in `.yaml` or `.yml`, otherwise `json`. */
+  readonly serialize?: "json" | "yaml";
+  /** Also writes a reference page (`openapi.html` for `openapi.json`) next to OpenAPI outputs. */
+  readonly ui?: SpecUiName;
+}
+interface SpecsConfig {
+  /** Module exporting a `defineApi()` result (or a function returning one) as `api` or default. */
+  readonly entry?: string;
+  /** The documents to write. Defaults to one OpenAPI document. */
+  readonly outputs?: readonly SpecOutputConfig[];
+  /** The lowest severity that fails `spec emit`, `check` and `validate`. Defaults to `error`. */
+  readonly failOn?: "error" | "warning" | "never";
+  /** Also write the diagnostics manifest (JSON) to this file, like `spec --manifest`. */
+  readonly manifest?: string;
+}
+/** A step `better-supabase gen` runs. */
+type GenTask = (typeof GEN_TASKS)[number];
+interface GenConfig {
+  /**
+   * The steps `better-supabase gen` runs, in this order: `types` (the
+   * generated modules and `generators`), `sql` (`sql sync`), `spec` (`spec
+   * emit`), `seed`, `scaffold` (`scaffold api`, its generated file only) and
+   * `env`. Without a list, `types` runs, plus `sql` when `blocks` or
+   * `realtime.policies` is set, `spec` and `seed` when their entry file
+   * exists, and `scaffold` when `scaffold.api` is set. `env` runs only when
+   * listed, because it needs the local stack. A listed step always runs.
+   */
+  readonly tasks?: readonly GenTask[];
+  /** Milliseconds between checks in `gen --watch` and `spec emit --watch`. */
+  readonly watchInterval?: number;
+}
+/** Glue `better-supabase init` and `add` write for a framework or runtime. */
+type IntegrationName = (typeof INTEGRATION_NAMES)[number];
+interface EnvFileConfig {
+  /** Env file `better-supabase env` writes. Defaults to `.env.local`. */
+  readonly output?: string;
+  /**
+   * Prefix for the browser variables, such as `NEXT_PUBLIC_`; `'none'` for
+   * no prefix. Detected from the framework by default.
+   */
+  readonly prefix?: string;
+}
+interface ScaffoldApiConfig {
+  /** Detected from `package.json` when the project has exactly one of them. */
+  readonly framework?: "hono" | "next";
+  /** Tables to serve. Defaults to every table and view in the public schema. */
+  readonly tables?: readonly string[];
+  /** The API module's name: `lib/<name>.ts` and `lib/<name>.generated.ts`. Defaults to `api`. */
+  readonly name?: string;
+  /** Where the resources are served. Defaults to `/api`. */
+  readonly basePath?: string;
+}
+interface ScaffoldConfig {
+  /** What `better-supabase scaffold api` writes; the `scaffold` gen step keeps its generated file current. */
+  readonly api?: ScaffoldApiConfig;
+}
+/** An agent folder `better-supabase skills install` writes to. */
+type SkillsAgent = (typeof SKILLS_AGENTS)[number];
+interface SkillsConfig {
+  /** Defaults to the agent folders the project has, else `agents`. */
+  readonly agents?: readonly SkillsAgent[];
+}
+interface KeysConfig {
+  /** Signing key file `better-supabase keys` writes. Defaults to `supabase/signing_keys.json`. */
+  readonly output?: string;
+}
+interface DoctorConfig {
+  /** Finding codes to skip, e.g. `['BS204']`. */
+  readonly ignore?: readonly string[];
+  /** Run only these checks, e.g. `['BS100', 'BS304']`. */
+  readonly only?: readonly string[];
+  /** Treat warnings as errors. */
+  readonly strict?: boolean;
+  /** Report format: `text` (default), `sarif` (code scanning) or `github` (workflow annotations). `--json` still wins. */
+  readonly format?: "text" | "sarif" | "github";
+  /** Write the report to this file. */
+  readonly output?: string;
+  /**
+   * App source files doctor scans for API use (BS210). Globs relative to the
+   * root. Defaults to `['src/**\/*.{ts,tsx}']`.
+   */
+  readonly sources?: readonly string[];
+  /**
+   * How many policies a security definer helper may appear in before BS206
+   * asks for an inlinable `language sql stable` function. Defaults to 5.
+   */
+  readonly policyHelperLimit?: number;
+  /**
+   * The BS405 limit in bytes. When the authorization provider's token hook
+   * has a budget, it replaces that budget and the whole token keeps 2048.
+   * Otherwise it limits the whole token's claims (default 2048).
+   */
+  readonly claimsLimit?: number;
+}
+//#endregion
+//#region src/preset/fields.d.ts
+/** How `/create` and `init` show one value: its label and, where the label is not enough, a hint. */
+interface PresetValueInfo {
+  readonly label: string;
+  readonly hint?: string;
+}
+/**
+ * One convention a preset sets. `values` and the field list are append-only:
+ * a code stores each value's index in `bits` bits, so a value keeps its
+ * index forever and a new value fits only while `values` stays within
+ * `bits`. A `multi` field stores one bit per value.
+ */
+interface PresetCodeField<K extends string = string, V extends string = string> {
+  readonly key: K;
+  readonly values: readonly V[];
+  readonly default: V | readonly V[];
+  readonly bits: number;
+  readonly multi?: true;
+  /** The code version that added the field; older codes decode it as its default. */
+  readonly since: number;
+}
+/** A convention field with the names `/create` and the `init` prompts show. */
+interface PresetField<K extends string = string, V extends string = string> extends PresetCodeField<K, V> {
+  readonly label: string;
+  readonly labels: { readonly [P in V]: PresetValueInfo; };
+}
+/** The value each convention field takes. */
+interface PresetConventions {
+  readonly framework: PresetFramework;
+  readonly platforms: "web" | "native" | "both";
+  readonly casing: "snake" | "camel";
+  readonly idType: "uuid" | "text" | "bigint" | "integer";
+  readonly scope: "tenant" | "user" | "none";
+  readonly tenantName: PresetTenantName;
+  readonly access: "roles" | "catalog" | "provider" | "custom";
+  readonly api: "none" | "api";
+  readonly integrations: readonly IntegrationName[];
+}
+/** A convention field's key. */
+type PresetFieldKey = keyof PresetConventions;
+/** The values a convention field takes. */
+type PresetFieldValue<K extends PresetFieldKey> = ValueOf<K>;
+type ValueOf<K extends PresetFieldKey> = PresetConventions[K] extends readonly (infer V extends string)[] ? V : Extract<PresetConventions[K], string>;
+/** The tenant names a preset can set (`sql.naming.tenant`), in code order. */
+declare const PRESET_TENANT_NAMES: readonly ["organization", "workspace", "team"];
+type PresetTenantName = (typeof PRESET_TENANT_NAMES)[number];
+/** The frameworks `/create` and `init --preset` set up glue for. */
+declare const PRESET_FRAMEWORKS: readonly ["next", "vite", "tanstack-start", "expo", "sveltekit", "nuxt", "hono", "astro", "react-router"];
+type PresetFramework = (typeof PRESET_FRAMEWORKS)[number];
+/**
+ * The convention fields, in code order. Append new fields at the end with
+ * the next `since`, and never remove or reorder one.
+ */
+declare const PRESET_FIELDS: readonly PresetField<PresetFieldKey>[];
+/** A convention field by key, with its values and labels typed. */
+declare function presetField<K extends PresetFieldKey>(key: K): PresetField<K, ValueOf<K>>;
+/** A field value's label, or the value itself when it has none. */
+declare function presetValueLabel(key: PresetFieldKey, value: string): PresetValueInfo;
+/**
+ * The integrations `init --preset` adds for a framework whatever the
+ * selection says: the framework's own one, when it has one, then what that
+ * one requires.
+ */
+declare function integrationsForFramework(framework: PresetFramework): readonly IntegrationName[];
+type PresetPlatforms = PresetConventions["platforms"];
+type PresetScope = PresetConventions["scope"];
+type PresetAccess = PresetConventions["access"];
+/** A block selection and its conventions: what a preset code encodes. */
+interface Preset extends PresetConventions {
+  /** Block names (`blocks` keys in the config), as selected; `resolvePreset` adds what they require. */
+  readonly blocks: readonly string[];
+}
+/** The newest code version; `encodePreset` writes it. */
+declare const PRESET_VERSION = 1;
+/** Every convention at its default. */
+declare const DEFAULT_CONVENTIONS: PresetConventions;
+//#endregion
+//#region src/preset/presets.d.ts
+/** Where a named preset sits in the `/create` and `init` pickers. */
+type PresetGroup = "starters" | "products" | "ai" | "platforms" | "everything";
+/** The preset groups in display order, with their headings. */
+declare const PRESET_GROUPS: Readonly<Record<PresetGroup, string>>;
+/** A named starting point: a block selection with the default conventions. */
+interface NamedPreset {
+  readonly name: string;
+  readonly title: string;
+  readonly description: string;
+  readonly group: PresetGroup;
+  /** The blocks it selects; `resolvePreset` adds what they require. */
+  readonly blocks: readonly string[];
+  /** The conventions it sets over the defaults, such as a user scope. */
+  readonly conventions?: Partial<PresetConventions>;
+}
+/** A named preset's name. */
+type PresetName = "minimal" | "saas" | "consumer" | "crm" | "projects" | "helpdesk" | "commerce" | "marketplace" | "scheduling" | "people" | "drive" | "docs" | "invoicing" | "forms" | "ai" | "ai-chat" | "ai-agents" | "developer-api" | "automation" | "enterprise" | "admin" | "everything";
+/** The named presets, for `defineConfig({ preset })` and `/create`. */
+declare const PRESETS: Readonly<Record<PresetName, NamedPreset>>;
+/** The named presets in display order, grouped by `group`. */
+declare const PRESET_NAMES: readonly PresetName[];
+declare function isPresetName(value: string): value is PresetName;
+/** The named preset as a `Preset`: the default conventions, then its own. */
+declare function namedPreset(name: PresetName): Preset;
+//#endregion
+//#region src/config/expose.d.ts
+/** A privilege the Data API roles can be granted on a table or view. */
+type Privilege = "select" | "insert" | "update" | "delete";
+type ColumnPrivilege = `${"select" | "insert" | "update"}(${string})`;
+type ExposePrivilege = Privilege | ColumnPrivilege;
+/** A role the `grants` module writes privileges for. */
+type ExposeRole = "anon" | "authenticated" | "service_role";
+/**
+ * Data API grants for one table: privileges for `authenticated`, or per
+ * role. `serviceRole` defaults to every privilege. For a function, keyed by
+ * its signature (`search_notes(text, integer)`), `execute` lists the roles
+ * that may call it; `service_role` is added unless `serviceRole` is false.
+ */
+type ExposeConfig = readonly ExposePrivilege[] | {
+  readonly anon?: readonly ExposePrivilege[];
+  readonly authenticated?: readonly ExposePrivilege[];
+  readonly serviceRole?: readonly ExposePrivilege[];
+} | {
+  readonly execute: readonly ("anon" | "authenticated")[];
+  readonly serviceRole?: boolean;
+};
+/** Resolved grants for one table. */
+interface ResolvedExpose {
+  readonly anon: readonly ExposePrivilege[];
+  readonly authenticated: readonly ExposePrivilege[];
+  readonly serviceRole: readonly ExposePrivilege[];
+}
+//#endregion
+//#region src/config/types/database.d.ts
+interface BucketConfig {
+  readonly id?: string;
+  readonly public?: boolean;
+  /**
+   * Path template with `{placeholders}`, e.g. `{organizationId}/{customerId}/logo.webp`,
+   * or several when the bucket stores objects in more than one layout. A last
+   * segment `{...rest}` matches one or more segments.
+   */
+  readonly path: string | readonly [string, ...string[]];
+  /** Generated storage policy, or an access contract policy (`{ access }`). */
+  readonly policy?: BucketPolicyName | AccessBucketPolicy;
+  readonly fileSizeLimit?: string;
+  readonly allowedMimeTypes?: readonly string[];
+  /** Keep earlier object versions. `bucket.apply()` sets it; doctor (BS302) compares it. */
+  readonly versioning?: boolean;
+  /** When noncurrent versions expire. Needs `versioning: true`. */
+  readonly lifecycle?: BucketLifecycle;
+}
+/**
+ * How the SQL modules reach the database: `pg-delta` (Supabase Declarative
+ * Schemas 2.0, `supabase db schema declarative sync`), `migra` (declarative
+ * schemas 1.0, `supabase db diff`) or `migrations` (no declarative schemas:
+ * the `sql` commands write the modules into a migration).
+ */
+type SqlWorkflow = "pg-delta" | "migra" | "migrations";
+interface SqlConfig {
+  /**
+   * The workflow. Unset, better-supabase reads `supabase/config.toml`:
+   * pg-delta when it enables it or nothing says otherwise, migra when it
+   * turns pg-delta off or the project keeps migra's declarative schemas.
+   */
+  readonly workflow?: SqlWorkflow;
+  /** Directory declarative schema files are written to. */
+  readonly dir?: string;
+  /** File name prefix, so generated files sort after yours. */
+  readonly prefix?: string;
+  /** Directory pgTAP files (the `pgtap` module) are written to. */
+  readonly testsDir?: string;
+  /**
+   * The schema every module writes its functions and managed tables to,
+   * unless `blocks.<name>.schema` sets its own. Defaults to `better_supabase`.
+   */
+  readonly schema?: string;
+  /**
+   * The Data API schema, such as `api`, every module writes its `security
+   * invoker` wrappers to, unless `blocks.<name>.api` sets its own or
+   * `false`.
+   */
+  readonly api?: string;
+  /**
+   * Who a block's rows belong to, unless `blocks.<name>.scope` sets its
+   * own: `tenant` (a tenant, checked through the access contract; the
+   * default), `user` (the signed-in user, with no tenants) or `none` (one
+   * shared space every signed-in user reads and writes).
+   */
+  readonly scope?: BlockScope;
+  /** Names for the tenant concept in tables, functions and columns. */
+  readonly naming?: SqlNaming;
+}
+/** `sql` with defaults applied. */
+interface ResolvedSqlConfig {
+  /** Unset when the config leaves it to `supabase/config.toml`. */
+  readonly workflow?: SqlWorkflow;
+  readonly dir: string;
+  readonly prefix: string;
+  readonly testsDir: string;
+  /** Unset means `tenant`. */
+  readonly scope?: BlockScope;
+  readonly naming?: SqlNaming;
+}
+interface SeedConfig {
+  /** Module exporting `defineSeed(...)` as `seed` or default. */
+  readonly entry?: string;
+  /** SQL file `better-supabase seed` writes. Add it to `[db.seed] sql_paths`. */
+  readonly output?: string;
+}
+interface RealtimeConfig {
+  /**
+   * Tables that broadcast a change signal for live queries (`table` or
+   * `schema.table`). Tenant tables broadcast per tenant. Install the
+   * triggers with `better-supabase add realtime-tables`.
+   */
+  readonly tables?: readonly string[];
+  /**
+   * Tables in `tables` without a tenant column. They broadcast on one topic
+   * every signed-in user receives. With the `tenant` plugin, a table that
+   * lacks the tenant column and is not listed here fails to install.
+   */
+  readonly global?: readonly string[];
+  /**
+   * Tables in `tables` whose rows belong to one user: table to its user
+   * column (`{ notifications: "user_id" }`). They broadcast on a topic per
+   * user, `bs:t:<schema>.<table>:u:<user id>`, which only that user
+   * receives, instead of the tenant's topic.
+   */
+  readonly users?: Readonly<Record<string, string>>;
+  /**
+   * Writes the `realtime.messages` policies of the topics that `from`
+   * exports (`defineTopic`) to `output`, a file in `supabase/schemas`, on
+   * `better-supabase sql sync`; `sql sync --check` fails when it is stale.
+   */
+  readonly policies?: TopicPoliciesConfig;
+  /**
+   * Broadcast triggers that `sql sync` writes to `policies.output` next to
+   * the policies: each one calls `better_supabase.broadcast_topic()` (the
+   * `realtime-tables` module) for a topic that `policies.from` exports.
+   */
+  readonly triggers?: readonly TopicTriggerConfig[];
+}
+/** One `realtime.triggers` entry: a table whose row changes go to a topic. */
+interface TopicTriggerConfig {
+  /** The template of a topic that `realtime.policies.from` exports. */
+  readonly topic: string;
+  /** `table` or `schema.table`. */
+  readonly table: string;
+  /** The column per placeholder. Defaults to the placeholder in snake_case. */
+  readonly values?: Readonly<Record<string, string>>;
+  /** Defaults to all three. */
+  readonly events?: readonly ("insert" | "update" | "delete")[];
+  /** The broadcast event name. Defaults to the operation. */
+  readonly event?: string;
+  /**
+   * `"keys"` (default) sends the primary key and the placeholder values.
+   * `"row"` sends the whole row, which bypasses column grants.
+   */
+  readonly payload?: "keys" | "row";
+}
+/** `realtime.policies`: where topic policies come from and go. */
+interface TopicPoliciesConfig {
+  /** Modules that export `defineTopic` results. Node imports them. */
+  readonly from: readonly string[];
+  /** The SQL file to write, such as `supabase/schemas/905_topics.sql`. */
+  readonly output: string;
+}
+/** pgvector distance: `<=>` (cosine), `<->` (l2) or `<#>` (negative inner product). */
+type VectorDistance = "cosine" | "l2" | "inner_product";
+/** The embedding column, or the column and its distance (default `cosine`). */
+type VectorSearchConfig = string | {
+  readonly column: string;
+  readonly distance?: VectorDistance;
+  /** The column's pgvector type. Defaults to `vector`. */
+  readonly type?: "vector" | "halfvec";
+  /** The primary key column `db.$search({ score: true })` merges by. Defaults to `id`. */
+  readonly key?: string;
+  /**
+   * Fuses a full-text ranking over a `tsvector` column with the vector
+   * ranking (reciprocal rank fusion), for `db.$search({ text })`.
+   */
+  readonly hybrid?: {
+    readonly tsvector: string;
+    /** The query's text search configuration. Defaults to `simple`. */
+    readonly config?: string;
+    /** The RRF constant. Defaults to 60. */
+    readonly k?: number;
+  };
+  /** A SQL expression over the row `t` the score is multiplied by, such as `t.priority`. */
+  readonly boost?: string;
+  /** Columns `db.$search({ filter })` narrows before ranking. */
+  readonly prefilter?: readonly string[];
+  /**
+   * A SQL condition over the row `t` every candidate must meet, applied
+   * before ranking: ranges, a parent row, such as
+   * `t.expires_at > now() and exists (select 1 from public.folders f where f.id = t.folder_id and not f.disabled)`.
+   */
+  readonly predicate?: string;
+  /** How `boost` combines with the score: `multiply` (default) or `add`. */
+  readonly boostMode?: "multiply" | "add";
+  /** A SQL `order by` list over the row `t` that breaks score ties, such as `t.created_at desc`. */
+  readonly order?: string;
+};
+//#endregion
+//#region src/config/types/entitlements.d.ts
+interface EntitlementsConfig {
+  /**
+   * `table.column` (or `schema.table.column`) holding each tenant's Stripe
+   * customer id, read by the `entitlements` SQL module. Required
+   * without the `organizations` module; with it, defaults to the
+   * `stripe_customer_id` column that module adds.
+   */
+  readonly customer?: string;
+  /** The tenant id column of that table. Defaults to `id`. */
+  readonly key?: string;
+  /**
+   * Where `has_entitlement` and `feature_claims` read memberships from.
+   * `"provider"` calls the authorization provider's `memberIds` and
+   * `memberIdsFor` functions; `"tenant"` reads `better_supabase.memberships`.
+   * Defaults to `"provider"` when `authorization` is set, else `"tenant"`.
+   */
+  readonly memberships?: "tenant" | "provider";
+  /**
+   * Where each tenant's entitlements come from. `"stripe-sync"` (the
+   * default) reads the Stripe Sync Engine's `stripe.active_entitlements`
+   * through `customer`. `{ plans }` reads a plan catalog: the tenant's
+   * active subscription and the features its plan includes. `"custom"`
+   * leaves `better_supabase.tenant_entitlements(tenant)` to you; the module
+   * writes the checks and the claim over it.
+   */
+  readonly source?: "stripe-sync" | "custom" | EntitlementPlansSource;
+  /**
+   * The shape of the features claim `feature_claims` writes, which every
+   * token carries. `false` writes `{}` (check entitlements in SQL with
+   * `has_entitlement` only); `maxTenants` keeps at most that many tenants;
+   * `keys` writes short codes instead of the feature keys. Pass the same
+   * `keys` to `hasEntitlement`.
+   */
+  readonly claim?: false | {
+    readonly maxTenants?: number;
+    readonly keys?: Readonly<Record<string, string>>;
+  };
+}
+/** `entitlements.source.plans`: a plan catalog in your own tables. */
+interface EntitlementPlansSource {
+  readonly plans: {
+    readonly subscriptions: {
+      /** `table` or `schema.table`. */
+      readonly table: string;
+      /** The tenant id column. */
+      readonly tenant: string;
+      /** The plan key column. */
+      readonly plan: string;
+      /** A status column; with it, only rows in `activeStatuses` count. */
+      readonly status?: string;
+      /** Defaults to `["active", "trialing"]`. */
+      readonly activeStatuses?: readonly string[];
+    };
+    readonly features: {
+      /** `table` or `schema.table`. */
+      readonly table: string;
+      /** The plan key column. */
+      readonly plan: string;
+      /** The feature key column: what `has_entitlement` and the claim name. */
+      readonly feature: string;
+      /** A boolean column; with it, only included features count. */
+      readonly included?: string;
+      /**
+       * A column with the feature's value (a number, text or jsonb), such as
+       * a limit, that `tenant_entitlement_value` returns.
+       */
+      readonly value?: string;
+    };
+  };
+}
+//#endregion
+//#region src/config/types/config.d.ts
+interface BetterSupabaseConfig {
+  readonly $schema?: string;
+  readonly source?: SourceConfig;
+  /** Postgres schemas to generate. Defaults to `['public']`. */
+  readonly schemas?: readonly string[];
+  /** Casing of generated models and returned rows. Defaults to `'snake'`. */
+  readonly casing?: Casing;
+  readonly tables?: Readonly<Record<string, TableConfig>>;
+  /**
+   * Main generated module. Defaults to `src/lib/supabase/generated.ts`;
+   * `database.types.ts` is written next to it.
+   */
+  readonly output?: string;
+  /**
+   * PostgREST major version, written to `__InternalSupabase` in
+   * `database.types.ts` so `createClient` picks matching behavior.
+   * Defaults to `'13'`.
+   */
+  readonly postgrestVersion?: string;
+  /** Types for jsonb columns, keyed by `table.column`. */
+  readonly json?: Readonly<Record<string, JsonTypeConfig>>;
+  readonly codecs?: CodecsConfig;
+  readonly relations?: RelationsConfig;
+  /**
+   * Columns that must not be read by accident (`table.column` or
+   * `schema.table.column`, database names), for the `noSensitiveSelect` rule.
+   */
+  readonly sensitive?: readonly string[];
+  /**
+   * Text columns that hold an object path, keyed by `table.column` or
+   * `schema.table.column` (database names), with the bucket as the value (a
+   * `buckets` key or a bucket id). Generated rows type them as
+   * `StoragePath<'bucket-id'>`.
+   */
+  readonly storagePaths?: Readonly<Record<string, string>>;
+  /**
+   * Function results `gen` may type as not null, keyed by function name.
+   * Results are `| null` by default, since Postgres can't promise a function
+   * returns a value. `notNull: true` covers the whole result (each element
+   * of a set, each column of `returns table`); a list names the
+   * `returns table` columns that are never null.
+   */
+  readonly functions?: Readonly<Record<string, FunctionConfig>>;
+  /**
+   * Data API grants, keyed by `table` or `schema.table`, and function
+   * `execute` grants, keyed by `name(argument types)` or
+   * `schema.name(argument types)`. A project with default privileges turned
+   * off grants new tables to no Data API role; the `grants` SQL module writes
+   * these as the complete privilege set (it revokes what is not listed), and
+   * doctor (BS106) checks them. Tables not listed need `select, insert,
+   * update, delete` for `authenticated` (`select` for views).
+   */
+  readonly expose?: Readonly<Record<string, ExposeConfig>>;
+  /**
+   * Modules that export `defineReadSet` results. `gen` compiles each set to
+   * a function in the `read-sets` SQL module. Node imports them, so
+   * relative imports need their `.ts` extension.
+   */
+  readonly readSets?: readonly string[];
+  readonly generators?: readonly Generator[];
+  /** Enables plugin flags in the generated metadata. */
+  readonly plugins?: PluginFlagsConfig;
+  readonly claims?: ClaimsConfig;
+  readonly buckets?: Readonly<Record<string, BucketConfig>>;
+  /** Realtime topic templates: `{ notifications: 'organization:{organizationId}:notifications' }`. */
+  readonly topics?: Readonly<Record<string, string>>;
+  readonly realtime?: RealtimeConfig;
+  readonly entitlements?: EntitlementsConfig;
+  /**
+   * An authorization system the SQL modules, policies and doctor delegate
+   * to: the `provider` access model, `entitlements.memberships` and the
+   * hook and policy checks.
+   */
+  readonly authorization?: AuthorizationProvider;
+  /**
+   * Embedding columns, keyed by `table` or `schema.table`. The
+   * `vector-search` SQL module writes `search_<table>(query, k)` for each,
+   * which `db.$search(table, { vector, k })` calls.
+   */
+  readonly vectorSearch?: Readonly<Record<string, VectorSearchConfig>>;
+  /**
+   * The app's subject types: the entities blocks attach tags, comments,
+   * fields and ranks to. Subject-bound SQL modules read this registry, the
+   * `subjects` module writes `subject_title`, `subject_url` and
+   * `can_subject` from it, and `gen` types `SubjectType` from its keys.
+   */
+  readonly subjects?: SubjectsConfig;
+  /**
+   * A named preset (`saas`, `crm`, ...), a code from `/create`, or its URL.
+   * `defineConfig` expands it into `blocks`, with the blocks they require,
+   * and the conventions it sets (`casing`, `sql.api`, `integrations`); the
+   * keys you set win.
+   */
+  readonly preset?: PresetName | (string & {});
+  /**
+   * The blocks to install and keep in sync (`better-supabase add`): a
+   * list of names, or an object keyed by block name whose values set each
+   * block's mode, schema, table and column names, permission keys and
+   * options. The foundation blocks (`tenant`, `access`, `updated-at`,
+   * `ensure-rls`, ...) are configured here too.
+   */
+  readonly blocks?: readonly string[] | BlocksConfig;
+  /**
+   * Tables the app owns, keyed by name, created in `public` by
+   * `better-supabase sql sync` with an `id`, the scope column, timestamps,
+   * row level security and policies for the scope. Columns reference each
+   * other, `auth.users` or a block's logical table. ADR 0040.
+   */
+  readonly appTables?: AppTablesConfig;
+  /** SQL-wide settings: the workflow, paths, and the `schema` and `api` every block inherits. */
+  readonly sql?: SqlConfig;
+  readonly seed?: SeedConfig;
+  /** @deprecated Use `specs`; `openapi.entry` and `openapi.output` map onto it. */
+  readonly openapi?: OpenApiConfig;
+  /** The documents `better-supabase spec emit` writes (OpenAPI, AsyncAPI, Arazzo). */
+  readonly specs?: SpecsConfig;
+  readonly doctor?: DoctorConfig;
+  /** What `better-supabase gen` runs. */
+  readonly gen?: GenConfig;
+  readonly env?: EnvFileConfig;
+  readonly scaffold?: ScaffoldConfig;
+  /** The integrations `init` and `add` wrote; `add` without a name sets up the ones that have no files yet. */
+  readonly integrations?: readonly IntegrationName[];
+  readonly skills?: SkillsConfig;
+  readonly keys?: KeysConfig;
+  /**
+   * Overrides per environment, keyed by name. The CLI applies the block
+   * for `--env <name>`, else `$BETTER_SUPABASE_ENV`, else `ci` when `$CI`
+   * is set. Objects merge into the config; arrays and other values replace.
+   */
+  readonly $env?: Readonly<Record<string, EnvironmentConfig>>;
+  /** Shorthand for `$env.development`. */
+  readonly $development?: EnvironmentConfig;
+  /** Shorthand for `$env.production`. */
+  readonly $production?: EnvironmentConfig;
+  /** Shorthand for `$env.test`. */
+  readonly $test?: EnvironmentConfig;
+  /** Shorthand for `$env.ci`, which the CLI picks when `$CI` is set. */
+  readonly $ci?: EnvironmentConfig;
+}
+/** The keys an environment block may override. */
+type EnvironmentConfig = Omit<BetterSupabaseConfig, "$schema" | "$env" | "$development" | "$production" | "$test" | "$ci" | "preset">;
+/** The config with defaults applied. */
+interface ResolvedConfig {
+  readonly root: string;
+  readonly source: SourceConfig;
+  readonly schemas: readonly string[];
+  readonly casing: Casing;
+  readonly tables: Readonly<Record<string, TableConfig>>;
+  readonly output: string;
+  /** `database.types.ts` next to `output`. */
+  readonly databaseTypesOutput: string;
+  readonly postgrestVersion: string;
+  readonly json: Readonly<Record<string, JsonTypeConfig>>;
+  readonly codecs: Required<CodecsConfig>;
+  readonly relations: Required<RelationsConfig>;
+  readonly sensitive: readonly string[];
+  readonly storagePaths: Readonly<Record<string, string>>;
+  readonly functions: Readonly<Record<string, FunctionConfig>>;
+  /** The table entries of `expose`. */
+  readonly expose: Readonly<Record<string, ResolvedExpose>>;
+  /** The function entries of `expose`: the roles that may execute each one. */
+  readonly exposeFunctions: Readonly<Record<string, readonly ExposeRole[]>>;
+  readonly readSets: readonly string[];
+  readonly generators: readonly Generator[];
+  readonly plugins: {
+    readonly timestamps: Required<TimestampsConfig> | undefined;
+    readonly softDelete: Required<SoftDeleteConfig> | undefined;
+    readonly tenant: Required<TenantConfig> | undefined;
+    readonly actor: Required<ActorConfig> | undefined;
+  };
+  readonly claims: Required<ClaimsConfig>;
+  readonly buckets: Readonly<Record<string, BucketConfig>>;
+  readonly entitlements: {
+    /** Unset without `entitlements.customer`. */
+    readonly table?: string;
+    readonly column?: string;
+    readonly key: string;
+    readonly memberships: "tenant" | "provider";
+    readonly source: NonNullable<EntitlementsConfig["source"]>;
+    readonly claim?: NonNullable<EntitlementsConfig["claim"]>;
+  };
+  readonly authorization?: AuthorizationProvider;
+  readonly vectorSearch: readonly ({
+    readonly table: string;
+    readonly column: string;
+    readonly distance: VectorDistance;
+  } & Omit<Exclude<VectorSearchConfig, string>, "column" | "distance">)[];
+  readonly subjects: SubjectsConfig;
+  readonly topics: Readonly<Record<string, string>>;
+  readonly realtime: Required<Omit<RealtimeConfig, "policies">> & {
+    readonly policies?: TopicPoliciesConfig;
+  };
+  /** The `preset` the config started from, as written; `blocks` already holds it expanded. */
+  readonly preset?: string;
+  /** `blocks` with `sql.schema` and `sql.api` applied, keyed by block name. */
+  readonly blocks: AnyBlocksConfig;
+  /** The installed blocks, in config order. */
+  readonly blockNames: readonly string[];
+  /** `appTables`, checked; empty without any. */
+  readonly appTables: AppTablesConfig;
+  readonly sql: ResolvedSqlConfig;
+  readonly seed: Required<SeedConfig>;
+  readonly openapi: Required<OpenApiConfig>;
+  readonly specs: {
+    readonly entry: string;
+    readonly outputs: readonly SpecOutputConfig[];
+    readonly failOn: NonNullable<SpecsConfig["failOn"]>;
+    readonly manifest?: string;
+  };
+  readonly doctor: Required<Omit<DoctorConfig, "claimsLimit" | "output">> & Pick<DoctorConfig, "claimsLimit" | "output">;
+  /** `tasks` stays unset without a list, so `gen` picks the steps the project uses. */
+  readonly gen: GenConfig;
+  readonly env: {
+    readonly output: string;
+    readonly prefix?: string;
+  };
+  readonly scaffold: ScaffoldConfig;
+  readonly integrations: readonly IntegrationName[];
+  readonly skills: SkillsConfig;
+  readonly keys: KeysConfig;
+  /** The environment block the CLI applied, when one was active. */
+  readonly environment?: string;
+}
+//#endregion
+//#region src/config/types/codegen.d.ts
+/**
+ * Where codegen reads the database from. Without any of these, `$DATABASE_URL`,
+ * `$SUPABASE_DB_URL` and then the local stack (`supabase start`) are used.
+ */
+interface SourceConfig {
+  /** Postgres connection string. */
+  readonly dbUrl?: string;
+  /**
+   * Hosted project ref. Read through the Management API's read-only SQL
+   * endpoint, so no database password is needed.
+   */
+  readonly projectRef?: string;
+  /**
+   * Management API token for `projectRef`. Defaults to
+   * `$SUPABASE_ACCESS_TOKEN`; prefer the env var over committing a token.
+   */
+  readonly accessToken?: string;
+  /** Read a saved `better-supabase introspect` snapshot instead of connecting. */
+  readonly snapshot?: string;
+  /**
+   * Read a Supabase Lite project's schema the way Lite runs it, from
+   * `[db] driver` in `supabase/config.toml`. On by default when that key is
+   * present; `false` reads the database like any other project.
+   */
+  readonly lite?: boolean;
+}
+/**
+ * A JSON Schema object, or a Standard JSON Schema value (zod 4, valibot,
+ * arktype, ...) that can produce one.
+ */
+type JsonSchemaSource = Readonly<Record<string, unknown>> | {
+  readonly "~standard": {
+    readonly jsonSchema: {
+      readonly input: (options: {
+        readonly target: string;
+      }) => Record<string, unknown>;
+    };
+  };
+};
+type JsonTypeConfig = ({
+  readonly import: string;
+} | {
+  readonly type: string;
+}) & {
+  /** Enforced in the database by `better-supabase add jsonb-schemas` (pg_jsonschema). */
+  readonly schema?: JsonSchemaSource;
+};
+interface TableConfig {
+  readonly casing?: Casing;
+  /** Leave the table out of the generated models. */
+  readonly exclude?: boolean;
+  /**
+   * Keep the table off the Data API on purpose: only `service_role` reaches
+   * it. The models are still generated for admin clients, and doctor (BS106)
+   * checks that `anon` and `authenticated` have no grants instead of
+   * requiring them.
+   */
+  readonly serviceRole?: boolean;
+  /** Rename generated relations: `{ primaryContact: 'contact' }`. */
+  readonly relations?: Readonly<Record<string, string>>;
+  /**
+   * Database names of not-null columns an insert may leave out because the
+   * database fills them, for example from a `before insert` trigger. `gen`
+   * makes them optional in `InsertOf` and the insert validators.
+   */
+  readonly insertOptional?: readonly string[];
+}
+interface FunctionConfig {
+  /** `true`, or the `returns table` columns (database names) that are never null. */
+  readonly notNull?: true | readonly string[];
+}
+interface TimestampsConfig {
+  readonly createdAt?: string;
+  readonly updatedAt?: string;
+}
+interface SoftDeleteConfig {
+  readonly column?: string;
+}
+interface TenantConfig {
+  /** Defaults to `organization_id`, or `<sql.naming.tenant>_id` when the tenant is renamed. */
+  readonly column?: string;
+}
+/** Claim names shared by the SQL modules, codegen and the runtime defaults. */
+interface ClaimsConfig {
+  /** Top-level claim holding the active tenant id. Defaults to `tenant_id`. */
+  readonly tenant?: string;
+  /** `scope` of the tenant entries `membership_claims()` writes. Defaults to `tenant`. */
+  readonly scope?: string;
+  /** Claim holding plan features per tenant (`{ [tenantId]: string[] }`). Defaults to `features`. */
+  readonly features?: string;
+  /** Claim the memberships hook (`membership_claims()` or the provider's) writes. Defaults to `memberships`. */
+  readonly memberships?: string;
+}
+interface ActorConfig {
+  readonly createdBy?: string;
+  readonly updatedBy?: string;
+  /** Defaults to `impersonated_by`, the column the SQL modules' `track_actor` fills. */
+  readonly impersonatedBy?: string;
+}
+interface PluginFlagsConfig {
+  readonly timestamps?: boolean | TimestampsConfig;
+  readonly softDelete?: boolean | SoftDeleteConfig;
+  readonly tenant?: boolean | TenantConfig;
+  readonly actor?: boolean | ActorConfig;
+}
+/**
+ * Runtime types for columns whose JSON form loses information. Defaults
+ * match `supabase gen types`: timestamps as ISO strings, `int8` and
+ * `numeric` as numbers.
+ */
+interface CodecsConfig {
+  /**
+   * `'instant'` decodes `timestamptz` columns to `Temporal.Instant` and
+   * `timestamp` columns to `Temporal.PlainDateTime`.
+   */
+  readonly timestamptz?: "string" | "instant";
+  /** `'bigint'` or `'string'` read `int8` exactly (above 2^53). */
+  readonly int8?: "number" | "string" | "bigint";
+  /** `'string'` reads `numeric` exactly. */
+  readonly numeric?: "number" | "string";
+}
+interface GeneratedFile {
+  /** Path relative to the project root. */
+  readonly path: string;
+  readonly contents: string;
+}
+interface GeneratorInput {
+  readonly meta: SchemaMeta;
+  /**
+   * The `@supabase/postgrest-typegen` metadata for the configured schemas,
+   * the same contract `supabase gen types` is built on.
+   */
+  readonly introspection: GeneratorMetadata;
+  /** Constraints, indexes, policies, triggers and grants typegen leaves out. */
+  readonly extras: SnapshotExtras;
+  readonly config: ResolvedConfig;
+  /** Absolute path of the main generated module. */
+  readonly output: string;
+  /** Import path from `from` (a generated file) to `to`, with extension. */
+  readonly importPath: (from: string, to: string) => string;
+  /**
+   * Where generated files import `better-supabase` runtime helpers from.
+   * Defaults to `better-supabase`.
+   */
+  readonly runtimeImport?: string;
+  /**
+   * The tables and enums `gen` emits, with the TypeScript type it wrote for
+   * each column (after `json` overrides, codecs and enum unions). Frozen.
+   */
+  readonly model: GeneratorModel;
+}
+interface GeneratorColumn {
+  /** Name in rows, after casing. */
+  readonly app: string;
+  /** Database name. */
+  readonly db: string;
+  /** TypeScript type without `| null`. */
+  readonly tsType: string;
+  readonly nullable: boolean;
+  /** Optional on insert. */
+  readonly optional: boolean;
+  /** Generated or identity always: never written. */
+  readonly readonly: boolean;
+  /** Enum or check-constraint values, when the column has a closed set. */
+  readonly values: readonly string[] | undefined;
+  readonly json: boolean;
+}
+interface GeneratorTable {
+  /** Key in `schema.tables` and on the client. */
+  readonly key: string;
+  readonly schema: string;
+  readonly name: string;
+  readonly casing: Casing;
+  readonly columns: readonly GeneratorColumn[];
+}
+interface GeneratorModel {
+  readonly tables: readonly GeneratorTable[];
+  readonly enums: readonly {
+    readonly schema: string;
+    readonly name: string;
+    readonly values: readonly string[];
+  }[];
+}
+/**
+ * Codegen extension point. First-party generators: `zod()`, `valibot()`,
+ * `jsonSchema()`, `standardSchema()`. Prove custom ones with `testGenerator`.
+ */
+interface Generator {
+  /** The generator contract it targets. `gen` refuses versions it doesn't know. */
+  readonly apiVersion?: 1;
+  readonly name: string;
+  generate(input: GeneratorInput): readonly GeneratedFile[] | Promise<readonly GeneratedFile[]>;
+}
+interface RelationsConfig {
+  /**
+   * Type a to-one include as `| null` when the related table has row level
+   * security, even over a `not null` foreign key, since a policy can hide
+   * the related row. `required: true` on the include keeps it non-null.
+   * Defaults to `false`.
+   */
+  readonly nullableUnderRls?: boolean;
+}
+//#endregion
+export { PresetAccess as $, RpcFunctionReturns as $t, TopicTriggerConfig as A, CatalogFunction as At, PRESETS as B, ExtrasHookFunction as Bt, EntitlementsConfig as C, SkillsConfig as Ct, SeedConfig as D, CatalogColumnGrant as Dt, ResolvedSqlConfig as E, CatalogColumn as Et, ExposePrivilege as F, CatalogTable as Ft, isPresetName as G, SnapshotExtras as Gt, PRESET_NAMES as H, ForeignKeyAction as Ht, ExposeRole as I, CatalogTrigger as It, PRESET_FIELDS as J, PostgresFunction as Jt, namedPreset as K, GeneratorMetadata as Kt, Privilege as L, CatalogUnique as Lt, VectorSearchConfig as M, CatalogGrant as Mt, ColumnPrivilege as N, CatalogIndex as Nt, SqlConfig as O, CatalogEnum as Ot, ExposeConfig as P, CatalogPolicy as Pt, Preset as Q, RpcFunctionOverload as Qt, ResolvedExpose as R, ExtrasFunction as Rt, EntitlementPlansSource as S, AppTablesConfig as Sn, SkillsAgent as St, RealtimeConfig as T, CatalogCheck as Tt, PresetGroup as U, Snapshot as Ut, PRESET_GROUPS as V, ExtrasTable as Vt, PresetName as W, SnapshotBucket as Wt, PRESET_TENANT_NAMES as X, RpcFunction as Xt, PRESET_FRAMEWORKS as Y, PostgresFunctionArg as Yt, PRESET_VERSION as Z, RpcFunctionArg as Zt, TenantConfig as _, AppReferenceTarget as _n, IntegrationName as _t, Generator as a, IntegrationInfo as an, PresetFramework as at, EnvironmentConfig as b, AppTableConfig as bn, ScaffoldApiConfig as bt, GeneratorModel as c, APP_COLUMN_TYPES as cn, PresetTenantName as ct, JsonTypeConfig as d, AppColumnConfig as dn, presetField as dt, RpcReturnColumn as en, PresetCodeField as et, PluginFlagsConfig as f, AppColumnFormat as fn, presetValueLabel as ft, TableConfig as g, AppReference as gn, GenTask as gt, SourceConfig as h, AppOnDeleteAction as hn, GenConfig as ht, GeneratedFile as i, INTEGRATION_NAMES as in, PresetFieldValue as it, VectorDistance as j, CatalogFunctionArg as jt, SqlWorkflow as k, CatalogForeignKey as kt, GeneratorTable as l, APP_ON_DELETE_ACTIONS as ln, PresetValueInfo as lt, SoftDeleteConfig as m, AppLookupConfig as mn, EnvFileConfig as mt, ClaimsConfig as n, GEN_TASKS as nn, PresetField as nt, GeneratorColumn as o, SKILLS_AGENTS as on, PresetPlatforms as ot, RelationsConfig as p, AppColumnType as pn, DoctorConfig as pt, DEFAULT_CONVENTIONS as q, PostgresColumn as qt, CodecsConfig as r, INTEGRATION_INFO as rn, PresetFieldKey as rt, GeneratorInput as s, APP_COLUMN_FORMATS as sn, PresetScope as st, ActorConfig as t, RpcTypeReference as tn, PresetConventions as tt, JsonSchemaSource as u, APP_ROLLUP_AGGREGATES as un, integrationsForFramework as ut, TimestampsConfig as v, AppRollupAggregate as vn, KeysConfig as vt, BucketConfig as w, Catalog as wt, ResolvedConfig as x, AppTableSubject as xn, ScaffoldConfig as xt, BetterSupabaseConfig as y, AppRollupConfig as yn, OpenApiConfig as yt, NamedPreset as z, ExtrasHook as zt };