better-supabase 0.2.0 → 0.4.0

package/dist/cli/init-ClnxRYBF.js

@@ -0,0 +1,550 @@
+import { a as list, r as defineCliCommand } from "./command-CK14fP91.js";
+import { r as writeIfChanged, t as display } from "./io-k41_z-jT.js";
+import { t as VERSION } from "./version-5mW_8sY1.js";
+import { n as findConfig } from "./config-D9R0o1LH.js";
+import { n as installCommand, t as detectProject } from "./project-B_GeXyHh.js";
+import { posix, resolve } from "node:path";
+import { existsSync } from "node:fs";
+//#region src/cli/templates.ts
+const INTEGRATIONS = [
+	"next",
+	"hono",
+	"orpc",
+	"edge",
+	"mcp",
+	"client",
+	"react"
+];
+const join$1 = (...parts) => posix.normalize(posix.join(...parts));
+const libDir = (context) => join$1(context.srcDir, "lib");
+/** `lib/supabase/`: the shared definition, `server.ts` and `client.ts`. */
+const supabaseDir = (context) => join$1(libDir(context), "supabase");
+/** `lib/supabase/index.ts`, imported as `lib/supabase` on both sides. */
+const libEntry = (context) => join$1(supabaseDir(context), "index.ts");
+/** Import path of `lib/supabase/index.ts`: the folder, unless the project keeps `.ts` extensions. */
+function importLib(context, from) {
+	const path = importFrom(context, from, libEntry(context));
+	return context.tsExtensions ? path : path.replace(/^(\.\.?\/.+)\/index$/, "$1");
+}
+/** Relative import from one project file to another, following the project's extension style. */
+function importFrom(context, from, to, keepTs = context.tsExtensions) {
+	let path = posix.relative(posix.dirname(from), to);
+	if (!path.startsWith(".")) path = `./${path}`;
+	return keepTs ? path : path.replace(/\.tsx?$/, "");
+}
+function publicEnv(context) {
+	const read = (prefix, access) => access === "vite" ? {
+		url: `import.meta.env.${prefix}SUPABASE_URL`,
+		key: `import.meta.env.${prefix}SUPABASE_PUBLISHABLE_KEY`
+	} : {
+		url: `process.env.${prefix}SUPABASE_URL!`,
+		key: `process.env.${prefix}SUPABASE_PUBLISHABLE_KEY!`
+	};
+	if (context.frameworks.includes("next")) return read("NEXT_PUBLIC_", "process");
+	if (context.frameworks.includes("expo")) return read("EXPO_PUBLIC_", "process");
+	if (context.frameworks.includes("vite")) return read("VITE_", "vite");
+	return read("", "process");
+}
+const denoJson = (context) => `${JSON.stringify({ imports: {
+	"better-supabase": `npm:better-supabase@^${context.version}`,
+	"better-supabase/": `npm:/better-supabase@^${context.version}/`,
+	"@supabase/supabase-js": "npm:@supabase/supabase-js@^2",
+	zod: "npm:zod@^4"
+} }, null, 2)}\n`;
+const SHARED = "supabase/functions/_shared/supabase.ts";
+function shared(context) {
+	return {
+		path: SHARED,
+		contents: `import { defineSupabase } from 'better-supabase';
+
+import { schema } from '${importFrom(context, SHARED, context.generated, true)}';
+
+export const betterSupabase = defineSupabase(schema);
+`
+	};
+}
+/** `supabase/functions/<name>/server.ts`: the function's `bs`. */
+function functionServer(name, contents) {
+	return {
+		path: `supabase/functions/${name}/server.ts`,
+		contents: contents("../_shared/supabase.ts")
+	};
+}
+/** Edge Functions import `_shared/supabase.ts`, so they don't need the app definition. */
+const needsLib = (names) => names.length === 0 || names.some((name) => name !== "edge" && name !== "mcp");
+/** The files `init` writes: the config and, unless `lib` is false, the isomorphic definition. */
+function baseFiles(context, casing, lib = true) {
+	const config = {
+		path: "better-supabase.config.ts",
+		contents: `import { defineConfig } from 'better-supabase/config';
+
+export default defineConfig({
+  casing: '${casing}',
+  output: '${context.generated}',
+});
+`
+	};
+	if (!lib) return [config];
+	const path = libEntry(context);
+	const generated = importFrom(context, path, context.generated);
+	return [config, {
+		path,
+		contents: `import { defineSupabase } from 'better-supabase';
+
+import { schema } from '${generated}';
+
+export type { Functions, Models } from '${generated}';
+
+export const betterSupabase = defineSupabase(schema);
+`
+	}];
+}
+const TEMPLATES = {
+	client: {
+		description: "Browser client with cookie sessions shared with the server",
+		requires: [],
+		packages: ["@supabase/ssr"],
+		files: (context) => {
+			const path = join$1(supabaseDir(context), "client.ts");
+			const env = publicEnv(context);
+			return [{
+				path,
+				contents: `import { createClient } from 'better-supabase/client';
+
+import { betterSupabase } from '${importLib(context, path)}';
+
+export const bs = createClient(betterSupabase, {
+  env: {
+    url: ${env.url},
+    publishableKey: ${env.key},
+  },
+});
+`
+			}];
+		}
+	},
+	next: {
+		description: "Next.js proxy, Server Components, route handlers and actions",
+		requires: ["client"],
+		packages: [
+			"@supabase/ssr",
+			"@supabase/server",
+			"server-only"
+		],
+		files: (context) => {
+			const server = join$1(supabaseDir(context), "server.ts");
+			const proxy = join$1(context.srcDir, "proxy.ts");
+			return [{
+				path: server,
+				contents: `import 'server-only';
+
+import { createNext } from 'better-supabase/next';
+
+import { betterSupabase } from '${importLib(context, server)}';
+
+export const bs = createNext(betterSupabase);
+`
+			}, {
+				path: proxy,
+				contents: `import type { NextRequest } from 'next/server';
+
+import { bs } from '${importFrom(context, proxy, server)}';
+
+export const proxy = (request: NextRequest) => bs.proxy(request);
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico|.*\\\\.(?:svg|png|jpg|webp)$).*)'],
+};
+`
+			}];
+		},
+		next: ["Read the session in Server Components with `const { db } = await bs.context()`."]
+	},
+	react: {
+		description: "React provider and typed hooks with TanStack Query",
+		requires: ["client"],
+		packages: ["@tanstack/react-query"],
+		files: (context) => {
+			const client = join$1(supabaseDir(context), "client.ts");
+			const providers = context.frameworks.includes("next") ? join$1(context.srcDir, "app", "providers.tsx") : join$1(context.srcDir, "providers.tsx");
+			const hooks = join$1(libDir(context), "hooks.ts");
+			return [{
+				path: providers,
+				contents: `${context.frameworks.includes("next") ? "'use client';\n\n" : ""}import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { BetterSupabaseProvider } from 'better-supabase/react';
+import { type ReactNode, useState } from 'react';
+
+import { bs } from '${importFrom(context, providers, client)}';
+
+export function Providers({ children }: { children: ReactNode }) {
+  const [queryClient] = useState(() => new QueryClient());
+  return (
+    <QueryClientProvider client={queryClient}>
+      <BetterSupabaseProvider client={bs} queryClient={queryClient}>
+        {children}
+      </BetterSupabaseProvider>
+    </QueryClientProvider>
+  );
+}
+`
+			}, {
+				path: hooks,
+				contents: `import { createHooks } from 'better-supabase/react';
+
+import type { bs } from '${importFrom(context, hooks, client)}';
+
+export const { useDb, useQueries, useAuth, useSupabase } = createHooks<typeof bs>();
+`
+			}];
+		},
+		next: ["Wrap your app in <Providers>."]
+	},
+	hono: {
+		description: "Hono middleware, handlers and REST resources",
+		requires: [],
+		packages: ["hono", "@supabase/server"],
+		files: (context) => {
+			const path = join$1(context.srcDir, "server.ts");
+			return [{
+				path,
+				contents: `import { Hono } from 'hono';
+import { type HonoEnv, createHono } from 'better-supabase/hono';
+
+import { betterSupabase, type Functions, type Models } from '${importLib(context, path)}';
+
+export const bs = createHono(betterSupabase);
+
+const app = new Hono<HonoEnv<Models, Functions, unknown>>()
+  .onError(bs.onError)
+  .use('/api/*', bs.middleware())
+  .get('/api/me', (c) => c.json({ kind: c.var.auth.kind }));
+
+export default app;
+`
+			}];
+		}
+	},
+	orpc: {
+		description: "oRPC middleware with typed context and ORPCError mapping",
+		requires: [],
+		packages: ["@orpc/server", "@supabase/server"],
+		files: (context) => {
+			const path = join$1(context.srcDir, "router.ts");
+			return [{
+				path,
+				contents: `import { os } from '@orpc/server';
+import { createOrpc, type OrpcRequestContext } from 'better-supabase/orpc';
+
+import { betterSupabase } from '${importLib(context, path)}';
+
+export const bs = createOrpc(betterSupabase);
+
+const base = os.$context<OrpcRequestContext>();
+const authed = base.use(bs.middleware());
+
+export const router = {
+  me: authed.handler(({ context }) => ({ kind: context.auth.kind })),
+};
+`
+			}];
+		}
+	},
+	edge: {
+		description: "A Supabase Edge Function with CORS and Problem Details",
+		requires: [],
+		packages: [],
+		files: (context) => [
+			shared(context),
+			functionServer("api", (shared) => `import { createEdge } from 'better-supabase/edge';
+
+import { betterSupabase } from '${shared}';
+
+export const bs = createEdge(betterSupabase, { cors: true });
+`),
+			{
+				path: "supabase/functions/api/index.ts",
+				contents: `import { bs } from './server.ts';
+
+Deno.serve(bs.handler((_request, { auth }) => ({ kind: auth.kind })));
+`
+			},
+			{
+				path: "supabase/functions/api/deno.json",
+				contents: denoJson(context)
+			}
+		],
+		next: ["Serve it locally with `supabase functions serve api`."]
+	},
+	mcp: {
+		description: "An MCP server (Streamable HTTP) as an Edge Function",
+		requires: [],
+		packages: [],
+		files: (context) => [
+			shared(context),
+			functionServer("mcp", (shared) => `import { createMcp } from 'better-supabase/mcp';
+
+import { betterSupabase } from '${shared}';
+
+export const bs = createMcp(betterSupabase, {
+  name: 'app',
+  version: '0.1.0',
+  resources: {},
+});
+`),
+			{
+				path: "supabase/functions/mcp/index.ts",
+				contents: `import { bs } from './server.ts';
+
+Deno.serve(bs.fetch);
+`
+			},
+			{
+				path: "supabase/functions/mcp/deno.json",
+				contents: denoJson(context)
+			}
+		],
+		next: ["List tables under `resources` to expose them as tools, e.g. `customers: true`."]
+	}
+};
+/** The integration and what it requires, dependencies first, without duplicates. */
+function resolveIntegrations(names) {
+	const ordered = [];
+	const visit = (name) => {
+		if (ordered.includes(name)) return;
+		for (const dependency of TEMPLATES[name].requires) visit(dependency);
+		ordered.push(name);
+	};
+	for (const name of names) visit(name);
+	return ordered;
+}
+function isIntegration(name) {
+	return INTEGRATIONS.includes(name);
+}
+/** Integrations `init` adds for the frameworks it finds. */
+function suggestedIntegrations(frameworks) {
+	const names = [];
+	for (const framework of frameworks) switch (framework) {
+		case "next":
+			names.push("next");
+			break;
+		case "hono":
+			names.push("hono");
+			break;
+		case "orpc":
+			names.push("orpc");
+			break;
+		case "vite":
+		case "expo":
+			names.push("client");
+			break;
+		case "tanstack-query":
+			names.push("react");
+			break;
+		default: throw new TypeError(`Unknown framework ${String(framework)}`);
+	}
+	return resolveIntegrations(names);
+}
+//#endregion
+//#region src/cli/commands/init.ts
+const INIT_ARGS = {
+	casing: {
+		type: "string",
+		description: "Row keys in camelCase (camel, the default) or the database's snake_case (snake)",
+		valueHint: "camel|snake"
+	},
+	with: {
+		type: "string",
+		description: "Integrations to add next to the detected ones: next, hono, orpc, edge, mcp, client, react",
+		valueHint: "integration,..."
+	},
+	force: {
+		type: "boolean",
+		description: "Overwrite files that exist"
+	},
+	"dry-run": {
+		type: "boolean",
+		description: "Show what would be written"
+	}
+};
+const ADD_ARGS = {
+	integration: {
+		type: "positional",
+		required: false,
+		description: "next, hono, orpc, edge, mcp, client or react"
+	},
+	force: {
+		type: "boolean",
+		description: "Overwrite files that exist"
+	},
+	"dry-run": {
+		type: "boolean",
+		description: "Show what would be written"
+	}
+};
+const CANCELLED = {
+	code: 1,
+	error: "Cancelled."
+};
+/** `--force`, or the person's answer when files exist; `undefined` when they cancel. */
+async function overwrite(root, files, args, prompts) {
+	if (args.force === true) return true;
+	const existing = [...new Set(files.map((file) => file.path).filter((path) => existsSync(resolve(root, path))))];
+	if (!prompts || existing.length === 0) return false;
+	return prompts.confirm(`${existing.map((path) => display(root, path)).join(", ")} ${existing.length === 1 ? "exists" : "exist"}. Overwrite?`);
+}
+async function writeFiles(root, files, args, force) {
+	const dryRun = args["dry-run"] === true;
+	const lines = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const file of files) {
+		if (seen.has(file.path)) continue;
+		seen.add(file.path);
+		const path = resolve(root, file.path);
+		const shown = display(root, file.path);
+		if (existsSync(path) && !force) {
+			lines.push(`Kept    ${shown} (exists)`);
+			continue;
+		}
+		if (dryRun) {
+			lines.push(`Would write ${shown}`);
+			continue;
+		}
+		lines.push(`${await writeIfChanged(path, file.contents) ? "Wrote  " : "Same   "} ${shown}`);
+	}
+	return lines;
+}
+function context(project, generated) {
+	return {
+		srcDir: project.srcDir,
+		generated,
+		tsExtensions: project.tsExtensions,
+		frameworks: project.frameworks,
+		version: VERSION
+	};
+}
+function integrationFiles(names, templateContext) {
+	return names.flatMap((name) => TEMPLATES[name].files(templateContext));
+}
+function packagesFor(project, names) {
+	const wanted = [
+		"better-supabase",
+		"@supabase/supabase-js",
+		...names.flatMap((name) => TEMPLATES[name].packages)
+	];
+	return [...new Set(wanted)].filter((name) => !(name in project.dependencies));
+}
+/** pg as a dev dependency, when the project lacks it. */
+function devPackages(project) {
+	return "pg" in project.dependencies ? [] : [["pg"]];
+}
+function chooseIntegrations(prompts, initial) {
+	return prompts.multiselect("Integrations", INTEGRATIONS.map((name) => ({
+		value: name,
+		label: name,
+		hint: TEMPLATES[name].description
+	})), initial);
+}
+function parseIntegrations(values) {
+	const unknown = values.filter((value) => !isIntegration(value));
+	if (unknown.length > 0) return `Unknown integration ${unknown.join(", ")}. Available: ${INTEGRATIONS.join(", ")}`;
+	return values.filter(isIntegration);
+}
+async function runInit(config, args, prompts) {
+	const casing = args.casing ?? (prompts ? await prompts.select("Row keys", [{
+		value: "camel",
+		label: "camelCase",
+		hint: "customerId"
+	}, {
+		value: "snake",
+		label: "snake_case",
+		hint: "customer_id, as in the database"
+	}], "camel") : "camel");
+	if (casing === void 0) return CANCELLED;
+	if (casing !== "camel" && casing !== "snake") return {
+		code: 2,
+		error: "--casing must be \"camel\" or \"snake\""
+	};
+	const project = await detectProject(config.root);
+	const requested = parseIntegrations(list(args.with));
+	if (typeof requested === "string") return {
+		code: 2,
+		error: requested
+	};
+	const detected = resolveIntegrations([...suggestedIntegrations(project.frameworks), ...requested]);
+	const chosen = args.with === void 0 && prompts ? await chooseIntegrations(prompts, detected) : detected;
+	if (chosen === void 0) return CANCELLED;
+	const integrations = resolveIntegrations(chosen);
+	const templateContext = context(project, findConfig(config.root) !== void 0 ? config.output : posix.normalize(posix.join(project.srcDir, "lib/supabase/generated.ts")));
+	const files = [...baseFiles(templateContext, casing, needsLib(integrations)), ...integrationFiles(integrations, templateContext)];
+	const force = await overwrite(config.root, files, args, prompts);
+	if (force === void 0) return CANCELLED;
+	const lines = [
+		project.frameworks.length > 0 ? `Found ${project.frameworks.join(", ")}.` : "No framework found.",
+		"",
+		...await writeFiles(config.root, files, args, force)
+	];
+	const packages = packagesFor(project, integrations);
+	const steps = [
+		...packages.length > 0 ? [installCommand(project.packageManager, packages)] : [],
+		...devPackages(project).map((names) => installCommand(project.packageManager, names, true)),
+		...project.hasSupabase ? [] : ["supabase init"],
+		"supabase start",
+		"better-supabase env",
+		"better-supabase gen"
+	];
+	lines.push("", "Next:", ...steps.map((step, index) => `  ${index + 1}. ${step}`));
+	for (const name of integrations) for (const hint of TEMPLATES[name].next ?? []) lines.push(`  - ${hint}`);
+	lines.push("", "Agent skills: better-supabase skills install");
+	return {
+		code: 0,
+		output: lines.join("\n")
+	};
+}
+async function runAdd(config, args, prompts) {
+	const named = args._.length === 0 && prompts ? await chooseIntegrations(prompts, []) : args._;
+	if (named === void 0) return CANCELLED;
+	if (named.length === 0) return {
+		code: 2,
+		error: `Name at least one integration: ${INTEGRATIONS.join(", ")}`
+	};
+	const requested = parseIntegrations(named);
+	if (typeof requested === "string") return {
+		code: 2,
+		error: requested
+	};
+	const project = await detectProject(config.root);
+	const integrations = resolveIntegrations(requested);
+	const templateContext = context(project, config.output);
+	const files = integrationFiles(integrations, templateContext);
+	const force = await overwrite(config.root, files, args, prompts);
+	if (force === void 0) return CANCELLED;
+	const lines = await writeFiles(config.root, files, args, force);
+	const lib = libEntry(templateContext);
+	if (!existsSync(resolve(config.root, lib)) && integrations.some((name) => needsLib([name]))) lines.push("", `Warning: ${lib} is missing. Run \`better-supabase init\` first.`);
+	const packages = packagesFor(project, integrations).filter((name) => name !== "better-supabase" && name !== "@supabase/supabase-js");
+	if (packages.length > 0) lines.push("", `Install: ${installCommand(project.packageManager, packages)}`);
+	for (const name of integrations) for (const hint of TEMPLATES[name].next ?? []) lines.push(`- ${hint}`);
+	return {
+		code: 0,
+		output: lines.join("\n")
+	};
+}
+const initCommand = defineCliCommand({
+	meta: {
+		name: "init",
+		description: "Writes better-supabase.config.ts, src/lib/supabase/index.ts and glue for the frameworks in package.json"
+	},
+	args: INIT_ARGS,
+	lists: ["with"],
+	run: (args, { config, io }) => runInit(config, args, io.prompts)
+});
+const addCommand = defineCliCommand({
+	meta: {
+		name: "add",
+		description: "Adds glue for an integration to an existing project"
+	},
+	args: ADD_ARGS,
+	run: (args, { config, io }) => runAdd(config, args, io.prompts)
+});
+//#endregion
+export { addCommand, initCommand };

package/dist/cli/introspect-DxqfkVIv.js

@@ -0,0 +1,81 @@
+import { r as defineCliCommand } from "./command-CK14fP91.js";
+import { r as writeIfChanged, t as display } from "./io-k41_z-jT.js";
+import { r as painter } from "./style-C0NFdJRL.js";
+import { l as fileDiff } from "./read-sets-CMa29t9a.js";
+import { _ as restrictSchemas, a as sourceArgs, o as loadSnapshot, t as SOURCE_ARGS, u as serializeSnapshot, v as serializeGenerator } from "./gen-Ccn_p90L.js";
+import { n as withSpinner } from "./prompts-BNcNfAve.js";
+import { resolve } from "node:path";
+import { readFile } from "node:fs/promises";
+//#region src/cli/commands/introspect.ts
+const ARGS = {
+	out: {
+		type: "string",
+		description: "Defaults to supabase/snapshot.json, or supabase/generator-metadata.json",
+		valueHint: "file"
+	},
+	format: {
+		type: "string",
+		description: "snapshot (the default) or generator-metadata (postgrest-typegen's input)",
+		valueHint: "snapshot|generator-metadata"
+	},
+	check: {
+		type: "boolean",
+		description: "Fail when the file is out of date"
+	},
+	...SOURCE_ARGS
+};
+const introspectCommand = defineCliCommand({
+	meta: {
+		name: "introspect",
+		description: "Saves the database schema as a snapshot for offline gen"
+	},
+	args: ARGS,
+	run: async (args, { config, env, io, signal }) => {
+		const format = args.format ?? "snapshot";
+		if (format !== "snapshot" && format !== "generator-metadata") return {
+			code: 2,
+			error: "--format must be \"snapshot\" or \"generator-metadata\""
+		};
+		const { snapshotPath: _ignored, ...source } = await sourceArgs(args, io);
+		const snapshot = await withSpinner(io.prompts, "Reading the schema", () => loadSnapshot(config, env, {
+			...source,
+			live: true,
+			...signal ? { signal } : {}
+		}));
+		const out = args.out ?? (format === "snapshot" ? "supabase/snapshot.json" : "supabase/generator-metadata.json");
+		const contents = format === "snapshot" ? serializeSnapshot(snapshot) : `${await serializeGenerator(restrictSchemas(snapshot.generator, config.schemas))}\n`;
+		if (args.check === true) {
+			const current = await readFile(resolve(config.root, out), "utf8").catch(() => void 0);
+			const file = display(config.root, out);
+			return current === contents ? {
+				code: 0,
+				output: `${file} is up to date.`,
+				data: {
+					file,
+					upToDate: true
+				}
+			} : {
+				code: 1,
+				output: fileDiff(file, current, contents, painter(io.color)),
+				error: `${file} is out of date. Run \`better-supabase introspect\`.`,
+				data: {
+					file,
+					upToDate: false
+				}
+			};
+		}
+		const wrote = await writeIfChanged(resolve(config.root, out), contents);
+		const tables = snapshot.extras.tables.length;
+		return {
+			code: 0,
+			output: `${wrote ? "Wrote" : "Unchanged"} ${display(config.root, out)} (${tables} tables).`,
+			data: {
+				file: display(config.root, out),
+				written: wrote,
+				tables
+			}
+		};
+	}
+});
+//#endregion
+export { introspectCommand };

package/dist/cli/io-k41_z-jT.js

@@ -0,0 +1,24 @@
+import { dirname, relative, resolve, sep } from "node:path";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+//#region src/cli/io.ts
+/** Writes a file when its contents changed. Returns whether it wrote. */
+async function writeIfChanged(path, contents) {
+	if (existsSync(path)) {
+		if (await readFile(path, "utf8") === contents) return false;
+	}
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, contents);
+	return true;
+}
+/** Relative ESM import specifier from one file to another, keeping `.ts`. */
+function importPath(fromFile, toFile) {
+	let path = relative(dirname(fromFile), toFile).split(sep).join("/");
+	if (!path.startsWith(".")) path = `./${path}`;
+	return path;
+}
+function display(root, path) {
+	return relative(root, resolve(root, path)).split(sep).join("/") || ".";
+}
+//#endregion
+export { importPath as n, writeIfChanged as r, display as t };