better-supabase 0.4.0 → 0.5.0

package/schemas/config-v1.json

@@ -292,7 +292,10 @@
               "type": "object",
               "additionalProperties": false,
               "properties": {
-                "scope": { "type": "string", "default": "organization" }
+                "scope": {
+                  "type": "string",
+                  "description": "The PermDock scope tenants are. Defaults to the manifest's root scope, the rls.scopes entry without within."
+                }
               }
             }
           ]
@@ -346,6 +349,11 @@
           "description": "Tables that broadcast change signals (`table` or `schema.table`). Install with `better-supabase sql add realtime-tables`.",
           "type": "array",
           "items": { "type": "string" }
+        },
+        "global": {
+          "description": "Tables in `tables` without a tenant column, which broadcast on one topic for every signed-in user.",
+          "type": "array",
+          "items": { "type": "string" }
         }
       }
     },
@@ -359,6 +367,14 @@
         "kit": { "type": "array", "items": { "type": "string" } }
       }
     },
+    "kits": {
+      "type": "object",
+      "description": "How each SQL kit module maps onto the database, keyed by module name.",
+      "properties": {
+        "access": { "$ref": "#/$defs/accessKit" }
+      },
+      "additionalProperties": { "$ref": "#/$defs/kitModule" }
+    },
     "seed": {
       "type": "object",
       "additionalProperties": false,
@@ -394,6 +410,120 @@
     }
   },
   "$defs": {
+    "stringRecord": {
+      "type": "object",
+      "additionalProperties": { "type": "string" }
+    },
+    "kitModuleProperties": {
+      "mode": { "enum": ["managed", "adopt", "custom"], "default": "managed" },
+      "schema": { "type": "string", "default": "better_supabase" },
+      "tables": {
+        "type": "object",
+        "additionalProperties": { "type": ["string", "null"] }
+      },
+      "columns": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "object",
+          "additionalProperties": { "type": ["string", "null"] }
+        }
+      },
+      "idType": { "type": "string" },
+      "triggerPrefix": { "type": "string", "default": "bs_" },
+      "permissions": { "$ref": "#/$defs/stringRecord" },
+      "options": { "type": "object" }
+    },
+    "kitModule": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "mode": { "$ref": "#/$defs/kitModuleProperties/mode" },
+        "schema": { "$ref": "#/$defs/kitModuleProperties/schema" },
+        "tables": { "$ref": "#/$defs/kitModuleProperties/tables" },
+        "columns": { "$ref": "#/$defs/kitModuleProperties/columns" },
+        "idType": { "$ref": "#/$defs/kitModuleProperties/idType" },
+        "triggerPrefix": {
+          "$ref": "#/$defs/kitModuleProperties/triggerPrefix"
+        },
+        "permissions": { "$ref": "#/$defs/kitModuleProperties/permissions" },
+        "options": { "$ref": "#/$defs/kitModuleProperties/options" }
+      }
+    },
+    "accessKit": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "mode": { "$ref": "#/$defs/kitModuleProperties/mode" },
+        "schema": { "$ref": "#/$defs/kitModuleProperties/schema" },
+        "tables": { "$ref": "#/$defs/kitModuleProperties/tables" },
+        "columns": { "$ref": "#/$defs/kitModuleProperties/columns" },
+        "idType": { "$ref": "#/$defs/kitModuleProperties/idType" },
+        "triggerPrefix": {
+          "$ref": "#/$defs/kitModuleProperties/triggerPrefix"
+        },
+        "permissions": { "$ref": "#/$defs/kitModuleProperties/permissions" },
+        "options": { "$ref": "#/$defs/kitModuleProperties/options" },
+        "model": {
+          "enum": ["roles", "catalog", "permdock", "custom"],
+          "default": "roles"
+        },
+        "roles": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "functions": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "can": { "type": "string" },
+            "tenantIdsWith": { "type": "string" },
+            "isPlatform": { "type": "string" },
+            "canUser": { "type": "string" },
+            "canAssign": { "type": "string" },
+            "permissionClaims": { "type": "string" }
+          }
+        },
+        "platformClaim": {
+          "type": "string",
+          "default": "platform_permissions"
+        },
+        "disabled": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "tenant": { "type": "string" },
+            "tenantKey": { "type": "string" },
+            "user": { "type": "string" },
+            "userKey": { "type": "string" }
+          }
+        },
+        "activeTenant": {
+          "oneOf": [
+            { "enum": ["claim", "resolver"] },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["profileColumn"],
+              "properties": {
+                "profileColumn": { "type": "string" },
+                "key": { "type": "string" }
+              }
+            }
+          ]
+        },
+        "permdock": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "schema": { "type": "string" },
+            "scope": { "type": "string" }
+          }
+        }
+      }
+    },
     "casing": { "enum": ["snake", "camel"] },
     "privileges": {
       "type": "array",

package/schemas/doctor-report-v1.json

@@ -73,6 +73,14 @@
               "BS304",
               "BS305",
               "BS306",
+              "BS307",
+              "BS308",
+              "BS309",
+              "BS310",
+              "BS311",
+              "BS312",
+              "BS313",
+              "BS314",
               "BS401",
               "BS402",
               "BS403",
@@ -81,6 +89,8 @@
               "BS406",
               "BS407",
               "BS408",
+              "BS409",
+              "BS410",
               "BS501",
               "BS502"
             ]

package/skills/better-supabase/SKILL.md

@@ -53,16 +53,19 @@ stay hidden.
 
 ## Workflow: after upgrading better-supabase
 
-1. Rerun `pnpm better-supabase sql add` with the kit modules the project
-   installed, so their SQL gets the release's fixes, then write a migration
-   from the changed files.
-2. Run `pnpm better-supabase gen` and commit the result. Since 0.3, a
+1. Run `pnpm better-supabase codemod <version> --dry-run` for each minor
+   version you crossed (`codemod` without a name lists them), then without
+   `--dry-run`, and fix the lines it lists for review.
+2. Run `pnpm better-supabase sql upgrade`, so the kit modules get the
+   release's SQL and any forward steps land in a migration, then write a
+   migration from the changed files.
+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
    the config to keep an old relation name.
-3. Run `pnpm better-supabase skills install --check` and reinstall the skills
+4. Run `pnpm better-supabase skills install --check` and reinstall the skills
    when it reports them stale.
-4. Read the release's breaking changes in
+5. Read the release's breaking changes in
    https://github.com/ScaleDockHQ/better-supabase/blob/main/CHANGELOG.md
    (guides live under https://bettersupabase.com/docs/migration). For 0.3: time values are
    `Temporal` (see below), `--db-url` is gone, `doctor --format json` is

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

@@ -53,9 +53,12 @@ filled it.
 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 the verified `tenant_id` claim (renamed with
-`claims.tenant` in `better-supabase.config.ts`), then `app_metadata.tenant_id`.
-Never read it from `user_metadata`, a URL or a request body. When the project
+The tenant comes from `context.tenant`, which the server's `tenant` resolver
+sets per request (the default `kits.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
+member of. Never trust a tenant from `user_metadata` or a request body. When the project
 has a `permdock.config.ts`, PermDock's hook writes that claim and the
 memberships: don't run `sql add tenant`, and follow the PermDock reference of
 the `better-supabase-auth` skill

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

@@ -16,6 +16,7 @@ Branch on `result.error.kind`, not on the message.
 | `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                                                        |

package/skills/better-supabase-api/SKILL.md

@@ -88,11 +88,18 @@ for lists that clients read page by page: the list takes `after` instead of
 
 ## Background work (`better-supabase/jobs`, needs `sql add jobs idempotency webhook-inbox`)
 
-- `createJobs(postgres.admin, { queue_name: zodSchema })` runs on Supabase Queues (pgmq): `enqueue` in the request, then `work` or `drain` in a worker. The handler throws to retry. `schedule(name, cron, queue, payload)` uses pg_cron. Queue names are lowercase letters, digits and underscores. With a service-role Supabase client instead of SQL, it uses the `pgmq_public` RPCs (no dedupe or schedules).
+- `createJobs(postgres.admin, { queue_name: zodSchema })` runs on Supabase Queues (pgmq): `enqueue` in the request, then `work` or `drain` in a worker. The handler throws to retry. `schedule(name, cron, queue, payload, { timeZone })` uses pg_cron, or with `kits.jobs.options.scheduler: "drain"` a `jobs.drainRoute({ secret: process.env.CRON_SECRET, handlers })` route that Vercel Cron calls; `kits.jobs.options.backend: "table"` runs without pgmq. Queue names are lowercase letters, digits and underscores. With a service-role Supabase client instead of SQL, it uses the `pgmq_public` RPCs (no dedupe or schedules).
 - `createIdempotency(postgres.admin).handle(request, handler)` for POST endpoints that clients retry.
 - `createInbox(postgres.admin, { source, secrets }).receive(request)` for webhooks; `process(handler)` later.
 - Times are `Temporal.Instant`: `EnqueueOptions.runAt`, `Job.enqueuedAt`, `Job.visibleUntil`, `InboxMessage.receivedAt` and webhook timestamps.
-- Schedule cleanup with pg_cron at a quiet hour: `better_supabase.purge_job_archive('<queue>')`, `purge_webhooks()`, `purge_audit_log()` and `purge_idempotency_keys()`. Only `service_role` can execute them.
+- Schedule cleanup with pg_cron at a quiet hour: `better_supabase.purge_job_archive('<queue>')`, `purge_webhooks()`, `purge_audit_log()`, `purge_idempotency_keys()`, `purge_rate_limits()`, `purge_outbox()`, `purge_notifications()` and `purge_webhook_deliveries()`, for the modules you installed. Only `service_role` can execute them.
+- Audit a table with `better_supabase.audit('public.t', redact => '{secret}', event_prefix => 't')`; record non-row events with `better_supabase.audit_event(event_type, ...)` and an `idempotency_key`. For per-tenant retention, write an `audit_retention(tenant)` SQL function or call `purgeAuditLog(sql, { retention })` from `better-supabase/jobs`.
+- For a "view as user" support mode, add the `support-sessions` SQL module, pass `support: supportSessions({ store: sqlSupportStore(postgres) })` to `createServer`, call `bs.startSupport({ targetUserId, reason })` and `bs.stopSupport()` from server actions, and show a banner with `useSupportSession()`. Sessions are read-only by default; grant admins the `support.start` platform permission.
+- For teams, add the `organizations` and `invitations` SQL modules and call them through `createOrgs({ transport: sqlTransport(postgres.asUser(claims)), events: betterSupabase.events, onInvite })` from `better-supabase/orgs`. Send the invitation email in `onInvite`, show `previewInvitation(token)` on the accept page, and switch with `orgs.switch(id)`, refreshing the session when it returns `refresh: true`. Errors carry codes such as `ORG_SLUG_TAKEN` in `hint`. Existing tables work with `mode: 'adopt'`.
+- For user profiles, add the `profiles` SQL module: sign-up creates the row from auth metadata with a unique username and mirrors the email; users update only the `updatable` columns. Adopt an existing table with `mode: 'adopt'` and `syncTrigger: false` when your own trigger creates profiles. Use `avatarBucket()` and `orgLogoBucket()` from `better-supabase/storage` for uploads; `policy: { access: { read, write } }` checks any bucket through the access contract.
+- For events other systems must see, add the `outbox` SQL module and write events with `emit_event(type, payload, subject, tenant, key)` inside the same transaction as the change (the kit modules emit theirs automatically). Relay them with `createOutbox(postgres.admin, { source }).relayRoute({ secret, consumers: { name: httpSink(url) } })` from `better-supabase/jobs` after `outbox.register(name, { types })`. Delivery is at least once; receivers deduplicate on the CloudEvent `id`.
+- For in-app notifications, add the `notifications` SQL module and send with `createNotifications({ transport: sqlTransport(postgres.asUser(claims)), types })` from `better-supabase/notifications`, where `types` maps each notification type to a Standard Schema for its data. Pass a `key` so retries don't notify twice. Show them with `useNotifications({ topic, load })` from `better-supabase/react`; the topic defaults to `notifications:{userId}`. For email or push, pass `channels` and call `notifications.deliver()` from a cron route with a service connection.
+- For webhooks to customers' endpoints, add the `webhooks-out` SQL module and publish with `createWebhooks({ transport: sqlTransport(postgres.admin) }).publish({ type, data, tenant, id })` from `better-supabase/webhooks`. Pass an `id` so retries don't send twice. Send with `webhooks.deliverRoute({ secret: process.env.CRON_SECRET })` from a cron route; deliveries are signed with Standard Webhooks and only go to public HTTPS URLs by default.
 
 Done when a failing job is retried and then archived after `maxAttempts`,
 a replayed webhook or POST doesn't run twice, and each kit table has a purge

package/skills/better-supabase-api/references/adapters.md

@@ -15,6 +15,7 @@ export const betterSupabase = defineSupabase(schema);
 ## Next.js
 
 ```ts title="src/lib/supabase/server.ts"
+import "server-only";
 import { createNext } from "better-supabase/next";
 
 import { betterSupabase } from "./index";
@@ -44,15 +45,15 @@ export const GET = bs.route(
 ## Hono
 
 ```ts title="src/server.ts"
-import { type HonoEnv, createHono } from "better-supabase/hono";
-import { Hono } from "hono";
+import { createHono } from "better-supabase/hono";
 
-import { type Functions, type Models, betterSupabase } from "./lib/supabase";
+import { betterSupabase } from "./lib/supabase";
 
 const bs = createHono(betterSupabase);
 
-const app = new Hono<HonoEnv<Models, Functions, unknown>>()
-  .onError(bs.onError)
+// bs.app() is new Hono<typeof bs.Env>() with bs.onError installed.
+const app = bs
+  .app()
   .use("/api/*", bs.middleware())
   .get("/api/me", (c) => c.json({ kind: c.var.auth.kind }))
   .route(
@@ -106,7 +107,7 @@ import { betterSupabase } from "../_shared/supabase.ts";
 const bs = createMcp(betterSupabase, {
   name: "crm",
   version: "0.1.0",
-  scopes: ["openid", "crm.read"],
+  advertisedScopes: ["openid", "crm.read"],
   allowedOrigins: ["https://claude.ai"],
   allowedHosts: ["crm.example.com", "localhost"],
   resourceDocumentation: "https://crm.example.com/docs/mcp",
@@ -126,6 +127,8 @@ const bs = createMcp(betterSupabase, {
 Deno.serve(bs.fetch);
 ```
 
-Tools run as the calling user, so RLS applies to every tool call. `scopes`
-on `createMcp` only advertises scopes; `authorize` refuses the call. A
+Tools run as the calling user, so RLS applies to every tool call.
+`advertisedScopes` only advertises scopes; `requiredScopes` refuses delegated
+tokens that lack one, and `authorize` refuses a single call. The session comes
+from the `Authorization` header only, never from a cookie. A
 `delegation` that is unset means the user's own token, which no scope limits.

package/skills/better-supabase-auth/SKILL.md

@@ -106,6 +106,9 @@ membership lasts until the next refresh. When that window matters:
 - Write policies that read the source of truth, for example
   `organization_id in (select better_supabase.member_org_ids())`, instead of
   the claim.
+- For signed-out, banned or deleted users, add the `sessions` SQL module and a
+  restrictive policy with `using ((select better_supabase.session_active()))`
+  on the tables that guard sensitive data.
 - After a change the user made themselves (joining an organization), call
   `supabase.auth.refreshSession()` in the browser.
 - In Next.js, drop the user's cached views with

package/skills/better-supabase-auth/references/permdock.md

@@ -26,29 +26,74 @@ the other.
   `hasEntitlement(session, ...)` works.
 - Run `permdock supabase inspect --out` before `sql add entitlements`. With
   `permdock.manifest.json` present, the module reads PermDock's
-  `member_<scope>_ids` helpers and doesn't add `tenant`. Set
-  `entitlements.permdock: { scope }` in `better-supabase.config.ts` for a
-  scope other than `organization`.
+  `member_<scope>_ids` helpers and doesn't add `tenant`. The scope is the
+  manifest's root scope (the `rls.scopes` entry without `within`); set
+  `entitlements.permdock: { scope }` in `better-supabase.config.ts` for
+  another one.
 - Name the same tenant claim on both sides. A non-default `claims.tenant` in
   `better-supabase.config.ts` must also be PermDock's `rls.tenantClaim` and
   go to `subjectFromSupabase` or `subjectFromSupabaseSession` as `{ tenant }`.
 - Validate claims with PermDock's schema: `betterSupabase.claims(supabaseClaims().extend(appClaims))`.
-- The helpers live in PermDock's `rls.schema`, which must equal the `schema`
-  option of buckets and topics in `permdock` mode.
+- The helpers live in PermDock's `rls.schema` (`permdock` by default). Buckets
+  and topics in `permdock` mode call them in `permdock` unless their `schema`
+  option names another schema; it must equal `rls.schema`.
+- Use the scope names the manifest declares (`organization`, not PermDock's
+  `tenant` alias): the helpers are named after them, and doctor reports a
+  key checked at another scope than its catalog entry.
+- The entitlements module needs PermDock's hook to fill `claims.features`
+  from `better_supabase.feature_claims`
+  (`supabase.hook.claims: { features: 'better_supabase.feature_claims' }`).
 - The `permdock` policy mode checks role and scope only. Use it only for
   permissions whose `rowConditions` is `false` in `permissions.catalog.json`.
+  A missing flag or a key the catalog doesn't list is unknown and refused;
+  regenerate the catalog with a current `permdock catalog`.
   Leave permissions with row conditions to the policies
   `permdock rls generate` writes; doctor reports BS214 and `permdock doctor`
   PD037 otherwise.
 - `permdock` mode compares ids as text, so a path or topic segment must be
   the id's lowercase form.
 - In MCP servers, narrow `tool.meta` with PermDock's `isPermission`, answer
-  `visible` with `mayUse` and `authorize` with `can`. `can` decides without
-  a row, so check row-conditioned permissions inside `run` or rely on RLS.
-- In Next.js, cache the permission snapshot with
-  `bs.cached({ tags: [snapshotTag(userId)], life: cacheLifeFor(snapshot) })`
-  and drop it with `bs.invalidateSession(userId, { tags: [snapshotTag(userId)] })`
-  when a role or plan changes.
+  `visible` with `mayUse` and `authorize` with `can`. A tool without a
+  PermDock permission in `meta` is denied: `visible` returns `false` and
+  `authorize` returns `{ allowed: false }`. Use `decide` instead of `can` to
+  put the denial reason in the refusal. `can` decides without a row, so check
+  row-conditioned permissions inside `run` or rely on RLS.
+- In oRPC and Hono, pass the adapter's auth state to PermDock:
+  `createPermDock(policy, { subject: ({ context }) => subjectFromSupabaseSession(context.auth) })`
+  from `permdock/orpc`, or `(c) => subjectFromSupabaseSession(c.get("auth"))`
+  from `permdock/hono`. Fail closed: export one builder that takes a
+  permission (`(permission) => authed.use(pd.protect(permission))`, or the
+  route helper `[bs.middleware(), pd.protect(permission)]` in Hono), and don't
+  install `bs.middleware()` app-wide, so a route without a permission has no
+  `db`.
+- In Next.js, cache the permission snapshot in a `'use cache: private'`
+  loader. The user id and the snapshot only exist after `bs.cached()`
+  returns, so pass it the static tags only, then tag and time the entry from
+  inside the loader with Next.js's `cacheTag` and `cacheLife`:
+
+  ```ts
+  import { cacheLife, cacheTag } from "next/cache";
+  import { snapshotFor } from "permdock";
+  import { cacheLifeFor, snapshotTag } from "permdock/next";
+  import { subjectFromSupabaseSession } from "permdock/supabase";
+
+  export async function loadSnapshot(orgId: string) {
+    "use cache: private";
+    const { session } = await bs.cached({ tags: [`org:${orgId}`] });
+    const snapshot = snapshotFor(policy, subjectFromSupabaseSession(session), {
+      tenant: orgId,
+    });
+    if (session.kind === "user") cacheTag(snapshotTag(session.user.id));
+    cacheLife(cacheLifeFor(snapshot));
+    return snapshot;
+  }
+  ```
+
+  `bs.cached()` already caps the stale time at the token's expiry, and Next.js
+  keeps the smaller `stale` of the two `cacheLife` calls. When a role or plan
+  changes, drop the user's entries and the snapshot with
+  `bs.invalidateSession(userId, { tags: [snapshotTag(userId)] })`.
+
 - Doctor BS405 measures `memberships` plus `attrs` against PermDock's 1 KB
   budget and the whole token against 2 KB; run `doctor --as <user id>`.
 

package/dist/cli/gen-D5cLCULx.js

@@ -1,2 +0,0 @@
-import { n as genCommand } from "./gen-Ccn_p90L.js";
-export { genCommand };

package/dist/cli/sql-D4VbqmXi.js

@@ -1,199 +0,0 @@
-import { r as defineCliCommand } from "./command-CK14fP91.js";
-import { r as writeIfChanged, t as display } from "./io-k41_z-jT.js";
-import { i as plain, r as painter } from "./style-C0NFdJRL.js";
-import { d as readSupabaseToml, f as schemaPaths, l as migrationCommand } from "./config-D9R0o1LH.js";
-import { c as readPermdock, l as fileDiff, o as permdockConfig, r as entitlementsMode, t as compiledReadSets } from "./read-sets-CMa29t9a.js";
-import { resolve } from "node:path";
-import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-import { SQL_MODULES, kitLayout, renderKit, resolveModules, sameKitFile } from "better-supabase/sql";
-//#region src/cli/commands/sql.ts
-const SQL_ARGS = {
-	action: {
-		type: "positional",
-		required: false,
-		description: "list (modules and whether they are installed), add <module...>, sync or print <module>"
-	},
-	check: {
-		type: "boolean",
-		description: "With sync: fail when a file is stale"
-	},
-	"tests-dir": {
-		type: "string",
-		description: "Where the pgtap module goes. Defaults to sql.testsDir",
-		valueHint: "dir"
-	},
-	"dry-run": {
-		type: "boolean",
-		description: "Show what would be written"
-	},
-	force: {
-		type: "boolean",
-		description: "Write tenant even though a permdock.config.ts is present"
-	}
-};
-const USAGE = "Run `better-supabase sql --help` for the actions.";
-/** Modules that fill a claim PermDock's hook also writes (`memberships`). */
-const PERMDOCK_OWNED = /* @__PURE__ */ new Set(["tenant"]);
-/** PermDock's helpers for the `entitlements` module; throws for a scope the manifest lacks. */
-async function permdockFor(config) {
-	const mode = entitlementsMode(config, await readPermdock(config.root, config.permdock));
-	switch (mode.kind) {
-		case "tenant": return;
-		case "permdock": return mode.permdock;
-		case "invalid": throw new TypeError(mode.problem);
-		default: return mode;
-	}
-}
-async function layout(config, args) {
-	return kitLayout(config, args["tests-dir"], [], await permdockFor(config));
-}
-/** The layout, with `config.readSets` compiled when `names` includes `read-sets`. */
-async function layoutFor(config, args, names) {
-	const permdock = await permdockFor(config);
-	const needsReadSets = resolveModules(names, { ...permdock ? { permdock } : {} }).some((module) => module.name === "read-sets");
-	return kitLayout(config, args["tests-dir"], needsReadSets ? await compiledReadSets(config) : [], permdock);
-}
-async function write(config, args, names, kit) {
-	const lines = [];
-	const dryRun = args["dry-run"] === true;
-	for (const file of renderKit(names, kit)) {
-		const path = resolve(config.root, file.path);
-		const shown = display(config.root, file.path);
-		if (dryRun) {
-			lines.push(`Would write ${shown} (${file.module})`);
-			continue;
-		}
-		const wrote = await writeIfChanged(path, file.contents);
-		lines.push(`${wrote ? "Wrote" : "Unchanged"} ${shown} (${file.module})`);
-	}
-	return lines;
-}
-/** A note when migra's `schema_paths` is set and misses kit files, which `supabase db diff` would then skip. */
-async function unlistedKitFiles(config, names, kit) {
-	const order = await schemaPaths(config.root, await readSupabaseToml(config.root));
-	if (!order.configured) return [];
-	const unlisted = new Set(order.unlisted);
-	const listed = new Set(order.files.filter((path) => !unlisted.has(path)));
-	const dir = `${config.sql.dir.replace(/\/$/, "")}/`;
-	const missing = renderKit(names, kit).map((file) => file.path).filter((path) => path.startsWith(dir) && !listed.has(path));
-	if (missing.length === 0) return [];
-	return [
-		"",
-		"supabase/config.toml sets [db.migrations] schema_paths, and no entry matches these files, so `supabase db diff` skips them.",
-		"Add them before the schemas that call their functions:",
-		...missing.map((path) => `  "./${path.startsWith("supabase/") ? path.slice(9) : path}",`)
-	];
-}
-async function runSql(config, args, paint = plain) {
-	const [action, ...names] = args._;
-	switch (action) {
-		case "list": {
-			const kit = await layout(config, args);
-			const files = new Map(renderKit(Object.keys(SQL_MODULES), kit).map((file) => [file.module, file.path]));
-			return {
-				code: 0,
-				output: `${Object.values(SQL_MODULES).map((module) => {
-					const path = files.get(module.name);
-					const installed = existsSync(resolve(config.root, path));
-					const tracked = config.sql.kit.includes(module.name);
-					const mark = installed ? tracked ? "●" : "○" : " ";
-					const requires = kit.permdock && module.permdockRequires ? module.permdockRequires : module.requires;
-					const needs = requires.length > 0 ? ` (needs ${requires.join(", ")})` : "";
-					return `${mark} ${module.name.padEnd(15)} ${module.description}${needs}`;
-				}).join("\n")}\n\n● installed and in sql.kit   ○ installed, not in sql.kit`
-			};
-		}
-		case "add": {
-			if (names.length === 0) return {
-				code: 2,
-				error: `Name at least one module.\n${USAGE}`
-			};
-			const unknown = names.filter((name) => !(name in SQL_MODULES));
-			if (unknown.length > 0) return {
-				code: 2,
-				error: `Unknown module ${unknown.join(", ")}. Available: ${Object.keys(SQL_MODULES).join(", ")}`
-			};
-			const permdock = permdockConfig(config.root);
-			const hookModules = names.filter((name) => PERMDOCK_OWNED.has(name));
-			if (permdock && hookModules.length > 0 && args.force !== true) return {
-				code: 1,
-				error: [
-					`${permdock} is present, so PermDock owns the access token hook and the memberships claim.`,
-					`${hookModules.join(" and ")} would add a second source for them. Use \`permdock supabase hook generate\` instead,`,
-					"or pass --force to write the modules anyway."
-				].join("\n")
-			};
-			const kit = await layoutFor(config, args, names);
-			const lines = await write(config, args, names, kit);
-			const pulledIn = resolveModules(names, kit).map((module) => module.name).filter((name) => PERMDOCK_OWNED.has(name) && !names.includes(name));
-			if (permdock && pulledIn.length > 0) lines.push("", `${pulledIn.join(" and ")} came along as a dependency: its memberships table backs has_org_role() and has_entitlement().`, `PermDock's hook still owns the memberships claim, so don't call better_supabase.membership_claims from a hook.`, "List better_supabase.memberships as a PermDock membership source if both should agree.");
-			const untracked = resolveModules(names, kit).map((module) => module.name).filter((name) => !config.sql.kit.includes(name));
-			if (untracked.length > 0) lines.push("", `Add them to your config so \`sql sync --check\` keeps them current:`, `  sql: { kit: [${[...config.sql.kit, ...untracked].map((name) => `'${name}'`).join(", ")}] }`);
-			if (args["dry-run"] !== true) lines.push(...await unlistedKitFiles(config, names, kit));
-			lines.push("", `Then create a migration: ${migrationCommand(await readSupabaseToml(config.root), "better_supabase_kit")}`);
-			return {
-				code: 0,
-				output: lines.join("\n")
-			};
-		}
-		case "sync": {
-			if (config.sql.kit.length === 0) return {
-				code: 0,
-				output: "sql.kit is empty; nothing to sync."
-			};
-			if (args.check !== true) return {
-				code: 0,
-				output: (await write(config, args, config.sql.kit, await layoutFor(config, args, config.sql.kit))).join("\n")
-			};
-			const stale = [];
-			const diffs = [];
-			for (const file of renderKit(config.sql.kit, await layoutFor(config, args, config.sql.kit))) {
-				const current = await readFile(resolve(config.root, file.path), "utf8").catch(() => void 0);
-				if (!sameKitFile(current, file.contents)) {
-					const shown = display(config.root, file.path);
-					stale.push(shown);
-					diffs.push(fileDiff(shown, current, file.contents, paint));
-				}
-			}
-			return stale.length === 0 ? {
-				code: 0,
-				output: "SQL kit files are up to date."
-			} : {
-				code: 1,
-				output: diffs.join("\n\n"),
-				error: `Out of date: ${stale.join(", ")}. Run \`better-supabase sql sync\`.`
-			};
-		}
-		case "print": {
-			const [name] = names;
-			const module = name ? SQL_MODULES[name] : void 0;
-			if (!module) return {
-				code: 2,
-				error: `Name one module: ${Object.keys(SQL_MODULES).join(", ")}`
-			};
-			return {
-				code: 0,
-				output: module.render ? module.render(config.claims, await layout(config, args)) : module.sql
-			};
-		}
-		case void 0: return {
-			code: 2,
-			error: `Name an action.\n${USAGE}`
-		};
-		default: return {
-			code: 2,
-			error: `Unknown sql action "${action}".\n${USAGE}`
-		};
-	}
-}
-const sqlCommand = defineCliCommand({
-	meta: {
-		name: "sql",
-		description: "Lists, adds, syncs and prints SQL kit modules"
-	},
-	args: SQL_ARGS,
-	run: (args, { config, io }) => runSql(config, args, painter(io.color))
-});
-//#endregion
-export { sqlCommand };