better-supabase 0.7.0 → 0.8.0

package/dist/{workflows-B0j9WKPu.d.ts → workflows-CcpCBfIe.d.ts}

@@ -1,7 +1,7 @@
 /// <reference lib="esnext.temporal" />
-import { t as AsyncResult, w as ErrorMapper } from "./result-D7y2fT87.js";
-import { t as BlockTransport } from "./block-transport-DvaoPuZ9.js";
-import { i as CursorPageOptions, r as BlockTemporalOptions } from "./block-helpers-CKtbFcRv.js";
+import { t as AsyncResult, w as ErrorMapper } from "./result-BchM1XZn.js";
+import { t as BlockTransport } from "./block-transport-inD4fFq-.js";
+import { i as CursorPageOptions, r as BlockTemporalOptions } from "./block-helpers-C0Xj8War.js";
 import { r as RunState } from "./run-state-CPo-1X2B.js";
 //#region src/blocks/workflows/workflows.d.ts
 /** A workflow run's state, in the words ai-chat and ai-tasks runs share. */

package/dist/{workflows-wu1WWBn7.js → workflows-IvxzG2cl.js}

@@ -1,7 +1,8 @@
-import { t as temporal } from "./temporal-required-BVvW7SYJ.js";
-import { a as ok, r as err } from "./result-DzUbqgdW.js";
-import { n as nextCronRun, t as assertCron } from "./cron-DVPUg5k3.js";
-import { O as textOf, S as requiredInstant, c as errorText, d as isRecord, g as pageOf, h as optionalText, i as blockCall, m as optionalInstant, n as applyTemporal, u as instantArg, w as seconds, x as recordsOf, y as recordOf } from "./block-helpers-DWHxHsEQ.js";
+import { t as temporal } from "./temporal-required-BtynQtM-.js";
+import { a as ok, r as err } from "./result-DEqHCMKP.js";
+import { n as isRecord } from "./guards-6F2bCtQR.js";
+import { n as nextCronRun, t as assertCron } from "./cron-D25Ukpxy.js";
+import { D as seconds, S as recordOf, T as requiredInstant, _ as optionalInstant, d as instantArg, i as blockCall, j as textOf, l as errorText, n as applyTemporal, v as optionalText, w as recordsOf, y as pageOf } from "./block-helpers-Cy3pB96I.js";
 //#region src/blocks/workflows/workflows.ts
 const STATUSES = /* @__PURE__ */ new Set([
 	"queued",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-supabase",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Strongly typed Supabase: generated schema, typed repositories, plugins, auth glue, framework integrations and the better-supabase CLI.",
   "keywords": [
     "cli",
@@ -346,6 +346,10 @@
       "types": "./dist/vercel-connect/index.d.ts",
       "default": "./dist/vercel-connect/index.js"
     },
+    "./better-result": {
+      "types": "./dist/better-result/index.d.ts",
+      "default": "./dist/better-result/index.js"
+    },
     "./blocks/inbox": {
       "types": "./dist/blocks/inbox/index.d.ts",
       "default": "./dist/blocks/inbox/index.js"
@@ -468,6 +472,22 @@
       "types": "./dist/openapi/index.d.ts",
       "default": "./dist/openapi/index.js"
     },
+    "./spec": {
+      "types": "./dist/spec/index.d.ts",
+      "default": "./dist/spec/index.js"
+    },
+    "./overlay": {
+      "types": "./dist/overlay/index.d.ts",
+      "default": "./dist/overlay/index.js"
+    },
+    "./asyncapi": {
+      "types": "./dist/asyncapi/index.d.ts",
+      "default": "./dist/asyncapi/index.js"
+    },
+    "./arazzo": {
+      "types": "./dist/arazzo/index.d.ts",
+      "default": "./dist/arazzo/index.js"
+    },
     "./otel": {
       "types": "./dist/otel/index.d.ts",
       "default": "./dist/otel/index.js"
@@ -517,6 +537,10 @@
       "types": "./dist/tanstack-db/index.d.ts",
       "default": "./dist/tanstack-db/index.js"
     },
+    "./tanstack-db/supabase": {
+      "types": "./dist/tanstack-db/supabase/index.d.ts",
+      "default": "./dist/tanstack-db/supabase/index.js"
+    },
     "./blocks/push": {
       "types": "./dist/blocks/push/index.d.ts",
       "default": "./dist/blocks/push/index.js"
@@ -554,10 +578,14 @@
     "@orpc/openapi": "2.0.0-beta.42",
     "@orpc/server": "2.0.0-beta.42",
     "@supabase-labs/middleware-openfeature": "0.2.0",
+    "@supabase-labs/tanstack-db": "0.1.0",
     "@supabase/config": "0.11.1",
+    "@supabase/lite": "0.11.0",
+    "@supabase/mcp-server-supabase": "0.13.0",
     "@supabase/postgrest-typegen": "0.4.0",
     "@supabase/supabase-js": "2.117.2",
     "@t3-oss/env-core": "0.13.11",
+    "@tanstack/db": "0.12.3",
     "@tanstack/query-core": "5.104.1",
     "@tanstack/react-query": "5.104.1",
     "@types/node": "26.6.4",
@@ -572,6 +600,7 @@
     "ai": "7.0.131",
     "ajv": "8.20.0",
     "ajv-formats": "3.0.1",
+    "better-result": "3.0.1",
     "c12": "4.0.0-rc.2",
     "chat": "4.41.1",
     "citty": "0.2.2",
@@ -581,6 +610,7 @@
     "expo-server": "57.0.3",
     "fastest-levenshtein": "1.0.16",
     "hono": "4.13.13",
+    "jsonpath-rfc9535": "1.3.0",
     "next": "16.3.8",
     "oxfmt": "0.71.0",
     "oxlint": "1.86.0",
@@ -603,6 +633,7 @@
     "vitest": "5.0.3",
     "vue": "3.5.43",
     "workflow": "5.1.0",
+    "yaml": "2.9.1",
     "zod": "4.6.5"
   },
   "peerDependencies": {
@@ -614,17 +645,22 @@
     "@next/playwright": ">=16.2 <17",
     "@opentelemetry/api": ">=1.9 <2",
     "@orpc/server": ">=2.0.0-beta.40 <3",
+    "@supabase-labs/tanstack-db": ">=0.1.0 <0.2",
     "@supabase/config": ">=0.9.0 <0.12",
-    "@supabase/postgrest-typegen": "0.4.0",
+    "@supabase/lite": ">=0.11.0 <0.12",
+    "@supabase/mcp-server-supabase": ">=0.13.0 <0.14",
+    "@supabase/postgrest-typegen": ">=0.4.0 <0.5",
     "@supabase/supabase-js": "^2.116.0",
     "@tanstack/query-core": "^5.62.0",
     "@workflow/world": ">=5.0.2 <5.1",
     "@workflow/world-postgres": ">=5.0.2 <5.1",
     "ai": ">=7 <8",
+    "better-result": ">=3 <4",
     "chat": ">=4.41 <5",
     "eve": ">=0.71 <1",
     "expo-server": ">=55 <59",
     "hono": ">=4 <5",
+    "jsonpath-rfc9535": ">=1.3.0 <2",
     "next": ">=16.3 <17",
     "oxfmt": ">=0.66.0 <1",
     "pg": ">=8.15 <9",
@@ -662,9 +698,18 @@
     "@orpc/server": {
       "optional": true
     },
+    "@supabase-labs/tanstack-db": {
+      "optional": true
+    },
     "@supabase/config": {
       "optional": true
     },
+    "@supabase/lite": {
+      "optional": true
+    },
+    "@supabase/mcp-server-supabase": {
+      "optional": true
+    },
     "@supabase/postgrest-typegen": {
       "optional": true
     },
@@ -680,6 +725,9 @@
     "ai": {
       "optional": true
     },
+    "better-result": {
+      "optional": true
+    },
     "chat": {
       "optional": true
     },
@@ -692,6 +740,9 @@
     "hono": {
       "optional": true
     },
+    "jsonpath-rfc9535": {
+      "optional": true
+    },
     "next": {
       "optional": true
     },
@@ -730,7 +781,7 @@
     "node": ">=24"
   },
   "scripts": {
-    "bench": "node tests/next/next.bench.ts && node tests/core/plugins.bench.ts && node tests/core/compile.bench.ts && node tests/server/context.bench.ts",
+    "bench": "node tests/next/next.bench.ts && node tests/core/plugins.bench.ts && node tests/core/compile.bench.ts && node tests/server/context.bench.ts && node tests/cli/spec/spec.bench.ts",
     "build": "tsdown",
     "check:publish": "publint && pnpm pack --out pack.tgz && attw --profile esm-only pack.tgz && rm -f pack.tgz",
     "gen:fixtures": "node scripts/gen-fixtures.ts",

package/schemas/config-v1.json

@@ -29,6 +29,10 @@
         "snapshot": {
           "type": "string",
           "description": "Read a saved introspection snapshot instead of connecting."
+        },
+        "lite": {
+          "type": "boolean",
+          "description": "Read a Supabase Lite project's schema from [db] driver in supabase/config.toml. On when that key is present; false reads the database like any other project."
         }
       }
     },
@@ -1128,6 +1132,8 @@
     },
     "openapi": {
       "type": "object",
+      "deprecated": true,
+      "description": "Deprecated: use specs. openapi.entry and openapi.output map onto it.",
       "additionalProperties": false,
       "properties": {
         "entry": {
@@ -1140,6 +1146,63 @@
         }
       }
     },
+    "specs": {
+      "type": "object",
+      "description": "The documents better-supabase spec emit writes (OpenAPI, AsyncAPI, Arazzo).",
+      "additionalProperties": false,
+      "properties": {
+        "entry": {
+          "type": "string",
+          "description": "Module exporting a defineApi() result (or a function returning one) as api or default. Defaults to openapi.entry.",
+          "default": "src/lib/openapi.ts"
+        },
+        "outputs": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["format"],
+            "properties": {
+              "format": {
+                "type": "string",
+                "minLength": 1,
+                "description": "A format id: openapi, asyncapi or arazzo."
+              },
+              "version": {
+                "type": "string",
+                "description": "Defaults to the format's default version."
+              },
+              "output": {
+                "type": "string",
+                "description": "File to write, relative to the root. Defaults to the format's file name."
+              },
+              "overlays": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Overlay files (JSON or YAML), applied in order."
+              },
+              "serialize": {
+                "enum": ["json", "yaml"],
+                "description": "Defaults to yaml when output ends in .yaml or .yml, otherwise json."
+              },
+              "ui": {
+                "enum": ["scalar", "swagger", "redoc", "elements", "rapidoc"],
+                "description": "Also writes a reference page (openapi.html for openapi.json) next to OpenAPI outputs."
+              }
+            }
+          }
+        },
+        "failOn": {
+          "enum": ["error", "warning", "never"],
+          "default": "error",
+          "description": "The lowest severity that fails spec emit, check and validate."
+        },
+        "manifest": {
+          "type": "string",
+          "description": "Also write the diagnostics manifest (JSON) to this file, like spec --manifest."
+        }
+      }
+    },
     "doctor": {
       "type": "object",
       "additionalProperties": false,
@@ -1151,9 +1214,26 @@
             "pattern": "^BS\\d{3}$"
           }
         },
+        "only": {
+          "type": "array",
+          "description": "Run only these checks.",
+          "items": {
+            "type": "string",
+            "pattern": "^BS\\d{3}$"
+          }
+        },
         "strict": {
           "type": "boolean"
         },
+        "format": {
+          "enum": ["text", "sarif", "github"],
+          "default": "text",
+          "description": "Report format. The global --json flag still picks the JSON report."
+        },
+        "output": {
+          "type": "string",
+          "description": "Write the report to this file."
+        },
         "sources": {
           "type": "array",
           "items": {
@@ -1169,9 +1249,172 @@
           "minimum": 1
         }
       }
+    },
+    "gen": {
+      "type": "object",
+      "description": "What better-supabase gen runs.",
+      "additionalProperties": false,
+      "properties": {
+        "tasks": {
+          "type": "array",
+          "description": "The steps gen runs, in order. Without a list: types, plus sql, spec, seed and scaffold when the project uses them. env runs only when listed.",
+          "items": {
+            "enum": ["types", "sql", "spec", "seed", "scaffold", "env"]
+          }
+        },
+        "watchInterval": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "description": "Milliseconds between checks in gen --watch and spec emit --watch."
+        }
+      }
+    },
+    "env": {
+      "type": "object",
+      "description": "The env file better-supabase env writes.",
+      "additionalProperties": false,
+      "properties": {
+        "output": {
+          "type": "string",
+          "default": ".env.local"
+        },
+        "prefix": {
+          "type": "string",
+          "description": "Prefix for browser variables, such as NEXT_PUBLIC_; none for no prefix. Detected from the framework by default."
+        }
+      }
+    },
+    "scaffold": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "api": {
+          "type": "object",
+          "description": "What better-supabase scaffold api writes; the scaffold gen step keeps its generated file current.",
+          "additionalProperties": false,
+          "properties": {
+            "framework": {
+              "enum": ["hono", "next"]
+            },
+            "tables": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "name": {
+              "type": "string",
+              "default": "api"
+            },
+            "basePath": {
+              "type": "string",
+              "default": "/api"
+            }
+          }
+        }
+      }
+    },
+    "integrations": {
+      "type": "array",
+      "description": "The integrations init and add wrote.",
+      "items": {
+        "enum": [
+          "next",
+          "hono",
+          "orpc",
+          "edge",
+          "expo",
+          "mcp",
+          "client",
+          "react"
+        ]
+      }
+    },
+    "skills": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "agents": {
+          "type": "array",
+          "description": "Agent folders skills install writes to. Defaults to the ones the project has, else agents.",
+          "items": {
+            "enum": ["cursor", "claude", "agents"]
+          }
+        }
+      }
+    },
+    "keys": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "output": {
+          "type": "string",
+          "description": "Signing key file better-supabase keys writes. Defaults to supabase/signing_keys.json."
+        }
+      }
+    },
+    "$env": {
+      "type": "object",
+      "description": "Overrides per environment, keyed by name. Picked by --env, $BETTER_SUPABASE_ENV, or ci when $CI is set.",
+      "additionalProperties": {
+        "$ref": "#/$defs/environment"
+      }
+    },
+    "$development": {
+      "$ref": "#/$defs/environment"
+    },
+    "$production": {
+      "$ref": "#/$defs/environment"
+    },
+    "$test": {
+      "$ref": "#/$defs/environment"
+    },
+    "$ci": {
+      "$ref": "#/$defs/environment"
     }
   },
   "$defs": {
+    "environment": {
+      "type": "object",
+      "description": "Keys an environment block overrides. Objects merge into the config; arrays and other values replace.",
+      "additionalProperties": false,
+      "properties": {
+        "source": { "$ref": "#/properties/source" },
+        "schemas": { "$ref": "#/properties/schemas" },
+        "casing": { "$ref": "#/properties/casing" },
+        "tables": { "$ref": "#/properties/tables" },
+        "output": { "$ref": "#/properties/output" },
+        "postgrestVersion": { "$ref": "#/properties/postgrestVersion" },
+        "codecs": { "$ref": "#/properties/codecs" },
+        "relations": { "$ref": "#/properties/relations" },
+        "json": { "$ref": "#/properties/json" },
+        "generators": { "$ref": "#/properties/generators" },
+        "plugins": { "$ref": "#/properties/plugins" },
+        "claims": { "$ref": "#/properties/claims" },
+        "buckets": { "$ref": "#/properties/buckets" },
+        "topics": { "$ref": "#/properties/topics" },
+        "sensitive": { "$ref": "#/properties/sensitive" },
+        "storagePaths": { "$ref": "#/properties/storagePaths" },
+        "functions": { "$ref": "#/properties/functions" },
+        "expose": { "$ref": "#/properties/expose" },
+        "readSets": { "$ref": "#/properties/readSets" },
+        "entitlements": { "$ref": "#/properties/entitlements" },
+        "authorization": { "$ref": "#/properties/authorization" },
+        "vectorSearch": { "$ref": "#/properties/vectorSearch" },
+        "realtime": { "$ref": "#/properties/realtime" },
+        "sql": { "$ref": "#/properties/sql" },
+        "seed": { "$ref": "#/properties/seed" },
+        "openapi": { "$ref": "#/properties/openapi" },
+        "specs": { "$ref": "#/properties/specs" },
+        "doctor": { "$ref": "#/properties/doctor" },
+        "gen": { "$ref": "#/properties/gen" },
+        "env": { "$ref": "#/properties/env" },
+        "scaffold": { "$ref": "#/properties/scaffold" },
+        "integrations": { "$ref": "#/properties/integrations" },
+        "skills": { "$ref": "#/properties/skills" },
+        "keys": { "$ref": "#/properties/keys" }
+      }
+    },
     "stringRecord": {
       "type": "object",
       "additionalProperties": {

package/schemas/doctor-report-v1.json

@@ -97,6 +97,8 @@
               "BS325",
               "BS326",
               "BS327",
+              "BS328",
+              "BS329",
               "BS401",
               "BS402",
               "BS403",
@@ -110,7 +112,8 @@
               "BS411",
               "BS412",
               "BS501",
-              "BS502"
+              "BS502",
+              "BS601"
             ]
           },
           "severity": { "enum": ["error", "warning", "info"] },

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

@@ -29,7 +29,11 @@ security`, a policy per role and command the app uses, and an index on
    `better-supabase.config.ts` and run `pnpm better-supabase sql 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
@@ -131,7 +135,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,12 +147,12 @@ 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`.
+- 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 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.