better-supabase 0.8.0 → 0.9.0

package/dist/cli/command-CK9Cn8HV.js

@@ -0,0 +1,836 @@
+import { n as CliError } from "./errors-Caiz_0so.js";
+import { parseArgs } from "node:util";
+//#region ../../node_modules/.pnpm/citty@0.2.2/node_modules/citty/dist/_chunks/libs/scule.mjs
+const NUMBER_CHAR_RE = /\d/;
+const STR_SPLITTERS = [
+	"-",
+	"_",
+	"/",
+	"."
+];
+function isUppercase(char = "") {
+	if (NUMBER_CHAR_RE.test(char)) return;
+	return char !== char.toLowerCase();
+}
+function splitByCase(str, separators) {
+	const splitters = separators ?? STR_SPLITTERS;
+	const parts = [];
+	if (!str || typeof str !== "string") return parts;
+	let buff = "";
+	let previousUpper;
+	let previousSplitter;
+	for (const char of str) {
+		const isSplitter = splitters.includes(char);
+		if (isSplitter === true) {
+			parts.push(buff);
+			buff = "";
+			previousUpper = void 0;
+			continue;
+		}
+		const isUpper = isUppercase(char);
+		if (previousSplitter === false) {
+			if (previousUpper === false && isUpper === true) {
+				parts.push(buff);
+				buff = char;
+				previousUpper = isUpper;
+				continue;
+			}
+			if (previousUpper === true && isUpper === false && buff.length > 1) {
+				const lastChar = buff.at(-1);
+				parts.push(buff.slice(0, Math.max(0, buff.length - 1)));
+				buff = lastChar + char;
+				previousUpper = isUpper;
+				continue;
+			}
+		}
+		buff += char;
+		previousUpper = isUpper;
+		previousSplitter = isSplitter;
+	}
+	parts.push(buff);
+	return parts;
+}
+function upperFirst(str) {
+	return str ? str[0].toUpperCase() + str.slice(1) : "";
+}
+function lowerFirst(str) {
+	return str ? str[0].toLowerCase() + str.slice(1) : "";
+}
+function pascalCase(str, opts) {
+	return str ? (Array.isArray(str) ? str : splitByCase(str)).map((p) => upperFirst(opts?.normalize ? p.toLowerCase() : p)).join("") : "";
+}
+function camelCase(str, opts) {
+	return lowerFirst(pascalCase(str || "", opts));
+}
+function kebabCase(str, joiner) {
+	return str ? (Array.isArray(str) ? str : splitByCase(str)).map((p) => p.toLowerCase()).join(joiner ?? "-") : "";
+}
+//#endregion
+//#region ../../node_modules/.pnpm/citty@0.2.2/node_modules/citty/dist/index.mjs
+function toArray(val) {
+	if (Array.isArray(val)) return val;
+	return val === void 0 ? [] : [val];
+}
+function resolveValue(input) {
+	return typeof input === "function" ? input() : input;
+}
+var CLIError = class extends Error {
+	code;
+	constructor(message, code) {
+		super(message);
+		this.name = "CLIError";
+		this.code = code;
+	}
+};
+function parseRawArgs(args = [], opts = {}) {
+	const booleans = new Set(opts.boolean || []);
+	const strings = new Set(opts.string || []);
+	const aliasMap = opts.alias || {};
+	const defaults = opts.default || {};
+	const aliasToMain = /* @__PURE__ */ new Map();
+	const mainToAliases = /* @__PURE__ */ new Map();
+	for (const [key, value] of Object.entries(aliasMap)) {
+		const targets = value;
+		for (const target of targets) {
+			aliasToMain.set(key, target);
+			if (!mainToAliases.has(target)) mainToAliases.set(target, []);
+			mainToAliases.get(target).push(key);
+			aliasToMain.set(target, key);
+			if (!mainToAliases.has(key)) mainToAliases.set(key, []);
+			mainToAliases.get(key).push(target);
+		}
+	}
+	const options = {};
+	function getType(name) {
+		if (booleans.has(name)) return "boolean";
+		const aliases = mainToAliases.get(name) || [];
+		for (const alias of aliases) if (booleans.has(alias)) return "boolean";
+		return "string";
+	}
+	function isStringType(name) {
+		if (strings.has(name)) return true;
+		const aliases = mainToAliases.get(name) || [];
+		for (const alias of aliases) if (strings.has(alias)) return true;
+		return false;
+	}
+	const allOptions = /* @__PURE__ */ new Set([
+		...booleans,
+		...strings,
+		...Object.keys(aliasMap),
+		...Object.values(aliasMap).flat(),
+		...Object.keys(defaults)
+	]);
+	for (const name of allOptions) if (!options[name]) options[name] = {
+		type: getType(name),
+		default: defaults[name]
+	};
+	for (const [alias, main] of aliasToMain.entries()) if (alias.length === 1 && options[main] && !options[main].short) options[main].short = alias;
+	const processedArgs = [];
+	const negatedFlags = {};
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--") {
+			processedArgs.push(...args.slice(i));
+			break;
+		}
+		if (arg.startsWith("--no-")) {
+			const flagName = arg.slice(5);
+			negatedFlags[flagName] = true;
+			continue;
+		}
+		processedArgs.push(arg);
+	}
+	let parsed;
+	try {
+		parsed = parseArgs({
+			args: processedArgs,
+			options: Object.keys(options).length > 0 ? options : void 0,
+			allowPositionals: true,
+			strict: false
+		});
+	} catch {
+		parsed = {
+			values: {},
+			positionals: processedArgs
+		};
+	}
+	const out = { _: [] };
+	out._ = parsed.positionals;
+	for (const [key, value] of Object.entries(parsed.values)) {
+		let coerced = value;
+		if (getType(key) === "boolean" && typeof value === "string") coerced = value !== "false";
+		else if (isStringType(key) && typeof value === "boolean") coerced = "";
+		out[key] = coerced;
+	}
+	for (const [name] of Object.entries(negatedFlags)) {
+		out[name] = false;
+		const mainName = aliasToMain.get(name);
+		if (mainName) out[mainName] = false;
+		const aliases = mainToAliases.get(name);
+		if (aliases) for (const alias of aliases) out[alias] = false;
+	}
+	for (const [alias, main] of aliasToMain.entries()) {
+		if (out[alias] !== void 0 && out[main] === void 0) out[main] = out[alias];
+		if (out[main] !== void 0 && out[alias] === void 0) out[alias] = out[main];
+		if (out[alias] !== out[main] && defaults[main] === out[main]) out[main] = out[alias];
+	}
+	return out;
+}
+const noColor = /* @__PURE__ */ (() => {
+	const env = globalThis.process?.env ?? {};
+	return env.NO_COLOR === "1" || env.TERM === "dumb" || env.TEST || env.CI;
+})();
+const _c = (c, r = 39) => (t) => noColor ? t : `\u001B[${c}m${t}\u001B[${r}m`;
+const cyan = /* @__PURE__ */ _c(36);
+function parseArgs$2(rawArgs, argsDef) {
+	const parseOptions = {
+		boolean: [],
+		string: [],
+		alias: {},
+		default: {}
+	};
+	const args = resolveArgs(argsDef);
+	for (const arg of args) {
+		if (arg.type === "positional") continue;
+		if (arg.type === "string" || arg.type === "enum") parseOptions.string.push(arg.name);
+		else if (arg.type === "boolean") parseOptions.boolean.push(arg.name);
+		if (arg.default !== void 0) parseOptions.default[arg.name] = arg.default;
+		if (arg.alias) parseOptions.alias[arg.name] = arg.alias;
+		const camelName = camelCase(arg.name);
+		const kebabName = kebabCase(arg.name);
+		if (camelName !== arg.name || kebabName !== arg.name) {
+			const existingAliases = toArray(parseOptions.alias[arg.name] || []);
+			if (camelName !== arg.name && !existingAliases.includes(camelName)) existingAliases.push(camelName);
+			if (kebabName !== arg.name && !existingAliases.includes(kebabName)) existingAliases.push(kebabName);
+			if (existingAliases.length > 0) parseOptions.alias[arg.name] = existingAliases;
+		}
+	}
+	const parsed = parseRawArgs(rawArgs, parseOptions);
+	const [...positionalArguments] = parsed._;
+	const parsedArgsProxy = new Proxy(parsed, { get(target, prop) {
+		return target[prop] ?? target[camelCase(prop)] ?? target[kebabCase(prop)];
+	} });
+	for (const [, arg] of args.entries()) if (arg.type === "positional") {
+		const nextPositionalArgument = positionalArguments.shift();
+		if (nextPositionalArgument !== void 0) parsedArgsProxy[arg.name] = nextPositionalArgument;
+		else if (arg.default === void 0 && arg.required !== false) throw new CLIError(`Missing required positional argument: ${arg.name.toUpperCase()}`, "EARG");
+		else parsedArgsProxy[arg.name] = arg.default;
+	} else if (arg.type === "enum") {
+		const argument = parsedArgsProxy[arg.name];
+		const options = arg.options || [];
+		if (argument !== void 0 && options.length > 0 && !options.includes(argument)) throw new CLIError(`Invalid value for argument: ${cyan(`--${arg.name}`)} (${cyan(argument)}). Expected one of: ${options.map((o) => cyan(o)).join(", ")}.`, "EARG");
+	} else if (arg.required && parsedArgsProxy[arg.name] === void 0) throw new CLIError(`Missing required argument: --${arg.name}`, "EARG");
+	return parsedArgsProxy;
+}
+function resolveArgs(argsDef) {
+	const args = [];
+	for (const [name, argDef] of Object.entries(argsDef || {})) args.push({
+		...argDef,
+		name,
+		alias: toArray(argDef.alias)
+	});
+	return args;
+}
+async function resolvePlugins(plugins) {
+	return Promise.all(plugins.map((p) => resolveValue(p)));
+}
+function defineCommand(def) {
+	return def;
+}
+async function runCommand(cmd, opts) {
+	const cmdArgs = await resolveValue(cmd.args || {});
+	const parsedArgs = parseArgs$2(opts.rawArgs, cmdArgs);
+	const context = {
+		rawArgs: opts.rawArgs,
+		args: parsedArgs,
+		data: opts.data,
+		cmd
+	};
+	const plugins = await resolvePlugins(cmd.plugins ?? []);
+	let result;
+	let runError;
+	try {
+		for (const plugin of plugins) await plugin.setup?.(context);
+		if (typeof cmd.setup === "function") await cmd.setup(context);
+		const subCommands = await resolveValue(cmd.subCommands);
+		if (subCommands && Object.keys(subCommands).length > 0) {
+			const subCommandArgIndex = findSubCommandIndex(opts.rawArgs, cmdArgs);
+			const explicitName = opts.rawArgs[subCommandArgIndex];
+			if (explicitName) {
+				const subCommand = await _findSubCommand(subCommands, explicitName);
+				if (!subCommand) throw new CLIError(`Unknown command ${cyan(explicitName)}`, "E_UNKNOWN_COMMAND");
+				await runCommand(subCommand, { rawArgs: opts.rawArgs.slice(subCommandArgIndex + 1) });
+			} else {
+				const defaultSubCommand = await resolveValue(cmd.default);
+				if (defaultSubCommand) {
+					if (cmd.run) throw new CLIError(`Cannot specify both 'run' and 'default' on the same command.`, "E_DEFAULT_CONFLICT");
+					const subCommand = await _findSubCommand(subCommands, defaultSubCommand);
+					if (!subCommand) throw new CLIError(`Default sub command ${cyan(defaultSubCommand)} not found in subCommands.`, "E_UNKNOWN_COMMAND");
+					await runCommand(subCommand, { rawArgs: opts.rawArgs });
+				} else if (!cmd.run) throw new CLIError(`No command specified.`, "E_NO_COMMAND");
+			}
+		}
+		if (typeof cmd.run === "function") result = await cmd.run(context);
+	} catch (error) {
+		runError = error;
+	}
+	const cleanupErrors = [];
+	if (typeof cmd.cleanup === "function") try {
+		await cmd.cleanup(context);
+	} catch (error) {
+		cleanupErrors.push(error);
+	}
+	for (const plugin of [...plugins].reverse()) try {
+		await plugin.cleanup?.(context);
+	} catch (error) {
+		cleanupErrors.push(error);
+	}
+	if (runError) throw runError;
+	if (cleanupErrors.length === 1) throw cleanupErrors[0];
+	if (cleanupErrors.length > 1) throw new Error("Multiple cleanup errors", { cause: cleanupErrors });
+	return { result };
+}
+async function _findSubCommand(subCommands, name) {
+	if (name in subCommands) return resolveValue(subCommands[name]);
+	for (const sub of Object.values(subCommands)) {
+		const resolved = await resolveValue(sub);
+		const meta = await resolveValue(resolved?.meta);
+		if (meta?.alias) {
+			if (toArray(meta.alias).includes(name)) return resolved;
+		}
+	}
+}
+function findSubCommandIndex(rawArgs, argsDef) {
+	for (let i = 0; i < rawArgs.length; i++) {
+		const arg = rawArgs[i];
+		if (arg === "--") return -1;
+		if (arg.startsWith("-")) {
+			if (!arg.includes("=") && _isValueFlag(arg, argsDef)) i++;
+			continue;
+		}
+		return i;
+	}
+	return -1;
+}
+function _isValueFlag(flag, argsDef) {
+	const name = flag.replace(/^-{1,2}/, "");
+	const normalized = camelCase(name);
+	for (const [key, def] of Object.entries(argsDef)) {
+		if (def.type !== "string" && def.type !== "enum") continue;
+		if (normalized === camelCase(key)) return true;
+		if ((Array.isArray(def.alias) ? def.alias : def.alias ? [def.alias] : []).includes(name)) return true;
+	}
+	return false;
+}
+//#endregion
+//#region src/cli/core/manifest.ts
+/** Root help prints the groups in this order and skips empty ones; `account` is kept for login and other cloud commands. */
+const GROUPS = [
+	["setup", "Set up"],
+	["generate", "Generate"],
+	["local", "Local stack"],
+	["inspect", "Inspect"],
+	["maintain", "Maintain"],
+	["account", "Account"]
+];
+/** Top-level names left free for account and cloud commands. */
+const RESERVED_NAMES = [
+	"login",
+	"logout",
+	"whoami",
+	"link",
+	"projects",
+	"deploy",
+	"cloud"
+];
+/** The hidden command the completion scripts call. */
+const COMPLETE_COMMAND = "__complete";
+const DOCS_ORIGIN = "https://bettersupabase.com";
+const FILES = { kind: "files" };
+const READS_DATABASE = {
+	kind: "database",
+	access: "read"
+};
+const MANAGEMENT_API = {
+	kind: "network",
+	target: "supabase-api",
+	when: "--project-ref"
+};
+const COMMANDS = [
+	{
+		name: "init",
+		description: "Writes better-supabase.config.ts, src/lib/supabase/index.ts and glue for the frameworks in package.json",
+		group: "setup",
+		docs: "/docs/cli/init",
+		examples: [{
+			command: "better-supabase init",
+			description: "Asks what to set up, then writes the files"
+		}, {
+			command: "better-supabase init --preset saas --yes",
+			description: "Starts from a preset without asking"
+		}],
+		effects: [FILES]
+	},
+	{
+		name: "add",
+		description: "Adds blocks with what they require, or glue for an integration with --integration",
+		group: "setup",
+		docs: "/docs/cli/init#add",
+		examples: [{
+			command: "better-supabase add organizations billing",
+			description: "Installs two blocks and the modules they require"
+		}, {
+			command: "better-supabase add --integration hono",
+			description: "Adds the Hono glue"
+		}],
+		effects: [FILES]
+	},
+	{
+		name: "apply",
+		description: "Applies a preset to an existing project: edits the config, shows the diff and writes the blocks' modules",
+		group: "setup",
+		docs: "/docs/cli/presets#apply",
+		effects: [
+			FILES,
+			{
+				...READS_DATABASE,
+				when: "--adopt"
+			},
+			MANAGEMENT_API
+		]
+	},
+	{
+		name: "adopt",
+		description: "Maps a block onto tables the app already has: proposes blocks.<block> in adopt mode and reports what can't map",
+		group: "setup",
+		docs: "/docs/cli/presets#adopt",
+		effects: [
+			FILES,
+			READS_DATABASE,
+			MANAGEMENT_API
+		]
+	},
+	{
+		name: "preset",
+		description: "Decodes a preset code, or shows the config's preset and how the config differs from it",
+		group: "setup",
+		docs: "/docs/cli/presets#preset",
+		effects: [],
+		subcommands: [{
+			name: "decode",
+			description: "Prints the blocks, auth and settings a preset code or Create URL holds",
+			docs: "/docs/cli/presets#preset",
+			effects: []
+		}, {
+			name: "info",
+			description: "Shows the config's preset and how the config differs from it",
+			docs: "/docs/cli/presets#preset",
+			effects: []
+		}]
+	},
+	{
+		name: "blocks",
+		description: "Lists, shows and searches the blocks you can add",
+		group: "setup",
+		docs: "/docs/cli/presets#blocks",
+		effects: [],
+		subcommands: [
+			{
+				name: "list",
+				description: "Lists the blocks, optionally in one category",
+				docs: "/docs/cli/presets#blocks",
+				effects: []
+			},
+			{
+				name: "view",
+				description: "Shows a block: its tables, the blocks it requires and its options",
+				docs: "/docs/cli/presets#blocks",
+				effects: []
+			},
+			{
+				name: "search",
+				description: "Finds blocks by name, description or category",
+				docs: "/docs/cli/presets#blocks",
+				effects: []
+			}
+		]
+	},
+	{
+		name: "skills",
+		description: "Installs the Agent Skills that ship with this version of better-supabase",
+		group: "setup",
+		docs: "/docs/for-ai-agents",
+		effects: [FILES],
+		subcommands: [{
+			name: "list",
+			description: "Lists the skills that ship with this version",
+			docs: "/docs/for-ai-agents",
+			effects: []
+		}, {
+			name: "install",
+			description: "Copies the skills into each agent's skills folder in the project, or the home folder with --global",
+			docs: "/docs/for-ai-agents",
+			effects: [FILES]
+		}]
+	},
+	{
+		name: "completion",
+		description: "Prints the shell completion script for bash, zsh or fish, for both better-supabase and bsb",
+		group: "setup",
+		docs: "/docs/cli/completion",
+		examples: [{
+			command: "eval \"$(better-supabase completion zsh)\"",
+			description: "Turns on completion in the current zsh; add it to ~/.zshrc"
+		}],
+		effects: []
+	},
+	{
+		name: "gen",
+		description: "Writes the typed client from the database, then every other generated file the config sets up",
+		group: "generate",
+		docs: "/docs/cli/gen",
+		examples: [{
+			command: "better-supabase gen",
+			description: "Regenerates every file the config sets up"
+		}, {
+			command: "better-supabase gen --check",
+			description: "Exits 1 when a generated file is out of date"
+		}],
+		effects: [
+			FILES,
+			READS_DATABASE,
+			MANAGEMENT_API
+		]
+	},
+	{
+		name: "introspect",
+		description: "Saves the database schema as a snapshot for offline gen",
+		group: "generate",
+		docs: "/docs/cli/introspect",
+		effects: [
+			FILES,
+			READS_DATABASE,
+			MANAGEMENT_API
+		]
+	},
+	{
+		name: "spec",
+		description: "Writes, checks or validates the OpenAPI and other spec documents your defineApi() module renders",
+		group: "generate",
+		docs: "/docs/cli/spec",
+		effects: [FILES],
+		subcommands: [{
+			name: "emit",
+			description: "Writes the spec documents, or exits 1 when one is out of date with --check",
+			docs: "/docs/cli/spec",
+			examples: [{
+				command: "better-supabase spec emit openapi",
+				description: "Writes the OpenAPI document"
+			}, {
+				command: "better-supabase spec emit --check",
+				description: "Exits 1 when a written document is out of date"
+			}],
+			effects: [FILES]
+		}, {
+			name: "validate",
+			description: "Validates the documents against their specs and lints them, writing nothing",
+			docs: "/docs/cli/spec",
+			effects: []
+		}]
+	},
+	{
+		name: "scaffold",
+		description: "Writes an API module and its routes for Hono or Next.js, or list, create and detail pages for an app table",
+		group: "generate",
+		docs: "/docs/cli/scaffold",
+		effects: [FILES],
+		subcommands: [{
+			name: "api",
+			description: "Writes an API module, its resource routes and an OpenAPI route for Hono or Next.js",
+			docs: "/docs/cli/scaffold",
+			effects: [FILES]
+		}, {
+			name: "screens",
+			description: "Writes Next.js list, create and detail pages for an app table",
+			docs: "/docs/cli/scaffold#screens",
+			effects: [FILES]
+		}]
+	},
+	{
+		name: "env",
+		description: "Writes the local stack's URL and keys from `supabase status` to an env file, keeping its other lines",
+		group: "local",
+		docs: "/docs/cli/local#env",
+		effects: [FILES]
+	},
+	{
+		name: "keys",
+		description: "Creates an ES256 signing key for the local stack, so local tokens verify through JWKS like hosted ones",
+		group: "local",
+		docs: "/docs/cli/local#keys",
+		effects: [FILES]
+	},
+	{
+		name: "seed",
+		description: "Renders the fixtures from defineSeed() (better-supabase/testing) to SQL",
+		group: "local",
+		docs: "/docs/cli/local#seed",
+		effects: [FILES, {
+			kind: "database",
+			access: "write",
+			when: "--apply"
+		}]
+	},
+	{
+		name: "doctor",
+		description: "Checks RLS, indexes, drift, auth config and env files; exits 1 on errors, or on warnings with --fail-on warning",
+		group: "inspect",
+		docs: "/docs/cli/doctor",
+		examples: [{
+			command: "better-supabase doctor",
+			description: "Checks the local database and the project"
+		}, {
+			command: "better-supabase doctor --format sarif --out doctor.sarif",
+			description: "Writes the findings for code scanning"
+		}],
+		effects: [
+			READS_DATABASE,
+			MANAGEMENT_API,
+			{
+				kind: "network",
+				target: "github"
+			}
+		]
+	},
+	{
+		name: "config",
+		description: "Prints the resolved config: the file it came from, the active environment and every option with its default",
+		group: "inspect",
+		docs: "/docs/cli/config#print-the-resolved-config",
+		effects: []
+	},
+	{
+		name: "sql",
+		description: "Low-level SQL module commands: lists, adds, syncs, upgrades and prints module files without touching app code, and writes their data migration",
+		group: "maintain",
+		docs: "/docs/blocks/sql",
+		effects: [FILES],
+		subcommands: [
+			{
+				name: "list",
+				description: "Lists the SQL modules and which ones the project has",
+				docs: "/docs/blocks/sql",
+				effects: []
+			},
+			{
+				name: "add",
+				description: "Writes module files and their pgTAP tests, and adds the modules to the config",
+				docs: "/docs/blocks/sql",
+				effects: [FILES]
+			},
+			{
+				name: "sync",
+				description: "Writes the files for the modules the config lists and removes the ones it no longer lists",
+				docs: "/docs/blocks/sql",
+				effects: [FILES]
+			},
+			{
+				name: "upgrade",
+				description: "Rewrites module files to this version's SQL, or exits 1 when one is behind with --check",
+				docs: "/docs/blocks/sql",
+				effects: [FILES]
+			},
+			{
+				name: "data",
+				description: "Writes the data migration for blocks in adopt mode",
+				docs: "/docs/blocks/sql",
+				effects: [FILES]
+			},
+			{
+				name: "print",
+				description: "Prints a module's SQL on stdout",
+				docs: "/docs/blocks/sql",
+				effects: []
+			}
+		]
+	},
+	{
+		name: "codemod",
+		description: "Rewrites imports, calls and config keys for renamed better-supabase APIs",
+		group: "maintain",
+		docs: "/docs/cli/codemod",
+		effects: [FILES],
+		subcommands: [
+			{
+				name: "0.4",
+				description: "Renames from 0.3 to 0.4",
+				docs: "/docs/cli/codemod",
+				effects: [FILES]
+			},
+			{
+				name: "0.5",
+				description: "Renames from 0.4 to 0.5",
+				docs: "/docs/cli/codemod",
+				effects: [FILES]
+			},
+			{
+				name: "0.6",
+				description: "Changes from 0.5 to 0.6: kits become blocks and modules",
+				docs: "/docs/cli/codemod",
+				effects: [FILES]
+			},
+			{
+				name: "0.9",
+				description: "Changes from 0.8 to 0.9: sql.modules becomes blocks, and CLI calls use the new subcommands and flags",
+				docs: "/docs/cli/codemod",
+				effects: [FILES]
+			}
+		]
+	}
+];
+/** The spec at `path` (`["sql", "add"]`), or `undefined`. */
+function findSpec(path, commands = COMMANDS) {
+	let level = commands;
+	let found;
+	for (const name of path) {
+		found = level?.find((spec) => spec.name === name);
+		if (!found) return;
+		level = found.subcommands;
+	}
+	return found;
+}
+/** The meta a built-in command's `defineCliCommand` takes, read from the manifest. */
+function commandMeta(path) {
+	const spec = findSpec(path.split(" "));
+	if (!spec) throw new TypeError(`"${path}" is not in the command manifest`);
+	return {
+		name: spec.name,
+		description: spec.description
+	};
+}
+//#endregion
+//#region src/cli/core/command.ts
+/** Options every command accepts; `run()` reads them before the command starts. */
+const GLOBAL_ARGS = {
+	cwd: {
+		type: "string",
+		description: "Project directory",
+		valueHint: "dir"
+	},
+	config: {
+		type: "string",
+		description: "Config file, relative to --cwd",
+		valueHint: "file"
+	},
+	env: {
+		type: "string",
+		description: "Config environment to apply ($env.<name> or $<name>). Defaults to $BETTER_SUPABASE_ENV, then ci when $CI is set",
+		valueHint: "name"
+	},
+	json: {
+		type: "boolean",
+		description: "Print one JSON document on stdout; errors as Problem Details. On by default in agent mode",
+		negativeDescription: "Print text, also in agent mode"
+	},
+	agent: {
+		type: "string",
+		description: "Agent mode (JSON output, no prompts, consent for destructive work): auto detects a coding agent, yes or no decide. Defaults to $BETTER_SUPABASE_AGENT, then auto",
+		valueHint: "auto|yes|no"
+	},
+	confirm: {
+		type: "string",
+		description: "The token from a consent_required result, passed once the user agreed",
+		valueHint: "token"
+	},
+	yes: {
+		type: "boolean",
+		alias: "y",
+		description: "Ask nothing; use the flags and the defaults"
+	},
+	color: {
+		type: "boolean",
+		default: true,
+		description: "Color the output on a terminal",
+		negativeDescription: "Print no colors, like $NO_COLOR"
+	},
+	debug: {
+		type: "boolean",
+		description: "Print stack traces, the commands the CLI runs, and timings on stderr"
+	}
+};
+const LISTS = /* @__PURE__ */ new WeakMap();
+const COMPLETIONS = /* @__PURE__ */ new WeakMap();
+const RUNS_WITH_INVALID_CONFIG = /* @__PURE__ */ new WeakSet();
+/** A citty command that receives the `CliContext` and returns a `CommandResult`. */
+function defineCliCommand(def) {
+	const version = def.apiVersion ?? 1;
+	if (version !== 1) throw new CliError("usage", `Command "${def.meta.name}" targets CLI command API v${String(version)}; this version supports v1.`);
+	const command = defineCommand({
+		meta: def.meta,
+		args: {
+			...def.args,
+			...GLOBAL_ARGS
+		},
+		run: ({ args, data }) => def.run(args, cliContext(data))
+	});
+	LISTS.set(command, def.lists ?? []);
+	COMPLETIONS.set(command, def.completions ?? {});
+	if (def.runsWithInvalidConfig === true) RUNS_WITH_INVALID_CONFIG.add(command);
+	return Object.assign(command, { apiVersion: 1 });
+}
+/** The list options a command declared through `defineCliCommand`. */
+function listArgs(command) {
+	return LISTS.get(command) ?? [];
+}
+/** The completion values a command declared through `defineCliCommand`, by argument. */
+function completionValues(command) {
+	return COMPLETIONS.get(command) ?? {};
+}
+function runsWithInvalidConfig(command) {
+	return RUNS_WITH_INVALID_CONFIG.has(command);
+}
+/** Splits a comma-separated option into its trimmed, non-empty parts. */
+function list(value) {
+	return (value ?? "").split(",").map((item) => item.trim()).filter(Boolean);
+}
+/**
+* Joins repeated list options (`--only a --only b`) into one comma-separated
+* value, because citty keeps only the last occurrence.
+*/
+function joinRepeated(argv, names) {
+	if (names.length === 0) return [...argv];
+	const lists = new Set(names);
+	const values = /* @__PURE__ */ new Map();
+	const rest = [];
+	for (let index = 0; index < argv.length; index += 1) {
+		const token = argv[index];
+		if (token === "--") {
+			rest.push(...argv.slice(index));
+			break;
+		}
+		const match = /^--([^=]+)(?:=(.*))?$/.exec(token);
+		const name = match?.[1];
+		if (name === void 0 || !lists.has(name)) {
+			rest.push(token);
+			continue;
+		}
+		let value = match?.[2];
+		if (value === void 0) {
+			const next = argv[index + 1];
+			if (next === void 0 || next.startsWith("-")) continue;
+			value = next;
+			index += 1;
+		}
+		values.set(name, [...values.get(name) ?? [], value]);
+	}
+	return [...[...values].map(([name, parts]) => `--${name}=${parts.join(",")}`), ...rest];
+}
+function isCliContext(value) {
+	return typeof value === "object" && value !== null && "config" in value && "io" in value && "env" in value && "json" in value;
+}
+function cliContext(data) {
+	if (!isCliContext(data)) throw new TypeError("better-supabase commands run through run() from better-supabase/cli");
+	return data;
+}
+//#endregion
+export { list as a, COMMANDS as c, GROUPS as d, RESERVED_NAMES as f, runCommand as h, joinRepeated as i, COMPLETE_COMMAND as l, parseArgs$2 as m, completionValues as n, listArgs as o, commandMeta as p, defineCliCommand as r, runsWithInvalidConfig as s, GLOBAL_ARGS as t, DOCS_ORIGIN as u };