better-supabase 0.7.0 → 0.8.0

package/dist/{config-D44Y7PAv.d.ts → index-Ba1SI-uO.d.ts}

@@ -1,7 +1,60 @@
 /// <reference lib="esnext.temporal" />
-import { P as SchemaMeta, U as BucketLifecycle, c as Casing, s as BucketPolicyName, t as AccessBucketPolicy } from "./types-6BdhkmZe.js";
+import { P as SchemaMeta, U as BucketLifecycle, c as Casing, s as BucketPolicyName, t as AccessBucketPolicy, u as ClaimsMeta } from "./types-CoE5Zwy4.js";
 import { s as ModulesConfig } from "./modules-DpPwzC7E.js";
 import { i as AuthorizationProvider } from "./authorization-BFCqamMs.js";
+//#region src/config/defaults.d.ts
+/**
+ * Every default `resolveConfig` fills in. Other modules (the SQL module
+ * registry, the CLI) read their fallbacks from here instead of repeating the
+ * literals.
+ */
+declare const CONFIG_DEFAULTS: {
+  readonly output: string;
+  readonly schemas: readonly string[];
+  readonly casing: "snake";
+  readonly postgrestVersion: string;
+  readonly codecs: {
+    readonly timestamptz: "string";
+    readonly int8: "number";
+    readonly numeric: "number";
+  };
+  readonly sql: {
+    readonly dir: string;
+    readonly prefix: string;
+    readonly testsDir: string;
+  };
+  readonly seed: {
+    readonly entry: string;
+    readonly output: string;
+  };
+  readonly openapi: {
+    readonly entry: string;
+    readonly output: string;
+  };
+  readonly specs: {
+    readonly failOn: "error";
+  };
+  readonly doctor: {
+    readonly format: "text";
+    readonly sources: readonly string[];
+    readonly policyHelperLimit: number;
+  };
+  readonly gen: {
+    readonly watchInterval: number;
+  };
+  readonly env: {
+    readonly output: string;
+  };
+};
+//#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"];
+/** 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
@@ -402,107 +455,35 @@ interface CatalogFunctionArg {
   readonly hasDefault: boolean;
 }
 //#endregion
-//#region src/config/config.d.ts
-/**
- * Where codegen reads the database from. Without any of these, `$DATABASE_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;
-}
+//#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";
 /**
- * A JSON Schema object, or a Standard JSON Schema value (zod 4, valibot,
- * arktype, ...) that can produce one.
+ * 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 JsonSchemaSource = Readonly<Record<string, unknown>> | {
-  readonly "~standard": {
-    readonly jsonSchema: {
-      readonly input: (options: {
-        readonly target: string;
-      }) => Record<string, unknown>;
-    };
-  };
-};
-type JsonTypeConfig = ({
-  readonly import: string;
+type ExposeConfig = readonly ExposePrivilege[] | {
+  readonly anon?: readonly ExposePrivilege[];
+  readonly authenticated?: readonly ExposePrivilege[];
+  readonly serviceRole?: readonly ExposePrivilege[];
 } | {
-  readonly type: string;
-}) & {
-  /** Enforced in the database by `sql add jsonb-schemas` (pg_jsonschema). */
-  readonly schema?: JsonSchemaSource;
-};
-/** The JSON Schema document for a `json[...].schema` entry. */
-declare function resolveJsonSchema(source: JsonSchemaSource): Readonly<Record<string, unknown>>;
-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 execute: readonly ("anon" | "authenticated")[];
   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 {
-  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;
+};
+/** 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;
@@ -549,117 +530,6 @@ interface SeedConfig {
   /** SQL file `better-supabase seed` writes. Add it to `[db.seed] sql_paths`. */
   readonly output?: string;
 }
-interface OpenApiConfig {
-  /** Module exporting the document (or a function returning it) as `openapi` or default. */
-  readonly entry?: string;
-  /** JSON file `better-supabase openapi emit` writes. */
-  readonly output?: string;
-}
-interface DoctorConfig {
-  /** Finding codes to skip, e.g. `['BS204']`. */
-  readonly ignore?: readonly string[];
-  /** Treat warnings as errors. */
-  readonly strict?: boolean;
-  /**
-   * 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;
-}
-/**
- * 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;
-  /**
-   * 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()`. 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 RealtimeConfig {
   /**
    * Tables that broadcast a change signal for live queries (`table` or
@@ -694,12 +564,50 @@ interface TopicPoliciesConfig {
   /** The SQL file to write, such as `supabase/schemas/905_topics.sql`. */
   readonly output: string;
 }
-interface EntitlementsConfig {
+/** 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;
   /**
-   * `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.
+   * 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`. */
@@ -764,77 +672,122 @@ interface EntitlementPlansSource {
     };
   };
 }
-/** 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;
+//#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 openapi emit` 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 {
   /**
-   * Fuses a full-text ranking over a `tsvector` column with the vector
-   * ranking (reciprocal rank fusion), for `db.$search({ text })`.
+   * 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 `sql.modules` 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 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[];
+  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;
   /**
-   * 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)`.
+   * Prefix for the browser variables, such as `NEXT_PUBLIC_`; `'none'` for
+   * no prefix. Detected from the framework by default.
    */
-  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;
-};
-/** 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[];
+  readonly prefix?: string;
 }
-interface RelationsConfig {
+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;
   /**
-   * 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`.
+   * App source files doctor scans for API use (BS210). Globs relative to the
+   * root. Defaults to `['src/**\/*.{ts,tsx}']`.
    */
-  readonly nullableUnderRls?: boolean;
+  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/config/types/config.d.ts
 interface BetterSupabaseConfig {
   readonly $schema?: string;
   readonly source?: SourceConfig;
@@ -917,9 +870,36 @@ interface BetterSupabaseConfig {
   readonly vectorSearch?: Readonly<Record<string, VectorSearchConfig>>;
   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">;
 /** The config with defaults applied. */
 interface ResolvedConfig {
   readonly root: string;
@@ -973,12 +953,379 @@ interface ResolvedConfig {
   readonly sql: ResolvedSqlConfig;
   readonly seed: Required<SeedConfig>;
   readonly openapi: Required<OpenApiConfig>;
-  readonly doctor: Required<Omit<DoctorConfig, "claimsLimit">> & Pick<DoctorConfig, "claimsLimit">;
+  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 `sql 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 {
+  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
+//#region src/config/json.d.ts
+/**
+ * The JSON Schema document for a `json[...].schema` entry. A Standard
+ * Schema converts for `target` (2020-12 by default); a JSON Schema object is
+ * returned as it is.
+ */
+declare function resolveJsonSchema(source: JsonSchemaSource, target?: "draft-2020-12" | "draft-07" | "openapi-3.0"): Readonly<Record<string, unknown>>;
+//#endregion
+//#region src/config/resolve.d.ts
 declare const CONFIG_SCHEMA_URL = "https://unpkg.com/better-supabase/schemas/config-v1.json";
 /** Identity helper that types `better-supabase.config.ts`. */
 declare function defineConfig(config: BetterSupabaseConfig): BetterSupabaseConfig;
 /** Applies defaults. Paths stay relative to `root`. */
 declare function resolveConfig(config: BetterSupabaseConfig, root: string): ResolvedConfig;
 //#endregion
-export { CatalogTable as $, SeedConfig as A, resolveConfig as B, PluginFlagsConfig as C, ResolvedConfig as D, RelationsConfig as E, TenantConfig as F, CatalogColumnGrant as G, Catalog as H, TimestampsConfig as I, CatalogFunction as J, CatalogEnum as K, VectorDistance as L, SourceConfig as M, SqlConfig as N, ResolvedExpose as O, TableConfig as P, CatalogPolicy as Q, VectorSearchConfig as R, OpenApiConfig as S, RealtimeConfig as T, CatalogCheck as U, resolveJsonSchema as V, CatalogColumn as W, CatalogGrant as X, CatalogFunctionArg as Y, CatalogIndex as Z, GeneratorInput as _, ClaimsConfig as a, ExtrasTable as at, JsonSchemaSource as b, DoctorConfig as c, SnapshotBucket as ct, ExposeConfig as d, PostgresColumn as dt, CatalogTrigger as et, ExposePrivilege as f, PostgresFunction as ft, GeneratorColumn as g, Generator as h, CONFIG_SCHEMA_URL as i, ExtrasHookFunction as it, SoftDeleteConfig as j, ResolvedSqlConfig as k, EntitlementPlansSource as l, SnapshotExtras as lt, GeneratedFile as m, BetterSupabaseConfig as n, ExtrasFunction as nt, CodecsConfig as o, ForeignKeyAction as ot, ExposeRole as p, PostgresFunctionArg as pt, CatalogForeignKey as q, BucketConfig as r, ExtrasHook as rt, ColumnPrivilege as s, Snapshot as st, ActorConfig as t, CatalogUnique as tt, EntitlementsConfig as u, GeneratorMetadata as ut, GeneratorModel as v, Privilege as w, JsonTypeConfig as x, GeneratorTable as y, defineConfig as z };
+//#region src/core/claims.d.ts
+declare const DEFAULT_CLAIMS: ClaimsMeta;
+/** Where an adapter reads each claim the SQL modules and the provider's hook write. */
+interface ClaimPaths {
+  /** The active tenant: the top-level claim, then the same key in `app_metadata`. */
+  readonly tenant: readonly [string, string];
+  /** `{ [tenantId]: string[] }` of plan features. */
+  readonly features: string;
+  /** The caller's memberships, a list of `{ scope, id, roles }` or a map of tenant id to role. */
+  readonly memberships: string;
+  /** The `scope` of tenant entries in the memberships list. */
+  readonly scope: string;
+}
+/**
+ * The claim paths for `config.claims`, with defaults. For a generated
+ * schema, pass `claimsOf(meta)`.
+ */
+declare function claimPaths(claims?: Partial<ClaimsMeta>): ClaimPaths;
+/** Where the active tenant is read from: the top-level claim, then `app_metadata`. */
+declare function tenantClaimPaths(tenant?: string): readonly [string, string];
+//#endregion
+//#region src/generators/json-schema-target.d.ts
+/** The JSON Schema dialects the generators and MCP emit. */
+type JsonSchemaTarget = "draft-2020-12" | "draft-07" | "openapi-3.0";
+//#endregion
+//#region src/generators/shared.d.ts
+/** What field planning reads: the metadata and the typed-jsonb config. */
+interface SchemaSource {
+  readonly meta: SchemaMeta;
+  readonly config: {
+    readonly json: Readonly<Record<string, unknown>>;
+  };
+  readonly runtimeImport?: string;
+}
+interface CommentEntry {
+  readonly id: number;
+  readonly schema: string;
+  readonly name: string;
+  readonly comment: string | null;
+}
+/**
+ * The catalog parts docs read: `GeneratorInput` satisfies it. Runtime callers
+ * that only have `meta` (OpenAPI, MCP) pass none and get no docs.
+ */
+interface DocsSource extends SchemaSource {
+  readonly introspection?: {
+    readonly tables: readonly CommentEntry[];
+    readonly views: readonly CommentEntry[];
+    readonly materializedViews?: readonly CommentEntry[];
+    readonly columns: readonly {
+      readonly table_id: number;
+      readonly name: string;
+      readonly comment: string | null;
+      readonly check: string | null;
+    }[];
+  };
+  readonly extras?: {
+    readonly tables: readonly {
+      readonly schema: string;
+      readonly name: string;
+      readonly checks: readonly {
+        readonly definition: string;
+      }[];
+    }[];
+  };
+}
+//#endregion
+//#region src/generators/json-schema.d.ts
+interface JsonSchemaGeneratorOptions {
+  /** Output path relative to the project root. Defaults to `<output>.schema.json`. */
+  readonly output?: string;
+  /** `$id` of the document. */
+  readonly id?: string;
+  /**
+   * The dialect. `draft-2020-12` (the default) writes `$defs`; `draft-07`
+   * and `openapi-3.0` (`nullable`, `example`) write `definitions`.
+   */
+  readonly target?: JsonSchemaTarget;
+}
+type JsonSchema = Record<string, unknown>;
+/**
+ * JSON Schema `$defs` for every table: `customersRow`, `customersInsert`,
+ * ... `target` lowers the document to draft-07 or the OpenAPI 3.0 dialect,
+ * which keep the schemas under `definitions`.
+ */
+declare function buildJsonSchema(input: DocsSource, id?: string, target?: JsonSchemaTarget): JsonSchema;
+/** Writes the JSON Schema document; `createOpenApi` reuses the same `$defs`. */
+declare function jsonSchema(options?: JsonSchemaGeneratorOptions): Generator;
+//#endregion
+//#region src/generators/standard-schema.d.ts
+interface StandardSchemaGeneratorOptions {
+  /** Output path relative to the project root. Defaults to `<output>.standard.ts`. */
+  readonly output?: string;
+  /**
+   * Standard Schemas for typed jsonb columns:
+   * `{ 'customers.metadata': './schemas.ts#metadata' }`.
+   */
+  readonly json?: Readonly<Record<string, string>>;
+}
+/**
+ * Standard Schemas for every table's Row, Insert and Update shape, with no
+ * validation library. Each one also converts to JSON Schema (Standard JSON
+ * Schema), and `validators` plugs into the validation plugin.
+ */
+declare function standardSchema(options?: StandardSchemaGeneratorOptions): Generator;
+//#endregion
+//#region src/generators/valibot.d.ts
+interface ValibotGeneratorOptions {
+  /** Output path relative to the project root. Defaults to `<output>.valibot.ts`. */
+  readonly output?: string;
+  /** Schemas for typed jsonb columns: `{ 'customers.metadata': './schemas.ts#metadata' }`. */
+  readonly json?: Readonly<Record<string, string>>;
+}
+/** Valibot schemas for every table's Row, Insert and Update shape. */
+declare function valibot(options?: ValibotGeneratorOptions): Generator;
+//#endregion
+//#region src/generators/zod.d.ts
+interface ZodGeneratorOptions {
+  /** Output path relative to the project root. Defaults to `<output>.zod.ts`. */
+  readonly output?: string;
+  /** Schemas for typed jsonb columns: `{ 'customers.metadata': './schemas.ts#metadata' }`. */
+  readonly json?: Readonly<Record<string, string>>;
+  /**
+   * `classic` (the default) imports `zod` and chains methods; `mini` imports
+   * `zod/mini` and uses its functional API (`z.nullable(...)`, `.check(...)`),
+   * which tree-shakes to a smaller bundle. Both need zod 4.
+   */
+  readonly flavor?: ZodFlavor;
+}
+type ZodFlavor = "classic" | "mini";
+/**
+ * Zod 4 schemas for every table's Row, Insert and Update shape, for `zod`
+ * or, with `flavor: 'mini'`, `zod/mini`.
+ */
+declare function zod(options?: ZodGeneratorOptions): Generator;
+//#endregion
+export { EntitlementsConfig as $, JsonTypeConfig as A, ExtrasTable as At, ResolvedConfig as B, INTEGRATION_NAMES as Bt, GeneratedFile as C, CatalogPolicy as Ct, GeneratorModel as D, ExtrasFunction as Dt, GeneratorInput as E, CatalogUnique as Et, TableConfig as F, GeneratorMetadata as Ft, IntegrationName as G, EnvFileConfig as H, CONFIG_DEFAULTS as Ht, TenantConfig as I, PostgresColumn as It, ScaffoldApiConfig as J, KeysConfig as K, TimestampsConfig as L, PostgresFunction as Lt, RelationsConfig as M, Snapshot as Mt, SoftDeleteConfig as N, SnapshotBucket as Nt, GeneratorTable as O, ExtrasHook as Ot, SourceConfig as P, SnapshotExtras as Pt, EntitlementPlansSource as Q, BetterSupabaseConfig as R, PostgresFunctionArg as Rt, CodecsConfig as S, CatalogIndex as St, GeneratorColumn as T, CatalogTrigger as Tt, GenConfig as U, DoctorConfig as V, SKILLS_AGENTS as Vt, GenTask as W, SkillsAgent as X, ScaffoldConfig as Y, SkillsConfig as Z, defineConfig as _, CatalogEnum as _t, valibot as a, VectorDistance as at, ActorConfig as b, CatalogFunctionArg as bt, JsonSchemaGeneratorOptions as c, ExposeConfig as ct, JsonSchemaTarget as d, Privilege as dt, BucketConfig as et, ClaimPaths as f, ResolvedExpose as ft, CONFIG_SCHEMA_URL as g, CatalogColumnGrant as gt, tenantClaimPaths as h, CatalogColumn as ht, ValibotGeneratorOptions as i, SqlConfig as it, PluginFlagsConfig as j, ForeignKeyAction as jt, JsonSchemaSource as k, ExtrasHookFunction as kt, buildJsonSchema as l, ExposePrivilege as lt, claimPaths as m, CatalogCheck as mt, ZodGeneratorOptions as n, ResolvedSqlConfig as nt, StandardSchemaGeneratorOptions as o, VectorSearchConfig as ot, DEFAULT_CLAIMS as p, Catalog as pt, OpenApiConfig as q, zod as r, SeedConfig as rt, standardSchema as s, ColumnPrivilege as st, ZodFlavor as t, RealtimeConfig as tt, jsonSchema as u, ExposeRole as ut, resolveConfig as v, CatalogForeignKey as vt, Generator as w, CatalogTable as wt, ClaimsConfig as x, CatalogGrant as xt, resolveJsonSchema as y, CatalogFunction as yt, EnvironmentConfig as z, GEN_TASKS as zt };