better-supabase 0.7.1 → 0.9.0

package/schemas/doctor-report-v1.json

@@ -50,6 +50,7 @@
               "BS114",
               "BS115",
               "BS116",
+              "BS117",
               "BS200",
               "BS204",
               "BS205",
@@ -70,6 +71,12 @@
               "BS220",
               "BS221",
               "BS222",
+              "BS223",
+              "BS224",
+              "BS225",
+              "BS226",
+              "BS227",
+              "BS228",
               "BS301",
               "BS302",
               "BS303",
@@ -97,6 +104,20 @@
               "BS325",
               "BS326",
               "BS327",
+              "BS328",
+              "BS329",
+              "BS330",
+              "BS331",
+              "BS332",
+              "BS333",
+              "BS334",
+              "BS335",
+              "BS336",
+              "BS337",
+              "BS338",
+              "BS339",
+              "BS340",
+              "BS341",
               "BS401",
               "BS402",
               "BS403",
@@ -109,8 +130,13 @@
               "BS410",
               "BS411",
               "BS412",
+              "BS413",
+              "BS414",
+              "BS415",
+              "BS416",
               "BS501",
-              "BS502"
+              "BS502",
+              "BS601"
             ]
           },
           "severity": { "enum": ["error", "warning", "info"] },

package/schemas/snapshot-v2.json

@@ -585,6 +585,256 @@
             },
             "required": ["comment", "id", "is_updatable", "name", "schema"]
           }
+        },
+        "rpcFunctions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "overloads": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "args": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "format": {
+                            "anyOf": [
+                              {
+                                "type": "string"
+                              },
+                              {
+                                "type": "null"
+                              }
+                            ]
+                          },
+                          "has_default": {
+                            "type": "boolean"
+                          },
+                          "mode": {
+                            "enum": ["in", "inout", "variadic"]
+                          },
+                          "name": {
+                            "type": "string"
+                          },
+                          "relation_id": {
+                            "anyOf": [
+                              {
+                                "type": "number"
+                              },
+                              {
+                                "type": "null"
+                              }
+                            ]
+                          },
+                          "type_id": {
+                            "type": "number"
+                          },
+                          "type_schema": {
+                            "anyOf": [
+                              {
+                                "type": "string"
+                              },
+                              {
+                                "type": "null"
+                              }
+                            ]
+                          }
+                        },
+                        "required": [
+                          "format",
+                          "has_default",
+                          "mode",
+                          "name",
+                          "relation_id",
+                          "type_id",
+                          "type_schema"
+                        ]
+                      }
+                    },
+                    "computed_field_of": {
+                      "anyOf": [
+                        {
+                          "type": "number"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "error": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "function_id": {
+                      "type": "number"
+                    },
+                    "is_set_returning": {
+                      "type": "boolean"
+                    },
+                    "returns": {
+                      "type": "object",
+                      "properties": {
+                        "columns": {
+                          "anyOf": [
+                            {
+                              "type": "array",
+                              "items": {
+                                "type": "object",
+                                "properties": {
+                                  "format": {
+                                    "anyOf": [
+                                      {
+                                        "type": "string"
+                                      },
+                                      {
+                                        "type": "null"
+                                      }
+                                    ]
+                                  },
+                                  "name": {
+                                    "type": "string"
+                                  },
+                                  "type_id": {
+                                    "type": "number"
+                                  },
+                                  "type_schema": {
+                                    "anyOf": [
+                                      {
+                                        "type": "string"
+                                      },
+                                      {
+                                        "type": "null"
+                                      }
+                                    ]
+                                  }
+                                },
+                                "required": [
+                                  "format",
+                                  "name",
+                                  "type_id",
+                                  "type_schema"
+                                ]
+                              }
+                            },
+                            {
+                              "type": "null"
+                            }
+                          ]
+                        },
+                        "format": {
+                          "anyOf": [
+                            {
+                              "type": "string"
+                            },
+                            {
+                              "type": "null"
+                            }
+                          ]
+                        },
+                        "relation_id": {
+                          "anyOf": [
+                            {
+                              "type": "number"
+                            },
+                            {
+                              "type": "null"
+                            }
+                          ]
+                        },
+                        "type_id": {
+                          "type": "number"
+                        },
+                        "type_schema": {
+                          "anyOf": [
+                            {
+                              "type": "string"
+                            },
+                            {
+                              "type": "null"
+                            }
+                          ]
+                        }
+                      },
+                      "required": [
+                        "columns",
+                        "format",
+                        "relation_id",
+                        "type_id",
+                        "type_schema"
+                      ]
+                    },
+                    "rows_estimate": {
+                      "anyOf": [
+                        {
+                          "type": "number"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "setof_options": {
+                      "anyOf": [
+                        {
+                          "type": "object",
+                          "properties": {
+                            "from": {
+                              "type": "string"
+                            },
+                            "is_one_to_one": {
+                              "type": "boolean"
+                            },
+                            "is_setof_return": {
+                              "type": "boolean"
+                            },
+                            "to": {
+                              "type": "string"
+                            }
+                          },
+                          "required": [
+                            "from",
+                            "is_one_to_one",
+                            "is_setof_return",
+                            "to"
+                          ]
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    }
+                  },
+                  "required": [
+                    "args",
+                    "computed_field_of",
+                    "error",
+                    "function_id",
+                    "is_set_returning",
+                    "returns",
+                    "rows_estimate",
+                    "setof_options"
+                  ]
+                }
+              },
+              "schema": {
+                "type": "string"
+              }
+            },
+            "required": ["name", "overloads", "schema"]
+          }
         }
       },
       "required": [
@@ -708,6 +958,12 @@
             }
           }
         },
+        "functionComments": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
         "hooks": {
           "type": "array",
           "items": {
@@ -993,6 +1249,21 @@
               },
               "function": {
                 "type": "string"
+              },
+              "args": {
+                "description": "The create trigger arguments, when there are any.",
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "source": {
+                "description": "The function body, only for functions other than broadcast_topic() that call realtime.send() or realtime.broadcast_changes().",
+                "type": "string"
+              },
+              "comment": {
+                "description": "The function comment, for the same functions as source.",
+                "type": "string"
               }
             }
           }

package/schemas/spec-manifest-v1.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/better-supabase/schemas/spec-manifest-v1.json",
+  "title": "better-supabase spec diagnostics manifest",
+  "description": "Output of `better-supabase spec emit|check|validate --json`, and the file `--manifest` writes. It has no timestamps, so the same inputs give the same bytes.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$schema",
+    "version",
+    "generator",
+    "failOn",
+    "ok",
+    "outputs",
+    "summary"
+  ],
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "const": 1 },
+    "generator": {
+      "type": "string",
+      "description": "`better-supabase` and its version."
+    },
+    "failOn": { "enum": ["error", "warning", "never"] },
+    "ok": {
+      "type": "boolean",
+      "description": "False when a finding fails `failOn` or `check` found a stale file."
+    },
+    "outputs": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/output" }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["error", "warning", "info"],
+      "properties": {
+        "error": { "type": "integer" },
+        "warning": { "type": "integer" },
+        "info": { "type": "integer" }
+      }
+    }
+  },
+  "$defs": {
+    "output": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "format",
+        "version",
+        "pin",
+        "path",
+        "sha256",
+        "status",
+        "cached",
+        "diagnostics"
+      ],
+      "properties": {
+        "format": { "type": "string" },
+        "version": { "type": "string" },
+        "pin": {
+          "type": "string",
+          "description": "The exact version or commit the output follows."
+        },
+        "path": {
+          "type": "string",
+          "description": "Relative to the project root."
+        },
+        "sha256": {
+          "type": "string",
+          "description": "SHA-256 of the rendered text."
+        },
+        "status": {
+          "enum": ["written", "unchanged", "up-to-date", "stale", "validated"]
+        },
+        "cached": { "type": "boolean" },
+        "diagnostics": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/diagnostic" }
+        }
+      }
+    },
+    "diagnostic": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "severity", "message"],
+      "properties": {
+        "code": { "type": "string" },
+        "severity": { "enum": ["error", "warning", "info"] },
+        "message": { "type": "string" },
+        "pointer": { "type": "string" }
+      }
+    }
+  }
+}

package/skills/better-supabase/SKILL.md

@@ -20,16 +20,24 @@ is no separate CLI package to add.
 new` for data and role settings. The sync needs
    `[experimental.pgdelta] enabled = true` in `supabase/config.toml`;
    doctor reports BS316 when a project is still on the legacy migra engine.
+   `sql.workflow` in the config picks how the SQL modules reach a migration:
+   `pg-delta` (the default), `migra` (declarative schemas 1.0, `supabase db
+diff`) or `migrations` (no `supabase/schemas`: the `sql` commands write
+   `<stamp>_better_supabase_modules.sql`, applied with `supabase migration up`).
 2. For a new table in an exposed schema, in the same file: `enable row level
 security`, a policy per role and command the app uses, and an index on
    every column a policy filters by. Write tenant checks as
    `organization_id in (select better_supabase.member_organization_ids())`, which
    Postgres runs once per statement, not `has_organization_role(organization_id)`,
    which runs once per row. List the table in `expose` in
-   `better-supabase.config.ts` and run `pnpm better-supabase sql add grants`:
+   `better-supabase.config.ts` and run `pnpm better-supabase add grants`:
    new tables get no Data API grants on their own.
 3. Apply it with `supabase db reset` (or `supabase migration up`).
-4. Run `pnpm better-supabase gen`, then fix the type errors it surfaces.
+4. Run `pnpm better-supabase gen`, then fix the type errors it surfaces. It
+   also runs every other generator the config sets up (`sql sync`, `spec
+emit`, the seed client, `scaffold api`); set `gen.tasks` to change the
+   list. Put flags you would repeat in `better-supabase.config.ts` (with a
+   `$ci` block for CI) instead of on the command line.
 5. Run `pnpm better-supabase doctor` and fix every error it reports (RLS off,
    missing policies, missing grants, unindexed foreign keys, drift).
 6. Commit the generated files. CI runs `better-supabase gen --check`, which
@@ -58,7 +66,8 @@ stay hidden.
    `--dry-run`, and fix the lines it lists for review.
 2. Run `pnpm better-supabase sql upgrade`, so the SQL modules get the
    release's SQL and any forward steps land in a migration, then write a
-   migration from the changed files.
+   migration from the changed files (under the `migrations` workflow it
+   writes that migration itself).
 3. Run `pnpm better-supabase gen` and commit the result. Since 0.3, a
    composite foreign key such as `(customer_id, organization_id)` is named
    after the remaining column (`customer`); set `tables.<name>.relations` in
@@ -91,6 +100,7 @@ Name the definition `betterSupabase` (in `lib/supabase/index.ts`) and every runt
 - Astro: `bs.locals(Astro).db`; SolidStart: `(await bs.require()).db`
 - Browser: `bs.db`, or the hooks from `createHooks<typeof bs>()`
 - Vue, Solid and Svelte, TanStack DB collections and a local expo-sqlite database: [references/frontend.md](references/frontend.md)
+- UI for a block (notification bell, notification list, command search, onboarding checklist): build it from the app's shadcn or React Native components and the block's hook, following [references/ui-recipes.md](references/ui-recipes.md). There is no better-supabase UI package; install glue with `npx shadcn add @better-supabase/<item>`.
 
 For who the caller is (sessions, claims, OAuth clients, agents, scopes), use
 the `better-supabase-auth` skill.
@@ -131,7 +141,7 @@ const customers = result.data;
 ```
 
 - Methods return a `Result`, and database errors never throw. Use `.orThrow()` only where an exception is really wanted.
-- Apps on better-result: `toBetterResult(result, Result, mapError)` converts at the boundary, and `defineBetterResultErrors(Result, { not_found: NotFound }, DbFailure)` maps `DbError` kinds to `TaggedError` classes once. Annotate the expected `Result<T, E>` type instead of casting.
+- Apps on better-result: `withBetterResult(db, toResult)` from `better-supabase/better-result` returns a `db` whose repositories, `$rpc` and `$list(list, query)` return better-result values; `toBetterResult(result, Result, mapError)` converts one result, and `defineBetterResultErrors(Result, { not_found: NotFound }, DbFailure)` maps `DbError` kinds to `TaggedError` classes once. Annotate the expected `Result<T, E>` type instead of casting.
 - Column names use the configured casing (`casing: 'camel'` means `organizationId`). Raw escape hatches (`$client`, and `queryRaw` on the `better-supabase/postgres` clients) use database names.
 - Writes: `create`, `createMany`, `update(id, patch)`, `updateMany`, `upsert`, `delete`.
 - Page lists with a cursor: `paginate({ after: null, size: 25, orderBy })`, then pass `nextCursor` back as `after` with the same `orderBy` and `where`. Use `page` numbers only when users jump to a page and need a total, and `paginate({ offset, limit, count: 'exact' })` when the caller already has an offset; both return the rows and the total in one request.
@@ -143,14 +153,15 @@ const customers = result.data;
 
 - With `codecs: { timestamptz: 'instant' }` in the config, `timestamptz` columns decode to `Temporal.Instant` and `timestamp` columns to `Temporal.PlainDateTime`, with microseconds. Without the codec they stay ISO strings.
 - `now` options, job and webhook timestamps and `bucket.sweep({ olderThan })` take `Temporal` values. Auth's `now` stays in epoch milliseconds.
-- On Node 24, Safari and other runtimes without `Temporal`, add `temporal-polyfill` and `import "temporal-polyfill/global"` once at startup. Without it, calls that need `Temporal` return an `unexpected` `DbError` that names the import.
+- On Node 24, Safari, Hermes and other runtimes without `Temporal`, add `temporal-polyfill` and pass its namespace: `defineSupabase(schema, { temporal: Temporal })` (block creators take the same `temporal` option). `import "temporal-polyfill/global"` once at startup also works. Without either, calls that need `Temporal` return an `unexpected` `DbError` that names both.
 - Use TypeScript 6 or 7; 5.9 has no Temporal lib.
 
 ## CLI in scripts and CI
 
-- No command takes a connection string as an argument. Set `$DATABASE_URL` or `source.dbUrl`, or pipe it in with `--db-url-stdin`.
-- `--json` prints one JSON document on stdout: the result, or Problem Details with a `code` on failure. `--yes` and `CI` turn prompts off.
-- Exit codes: 0 success, 1 a failure or finding (`--check` drift, doctor errors), 2 a usage, config or environment problem. Each error code is listed at https://bettersupabase.com/docs/cli/errors.
+- No command takes a connection string as an argument. Set `$DATABASE_URL`, `$SUPABASE_DB_URL` or `source.dbUrl`, or pipe it in with `--db-url-stdin`.
+- `--json` prints one envelope on stdout: `status`, the result under `data`, Problem Details with a `code` under `error`, and the commands to run under `next`. `--yes` and `CI` turn prompts off.
+- Exit codes: 0 success, 1 a failure or finding (`--check` drift, doctor errors), 2 a usage, config or environment problem, 3 when the user has to act. Each error code is listed at https://bettersupabase.com/docs/cli/errors.
+- When the CLI detects an agent it prints JSON and never prompts. Exit code 3 with `input_required` lists `missing` flags and their `choices`; run the `next` command with the value filled in. `consent_required` means the user must agree first (`--force` over their files, `seed --apply` on a remote database): ask them, then run the `next` command with its `--confirm` token. Never pass `--confirm` without asking. See https://bettersupabase.com/docs/cli/agent-mode.
 
 ## Don't
 

package/skills/better-supabase/references/plugins.md

@@ -54,7 +54,7 @@ RLS still decides what a user can read and write. `tenant()` makes queries
 explicit and fills the column; it doesn't replace the policy.
 
 The tenant comes from `context.tenant`, which the server's `tenant` resolver
-sets per request (the default `sql.modules.access.activeTenant: 'resolver'`), then
+sets per request (the default `blocks.access.activeTenant: 'resolver'`), then
 the verified `tenant_id` claim (renamed with `claims.tenant` in
 `better-supabase.config.ts`), then `app_metadata.tenant_id`. A resolver may
 read the URL, but `current_tenant_id()` only returns a tenant the caller is a
@@ -64,7 +64,7 @@ or `bs.action({ tenant: (input) => input.organizationId })`, which take the
 resolver's path and get the same check. Never trust a tenant from
 `user_metadata`, and never use one from a request body outside those options. When the config
 has an `authorization` provider whose hook owns `memberships`, that hook
-writes the claim and the memberships: don't run `sql add tenant`, and follow
+writes the claim and the memberships: don't run `add tenant`, and follow
 the authorization providers reference of the `better-supabase-auth` skill
 (https://bettersupabase.com/docs/extending/authorization-providers.md).
 

package/skills/better-supabase/references/troubleshooting.md

@@ -7,24 +7,24 @@ Start with `pnpm better-supabase doctor`. It checks the database, RLS,
 
 Branch on `result.error.kind`, not on the message.
 
-| Kind                                                  | Usual cause                                                                    | Fix                                                                           |
-| ----------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
-| `not_found`                                           | The row doesn't exist, or RLS hides it from this user                          | Check the policy with an `asUser` test before assuming the row is gone        |
-| `unauthorized`                                        | No valid session or token                                                      | Get `db` from the adapter for this request                                    |
-| `forbidden`                                           | RLS or a grant rejected the write                                              | Fix the policy or the grant; don't switch to `bs.admin()`                     |
-| `conflict`                                            | Unique violation                                                               | Use `upsert`, or return the error to the caller                               |
-| `foreign_key`                                         | Referenced row missing, or still referenced on delete                          | Create the parent first, or delete children                                   |
-| `not_null`, `check`, `exclusion`                      | A constraint rejected the row                                                  | Validate input earlier with the `validation()` plugin                         |
-| `invalid_input`                                       | Postgres couldn't parse a value (bad uuid, enum)                               | Validate before the call                                                      |
-| `invalid_value`                                       | A stored value the app type can't hold (`infinity` in a Temporal timestamp)    | Store a real timestamp or `null`, or read the column without the codec        |
-| `validation`                                          | A Standard Schema rejected the input; see `issues`                             | Show the issues to the user                                                   |
-| `invalid_request`                                     | The query can't run over PostgREST (for example a relation filter on `update`) | Read the keys first, or use a database function or `better-supabase/postgres` |
-| `multiple_rows`                                       | `findUnique` or a single-row write matched more than one row                   | Filter by a unique key                                                        |
-| `stale`                                               | `update(..., { expect })` found a newer row                                    | Reload the row and retry                                                      |
-| `serialization`, `timeout`, `network`, `rate_limited` | Transient                                                                      | Retry with backoff, or surface the error                                      |
-| `unsupported`                                         | The executor can't run the query, such as an include on SQLite (PowerSync)     | Read it on the server, or check list definitions with `checkSqlite` in a test |
-| `raised`                                              | A database function raised an exception                                        | Read `message` and `code` from the function                                   |
-| `unexpected` naming `temporal-polyfill/global`        | The runtime has no `Temporal` (Node 24, Safari)                                | Pass `temporal: Temporal` from `temporal-polyfill` to `defineSupabase`        |
+| Kind                                                  | Usual cause                                                                    | Fix                                                                                                         |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
+| `not_found`                                           | The row doesn't exist, or RLS hides it from this user                          | Check the policy with an `asUser` test before assuming the row is gone                                      |
+| `unauthorized`                                        | No valid session or token                                                      | Get `db` from the adapter for this request                                                                  |
+| `forbidden`                                           | RLS or a grant rejected the write                                              | Fix the policy or the grant; don't switch to `bs.admin()`                                                   |
+| `conflict`                                            | Unique violation                                                               | Use `upsert`, or return the error to the caller                                                             |
+| `foreign_key`                                         | Referenced row missing, or still referenced on delete                          | Create the parent first, or delete children                                                                 |
+| `not_null`, `check`, `exclusion`                      | A constraint rejected the row                                                  | Validate input earlier with the `validation()` plugin                                                       |
+| `invalid_input`                                       | Postgres couldn't parse a value (bad uuid, enum)                               | Validate before the call                                                                                    |
+| `invalid_value`                                       | A stored value the app type can't hold (`infinity` in a Temporal timestamp)    | Store a real timestamp or `null`, or read the column without the codec                                      |
+| `validation`                                          | A Standard Schema rejected the input; see `issues`                             | Show the issues to the user                                                                                 |
+| `invalid_request`                                     | The query can't run over PostgREST (for example a relation filter on `update`) | Read the keys first, or use a database function or `better-supabase/postgres`                               |
+| `multiple_rows`                                       | `findUnique` or a single-row write matched more than one row                   | Filter by a unique key                                                                                      |
+| `stale`                                               | `update(..., { expect })` found a newer row                                    | Reload the row and retry                                                                                    |
+| `serialization`, `timeout`, `network`, `rate_limited` | Transient                                                                      | Retry with backoff, or surface the error                                                                    |
+| `unsupported`                                         | The executor can't run the query, such as an include on SQLite (PowerSync)     | Read it on the server, set the PowerSync `fallback`, or check list definitions with `checkSqlite` in a test |
+| `raised`                                              | A database function raised an exception                                        | Read `message` and `code` from the function                                                                 |
+| `unexpected` naming `temporal-polyfill/global`        | The runtime has no `Temporal` (Node 24, Safari)                                | Pass `temporal: Temporal` from `temporal-polyfill` to `defineSupabase`                                      |
 
 ## By error `code`
 
@@ -51,8 +51,8 @@ Branch on `result.error.kind`, not on the message.
 - The CLI exits with 2: the command line, the config or an environment
   variable needs a change. Rerun with `--json` to get the error `code`, and
   look it up at https://bettersupabase.com/docs/cli/errors.
-- `--db-url` is rejected: set `$DATABASE_URL` or pipe the URL in with
-  `--db-url-stdin`.
+- `--db-url` is rejected: set `$DATABASE_URL` or `$SUPABASE_DB_URL`, or pipe
+  the URL in with `--db-url-stdin`.
 - Two different `Temporal.Instant` values compare equal in `toEqual`: compare
   with `.equals()` or register an equality tester (the
   `better-supabase-testing` skill).