better-supabase 0.2.0 → 0.4.0

package/dist/cli/doctor-BOym3mbL.js

@@ -0,0 +1,2382 @@
+import { a as list, r as defineCliCommand } from "./command-CK14fP91.js";
+import { n as CliError } from "./errors-4v4DTtda.js";
+import { r as writeIfChanged } from "./io-k41_z-jT.js";
+import { i as plain, r as painter } from "./style-C0NFdJRL.js";
+import { t as VERSION } from "./version-5mW_8sY1.js";
+import { c as diffEngine, d as readSupabaseToml, f as schemaPaths, l as migrationCommand, p as tomlGet, s as stdinDatabaseUrl, u as pgFunctionHooks } from "./config-D9R0o1LH.js";
+import { a as parseHookMarker, c as readPermdock, i as parseGrantsMarker, s as permdockSource, t as compiledReadSets } from "./read-sets-CMa29t9a.js";
+import { t as byCodePoint } from "./compare-BmIWVEui.js";
+import { C as catalogOf, D as qualified, E as policyObject, O as tableObject, S as entitlementsKit, T as lineOf, c as openSource, d as snapshotFile, h as CACHE_DIR, o as loadSnapshot, r as renderFiles, s as managementTarget, w as exposed, x as PERMDOCK_RULES } from "./gen-Ccn_p90L.js";
+import { n as withSpinner } from "./prompts-BNcNfAve.js";
+import { t as connect } from "./db-DOBPt660.js";
+import { dirname, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { glob, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { kitLayout, renderKit, sameKitFile } from "better-supabase/sql";
+import { createHash } from "node:crypto";
+import { defineBucket, parseSize } from "better-supabase/storage";
+//#region src/cli/doctor/advisors.ts
+/**
+* splinter (https://github.com/supabase/splinter), the linter behind the
+* dashboard's Security and Performance Advisors. It has no license, so it is
+* downloaded at this commit and checked against the hash instead of bundled.
+*/
+const SPLINTER_COMMIT = "e74a9e36cb12258cb67d1464bc1cb196e9cd8446";
+const SPLINTER_SHA256 = "d8d558baad3e03832e521c527907fa50a9a172fabd899dd0f5c2504a5a0e9349";
+const SPLINTER_URL = `https://raw.githubusercontent.com/supabase/splinter/${SPLINTER_COMMIT}/splinter.sql`;
+function isLint(value) {
+	const lint = value;
+	return typeof lint === "object" && lint !== null && typeof lint.name === "string" && typeof lint.level === "string" && Array.isArray(lint.categories);
+}
+/** The hosted project's advisors (`GET /v1/projects/{ref}/advisors/{category}`). */
+function managementAdvisors(options) {
+	const base = (options.apiUrl ?? "https://api.supabase.com").replace(/\/$/, "");
+	const doFetch = options.fetch ?? fetch;
+	return {
+		describe: `project ${options.projectRef} advisors (Management API)`,
+		async lints(category) {
+			const url = `${base}/v1/projects/${encodeURIComponent(options.projectRef)}/advisors/${category}`;
+			const response = await doFetch(url, { headers: { authorization: `Bearer ${options.accessToken}` } });
+			const text = await response.text();
+			if (!response.ok) throw new Error(`Management API ${category} advisors failed (${response.status}): ${text.slice(0, 300)}`);
+			const body = JSON.parse(text);
+			if (!Array.isArray(body.lints)) throw new TypeError(`Management API ${category} advisors returned no "lints".`);
+			return body.lints.filter(isLint);
+		}
+	};
+}
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+/** Downloads (once) and verifies the pinned `splinter.sql`. */
+async function splinterSql(options) {
+	const file = resolve(options.cacheDir, `splinter-${SPLINTER_COMMIT}.sql`);
+	if (existsSync(file)) {
+		const cached = await readFile(file, "utf8");
+		if (sha256(cached) === SPLINTER_SHA256) return cached;
+	}
+	const response = await (options.fetch ?? fetch)(SPLINTER_URL);
+	if (!response.ok) throw new Error(`Downloading splinter.sql failed (${response.status}) from ${SPLINTER_URL}`);
+	const text = await response.text();
+	if (sha256(text) !== SPLINTER_SHA256) throw new Error(`splinter.sql from ${SPLINTER_URL} does not match the pinned hash; refusing to run it.`);
+	await mkdir(dirname(file), { recursive: true });
+	await writeFile(file, text);
+	return text;
+}
+/** `pg` returns one result per statement for a multi-statement query. */
+function lintRows(result) {
+	const results = Array.isArray(result) ? result : [result];
+	return results.find((entry) => entry.fields?.some((field) => field.name === "cache_key"))?.rows ?? results.at(-1)?.rows ?? [];
+}
+/**
+* Runs splinter against a database (local stack, `$DATABASE_URL` or `--db-url-stdin`) in a
+* read-only transaction that is rolled back.
+*/
+function splinterAdvisors(queryable, describe, options) {
+	let all;
+	const run = async () => {
+		const sql = await splinterSql(options);
+		return lintRows(await queryable.query(`begin read only;\n${sql}\n;\nrollback;`)).filter(isLint);
+	};
+	return {
+		describe: `${describe} (splinter ${SPLINTER_COMMIT.slice(0, 7)})`,
+		async lints(category) {
+			all ??= run();
+			const wanted = category.toUpperCase();
+			return (await all).filter((lint) => lint.categories.includes(wanted));
+		}
+	};
+}
+//#endregion
+//#region src/cli/doctor/live.ts
+/** Statements slower than this (ms, mean) with more calls than `SLOW_CALLS` are BS209. */
+const SLOW_MEAN_MS = 50;
+const SLOW_CALLS = 1e3;
+/** Rows `--explain` reads, like a `findMany()` under Supabase's default `max_rows`. */
+const EXPLAIN_LIMIT = 1e3;
+const escape$2 = (name) => name.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const ident = (name) => `"${name.replaceAll("\"", "\"\"")}"`;
+const literal = (text) => `'${text.replaceAll("'", "''")}'`;
+const errorText = (cause) => cause instanceof Error ? cause.message : String(cause);
+const oneLine = (query, max = 160) => {
+	const flat = query.replaceAll(/\s+/g, " ").trim();
+	return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+};
+const plural$1 = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+const megabytes = (bytes) => `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+/** The schema `pg_stat_statements` lives in, when the extension is installed. */
+async function statementsView(db) {
+	const [row] = await db.query(`select n.nspname as schema from pg_extension e join pg_namespace n on n.oid = e.extnamespace where e.extname = 'pg_stat_statements'`);
+	return row ? `${ident(row.schema)}.pg_stat_statements` : void 0;
+}
+/** The first exposed table a statement names, to locate it in the SQL files. */
+function tableIn(query, tables) {
+	return tables.find((table) => {
+		const schema = escape$2(table.schema);
+		const name = escape$2(table.name);
+		return new RegExp(`(?:"${schema}"|\\b${schema})\\.(?:"${name}"|${name}\\b)`).test(query);
+	});
+}
+const live = (context) => context.database;
+/**
+* Function calls and self time so far in this transaction. The view can
+* still hold unflushed counts from earlier transactions, so callers diff two
+* readings.
+*/
+async function functionTimes(db) {
+	const rows = await db.query(`select schemaname || '.' || funcname as name, calls, self_time from pg_stat_xact_user_functions`);
+	return new Map(rows.map((row) => [row.name, {
+		calls: Number(row.calls),
+		selfTime: Number(row.self_time)
+	}]));
+}
+/** Node types, timings and loops of an `EXPLAIN (ANALYZE, FORMAT JSON)` plan; never rows. */
+function summarizePlan(output) {
+	const nodes = [];
+	const perRowSubPlans = [];
+	let initPlans = 0;
+	const walk = (node) => {
+		const loops = node["Actual Loops"] ?? 1;
+		const ms = (node["Actual Total Time"] ?? 0).toFixed(2);
+		const on = node["Relation Name"] ? ` on ${node["Relation Name"]}` : "";
+		const sub = node["Subplan Name"] ? `${node["Subplan Name"]}: ` : "";
+		nodes.push(`${sub}${node["Node Type"]}${on} ${ms} ms ×${loops}`);
+		if (node["Parent Relationship"] === "InitPlan") initPlans += 1;
+		if (node["Parent Relationship"] === "SubPlan" && loops > 1) perRowSubPlans.push(`${sub}${node["Node Type"]}${on} ×${loops}`);
+		for (const child of node.Plans ?? []) walk(child);
+	};
+	walk(output.Plan);
+	return {
+		nodes,
+		initPlans,
+		perRowSubPlans,
+		executionMs: output["Execution Time"] ?? 0
+	};
+}
+const ROLE = /^[a-z_][a-z0-9_]*$/;
+async function explainTable(db, table, claims) {
+	const role = typeof claims["role"] === "string" ? claims["role"] : "anon";
+	if (!ROLE.test(role)) throw new Error(`Invalid role "${role}" in the claims`);
+	await db.query("begin");
+	try {
+		await db.query(`set local statement_timeout = '30s'`);
+		let tracked = true;
+		await db.query("savepoint bs_track");
+		try {
+			await db.query(`set local track_functions = 'all'`);
+			await db.query("release savepoint bs_track");
+		} catch {
+			tracked = false;
+			await db.query("rollback to savepoint bs_track");
+		}
+		await db.query(`select set_config('request.jwt.claims', ${literal(JSON.stringify(claims))}, true)`);
+		const before = tracked ? await functionTimes(db) : /* @__PURE__ */ new Map();
+		await db.query(`set local role ${ident(role)}`);
+		const [row] = await db.query(`explain (analyze, buffers, format json) select * from ${ident(table.schema)}.${ident(table.name)} limit ${EXPLAIN_LIMIT}`);
+		const raw = row?.["QUERY PLAN"];
+		const plan = typeof raw === "string" ? JSON.parse(raw) : raw;
+		if (!plan?.[0]) throw new Error("EXPLAIN returned no plan");
+		const functions = tracked ? [...await functionTimes(db)].map(([name, after]) => {
+			const start = before.get(name);
+			return {
+				name,
+				calls: after.calls - (start?.calls ?? 0),
+				selfTime: after.selfTime - (start?.selfTime ?? 0)
+			};
+		}).filter((fn) => fn.calls > 0).sort((a, b) => b.selfTime - a.selfTime) : void 0;
+		return {
+			summary: summarizePlan(plan[0]),
+			functions
+		};
+	} finally {
+		await db.query("rollback");
+	}
+}
+function resolveTable(context, name) {
+	return name.includes(".") ? catalogOf(context).tables.find((table) => qualified(table) === name) : exposed(context).find((table) => table.name === name);
+}
+const LIVE_RULES = [
+	{
+		code: "BS208",
+		severity: "warning",
+		title: "Queries spill to temporary files",
+		description: "Sorts and hashes that exceed `work_mem` write temporary files, which is slow. Reads `pg_stat_database` and, when installed, the top statements from `pg_stat_statements`.",
+		async check(context) {
+			const db = live(context);
+			if (!db || "skipped" in db) return [];
+			try {
+				const [stats] = await db.query(`select temp_files, temp_bytes, current_setting('work_mem') as work_mem from pg_stat_database where datname = current_database()`);
+				const files = Number(stats?.temp_files ?? 0);
+				if (files === 0) return [];
+				let top = "";
+				const view = await statementsView(db);
+				if (view) {
+					const statements = await db.query(`select query, temp_blks_written from ${view} where temp_blks_written > 0 order by temp_blks_written desc limit 5`).catch(() => []);
+					if (statements.length > 0) top = ` Top statements by temporary blocks written: ${statements.map((statement) => `${oneLine(statement.query, 100)} (${statement.temp_blks_written} blocks)`).join("; ")}.`;
+				}
+				return [{
+					message: `${files} temporary files (${megabytes(Number(stats?.temp_bytes ?? 0))}) since the statistics were reset; work_mem is ${stats?.work_mem}. Add indexes so large sorts go away, or raise work_mem for the role that runs them.${top}`,
+					target: "pg_stat_database:temp_files"
+				}];
+			} catch (cause) {
+				return [{
+					severity: "info",
+					message: `Could not read pg_stat_database (${db.describe}): ${errorText(cause)}`
+				}];
+			}
+		}
+	},
+	{
+		code: "BS209",
+		severity: "warning",
+		title: "Slow frequent statements",
+		description: `Statements from \`pg_stat_statements\` with a mean time above ${SLOW_MEAN_MS} ms and more than ${SLOW_CALLS} calls. Runs with \`--stats\`.`,
+		async check(context) {
+			if (!context.stats) return [];
+			const db = live(context);
+			if (!db) return [];
+			if ("skipped" in db) return [{
+				severity: "info",
+				message: `Skipped --stats: ${db.skipped}`
+			}];
+			try {
+				const view = await statementsView(db);
+				if (!view) return [{
+					severity: "info",
+					message: "pg_stat_statements is not installed, so --stats has nothing to read. Run `create extension pg_stat_statements with schema extensions;`."
+				}];
+				const statements = await db.query(`select queryid::text as queryid, query, calls, mean_exec_time from ${view} where calls > ${SLOW_CALLS} and mean_exec_time > ${SLOW_MEAN_MS} order by total_exec_time desc limit 20`);
+				const tables = exposed(context);
+				return statements.map((statement) => {
+					const table = tableIn(statement.query, tables);
+					return {
+						message: `${Number(statement.mean_exec_time).toFixed(1)} ms mean over ${statement.calls} calls: ${oneLine(statement.query)}`,
+						target: `pg_stat_statements:${statement.queryid}`,
+						...table ? { object: tableObject(table) } : {}
+					};
+				});
+			} catch (cause) {
+				return [{
+					severity: "info",
+					message: `Could not read pg_stat_statements (${db.describe}): ${errorText(cause)}`
+				}];
+			}
+		}
+	},
+	{
+		code: "BS212",
+		severity: "info",
+		title: "RLS plan for a table",
+		description: `\`--explain <tables>\` runs \`EXPLAIN (ANALYZE, BUFFERS)\` on \`select * from <table> limit ${EXPLAIN_LIMIT}\` as the given claims, in a transaction that is rolled back. It reports node types, timings and loops, never rows, and warns when a policy SubPlan runs once per row.`,
+		async check(context) {
+			const request = context.explain;
+			if (!request) return [];
+			const db = live(context);
+			if (!db || "skipped" in db || !db.session) return [{
+				severity: "warning",
+				message: `--explain needs a direct database connection (local stack, $DATABASE_URL or --db-url-stdin)${db && "skipped" in db ? `: ${db.skipped}` : "."}`
+			}];
+			const who = typeof request.claims["sub"] === "string" ? `${String(request.claims["role"] ?? "anon")} ${request.claims["sub"]}` : String(request.claims["role"] ?? "anon");
+			const findings = [];
+			for (const name of request.tables) {
+				const table = resolveTable(context, name);
+				if (!table) {
+					findings.push({
+						severity: "warning",
+						message: `--explain: no table "${name}" in the exposed schemas; qualify tables in other schemas, like better_supabase.memberships.`
+					});
+					continue;
+				}
+				try {
+					const { summary, functions } = await explainTable(db, table, request.claims);
+					const helpers = functions ? functions.length > 0 ? ` Function time: ${functions.map((fn) => {
+						const self = fn.selfTime;
+						const share = summary.executionMs > 0 ? Math.round(self / summary.executionMs * 100) : 0;
+						return `${fn.name} ${self.toFixed(2)} ms over ${plural$1(fn.calls, "call")} (${share}%)`;
+					}).join(", ")}.` : " No tracked function ran; inlined SQL functions are part of the plan." : " Function times need `track_functions`, which this role may not set; showing the plan only.";
+					const perRow = summary.perRowSubPlans.length > 0 ? ` Per-row SubPlans: ${summary.perRowSubPlans.join(", ")}; wrap the policy's function calls in \`(select ...)\` so they run once as an InitPlan.` : "";
+					findings.push({
+						...summary.perRowSubPlans.length > 0 ? { severity: "warning" } : {},
+						message: `${qualified(table)} as ${who}: ${summary.executionMs.toFixed(2)} ms, ${plural$1(summary.initPlans, "InitPlan")}. Plan: ${summary.nodes.join(" > ")}.${perRow}${helpers}`,
+						target: `${qualified(table)}:explain`,
+						object: tableObject(table)
+					});
+				} catch (cause) {
+					findings.push({
+						severity: "warning",
+						message: `--explain ${qualified(table)} failed: ${errorText(cause)}`,
+						target: `${qualified(table)}:explain`
+					});
+				}
+			}
+			return findings;
+		}
+	}
+];
+//#endregion
+//#region src/cli/doctor/hooks.ts
+/** Claims past this size make every request carry a large cookie and header. */
+const HOOK_CLAIMS_LIMIT = 2048;
+/** PermDock's default `supabase.hook.budget`, over `memberships` plus `attrs`. */
+const PERMDOCK_CLAIMS_LIMIT = 1024;
+/**
+* The BS405 limits. With PermDock, `doctor.claimsLimit` (else the manifest's
+* budget) is its budget for `memberships` plus `attrs` and the whole token
+* keeps 2048; without it, `doctor.claimsLimit` limits the whole token.
+*/
+function claimsLimits(context) {
+	const configured = context.config.doctor.claimsLimit;
+	return context.permdock ? {
+		token: HOOK_CLAIMS_LIMIT,
+		budget: configured ?? context.permdock.manifest?.budget ?? PERMDOCK_CLAIMS_LIMIT
+	} : {
+		token: configured ?? HOOK_CLAIMS_LIMIT,
+		budget: void 0
+	};
+}
+/** The kit function that fills PermDock's `memberships` claim. */
+const KIT_MEMBERSHIPS = /better_supabase\s*\.\s*membership_claims\b/i;
+const PERMDOCK_CALL = /\bpermdock\w*\s*\(|permdock\s*\./i;
+/** Only PermDock's generated hook sets this claim, so it marks that hook's body. */
+const PERMDOCK_HOOK = /'\{\s*(?:claims\s*,\s*)?memberships_truncated\s*\}'/i;
+const escapeRegExp = (text) => text.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** The claims PermDock's hook writes that a second writer would contradict. */
+function ownedClaims(tenant) {
+	return [
+		"roles",
+		"user_role",
+		"memberships",
+		tenant
+	];
+}
+const quotedName = (schema, name) => `(?:"?${escapeRegExp(schema)}"?\\s*\\.\\s*)?"?${escapeRegExp(name)}"?`;
+/** A SQL file that starts with PermDock's hook marker and creates `fn`. */
+function markerFileFor(context, fn) {
+	const creates = new RegExp(`create\\s+(?:or\\s+replace\\s+)?function\\s+${quotedName(fn.schema, fn.name)}\\s*\\(`, "i");
+	for (const file of context.sqlFiles ?? []) {
+		const marker = parseHookMarker(file.text);
+		if (marker && creates.test(file.text)) return marker;
+	}
+}
+/** Whether `fn` is the hook PermDock generated: by its manifest, its marker file or its body. */
+function isPermdockHook(context, fn) {
+	const hook = context.permdock?.manifest?.hook;
+	if (hook && hook.schema === fn.schema && hook.function === fn.name) return true;
+	if (markerFileFor(context, fn)) return true;
+	return fn.source !== void 0 && PERMDOCK_HOOK.test(fn.source);
+}
+/**
+* Extra claims PermDock's hook writes from `supabase.hook.claims`, by claim
+* name, with the function that fills each: from the manifest, else from the
+* hook marker's `claims=` list.
+*/
+function registeredClaims(context) {
+	const claims = /* @__PURE__ */ new Map();
+	for (const claim of context.permdock?.manifest?.claims ?? []) if (claim.source !== "permdock") claims.set(claim.name, claim.source);
+	if (claims.size > 0) return claims;
+	const owned = /* @__PURE__ */ new Set([
+		...ownedClaims(context.config.claims.tenant),
+		"memberships_truncated",
+		"attrs",
+		"authz_ver"
+	]);
+	for (const file of context.sqlFiles ?? []) for (const name of parseHookMarker(file.text)?.claims ?? []) if (!owned.has(name)) claims.set(name, void 0);
+	return claims;
+}
+/** Whether the hook body calls PermDock's generated hook (a wrapper around it). */
+function wrapsPermdockHook(context, source) {
+	const hook = context.permdock?.manifest?.hook;
+	return hook !== void 0 && new RegExp(`${quotedName(hook.schema, hook.function)}\\s*\\(`, "i").test(source);
+}
+/** Which of `claims` the hook body writes through `jsonb_set` or `jsonb_build_object`. */
+function writtenClaims(source, claims) {
+	return claims.filter((claim) => {
+		const name = escapeRegExp(claim);
+		return new RegExp(`jsonb_set\\s*\\([^;]*?'\\{\\s*(?:claims\\s*,\\s*)?${name}\\s*\\}'`, "i").test(source) || new RegExp(`jsonb_build_object\\s*\\([^;]*?'${name}'\\s*,`, "i").test(source);
+	});
+}
+const API_ROLES$1 = ["authenticated", "anon"];
+/** Hooks enabled in `config.toml`, matched with their introspected functions. */
+function configuredHooks(context) {
+	if (!context.configToml) return [];
+	const introspected = context.snapshot.extras.hooks ?? [];
+	return pgFunctionHooks(context.configToml.document).map((config) => ({
+		config,
+		extras: introspected.find((hook) => hook.hook === config.hook && hook.schema === config.schema && hook.name === config.name)
+	}));
+}
+function hookLocation(context, hook) {
+	if (!context.configToml) return void 0;
+	const line = lineOf(context.configToml.text, new RegExp(`^\\s*\\[auth\\.hook\\.${hook}\\]`));
+	return line ? {
+		file: context.configToml.path,
+		line
+	} : void 0;
+}
+const signatureOf = (fn) => `${fn.schema}.${fn.name}(${fn.signature})`;
+/** What is wrong with who may call a hook function, and the SQL that fixes it. */
+function grantProblems(fn) {
+	const problems = [];
+	const fix = [];
+	if (!fn.schemaUsage.includes("supabase_auth_admin")) {
+		problems.push(`supabase_auth_admin has no usage on schema ${fn.schema}`);
+		fix.push(`grant usage on schema ${fn.schema} to supabase_auth_admin;`);
+	}
+	if (!fn.execute.includes("supabase_auth_admin")) {
+		problems.push("supabase_auth_admin may not execute it");
+		fix.push(`grant execute on function ${signatureOf(fn)} to supabase_auth_admin;`);
+	}
+	const exposedTo = API_ROLES$1.filter((role) => fn.execute.includes(role));
+	if (exposedTo.length > 0 || fn.publicExecute) {
+		const roles = [...exposedTo, ...fn.publicExecute ? ["public"] : []];
+		problems.push(`${roles.join(", ")} may execute it, so any client can call it through the API`);
+		fix.push(`revoke execute on function ${signatureOf(fn)} from authenticated, anon, public;`);
+	}
+	return {
+		problems,
+		fix
+	};
+}
+/** The `-- permdock:grants v1` migration that grants `fn`, if any. */
+function grantsMigrationFor(context, fn) {
+	const grants = new RegExp(`grant\\s+execute\\s+on\\s+function\\s+${quotedName(fn.schema, fn.name)}\\s*\\(`, "i");
+	return (context.sqlFiles ?? []).find((file) => parseGrantsMarker(file.text) && grants.test(file.text))?.path;
+}
+const PERMDOCK_GRANTS_COMMAND = "permdock supabase hook generate --grants-out supabase/migrations/<timestamp>_permdock_hook_grants.sql";
+/** Configured hook functions whose grants are wrong (BS404, `doctor --fix-grants`). */
+function hookGrantProblems(context) {
+	return configuredHooks(context).flatMap(({ config, extras }) => (extras?.functions ?? []).flatMap((fn) => {
+		const { problems, fix } = grantProblems(fn);
+		if (problems.length === 0) return [];
+		const file = grantsMigrationFor(context, fn);
+		return [{
+			hook: config.hook,
+			fn,
+			problems,
+			fix: file ? {
+				kind: "migration",
+				file
+			} : isPermdockHook(context, fn) ? { kind: "permdock" } : {
+				kind: "sql",
+				sql: fix
+			}
+		}];
+	}));
+}
+/** The sentence that tells the reader how to apply `fix`. */
+function grantFixText(fix, engine) {
+	switch (fix.kind) {
+		case "sql": return engine === "pg-delta" ? `Add to the schema file that defines the function, then run \`supabase db schema declarative sync\` (\`doctor --fix-grants\` prints every block):\n${fix.sql.join("\n")}` : `Append to the migration \`supabase db diff\` wrote (\`doctor --fix-grants\` prints every block):\n${fix.sql.join("\n")}`;
+		case "permdock": return `It is PermDock's hook, so let PermDock write the grants: \`${PERMDOCK_GRANTS_COMMAND}\`.`;
+		case "migration": return `${fix.file} grants it, so the database is behind the migrations: apply them (\`supabase migration up\`).`;
+		default: return fix;
+	}
+}
+/** `doctor --fix-grants`: the SQL block for every BS404 problem, as one migration snippet. */
+function hookGrantBlock(problems, engine = "migra") {
+	if (problems.length === 0) return "-- Every configured Auth hook function has its grants.";
+	const lines = ["-- Auth hook grants (better-supabase doctor --fix-grants).", engine === "pg-delta" ? "-- Add this to the schema file that defines the function, then run `supabase db schema declarative sync`." : "-- `supabase db diff` does not carry function grants; append this to its migration."];
+	for (const { fn, hook, fix } of problems) {
+		const name = `${signatureOf(fn)} ([auth.hook.${hook}])`;
+		switch (fix.kind) {
+			case "sql":
+				lines.push("", `-- ${name}`, ...fix.sql);
+				break;
+			case "permdock":
+				lines.push("", `-- ${name} is PermDock's hook: ${PERMDOCK_GRANTS_COMMAND}`);
+				break;
+			case "migration":
+				lines.push("", `-- ${name}: ${fix.file} grants it; run \`supabase migration up\`.`);
+				break;
+			default: return fix;
+		}
+	}
+	return lines.join("\n");
+}
+const emptySearchPath = (fn) => {
+	const value = fn.settings["search_path"];
+	return value === "" || value === "\"\"" || value === "''";
+};
+async function hookClaimsSize(db, fn, userId) {
+	const call = `${ident(fn.schema)}.${ident(fn.name)}`;
+	await db.query("begin");
+	try {
+		await db.query(`set local statement_timeout = '10s'`);
+		const [user] = await db.query(`select set_config('better_supabase.hook_event', jsonb_build_object(
+        'user_id', u.id,
+        'authentication_method', 'password',
+        'claims', jsonb_build_object(
+          'aud', 'authenticated', 'role', 'authenticated', 'sub', u.id,
+          'email', coalesce(u.email, ''), 'phone', coalesce(u.phone, ''),
+          'app_metadata', coalesce(u.raw_app_meta_data, '{}'::jsonb),
+          'user_metadata', coalesce(u.raw_user_meta_data, '{}'::jsonb),
+          'aal', 'aal1', 'session_id', gen_random_uuid(),
+          'is_anonymous', coalesce(u.is_anonymous, false),
+          'iat', extract(epoch from now())::int8,
+          'exp', extract(epoch from now())::int8 + 3600
+        )
+      )::text, true) as event
+      from auth.users u where u.id = ${literal(userId)}::uuid`);
+		if (!user?.event) return void 0;
+		const [role] = await db.query(`select case when exists(select 1 from pg_roles where rolname = 'supabase_auth_admin')
+        then pg_has_role('supabase_auth_admin', 'member') else false end as member`);
+		if (role?.member) await db.query("set local role supabase_auth_admin");
+		const [row] = await db.query(`select octet_length(c::text) as bytes,
+        octet_length((c -> 'memberships')::text) as memberships,
+        octet_length((c -> 'attrs')::text) as attrs,
+        c ->> 'memberships_truncated' = 'true' as truncated
+      from (select ${call}(current_setting('better_supabase.hook_event')::jsonb) -> 'claims' as c) h`);
+		const memberships = Number(row?.memberships ?? 0);
+		return {
+			bytes: Number(row?.bytes ?? 0),
+			memberships,
+			budget: memberships + Number(row?.attrs ?? 0),
+			truncated: row?.truncated === true
+		};
+	} finally {
+		await db.query("rollback");
+	}
+}
+const HOOK_RULES = [
+	{
+		code: "BS404",
+		severity: "error",
+		title: "Auth hook function grants",
+		description: "Auth calls Postgres hook functions as `supabase_auth_admin`, which needs usage on the schema and execute on the function. Nobody else should be able to call them: a client calling the custom access token hook through the API sees what it adds for any user id.",
+		check: (context) => [...configuredHooks(context).flatMap(({ config, extras }) => {
+			if (!extras || extras.functions.length > 0) return [];
+			const location = hookLocation(context, config.hook);
+			return [{
+				message: `[auth.hook.${config.hook}] calls ${config.schema}.${config.name}, which does not exist. Sign-ins fail until it does.`,
+				target: `[auth.hook.${config.hook}]`,
+				...location ? { location } : {}
+			}];
+		}), ...hookGrantProblems(context).map(({ hook, fn, problems, fix }) => ({
+			message: `${signatureOf(fn)} ([auth.hook.${hook}]): ${problems.join("; ")}. ${grantFixText(fix, diffEngine(context.configToml))}`,
+			target: signatureOf(fn),
+			object: {
+				kind: "function",
+				schema: fn.schema,
+				name: fn.name
+			}
+		}))]
+	},
+	{
+		code: "BS405",
+		severity: "warning",
+		title: "Custom access token hook shape",
+		description: `Auth runs the custom access token hook on every sign-in and refresh. It should be \`stable\` with \`set search_path = ''\`, and the claims it returns end up in every request's cookie and Authorization header. With \`--as <user id>\` doctor calls it for that user in a transaction that is rolled back. It warns when the whole token's claims pass ${HOOK_CLAIMS_LIMIT} bytes (\`doctor.claimsLimit\` without PermDock). With a \`permdock.config.ts\` it also warns when \`memberships\` plus \`attrs\` pass PermDock's budget, ${PERMDOCK_CLAIMS_LIMIT} bytes or \`doctor.claimsLimit\`, measured with \`octet_length\` as PermDock's hook measures it.`,
+		async check(context) {
+			const findings = [];
+			const limits = claimsLimits(context);
+			for (const { config, extras } of configuredHooks(context)) {
+				if (config.hook !== "custom_access_token" || !extras) continue;
+				for (const fn of extras.functions) {
+					const object = {
+						kind: "function",
+						schema: fn.schema,
+						name: fn.name
+					};
+					const problems = [];
+					if (fn.volatility !== "stable") problems.push(`it is ${fn.volatility}; declare it \`stable\``);
+					if (!emptySearchPath(fn)) problems.push("it has no `set search_path = ''`; add it and qualify every table");
+					if (problems.length > 0) findings.push({
+						message: `${signatureOf(fn)}: ${problems.join("; ")}.`,
+						target: signatureOf(fn),
+						object
+					});
+					if (!context.hookUser) continue;
+					const db = context.database;
+					if (!db || "skipped" in db || !db.session) {
+						findings.push({
+							severity: "info",
+							message: `Measuring the hook's claims needs a direct database connection (local stack, $DATABASE_URL or --db-url-stdin)${db && "skipped" in db ? `: ${db.skipped}` : "."}`,
+							target: `${signatureOf(fn)}:claims`
+						});
+						continue;
+					}
+					try {
+						const size = await hookClaimsSize(db, fn, context.hookUser);
+						if (size === void 0) {
+							findings.push({
+								severity: "info",
+								message: `--as ${context.hookUser}: no such user in auth.users, so the hook was not called.`,
+								target: `${signatureOf(fn)}:claims`
+							});
+							continue;
+						}
+						if (limits.budget !== void 0 && size.budget > limits.budget) findings.push({
+							message: `${signatureOf(fn)} returns ${size.budget} bytes of memberships and attrs for ${context.hookUser}, over PermDock's budget of ${limits.budget} (memberships ${size.memberships}). Raise \`supabase.hook.budget\` and \`doctor.claimsLimit\` together, or move attrs out of the token.`,
+							target: `${signatureOf(fn)}:budget`,
+							object
+						});
+						if (size.bytes > limits.token) findings.push({
+							message: `${signatureOf(fn)} returns ${size.bytes} bytes of claims for ${context.hookUser} (limit ${limits.token}, memberships ${size.memberships}). Every request carries them twice (cookie and header); keep ids and roles in the token and look up the rest.`,
+							target: `${signatureOf(fn)}:claims`,
+							object
+						});
+						if (size.truncated) findings.push({
+							severity: "info",
+							message: `${signatureOf(fn)} sets memberships_truncated for ${context.hookUser}: the token lists only some memberships (${size.memberships} bytes). Server checks for this user need a database lookup (PermDock's claimsFirst falls back to one).`,
+							target: `${signatureOf(fn)}:truncated`,
+							object
+						});
+					} catch (cause) {
+						findings.push({
+							message: `Calling ${signatureOf(fn)} for ${context.hookUser} failed: ${errorText(cause)}`,
+							target: `${signatureOf(fn)}:claims`,
+							object
+						});
+					}
+				}
+			}
+			return findings;
+		}
+	},
+	{
+		code: "BS407",
+		severity: "error",
+		title: "Two authorization hooks",
+		description: "A `permdock.config.ts` or `permdock.manifest.json` (or a hook that calls PermDock's functions) means PermDock writes `user_role`, `roles`, `memberships` and the tenant claim (`claims.tenant`) into the token. A custom access token hook that also calls `better_supabase.membership_claims`, or writes one of those claims itself, gives them a second source that drifts from PermDock's. Generate the hook with `permdock supabase hook generate` and drop the extra writes. Functions registered in PermDock's `supabase.hook.claims` (such as `better_supabase.feature_claims` for `features`) are PermDock's hook's own sources and are not reported; a hook that wraps PermDock's and writes one of those claims again is.",
+		check: (context) => {
+			const project = context.permdock;
+			const findings = [];
+			if (project) {
+				findings.push(...project.problems.filter((problem) => problem.startsWith(project.manifestPath)).map((problem) => ({
+					severity: "info",
+					message: `Could not read PermDock's manifest: ${problem}`,
+					target: project.manifestPath
+				})));
+				if (project.config && !project.manifest && !project.problems.some((problem) => problem.startsWith(project.manifestPath))) findings.push({
+					severity: "info",
+					message: `${project.config} is present but ${project.manifestPath} is not, so doctor and the SQL kit can't see PermDock's hook, helpers and membership sources. Run \`permdock supabase inspect --out\`, and \`permdock supabase inspect --check\` in CI.`,
+					target: project.manifestPath
+				});
+			}
+			const registered = registeredClaims(context);
+			for (const { config, extras } of configuredHooks(context)) {
+				if (config.hook !== "custom_access_token" || !extras) continue;
+				for (const fn of extras.functions) {
+					if (fn.source === void 0 || isPermdockHook(context, fn)) continue;
+					const kit = KIT_MEMBERSHIPS.test(fn.source);
+					const wrapper = wrapsPermdockHook(context, fn.source);
+					const written = writtenClaims(fn.source, [...ownedClaims(context.config.claims.tenant), ...wrapper ? registered.keys() : []]);
+					if (!kit && written.length === 0) continue;
+					const permdock = project ? permdockSource(project) : PERMDOCK_CALL.test(fn.source) ? "the hook body" : void 0;
+					if (!permdock) continue;
+					const location = hookLocation(context, config.hook);
+					const what = [...kit ? ["calls better_supabase.membership_claims"] : [], ...written.length > 0 ? [`writes ${written.join(", ")}`] : []].join(" and ");
+					const extra = written.filter((claim) => registered.has(claim));
+					const sources = extra.map((claim) => {
+						const source = registered.get(claim);
+						return source ? `${claim} from ${source}` : claim;
+					}).join(", ");
+					findings.push({
+						message: `${signatureOf(fn)} ${what}, and ${permdock} says PermDock owns those claims${extra.length > 0 ? ` (its hook already writes ${sources} through supabase.hook.claims)` : ""}. Keep one source: run \`permdock supabase hook generate\` and remove these writes from your hook.`,
+						target: signatureOf(fn),
+						object: {
+							kind: "function",
+							schema: fn.schema,
+							name: fn.name
+						},
+						...location ? { location } : {}
+					});
+				}
+			}
+			return findings;
+		}
+	}
+];
+//#endregion
+//#region src/cli/doctor/rls.ts
+const escape$1 = (name) => name.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** `'it''s'` and other string literals, blanked so their text can't match. */
+const withoutStrings = (text) => text.replaceAll(/'(?:[^']|'')*'/g, "''");
+const functionName = (fn) => `${fn.schema}.${fn.name}`;
+const functionObject = (fn) => ({
+	kind: "function",
+	schema: fn.schema,
+	name: fn.name
+});
+/** The functions policies call, by `schema.name`; overloads share a key. */
+function functionsByName(context) {
+	const map = /* @__PURE__ */ new Map();
+	for (const fn of context.snapshot.extras.functions ?? []) {
+		const key = functionName(fn);
+		const list = map.get(key);
+		if (list) list.push(fn);
+		else map.set(key, [fn]);
+	}
+	return map;
+}
+/** Argument lists of every call to `schema.name(...)` in an expression. */
+function callArguments(expression, fn) {
+	if (!expression) return [];
+	const text = withoutStrings(expression);
+	const pattern = new RegExp(`(?<![\\w."])(?:"?${escape$1(fn.schema)}"?\\.)?"?${escape$1(fn.name)}"?\\s*\\(`, "g");
+	const calls = [];
+	for (const match of text.matchAll(pattern)) {
+		const start = match.index + match[0].length;
+		let depth = 1;
+		let end = start;
+		while (end < text.length && depth > 0) {
+			if (text[end] === "(") depth += 1;
+			else if (text[end] === ")") depth -= 1;
+			end += 1;
+		}
+		calls.push(text.slice(start, end - 1));
+	}
+	return calls;
+}
+/** The first column of `table` an argument list refers to, bare or as `table.column`. */
+function columnArgument(args, table) {
+	return table.columns.find((column) => new RegExp(`(?<![\\w."$:])(?:"?${escape$1(table.name)}"?\\.)?"?${escape$1(column.name)}"?(?![\\w"(.$])`).test(args))?.name;
+}
+const expressions = (policy) => [policy.using, policy.check];
+/**
+* Why Postgres can't inline `fn` into the query that calls it, or
+* `undefined` when it can: only `language sql` functions that are not
+* volatile, not security definer and have no `set` options are inlined.
+*/
+function notInlinable(fn) {
+	if (fn.language !== "sql") return `a ${fn.language} function`;
+	if (fn.volatility === "volatile") return "a volatile function";
+	if (fn.securityDefiner) return "a security definer function";
+	const settings = Object.keys(fn.settings);
+	if (settings.length > 0) return `a function with \`set ${settings.join(", ")}\``;
+}
+const rlsTables = (context) => exposed(context).filter((table) => table.rls);
+const COMMANDS$1 = [
+	"select",
+	"insert",
+	"update",
+	"delete"
+];
+/** Policies apply to every role when they list `public` or none. */
+const appliesTo = (policy, role) => policy.roles.length === 0 || policy.roles.includes("public") || policy.roles.includes(role);
+/** Commands and roles that more than one permissive policy of the table covers. */
+function permissiveOverlaps(table) {
+	const permissive = table.policies.filter((policy) => policy.permissive);
+	const roles = /* @__PURE__ */ new Set();
+	for (const policy of permissive) {
+		const named = policy.roles.filter((role) => role !== "public");
+		if (named.length < policy.roles.length || policy.roles.length === 0) {
+			roles.add("anon");
+			roles.add("authenticated");
+		}
+		for (const role of named) roles.add(role);
+	}
+	const overlaps = [];
+	for (const command of COMMANDS$1) for (const role of [...roles].sort()) {
+		const policies = permissive.filter((policy) => (policy.command === "all" || policy.command === command) && appliesTo(policy, role)).map((policy) => policy.name);
+		if (policies.length > 1) overlaps.push({
+			command,
+			role,
+			policies
+		});
+	}
+	return overlaps;
+}
+const WRITES = ["insert", "update"];
+const API_ROLES = ["anon", "authenticated"];
+const NOT_ALIAS = /* @__PURE__ */ new Set([
+	"where",
+	"join",
+	"inner",
+	"left",
+	"right",
+	"full",
+	"cross",
+	"on",
+	"using",
+	"group",
+	"order",
+	"limit",
+	"union",
+	"natural",
+	"lateral",
+	"as"
+]);
+/** The body of `schema.name` from the snapshot, else from the first SQL file that creates it. */
+function functionBody(context, schema, name) {
+	const introspected = context.snapshot.generator.functions.find((fn) => fn.schema === schema && fn.name === name && fn.definition)?.definition;
+	if (introspected) return introspected;
+	const creates = new RegExp(`create\\s+(?:or\\s+replace\\s+)?function\\s+(?:"?${escape$1(schema)}"?\\.)?"?${escape$1(name)}"?\\s*\\([\\s\\S]*?\\bas\\s+(\\$\\w*\\$)([\\s\\S]*?)\\1`, "i");
+	for (const file of context.sqlFiles ?? []) {
+		const match = creates.exec(file.text);
+		if (match) return match[2];
+	}
+}
+const helpersByContext = /* @__PURE__ */ new WeakMap();
+/** The functions policies call, and the functions those call, with their bodies. */
+function policyHelpers(context) {
+	let helpers = helpersByContext.get(context);
+	if (!helpers) {
+		helpers = findPolicyHelpers(context);
+		helpersByContext.set(context, helpers);
+	}
+	return helpers;
+}
+function findPolicyHelpers(context) {
+	const known = context.snapshot.generator.functions;
+	const queue = catalogOf(context).tables.flatMap((table) => table.policies.flatMap((policy) => policy.functions ?? []));
+	const bodies = /* @__PURE__ */ new Map();
+	while (queue.length > 0) {
+		const key = queue.pop();
+		if (bodies.has(key)) continue;
+		const dot = key.indexOf(".");
+		const body = functionBody(context, key.slice(0, dot), key.slice(dot + 1));
+		if (!body) continue;
+		const text = withoutStrings(body);
+		bodies.set(key, text);
+		for (const fn of known) {
+			const called = `${fn.schema}.${fn.name}`;
+			if (!bodies.has(called) && callArguments(text, fn).length > 0) queue.push(called);
+		}
+	}
+	return bodies;
+}
+/** Tables a function body reads (`from` and `join`), with the names it refers to them by. */
+function readTables(body, tables) {
+	const found = /* @__PURE__ */ new Map();
+	for (const match of body.matchAll(/\b(?:from|join)\s+(?:"?(\w+)"?\s*\.\s*)?"?(\w+)"?(?:\s+(?:as\s+)?"?(\w+)"?)?/gi)) {
+		const [, schema, name, alias] = match;
+		const table = tables.find((t) => t.name === name && t.schema === schema) ?? (schema ? void 0 : tables.find((t) => t.name === name && t.schema === "public") ?? tables.find((t) => t.name === name));
+		if (!table) continue;
+		const names = found.get(table) ?? /* @__PURE__ */ new Set([table.name]);
+		if (alias && !NOT_ALIAS.has(alias.toLowerCase())) names.add(alias);
+		found.set(table, names);
+	}
+	return [...found].map(([table, names]) => ({
+		table,
+		names: [...names]
+	}));
+}
+/**
+* Columns that decide who may read other rows, by `schema.table`: the
+* columns of the tables policy helpers read that their bodies mention
+* (qualified, or bare when the body reads one table), and the manifest's
+* `decidingColumns`.
+*/
+function grantColumns(context) {
+	const tables = catalogOf(context).tables;
+	const columns = /* @__PURE__ */ new Map();
+	const entry = (table, column) => {
+		const byColumn = columns.get(table) ?? /* @__PURE__ */ new Map();
+		columns.set(table, byColumn);
+		const existing = byColumn.get(column);
+		if (existing) return existing;
+		const created = {
+			helpers: /* @__PURE__ */ new Set(),
+			permdock: false
+		};
+		byColumn.set(column, created);
+		return created;
+	};
+	for (const [helper, body] of policyHelpers(context)) {
+		const read = readTables(body, tables);
+		for (const { table, names } of read) for (const column of table.columns) {
+			const col = `"?${escape$1(column.name)}"?(?![\\w"(])`;
+			const qualifiedColumn = new RegExp(`(?<![\\w"])(?:${names.map((name) => `"?${escape$1(name)}"?`).join("|")})\\s*\\.\\s*${col}`, "i");
+			const bare = new RegExp(`(?<![\\w."])${col}`, "i");
+			if (qualifiedColumn.test(body) || read.length === 1 && bare.test(body)) entry(qualified(table), column.name).helpers.add(helper);
+		}
+	}
+	for (const deciding of context.permdock?.manifest?.decidingColumns ?? []) {
+		const dot = deciding.lastIndexOf(".");
+		if (dot > 0) entry(deciding.slice(0, dot), deciding.slice(dot + 1)).permdock = true;
+	}
+	return columns;
+}
+/** Whether `role` may run `command` on rows of `table` at all: no RLS, or a permissive policy for it. */
+const policyAllows = (table, command, role) => !table.rls || table.policies.some((policy) => policy.permissive && (policy.command === "all" || policy.command === command) && appliesTo(policy, role));
+/** The grant columns `role` may write with `command`, through a table-level or a column-level grant. */
+function writableColumns(table, columns, command, role) {
+	if (!policyAllows(table, command, role)) return [];
+	const privilege = command.toUpperCase();
+	if (table.grants.some((grant) => grant.role === role && grant.privileges.includes(privilege))) return [...columns];
+	return columns.filter((column) => (table.columnGrants ?? []).some((grant) => grant.role === role && grant.column === column && grant.privileges.includes(privilege)));
+}
+/** PostgREST's default for `db-hoisted-tx-settings`. */
+const DEFAULT_HOISTED = [
+	"statement_timeout",
+	"plan_filter.statement_cost_limit",
+	"default_transaction_isolation"
+];
+const TIMEOUT_ROLES = [
+	"anon",
+	"authenticated",
+	"authenticator"
+];
+const RLS_RULES = [
+	{
+		code: "BS205",
+		severity: "warning",
+		title: "Policy calls a slow function once per row",
+		description: "A policy passes a column of the row to a function Postgres cannot inline: plpgsql, volatile, security definer, or with a `set` option such as `search_path`. It runs once for every row the query reads.",
+		check: (context) => {
+			const functions = functionsByName(context);
+			return rlsTables(context).flatMap((table) => table.policies.flatMap((policy) => {
+				for (const name of policy.functions ?? []) {
+					const slow = functions.get(name)?.find((fn) => notInlinable(fn) !== void 0);
+					if (!slow) continue;
+					const column = expressions(policy).flatMap((expression) => callArguments(expression, slow)).map((args) => columnArgument(args, table)).find((found) => found !== void 0);
+					if (!column) continue;
+					const fix = slow.securityDefiner || Object.keys(slow.settings).length > 0 ? "" : `, or make it \`language sql stable\` so Postgres inlines it`;
+					return [{
+						message: `Policy "${policy.name}" on ${qualified(table)} calls ${name}(${column}), ${notInlinable(slow)}, with a column of the row, so it runs once per row. Have a helper return the allowed values once and compare: \`${column} in (select <helper>())\`${fix}.`,
+						target: `${qualified(table)}.${policy.name}`,
+						object: policyObject(table, policy)
+					}];
+				}
+				return [];
+			}));
+		}
+	},
+	{
+		code: "BS206",
+		severity: "warning",
+		title: "Security definer policy helper that cannot be inlined",
+		description: "A security definer function is used in many policies. Postgres never inlines a security definer function, so a call that takes a column of the row runs once per row. Wrapped in `(select ...)`, or returning a set the policy compares with `in (select ...)`, it runs once per statement.",
+		check: (context) => {
+			const limit = context.config.doctor.policyHelperLimit;
+			const functions = functionsByName(context);
+			const uses = /* @__PURE__ */ new Map();
+			for (const table of rlsTables(context)) for (const policy of table.policies) for (const name of policy.functions ?? []) {
+				const list = uses.get(name) ?? [];
+				list.push(`${qualified(table)}.${policy.name}`);
+				uses.set(name, list);
+			}
+			return [...uses].flatMap(([name, policies]) => {
+				if (policies.length <= limit) return [];
+				const fn = functions.get(name)?.find((candidate) => candidate.securityDefiner);
+				if (!fn) return [];
+				const shown = policies.slice(0, 5).join(", ");
+				const more = policies.length > 5 ? ` and ${policies.length - 5} more` : "";
+				return [{
+					message: `${name} is a security definer ${fn.language} function used in ${policies.length} policies (${shown}${more}; the limit is ${limit}). Postgres can't inline it, so call it as \`(select ${name}(...))\` when its arguments don't come from the row, or return the allowed ids as a set and compare with \`column in (select ${name}())\`, so it runs once per statement.`,
+					target: name,
+					object: functionObject(fn)
+				}];
+			});
+		}
+	},
+	{
+		code: "BS207",
+		severity: "warning",
+		title: "Several permissive policies for one command and role",
+		description: "Postgres evaluates every permissive policy that applies and ORs them, so each extra policy adds its cost to every row. Merge them into one policy per command and role. This replaces splinter's `multiple_permissive_policies` lint for the same table.",
+		check: (context) => rlsTables(context).flatMap((table) => {
+			const overlaps = permissiveOverlaps(table);
+			if (overlaps.length === 0) return [];
+			const first = table.policies.find((policy) => policy.name === overlaps[0].policies[0]);
+			const list = overlaps.map((overlap) => `${overlap.command} for ${overlap.role}: ${overlap.policies.join(", ")}`).join("; ");
+			return [{
+				message: `${qualified(table)} has several permissive policies per command and role (${list}). Postgres runs all of them for every row; merge each group into one policy.`,
+				target: qualified(table),
+				object: policyObject(table, first)
+			}];
+		})
+	},
+	{
+		code: "BS213",
+		severity: "warning",
+		title: "API roles can write the columns that grant access",
+		description: "RLS helpers decide access from columns such as `memberships.user_id`, `memberships.role` or `contacts.customer_id`, and PermDock's manifest lists them as `decidingColumns`. When `anon` or `authenticated` may insert or update one of them, and a policy lets them write the row, a user can grant themselves access. A table-level grant counts even after a column-level revoke.",
+		check: (context) => {
+			const tables = new Map(catalogOf(context).tables.map((table) => [qualified(table), table]));
+			return [...grantColumns(context)].flatMap(([name, byColumn]) => {
+				const table = tables.get(name);
+				if (!table) return [];
+				const columns = table.columns.map((column) => column.name).filter((column) => byColumn.has(column)).sort();
+				const writes = [];
+				const fix = [];
+				for (const role of API_ROLES) {
+					const tableLevel = [];
+					for (const command of WRITES) {
+						const writable = writableColumns(table, columns, command, role);
+						if (writable.length === 0) continue;
+						writes.push(`${role} may ${command} ${writable.join(", ")}`);
+						if (table.grants.some((grant) => grant.role === role && grant.privileges.includes(command.toUpperCase()))) tableLevel.push(command);
+						else fix.push(`revoke ${command} (${writable.join(", ")}) on ${name} from ${role};`);
+					}
+					if (tableLevel.length === 0) continue;
+					fix.push(`revoke ${tableLevel.join(", ")} on ${name} from ${role};`);
+					const rest = table.columns.map((column) => column.name).filter((column) => !byColumn.has(column));
+					if (rest.length > 0) fix.push(`grant ${tableLevel.map((command) => `${command} (${rest.join(", ")})`).join(", ")} on ${name} to ${role};`);
+				}
+				if (writes.length === 0) return [];
+				const helpers = [...new Set(columns.flatMap((column) => [...byColumn.get(column).helpers]))].sort();
+				const permdock = columns.filter((column) => byColumn.get(column).permdock);
+				const readers = [...helpers.length > 0 ? [`${helpers.join(", ")} read${helpers.length === 1 ? "s" : ""} them to decide access`] : [], ...permdock.length > 0 ? [`PermDock's manifest lists ${permdock.join(", ")} as deciding columns, which PD028 protects`] : []].join(", and ");
+				return [{
+					message: `${name}: ${writes.join("; ")}. ${readers}, so a user who writes them can grant themselves access. Revoke the columns and grant the rest:\n${fix.join("\n")}`,
+					target: name,
+					object: tableObject(table)
+				}];
+			});
+		}
+	},
+	{
+		code: "BS211",
+		severity: "info",
+		title: "Statement timeouts for the Data API roles",
+		description: "PostgREST switches to `anon` or `authenticated` for each request, so their `statement_timeout` limits Data API queries. A function's own `set statement_timeout` only applies when PostgREST hoists it (`pgrst.db_hoisted_tx_settings`). `idle_in_transaction_session_timeout` ends sessions that leave a transaction open; it applies to the role a connection logs in as.",
+		check: (context) => {
+			const settings = context.snapshot.extras.roleSettings;
+			if (!settings) return [];
+			const values = (setting) => TIMEOUT_ROLES.map((role) => `${role} ${settings[role]?.[setting] ?? "not set"}`).join(", ");
+			const findings = [{
+				message: `statement_timeout: ${values("statement_timeout")}. idle_in_transaction_session_timeout: ${values("idle_in_transaction_session_timeout")}. Unset roles use the database default.`,
+				target: "roles:statement_timeout"
+			}];
+			const configured = settings["authenticator"]?.["pgrst.db_hoisted_tx_settings"];
+			if ((configured ? configured.split(",").map((setting) => setting.trim()) : DEFAULT_HOISTED).includes("statement_timeout")) return findings;
+			for (const fn of context.snapshot.extras.functions ?? []) {
+				const timeout = fn.settings["statement_timeout"];
+				if (!timeout || !context.config.schemas.includes(fn.schema)) continue;
+				findings.push({
+					severity: "warning",
+					message: `${functionName(fn)}(${fn.signature}) sets statement_timeout = ${timeout}, but pgrst.db_hoisted_tx_settings (${configured}) leaves it out, so the setting doesn't limit the RPC. Add statement_timeout to it, or set the timeout on the role.`,
+					target: `${functionName(fn)}:statement_timeout`,
+					object: functionObject(fn)
+				});
+			}
+			return findings;
+		}
+	}
+];
+//#endregion
+//#region src/cli/doctor/policies.ts
+const AUTH_ROLE = /\bauth"?\s*\.\s*"?role"?\s*\(\s*\)/i;
+/** A check of who is calling: the JWT, the user id, or the session role. */
+const CALLER_CHECK = /\bauth"?\s*\.\s*"?(?:uid|jwt)"?\s*\(|request\.jwt|\b(?:current_user|session_user|current_role)\b|has_org_role|member_org_ids/i;
+const USER_METADATA = /\buser_metadata\b/i;
+/** Privileges an API role never needs on a table. */
+const NEEDLESS = [
+	"TRUNCATE",
+	"REFERENCES",
+	"TRIGGER"
+];
+const policyText = (policy) => withoutStrings(`${policy.using ?? ""} ${policy.check ?? ""}`);
+/** A permissive policy lets `role` run `command` on the table. */
+const allows = (table, command, role) => table.policies.some((policy) => policy.permissive && (policy.command === "all" || policy.command === command) && appliesTo(policy, role));
+/** Policy commands on `storage.objects` the SQL files create, by policy name. */
+function storagePolicies(context) {
+	const commands = /* @__PURE__ */ new Map();
+	const pattern = /create\s+policy\s+("(?:[^"]|"")+"|\S+)\s+on\s+"?storage"?\s*\.\s*"?objects"?\b([^;]*)/gi;
+	for (const file of context.sqlFiles ?? []) for (const match of withoutStrings(file.text).matchAll(pattern)) {
+		const name = match[1];
+		if (commands.has(name)) continue;
+		const command = /\bfor\s+(select|insert|update|delete|all)\b/i.exec(match[2])?.[1];
+		commands.set(name, command?.toLowerCase() ?? "all");
+	}
+	return commands;
+}
+const POLICY_RULES = [
+	{
+		code: "BS109",
+		severity: "warning",
+		title: "auth.role() in a policy or function",
+		description: "Supabase deprecated `auth.role()`. Scope the policy with `to authenticated`, or read the claim with `(select auth.jwt() ->> 'role')`.",
+		check: (context) => {
+			const findings = [];
+			for (const table of catalogOf(context).tables) for (const policy of table.policies) {
+				if (!AUTH_ROLE.test(policyText(policy))) continue;
+				findings.push({
+					message: `Policy "${policy.name}" on ${qualified(table)} calls auth.role(), which Supabase deprecated. Use \`to authenticated\` on the policy, or \`(select auth.jwt() ->> 'role')\`.`,
+					target: `${qualified(table)}.${policy.name}`,
+					object: policyObject(table, policy)
+				});
+			}
+			const bodies = new Map(policyHelpers(context));
+			for (const fn of context.snapshot.generator.functions) {
+				if (!context.config.schemas.includes(fn.schema) || !fn.definition) continue;
+				bodies.set(`${fn.schema}.${fn.name}`, withoutStrings(fn.definition));
+			}
+			for (const [name, body] of bodies) {
+				if (!AUTH_ROLE.test(body)) continue;
+				const dot = name.indexOf(".");
+				findings.push({
+					message: `${name} calls auth.role(), which Supabase deprecated. Read \`auth.jwt() ->> 'role'\` instead.`,
+					target: name,
+					object: {
+						kind: "function",
+						schema: name.slice(0, dot),
+						name: name.slice(dot + 1)
+					}
+				});
+			}
+			return findings;
+		}
+	},
+	{
+		code: "BS110",
+		severity: "warning",
+		title: "Update policy without a select policy or with check",
+		description: "An update has to find the rows first, so without a select policy for the same role it matches no rows and reports success. Without `with check`, Postgres checks the new row against `using`, which hides whether moving a row to another owner or tenant is allowed.",
+		check: (context) => exposed(context).flatMap((table) => {
+			if (!table.rls) return [];
+			return table.policies.flatMap((policy) => {
+				if (!policy.permissive || policy.command !== "update") return [];
+				const blind = (policy.roles.length === 0 || policy.roles.includes("public") ? ["anon", "authenticated"] : policy.roles).filter((role) => !allows(table, "select", role));
+				const target = `${qualified(table)}.${policy.name}`;
+				if (blind.length > 0) return [{
+					message: `Policy "${policy.name}" on ${qualified(table)} allows update for ${blind.join(", ")}, but no select policy does, so updates match no rows without an error. Add a select policy for ${blind.join(", ")}.`,
+					target,
+					object: policyObject(table, policy)
+				}];
+				if (policy.check !== null) return [];
+				return [{
+					severity: "info",
+					message: `Policy "${policy.name}" on ${qualified(table)} has no \`with check\`, so Postgres checks updated rows against \`using\`. State the rule for the new row with \`with check (...)\`.`,
+					target,
+					object: policyObject(table, policy)
+				}];
+			});
+		})
+	},
+	{
+		code: "BS111",
+		severity: "warning",
+		title: "API roles hold privileges they don't use",
+		description: "`anon` and `authenticated` never need `truncate`, `references` or `trigger`, and `truncate` skips RLS. A grant to `anon` on a table no policy opens to it does nothing except list the table in the Data API schema.",
+		check: (context) => exposed(context).flatMap((table) => {
+			if (table.kind !== "table") return [];
+			const findings = [];
+			for (const role of ["anon", "authenticated"]) {
+				const privileges = new Set(table.grants.filter((grant) => grant.role === role).flatMap((grant) => grant.privileges));
+				const needless = NEEDLESS.filter((privilege) => privileges.has(privilege));
+				if (needless.length > 0) findings.push({
+					message: `${role} has ${needless.join(", ").toLowerCase()} on ${qualified(table)}. \`truncate\` bypasses RLS. Run \`revoke ${needless.join(", ").toLowerCase()} on table ${qualified(table)} from ${role};\`.`,
+					target: `${qualified(table)}:${role}`,
+					object: tableObject(table)
+				});
+				if (role !== "anon" || !table.rls) continue;
+				const unused = COMMANDS$1.filter((command) => privileges.has(command.toUpperCase()) && !allows(table, command, role));
+				if (unused.length > 0) findings.push({
+					severity: "info",
+					message: `anon has ${unused.join(", ")} on ${qualified(table)}, but no policy allows it for anon, so the grant only lists the table in the Data API schema. Run \`revoke ${unused.join(", ")} on table ${qualified(table)} from anon;\`.`,
+					target: `${qualified(table)}:anon:unused`,
+					object: tableObject(table)
+				});
+			}
+			return findings;
+		})
+	},
+	{
+		code: "BS112",
+		severity: "warning",
+		title: "Exposed security definer function that doesn't check the caller",
+		description: "A `security definer` function in an exposed schema runs as its owner, past RLS, and the Data API serves it at `/rpc`. When anon or authenticated may execute it and its body never reads `auth.uid()` or `auth.jwt()`, any caller gets the owner's access. Check the caller, revoke `execute`, or move it to a schema the API doesn't expose.",
+		check: (context) => (context.snapshot.extras.functions ?? []).flatMap((fn) => {
+			if (!fn.securityDefiner || !context.config.schemas.includes(fn.schema)) return [];
+			const callers = fn.execute ?? [];
+			if (callers.length === 0) return [];
+			const body = functionBody(context, fn.schema, fn.name);
+			if (body === void 0 || CALLER_CHECK.test(body)) return [];
+			return [{
+				message: `${fn.schema}.${fn.name}(${fn.signature}) is security definer, ${callers.join(" and ")} may execute it through /rpc, and it never checks auth.uid() or auth.jwt(). Check the caller, run \`revoke execute on function ${fn.schema}.${fn.name}(${fn.signature}) from ${callers.join(", ")};\`, or move it to a private schema.`,
+				target: `${fn.schema}.${fn.name}`,
+				object: functionObject(fn)
+			}];
+		})
+	},
+	{
+		code: "BS113",
+		severity: "info",
+		title: "Storage upload policy without the upsert policies",
+		description: "An upload with `upsert: true` (`x-upsert`) needs `select` and `update` policies on `storage.objects` besides `insert`; without them, replacing an existing file fails with a 403. Doctor reads the policies in `supabase/schemas` and the migrations.",
+		check: (context) => {
+			const commands = new Set(storagePolicies(context).values());
+			if (!commands.has("insert") || commands.has("all")) return [];
+			const missing = ["select", "update"].filter((command) => !commands.has(command));
+			if (missing.length === 0) return [];
+			return [{
+				message: `storage.objects has an insert policy but no ${missing.join(" or ")} policy, so uploads with \`upsert: true\` fail with 403 when the file exists. Add ${missing.join(" and ")} policies with the same bucket and path check.`,
+				target: "storage.objects"
+			}];
+		}
+	},
+	{
+		code: "BS114",
+		severity: "error",
+		title: "Policy helper reads user_metadata",
+		description: "Users can change their own `raw_user_meta_data` with `auth.updateUser()`, so a helper that reads `user_metadata` to decide access lets them grant themselves rights. Read `app_metadata`, which only the service role can write. Splinter's `rls_references_user_metadata` covers the policy text; this covers the functions policies call.",
+		check: (context) => [...policyHelpers(context).keys()].flatMap((name) => {
+			const dot = name.indexOf(".");
+			const body = functionBody(context, name.slice(0, dot), name.slice(dot + 1));
+			if (!body || !USER_METADATA.test(body)) return [];
+			return [{
+				message: `${name} reads user_metadata, which users can write themselves, and policies call it. Read \`auth.jwt() -> 'app_metadata'\` instead.`,
+				target: name,
+				object: {
+					kind: "function",
+					schema: name.slice(0, dot),
+					name: name.slice(dot + 1)
+				}
+			}];
+		})
+	},
+	{
+		code: "BS215",
+		severity: "warning",
+		title: "Policy calls a helper per row that could run once",
+		description: "A call such as `current_tenant_id()` takes no column of the row, so its result is the same for every row. Wrapped as `(select current_tenant_id())`, Postgres runs it once per statement as an InitPlan. Splinter's `auth_rls_initplan` covers `auth.*` calls; this covers your own helpers.",
+		check: (context) => {
+			const volatility = new Map((context.snapshot.extras.functions ?? []).map((fn) => [`${fn.schema}.${fn.name}`, fn.volatility]));
+			return exposed(context).flatMap((table) => {
+				if (!table.rls) return [];
+				return table.policies.flatMap((policy) => {
+					const text = policyText(policy);
+					const bare = (policy.functions ?? []).filter((name) => {
+						const dot = name.indexOf(".");
+						const schema = name.slice(0, dot);
+						if (schema === "auth" || volatility.get(name) === "immutable") return false;
+						return new RegExp(`(?<!\\bselect\\s+)(?<![\\w."])(?:"?${escape$1(schema)}"?\\.)?"?${escape$1(name.slice(dot + 1))}"?\\s*\\(\\s*\\)`, "i").test(text);
+					});
+					if (bare.length === 0) return [];
+					return [{
+						message: `Policy "${policy.name}" on ${qualified(table)} calls ${bare.map((name) => `${name}()`).join(", ")} without \`(select ...)\`, so it runs once per row. Write \`(select ${bare[0]}())\`.`,
+						target: `${qualified(table)}.${policy.name}`,
+						object: policyObject(table, policy)
+					}];
+				});
+			});
+		}
+	}
+];
+//#endregion
+//#region src/cli/doctor/schema-design.ts
+/** Whether the first `columns.length` columns of a non-partial index are exactly `columns`, in any order. */
+const covers = (index, columns) => !index.partial && index.columns.length >= columns.length && index.columns.slice(0, columns.length).every((column) => columns.includes(column));
+/** Foreign keys of `table` that no index starts with. */
+const unindexedForeignKeys = (table) => table.foreignKeys.filter((key) => !table.indexes.some((index) => covers(index, key.columns)));
+const SOFT_DELETE = /^(?:deleted|archived)_at$/;
+/** Operators that need a GIN index on jsonb or array columns. */
+const CONTAINS = String.raw`(?:@>|<@|\?\||\?&|\?|&&)`;
+/** `.contains("tags"`, `.containedBy('meta'`, `.overlaps("labels"`, supabase-js filters. */
+const CLIENT_CONTAINS = /\.(?:contains|containedBy|overlaps)\(\s*["'`]([A-Za-z_]\w*)["'`]/g;
+/** Column types Postgres' wiki and the Supabase skills advise against. */
+const AVOID = {
+	timestamp: "timestamptz",
+	varchar: "text with a check constraint",
+	bpchar: "text",
+	money: "numeric",
+	json: "jsonb"
+};
+/** A Supabase direct (`db.<ref>.supabase.co`) or session-pooler (`:5432`) connection string. */
+const DIRECT_URL = /postgres(?:ql)?:\/\/[^\s"'`]*@(?:db\.[a-z0-9]+\.supabase\.co(?::5432)?|[\w.-]+\.pooler\.supabase\.com:5432)\b/i;
+/** Files that show the app runs on serverless or edge functions. */
+const SERVERLESS = /\bexport\s+(?:const\s+runtime|async\s+function\s+(?:GET|POST|PUT|PATCH|DELETE)|default\s+\{\s*(?:async\s+)?fetch)\b|\bDeno\.serve\(/;
+function lines(file) {
+	return file.text.split("\n").map((text, index) => ({
+		line: index + 1,
+		text
+	}));
+}
+const SCHEMA_DESIGN_RULES = [
+	{
+		code: "BS216",
+		severity: "info",
+		title: "Foreign key without an index",
+		description: "Deletes and updates on the referenced table scan the referencing table for each row, and joins on the key can't use an index. Add an index that starts with the key's columns. This replaces splinter's `unindexed_foreign_keys` for the same table and also runs on a saved snapshot.",
+		check: (context) => exposed(context).flatMap((table) => {
+			if (table.kind !== "table") return [];
+			return unindexedForeignKeys(table).map((key) => ({
+				message: `${qualified(table)}.${key.name} (${key.columns.join(", ")}) has no index that starts with its columns, so deletes on ${key.refSchema}.${key.refTable} scan ${qualified(table)}. Run \`create index on ${qualified(table)} (${key.columns.join(", ")});\`.`,
+				target: `${qualified(table)}.${key.name}`,
+				object: tableObject(table)
+			}));
+		})
+	},
+	{
+		code: "BS217",
+		severity: "warning",
+		title: "Tenant foreign key that can cross tenants",
+		description: "When a tenant table references another tenant table by `id` alone, a row can point at a parent in another organization; RLS checks each row, not the pair. Reference `(id, organization_id)` with a composite foreign key, backed by `unique (id, organization_id)` on the parent.",
+		check: (context) => {
+			const column = context.config.plugins.tenant?.column;
+			if (!column) return [];
+			const tables = new Map(catalogOf(context).tables.map((table) => [qualified(table), table]));
+			const hasTenant = (table) => table?.columns.some((entry) => entry.name === column) ?? false;
+			return exposed(context).flatMap((table) => {
+				if (table.kind !== "table" || !hasTenant(table)) return [];
+				return table.foreignKeys.flatMap((key) => {
+					if (key.columns.includes(column)) return [];
+					const parent = tables.get(`${key.refSchema}.${key.refTable}`);
+					if (!hasTenant(parent) || parent === table) return [];
+					return [{
+						message: `${qualified(table)}.${key.name} references ${key.refSchema}.${key.refTable} (${key.refColumns.join(", ")}) without ${column}, so a row can point at another tenant's ${key.refTable}. Add \`unique (${[...key.refColumns, column].join(", ")})\` to ${key.refTable} and reference \`(${[...key.columns, column].join(", ")})\`.`,
+						target: `${qualified(table)}.${key.name}`,
+						object: tableObject(table)
+					}];
+				});
+			});
+		}
+	},
+	{
+		code: "BS218",
+		severity: "info",
+		title: "Soft-delete table without a partial index",
+		description: "Queries on a table with `deleted_at` or `archived_at` read the live rows (`where deleted_at is null`). A partial index with that predicate stays small and matches those queries.",
+		check: (context) => exposed(context).flatMap((table) => {
+			if (table.kind !== "table") return [];
+			const column = table.columns.find((entry) => SOFT_DELETE.test(entry.name) && entry.nullable);
+			if (!column) return [];
+			const isNull = new RegExp(`"?${escape$1(column.name)}"?\\s+IS\\s+NULL`, "i");
+			if (table.indexes.some((index) => index.partial && (index.predicate === void 0 || index.predicate !== null && isNull.test(index.predicate)))) return [];
+			return [{
+				message: `${qualified(table)} soft-deletes with ${column.name}, but no index has \`where ${column.name} is null\`. Index the live rows you list, for example \`create index on ${qualified(table)} (created_at desc) where ${column.name} is null;\`.`,
+				target: `${qualified(table)}.${column.name}`,
+				object: tableObject(table)
+			}];
+		})
+	},
+	{
+		code: "BS219",
+		severity: "warning",
+		title: "Containment filter on a column without a GIN index",
+		description: "`@>`, `<@`, `?` and `&&` on jsonb and array columns, and the `.contains()`, `.containedBy()` and `.overlaps()` filters, can only use a GIN index. Without one, every query reads the whole table. Doctor looks in policies, exposed functions and `doctor.sources`.",
+		check: (context) => {
+			const tables = exposed(context).filter((table) => table.kind === "table");
+			const policyText = (table) => withoutStrings(table.policies.map((policy) => `${policy.using ?? ""} ${policy.check ?? ""}`).join(" "));
+			const functions = context.snapshot.generator.functions.filter((fn) => context.config.schemas.includes(fn.schema) && fn.definition).map((fn) => withoutStrings(fn.definition)).join("\n");
+			const filtered = /* @__PURE__ */ new Set();
+			for (const file of context.sources) for (const match of file.text.matchAll(CLIENT_CONTAINS)) filtered.add(match[1]);
+			return tables.flatMap((table) => {
+				const own = policyText(table);
+				return table.columns.filter((column) => {
+					if (!column.isArray && column.udt !== "jsonb") return false;
+					if (table.indexes.some((index) => index.columns[0] === column.name && (index.method === void 0 || index.method === "gin"))) return false;
+					const used = new RegExp(`"?${escape$1(column.name)}"?\\s*${CONTAINS}|${CONTAINS}\\s*[\\w."]*\\b${escape$1(column.name)}\\b`);
+					return filtered.has(column.name) || used.test(own) || functions.includes(table.name) && used.test(functions);
+				}).map((column) => ({
+					message: `${qualified(table)}.${column.name} is filtered by containment but has no GIN index, so each query scans the table. Run \`create index on ${qualified(table)} using gin (${column.name}${column.udt === "jsonb" ? " jsonb_path_ops" : ""});\`${column.udt === "jsonb" ? " (`jsonb_path_ops` supports `@>` only; drop it for `?`)" : ""}.`,
+					target: `${qualified(table)}.${column.name}`,
+					object: tableObject(table)
+				}));
+			});
+		}
+	},
+	{
+		code: "BS220",
+		severity: "info",
+		title: "Column type to avoid",
+		description: "`timestamp` drops the time zone, `varchar(n)` and `char(n)` only add a length check `text` does with a constraint, `money` rounds by locale and `json` reparses on every read. Use `timestamptz`, `text`, `numeric` and `jsonb`.",
+		check: (context) => exposed(context).flatMap((table) => {
+			if (table.kind !== "table") return [];
+			const columns = table.columns.filter((column) => column.typeSchema === "pg_catalog" && column.udt in AVOID);
+			if (columns.length === 0) return [];
+			return [{
+				message: `${qualified(table)}: ${columns.map((column) => `${column.name} is ${column.udt}, use ${AVOID[column.udt]}`).join("; ")}.`,
+				target: qualified(table),
+				object: tableObject(table)
+			}];
+		})
+	},
+	{
+		code: "BS221",
+		severity: "warning",
+		title: "Direct database connection in a serverless app",
+		description: "Each serverless or edge invocation opens its own connection. Through the direct host or the session pooler on port 5432 they exhaust `max_connections`; the transaction pooler on port 6543 shares them. The direct host is also IPv6 only.",
+		check: (context) => {
+			if (!(context.sources.some((file) => SERVERLESS.test(file.text)) || context.envFiles.some((file) => /^\s*VERCEL\w*=/m.test(file.text)))) return [];
+			return context.envFiles.flatMap((file) => lines(file).flatMap(({ line, text }) => {
+				if (/^\s*#/.test(text) || !DIRECT_URL.test(text)) return [];
+				const key = /^\s*(?:export\s+)?(\w+)\s*=/.exec(text)?.[1];
+				return [{
+					message: `${file.path}${key ? `:${key}` : ""} connects through port 5432 or the direct host, but the app runs on serverless functions. Use the transaction pooler: \`postgres://postgres.<ref>:<password>@<region>.pooler.supabase.com:6543/postgres\`.`,
+					target: `${file.path}${key ? `:${key}` : ""}`,
+					location: {
+						file: file.path,
+						line
+					}
+				}];
+			}));
+		}
+	}
+];
+//#endregion
+//#region src/cli/doctor/rules.ts
+const DOCS_URL = "https://bettersupabase.com/docs/cli/doctor";
+const writes = (policy) => policy.command === "all" || policy.command === "insert" || policy.command === "update" || policy.command === "delete";
+const publicRoles = (policy) => policy.roles.length === 0 || policy.roles.some((role) => role === "public" || role === "anon");
+const isTrue = (expression) => expression !== null && /^\(*\s*true\s*\)*$/i.test(expression.trim());
+function authSetting(context, key) {
+	return context.configToml ? tomlGet(context.configToml.document, ["auth", key]) : void 0;
+}
+function tomlLocation(context, key) {
+	if (!context.configToml) return void 0;
+	const line = lineOf(context.configToml.text, new RegExp(`^\\s*${key}\\s*=`)) ?? lineOf(context.configToml.text, /^\[auth\]/);
+	return line ? {
+		file: context.configToml.path,
+		line
+	} : void 0;
+}
+const PUBLIC_PREFIXES = [
+	"NEXT_PUBLIC_",
+	"VITE_",
+	"PUBLIC_",
+	"EXPO_PUBLIC_",
+	"NUXT_PUBLIC_"
+];
+function envEntries(file) {
+	return file.text.split("\n").flatMap((raw, index) => {
+		const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(raw);
+		if (!match) return [];
+		const value = match[2].trim().replace(/^(['"])(.*)\1$/, "$2");
+		return [{
+			key: match[1],
+			value,
+			line: index + 1
+		}];
+	});
+}
+const ADVISOR_SEVERITY = {
+	ERROR: "error",
+	WARN: "warning",
+	INFO: "info"
+};
+function lintObject(lint) {
+	const { schema, name, type } = lint.metadata ?? {};
+	if (typeof schema !== "string" || typeof name !== "string") return void 0;
+	if (type === "table" || type === "view") return {
+		kind: "table",
+		schema,
+		name
+	};
+	if (type === "function") return {
+		kind: "function",
+		schema,
+		name
+	};
+}
+function lintFinding(lint) {
+	const object = lintObject(lint);
+	return {
+		severity: ADVISOR_SEVERITY[lint.level] ?? "warning",
+		title: lint.title,
+		message: `${lint.detail.replaceAll("\\`", "`")} [${lint.name}]`,
+		target: object ? `${object.schema}.${object.name}` : lint.cache_key,
+		help: lint.remediation,
+		...object ? { object } : {}
+	};
+}
+function advisorRule(code, category, title, description, covered = () => false) {
+	return {
+		code,
+		severity: "warning",
+		title,
+		description,
+		async check(context) {
+			const { advisors } = context;
+			if (!advisors) return [];
+			if ("skipped" in advisors) return [{
+				severity: "info",
+				message: `Skipped the ${category} advisor: ${advisors.skipped}`
+			}];
+			try {
+				return (await advisors.lints(category)).filter((lint) => !covered(lint, context)).map(lintFinding);
+			} catch (cause) {
+				return [{ message: `The ${category} advisor could not run (${advisors.describe}): ${cause instanceof Error ? cause.message : String(cause)}` }];
+			}
+		}
+	};
+}
+/**
+* splinter lints doctor's own rules report for the same table:
+* `multiple_permissive_policies` (BS207) and `unindexed_foreign_keys` (BS216).
+*/
+function coveredByOwnRules(lint, context) {
+	const code = lint.name === "multiple_permissive_policies" ? "BS207" : lint.name === "unindexed_foreign_keys" ? "BS216" : void 0;
+	if (!code || !context.codes?.includes(code)) return false;
+	const object = lintObject(lint);
+	if (!object) return false;
+	const table = exposed(context).find((candidate) => candidate.schema === object.schema && candidate.name === object.name);
+	if (!table) return false;
+	return code === "BS207" ? permissiveOverlaps(table).length > 0 : unindexedForeignKeys(table).length > 0;
+}
+/**
+* `db.x.aggregate(`, an `_sum:`/`_avg:`/`_min:`/`_max:` include or a list
+* with `facetCounts: true`.
+*/
+const AGGREGATE_USE = /\.aggregate\(|\b_(?:sum|avg|min|max)\s*:\s*\{|\bfacetCounts\s*:\s*true\b/;
+/**
+* A policy that reads memberships or the tenant claim: `is_member(...)`,
+* `current_tenant_id()`, `memberships`, PermDock's `permitted_*_ids()`.
+*/
+const TENANT_HELPER = /member|tenant|current_org|org_id|permitted_\w+_ids/i;
+/** A foreign key to the tenant table itself, whose own policies are usually read-only. */
+const TENANT_COLUMN = /^(?:org|organization|tenant|team|workspace|account)_id$/;
+const COMMANDS = [
+	"select",
+	"insert",
+	"update",
+	"delete"
+];
+const MFA_FACTORS = /\bauth\.\s*"?mfa_factors\b/i;
+const RULES = [
+	...[
+		advisorRule("BS100", "security", "Supabase security advisor", "Findings from the Security Advisor (splinter): RLS disabled in exposed schemas, RLS without policies, mutable search_path, security definer functions callable by anon, exposed auth.users and more. Hosted projects use the Management API; local stacks and direct connections run the pinned splinter.sql."),
+		{
+			code: "BS103",
+			severity: "error",
+			title: "Policy allows anonymous writes",
+			description: "A permissive policy with `true` for anon or public lets anyone insert, update or delete rows.",
+			check: (context) => exposed(context).flatMap((table) => table.policies.filter((policy) => policy.permissive && writes(policy) && publicRoles(policy) && (isTrue(policy.using) || isTrue(policy.check))).map((policy) => ({
+				message: `Policy "${policy.name}" on ${qualified(table)} allows ${policy.command} for ${policy.roles.join(", ") || "public"} with \`true\`.`,
+				target: `${qualified(table)}.${policy.name}`,
+				object: policyObject(table, policy)
+			})))
+		},
+		{
+			code: "BS106",
+			severity: "error",
+			title: "Table not granted to the Data API",
+			description: "Supabase no longer grants new tables to anon and authenticated. Without a grant, every Data API request fails with 42501 before RLS runs. Tables in `expose` need the privileges listed there; other tables need `select` for authenticated.",
+			check: (context) => {
+				const auto = context.configToml ? tomlGet(context.configToml.document, ["api", "auto_expose_new_tables"]) : void 0;
+				const note = auto === false || auto === "false" ? " config.toml sets [api] auto_expose_new_tables = false, so new tables start without grants." : "";
+				return exposed(context).flatMap((table) => {
+					if (context.config.tables[table.name]?.exclude) return [];
+					const wanted = context.config.expose[qualified(table)] ?? context.config.expose[table.name] ?? {
+						anon: [],
+						authenticated: ["select"]
+					};
+					const granted = (role) => new Set(table.grants.filter((grant) => grant.role === role || grant.role === "PUBLIC").flatMap((grant) => grant.privileges.map((privilege) => privilege.toLowerCase())));
+					return ["anon", "authenticated"].flatMap((role) => {
+						const have = granted(role);
+						const missing = wanted[role].filter((privilege) => !have.has(privilege));
+						if (missing.length === 0) return [];
+						return [{
+							message: `${role} has no ${missing.join(", ")} on ${qualified(table)}, so the Data API answers 42501. Add it to \`expose\` and run \`better-supabase sql add grants\`, or run \`grant ${missing.join(", ")} on table ${qualified(table)} to ${role};\`.${note}`,
+							target: `${qualified(table)}:${role}`,
+							object: tableObject(table)
+						}];
+					});
+				});
+			}
+		},
+		{
+			code: "BS107",
+			severity: "warning",
+			title: "Tenant table without a policy for every command",
+			description: "A tenant-scoped table with policies for some commands but not all four denies the rest silently: an update or delete then affects 0 rows without an error. Add the missing policies, or a restrictive one, so the intent is explicit, and test it with `expectTenantIsolation`.",
+			check: (context) => {
+				const column = context.config.plugins.tenant?.column;
+				const tables = exposed(context);
+				const roots = new Set(tables.flatMap((table) => table.foreignKeys.filter((key) => key.columns.length === 1 && (column === void 0 ? TENANT_COLUMN.test(key.columns[0]) : key.columns[0] === column)).map((key) => `${key.refSchema}.${key.refTable}`)));
+				return tables.flatMap((table) => {
+					if (table.kind !== "table" || !table.rls) return [];
+					if (roots.has(qualified(table))) return [];
+					if (context.config.tables[table.name]?.exclude) return [];
+					const granting = table.policies.filter((policy) => policy.permissive && policy.roles.some((role) => ["authenticated", "public"].includes(role)));
+					if (granting.length === 0) return [];
+					if (!(column !== void 0 && table.columns.some((entry) => entry.name === column) || granting.some((policy) => TENANT_HELPER.test([
+						policy.using ?? "",
+						policy.check ?? "",
+						...policy.functions ?? []
+					].join(" "))))) return [];
+					const covered = new Set(granting.flatMap((policy) => policy.command === "all" ? COMMANDS : [policy.command]));
+					const missing = COMMANDS.filter((command) => !covered.has(command));
+					if (missing.length === 0) return [];
+					return [{
+						message: `${qualified(table)} is tenant-scoped but has no ${missing.join(", ")} policy for authenticated, so ${missing.join(" and ")} silently match no rows. Add the policies, or state the intent with a restrictive \`using (false)\` policy.`,
+						target: qualified(table),
+						object: tableObject(table)
+					}];
+				});
+			}
+		},
+		{
+			code: "BS108",
+			severity: "error",
+			title: "Policy reads auth.mfa_factors directly",
+			description: "`authenticated` has no access to `auth.mfa_factors`, so a policy that reads it fails every request with 42501. Check the factor in a `security definer` function such as `better_supabase.mfa_satisfied()` from the `mfa` kit module.",
+			check: (context) => exposed(context).flatMap((table) => table.policies.filter((policy) => MFA_FACTORS.test(`${policy.using ?? ""} ${policy.check ?? ""}`)).map((policy) => ({
+				message: `Policy "${policy.name}" on ${qualified(table)} reads auth.mfa_factors, which authenticated can't select, so every request fails with 42501. Use \`(select better_supabase.mfa_satisfied())\` from \`better-supabase sql add mfa\` instead.`,
+				target: `${qualified(table)}.${policy.name}`,
+				object: policyObject(table, policy)
+			})))
+		},
+		advisorRule("BS200", "performance", "Supabase performance advisor", "Findings from the Performance Advisor (splinter): unindexed foreign keys, auth calls re-evaluated per row in policies, multiple permissive policies, unused and duplicate indexes and more.", coveredByOwnRules),
+		{
+			code: "BS204",
+			severity: "warning",
+			title: "Tenant column without an index",
+			description: "The tenant plugin and tenant policies filter every query on this column.",
+			check: (context) => {
+				const tenant = context.config.plugins.tenant;
+				if (!tenant) return [];
+				return exposed(context).filter((table) => table.columns.some((column) => column.name === tenant.column) && !table.indexes.some((index) => !index.partial && index.columns[0] === tenant.column)).map((table) => ({
+					message: `${qualified(table)}.${tenant.column} has no index starting with it.`,
+					target: `${qualified(table)}.${tenant.column}`,
+					object: tableObject(table)
+				}));
+			}
+		},
+		{
+			code: "BS210",
+			severity: "warning",
+			title: "Aggregates used while PostgREST disables them",
+			description: "PostgREST rejects `count()`, `sum()` and the other aggregates with PGRST123 unless `pgrst.db_aggregates_enabled` is on for the authenticator role. `aggregate()`, `_sum`/`_avg`/`_min`/`_max` includes and list `facetCounts` need it; `better-supabase/postgres` does not.",
+			check: (context) => {
+				const settings = context.snapshot.extras.roleSettings;
+				if (!settings) return [];
+				const enabled = settings["authenticator"]?.["pgrst.db_aggregates_enabled"];
+				if (enabled === "true" || enabled === "on") return [];
+				for (const file of context.sources) {
+					const line = lineOf(file.text, AGGREGATE_USE);
+					if (line === void 0) continue;
+					return [{
+						message: `${file.path} uses aggregates, but PostgREST has them off, so these requests fail with PGRST123. Run \`alter role authenticator set pgrst.db_aggregates_enabled = 'true'; notify pgrst, 'reload config';\` in a migration.`,
+						target: "authenticator:pgrst.db_aggregates_enabled",
+						location: {
+							file: file.path,
+							line
+						}
+					}];
+				}
+				return [];
+			}
+		},
+		{
+			code: "BS301",
+			severity: "warning",
+			title: "Soft delete hidden by a select policy",
+			description: "PostgREST re-reads updated rows through the select policy. If it hides deleted rows, soft-deleting fails with an RLS error unless the update returns nothing.",
+			check: (context) => {
+				const softDelete = context.config.plugins.softDelete;
+				if (!softDelete) return [];
+				return exposed(context).flatMap((table) => {
+					if (!table.columns.some((column) => column.name === softDelete.column)) return [];
+					return table.policies.filter((policy) => (policy.command === "select" || policy.command === "all") && new RegExp(`\\b${softDelete.column}\\b\\s+IS\\s+NULL`, "i").test(policy.using ?? "")).map((policy) => ({
+						message: `Policy "${policy.name}" on ${qualified(table)} hides rows where ${softDelete.column} is set, so \`softDelete()\` can't read the row back. Filter deleted rows in queries (the plugin does) instead of in the policy.`,
+						target: `${qualified(table)}.${policy.name}`,
+						object: policyObject(table, policy)
+					}));
+				});
+			}
+		},
+		{
+			code: "BS302",
+			severity: "warning",
+			title: "Bucket differs from the config",
+			description: "A bucket in `buckets` is missing or has different settings in the database.",
+			check: (context) => Object.entries(context.config.buckets).flatMap(([name, bucket]) => {
+				const id = bucket.id ?? name.replaceAll(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
+				const defined = defineBucket({
+					id,
+					path: bucket.path,
+					...bucket.public === void 0 ? {} : { public: bucket.public },
+					...bucket.fileSizeLimit === void 0 ? {} : { fileSizeLimit: bucket.fileSizeLimit },
+					...bucket.allowedMimeTypes === void 0 ? {} : { allowedMimeTypes: bucket.allowedMimeTypes }
+				});
+				const actual = catalogOf(context).buckets.find((entry) => entry.id === id);
+				const inDatabase = defined.drift(actual).map((drift) => ({
+					message: `Bucket ${id}: ${drift.message}`,
+					target: `storage.buckets.${id}`
+				}));
+				const toml = context.configToml;
+				const declared = toml ? tomlGet(toml.document, [
+					"storage",
+					"buckets",
+					id
+				]) : void 0;
+				if (!toml || !declared || typeof declared !== "object" || Array.isArray(declared)) return inDatabase;
+				const entry = declared;
+				const size = entry["file_size_limit"];
+				const mimes = entry["allowed_mime_types"];
+				const line = lineOf(toml.text, new RegExp(`^\\[storage\\.buckets\\.${id.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\]`));
+				const inToml = defined.drift({
+					public: entry["public"] === true,
+					fileSizeLimit: typeof size === "string" || typeof size === "number" ? parseSize(size) : null,
+					allowedMimeTypes: Array.isArray(mimes) ? mimes.map(String) : null
+				}).map((drift) => ({
+					message: `${toml.path} [storage.buckets.${id}]: ${drift.message.replace(`Bucket "${id}" `, "")}`,
+					target: `[storage.buckets.${id}]`,
+					...line ? { location: {
+						file: toml.path,
+						line
+					} } : {}
+				}));
+				return [...inDatabase, ...inToml];
+			})
+		},
+		{
+			code: "BS303",
+			severity: "error",
+			title: "Generated code is out of date",
+			description: "The generated module no longer matches the database, so types and metadata are wrong. Same check as `gen --check`.",
+			check: async (context) => {
+				const stale = [];
+				for (const file of await renderFiles(context.config, context.snapshot)) {
+					const current = await readFile(resolve(context.config.root, file.path), "utf8").catch(() => void 0);
+					if (current !== file.contents) stale.push({
+						message: `${file.path} is ${current === void 0 ? "missing" : "out of date"}. Run \`better-supabase gen\`.`,
+						target: file.path,
+						...current === void 0 ? {} : { location: {
+							file: file.path,
+							line: 1
+						} }
+					});
+				}
+				return stale;
+			}
+		},
+		{
+			code: "BS304",
+			severity: "warning",
+			title: "SQL kit files are out of date",
+			description: "A module listed in `sql.kit` differs from the version in this release. Same check as `sql sync --check`.",
+			check: async (context) => {
+				if (context.config.sql.kit.length === 0) return [];
+				const stale = [];
+				const readSets = context.readSets;
+				const skipped = readSets !== void 0 && "skipped" in readSets;
+				for (const file of renderKit(context.config.sql.kit, kitLayout(context.config, context.config.sql.testsDir, skipped ? [] : readSets, entitlementsKit(context)))) {
+					if (skipped && file.module === "read-sets") continue;
+					const current = await readFile(resolve(context.config.root, file.path), "utf8").catch(() => void 0);
+					if (sameKitFile(current, file.contents)) continue;
+					stale.push({
+						message: `${file.path} (${file.module}) is ${current === void 0 ? "missing" : "out of date"}. Run \`better-supabase sql sync\`, then \`${migrationCommand(context.configToml)}\`.`,
+						target: file.path,
+						...current === void 0 ? {} : { location: {
+							file: file.path,
+							line: 1
+						} }
+					});
+				}
+				return stale;
+			}
+		},
+		{
+			code: "BS305",
+			severity: "warning",
+			title: "Live query table without change broadcasts",
+			description: "A table in `realtime.tables` has no `bs_realtime` trigger, so live queries never hear about its changes.",
+			check: (context) => {
+				const tables = catalogOf(context).tables;
+				return context.config.realtime.tables.flatMap((name) => {
+					const table = tables.find((entry) => entry.name === name || qualified(entry) === name);
+					if (!table) return [{
+						message: `realtime.tables lists "${name}", which doesn't exist.`,
+						target: name
+					}];
+					if (table.triggers.some((trigger) => trigger.name.startsWith("bs_realtime"))) return [];
+					return [{
+						message: `${qualified(table)} is in realtime.tables but has no broadcast trigger. Run \`better-supabase sql add realtime-tables\`, then \`${migrationCommand(context.configToml)}\`.`,
+						target: qualified(table),
+						object: tableObject(table)
+					}];
+				});
+			}
+		},
+		{
+			code: "BS306",
+			severity: "warning",
+			title: "Realtime delete events without keys",
+			description: "Tables in the `supabase_realtime` publication send the replica identity of deleted rows. With `nothing`, or `default` without a primary key, delete events carry no keys and clients cannot tell which row went away.",
+			check: (context) => {
+				const published = new Set(catalogOf(context).realtime);
+				return catalogOf(context).tables.filter((table) => published.has(qualified(table)) && (table.replicaIdentity === "NOTHING" || table.replicaIdentity === "DEFAULT" && table.primaryKey.length === 0)).map((table) => ({
+					message: `${qualified(table)} is published to Realtime with replica identity ${table.replicaIdentity?.toLowerCase() ?? "unknown"}${table.primaryKey.length === 0 ? " and no primary key" : ""}. Add a primary key or run \`alter table ${qualified(table)} replica identity full\`.`,
+					target: qualified(table),
+					object: tableObject(table)
+				}));
+			}
+		},
+		{
+			code: "BS401",
+			severity: "warning",
+			title: "Refresh token reuse interval is 0",
+			description: "Server instances refreshing the same session at once need a reuse interval, or all but one of them sign the user out.",
+			check: (context) => {
+				if (!context.configToml) return [];
+				const rotation = authSetting(context, "enable_refresh_token_rotation");
+				const interval = authSetting(context, "refresh_token_reuse_interval");
+				if (rotation === false || rotation === "false" || interval === void 0 || Number(interval) > 0) return [];
+				const location = tomlLocation(context, "refresh_token_reuse_interval");
+				return [{
+					message: "refresh_token_reuse_interval = 0 with refresh token rotation. Use 10 (the Supabase default) so concurrent refreshes succeed.",
+					target: "[auth] refresh_token_reuse_interval",
+					...location ? { location } : {}
+				}];
+			}
+		},
+		{
+			code: "BS402",
+			severity: "info",
+			title: "Long access token lifetime",
+			description: "Tokens are verified locally without an auth call, so a revoked session stays valid until the token expires.",
+			check: (context) => {
+				if (!context.configToml) return [];
+				const expiry = Number(authSetting(context, "jwt_expiry") ?? 3600);
+				if (expiry <= 3600) return [];
+				const location = tomlLocation(context, "jwt_expiry");
+				return [{
+					message: `jwt_expiry is ${expiry}s. Keep it at 3600 or less; sessions refresh in the proxy.`,
+					target: "[auth] jwt_expiry",
+					...location ? { location } : {}
+				}];
+			}
+		},
+		{
+			code: "BS403",
+			severity: "info",
+			title: "Local stack signs tokens with a shared secret",
+			description: "Hosted projects sign with asymmetric keys. Using the same locally means local tokens verify through JWKS just like production.",
+			check: (context) => {
+				if (!context.configToml || authSetting(context, "signing_keys_path")) return [];
+				const location = tomlLocation(context, "signing_keys_path");
+				return [{
+					message: "No [auth] signing_keys_path. Run `better-supabase keys` to sign local tokens with ES256.",
+					target: "[auth] signing_keys_path",
+					...location ? { location } : {}
+				}];
+			}
+		},
+		{
+			code: "BS406",
+			severity: "warning",
+			title: "Foreign key to auth.users blocks account deletion",
+			description: "A foreign key to `auth.users` with `no action` or `restrict` makes `auth.admin.deleteUser` (and `deleteAccount`) fail with \"Database error deleting user\" while the user has rows. Use `on delete cascade` for data the user owns, or `on delete set null` for records that outlive them.",
+			check: (context) => catalogOf(context).tables.flatMap((table) => table.schema === "auth" ? [] : table.foreignKeys.filter((key) => key.refSchema === "auth" && key.refTable === "users" && (key.onDelete === "no action" || key.onDelete === "restrict")).map((key) => ({
+				message: `${qualified(table)}.${key.name} (${key.columns.join(", ")}) references auth.users with on delete ${key.onDelete}. Deleting the user fails while rows point at it; use on delete cascade or set null.`,
+				target: `${qualified(table)}.${key.name}`,
+				object: tableObject(table)
+			})))
+		},
+		{
+			code: "BS501",
+			severity: "error",
+			title: "Secret in a browser variable",
+			description: "Variables with a public prefix are bundled into client code. A secret key there gives every visitor full access.",
+			check: (context) => context.envFiles.flatMap((file) => envEntries(file).filter((entry) => PUBLIC_PREFIXES.some((prefix) => entry.key.startsWith(prefix)) && (entry.value.startsWith("sb_secret_") || /SECRET|SERVICE_ROLE/.test(entry.key))).map((entry) => ({
+				message: `${entry.key} in ${file.path} is exposed to the browser but holds a secret. Rename it without the public prefix and rotate the key.`,
+				target: `${file.path}:${entry.key}`,
+				location: {
+					file: file.path,
+					line: entry.line
+				}
+			})))
+		},
+		{
+			code: "BS502",
+			severity: "warning",
+			title: "Env file with secrets is not ignored by git",
+			description: "Env files holding a secret key or database password should never be committed.",
+			check: (context) => {
+				const patterns = context.gitignore.split("\n").map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("#"));
+				const ignored = (path) => patterns.some((pattern) => {
+					const source = pattern.replace(/^\//, "").replaceAll(/[.+^${}()|[\]\\]/g, "\\$&").replaceAll("*", ".*");
+					return new RegExp(`^${source}$`).test(path) || new RegExp(`(^|/)${source}$`).test(path);
+				});
+				return context.envFiles.flatMap((file) => {
+					const secret = envEntries(file).find((entry) => entry.value.startsWith("sb_secret_") || /SECRET_KEY|SERVICE_ROLE|DB_URL|DATABASE_URL/.test(entry.key));
+					if (!secret || ignored(file.path) || file.path.endsWith(".example")) return [];
+					return [{
+						message: `${file.path} contains ${secret.key} but isn't in .gitignore.`,
+						target: file.path,
+						location: {
+							file: file.path,
+							line: secret.line
+						}
+					}];
+				});
+			}
+		}
+	],
+	...RLS_RULES,
+	...POLICY_RULES,
+	...SCHEMA_DESIGN_RULES,
+	...HOOK_RULES,
+	...PERMDOCK_RULES,
+	...LIVE_RULES
+].sort((a, b) => byCodePoint(a.code, b.code));
+const RULE_CODES = RULES.map((rule) => rule.code);
+async function runRules(context, rules = RULES) {
+	const findings = [];
+	const scoped = {
+		...context,
+		codes: rules.map((rule) => rule.code)
+	};
+	for (const rule of rules) for (const input of await rule.check(scoped)) findings.push({
+		code: rule.code,
+		severity: rule.severity,
+		title: rule.title,
+		help: `${DOCS_URL}#${rule.code.toLowerCase()}`,
+		...input
+	});
+	return findings;
+}
+//#endregion
+//#region src/cli/doctor/format.ts
+const DOCTOR_FORMATS = [
+	"text",
+	"json",
+	"sarif",
+	"github"
+];
+const DOCTOR_REPORT_SCHEMA_URL = "https://unpkg.com/better-supabase/schemas/doctor-report-v1.json";
+const SARIF_SCHEMA_URL = "https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/schemas/sarif-schema-2.1.0.json";
+function summarize(findings) {
+	return {
+		errors: findings.filter((finding) => finding.severity === "error").length,
+		warnings: findings.filter((finding) => finding.severity === "warning").length,
+		infos: findings.filter((finding) => finding.severity === "info").length
+	};
+}
+const plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+const SEVERITY_FORMAT = {
+	error: "red",
+	warning: "yellow",
+	info: "cyan"
+};
+function text(findings, paint) {
+	if (findings.length === 0) return "No problems found.";
+	const order = [
+		"error",
+		"warning",
+		"info"
+	];
+	const lines = [...findings].sort((a, b) => order.indexOf(a.severity) - order.indexOf(b.severity) || byCodePoint(a.code, b.code)).flatMap((finding) => [
+		`${paint(SEVERITY_FORMAT[finding.severity], finding.severity.padEnd(7))} ${paint("bold", finding.code)} ${finding.title}${finding.location ? `  ${finding.location.file}:${finding.location.line}` : ""}`,
+		`        ${finding.message}`,
+		`        ${finding.help}`
+	]);
+	const summary = summarize(findings);
+	lines.push("", `${plural(summary.errors, "error")}, ${plural(summary.warnings, "warning")}, ${plural(summary.infos, "note")}.`);
+	return lines.join("\n");
+}
+function sarifLevel(severity) {
+	switch (severity) {
+		case "error": return "error";
+		case "warning": return "warning";
+		case "info": return "note";
+		default: return severity;
+	}
+}
+function sarif(findings, rules, version, fallback) {
+	return {
+		$schema: SARIF_SCHEMA_URL,
+		version: "2.1.0",
+		runs: [{
+			tool: { driver: {
+				name: "better-supabase doctor",
+				version,
+				informationUri: DOCS_URL,
+				rules: rules.map((rule) => ({
+					id: rule.code,
+					name: rule.title.replaceAll(/[^A-Za-z0-9]+(.)?/g, (_, char) => (char ?? "").toUpperCase()),
+					shortDescription: { text: rule.title },
+					fullDescription: { text: rule.description },
+					helpUri: `${DOCS_URL}#${rule.code.toLowerCase()}`,
+					defaultConfiguration: { level: sarifLevel(rule.severity) }
+				}))
+			} },
+			results: findings.map((finding) => ({
+				ruleId: finding.code,
+				ruleIndex: rules.findIndex((rule) => rule.code === finding.code),
+				level: sarifLevel(finding.severity),
+				message: { text: finding.message },
+				locations: [{ physicalLocation: {
+					artifactLocation: { uri: finding.location?.file ?? fallback },
+					region: { startLine: finding.location?.line ?? 1 }
+				} }],
+				partialFingerprints: { target: `${finding.code}:${finding.target ?? finding.message}` }
+			}))
+		}]
+	};
+}
+const escapeData = (value) => value.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
+const escapeProperty = (value) => escapeData(value).replaceAll(":", "%3A").replaceAll(",", "%2C");
+function github(findings) {
+	return findings.map((finding) => {
+		return `::${finding.severity === "info" ? "notice" : finding.severity} ${[...finding.location ? [`file=${escapeProperty(finding.location.file)}`, `line=${finding.location.line}`] : [], `title=${escapeProperty(`${finding.code} ${finding.title}`)}`].join(",")}::${escapeData(`${finding.message} (${finding.help})`)}`;
+	}).join("\n");
+}
+function jsonReport(findings, version) {
+	return {
+		$schema: DOCTOR_REPORT_SCHEMA_URL,
+		version: 1,
+		tool: {
+			name: "better-supabase",
+			version
+		},
+		summary: summarize(findings),
+		findings
+	};
+}
+function formatReport(findings, options) {
+	switch (options.format) {
+		case "text": return text(findings, options.paint ?? plain);
+		case "json": return JSON.stringify(jsonReport(findings, options.version), null, 2);
+		case "sarif": return JSON.stringify(sarif(findings, options.rules, options.version, options.fallbackFile), null, 2);
+		case "github": return github(findings);
+		default: return options.format;
+	}
+}
+//#endregion
+//#region src/cli/commands/doctor.ts
+const ARGS = {
+	format: {
+		type: "string",
+		description: "text (default), sarif (code scanning) or github (workflow annotations); --json for the JSON report",
+		valueHint: "format"
+	},
+	out: {
+		type: "string",
+		description: "Write the report to a file",
+		valueHint: "file"
+	},
+	only: {
+		type: "string",
+		description: "Run only these checks, e.g. --only BS100,BS304",
+		valueHint: "codes"
+	},
+	ignore: {
+		type: "string",
+		description: "Skip checks; also doctor.ignore in the config",
+		valueHint: "codes"
+	},
+	strict: {
+		type: "boolean",
+		description: "Fail on warnings; also doctor.strict"
+	},
+	snapshot: {
+		type: "string",
+		description: "Check a saved snapshot instead of the database",
+		valueHint: "file"
+	},
+	"db-url-stdin": {
+		type: "boolean",
+		description: "Read the connection string from stdin instead of $DATABASE_URL or the config"
+	},
+	"project-ref": {
+		type: "string",
+		description: "Read a hosted project through the Management API",
+		valueHint: "ref"
+	},
+	stats: {
+		type: "boolean",
+		description: "Report slow frequent statements from pg_stat_statements (BS209)"
+	},
+	explain: {
+		type: "string",
+		description: "EXPLAIN ANALYZE these tables under RLS, rolled back (BS212)",
+		valueHint: "tables"
+	},
+	as: {
+		type: "string",
+		description: "Plan as this authenticated user, and measure the claims the custom access token hook returns for them (BS405)",
+		valueHint: "uuid"
+	},
+	claims: {
+		type: "string",
+		description: "Plan with these JWT claims ({\"role\":\"authenticated\",...})",
+		valueHint: "json"
+	},
+	"fix-grants": {
+		type: "boolean",
+		description: "Print the grant and revoke SQL BS404 asks for, to add to your schema or migration"
+	}
+};
+const ENV_FILES = [
+	".env",
+	".env.local",
+	".env.development",
+	".env.development.local",
+	".env.production",
+	".env.production.local"
+];
+async function readText(root, path) {
+	const absolute = resolve(root, path);
+	return existsSync(absolute) ? {
+		path,
+		text: await readFile(absolute, "utf8")
+	} : void 0;
+}
+/** The declarative schemas in the diff engine's order, then the migrations newest first. */
+async function sqlFiles(root, toml) {
+	const read = async (path) => ({
+		path,
+		text: await readFile(resolve(root, path), "utf8")
+	});
+	const schemas = await Promise.all((await schemaPaths(root, toml)).files.map(read));
+	const migrationsDir = resolve(root, "supabase/migrations");
+	const migrations = existsSync(migrationsDir) ? (await readdir(migrationsDir)).filter((name) => name.endsWith(".sql")).sort().reverse().map((name) => `supabase/migrations/${name}`) : [];
+	return [...schemas, ...await Promise.all(migrations.map(read))];
+}
+/** Files matching `doctor.sources`, skipping dependencies and build output. */
+async function sourceFiles(config) {
+	const files = [];
+	for await (const path of glob([...config.doctor.sources], {
+		cwd: config.root,
+		exclude: (name) => name === "node_modules" || name === ".next"
+	})) files.push({
+		path,
+		text: await readFile(resolve(config.root, path), "utf8")
+	});
+	return files.sort((a, b) => byCodePoint(a.path, b.path));
+}
+const escape = (name) => name.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** Where a table, function or policy is declared: declarative schemas first, then the newest migration. */
+function locate(files, object) {
+	const name = `"?${escape(object.name)}"?`;
+	const qualifiedName = `(?:"?${escape(object.schema)}"?\\.)?${name}`;
+	const pattern = object.kind === "table" ? new RegExp(`create\\s+(?:unlogged\\s+)?table\\s+(?:if\\s+not\\s+exists\\s+)?${qualifiedName}(?:\\s|\\(|$)`, "i") : object.kind === "function" ? new RegExp(`create\\s+(?:or\\s+replace\\s+)?function\\s+${qualifiedName}\\s*\\(`, "i") : new RegExp(`create\\s+policy\\s+${name}`, "i");
+	for (const file of files) {
+		const line = lineOf(file.text, pattern);
+		if (line) return {
+			file: file.path,
+			line
+		};
+	}
+}
+const FLAG_FORMATS = DOCTOR_FORMATS.filter((format) => format !== "json");
+/** `--json` picks the JSON report; `--format` picks between the others. */
+function reportFormat(args) {
+	if (args.format === "json") throw new CliError("usage", "--format json is now the global --json flag");
+	if (args.json === true) {
+		if (args.format !== void 0) throw new CliError("usage", "Pass --json or --format, not both");
+		return "json";
+	}
+	if (args.format === void 0) return "text";
+	const format = FLAG_FORMATS.find((candidate) => candidate === args.format);
+	if (!format) throw new CliError("usage", `--format must be one of ${FLAG_FORMATS.join(", ")}`);
+	return format;
+}
+/** Checks that read the database itself rather than the snapshot. */
+const LIVE_CODES = /* @__PURE__ */ new Set([
+	"BS100",
+	"BS200",
+	"BS208",
+	"BS209",
+	"BS212"
+]);
+/**
+* The database doctor reads, for advisors and live checks: the Management
+* API for hosted projects, one lazily opened connection otherwise (splinter
+* runs over it). Saved snapshots skip both.
+*/
+function openLive(config, env, source, pg) {
+	const none = { close: () => Promise.resolve() };
+	const file = snapshotFile(config, source);
+	if (file) {
+		const skipped = `reading the saved snapshot ${file}; set $DATABASE_URL, or pass --db-url-stdin or --project-ref, to check a database.`;
+		return {
+			...none,
+			advisors: { skipped },
+			database: { skipped }
+		};
+	}
+	let opened;
+	const open = () => opened ??= openSource(config, env, source, pg);
+	const target = managementTarget(config, env, source);
+	const database = {
+		describe: target ? `project ${target.projectRef} (Management API)` : "database",
+		session: !target,
+		async query(sql) {
+			return (await (await open()).queryable.query(sql)).rows;
+		}
+	};
+	const close = async () => {
+		if (opened) await (await opened).close();
+	};
+	if (target) return {
+		advisors: managementAdvisors(target),
+		database,
+		open,
+		close
+	};
+	let splinter;
+	const cacheDir = resolve(config.root, CACHE_DIR);
+	return {
+		advisors: {
+			describe: "database (splinter)",
+			async lints(category) {
+				splinter ??= open().then((db) => splinterAdvisors(db.queryable, db.describe, { cacheDir }));
+				return (await splinter).lints(category);
+			}
+		},
+		database,
+		open,
+		close
+	};
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** `--as <uuid>` or `--claims <json>` as `request.jwt.claims`. */
+function explainClaims(args) {
+	const as = args.as;
+	const claims = args.claims;
+	if (as && claims) return { error: "Pass --as or --claims, not both" };
+	if (as) {
+		if (!UUID.test(as)) return { error: `--as takes a user id (uuid), got "${as}"` };
+		return {
+			sub: as,
+			role: "authenticated"
+		};
+	}
+	if (!claims) return { role: "anon" };
+	try {
+		const parsed = JSON.parse(claims);
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return { error: "--claims takes a JSON object" };
+		return {
+			role: "anon",
+			...parsed
+		};
+	} catch (cause) {
+		return { error: `--claims is not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}` };
+	}
+}
+async function runDoctor(config, args, env, options = {}) {
+	const format = reportFormat(args);
+	const only = list(args.only);
+	const ignore = /* @__PURE__ */ new Set([...config.doctor.ignore, ...list(args.ignore)]);
+	const unknown = [...only, ...ignore].filter((code) => !RULE_CODES.includes(code));
+	if (unknown.length > 0) return {
+		code: 2,
+		error: `Unknown check ${unknown.join(", ")}. Checks: ${RULE_CODES.join(", ")}`
+	};
+	const explainTables = list(args.explain);
+	const stats = args.stats === true;
+	const claims = explainClaims(args);
+	if ("error" in claims) return {
+		code: 2,
+		error: String(claims.error)
+	};
+	const hookUser = args.as;
+	const asked = /* @__PURE__ */ new Set([
+		...stats ? ["BS209"] : [],
+		...explainTables.length > 0 ? ["BS212"] : [],
+		...hookUser ? ["BS405"] : []
+	]);
+	const fixGrants = args["fix-grants"] === true;
+	const rules = fixGrants ? RULES.filter((rule) => rule.code === "BS404") : RULES.filter((rule) => (only.length === 0 || only.includes(rule.code) || asked.has(rule.code)) && !ignore.has(rule.code));
+	const snapshotPath = args.snapshot;
+	const dbUrl = options.dbUrl;
+	const projectRef = args["project-ref"];
+	const source = {
+		...stats || explainTables.length > 0 || hookUser ? { live: true } : {},
+		...snapshotPath ? { snapshotPath } : {},
+		...dbUrl ? { dbUrl } : {},
+		...projectRef ? { projectRef } : {},
+		...options.signal ? { signal: options.signal } : {}
+	};
+	const pg = options.connect ?? connect;
+	const wantsLive = hookUser !== void 0 || rules.some((rule) => LIVE_CODES.has(rule.code));
+	const opened = options.snapshot || !wantsLive ? {
+		advisors: options.advisors,
+		database: options.database,
+		close: () => Promise.resolve()
+	} : {
+		...openLive(config, env, source, pg),
+		...options.advisors === void 0 ? {} : { advisors: options.advisors },
+		...options.database === void 0 ? {} : { database: options.database }
+	};
+	const [snapshot, envFiles, permdock, [configToml, sql], gitignore, sources, readSets] = await Promise.all([
+		options.snapshot ?? loadSnapshot(config, env, source, pg, opened.open),
+		Promise.all(ENV_FILES.map((path) => readText(config.root, path))).then((files) => files.filter((file) => file !== void 0)),
+		readPermdock(config.root, config.permdock),
+		readSupabaseToml(config.root).then(async (toml) => [toml, await sqlFiles(config.root, toml)]),
+		readText(config.root, ".gitignore"),
+		sourceFiles(config),
+		compiledReadSets(config).catch((cause) => ({ skipped: cause instanceof Error ? cause.message : String(cause) }))
+	]).catch(async (cause) => {
+		await opened.close();
+		throw cause;
+	});
+	const context = {
+		config,
+		snapshot,
+		...permdock ? { permdock } : {},
+		sqlFiles: sql,
+		configToml,
+		envFiles,
+		gitignore: gitignore?.text ?? "",
+		sources,
+		readSets,
+		...opened.advisors ? { advisors: opened.advisors } : {},
+		...opened.database ? { database: opened.database } : {},
+		...stats ? { stats } : {},
+		...hookUser ? { hookUser } : {},
+		...explainTables.length > 0 ? { explain: {
+			tables: explainTables,
+			claims
+		} } : {}
+	};
+	if (fixGrants) {
+		await opened.close();
+		return {
+			code: 0,
+			output: hookGrantBlock(hookGrantProblems(context), diffEngine(context.configToml))
+		};
+	}
+	let ran;
+	try {
+		ran = await runRules(context, rules);
+	} finally {
+		await opened.close();
+	}
+	const findings = ran.map((finding) => {
+		if (finding.location || !finding.object) return finding;
+		const location = locate(sql, finding.object);
+		return location ? {
+			...finding,
+			location
+		} : finding;
+	});
+	const out = args.out;
+	const report = formatReport(findings, {
+		format,
+		rules,
+		version: VERSION,
+		fallbackFile: context.configToml?.path ?? "package.json",
+		...options.paint && !out ? { paint: options.paint } : {}
+	});
+	const errors = findings.filter((finding) => finding.severity === "error").length;
+	const warnings = findings.filter((finding) => finding.severity === "warning").length;
+	const strict = args.strict === true || config.doctor.strict;
+	const code = errors > 0 || strict && warnings > 0 ? 1 : 0;
+	if (out) {
+		await writeIfChanged(resolve(config.root, out), `${report}\n`);
+		return {
+			code,
+			output: `Wrote ${out}: ${errors} errors, ${warnings} warnings.`,
+			data: {
+				out,
+				errors,
+				warnings
+			}
+		};
+	}
+	return format === "json" ? {
+		code,
+		data: jsonReport(findings, VERSION)
+	} : {
+		code,
+		output: report
+	};
+}
+const doctorCommand = defineCliCommand({
+	meta: {
+		name: "doctor",
+		description: "Checks RLS, indexes, drift, auth config and env files; exits 1 on errors, or on warnings with --strict"
+	},
+	args: ARGS,
+	lists: [
+		"only",
+		"ignore",
+		"explain"
+	],
+	run: async (args, { config, env, io, signal }) => {
+		const dbUrl = await stdinDatabaseUrl(args["db-url-stdin"], io);
+		return withSpinner(args.snapshot === void 0 ? io.prompts : void 0, "Checking the database", () => runDoctor(config, args, env, {
+			paint: painter(io.color),
+			...dbUrl ? { dbUrl } : {},
+			...signal ? { signal } : {}
+		}));
+	}
+});
+//#endregion
+export { doctorCommand };