better-supabase 0.12.0 → 0.14.0

package/dist/cli/codemod-Dz4R-tVY.js

@@ -0,0 +1,1127 @@
+import { p as commandMeta, r as defineCliCommand } from "./command-33pu13LT.js";
+import { i as plain } from "./style-Bm2X5JrN.js";
+import { n as CliError } from "./errors-BTe6A15O.js";
+import { t as migrateCliCall } from "./moved-CdNtCf4t.js";
+import { t as isRecord$1 } from "./guards-CUlDNYZs.js";
+import { i as changedFiles, n as applyPlan, r as changeLines, s as planResult } from "./files-C5JfVnj5.js";
+import { _ as codeRanges, a as configObject, c as mask, f as setPathInConfig, g as skipSpace, i as closingIndex, l as properties, o as indentAt, p as setPathInJson } from "./config-edit-D46H0UHp.js";
+import { extname, join, relative, resolve } from "node:path";
+import { readFile, readdir, stat } from "node:fs/promises";
+import { BLOCK_EVENT_RENAMES } from "better-supabase/events";
+//#region src/cli/codemod-calls.ts
+/** Files whose CLI calls a codemod rewrites. */
+const CLI_CALL_FILE = /(?:^|[\\/])(?:package\.json|\.github[\\/]workflows[\\/][^\\/]+\.ya?ml)$/;
+/** Other files that run shell commands; their CLI calls are listed for review. */
+const SHELL_FILE = /(?:^|[\\/])(?:[^\\/]+\.(?:sh|bash|zsh|ya?ml)|Makefile|justfile|Dockerfile)$/;
+/** The bin, with an optional `@version`, followed by its arguments. */
+const BIN = /(?<![\w.@-])(?:better-supabase|bsb)(?:@[\w.^~-]+)?(?=[ \t])/g;
+/**
+* Where a call's arguments end: a line break, a shell operator, a closing quote
+* or a comment.
+*/
+const CALL_END = /\r?\n|&&|\|\||[;|)`]|\\?"|\s#/;
+/** `pnpm --filter better-supabase <script>` names the package, not the bin. */
+const PACKAGE_FILTER = /(?:--filter|-F)[= ]$/;
+function cliCalls(text, migrate) {
+	const calls = [];
+	for (const match of text.matchAll(BIN)) {
+		if (PACKAGE_FILTER.test(text.slice(0, match.index))) continue;
+		const start = match.index + match[0].length;
+		const tail = text.slice(start);
+		const end = start + (CALL_END.exec(tail)?.index ?? tail.length);
+		const words = text.slice(start, end).trim().split(/\s+/u);
+		const to = words[0] === "" ? void 0 : migrate(words);
+		if (to) calls.push({
+			start,
+			end,
+			bin: match[0],
+			to
+		});
+	}
+	return calls;
+}
+/** `text` with every moved CLI call spelled the new way. */
+function rewriteCliCalls(text, migrate) {
+	let out = "";
+	let cursor = 0;
+	for (const call of cliCalls(text, migrate)) {
+		const original = text.slice(call.start, call.end);
+		const trailing = /\s*$/u.exec(original)?.[0] ?? "";
+		out += `${text.slice(cursor, call.start)} ${call.to.join(" ")}${trailing}`;
+		cursor = call.end;
+	}
+	return out + text.slice(cursor);
+}
+/** One review line per moved CLI call, with the new spelling. */
+function cliCallHints(text, migrate) {
+	return cliCalls(text, migrate).map((call) => ({
+		line: text.slice(0, call.start).split("\n").length,
+		message: `This call uses a renamed command or flag: run \`${call.bin} ${call.to.join(" ")}\``
+	}));
+}
+//#endregion
+//#region src/cli/sql/config-move.ts
+const lineStart = (source, index) => source.lastIndexOf("\n", index - 1) + 1;
+function propertySpan(source, code, open, props, index) {
+	const prop = props[index];
+	const previous = props[index - 1];
+	if (prop === void 0) throw new Error(`no property at ${index}`);
+	const close = closingIndex(code, open);
+	const multiline = code.slice(open, close).includes("\n");
+	const after = skipSpace(code, prop.valueEnd);
+	const hasComma = code[after] === ",";
+	const tailFrom = hasComma ? after + 1 : prop.valueEnd;
+	if (!multiline) {
+		const value = source.slice(prop.start, prop.valueEnd);
+		if (previous) return {
+			start: previous.valueEnd,
+			end: prop.valueEnd,
+			value,
+			keyAt: 0,
+			trailing: "",
+			hasComma,
+			multiline
+		};
+		return {
+			start: prop.start,
+			end: hasComma ? skipSpace(code, tailFrom) : prop.valueEnd,
+			value,
+			keyAt: 0,
+			trailing: "",
+			hasComma,
+			multiline
+		};
+	}
+	let before = open + 1;
+	if (previous) {
+		const comma = skipSpace(code, previous.valueEnd);
+		before = code[comma] === "," ? comma + 1 : previous.valueEnd;
+	}
+	const newline = source.slice(before, prop.start).indexOf("\n");
+	const start = newline === -1 ? prop.start : before + newline + 1;
+	const lineEnd = source.indexOf("\n", tailFrom);
+	const restIsBlank = lineEnd !== -1 && code.slice(tailFrom, lineEnd).trim() === "";
+	return {
+		start,
+		end: restIsBlank ? lineEnd + 1 : tailFrom,
+		value: source.slice(start, prop.valueEnd),
+		keyAt: prop.start - start,
+		trailing: restIsBlank ? source.slice(tailFrom, lineEnd).trimEnd() : "",
+		hasComma,
+		multiline
+	};
+}
+/** `modules: ...` as `blocks: ...`, keeping the key's quotes. */
+function renameKey(text, keyAt, prop) {
+	const head = text.slice(keyAt);
+	const quoted = /^(["'])modules\1/.exec(head);
+	if (quoted) {
+		const quote = quoted[1] ?? "\"";
+		return `${text.slice(0, keyAt)}${quote}blocks${quote}${head.slice(quoted[0].length)}`;
+	}
+	if (prop.valueStart === prop.start) return `${text.slice(0, keyAt)}blocks: modules${head.slice(7)}`;
+	return `${text.slice(0, keyAt)}blocks${head.slice(7)}`;
+}
+function reindent(text, from, to) {
+	return text.split("\n").map((line) => line.startsWith(from) ? to + line.slice(from.length) : line).join("\n");
+}
+const sortKey = (key) => (key ?? "").toLowerCase();
+function keysSorted(keys) {
+	return keys.every((key, index) => index === 0 || key !== void 0 && sortKey(keys[index - 1]) <= sortKey(key));
+}
+function rootKeys(source) {
+	const code = mask(source);
+	const root = configObject(code);
+	return (root === void 0 ? void 0 : properties(source, code, root))?.map((prop) => prop.key) ?? [];
+}
+function sortBlocksKey(source) {
+	const code = mask(source);
+	const root = configObject(code);
+	if (root === void 0) return source;
+	const props = properties(source, code, root);
+	const blocksIndex = props?.findIndex((prop) => prop.key === "blocks") ?? -1;
+	if (!props || blocksIndex === -1) return source;
+	const targetIndex = props.findIndex((prop, index) => index !== blocksIndex && sortKey(prop.key) > sortKey("blocks"));
+	if (targetIndex === -1 || targetIndex === blocksIndex + 1) return source;
+	const blocks = propertySpan(source, code, root, props, blocksIndex);
+	const target = props[targetIndex];
+	if (target.start > blocks.start) return source;
+	const at = blocks.multiline ? propertySpan(source, code, root, props, targetIndex).start : target.start;
+	const moved = blocks.multiline ? `${blocks.value},${blocks.trailing}\n` : `${blocks.value}, `;
+	return source.slice(0, at) + moved + source.slice(at, blocks.start) + source.slice(blocks.end);
+}
+/**
+* `source` with `sql.modules` moved to a top-level `blocks` key, placed right
+* after `sql`, or in sorted position when the config's top-level keys are
+* sorted. `sql` is dropped when nothing else is left in it. A config without
+* `sql.modules` comes back unchanged; one that also sets `blocks` is refused,
+* because the two need a merge by hand.
+*/
+function moveSqlModulesToBlocks(source) {
+	const edit = moveSqlModules(source);
+	return edit.ok && edit.text !== source && keysSorted(rootKeys(source)) ? {
+		ok: true,
+		text: sortBlocksKey(edit.text)
+	} : edit;
+}
+function moveSqlModules(source) {
+	const code = mask(source);
+	const root = configObject(code);
+	if (root === void 0) return /\bmodules\b/.test(code) ? {
+		ok: false,
+		reason: "it doesn't pass an object literal to defineConfig()"
+	} : {
+		ok: true,
+		text: source
+	};
+	const rootProps = properties(source, code, root);
+	if (!rootProps) return {
+		ok: false,
+		reason: "its config object can't be read"
+	};
+	const sqlIndex = rootProps.findIndex((prop) => prop.key === "sql");
+	const sql = rootProps[sqlIndex];
+	if (sql === void 0) return {
+		ok: true,
+		text: source
+	};
+	if (code[sql.valueStart] !== "{" || sql.valueStart === sql.start) return /\bmodules\b/.test(code) ? {
+		ok: false,
+		reason: "its `sql` value isn't an object literal; move `sql.modules` to `blocks` by hand"
+	} : {
+		ok: true,
+		text: source
+	};
+	const sqlProps = properties(source, code, sql.valueStart);
+	if (!sqlProps) return {
+		ok: false,
+		reason: "its `sql` object can't be read"
+	};
+	const modulesIndex = sqlProps.findIndex((prop) => prop.key === "modules");
+	const modules = sqlProps[modulesIndex];
+	if (modules === void 0) return {
+		ok: true,
+		text: source
+	};
+	if (rootProps.some((prop) => prop.key === "blocks")) return {
+		ok: false,
+		reason: "it sets both `sql.modules` and `blocks`; merge `sql.modules` into `blocks` by hand"
+	};
+	const cut = propertySpan(source, code, sql.valueStart, sqlProps, modulesIndex);
+	const outer = propertySpan(source, code, root, rootProps, sqlIndex);
+	const renamed = renameKey(cut.value, cut.keyAt, modules);
+	const sqlClose = closingIndex(code, sql.valueStart);
+	const leftover = source.slice(sql.valueStart + 1, cut.start) + source.slice(cut.end, sqlClose);
+	const dropSql = sqlProps.length === 1 && leftover.trim() === "";
+	if (!cut.multiline || !outer.multiline) {
+		const property = renamed.trim();
+		if (dropSql) return {
+			ok: true,
+			text: source.slice(0, sql.start) + property + source.slice(sql.valueEnd)
+		};
+		return {
+			ok: true,
+			text: `${source.slice(0, cut.start)}${source.slice(cut.end, sql.valueEnd)}, ${property}${source.slice(sql.valueEnd)}`
+		};
+	}
+	const sqlIndent = indentAt(source, sql.start);
+	const body = reindent(renamed, indentAt(source, modules.start), sqlIndent);
+	const moved = `${cut.start === modules.start ? sqlIndent + body : body},${cut.trailing}\n`;
+	if (dropSql) return {
+		ok: true,
+		text: source.slice(0, lineStart(source, sql.start)) + moved + source.slice(outer.end)
+	};
+	const atLineStart = source[outer.end - 1] === "\n";
+	return {
+		ok: true,
+		text: source.slice(0, cut.start) + source.slice(cut.end, sql.valueEnd) + (outer.hasComma ? "" : ",") + source.slice(sql.valueEnd, outer.end) + (atLineStart ? "" : "\n") + moved + source.slice(outer.end)
+	};
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function withBlocksSorted(config) {
+	const entries = Object.entries(config).filter(([key]) => key !== "blocks");
+	const after = entries.findIndex(([key]) => sortKey(key) > "blocks");
+	entries.splice(after === -1 ? entries.length : after, 0, ["blocks", config["blocks"]]);
+	return Object.fromEntries(entries);
+}
+/** `moveSqlModulesToBlocks` for `better-supabase.config.json`. */
+function moveSqlModulesToBlocksJson(source) {
+	let config;
+	try {
+		config = JSON.parse(source);
+	} catch {
+		return {
+			ok: false,
+			reason: "it isn't valid JSON"
+		};
+	}
+	if (!isRecord(config)) return {
+		ok: false,
+		reason: "it isn't a JSON object"
+	};
+	const sql = config["sql"];
+	if (!isRecord(sql) || !("modules" in sql)) return {
+		ok: true,
+		text: source
+	};
+	if ("blocks" in config) return {
+		ok: false,
+		reason: "it sets both `sql.modules` and `blocks`; merge `sql.modules` into `blocks` by hand"
+	};
+	const { modules, ...restSql } = sql;
+	const next = {};
+	for (const [key, value] of Object.entries(config)) {
+		if (key !== "sql") {
+			next[key] = value;
+			continue;
+		}
+		if (Object.keys(restSql).length > 0) next["sql"] = restSql;
+		next["blocks"] = modules;
+	}
+	const sorted = keysSorted(Object.keys(config)) ? withBlocksSorted(next) : next;
+	const indent = /^[ \t]+/m.exec(source)?.[0] ?? "  ";
+	return {
+		ok: true,
+		text: `${JSON.stringify(sorted, null, indent)}\n`
+	};
+}
+//#endregion
+//#region src/cli/sql/config-webhook-format.ts
+const PATH = [
+	"blocks",
+	"webhooks-out",
+	"options",
+	"defaultFormat"
+];
+function needsPin(block) {
+	if (!isRecord$1(block) || block["mode"] !== "adopt") return false;
+	const options = block["options"];
+	const columns = block["columns"];
+	const endpoints = isRecord$1(columns) ? columns["endpoints"] : void 0;
+	return !(isRecord$1(options) && options["defaultFormat"] !== void 0) && !(isRecord$1(endpoints) && endpoints["format"] !== void 0);
+}
+function pinJson(source, format) {
+	let config;
+	try {
+		config = JSON.parse(source);
+	} catch {
+		return {
+			ok: false,
+			reason: "it isn't valid JSON"
+		};
+	}
+	const blocks = isRecord$1(config) ? config["blocks"] : void 0;
+	return isRecord$1(blocks) && needsPin(blocks["webhooks-out"]) ? setPathInJson(source, PATH, format) : void 0;
+}
+/** The object literal at `prop`'s value, or `undefined` when it isn't one. */
+function objectAt(source, code, prop) {
+	return prop && code[prop.valueStart] === "{" ? properties(source, code, prop.valueStart) : void 0;
+}
+function pinTs(source, format) {
+	const code = mask(source);
+	const root = configObject(code);
+	if (root === void 0) return;
+	const find = (props, key) => props?.find((prop) => prop.key === key);
+	const blockProp = find(objectAt(source, code, find(properties(source, code, root), "blocks")), "webhooks-out");
+	if (!blockProp) return;
+	const block = objectAt(source, code, blockProp);
+	if (!block) return {
+		ok: false,
+		reason: "its blocks[\"webhooks-out\"] isn't a literal object"
+	};
+	const mode = find(block, "mode");
+	const modeText = mode ? source.slice(mode.valueStart, mode.valueEnd).trim() : void 0;
+	if (modeText !== "\"adopt\"" && modeText !== "'adopt'") return;
+	const options = find(block, "options");
+	const columns = find(block, "columns");
+	if (options && !objectAt(source, code, options) || columns && !objectAt(source, code, columns)) return {
+		ok: false,
+		reason: "its blocks[\"webhooks-out\"] options or columns aren't literal objects"
+	};
+	const endpoints = find(objectAt(source, code, columns), "endpoints");
+	if (endpoints && !objectAt(source, code, endpoints)) return {
+		ok: false,
+		reason: "its blocks[\"webhooks-out\"].columns.endpoints isn't a literal object"
+	};
+	if (find(objectAt(source, code, options), "defaultFormat") || find(objectAt(source, code, endpoints), "format")) return;
+	return setPathInConfig(source, PATH, format);
+}
+/**
+* Pins `defaultFormat` to `format` where an adopted block leaves it to the
+* default.
+*/
+function pinWebhookFormat(source, json, format) {
+	return json ? pinJson(source, format) : pinTs(source, format);
+}
+//#endregion
+//#region src/cli/codemod.ts
+/**
+* `better-supabase.config.*`, the files a codemod's `configFile` edit applies
+* to.
+*/
+const CONFIG_FILE = /(?:^|[\\/])better-supabase\.config\.(?:ts|mts|cts|js|mjs|cjs|json)$/;
+const OFFSET_PIN = {
+	key: "pagination",
+	value: "\"offset\"",
+	when: /\.page\b(?!\s*\()|\bpageCount\b|\btotalPages\b|\bpage\s*:|[?&]page=|["']page["']/,
+	message: "Lists and resources page by cursor (`after`, `nextCursor`, no total) unless `pagination: \"offset\"` is set. This file shows no page numbers, so the codemod left it: add `pagination: \"offset\"` if a UI elsewhere reads `page` or the total, or the list sorts by a relation"
+};
+/** Review lines for `sql.modules` left in environment blocks after the move. */
+function environmentModules(text) {
+	return mask(text).split("\n").flatMap((line, index) => /\bmodules\s*:/.test(line) ? [{
+		line: index + 1,
+		message: "`sql.modules` in an environment block moves to `blocks` too"
+	}] : []);
+}
+/**
+* `edit` with `defaultFormat` pinned to `format` where an adopted webhooks-out
+* block needs it.
+*/
+function withWebhookFormat(edit, json, format) {
+	if (!edit.ok) return edit;
+	const earlier = "review" in edit ? edit.review : [];
+	const pin = pinWebhookFormat(edit.text, json, format);
+	if (pin === void 0) return {
+		ok: true,
+		text: edit.text,
+		review: earlier
+	};
+	if (!pin.ok) return {
+		ok: true,
+		text: edit.text,
+		review: [...earlier, {
+			line: 1,
+			message: `blocks["webhooks-out"] is adopted and maps no columns.endpoints.format, but defaultFormat wasn't pinned: ${pin.reason}. Set options.defaultFormat to "${format}" to keep the body endpoints get now`
+		}]
+	};
+	const line = pin.text.split("\n").findIndex((text) => text.includes("defaultFormat")) + 1;
+	return {
+		ok: true,
+		text: pin.text,
+		review: [...earlier, {
+			line: Math.max(line, 1),
+			message: `blocks["webhooks-out"] is adopted and maps no columns.endpoints.format, so the codemod set options.defaultFormat to "${format}", the body its endpoints get now. Change it if your receivers expect the other format`
+		}]
+	};
+}
+const SQL_ADD_HINT = {
+	pattern: /(?<![\w.@-])(?:better-supabase|bsb)(?:@[\w.^~-]+)?\s+sql\s+add\b/,
+	message: "`sql add` still only writes the block's SQL; `add` also wires its clients and config. Use `add` unless the script needs the SQL alone"
+};
+const CODEMODS = {
+	"0.4": {
+		name: "0.4",
+		description: "Renames from 0.3 to 0.4 (the naming page lists them)",
+		imports: {
+			createBrowser: "createClient",
+			BetterBrowser: "BetterClient",
+			BrowserOptions: "ClientOptions",
+			BrowserAuth: "ClientAuth",
+			BetterEnv: "HonoEnv",
+			HandlerOptions: "MiddlewareOptions",
+			Queries: "BetterQueries",
+			CreateQueriesOptions: "QueriesOptions",
+			Postgres: "BetterPostgres",
+			DefineSupabaseOptions: "SupabaseOptions"
+		},
+		members: [
+			{
+				from: "serverFor",
+				to: "contextForSession"
+			},
+			{
+				from: "toORPCError",
+				to: "toOrpcError"
+			},
+			{
+				from: "$table",
+				to: "$tableName",
+				notCalled: true
+			}
+		],
+		props: [{
+			component: "BetterSupabaseProvider",
+			from: "browser",
+			to: "client"
+		}],
+		review: [
+			{
+				pattern: /\.server\(\)/,
+				message: "`next.server()` is `bs.context()` on the createNext() instance"
+			},
+			{
+				pattern: /\.handle\(\)/,
+				message: "Hono's `bs.handle()` is `bs.handler()`"
+			},
+			{
+				pattern: /\bmcp\.handler\b/,
+				message: "`mcp.handler` is `bs.endpoint`"
+			},
+			{
+				pattern: /\.sb\b/,
+				message: "`client.sb` is `client.betterSupabase`"
+			},
+			{
+				pattern: /\btestExecutor\(\s*\{[^}]*\bsb\b/,
+				message: "`{ sb }` in testExecutor is `{ betterSupabase }`"
+			}
+		]
+	},
+	"0.5": {
+		name: "0.5",
+		description: "Renames from 0.4 to 0.5: createMcp's scopes is advertisedScopes",
+		options: [{
+			call: "createMcp",
+			from: "scopes",
+			to: "advertisedScopes"
+		}]
+	},
+	"0.6": {
+		name: "0.6",
+		description: "Changes from 0.5 to 0.6: kits become blocks and modules, org becomes organization (in event types too), $rpc returns table rows and records in the configured casing, and bucket publicUrl() and path() return a Result",
+		strings: {
+			...BLOCK_EVENT_RENAMES,
+			"org.*": "organization.*"
+		},
+		imports: {
+			KitEvent: "BlockEvent",
+			KitEventMap: "BlockEventMap",
+			KitEventType: "BlockEventType",
+			KitEventMeta: "BlockEventMeta",
+			KitEventPattern: "BlockEventPattern",
+			KitEventsMatching: "BlockEventsMatching",
+			onKitEvent: "onBlockEvent",
+			forwardKitEvents: "forwardBlockEvents",
+			ForwardKitOptions: "ForwardBlockOptions",
+			KIT_ATTRIBUTES: "BLOCK_ATTRIBUTES",
+			kitCloudEvent: "blockCloudEvent",
+			kitEventAttributes: "blockEventAttributes",
+			traceKitEvents: "traceBlockEvents",
+			KitTransport: "BlockTransport",
+			OrgEventData: "OrganizationEventData",
+			createOrgs: "createOrganizations",
+			Orgs: "Organizations",
+			OrgsOptions: "OrganizationsOptions",
+			CreateOrgOptions: "CreateOrganizationOptions",
+			OrgAttributes: "OrganizationAttributes",
+			orgLogoBucket: "organizationLogoBucket",
+			OrgLogoBucketOptions: "OrganizationLogoBucketOptions",
+			KitsConfig: "BlocksConfig",
+			KitModuleConfig: "BlockConfig",
+			KitMode: "BlockMode",
+			AccessKitConfig: "AccessBlockConfig",
+			renderKit: "renderModules",
+			kitLayout: "moduleLayout",
+			kitPermissionKeys: "modulePermissionKeys",
+			kitDeprecations: "moduleDeprecations",
+			kitFilePaths: "moduleFilePaths",
+			kitFileVersion: "moduleFileVersion",
+			sameKitFile: "sameModuleFile",
+			kitIdType: "moduleIdType",
+			isKitIdType: "isModuleIdType",
+			KIT_ID_TYPES: "MODULE_ID_TYPES",
+			KitIdType: "ModuleIdType",
+			KitContext: "ModuleContext",
+			KitLayout: "ModuleLayout",
+			KitFile: "ModuleFile",
+			KitNames: "ModuleNames",
+			KitTableSpec: "ModuleTableSpec",
+			KitContractFunction: "ModuleContractFunction",
+			KitDeprecation: "ModuleDeprecation",
+			KitPermissionKey: "ModulePermissionKey",
+			KitUpgrade: "ModuleUpgrade",
+			KitUpgradePlan: "ModuleUpgradePlan",
+			InstalledKitModule: "InstalledModule"
+		},
+		options: [{
+			call: "defineSupabase",
+			from: "maxUrlLength",
+			to: "urlLengthLimit"
+		}],
+		review: [
+			{
+				pattern: /from\s*["']better-supabase\/(orgs|jobs|notifications|webhooks)["']/,
+				message: "This subpath moved under `better-supabase/blocks/` (`orgs` is `blocks/organizations`; the outbox, entitlements and audit retention left `jobs` for their own blocks); the 0.5 to 0.6 guide maps each export"
+			},
+			{
+				pattern: /\bcreateInbox\b[^\n]*from\s*["']better-supabase\/(blocks\/)?jobs["']/,
+				message: "The webhook inbox is `createWebhookInbox` from `better-supabase/blocks/jobs`; `createInbox` is now the conversation inbox in `blocks/inbox`"
+			},
+			{
+				pattern: /\$rpc\s*(<|\()/,
+				message: "`$rpc` now returns table rows and `returns table (...)` records in the configured casing, with codecs applied: drop a snake-to-camel mapping of the result, or pass `{ raw: true }` to keep database names. Scalar results and `returns table` columns are now `| null` unless `functions.<name>.notNull` says otherwise"
+			},
+			{
+				pattern: /\.publicUrl\s*\(/,
+				message: "A connected bucket's `publicUrl()` returns a `Result` instead of throwing: read `.data` (`null` on an error) or check `.ok`"
+			},
+			{
+				pattern: /\.path\s*\(\s*\{/,
+				message: "A bucket definition's `path(values)` returns a `Result` instead of throwing, like the connected client's `path()`: read `.data` (`null` on an error) or check `.ok`"
+			}
+		]
+	},
+	"0.9": {
+		name: "0.9",
+		description: "Moves sql.modules to the top-level blocks key in better-supabase.config.*, rewrites CLI calls in package.json scripts and GitHub workflows to the new subcommands and flags (other shell files are listed), renames the config types (ModulesConfig to BlocksConfig, ModuleConfig to BlockConfig, AccessModuleConfig to AccessBlockConfig, ModuleMode to BlockMode), pins pagination: 'offset' on lists and resources in files that read page numbers, and lists behaviour changes for review: support sessions (denied without authorize, approved by a second admin), canApprove (now isApprover), outgoing webhook transforms and receivers (CloudEvents), gatewayOptions callers, generic problem types (about:blank), the delegation cap, role helpers, event and schedule starts (runAs), workflow builders, delivery and realtime fan-out, agent actors, share links, before_promotion_activate and comment subjects",
+		imports: {
+			ModulesConfig: "BlocksConfig",
+			ModuleConfig: "BlockConfig",
+			AccessModuleConfig: "AccessBlockConfig",
+			ModuleMode: "BlockMode"
+		},
+		configFile: (source, json) => {
+			const moved = json ? moveSqlModulesToBlocksJson(source) : moveSqlModulesToBlocks(source);
+			return withWebhookFormat(moved.ok && !json ? {
+				...moved,
+				review: environmentModules(moved.text)
+			} : moved, json, "standard");
+		},
+		cliCalls: migrateCliCall,
+		cliReview: [SQL_ADD_HINT],
+		pins: [{
+			call: "defineListQuery",
+			argument: 2,
+			...OFFSET_PIN
+		}, {
+			call: "defineResource",
+			argument: 2,
+			unless: ["list"],
+			...OFFSET_PIN
+		}],
+		review: [
+			{
+				pattern: /\bresources\s*:\s*\{/,
+				message: "The default list of each `defineApi` resource pages by cursor (`after`, `nextCursor`) unless the table has no primary key; set `pagination: \"offset\"` on a resource whose clients send `page` or read the total"
+			},
+			{
+				pattern: /\bsupportSessions\s*\(/,
+				message: "Support sessions refuse every start without `authorize` (or the server's `authorization.support.authorize`), and a start needs a request approved by a different admin unless `policy.approval` is `\"none\"`. `authorize: \"store\"` keeps the store-only check"
+			},
+			{
+				pattern: /\bcanApprove\b/,
+				message: "`authorization.functions.canApprove` is deprecated: set `isApprover` with `{kind}` (`'ai-tool'`), `{subject}` (the tool name, was `{tool}`) and `{tenant}`"
+			},
+			{
+				pattern: /\bcreateWebhooks\s*\(/,
+				message: "Outgoing webhooks send CloudEvents 1.0 (`application/cloudevents+json`) instead of `{ type, timestamp, data }`; a `transform` now returns only the event's `data`, and receivers read `data` from the CloudEvent. `sql upgrade` keeps existing endpoints on `format = 'standard'` (the 0.8 body) until you set each one to `cloudevents`"
+			},
+			{
+				pattern: /\bgatewayOptions\s*\(/,
+				message: "`gatewayOptions` ignores a `user` in its second argument; pass the caller's id as `context.userId`"
+			},
+			{
+				pattern: /bettersupabase\.com\/problems\/(invalid-request|unauthorized|forbidden|not-found|conflict|rate-limited|unexpected)\b|["'](Invalid request|Not found|Too many requests|Unexpected error)["']/,
+				message: "Generic problems use `type: \"about:blank\"` and the HTTP status phrase as `title` (`Bad Request`, `Not Found`, `Too Many Requests`, `Internal Server Error`); match on `kind` or `code` instead"
+			},
+			{
+				pattern: /\bpublish_webhook_event\s*\(/,
+				message: "`publish_webhook_event` takes `subject` and `read_permission` and delivers only to endpoints whose owner may read the event"
+			},
+			{
+				pattern: /\btoken_scope_allows\s*\(|["']oauth-client["']/,
+				message: "Delegated tokens are narrowed inside `member_can`, `platform_can` and `tenant_ids_with`: a permission passes only when one of the token's scopes maps to it. Map scopes in `blocks.access.scopes` or `authorization.delegation.scopes`; a `token_scope_allows` check in a write policy is now covered by the cap"
+			},
+			{
+				pattern: /\b(has_organization_role|member_organization_ids|organization_member_role)\s*\(/,
+				message: "Under the provider model the role helpers take membership from the provider's `memberIds`, and a role name check skips the delegation cap (doctor BS334): check a permission with `tenant_ids_with('<permission>')` or `member_can()`"
+			},
+			{
+				pattern: /\b(workflowStarter|startOnEvent)\s*\(/,
+				message: "Event and schedule starts need `runAs: { publisher, permissions }` (or a function returning it): a schedule start without it throws, and the run's context is the publisher's, capped to `permissions`"
+			},
+			{
+				pattern: /\bcreateBuilder\s*\(/,
+				message: "Published versions run as their publisher (`versions.runAs`), and versions published before 0.9 fail with `WORKFLOW_PUBLISHER_REVOKED` until republished. A version the organization owns runs as its default service principal: create one with `default: true` or set `automation.runAs`"
+			},
+			{
+				pattern: /\b(createNotifications|createReminders)\s*\(|\.fanOut\s*\(/,
+				message: "Under an authorization provider without `delivery.subscribers` or `delivery.audience`, an event about a registered subject reaches only users who may read it (`subjectReaders`), and realtime `fanOut` refuses it (`REALTIME_SUBSCRIBER_POLICY_REQUIRED`) until you pass a `policy`"
+			},
+			{
+				pattern: /\bkind\s*:\s*["']agent["']/,
+				message: "An `act` level `{ kind: \"agent\", sub, tools }` is now valid (build it with `agentClaims`) and writes with the user's rights unless it sets `read_only: true`; `tools` must be a list of names"
+			},
+			{
+				pattern: /\bcreate_share_link\b/,
+				message: "`create_share_link` takes `version_id` and `expires_at` after `role`; grants and revokes on the four-argument signature must name `(uuid, text, text, text, uuid, timestamptz)`"
+			},
+			{
+				pattern: /\bbefore_promotion_activate\b/,
+				message: "`promotions` now calls `before_promotion_activate(promotion uuid)` after every write that leaves a promotion active; a function of that name runs on each such save"
+			},
+			{
+				pattern: /\bcomments\s*:\s*\{/,
+				message: "With `config.subjects` set and no `subjects` option, comments accept only the registered subject types and require read on the subject row"
+			}
+		]
+	},
+	"0.11": {
+		name: "0.11",
+		description: "Pins blocks[\"webhooks-out\"].options.defaultFormat to \"cloudevents\" in better-supabase.config.* when the block is adopted and maps no columns.endpoints.format, since adopt mode requires it from 0.11; the 0.9 codemod pins \"standard\" instead for configs coming from 0.8",
+		configFile: (source, json) => withWebhookFormat({
+			ok: true,
+			text: source
+		}, json, "cloudevents")
+	}
+};
+function applyEdits(text, edits) {
+	let out = "";
+	let cursor = 0;
+	for (const edit of edits.toSorted((a, b) => a.start - b.start)) {
+		if (edit.start < cursor) continue;
+		out += text.slice(cursor, edit.start) + edit.text;
+		cursor = edit.end;
+	}
+	return out + text.slice(cursor);
+}
+const escapeRegExp = (value) => value.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function inCode(ranges, index) {
+	let low = 0;
+	let high = ranges.length - 1;
+	while (low <= high) {
+		const middle = Math.floor((low + high) / 2);
+		const [start, end] = ranges[middle];
+		if (index < start) high = middle - 1;
+		else if (index >= end) low = middle + 1;
+		else return true;
+	}
+	return false;
+}
+const OPENING = "({[";
+const CLOSING = ")}]";
+/** Matches of `pattern` that start in code. */
+function codeMatches(text, pattern, ranges) {
+	return [...text.matchAll(pattern)].filter((match) => inCode(ranges, match.index));
+}
+const IMPORT = /\b(import|export)\s+(type\s+)?\{([^}]*)\}\s*from\s*(["'])better-supabase(?:\/[\w./-]*)?\4/g;
+function renameImports(text, renames) {
+	const ranges = codeRanges(text);
+	const locals = /* @__PURE__ */ new Set();
+	const edits = [];
+	for (const match of codeMatches(text, IMPORT, ranges)) {
+		const list = match[3];
+		const listStart = match.index + match[0].indexOf("{") + 1;
+		const renamed = list.replaceAll(/(\btype\s+)?([\w$]+)(\s+as\s+[\w$]+)?/g, (spec, type, name, alias) => {
+			const to = renames[name];
+			if (to === void 0) return spec;
+			if (alias === void 0 && match[1] === "import") locals.add(name);
+			return `${type ?? ""}${to}${alias ?? ""}`;
+		});
+		if (renamed !== list) edits.push({
+			start: listStart,
+			end: listStart + list.length,
+			text: renamed
+		});
+	}
+	return {
+		text: applyEdits(text, edits),
+		locals
+	};
+}
+function renameIdentifiers(text, renames) {
+	if (renames.size === 0) return text;
+	const ranges = codeRanges(text);
+	const names = [...renames.keys()].map(escapeRegExp).join("|");
+	return applyEdits(text, codeMatches(text, new RegExp(`(?<![\\w$.])(?:${names})(?![\\w$])`, "g"), ranges).map((match) => ({
+		start: match.index,
+		end: match.index + match[0].length,
+		text: renames.get(match[0])
+	})));
+}
+function renameStrings(text, strings) {
+	const names = Object.keys(strings).map(escapeRegExp).join("|");
+	if (names === "") return text;
+	const ranges = codeRanges(text);
+	const pattern = new RegExp(`(["'\`])(${names})\\1`, "g");
+	return applyEdits(text, [...text.matchAll(pattern)].filter((match) => !inCode(ranges, match.index + 1)).map((match) => ({
+		start: match.index + 1,
+		end: match.index + 1 + match[2].length,
+		text: strings[match[2]]
+	})));
+}
+function renameMembers(text, members) {
+	const ranges = codeRanges(text);
+	return applyEdits(text, members.flatMap((member) => codeMatches(text, new RegExp(`\\.${escapeRegExp(member.from)}(?![\\w$])${member.notCalled === true ? "(?!\\s*\\()" : ""}`, "g"), ranges).map((match) => ({
+		start: match.index,
+		end: match.index + match[0].length,
+		text: `.${member.to}`
+	}))));
+}
+function renameProps(text, props) {
+	const ranges = codeRanges(text);
+	const edits = [];
+	for (const prop of props) {
+		const tag = new RegExp(`<${escapeRegExp(prop.component)}(?![\\w$.])`, "g");
+		for (const match of codeMatches(text, tag, ranges)) {
+			let depth = 0;
+			for (let index = match.index + match[0].length; index < text.length; index += 1) {
+				if (!inCode(ranges, index)) continue;
+				const char = text[index];
+				if (char === "{") depth += 1;
+				else if (char === "}") depth -= 1;
+				else if (char === ">" && depth === 0) break;
+				if (depth === 0 && /\s/.test(text[index - 1] ?? "") && text.startsWith(`${prop.from}=`, index)) edits.push({
+					start: index,
+					end: index + prop.from.length,
+					text: prop.to
+				});
+			}
+		}
+	}
+	return applyEdits(text, edits);
+}
+/** The index after the bracket that closes the one at `open`, in code only. */
+function closing(text, open, ranges) {
+	let depth = 0;
+	for (let index = open; index < text.length; index += 1) {
+		if (!inCode(ranges, index)) continue;
+		const char = text[index];
+		if (OPENING.includes(char)) depth += 1;
+		else if (CLOSING.includes(char)) {
+			depth -= 1;
+			if (depth === 0) return index + 1;
+		}
+	}
+	return text.length;
+}
+/**
+* Calls `visit(index, depth)` for each code character from `open` to its
+* closing bracket.
+*/
+function walkBrackets(text, open, ranges, visit) {
+	const end = closing(text, open, ranges);
+	let depth = 0;
+	for (let index = open; index < end; index += 1) {
+		if (!inCode(ranges, index)) continue;
+		const char = text[index];
+		if (OPENING.includes(char)) depth += 1;
+		else if (CLOSING.includes(char)) depth -= 1;
+		visit(index, depth, char);
+	}
+}
+/** Where `key` is a top-level key of the object literal at `open`. */
+function topLevelKeys(text, open, key, ranges) {
+	const keys = [];
+	let previous = "";
+	walkBrackets(text, open, ranges, (index, depth, char) => {
+		if (depth === 1 && (previous === "{" || previous === ",") && text.startsWith(key, index) && !/[\w$]/.test(text[index + key.length] ?? "")) {
+			const after = /^\s*(\S)/.exec(text.slice(index + key.length))?.[1];
+			if (after === ":") keys.push({
+				index,
+				shorthand: false
+			});
+			else if (after === "," || after === "}") keys.push({
+				index,
+				shorthand: true
+			});
+		}
+		if (depth === 1 && !/\s/.test(char)) previous = char;
+	});
+	return keys;
+}
+function renameOptions(text, options) {
+	const ranges = codeRanges(text);
+	const edits = [];
+	for (const option of options) {
+		const call = new RegExp(`(?<![\\w$.])${escapeRegExp(option.call)}\\s*(?:<[^>]*>)?\\s*\\(`, "g");
+		for (const match of codeMatches(text, call, ranges)) {
+			const objects = [];
+			walkBrackets(text, match.index + match[0].length - 1, ranges, (index, depth, char) => {
+				if (depth === 2 && char === "{") objects.push(index);
+			});
+			for (const object of objects) for (const { index, shorthand } of topLevelKeys(text, object, option.from, ranges)) edits.push({
+				start: index,
+				end: index + option.from.length,
+				text: shorthand ? `${option.to}: ${option.from}` : option.to
+			});
+		}
+	}
+	return applyEdits(text, edits);
+}
+/** The arguments of the call whose `(` is at `open`: start and end of each. */
+function callArguments(text, open, ranges) {
+	const args = [];
+	let start = open + 1;
+	const end = closing(text, open, ranges) - 1;
+	walkBrackets(text, open, ranges, (index, depth, char) => {
+		if (depth === 1 && char === ",") {
+			args.push({
+				start,
+				end: index
+			});
+			start = index + 1;
+		}
+	});
+	if (text.slice(start, end).trim() !== "") args.push({
+		start,
+		end
+	});
+	return args;
+}
+/**
+* Calls of `pin.call` whose options object lacks `pin.key`, with the insertion
+* when one is safe.
+*/
+function pinTargets(text, pin) {
+	const ranges = codeRanges(text);
+	const call = new RegExp(`(?<![\\w$.])${escapeRegExp(pin.call)}\\s*(?:<[^>]*>)?\\s*\\(`, "g");
+	const targets = [];
+	const entry = `${pin.key}: ${pin.value}`;
+	for (const match of codeMatches(text, call, ranges)) {
+		const open = match.index + match[0].length - 1;
+		const args = callArguments(text, open, ranges);
+		const arg = args[pin.argument];
+		if (arg === void 0) {
+			if (args.length !== pin.argument) {
+				targets.push({
+					call: match.index,
+					edit: void 0
+				});
+				continue;
+			}
+			const last = args.at(-1);
+			const at = last === void 0 ? open + 1 : last.end;
+			const trailing = text[at] === ",";
+			targets.push({
+				call: match.index,
+				edit: trailing ? {
+					start: at + 1,
+					end: at + 1,
+					text: ` { ${entry} }`
+				} : {
+					start: at,
+					end: at,
+					text: `, { ${entry} }`
+				}
+			});
+			continue;
+		}
+		const offset = text.slice(arg.start, arg.end).search(/\S/);
+		const object = arg.start + offset;
+		if (text[object] !== "{") {
+			targets.push({
+				call: match.index,
+				edit: void 0
+			});
+			continue;
+		}
+		if ([pin.key, ...pin.unless ?? []].some((key) => topLevelKeys(text, object, key, ranges).length > 0)) continue;
+		const spreads = [];
+		walkBrackets(text, object, ranges, (index, depth) => {
+			if (depth === 1 && text.startsWith("...", index)) spreads.push(index);
+		});
+		if (spreads.length > 0) {
+			targets.push({
+				call: match.index,
+				edit: void 0
+			});
+			continue;
+		}
+		const body = text.slice(object + 1, closing(text, object, ranges) - 1);
+		const first = /^[ \t]*\n([ \t]*)\S/.exec(body);
+		targets.push({
+			call: match.index,
+			edit: body.trim() === "" ? {
+				start: object,
+				end: object + body.length + 2,
+				text: `{ ${entry} }`
+			} : first ? {
+				start: object + 1,
+				end: object + 1,
+				text: `\n${first[1]}${entry},`
+			} : {
+				start: object + 1,
+				end: object + 1,
+				text: ` ${entry},`
+			}
+		});
+	}
+	return targets;
+}
+function pinOptions(text, pins) {
+	let out = text;
+	for (const pin of pins) if (pin.when.test(out)) out = applyEdits(out, pinTargets(out, pin).flatMap((target) => target.edit === void 0 ? [] : [target.edit]));
+	const review = pins.flatMap((pin) => pinTargets(out, pin).map((target) => ({
+		line: out.slice(0, target.call).split("\n").length,
+		message: pin.message
+	})));
+	return {
+		text: out,
+		review
+	};
+}
+/** Applies one codemod to a source file. */
+function applyCodemod(codemod, source, file) {
+	if (file !== void 0 && (CLI_CALL_FILE.test(file) || SHELL_FILE.test(file))) {
+		const hints = linesMatching(source, codemod.cliReview ?? []);
+		if (!codemod.cliCalls) return {
+			text: source,
+			review: hints
+		};
+		return CLI_CALL_FILE.test(file) ? {
+			text: rewriteCliCalls(source, codemod.cliCalls),
+			review: hints
+		} : {
+			text: source,
+			review: [...cliCallHints(source, codemod.cliCalls), ...hints]
+		};
+	}
+	let text = source;
+	const refused = [];
+	if (codemod.configFile && file !== void 0 && CONFIG_FILE.test(file)) {
+		const json = file.endsWith(".json");
+		const edit = codemod.configFile(source, json);
+		if (edit.ok) {
+			text = edit.text;
+			refused.push(..."review" in edit ? edit.review : []);
+		} else refused.push({
+			line: 1,
+			message: `The config wasn't rewritten: ${edit.reason}`
+		});
+		if (json) return {
+			text,
+			review: refused
+		};
+	}
+	if (codemod.imports) {
+		const imported = renameImports(text, codemod.imports);
+		text = renameIdentifiers(imported.text, new Map([...imported.locals].map((name) => [name, codemod.imports[name]])));
+	}
+	if (codemod.members) text = renameMembers(text, codemod.members);
+	if (codemod.props) text = renameProps(text, codemod.props);
+	if (codemod.options) text = renameOptions(text, codemod.options);
+	if (codemod.strings) text = renameStrings(text, codemod.strings);
+	if (codemod.pins) {
+		const pinned = pinOptions(text, codemod.pins);
+		text = pinned.text;
+		refused.push(...pinned.review);
+	}
+	return {
+		text,
+		review: [...refused, ...linesMatching(text, codemod.review ?? [])]
+	};
+}
+/** One review line per line of `text` that a hint's pattern matches. */
+function linesMatching(text, hints) {
+	return hints.flatMap((hint) => text.split("\n").flatMap((line, index) => hint.pattern.test(line) ? [{
+		line: index + 1,
+		message: hint.message
+	}] : []));
+}
+//#endregion
+//#region src/cli/commands/codemod.ts
+const CODEMOD_ARGS = {
+	path: {
+		type: "positional",
+		required: false,
+		variadic: true,
+		description: "Files or directories to rewrite (default: the project)"
+	},
+	"dry-run": {
+		type: "boolean",
+		description: "Show the changes without writing them"
+	},
+	check: {
+		type: "boolean",
+		description: "Write nothing; exit 1 with a diff when a file would change"
+	}
+};
+const SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([
+	".ts",
+	".tsx",
+	".mts",
+	".cts",
+	".js",
+	".jsx",
+	".mjs",
+	".cjs"
+]);
+const SKIPPED_DIRS = /* @__PURE__ */ new Set([
+	"node_modules",
+	".git",
+	".next",
+	".turbo",
+	".vercel",
+	"dist",
+	"build",
+	"coverage"
+]);
+/**
+* Source, config and script files under `path`, skipping dependencies, build
+* output and `.d.ts` files.
+*/
+async function sourceFiles(path) {
+	const info = await stat(path).catch(() => void 0);
+	if (!info) return [];
+	if (info.isFile()) return [path];
+	const files = [];
+	for (const entry of await readdir(path, { withFileTypes: true })) {
+		const full = join(path, entry.name);
+		if (entry.isDirectory()) {
+			if (!SKIPPED_DIRS.has(entry.name)) files.push(...await sourceFiles(full));
+		} else if (SOURCE_EXTENSIONS.has(extname(entry.name)) && !entry.name.endsWith(".d.ts") || CONFIG_FILE.test(entry.name) || CLI_CALL_FILE.test(full) || SHELL_FILE.test(entry.name)) files.push(full);
+	}
+	return files.toSorted();
+}
+async function runCodemod(config, args, paint = plain) {
+	const [name, ...paths] = args._ ?? [];
+	const names = Object.entries(CODEMODS).map(([key, codemod]) => `  ${key.padEnd(5)} ${codemod.description}`).join("\n");
+	if (name === void 0) throw new CliError("usage", `Name a codemod:\n${names}`);
+	const codemod = CODEMODS[name];
+	if (!codemod) throw new CliError("usage", `Unknown codemod "${name}". Codemods:\n${names}`);
+	const roots = (paths.length > 0 ? paths : ["."]).map((path) => resolve(config.root, path));
+	const files = [...new Set((await Promise.all(roots.map(sourceFiles))).flat())];
+	const dryRun = args["dry-run"] === true;
+	const edits = [];
+	const review = [];
+	for (const file of files) {
+		const source = await readFile(file, "utf-8");
+		const result = applyCodemod(codemod, source, file);
+		const path = relative(config.root, file);
+		review.push(...result.review.map((hint) => ({
+			file: path,
+			...hint
+		})));
+		if (result.text !== source) edits.push({
+			path: file,
+			contents: result.text,
+			policy: "edit"
+		});
+	}
+	const plan = {
+		root: config.root,
+		regenerate: `better-supabase codemod ${codemod.name}`,
+		files: edits
+	};
+	const applied = await applyPlan(plan, args, paint);
+	const changed = changedFiles(applied);
+	if (applied.mode === "check" && applied.drift) return planResult(plan, applied, { data: { codemod: codemod.name } });
+	const lines = [...applied.mode === "write" ? [] : applied.diffs, changed.length === 0 ? `Nothing to change in ${String(files.length)} files.` : [...changeLines(applied), `${applied.mode === "write" ? "Updated" : "Would update"} ${String(changed.length)} of ${String(files.length)} files.`].join("\n")];
+	if (review.length > 0) lines.push("", "Check these by hand:", ...review.map((hint) => `  ${hint.file}:${String(hint.line)}: ${hint.message}`));
+	return {
+		code: 0,
+		output: lines.join("\n"),
+		data: {
+			codemod: codemod.name,
+			dryRun,
+			changed,
+			files: applied.changes,
+			review
+		}
+	};
+}
+/** The `codemod <name>` subcommand for one codemod in `CODEMODS`. */
+function codemodCommand(name) {
+	return defineCliCommand({
+		meta: commandMeta(`codemod ${name}`),
+		args: CODEMOD_ARGS,
+		runsWithInvalidConfig: true,
+		run: (args, { config, paint }) => runCodemod(config, {
+			...args,
+			_: [name, ...args._]
+		}, paint)
+	});
+}
+//#endregion
+export { codemodCommand };