better-supabase 0.8.0 → 0.10.0

package/dist/cli/module-migration-CLkZ8jpw.js

@@ -0,0 +1,592 @@
+import { n as CliError } from "./errors-Caiz_0so.js";
+import { t as importFresh } from "./fresh-import-BeYf9I3x.js";
+import { d as readSupabaseToml, f as schemaPaths, n as declarativeSchemasDir, p as sqlWorkflow } from "./supabase-toml-DjLgBYEo.js";
+import { n as applyPlan, r as changeLines } from "./files-DDvAwTko.js";
+import { existsSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { readFile, readdir } from "node:fs/promises";
+import { MODULE_ID_TYPES, adoptedColumnProblems, auditRegistrations, compileReadSets, declaredTables, extensionSchema, moduleIdType, moduleLayout, modulePermissionKeys, moduleSchemaExtensions, policyGrants, renderModules, resolveExposeColumns, resolveModules, rlsTables, sameTenantLayout, scopeProblems, templateFunctions } from "better-supabase/sql";
+import { isReadSet } from "better-supabase";
+//#region src/cli/authorization.ts
+/** How findings name the provider. */
+const providerLabel = (provider) => `the authorization provider (${provider.name})`;
+/**
+* The provider's tenant scope and its id type. A scope missing from
+* `scopes`, or without an id type this release renders, is invalid rather
+* than a guess.
+*/
+function tenantScope(provider, subject) {
+	const scope = provider.tenantScope;
+	const entry = provider.scopes.find((candidate) => candidate.name === scope);
+	const label = providerLabel(provider);
+	const problems = scopeProblems(provider);
+	if (problems.length > 0) return {
+		kind: "invalid",
+		problem: `The scopes of ${label} are inconsistent: ${problems.join("; ")}.`
+	};
+	if (!entry) return {
+		kind: "invalid",
+		problem: `authorization.tenantScope is "${scope}", but ${label} has the scopes ${provider.scopes.map((candidate) => candidate.name).join(", ") || "none"}.`
+	};
+	if (entry.idType === void 0) return {
+		kind: "invalid",
+		problem: `${label} gives scope "${scope}" no idType, so ${subject} can't tell its id type.`
+	};
+	const idType = moduleIdType(entry.idType);
+	if (idType === void 0) return {
+		kind: "invalid",
+		problem: `${label} gives scope "${scope}" the type ${entry.idType}, but ${subject} renders only ${MODULE_ID_TYPES.join(", ").replace(/, (?=[^,]*$)/, " or ")} ids.`
+	};
+	return {
+		kind: "ok",
+		scope,
+		idType
+	};
+}
+/** The provider's membership tables that can hold rows of `scope`. */
+const scopeMemberships = (provider, scope) => (provider.memberships ?? []).filter((source) => !("value" in source.scope) || source.scope.value === scope);
+/**
+* Provider mode when `entitlements.memberships` resolves to `"provider"`
+* (the default with `authorization`). The provider needs `memberIds` and
+* `memberIdsFor`, so the module never falls back to `tenant` on its own.
+*/
+function entitlementsMode(config) {
+	if (config.entitlements.memberships === "tenant") return { kind: "tenant" };
+	const provider = config.authorization;
+	if (!provider) return {
+		kind: "invalid",
+		problem: "entitlements.memberships is \"provider\", but the config has no authorization. Set authorization, or set entitlements.memberships to \"tenant\"."
+	};
+	const chosen = tenantScope(provider, "the entitlements module");
+	if (chosen.kind === "invalid") return chosen;
+	const { memberIds, memberIdsFor } = provider.functions;
+	if (memberIds === void 0 || memberIdsFor === void 0) return {
+		kind: "invalid",
+		problem: `${providerLabel(provider)} has no authorization.functions.${memberIds === void 0 ? "memberIds" : "memberIdsFor"}, which the entitlements module calls. Use a provider that sets both, or set entitlements.memberships to "tenant" to keep the tenant module's memberships.`
+	};
+	return {
+		kind: "provider",
+		provider: {
+			name: provider.name,
+			scope: chosen.scope,
+			idType: chosen.idType,
+			memberIds,
+			memberIdsFor,
+			memberships: scopeMemberships(provider, chosen.scope)
+		}
+	};
+}
+/**
+* The `provider` access model's functions, from `authorization`. `off` when
+* another model is chosen; without a provider the model is invalid, never a
+* default.
+*/
+function accessProviderMode(config) {
+	const access = config.blocks.access;
+	if (access?.model !== "provider") return { kind: "off" };
+	const provider = config.authorization;
+	if (!provider) return {
+		kind: "invalid",
+		problem: "blocks.access.model is \"provider\", but the config has no authorization. Set authorization, or choose another blocks.access.model."
+	};
+	const chosen = tenantScope(provider, "the provider access model");
+	if (chosen.kind === "invalid") return chosen;
+	const idType = access.idType === void 0 ? void 0 : moduleIdType(access.idType);
+	if (idType !== void 0 && idType !== chosen.idType) return {
+		kind: "invalid",
+		problem: `blocks.access.idType is "${access.idType}", but ${providerLabel(provider)} gives scope "${chosen.scope}" the type ${chosen.idType}. Set blocks.access.idType to "${chosen.idType}", or remove it.`
+	};
+	const { user, tenant } = provider.suspension ?? {};
+	return {
+		kind: "provider",
+		access: {
+			name: provider.name,
+			scope: chosen.scope,
+			scopes: provider.scopes.map((scope) => scope.name),
+			idType: chosen.idType,
+			functions: provider.functions,
+			...user || tenant ? { suspension: {
+				...user ? { user } : {},
+				...tenant ? { tenant } : {}
+			} } : {},
+			...provider.roleSources && provider.roleSources.length > 0 ? { roleSources: provider.roleSources } : {},
+			...provider.approvals?.distinctApprover === true ? { approvals: { distinctApprover: true } } : {},
+			...provider.operations && Object.keys(provider.operations).length > 0 ? { operations: provider.operations } : {}
+		}
+	};
+}
+/**
+* `complete` when the provider marks the key `sqlComplete: true`. A key
+* without the flag is unknown, and so is every key when the provider lists
+* no permissions.
+*/
+function keyStatus(provider, key) {
+	if (!provider.permissions) return "unknown";
+	const entry = provider.permissions.find((permission) => permission.key === key);
+	if (!entry) return "missing";
+	if (entry.sqlComplete === void 0) return "unknown";
+	return entry.sqlComplete ? "complete" : "incomplete";
+}
+const INCOMPLETE_FIX = "Use the provider's own policies for it, or a permission its SQL functions answer for completely.";
+const UNKNOWN_FIX = "Have the provider set sqlComplete on every entry of authorization.permissions.";
+/**
+* Why the provider's SQL functions can't be trusted with `key`, or
+* `undefined` when it is marked `sqlComplete: true`. Unknown and missing
+* keys count as unsafe.
+*/
+function unsafeKey(provider, key) {
+	const status = keyStatus(provider, key);
+	switch (status) {
+		case "complete": return;
+		case "incomplete": return {
+			status,
+			reason: `has conditions ${providerLabel(provider)}'s SQL functions don't check (sqlComplete: false)`,
+			fix: INCOMPLETE_FIX
+		};
+		case "unknown": return {
+			status,
+			reason: provider.permissions ? "has no sqlComplete flag in authorization.permissions, so whether the SQL functions answer for it completely is unknown" : "can't be checked: authorization.permissions is not set, so whether the SQL functions answer for it completely is unknown",
+			fix: UNKNOWN_FIX
+		};
+		case "missing": return {
+			status,
+			reason: "is not in authorization.permissions",
+			fix: UNKNOWN_FIX
+		};
+		default: return status;
+	}
+}
+/**
+* Checks the keys the SQL modules pass to the provider's functions against
+* `authorization.permissions`, with the statuses bucket policies use: only
+* `sqlComplete: true` passes.
+*/
+function moduleKeyProblems(provider, keys) {
+	if (keys.length === 0) return [];
+	if (!provider.permissions) return [{
+		target: "authorization.permissions",
+		message: `The provider access model passes ${keys.length} module permission keys to ${providerLabel(provider)}'s SQL functions, but authorization.permissions is not set, so whether they answer for them completely is unknown. Use a provider that lists its permissions.`
+	}];
+	return keys.flatMap((entry) => {
+		const problem = unsafeKey(provider, entry.key);
+		if (!problem) return [];
+		const fn = entry.scope === "platform" ? "authorization.functions.isPlatform" : "authorization.functions.idsWith";
+		const setting = entry.setting ?? `blocks.${entry.module}.permissions.${entry.action}`;
+		const fix = problem.status === "incomplete" ? `The provider's SQL functions check role and scope, not the key's other conditions, so the module would grant it everywhere in the scope. Set ${setting} to a permission marked sqlComplete: true.` : `${problem.fix} If the provider doesn't define it, set ${setting} to a key it lists.`;
+		return [{
+			target: setting,
+			message: `The ${entry.module} module checks "${entry.key}" (${entry.action}) with ${fn}, but it ${problem.reason}. ${fix}`
+		}];
+	});
+}
+const requirementsOf = (functions, scope, templates) => templates.flatMap(([template, role]) => {
+	const sql = functions[template];
+	return sql === void 0 ? [] : templateFunctions(sql, scope).map((fn) => ({
+		function: fn,
+		template,
+		role
+	}));
+});
+/** The functions the `provider` access model calls, as `authenticated`. */
+const accessRequirements = (access) => requirementsOf(access.functions, access.scope, [["idsWith", "authenticated"], ["isPlatform", "authenticated"]]);
+/**
+* The functions the `entitlements` module calls for the tenant scope:
+* `memberIds` from `has_entitlement` as `authenticated`, and `memberIdsFor`
+* from `feature_claims`, which the access token hook runs as
+* `supabase_auth_admin`.
+*/
+const entitlementRequirements = (provider) => [...templateFunctions(provider.memberIds, provider.scope).map((fn) => ({
+	kind: "member",
+	function: fn,
+	template: "memberIds",
+	caller: "has_entitlement",
+	role: "authenticated"
+})), ...templateFunctions(provider.memberIdsFor, provider.scope).map((fn) => ({
+	kind: "member-for",
+	function: fn,
+	template: "memberIdsFor",
+	caller: "feature_claims",
+	role: "supabase_auth_admin"
+}))];
+//#endregion
+//#region src/cli/read-sets.ts
+/** Every read set exported by the modules in `config.readSets`. */
+async function loadReadSets(config) {
+	const sets = [];
+	for (const entry of config.readSets) {
+		const loaded = await importFresh(resolve(config.root, entry));
+		const found = Object.values(loaded).filter(isReadSet);
+		if (found.length === 0) throw new CliError("invalid_input", `${entry} exports no read set (defineReadSet)`);
+		for (const set of found) if (!sets.includes(set)) sets.push(set);
+	}
+	return sets;
+}
+/** The compiled functions for `config.readSets`; empty when none are configured. */
+async function compiledReadSets(config) {
+	if (config.readSets.length === 0) return [];
+	return compileReadSets(await loadReadSets(config));
+}
+//#endregion
+//#region src/cli/sql-layout.ts
+/** The folder the module data files sit next to, for the project's workflow. */
+async function schemasDirOf(config) {
+	const toml = await readSupabaseToml(config.root);
+	return declarativeSchemasDir(toml, sqlWorkflow(config, toml));
+}
+/** The declarative schema files, then the migrations oldest first. */
+async function schemaTexts(config) {
+	const toml = await readSupabaseToml(config.root);
+	const migrations = resolve(config.root, migrationsDir(config));
+	const paths = [...(await schemaPaths(config.root, toml, sqlWorkflow(config, toml))).files, ...existsSync(migrations) ? (await readdir(migrations)).filter((name) => name.endsWith(".sql")).toSorted().map((name) => join(migrations, name)) : []];
+	return Promise.all(paths.map(async (path) => ({ text: await readFile(resolve(config.root, path), "utf-8") })));
+}
+async function declarativeTexts(config) {
+	const toml = await readSupabaseToml(config.root);
+	const { files } = await schemaPaths(config.root, toml, sqlWorkflow(config, toml));
+	if (files.length === 0) return schemaTexts(config);
+	return Promise.all(files.map(async (path) => ({ text: await readFile(resolve(config.root, path), "utf-8") })));
+}
+/**
+* The `better_supabase.audit(...)` calls in the declarative schemas, then
+* the migrations oldest first, so a later call or `unaudit` wins.
+*/
+async function auditedTables(config) {
+	return auditRegistrations(await schemaTexts(config));
+}
+/**
+* The layout `sql sync` and doctor render the module files with, so both
+* see the same grants, session policies, audit triggers and vector schema.
+*/
+async function moduleLayoutFor(config, input) {
+	const resolved = new Set(resolveModules(input.names, { ...input.entitlementsProvider ? { entitlementsProvider: input.entitlementsProvider } : {} }).map((module) => module.name));
+	const adopted = adoptedColumnProblems(config.blocks, await declarativeTexts(config), config.schemas);
+	if (adopted.length > 0) throw new TypeError(adopted.join("\n"));
+	const fromPolicies = resolved.has("grants") && config.blocks["grants"]?.options?.["fromPolicies"] === true;
+	const sessionPolicies = resolved.has("sessions") && config.blocks["sessions"]?.options?.["policies"] === true;
+	const sameTenant = config.blocks["tenant"]?.options?.["sameTenant"];
+	const autoSameTenant = resolved.has("tenant") && typeof sameTenant === "object" && sameTenant !== null && "auto" in sameTenant && sameTenant.auto === true;
+	const base = moduleLayout(config, input.testsDir, input.readSets ?? [], input.entitlementsProvider, input.accessProvider, input.permissionCatalog);
+	const grants = base.grants === void 0 ? void 0 : resolveExposeColumns(base.grants, await declarativeTexts(config), config.schemas);
+	return {
+		...base,
+		...grants === void 0 ? {} : { grants },
+		schemasDir: await schemasDirOf(config),
+		...resolved.has("audit") ? { auditedTables: await auditedTables(config) } : {},
+		...resolved.has("vector-search") ? vectorSchemaOf(await schemaTexts(config)) : {},
+		...fromPolicies ? { policyGrants: policyGrants(await declarativeTexts(config), config.schemas) } : {},
+		...fromPolicies ? { rlsTables: rlsTables(await declarativeTexts(config), config.schemas) } : {},
+		...autoSameTenant ? sameTenantLayout(await declarativeTexts(config), config.schemas) : {},
+		...fromPolicies || sessionPolicies ? { declaredTables: declaredTables(await declarativeTexts(config), config.schemas) } : {}
+	};
+}
+function vectorSchemaOf(sources) {
+	const schema = extensionSchema(sources, "vector");
+	return schema === void 0 ? {} : { vectorSchema: schema };
+}
+/**
+* The folder that holds both the project root and `sql.dir`: the root, or
+* an ancestor when `sql.dir` points at a shared stack. The `sql` commands
+* write SQL files only inside it.
+*/
+function sqlRoot(config) {
+	const dir = resolve(config.root, config.sql.dir);
+	let stop = resolve(config.root);
+	while (dir !== stop && !dir.startsWith(stop + sep) && dirname(stop) !== stop) stop = dirname(stop);
+	return stop;
+}
+/**
+* A plan for files under the project root or `sql.dir`, with paths relative
+* to the project root.
+*/
+function sqlPlan(config, plan) {
+	return {
+		...plan,
+		root: sqlRoot(config),
+		base: config.root,
+		files: plan.files.map((file) => ({
+			...file,
+			path: resolve(config.root, file.path)
+		})),
+		...plan.remove ? { remove: plan.remove.map((path) => resolve(config.root, path)) } : {}
+	};
+}
+/**
+* The migrations folder next to the `config.toml` found walking up from
+* `sql.dir`, relative to the root; `supabase/migrations` without one. The
+* walk stops where `sql.dir` and the root meet, so a `sql.dir` outside the
+* project (a shared stack in a monorepo) finds that stack's folder.
+*/
+function migrationsDir(config) {
+	const root = resolve(config.root);
+	let dir = resolve(root, config.sql.dir);
+	const stop = sqlRoot(config);
+	for (;;) {
+		if (existsSync(join(dir, "config.toml"))) return relative(root, join(dir, "migrations")).replaceAll("\\", "/");
+		if (dir === stop || dirname(dir) === dir) break;
+		dir = dirname(dir);
+	}
+	return "supabase/migrations";
+}
+//#endregion
+//#region src/cli/sql/providers.ts
+/** Modules that fill the `memberships` claim, which a provider's hook may own. */
+const MEMBERSHIP_CLAIM_MODULES = /* @__PURE__ */ new Set(["tenant"]);
+/** Whether the provider's access token hook writes the `memberships` claim itself. */
+const providerOwnsMemberships = (config) => config.authorization?.tokenHook?.ownedClaims.includes("memberships") ?? false;
+/**
+* The provider's memberships for the `entitlements` module. When `names`
+* resolve to that module, an invalid mode (no provider, a scope it lacks,
+* an unknown id type) throws instead of falling back to the tenant module.
+* Without `names` (`sql list`) it only describes the modules, so it doesn't.
+*/
+function entitlementsProviderFor(config, names) {
+	const mode = entitlementsMode(config);
+	switch (mode.kind) {
+		case "tenant": return;
+		case "provider": return mode.provider;
+		case "invalid":
+			if (names === void 0 || !resolveModules(names, {}).some((module) => module.name === "entitlements")) return;
+			throw new TypeError(mode.problem);
+		default: return mode;
+	}
+}
+/**
+* The provider for the `access` module's `provider` model. When `names`
+* resolve to `access`, an invalid mode throws, and so does a module
+* permission key the provider doesn't mark `sqlComplete: true`. `sql list`
+* (no `names`) doesn't render, so it doesn't throw.
+*/
+function accessProviderFor(config, names) {
+	const mode = accessProviderMode(config);
+	const renders = names !== void 0 && resolveModules(names, {}).some((module) => module.name === "access");
+	switch (mode.kind) {
+		case "off": return;
+		case "provider": {
+			if (!renders || !config.authorization) return mode.access;
+			const problems = moduleKeyProblems(config.authorization, modulePermissionKeys(config.blocks, names));
+			if (problems.length > 0) throw new TypeError(problems.map((problem) => problem.message).join("\n"));
+			return mode.access;
+		}
+		case "invalid":
+			if (!renders) return;
+			throw new TypeError(mode.problem);
+		default: return mode;
+	}
+}
+/** The provider's permission keys, for `api-keys` scopes. */
+const permissionKeysFor = (config) => config.authorization?.permissions?.map((permission) => permission.key);
+async function layout(config, args, names) {
+	return {
+		...moduleLayout(config, args["tests-dir"], [], entitlementsProviderFor(config, names), accessProviderFor(config, names), permissionKeysFor(config)),
+		schemasDir: await schemasDirOf(config)
+	};
+}
+/**
+* The layout, with `config.readSets` compiled when `names` includes
+* `read-sets`.
+*/
+async function layoutFor(config, args, names) {
+	const entitlementsProvider = entitlementsProviderFor(config, names);
+	const resolved = new Set(resolveModules(names, { ...entitlementsProvider ? { entitlementsProvider } : {} }).map((module) => module.name));
+	const accessProvider = accessProviderFor(config, names);
+	return moduleLayoutFor(config, {
+		names,
+		testsDir: args["tests-dir"],
+		readSets: resolved.has("read-sets") ? await compiledReadSets(config) : [],
+		...entitlementsProvider ? { entitlementsProvider } : {},
+		...accessProvider ? { accessProvider } : {},
+		permissionCatalog: permissionKeysFor(config)
+	});
+}
+//#endregion
+//#region src/cli/sql/migrations.ts
+/** `YYYYMMDDHHMMSS` in UTC, the Supabase CLI's migration prefix. */
+const migrationStamp = (now) => now.toISOString().replaceAll(/[-:T]/g, "").slice(0, 14);
+/**
+* A stamp for `now`, or one second after the newest migration when that one
+* has the same stamp or a later one: the Supabase CLI keys migrations by
+* stamp, and the data has to run after the schema.
+*/
+function stampAfter(migrations, now) {
+	const newest = migrations.map((name) => /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})(?!\d)/.exec(name)).filter((match) => match !== null).map((match) => Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3]), Number(match[4]), Number(match[5]), Number(match[6]))).reduce((max, time) => Math.max(max, time), Number.NEGATIVE_INFINITY);
+	const at = Math.floor(now.getTime() / 1e3) * 1e3;
+	return migrationStamp(new Date(Math.max(at, newest + 1e3)));
+}
+const EXTENSIONS_SUFFIX = "_better_supabase_extensions.sql";
+const MIGRATION_EXTENSION = /^\s*create\s+extension\s+(?:if\s+not\s+exists\s+)?"?([a-z_][a-z0-9_]*)"?/gim;
+async function unmigratedExtensions(config, files) {
+	const dir = migrationsDir(config);
+	const existing = await readdir(resolve(config.root, dir)).catch(() => []);
+	const created = /* @__PURE__ */ new Set();
+	for (const name of existing) {
+		if (!name.endsWith(".sql") || name.endsWith(DATA_SUFFIX)) continue;
+		const text = await readFile(resolve(config.root, dir, name), "utf-8");
+		for (const match of text.matchAll(MIGRATION_EXTENSION)) created.add(match[1].toLowerCase());
+	}
+	return {
+		dir,
+		existing,
+		missing: moduleSchemaExtensions(files).filter((extension) => !created.has(extension.name))
+	};
+}
+async function writeExtensionsMigration(config, files, dryRun, now) {
+	const { dir, existing, missing } = await unmigratedExtensions(config, files);
+	if (missing.length === 0) return [];
+	const path = `${dir}/${stampAfter(existing, /* @__PURE__ */ new Date(now().getTime() - 1e3))}${EXTENSIONS_SUFFIX}`;
+	const applied = await applyPlan(sqlPlan(config, {
+		regenerate: "better-supabase sql sync",
+		files: [{
+			path,
+			contents: `-- better-supabase sql: the extensions of ${missing.map((extension) => extension.name).join(", ")}, created before the schema migration that needs them.\n\n${missing.map((extension) => extension.statement).join("\n")}\n`
+		}]
+	}), { "dry-run": dryRun });
+	return [...changeLines(applied), ...dryRun ? [] : ["It creates the extensions the module schemas need, so create the schema migration after it."]];
+}
+const DATA_NEXT = "The better-supabase-data files hold rows and settings a schema diff skips: after the schema migration, run `better-supabase sql data`.";
+const DATA_SUFFIX = "_better_supabase_module_data.sql";
+/**
+* Writes the data files of `blocks` into one migration, meant to run after
+* the schema migration that creates their tables. Every statement is
+* idempotent, so the migration carries all of them, not only the changes.
+*/
+async function dataMigration(config, args, now) {
+	if (config.blockNames.length === 0) return {
+		code: 0,
+		output: "blocks is empty; nothing to write.",
+		data: { wrote: false }
+	};
+	if (sqlWorkflow(config, await readSupabaseToml(config.root)) === "migrations") return {
+		code: 0,
+		output: "sql.workflow is 'migrations', so `better-supabase sql sync` already writes the rows into the module migration; nothing to write.",
+		data: { wrote: false }
+	};
+	const rendered = renderModules(config.blockNames, await layoutFor(config, args, config.blockNames));
+	const { missing } = await unmigratedExtensions(config, rendered);
+	if (missing.length > 0) return {
+		code: 1,
+		error: [`No migration before the data migration creates ${missing.map((extension) => extension.name).join(", ")}, and the schema migration needs ${missing.length === 1 ? "it" : "them"} while it applies.`, "Run `better-supabase sql sync` to write the extensions migration, then create the schema migration again after it."].join("\n")
+	};
+	const files = rendered.filter((file) => file.kind === "data");
+	const contents = `-- better-supabase sql data: the rows and settings of ${files.map((file) => file.module).join(", ")}, which a schema diff skips.\n\n${files.map((file) => file.contents.trim()).join("\n\n")}\n`;
+	const dir = migrationsDir(config);
+	const existing = await readdir(resolve(config.root, dir)).catch(() => []);
+	const latest = existing.toSorted().findLast((name) => name.endsWith(DATA_SUFFIX));
+	if (latest !== void 0 && await readFile(resolve(config.root, dir, latest), "utf-8") === contents) return {
+		code: 0,
+		output: `${dir}/${latest} already has these rows; nothing to write.`,
+		data: {
+			file: `${dir}/${latest}`,
+			wrote: false
+		}
+	};
+	const path = `${dir}/${stampAfter(existing, now())}${DATA_SUFFIX}`;
+	const applied = await applyPlan(sqlPlan(config, {
+		regenerate: "better-supabase sql data",
+		files: [{
+			path,
+			contents
+		}]
+	}), { "dry-run": args["dry-run"] });
+	return {
+		code: 0,
+		output: changeLines(applied).join("\n"),
+		data: {
+			file: path,
+			wrote: applied.mode === "write",
+			files: applied.changes
+		}
+	};
+}
+//#endregion
+//#region src/cli/sql/module-migration.ts
+/** The migration the migrations workflow writes the SQL modules into. */
+const MODULES_SUFFIX = "_better_supabase_modules.sql";
+/** The migration `gen` writes the read-sets module into under the migrations workflow. */
+const READ_SETS_SUFFIX = "_better_supabase_read_sets.sql";
+const UPGRADE_START = "-- @bs-upgrade-start";
+const UPGRADE_END = "-- @bs-upgrade-end";
+/** Whether the project runs the migrations workflow, with no declarative schemas. */
+async function writesMigrations(config) {
+	return sqlWorkflow(config, await readSupabaseToml(config.root)) === "migrations";
+}
+/**
+* One migration that holds, in order, the extensions, the upgrade steps,
+* each module's schema body with its `@bs-module` header, the realtime topic
+* policies and the data statements. Every statement is re-runnable, so a
+* later migration carries all of them, not only the changes.
+*/
+function renderModuleMigration(parts) {
+	const schema = parts.files.filter((file) => file.kind === "schema");
+	const data = parts.files.filter((file) => file.kind === "data");
+	const modules = [...new Set(schema.map((file) => file.module))];
+	const extensions = moduleSchemaExtensions(parts.files);
+	const upgrade = parts.upgrade ?? [];
+	return `${[
+		[
+			`-- better-supabase sql: ${modules.length > 0 ? `the SQL modules ${modules.join(", ")}` : "the realtime topic policies"}, in one migration (sql.workflow: 'migrations').`,
+			"-- Managed by `better-supabase sql`, which writes a new migration when they change.",
+			"-- Change them through `blocks` in better-supabase.config.ts and the module's SQL hooks."
+		].join("\n"),
+		...extensions.length > 0 ? [extensions.map((extension) => extension.statement).join("\n")] : [],
+		...upgrade.length > 0 ? [[
+			UPGRADE_START,
+			...upgrade,
+			UPGRADE_END
+		].join("\n\n")] : [],
+		...schema.map((file) => file.contents.trim()),
+		...parts.topics === void 0 ? [] : [parts.topics.trim()],
+		...data.map((file) => file.contents.trim())
+	].join("\n\n")}\n`;
+}
+/** The migration without its upgrade steps and package versions, which a later one doesn't repeat. */
+function comparable(text) {
+	return text.replaceAll("\r\n", "\n").replace(new RegExp(`\\n\\n${UPGRADE_START}\\n[\\s\\S]*?\\n${UPGRADE_END}`), "").replaceAll(/^(-- better-supabase module: [^\n(]*?)(?: \([^)]*\))?$/gm, "$1");
+}
+/** Whether two module migrations hold the same modules. */
+const sameModuleMigration = (current, expected) => current !== void 0 && comparable(current) === comparable(expected);
+/** Whether a module migration holds `contents` (one module's file) unchanged. */
+const migrationHolds = (text, contents) => comparable(text).includes(comparable(contents.trim()));
+/** The newest migration that ends in `suffix`, with its text. */
+async function latestMigration(config, suffix) {
+	const dir = migrationsDir(config);
+	const latest = (await readdir(resolve(config.root, dir)).catch(() => [])).toSorted().findLast((name) => name.endsWith(suffix));
+	if (latest === void 0) return;
+	return {
+		path: `${dir}/${latest}`,
+		text: await readFile(resolve(config.root, dir, latest), "utf-8")
+	};
+}
+const MODULE_MARKERS = /^-- @bs-module ([a-z0-9-]+)@(\d+)\b/gm;
+/** The modules and versions a module migration installs, from its `@bs-module` lines. */
+function migrationModules(text) {
+	return new Map([...text.matchAll(MODULE_MARKERS)].map((match) => [match[1], Number(match[2])]));
+}
+/**
+* Writes `contents` as a new migration ending in `suffix`, unless the newest
+* one already holds the same statements. `force` writes it anyway, for
+* upgrade steps that have to run once.
+*/
+async function writeLatestMigration(config, suffix, contents, options) {
+	const latest = await latestMigration(config, suffix);
+	if (options.force !== true && latest !== void 0 && sameModuleMigration(latest.text, contents)) return {
+		path: latest.path,
+		wrote: false,
+		line: `Unchanged ${latest.path} (it has these statements)`
+	};
+	const dir = migrationsDir(config);
+	const path = `${dir}/${stampAfter(await readdir(resolve(config.root, dir)).catch(() => []), options.now)}${suffix}`;
+	const applied = await applyPlan(sqlPlan(config, {
+		regenerate: "better-supabase sql sync",
+		files: [{
+			path,
+			contents
+		}]
+	}), { "dry-run": options.dryRun });
+	return {
+		path,
+		wrote: applied.mode === "write",
+		line: changeLines(applied).join("\n")
+	};
+}
+//#endregion
+export { accessRequirements as C, providerLabel as D, moduleKeyProblems as E, unsafeKey as O, accessProviderMode as S, entitlementsMode as T, providerOwnsMemberships as _, migrationModules as a, sqlPlan as b, writeLatestMigration as c, dataMigration as d, migrationStamp as f, layoutFor as g, layout as h, migrationHolds as i, writesMigrations as l, MEMBERSHIP_CLAIM_MODULES as m, READ_SETS_SUFFIX as n, renderModuleMigration as o, writeExtensionsMigration as p, latestMigration as r, sameModuleMigration as s, MODULES_SUFFIX as t, DATA_NEXT as u, migrationsDir as v, entitlementRequirements as w, compiledReadSets as x, moduleLayoutFor as y };