better-supabase 0.12.0 → 0.13.0

package/dist/create/index.d.ts

@@ -1,8 +1,100 @@
-import { Q as ModuleAccessProvider } from "../index-Cm2-g_4H.js";
-import { Cn as AppOnDeleteAction, Mn as AppTableVersions, bn as AppColumnFormat, hn as APP_ON_DELETE_ACTIONS, nt as Preset, vn as AppColumnAccess, xn as AppColumnType } from "../codegen-C64C0NZG.js";
-import { M as PresetInput, c as DesignChange, p as CreateDesign } from "../index-BJLPQr2s.js";
-import { a as SupabaseLint, o as SupabaseOrganization, s as SupabaseProject } from "../management-D1gG89z2.js";
+/// <reference lib="esnext.temporal" />
+import { et as ModuleAccessProvider } from "../index-DdZcWH6q.js";
+import { Cn as AppColumnFormat, En as AppOnDeleteAction, Fn as AppTableVersions, at as Preset, vn as APP_ON_DELETE_ACTIONS, wn as AppColumnType, xn as AppColumnAccess } from "../codegen-DGtOsqz9.js";
+import { c as DesignChange, g as DesignErrorCode, p as CreateDesign, z as PresetInput } from "../index-PADpaDku.js";
+import { a as SupabaseLint, o as SupabaseOrganization, s as SupabaseProject } from "../management-wtecfrNf.js";
 import { t as PresetMigrationFile } from "../types-DGHfTW8_.js";
+//#region src/create/design-computed.d.ts
+/** The aggregates a rollup takes (`APP_ROLLUP_AGGREGATES`). */
+export declare const ROLLUP_AGGREGATES: readonly ["count", "sum", "min", "max", "avg"];
+export type RollupAggregate = (typeof ROLLUP_AGGREGATES)[number];
+/** `appTables.<table>.rollups.<name>`; the shape of `AppRollupConfig`. */
+export interface AppRollup {
+  readonly table: string;
+  readonly via: string;
+  readonly aggregate: RollupAggregate;
+  readonly column?: string;
+  readonly where?: {
+    readonly column: string;
+    readonly equals: string;
+  };
+}
+/** `appTables.<table>.lookups.<name>`; the shape of `AppLookupConfig`. */
+export interface AppLookup {
+  readonly via: string;
+  readonly column: string;
+}
+/** A rollup or lookup as a table node and the inspector list it. */
+export interface ComputedRow {
+  readonly name: string;
+  readonly kind: "rollup" | "lookup";
+  /** What it computes, such as `count of tasks where status = todo`. */
+  readonly summary: string;
+  /** The short form the node shows next to the name, such as `count`. */
+  readonly label: string;
+}
+type Tables = Readonly<Record<string, AppTable>>;
+export declare function isRollupAggregate(value: unknown): value is RollupAggregate;
+/** The columns of `table` a rollup or lookup can read, with their types. */
+export declare function readableColumns(table: AppTable): readonly (readonly [string, AppColumnType])[];
+/**
+ * The columns `aggregate` can read: numbers for sum and avg, ordered types for
+ * min and max, none for count.
+ */
+export declare function rollupColumns(child: AppTable, aggregate: RollupAggregate): readonly string[];
+/** The select columns of `child` (text with options) a rollup can filter on. */
+export declare function filterColumns(child: AppTable): readonly (readonly [string, readonly string[]])[];
+/**
+ * Each app table column that references `parent`, as `{ table, via }`: what a
+ * rollup on `parent` can aggregate.
+ */
+export declare function rollupSources(tables: Tables, parent: string): readonly {
+  readonly table: string;
+  readonly via: string;
+}[];
+/**
+ * Each column of `name` that references another app table, with that table:
+ * what a lookup can follow.
+ */
+export declare function lookupSources(tables: Tables, name: string): readonly {
+  readonly via: string;
+  readonly target: string;
+}[];
+export type DraftRollup = { -readonly [K in keyof AppRollup]: AppRollup[K]; };
+/**
+ * `table` with a rollup or lookup set under `name`, replacing `previous` in its
+ * place.
+ */
+export declare function tableWithComputed(table: AppTable, name: string, computed: {
+  readonly rollup: AppRollup;
+} | {
+  readonly lookup: AppLookup;
+}, previous: string): AppTable;
+/** `table` without the rollup or lookup `name`. */
+export declare function tableWithoutComputed(table: AppTable, name: string): AppTable;
+/**
+ * The tables with every rollup and lookup that no longer fits dropped: one
+ * whose table, link or column was deleted or retyped, or whose name a column
+ * now uses. `sql sync` would refuse them, and the design code would not
+ * encode.
+ */
+export declare function prunedComputed(tables: Tables): Tables;
+/** The rollups that aggregate `from`, pointed at `to`. */
+export declare function computedTableRenamed(tables: Tables, from: string, to: string): Tables;
+/**
+ * The rollup fitted to a new source or aggregate: a column the aggregate can
+ * read, and a filter the child still has.
+ */
+export declare function fittedRollup(tables: Tables, rollup: AppRollup): AppRollup;
+/**
+ * Every rollup and lookup that reads `table.from`, reading `table.to`. The
+ * tables already have the column renamed, so a lookup finds its target through
+ * the renamed link.
+ */
+export declare function computedColumnRenamed(tables: Tables, table: string, from: string, to: string): Tables;
+/** The rollups and lookups of an app table, in the view's column order. */
+export declare function computedRows(table: AppTable): readonly ComputedRow[];
+//#endregion
 //#region src/create/schema.d.ts
 /** One rendered SQL file, as `/create/migrations` returns it. */
 export interface SchemaSource {
@@ -10,7 +102,10 @@ export interface SchemaSource {
   readonly module: string;
   readonly contents: string;
 }
-/** The table a foreign key points at. `columns` is empty when the SQL names none: the target's primary key. */
+/**
+ * The table a foreign key points at. `columns` is empty when the SQL names
+ * none: the target's primary key.
+ */
 export interface SchemaTarget {
   readonly schema: string;
   readonly table: string;
@@ -56,8 +151,8 @@ export interface SchemaComputed {
 }
 /**
  * A column that points at a table without a foreign key: the tenant or user
- * column a block keeps plain so its rows outlive deletes, or a `regclass`
- * that names any table (`to` is `null`).
+ * column a block keeps plain so its rows outlive deletes, or a `regclass` that
+ * names any table (`to` is `null`).
  */
 export interface SchemaSoftRef {
   readonly from: string;
@@ -73,7 +168,10 @@ export interface SchemaData {
   readonly manifests: Readonly<Record<string, string>>;
   /** The table ids `blocks.<module>.options.extraColumns` adds columns to. */
   readonly extraColumns: readonly string[];
-  /** Table id to its module and logical table, the names an app table's reference uses. */
+  /**
+   * Table id to its module and logical table, the names an app table's
+   * reference uses.
+   */
   readonly blockTables: Readonly<Record<string, {
     readonly block: string;
     readonly table: string;
@@ -81,110 +179,49 @@ export interface SchemaData {
   /** The table tenant columns point at, or `null` without tenant foreign keys. */
   readonly tenantTable: string | null;
 }
-/** The columns a diagram shows before a table is expanded: keys, tenant and soft references. */
+/**
+ * The columns a diagram shows before a table is expanded: keys, tenant and soft
+ * references.
+ */
 export declare function keyColumnsOf(table: SchemaTable, softColumns?: ReadonlySet<string>): readonly SchemaColumn[];
 export interface SchemaOptions {
-  /** The tenant column the config names (`organization_id` by default); `null` without tenants. */
+  /**
+   * The tenant column the config names (`organization_id` by default); `null`
+   * without tenants.
+   */
   readonly tenantColumn?: string | null;
 }
-/** The column the tenant blocks key rows by, from the preset's tenant name; `null` without tenants. */
+/**
+ * The column the tenant blocks key rows by, from the preset's tenant name;
+ * `null` without tenants.
+ */
 export declare function tenantColumnOf(preset: Preset): string | null;
 /**
- * The tables in rendered module SQL: every `create table`, plus the columns
- * and foreign keys later `alter table ... add` statements give them. A
- * `create table` it can't read throws with the file and line, so a new SQL
- * shape fails the tests instead of dropping a table from the diagram.
+ * The tables in rendered module SQL: every `create table`, plus the columns and
+ * foreign keys later `alter table ... add` statements give them. A `create
+ * table` it can't read throws with the file and line, so a new SQL shape fails
+ * the tests instead of dropping a table from the diagram.
  */
 export declare function parseSchema(files: readonly SchemaSource[], options?: SchemaOptions): readonly SchemaTable[];
 /**
- * The statements that shape one table, as written: its `create table` and
- * the `alter table` statements after it. Empty when no file creates it.
+ * The statements that shape one table, as written: its `create table` and the
+ * `alter table` statements after it. Empty when no file creates it.
  */
 export declare function tableStatements(files: readonly SchemaSource[], id: string): readonly string[];
-/** The foreign keys between tables, one per pair, with the targets outside the schema named by id. */
+/**
+ * The foreign keys between tables, one per pair, with the targets outside the
+ * schema named by id.
+ */
 export declare function schemaRelations(tables: readonly SchemaTable[]): readonly {
   readonly from: string;
   readonly to: string;
 }[];
 //#endregion
-//#region src/create/design-computed.d.ts
-/** The aggregates a rollup takes (`APP_ROLLUP_AGGREGATES`). */
-export declare const ROLLUP_AGGREGATES: readonly ["count", "sum", "min", "max", "avg"];
-export type RollupAggregate = (typeof ROLLUP_AGGREGATES)[number];
-/** `appTables.<table>.rollups.<name>`; the shape of `AppRollupConfig`. */
-export interface AppRollup {
-  readonly table: string;
-  readonly via: string;
-  readonly aggregate: RollupAggregate;
-  readonly column?: string;
-  readonly where?: {
-    readonly column: string;
-    readonly equals: string;
-  };
-}
-/** `appTables.<table>.lookups.<name>`; the shape of `AppLookupConfig`. */
-export interface AppLookup {
-  readonly via: string;
-  readonly column: string;
-}
-/** A rollup or lookup as a table node and the inspector list it. */
-export interface ComputedRow {
-  readonly name: string;
-  readonly kind: "rollup" | "lookup";
-  /** What it computes, such as `count of tasks where status = todo`. */
-  readonly summary: string;
-  /** The short form the node shows next to the name, such as `count`. */
-  readonly label: string;
-}
-type Tables = Readonly<Record<string, AppTable>>;
-export declare function isRollupAggregate(value: unknown): value is RollupAggregate;
-/** The columns of `table` a rollup or lookup can read, with their types. */
-export declare function readableColumns(table: AppTable): readonly (readonly [string, AppColumnType])[];
-/** The columns `aggregate` can read: numbers for sum and avg, ordered types for min and max, none for count. */
-export declare function rollupColumns(child: AppTable, aggregate: RollupAggregate): readonly string[];
-/** The select columns of `child` (text with options) a rollup can filter on. */
-export declare function filterColumns(child: AppTable): readonly (readonly [string, readonly string[]])[];
-/** Each app table column that references `parent`, as `{ table, via }`: what a rollup on `parent` can aggregate. */
-export declare function rollupSources(tables: Tables, parent: string): readonly {
-  readonly table: string;
-  readonly via: string;
-}[];
-/** Each column of `name` that references another app table, with that table: what a lookup can follow. */
-export declare function lookupSources(tables: Tables, name: string): readonly {
-  readonly via: string;
-  readonly target: string;
-}[];
-export type DraftRollup = { -readonly [K in keyof AppRollup]: AppRollup[K]; };
-/** `table` with a rollup or lookup set under `name`, replacing `previous` in its place. */
-export declare function tableWithComputed(table: AppTable, name: string, computed: {
-  readonly rollup: AppRollup;
-} | {
-  readonly lookup: AppLookup;
-}, previous: string): AppTable;
-/** `table` without the rollup or lookup `name`. */
-export declare function tableWithoutComputed(table: AppTable, name: string): AppTable;
-/**
- * The tables with every rollup and lookup that no longer fits dropped: one
- * whose table, link or column was deleted or retyped, or whose name a
- * column now uses. `sql sync` would refuse them, and the design code would
- * not encode.
- */
-export declare function prunedComputed(tables: Tables): Tables;
-/** The rollups that aggregate `from`, pointed at `to`. */
-export declare function computedTableRenamed(tables: Tables, from: string, to: string): Tables;
-/** The rollup fitted to a new source or aggregate: a column the aggregate can read, and a filter the child still has. */
-export declare function fittedRollup(tables: Tables, rollup: AppRollup): AppRollup;
+//#region src/create/design-subject.d.ts
 /**
- * Every rollup and lookup that reads `table.from`, reading `table.to`. The
- * tables already have the column renamed, so a lookup finds its target
- * through the renamed link.
+ * Makes the rows a subject (`appTables.<table>.subject`); the shape of
+ * `AppTableSubject`.
  */
-export declare function computedColumnRenamed(tables: Tables, table: string, from: string, to: string): Tables;
-/** The rollups and lookups of an app table, in the view's column order. */
-export declare function computedRows(table: AppTable): readonly ComputedRow[];
-//#endregion
-//#region src/create/design-subject.d.ts
-/** Makes the rows a subject (`appTables.<table>.subject`); the shape of `AppTableSubject`. */
 export interface AppSubject {
   readonly type: string;
   readonly title?: string;
@@ -205,17 +242,29 @@ export interface AppEvents {
   readonly on?: readonly ("created" | "updated" | "deleted")[];
   readonly include?: readonly string[];
 }
-/** The columns `subject` adds: `rank` for manual order and `deleted_at` for trash. */
+/**
+ * The columns `subject` adds: `rank` for manual order and `deleted_at` for
+ * trash.
+ */
 export declare function subjectColumns(subject: AppSubject | undefined): SchemaColumn[];
 /** The subject with the columns it names renamed or dropped by `edit`. */
 export declare function subjectColumnsEdited(subject: AppSubject, edit: (columns: readonly string[]) => readonly string[]): AppSubject;
-/** Why `type` can't be the subject type of the app table `table`, or `undefined` when it can. */
+/**
+ * Why `type` can't be the subject type of the app table `table`, or `undefined`
+ * when it can.
+ */
 export declare function subjectTypeError(design: Design, table: string, type: string): string | undefined;
-/** App table events with `edit` applied to the payload columns, dropping an empty list. */
+/**
+ * App table events with `edit` applied to the payload columns, dropping an
+ * empty list.
+ */
 export declare function eventsColumnsEdited(events: true | AppEvents, edit: (columns: readonly string[]) => readonly string[]): true | AppEvents;
 //#endregion
 //#region src/create/design.d.ts
-/** Another app table or `auth.users` (`{ table }`), or a block module's logical table (`{ block, table }`). */
+/**
+ * Another app table or `auth.users` (`{ table }`), or a block module's logical
+ * table (`{ block, table }`).
+ */
 export interface AppReference {
   readonly table: string;
   readonly block?: string;
@@ -233,7 +282,10 @@ export interface AppColumn {
   readonly max?: number;
   readonly comment?: string;
   readonly identity?: boolean;
-  /** Who reads and writes the column: everyone by default, `read`, or `server` (ADR 0051). */
+  /**
+   * Who reads and writes the column: everyone by default, `read`, or `server`
+   * (ADR 0051).
+   */
   readonly access?: AppColumnAccess;
 }
 export type AppScope = "inherit" | "user" | "none";
@@ -253,9 +305,9 @@ export interface AppTable {
   readonly events?: true | AppEvents;
 }
 /**
- * What the canvas adds to a preset: app tables, extra columns on block
- * tables (by module) and the positions of moved tables (by table id). It has
- * the shape of `CreateDesign` from `better-supabase/preset`.
+ * What the canvas adds to a preset: app tables, extra columns on block tables
+ * (by module) and the positions of moved tables (by table id). It has the shape
+ * of `CreateDesign` from `better-supabase/preset`.
  */
 export interface Design {
   readonly appTables?: Readonly<Record<string, AppTable>>;
@@ -273,8 +325,8 @@ export declare function identifierError(name: string): string | undefined;
 /** Why a column can't be added to an app table, or `undefined` when it can. */
 export declare function columnError(table: AppTable, name: string, preset: Pick<Preset, "scope" | "tenantName" | "idType">): string | undefined;
 /**
- * Why `value` can't be the default of `column` (its type, options and
- * bounds), or `undefined` when it can or is empty.
+ * Why `value` can't be the default of `column` (its type, options and bounds),
+ * or `undefined` when it can or is empty.
  */
 export declare function defaultError(column: Pick<AppColumn, "type" | "options" | "min" | "max" | "format">, value: string): string | undefined;
 /** A free app table name: `base`, then `base_2`, `base_3` and so on. */
@@ -282,8 +334,8 @@ export declare function freeTableName(design: Design, taken: ReadonlySet<string>
 /** Adds an app table, placed at `position` when given. */
 export declare function addTable(design: Design, name: string, table?: AppTable, position?: readonly [number, number]): Design;
 /**
- * Removes an app table, every app table column that references it (and
- * those columns from key sets), and the rollups and lookups that read it.
+ * Removes an app table, every app table column that references it (and those
+ * columns from key sets), and the rollups and lookups that read it.
  */
 export declare function deleteTable(design: Design, name: string): Design;
 /** Renames an app table and the references to it. */
@@ -292,8 +344,8 @@ export type TablePatch = { readonly [K in "scope" | "timestamps" | "id" | "uniqu
 /** Updates an app table's options; a key set to `undefined` is removed. */
 export declare function updateTable(design: Design, name: string, patch: TablePatch): Design;
 /**
- * Sets an app table's id type and retypes the app table columns that
- * reference it, since a key has the type of the id it points at.
+ * Sets an app table's id type and retypes the app table columns that reference
+ * it, since a key has the type of the id it points at.
  */
 export declare function setTableId(design: Design, name: string, id: AppTableId): Design;
 /** Sets (adds or replaces) an app table column. */
@@ -303,7 +355,10 @@ export declare function renameColumn(design: Design, table: string, from: string
 /** Replaces an app table with `edit` applied to it, such as `tableWithComputed`. */
 export declare function editTable(design: Design, table: string, edit: (current: AppTable) => AppTable): Design;
 export declare function deleteColumn(design: Design, table: string, name: string): Design;
-/** Sets an extra column on a block table (`blocks.<module>.options.extraColumns`). */
+/**
+ * Sets an extra column on a block table
+ * (`blocks.<module>.options.extraColumns`).
+ */
 export declare function setExtraColumn(design: Design, module: string, name: string, type: string): Design;
 export declare function deleteExtraColumn(design: Design, module: string, name: string): Design;
 /** A design with the name of the table an edit created. */
@@ -342,38 +397,51 @@ export type ConnectResult = {
   readonly error: string;
 };
 /**
- * Adds a foreign key column from an app table to `target`. Only app tables
- * get new columns. A self reference gets `parent_id`, and a second
- * reference to the same table gets a role name (`owner_id`, `<target>_2_id`)
- * the user can rename. A target without a single-column primary key, and
- * the tenant table the scope column already references, are refused with a
- * message.
+ * Adds a foreign key column from an app table to `target`. Only app tables get
+ * new columns. A self reference gets `parent_id`, and a second reference to the
+ * same table gets a role name (`owner_id`, `<target>_2_id`) the user can
+ * rename. A target without a single-column primary key, and the tenant table
+ * the scope column already references, are refused with a message.
  */
 export declare function connect(design: Design, data: SchemaData, preset: Pick<Preset, "scope" | "tenantName" | "idType">, connection: Connection): ConnectResult;
 /**
- * Adds a key to `targetId` on the app table `name` in the design, which can
- * be a table the schema doesn't have yet: `<target>_id`, `parent_id` for a
- * self reference, or a free role name when that column is taken.
+ * Adds a key to `targetId` on the app table `name` in the design, which can be
+ * a table the schema doesn't have yet: `<target>_id`, `parent_id` for a self
+ * reference, or a free role name when that column is taken.
  */
 export declare function referenceFrom(design: Design, data: SchemaData, preset: Pick<Preset, "scope" | "tenantName" | "idType">, name: string, targetId: string): ConnectResult;
+/**
+ * The schema with the design applied: app tables added, extra columns appended
+ * to the block tables that accept them.
+ */
+export declare function withDesign(data: SchemaData, design: Design, preset: Pick<Preset, "scope" | "tenantName" | "idType">): SchemaData;
+//#endregion
+//#region src/create/design-issues.d.ts
+/**
+ * Why `checkDesign` rejects a design: a `DesignErrorCode` from parsing, or a
+ * rule that needs the preset. The codes are stable; the messages may change.
+ */
+export type DesignIssueCode = DesignErrorCode | "table_name_taken" | "name_too_long" | "subject_type_taken" | "invalid_default" | "default_required" | "column_clash" | "unknown_column" | "missing_reference" | "set_null_required" | "preset_conflict";
 export interface DesignIssue {
-  /** The app table or block module the issue is on. */
+  readonly code: DesignIssueCode;
+  /**
+   * A JSON Pointer (RFC 6901) into the design, such as
+   * `/appTables/tasks/columns/title`. `""` is the design itself, and the path
+   * of an issue with the preset.
+   */
+  readonly path: string;
+  /** The app table or block module the issue is on, or `design` or `preset`. */
   readonly table: string;
   readonly message: string;
 }
 /**
  * What would stop `sql sync` from writing the design: a table name a block
  * already uses, a reference to a table the preset no longer installs, a
- * set-null delete on a required column, a composite key on a column the
- * table doesn't have, and extra columns for a block that is gone or no
- * longer takes them.
+ * set-null delete on a required column, a composite key on a column the table
+ * doesn't have, and extra columns for a block that is gone or no longer takes
+ * them.
  */
 export declare function designIssues(design: Design, data: SchemaData, preset: Pick<Preset, "scope" | "tenantName" | "idType">): readonly DesignIssue[];
-/**
- * The schema with the design applied: app tables added, extra columns
- * appended to the block tables that accept them.
- */
-export declare function withDesign(data: SchemaData, design: Design, preset: Pick<Preset, "scope" | "tenantName" | "idType">): SchemaData;
 //#endregion
 //#region src/create/check.d.ts
 /** What `checkDesign` returns. */
@@ -381,19 +449,26 @@ export type DesignCheck = {
   readonly ok: true;
   /** The design, with its empty parts dropped. */
   readonly design: CreateDesign;
-  /** Its `encodeDesign` code, or `null` when it is too long for a URL. */
+  /** Whether its code fits in a `/create` URL (`MAX_DESIGN_CODE_LENGTH`). */
+  readonly fitsUrl: boolean;
+  /**
+   * Its `encodeDesign` code. `null` only when `fitsUrl` is false; send a
+   * design file then.
+   */
   readonly code: string | null;
 } | {
   readonly ok: false;
-  /** Each problem; `table` is `design` or `preset` for one outside a table. */
+  /**
+   * Each problem, with a stable `code` and a JSON Pointer `path` into the
+   * design; `table` is `design` or `preset` for one outside a table.
+   */
   readonly issues: readonly DesignIssue[];
 };
 /**
- * Checks a design against a preset with every rule the canvas and
- * `sql sync` apply, so a server, an MCP tool and the canvas share one
- * answer. `input` is a design object, a design code or a `/create` URL with
- * `&design=`. It never throws for a bad design or preset: each problem is
- * an issue.
+ * Checks a design against a preset with every rule the canvas and `sql sync`
+ * apply, so a server, an MCP tool and the canvas share one answer. `input` is a
+ * design object, a design code or a `/create` URL with `&design=`. It never
+ * throws for a bad design or preset: each problem is an issue.
  */
 export declare function checkDesign(input: unknown, preset: PresetInput): Promise<DesignCheck>;
 //#endregion
@@ -407,20 +482,26 @@ export declare function lockedWithoutDefault(column: AppColumn): boolean;
 export declare function takesBounds(type: AppColumnType): boolean;
 /**
  * A column without the keys its type can't take: a format of another type,
- * options outside text and text[], bounds that don't apply, an identity
- * outside integer and bigint, and a default an identity or the type refuses.
+ * options outside text and text[], bounds that don't apply, an identity outside
+ * integer and bigint, and a default an identity or the type refuses.
  */
 export declare function fitted(column: AppColumn): AppColumn;
 /** Why `option` can't join a select's `options`, or `undefined` when it can. */
 export declare function optionError(options: readonly string[], option: string): string | undefined;
-/** Why `value` can't be a bound of `column`, or `undefined` when it can (an empty value clears it). */
+/**
+ * Why `value` can't be a bound of `column`, or `undefined` when it can (an
+ * empty value clears it).
+ */
 export declare function boundError(column: AppColumn, side: "min" | "max", value: string): string | undefined;
 /** `column` with its bounds replaced; a bound left out is removed. */
 export declare function withBounds(column: AppColumn, bounds: {
   readonly min?: number | undefined;
   readonly max?: number | undefined;
 }): AppColumn;
-/** What the canvas shows for a column that is more than its type, such as an email or a select. */
+/**
+ * What the canvas shows for a column that is more than its type, such as an
+ * email or a select.
+ */
 export declare function columnLabel(column: AppColumn): string | undefined;
 //#endregion
 //#region src/create/column-kinds.d.ts
@@ -428,8 +509,8 @@ export declare function columnLabel(column: AppColumn): string | undefined;
 export declare const KIND_GROUPS: readonly ["Text", "Number", "Date and time", "Choice", "Relation", "Other"];
 export type KindGroup = (typeof KIND_GROUPS)[number];
 /**
- * A choice in the column type picker: a Postgres type with the format,
- * options, identity or reference that make it, say, an email or a rating.
+ * A choice in the column type picker: a Postgres type with the format, options,
+ * identity or reference that make it, say, an email or a rating.
  */
 export interface ColumnKind {
   readonly id: string;
@@ -453,10 +534,10 @@ export declare function kindOf(column: AppColumn): ColumnKind;
  */
 export declare function withKind(column: AppColumn, kind: ColumnKind): AppColumn;
 /**
- * Sets an app table column to `kind`. Currency keeps money as two columns:
- * the column becomes `<name>_minor` (unless the name is taken) and a
- * `<name>_currency` text column of 3 characters joins it. Returns the
- * column's name after the change.
+ * Sets an app table column to `kind`. Currency keeps money as two columns: the
+ * column becomes `<name>_minor` (unless the name is taken) and a
+ * `<name>_currency` text column of 3 characters joins it. Returns the column's
+ * name after the change.
  */
 export declare function setColumnKind(design: Design, table: string, name: string, kind: ColumnKind): NamedDesign;
 //#endregion
@@ -464,17 +545,40 @@ export declare function setColumnKind(design: Design, table: string, name: strin
 /** The name the deploy gives its migration in `supabase_migrations`. */
 export declare const MIGRATION_NAME = "better_supabase_blocks";
 /**
- * Why this preset can't be deployed, or `undefined` when it can. With
- * `access: "provider"` the preview renders a stand-in provider whose
- * functions no real project has.
+ * Why this preset can't be deployed, or `undefined` when it can. With `access:
+ * "provider"` the preview renders a stand-in provider whose functions no real
+ * project has.
  */
 export declare function deployBlocker(preset: Preset): string | undefined;
+/** A new deploy id: a random UUID. */
+export declare function newDeployId(): string;
+/**
+ * What a host app stores for one deploy, so it can show the project's preset
+ * later and match the project to the record by the `id` comment at the top of
+ * the migration.
+ */
+export interface DeployRecord {
+  readonly id: string;
+  readonly ref: string;
+  /** The preset code. */
+  readonly preset: string;
+  /** The design code, or `null` when the preset had no design. */
+  readonly design: string | null;
+  readonly migration: string;
+  /** An ISO 8601 instant, such as `Temporal.Now.instant().toString()`. */
+  readonly deployedAt: string;
+}
+export interface DeployQueryOptions {
+  /** Written as `-- better-supabase deploy <id>` on the first line. */
+  readonly id?: string | undefined;
+}
 /**
  * The SQL of one migration for the rendered files: every schema file, then
- * every data file, each in render order, which is the order `sql sync` and
- * `sql data` apply them. pgTAP tests stay out.
+ * every data file, each in render order, which is the order `sql sync` and `sql
+ * data` apply them. pgTAP tests stay out. Throws a `TypeError` when `id` holds
+ * anything but letters, digits, `_` and `-`.
  */
-export declare function deployQuery(files: readonly PresetMigrationFile[]): string;
+export declare function deployQuery(files: readonly PresetMigrationFile[], options?: DeployQueryOptions): string;
 /** A database password for a new project: 32 base64url characters. */
 export declare function generatePassword(): string;
 /** The project name the dialog suggests: the preset's name, or `my-app`. */
@@ -499,7 +603,13 @@ export interface ProjectStatusResponse {
 }
 /** `POST /create/supabase/deploy`. */
 export interface DeployResponse {
+  /** The id written at the top of the migration; store it in a `DeployRecord`. */
+  readonly id: string;
   readonly ref: string;
+  /** The preset code. */
+  readonly preset: string;
+  /** The design code, or `null` when the preset had no design. */
+  readonly design: string | null;
   readonly migration: string;
   readonly lints: readonly SupabaseLint[];
 }
@@ -516,7 +626,10 @@ export interface History<T> {
   readonly past: readonly T[];
   readonly present: T;
   readonly future: readonly T[];
-  /** The value before the drag in progress, which `commitDrag` records as one step. */
+  /**
+   * The value before the drag in progress, which `commitDrag` records as one
+   * step.
+   */
   readonly dragStart: T | null;
 }
 export type HistoryAction<T> = {
@@ -540,27 +653,26 @@ export type HistoryAction<T> = {
 };
 export declare function initialHistory<T>(value: T): History<T>;
 /**
- * An undo history. `drag` updates the value without a step while the
- * pointer moves; `commitDrag` records the whole drag as one step. `amend`
- * replaces the value in the current step, so a follow-up such as placing a
- * dropped block stays part of the step that added it. `reset` replaces the
- * value and clears the history, as loading a link does.
+ * An undo history. `drag` updates the value without a step while the pointer
+ * moves; `commitDrag` records the whole drag as one step. `amend` replaces the
+ * value in the current step, so a follow-up such as placing a dropped block
+ * stays part of the step that added it. `reset` replaces the value and clears
+ * the history, as loading a link does.
  */
 export declare function undoHistory<T>(current: History<T>, action: HistoryAction<T>): History<T>;
 //#endregion
 //#region src/create/preview-provider.d.ts
 /**
- * A stand-in for the app's authorization provider, so `/create` can render
- * the SQL and the diagram for `access: "provider"`. Its templates call
- * functions in a `provider` schema that no real project has: the preview
- * says so next to the output.
+ * A stand-in for the app's authorization provider, so `/create` can render the
+ * SQL and the diagram for `access: "provider"`. Its templates call functions in
+ * a `provider` schema that no real project has: the preview says so next to the
+ * output.
  */
 export declare function previewAccessProvider(preset: Preset): ModuleAccessProvider;
 /**
  * The files `sql sync` writes for a config with only this preset and its
- * `/create` design (app tables and extra columns). With
- * `access: "provider"` the access functions come from
- * `previewAccessProvider`.
+ * `/create` design (app tables and extra columns). With `access: "provider"`
+ * the access functions come from `previewAccessProvider`.
  */
 export declare function previewFiles(code: string, design?: CreateDesign): readonly PresetMigrationFile[];
 //#endregion
@@ -574,7 +686,10 @@ export interface SampleTable {
 export declare const SAMPLE_ROW_COUNT = 8;
 /** Who reads the rows: a signed-in member, or server code with the service role. */
 export type SampleViewer = "member" | "server";
-/** The columns of `table` a `viewer` can't select: `access: "server"` ones for a member. */
+/**
+ * The columns of `table` a `viewer` can't select: `access: "server"` ones for a
+ * member.
+ */
 export declare function hiddenColumns(table: AppTable | undefined, viewer: SampleViewer): readonly string[];
 /**
  * Deterministic sample rows for app table `name`, from its columns' types,
@@ -585,14 +700,17 @@ export declare function hiddenColumns(table: AppTable | undefined, viewer: Sampl
 export declare function sampleRows(design: Design, name: string, count?: number, viewer?: SampleViewer): SampleTable;
 //#endregion
 //#region src/create/schema-meta.d.ts
-/** The tables plus the soft references, manifests and extra-column tables the canvas draws. */
+/**
+ * The tables plus the soft references, manifests and extra-column tables the
+ * canvas draws.
+ */
 export declare function schemaData(tables: readonly SchemaTable[], tenantName?: string): SchemaData;
 //#endregion
 //#region src/create/migration.d.ts
 /**
- * Why no migration was written: `breaking` changes need the expand and
- * contract steps in each change, and `unsupported` ones are outside what a
- * generated migration covers.
+ * Why no migration was written: `breaking` changes need the expand and contract
+ * steps in each change, and `unsupported` ones are outside what a generated
+ * migration covers.
  */
 export type MigrationRefusal = "breaking" | "unsupported";
 export type MigrationPlan = {
@@ -603,16 +721,19 @@ export type MigrationPlan = {
 } | {
   readonly ok: false;
   readonly reason: MigrationRefusal;
-  /** The changes that caused the refusal, or every change when a file outside the app tables differs. */
+  /**
+   * The changes that caused the refusal, or every change when a file
+   * outside the app tables differs.
+   */
   readonly changes: readonly DesignChange[];
 };
 /**
- * The migration that takes a project deployed from `base` to `next`, for
- * added tables and added columns only. The rendered app-table SQL is
- * idempotent (`create table if not exists`, `add column if not exists`,
- * `drop policy if exists`), so the migration is the re-rendered file.
- * Anything else, such as a rename, a retype, a changed default or a change
- * outside `appTables`, is refused so a deploy never guesses.
+ * The migration that takes a project deployed from `base` to `next`, for added
+ * tables and added columns only. The rendered app-table SQL is idempotent
+ * (`create table if not exists`, `add column if not exists`, `drop policy if
+ * exists`), so the migration is the re-rendered file. Anything else, such as a
+ * rename, a retype, a changed default or a change outside `appTables`, is
+ * refused so a deploy never guesses.
  */
 export declare function migrationBetween(code: string, base: CreateDesign, next: CreateDesign): MigrationPlan;
 //#endregion