better-supabase 0.8.0 → 0.9.0

package/dist/cli/index.d.ts

@@ -1,6 +1,133 @@
 import { styleText } from "node:util";
 import { Catalog, CatalogCheck, CatalogColumn, CatalogColumnGrant, CatalogEnum, CatalogForeignKey, CatalogFunction, CatalogFunctionArg, CatalogGrant, CatalogIndex, CatalogPolicy, CatalogTable, CatalogTrigger, CatalogUnique, ExtrasFunction, ExtrasHook, ExtrasHookFunction, ExtrasTable, ForeignKeyAction, GeneratedFile, GeneratorMetadata, GeneratorMetadata as GeneratorMetadata$1, ResolvedConfig, Snapshot, SnapshotBucket, SnapshotExtras } from "better-supabase/config";
 import { Casing, Codec, FunctionMeta, RelationMeta, SchemaMeta, TableMeta } from "better-supabase";
+import "better-supabase/blocks";
+//#region src/cli/prompts.d.ts
+interface Choice<T extends string> {
+  readonly value: T;
+  readonly label: string;
+  readonly hint?: string;
+}
+/**
+ * Questions for a person at a terminal. `run()` only gets one
+ * from the bin on a TTY outside CI. A method that resolves `undefined` gave
+ * no answer, and the command takes its default.
+ */
+interface Prompter {
+  readonly select: <T extends string>(message: string, choices: readonly Choice<T>[], initial: T) => Promise<T | undefined>;
+  readonly multiselect: <T extends string>(message: string, choices: readonly Choice<T>[], initial: readonly T[]) => Promise<T[] | undefined>;
+  readonly confirm: (message: string) => Promise<boolean | undefined>;
+}
+//#endregion
+//#region src/cli/core/errors.d.ts
+/**
+ * `1` for a failure or a failed check, `2` for a usage error the caller can
+ * fix by changing the command, `3` when the user has to act (give an input,
+ * consent, log in), `130` when the run was interrupted or a prompt cancelled,
+ * `143` when it was terminated (SIGTERM), and `65` when `gen --metadata`
+ * rejects its input.
+ */
+type ExitCode = 1 | 2 | 3 | 65 | 130 | 143;
+type CliErrorCode = "usage" | "unknown_command" | "unknown_flag" | "invalid_value" | "command_moved" | "flag_renamed" | "missing_value" | "outside_root" | "config_not_found" | "config_invalid" | "env_invalid" | "not_found" | "invalid_input" | "dependency_missing" | "database_unreachable" | "supabase_cli_missing" | "supabase_cli_failed" | "network_error" | "request_failed" | "auth_required" | "integrity_failed" | "generator_failed" | "check_failed" | "file_conflict" | "findings" | "input_required" | "consent_required" | "cancelled" | "failed" | "internal";
+/** Each code has a heading on this page, so `type` links to its explanation. */
+export declare const CLI_ERRORS_URL = "https://bettersupabase.com/docs/cli/errors";
+/** RFC 9457 Problem Details for a CLI error. `--json` prints it on stdout. */
+interface CliProblem {
+  readonly type: string;
+  readonly title: string;
+  readonly detail: string;
+  readonly code: CliErrorCode;
+  readonly exitCode: number;
+  /** The closest command, for `unknown_command`. */
+  readonly suggestion?: string;
+  /** The flag that supplies the value, for `missing_value`. */
+  readonly flag?: string;
+  /** One line per problem, for `config_invalid` and `env_invalid`. */
+  readonly issues?: readonly string[];
+  /** The flags the run needs, for `input_required`. */
+  readonly missing?: readonly string[];
+  /** The values each missing flag takes, the suggested one first. */
+  readonly choices?: Readonly<Record<string, readonly string[]>>;
+  /** The value for `--confirm` once the user agrees, for `consent_required`. */
+  readonly token?: string;
+}
+type CliProblemExtensions = Pick<CliProblem, "suggestion" | "flag" | "issues" | "missing" | "choices" | "token">;
+interface CliErrorOptions extends CliProblemExtensions {
+  readonly exitCode?: number;
+  readonly cause?: unknown;
+  /** Commands that resolve the error, printed as the envelope's `next`. */
+  readonly next?: readonly NextStep[];
+}
+/** An error the CLI reports as text, or as Problem Details under `--json`. */
+export declare class CliError extends Error {
+  override readonly name = "CliError";
+  readonly code: CliErrorCode;
+  readonly exitCode: number;
+  readonly problem: CliProblem;
+  readonly next: readonly NextStep[];
+  constructor(code: CliErrorCode, message: string, options?: CliErrorOptions);
+}
+//#endregion
+//#region src/cli/core/io.d.ts
+interface CliIo {
+  readonly stdout: (text: string) => void;
+  readonly stderr: (text: string) => void;
+  /** All of stdin, for the `--*-stdin` flags that keep secrets out of arguments. */
+  readonly stdin?: () => Promise<string>;
+  /** Stdin is a terminal, so reading it would wait for typing instead of a pipe. */
+  readonly stdinIsTty?: boolean;
+  /** Stdout is a terminal. Agent detection counts `CURSOR_TRACE_ID` only when it is not. */
+  readonly stdoutIsTty?: boolean;
+  /** Whether a path exists on the host, for agent detection. Without it, no file counts. */
+  readonly exists?: (path: string) => boolean;
+  /** Color stdout with ANSI escapes. Off unless set; `--no-color` turns it off. */
+  readonly color?: boolean;
+  /** Color stderr with ANSI escapes. Defaults to `color`. */
+  readonly stderrColor?: boolean;
+  /**
+   * Shows `message` on stderr until the returned function is called: a
+   * spinner on a terminal, a plain line elsewhere. Without it, progress
+   * shows nothing.
+   */
+  readonly spinner?: (message: string) => () => void;
+  /**
+   * Prompts for a person at a terminal. `run()` drops them in CI, in agent
+   * mode and under `--json` or `--yes`, and without them commands never ask.
+   */
+  readonly prompts?: Prompter;
+}
+interface RunResult {
+  readonly code: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+/** A command to run next, and when it applies. */
+interface NextStep {
+  readonly command: string;
+  readonly when: string;
+}
+interface CommandResult {
+  readonly code: number;
+  readonly output?: string;
+  readonly error?: string;
+  /**
+   * The error code `--json` reports when `code` is not 0. Without it, exit
+   * code 2 reports `usage`, 3 `input_required`, 130 `cancelled`, and any
+   * other `failed`.
+   */
+  readonly errorCode?: CliErrorCode;
+  /** The `data` of the `--json` envelope. */
+  readonly data?: unknown;
+  readonly next?: readonly NextStep[];
+  /**
+   * Printed on stdout exactly as is, in place of `output` and the envelope:
+   * a document another tool reads, like `gen --metadata` without `--out`.
+   */
+  readonly raw?: string;
+  /** The command already printed its results through `emit`, so `run()` prints nothing more. */
+  readonly streamed?: boolean;
+}
+//#endregion
 //#region ../../node_modules/.pnpm/citty@0.2.2/node_modules/citty/dist/index.d.mts
 //#region src/types.d.ts
 type ArgType = "boolean" | "string" | "enum" | "positional" | undefined;
@@ -42,7 +169,7 @@ type RawArgs = {
   _: string[];
 };
 type ParsedArg<T extends ArgDef> = T["type"] extends "positional" ? ParsedPositionalArg<T> : T["type"] extends "boolean" ? ParsedBooleanArg<T> : T["type"] extends "string" ? ParsedStringArg<T> : T["type"] extends "enum" ? ParsedEnumArg<T> : never;
-type ParsedArgs$1<T extends ArgsDef = ArgsDef> = RawArgs & { [K in keyof T]: ParsedArg<T[K]>; } & { [K in keyof T as T[K] extends {
+type ParsedArgs<T extends ArgsDef = ArgsDef> = RawArgs & { [K in keyof T]: ParsedArg<T[K]>; } & { [K in keyof T as T[K] extends {
   alias: string;
 } ? T[K]["alias"] : never]: ParsedArg<T[K]>; } & { [K in keyof T as T[K] extends {
   alias: string[];
@@ -61,21 +188,21 @@ type CommandDef<T extends ArgsDef = ArgsDef> = {
   default?: Resolvable<string>;
   subCommands?: Resolvable<SubCommandsDef>;
   plugins?: Resolvable<CittyPlugin>[];
-  setup?: (context: CommandContext$1<T>) => any | Promise<any>;
-  cleanup?: (context: CommandContext$1<T>) => any | Promise<any>;
-  run?: (context: CommandContext$1<T>) => any | Promise<any>;
+  setup?: (context: CommandContext<T>) => any | Promise<any>;
+  cleanup?: (context: CommandContext<T>) => any | Promise<any>;
+  run?: (context: CommandContext<T>) => any | Promise<any>;
 };
-type CommandContext$1<T extends ArgsDef = ArgsDef> = {
+type CommandContext<T extends ArgsDef = ArgsDef> = {
   rawArgs: string[];
-  args: ParsedArgs$1<T>;
+  args: ParsedArgs<T>;
   cmd: CommandDef<T>;
   subCommand?: CommandDef<T>;
   data?: any;
 };
 type CittyPlugin = {
   name: string;
-  setup?(context: CommandContext$1<any>): void | Promise<void>;
-  cleanup?(context: CommandContext$1<any>): void | Promise<void>;
+  setup?(context: CommandContext<any>): void | Promise<void>;
+  cleanup?(context: CommandContext<any>): void | Promise<void>;
 };
 type Resolvable<T> = T | Promise<T> | (() => T) | (() => Promise<T>);
 //#endregion
@@ -98,55 +225,47 @@ interface CliEnv {
   readonly CI?: string | undefined;
   /** The config environment to apply when `--env` is not passed. */
   readonly BETTER_SUPABASE_ENV?: string | undefined;
+  /** Agent mode when `--agent` is not passed: auto, yes or no. `run()` reads it before parsing. */
+  readonly BETTER_SUPABASE_AGENT?: string | undefined;
+  /** Every variable of the run, for the processes the CLI starts. */
+  readonly [PROCESS_ENV]?: Readonly<Record<string, string | undefined>>;
 }
+/** The key of the full environment on a `CliEnv`; a symbol, so JSON output never shows it. */
+declare const PROCESS_ENV: unique symbol;
 //#endregion
-//#region src/cli/prompts.d.ts
-interface Choice<T extends string> {
-  readonly value: T;
-  readonly label: string;
-  readonly hint?: string;
+//#region src/cli/style.d.ts
+type Format = Parameters<typeof styleText>[0];
+/** Styles text, or returns it unchanged when colors are off. */
+type Paint = (format: Format, text: string) => string;
+//#endregion
+//#region src/cli/core/agent.d.ts
+/** Destructive work that waits for a person's consent in agent mode. */
+interface ConsentRequest {
+  /** A stable id for the kind of work: `overwrite`, `database-write`. */
+  readonly effect: string;
+  /** What happens, as a sentence the agent can show the user. */
+  readonly detail: string;
 }
+//#endregion
+//#region src/cli/core/log.d.ts
 /**
- * Questions and progress for a person at a terminal. `run()` only gets one
- * from the bin on a TTY outside CI; every method resolves `undefined` when the
- * person cancels.
+ * Messages for the person running the command. Every method writes to
+ * stderr, so stdout carries only the command's output or its JSON document.
  */
-interface Prompter {
-  readonly select: <T extends string>(message: string, choices: readonly Choice<T>[], initial: T) => Promise<T | undefined>;
-  readonly multiselect: <T extends string>(message: string, choices: readonly Choice<T>[], initial: readonly T[]) => Promise<T[] | undefined>;
-  readonly confirm: (message: string) => Promise<boolean | undefined>;
-  /** Shows `message` with a spinner until the returned function is called. */
-  readonly spinner: (message: string) => () => void;
-}
-//#endregion
-//#region src/cli/io.d.ts
-interface CliIo {
-  readonly stdout: (text: string) => void;
-  readonly stderr: (text: string) => void;
-  /** All of stdin, for the `--*-stdin` flags that keep secrets out of arguments. */
-  readonly stdin?: () => Promise<string>;
-  /** Color the output with ANSI escapes. Off unless set. */
-  readonly color?: boolean;
+interface CliLog {
+  readonly info: (text: string) => void;
+  readonly warn: (text: string) => void;
+  readonly error: (text: string) => void;
+  /** Written only under `--debug`. */
+  readonly debug: (text: string) => void;
   /**
-   * Prompts and spinners for a person at a terminal. `run()` drops them in
-   * CI and under `--json` or `--yes`, and without them commands never ask.
+   * Runs `task` while `message` shows: a spinner on a terminal, one plain
+   * line elsewhere. Under `--debug` it also logs how long the task took.
    */
-  readonly prompts?: Prompter;
-}
-interface RunResult {
-  readonly code: number;
-  readonly stdout: string;
-  readonly stderr: string;
-}
-interface CommandResult {
-  readonly code: number;
-  readonly output?: string;
-  readonly error?: string;
-  /** The JSON document `--json` prints instead of `output`. */
-  readonly data?: unknown;
+  readonly progress: <T>(message: string, task: () => Promise<T>) => Promise<T>;
 }
 //#endregion
-//#region src/cli/command.d.ts
+//#region src/cli/core/command.d.ts
 /** What `run()` hands every command next to its parsed arguments. */
 interface CliContext {
   readonly cwd: string;
@@ -155,12 +274,28 @@ interface CliContext {
   readonly configFile?: string;
   /** Loads the config file again, for commands that run until stopped. */
   readonly reloadConfig?: () => Promise<ResolvedConfig>;
-  /** `prompts` is unset in CI and under `--json` or `--yes`. */
+  /** `prompts` is unset in CI, in agent mode and under `--json` or `--yes`. */
   readonly io: CliIo;
   readonly env: CliEnv;
   /** `--json`: return `data`, which `run()` prints as the one JSON document. */
   readonly json: boolean;
   readonly signal: AbortSignal | undefined;
+  /** Messages and progress on stderr. */
+  readonly log: CliLog;
+  /** Colors text for stdout, or leaves it plain under `--no-color` and in a pipe. */
+  readonly paint: Paint;
+  /**
+   * Prints one result now, for a command that runs until stopped: the text
+   * output, or under `--json` one envelope on its own line (NDJSON).
+   */
+  readonly emit: (result: CommandResult) => void;
+  /** The coding agent running the CLI, in agent mode; `undefined` for a person. */
+  readonly agent: string | undefined;
+  /**
+   * In agent mode, throws `consent_required` until the run passes
+   * `--confirm` with this request's token; does nothing for a person.
+   */
+  readonly requireConsent: (request: ConsentRequest) => void;
 }
 /** Options every command accepts; `run()` reads them before the command starts. */
 declare const GLOBAL_ARGS: {
@@ -181,52 +316,64 @@ declare const GLOBAL_ARGS: {
   };
   readonly json: {
     readonly type: "boolean";
-    readonly description: "Print one JSON document on stdout; errors as Problem Details";
+    readonly description: "Print one JSON document on stdout; errors as Problem Details. On by default in agent mode";
+    readonly negativeDescription: "Print text, also in agent mode";
+  };
+  readonly agent: {
+    readonly type: "string";
+    readonly description: "Agent mode (JSON output, no prompts, consent for destructive work): auto detects a coding agent, yes or no decide. Defaults to $BETTER_SUPABASE_AGENT, then auto";
+    readonly valueHint: "auto|yes|no";
+  };
+  readonly confirm: {
+    readonly type: "string";
+    readonly description: "The token from a consent_required result, passed once the user agreed";
+    readonly valueHint: "token";
   };
   readonly yes: {
     readonly type: "boolean";
     readonly alias: "y";
     readonly description: "Ask nothing; use the flags and the defaults";
   };
+  readonly color: {
+    readonly type: "boolean";
+    readonly default: true;
+    readonly description: "Color the output on a terminal";
+    readonly negativeDescription: "Print no colors, like $NO_COLOR";
+  };
+  readonly debug: {
+    readonly type: "boolean";
+    readonly description: "Print stack traces, the commands the CLI runs, and timings on stderr";
+  };
 };
-type CliArgs<T extends ArgsDef> = ParsedArgs$1<T & typeof GLOBAL_ARGS>;
+type CliArgs<T extends ArgsDef> = ParsedArgs<T & typeof GLOBAL_ARGS>;
+/** The values a shell offers for one argument, for names it can't know from the arg definition. */
+type CompletionValues = () => readonly string[];
 interface CliCommandDef<T extends ArgsDef> {
+  /** The command contract; a breaking change to `CliContext` or `CommandResult` ships a new one. */
+  readonly apiVersion?: 1;
   readonly meta: CommandMeta & {
     readonly name: string;
   };
   readonly args: T;
   /** String options that take a list: comma-separated, repeated, or both. */
   readonly lists?: readonly (keyof T & string)[];
+  /** Values `completion` offers per argument: block, preset or task names. */
+  readonly completions?: { readonly [K in keyof T & string]?: CompletionValues; };
+  readonly runsWithInvalidConfig?: boolean;
   readonly run: (args: CliArgs<T>, context: CliContext) => Promise<CommandResult>;
 }
 /** Any citty command, whatever its arguments. */
 type AnyCommand = Exclude<SubCommandsDef[string], Promise<unknown> | (() => unknown)>;
+/** A command from `defineCliCommand`, which `createCli` accepts. */
+type CliCommand = AnyCommand & {
+  readonly apiVersion: 1;
+};
 /** A citty command that receives the `CliContext` and returns a `CommandResult`. */
-export declare function defineCliCommand<const T extends ArgsDef>(def: CliCommandDef<T>): AnyCommand;
+export declare function defineCliCommand<const T extends ArgsDef>(def: CliCommandDef<T>): CliCommand;
 /** Splits a comma-separated option into its trimmed, non-empty parts. */
 export declare function list(value: string | undefined): string[];
 //#endregion
-//#region src/cli/legacy.d.ts
-type FlagValue = string | boolean | readonly string[];
-/** The arguments of a `(context) => CommandResult` command, parsed the 0.2 way. */
-interface ParsedArgs {
-  readonly command: string | undefined;
-  readonly rest: readonly string[];
-  readonly flags: Readonly<Record<string, FlagValue>>;
-}
-/** What a `(context) => CommandResult` command receives. */
-interface CommandContext {
-  readonly args: ParsedArgs;
-  readonly cwd: string;
-  readonly config: ResolvedConfig;
-  readonly io: CliIo;
-  readonly env: Readonly<Record<string, string | undefined>>;
-  readonly signal: AbortSignal | undefined;
-}
-/** The command shape before 0.3; `registerCommand` still accepts it, deprecated. */
-type Command = (context: CommandContext) => Promise<CommandResult>;
-//#endregion
-//#region src/cli/run.d.ts
+//#region src/cli/core/run.d.ts
 interface RunOptions {
   /** Directory `--cwd` is relative to. */
   readonly cwd?: string;
@@ -234,61 +381,30 @@ interface RunOptions {
   readonly env?: Readonly<Record<string, string | undefined>>;
   readonly io?: CliIo;
   readonly signal?: AbortSignal;
+  /** The name the CLI was called with, for help and hints. Defaults to `better-supabase`. */
+  readonly bin?: string;
 }
 interface Cli {
   /** Runs the CLI. Never exits the process; returns the exit code and output. */
   run(argv: readonly string[], options?: RunOptions): Promise<RunResult>;
-  /** The usage text for the CLI, or for one command; plain unless `color` is set. */
+  /** The usage text for the CLI, or for one command path (`"sql add"`); plain unless `color` is set. */
   help(command?: string, color?: boolean): Promise<string>;
-  /** The names `run()` dispatches, registered commands included. */
+  /** The top-level names `run()` dispatches, your own commands included. */
   commandNames(): string[];
-  /** The root usage's description of each lazily loaded command, for checking against the command. */
-  commandDescriptions(): ReadonlyMap<string, string>;
-  /** Adds a command that is already loaded. */
-  register(name: string, command: AnyCommand): void;
 }
+interface CreateCliOptions {
+  /** Commands from `defineCliCommand` to add next to the built-in ones, keyed by name. */
+  readonly commands?: Readonly<Record<string, CliCommand>>;
+}
+/**
+ * A CLI with every built-in command plus `options.commands`. Each one has to
+ * come from `defineCliCommand` (`apiVersion: 1`) and take a free name.
+ */
+export declare function createCli(options?: CreateCliOptions): Cli;
 export declare const run: Cli["run"];
 export declare const help: Cli["help"];
-/** The names `run()` dispatches, registered commands included. */
+/** The names `run()` dispatches. */
 export declare const commandNames: Cli["commandNames"];
-/** Registers a citty command; `defineCliCommand` gives it the `CliContext`. */
-export declare function registerCommand(name: string, command: AnyCommand): void;
-/** @deprecated Pass a citty `CommandDef` from `defineCliCommand` instead. */
-export declare function registerCommand(name: string, command: Command, help?: string): void;
-//#endregion
-//#region src/cli/errors.d.ts
-/** `1` for a failure, `2` for a usage error the caller can fix by changing the command. */
-type ExitCode = 1 | 2;
-type CliErrorCode = "usage" | "unknown_command" | "missing_value" | "config_not_found" | "config_invalid" | "env_invalid" | "failed" | "internal";
-/** Each code has a heading on this page, so `type` links to its explanation. */
-export declare const CLI_ERRORS_URL = "https://bettersupabase.com/docs/cli/errors";
-/** RFC 9457 Problem Details for a CLI error. `--json` prints it on stdout. */
-interface CliProblem {
-  readonly type: string;
-  readonly title: string;
-  readonly detail: string;
-  readonly code: CliErrorCode;
-  readonly exitCode: number;
-  /** The closest command, for `unknown_command`. */
-  readonly suggestion?: string;
-  /** The flag that supplies the value, for `missing_value`. */
-  readonly flag?: string;
-  /** One line per problem, for `config_invalid` and `env_invalid`. */
-  readonly issues?: readonly string[];
-}
-type CliProblemExtensions = Pick<CliProblem, "suggestion" | "flag" | "issues">;
-interface CliErrorOptions extends CliProblemExtensions {
-  readonly exitCode?: number;
-  readonly cause?: unknown;
-}
-/** An error the CLI reports as text, or as Problem Details under `--json`. */
-export declare class CliError extends Error {
-  override readonly name = "CliError";
-  readonly code: CliErrorCode;
-  readonly exitCode: number;
-  readonly problem: CliProblem;
-  constructor(code: CliErrorCode, message: string, options?: CliErrorOptions);
-}
 //#endregion
 //#region src/cli/gen/render.d.ts
 interface RenderOptions {
@@ -300,10 +416,21 @@ interface RenderOptions {
 /**
  * Renders every generated file for a snapshot, without touching disk:
  * `database.types.ts` (what `supabase gen types` prints), the main module,
+ * `blocks.generated.ts` when the config installs blocks,
  * then each configured generator's files.
  */
 export declare function renderFiles(config: ResolvedConfig, snapshot: Snapshot, options?: RenderOptions): Promise<GeneratedFile[]>;
 //#endregion
+//#region src/cli/gen/blocks.d.ts
+/**
+ * `blocks.generated.ts`: each installed block's schema, API schema and the
+ * options its TypeScript side reads, for `defineBlocks(blockConfig, ...)`.
+ * `undefined` when the config installs no blocks.
+ */
+export declare function emitBlockConfig(config: Pick<ResolvedConfig, "blocks" | "blockNames" | "output" | "sql">, options?: {
+  readonly runtimeImport?: string;
+}): GeneratedFile | undefined;
+//#endregion
 //#region src/cli/db.d.ts
 /** The subset of `pg.Client` the CLI uses. */
 interface PgQueryable {
@@ -393,22 +520,21 @@ export declare function loadSnapshot(config: ResolvedConfig, env: Env, source: S
 export declare function parseSnapshot(data: unknown, label?: string): Promise<Snapshot>;
 export declare function serializeSnapshot(snapshot: Snapshot): string;
 //#endregion
-//#region src/cli/style.d.ts
-type Format = Parameters<typeof styleText>[0];
-/** Styles text, or returns it unchanged when colors are off. */
-type Paint = (format: Format, text: string) => string;
-//#endregion
 //#region src/cli/gen/run.d.ts
 interface GenOptions extends SnapshotSource {
   readonly config: ResolvedConfig;
   readonly env: CliEnv;
   readonly check: boolean;
+  /** Prints what would change and writes nothing. */
+  readonly dryRun?: boolean;
+  /** Overwrites generated paths that hold a file the CLI did not write. */
+  readonly force?: boolean;
   /** Colors the `--check` diffs. */
   readonly paint?: Paint;
   /** Pre-loaded snapshot (tests, watch mode). */
   readonly snapshot?: Snapshot;
   /**
-   * Writes only the generated files (`gen --metadata --out`): no read-set SQL
+   * Writes only the generated files (`gen --metadata --out-dir`): no read-set SQL
    * module, and the manifest that removes files an earlier run wrote is
    * neither read nor written.
    */
@@ -444,7 +570,7 @@ export declare function introspect(db: Queryable, schemas: readonly string[], op
  */
 export declare function fromCatalog(catalog: Catalog): Snapshot;
 //#endregion
-//#region src/cli/gen/model.d.ts
+//#region src/cli/gen/model-types.d.ts
 interface ColumnModel {
   readonly app: string;
   readonly db: string;
@@ -509,6 +635,8 @@ interface JsonImport {
   /** Path relative to the project root, without the `#Name` part. */
   readonly from: string;
 }
+//#endregion
+//#region src/cli/gen/model.d.ts
 interface Model {
   readonly tables: readonly TableModel[];
   readonly enums: readonly EnumModel[];
@@ -550,11 +678,12 @@ export declare function emitModule(model: Model, options: EmitOptions): string;
  * are off so the one file is the whole config. `environment` merges its
  * blocks in (`applyEnvironment`); c12's own `envName` is off because it
  * concatenates arrays. A discovered file sets the project root to its own
- * directory; `--config` keeps `cwd` as the root.
+ * directory; `--config` keeps `cwd` as the root. `path` is the file
+ * `discoverConfig` found, for callers that already looked it up.
  */
-export declare function loadConfig(cwd: string, explicit?: string, environment?: string): Promise<ResolvedConfig>;
+export declare function loadConfig(cwd: string, explicit?: string, environment?: string, path?: string | undefined): Promise<ResolvedConfig>;
 //#endregion
 //#region src/cli/version.d.ts
-export declare const VERSION = "0.8.0";
+export declare const VERSION = "0.9.0";
 //#endregion
-export type { Catalog, CatalogCheck, CatalogColumn, CatalogColumnGrant, CatalogEnum, CatalogForeignKey, CatalogFunction, CatalogFunctionArg, CatalogGrant, CatalogIndex, CatalogPolicy, CatalogTable, CatalogTrigger, CatalogUnique, CliArgs, CliCommandDef, CliContext, CliEnv, CliErrorCode, CliErrorOptions, CliIo, CliProblem, CliProblemExtensions, Command, CommandContext, CommandResult, ExitCode, ExtrasFunction, ExtrasHook, ExtrasHookFunction, ExtrasTable, ForeignKeyAction, GeneratorMetadata, IntrospectionSource, ManagementSourceOptions, ParsedArgs, Queryable, RunOptions, RunResult, Snapshot, SnapshotBucket, SnapshotExtras };
+export type { Catalog, CatalogCheck, CatalogColumn, CatalogColumnGrant, CatalogEnum, CatalogForeignKey, CatalogFunction, CatalogFunctionArg, CatalogGrant, CatalogIndex, CatalogPolicy, CatalogTable, CatalogTrigger, CatalogUnique, Choice, Cli, CliArgs, CliCommand, CliCommandDef, CliContext, CliEnv, CliErrorCode, CliErrorOptions, CliIo, CliLog, CliProblem, CliProblemExtensions, CommandResult, CreateCliOptions, ExitCode, ExtrasFunction, ExtrasHook, ExtrasHookFunction, ExtrasTable, ForeignKeyAction, Format, GeneratorMetadata, IntrospectionSource, ManagementSourceOptions, NextStep, Paint, Prompter, Queryable, RunOptions, RunResult, Snapshot, SnapshotBucket, SnapshotExtras };

package/dist/cli/index.js

@@ -1,11 +1,12 @@
-import { a as list, r as defineCliCommand } from "./command-DV-StG1x.js";
-import { i as run, n as help, r as registerCommand, t as commandNames } from "./run-DA6_lg3w.js";
-import { n as CliError, t as CLI_ERRORS_URL } from "./errors-CqTLXe2M.js";
-import { t as VERSION } from "./version-B4k0aUxS.js";
-import { a as buildModel, c as toCatalog, r as emitModule, t as GENERATED_HEADER } from "./emit-BHHfwUoT.js";
-import { n as runGen, y as renderFiles } from "./run-DuN1MX-7.js";
-import { o as loadConfig } from "./config-M-WzL9O2.js";
-import { a as serializeSnapshot, d as pgSource, i as parseSnapshot, l as introspect, t as loadSnapshot, u as managementSource } from "./snapshot-Bstk6ulj.js";
+import { a as list, r as defineCliCommand } from "./command-CK9Cn8HV.js";
+import { i as run, n as createCli, r as help, t as commandNames } from "./run-CM_2g6KQ.js";
+import { t as VERSION } from "./version-DNRW4DAP.js";
+import { n as CliError, t as CLI_ERRORS_URL } from "./errors-Caiz_0so.js";
+import { t as toCatalog } from "./catalog-Di15TkM2.js";
+import { a as buildModel, r as emitModule, t as GENERATED_HEADER } from "./emit-ZAYeh4Yn.js";
+import { A as renderFiles, j as emitBlockConfig, n as runGen } from "./run-DaHfUUO9.js";
+import { s as loadConfig } from "./config-CLHpTk9Y.js";
+import { a as serializeSnapshot, d as managementSource, f as pgSource, i as parseSnapshot, l as introspect, t as loadSnapshot } from "./snapshot-DAxLi4hO.js";
 //#region src/cli/introspect/from-catalog.ts
 /**
 * Builds a snapshot from catalog records: the inverse of `toCatalog`. Tests
@@ -154,6 +155,7 @@ function fromCatalog(catalog) {
 			config_params: fn.searchPath === null ? null : { search_path: fn.searchPath === "" ? "\"\"" : fn.searchPath }
 		});
 	});
+	const comments = catalog.functions.flatMap((fn) => fn.comment === void 0 ? [] : [[`${fn.schema}.${fn.name}(${fn.signature})`, fn.comment]]);
 	return {
 		version: 2,
 		schemas,
@@ -178,9 +180,10 @@ function fromCatalog(catalog) {
 				...table.columnGrants ? { columnGrants: table.columnGrants } : {}
 			})),
 			buckets: catalog.buckets,
-			realtime: catalog.realtime
+			realtime: catalog.realtime,
+			...comments.length > 0 ? { functionComments: Object.fromEntries(comments) } : {}
 		}
 	};
 }
 //#endregion
-export { CLI_ERRORS_URL, CliError, GENERATED_HEADER, VERSION, buildModel, commandNames, defineCliCommand, emitModule, fromCatalog, help, introspect, list, loadConfig, loadSnapshot, managementSource, parseSnapshot, pgSource, registerCommand, renderFiles, run, runGen, serializeSnapshot, toCatalog };
+export { CLI_ERRORS_URL, CliError, GENERATED_HEADER, VERSION, buildModel, commandNames, createCli, defineCliCommand, emitBlockConfig, emitModule, fromCatalog, help, introspect, list, loadConfig, loadSnapshot, managementSource, parseSnapshot, pgSource, renderFiles, run, runGen, serializeSnapshot, toCatalog };