@saastemly/voidcommerce 0.1.0

package/src/deploy/wrangler.ts

@@ -0,0 +1,111 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { delimiter, dirname, join } from "node:path";
+
+/**
+ * wrangler, as vc uses it: found, asked who it is, and driven for the
+ * account operations a deploy needs. Nothing here needs a Void account.
+ */
+
+export function findWrangler(from = process.cwd()): string | null {
+	let dir = from;
+	for (;;) {
+		const local = join(dir, "node_modules", ".bin", "wrangler");
+		if (existsSync(local)) return local;
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	const onPath = (process.env["PATH"] ?? "")
+		.split(delimiter)
+		.filter(Boolean)
+		.some((d) => existsSync(join(d, "wrangler")));
+	return onPath ? "wrangler" : null;
+}
+
+export interface Ran {
+	code: number;
+	out: string;
+}
+
+/** Run wrangler. `inherit` hands the terminal over (prompts, progress); otherwise output is captured. */
+export function wrangler(bin: string, args: string[], cwd: string, inherit = false): Promise<Ran> {
+	return new Promise((resolve) => {
+		const child = spawn(bin, args, { cwd, stdio: inherit ? "inherit" : ["ignore", "pipe", "pipe"] });
+		let out = "";
+		child.stdout?.on("data", (chunk) => {
+			out += chunk;
+		});
+		child.stderr?.on("data", (chunk) => {
+			out += chunk;
+		});
+		child.on("error", (error) => resolve({ code: 1, out: String(error) }));
+		child.on("exit", (code) => resolve({ code: code ?? 1, out }));
+	});
+}
+
+export interface WhoAmI {
+	state: "logged-in" | "logged-out" | "unknown";
+	accounts: Array<{ name: string; id: string }>;
+	raw: string;
+}
+
+/**
+ * `wrangler whoami` exits 0 whether or not you are logged in, so the text
+ * decides. Logged in, it prints a table of accounts; those are what pinning
+ * needs.
+ */
+export function parseWhoAmI(raw: string): WhoAmI {
+	if (/not authenticated/i.test(raw)) return { state: "logged-out", accounts: [], raw };
+	const accounts = [...raw.matchAll(/│\s*([^│\n]+?)\s*│\s*([0-9a-f]{32})\s*│/g)].map((m) => ({ name: m[1]!, id: m[2]! }));
+	if (/logged in/i.test(raw) || accounts.length > 0) return { state: "logged-in", accounts, raw };
+	return { state: "unknown", accounts: [], raw };
+}
+
+export async function whoami(bin: string, cwd: string): Promise<WhoAmI> {
+	return parseWhoAmI((await wrangler(bin, ["whoami"], cwd)).out);
+}
+
+/** Secret names on the worker, or null when they cannot be listed — a worker not deployed yet says so. */
+export async function secretNames(bin: string, cwd: string): Promise<Set<string> | null> {
+	const ran = await wrangler(bin, ["secret", "list", "--format", "json"], cwd);
+	if (ran.code !== 0) return null;
+	try {
+		const start = ran.out.indexOf("[");
+		const rows = JSON.parse(ran.out.slice(start)) as Array<{ name: string }>;
+		return new Set(rows.map((row) => row.name));
+	} catch {
+		return null;
+	}
+}
+
+export interface D1 {
+	name: string;
+	uuid: string;
+}
+
+export async function d1List(bin: string, cwd: string): Promise<D1[]> {
+	const ran = await wrangler(bin, ["d1", "list", "--json"], cwd);
+	if (ran.code !== 0) throw new Error(`wrangler d1 list failed:\n${ran.out.trim()}`);
+	const start = ran.out.indexOf("[");
+	return JSON.parse(ran.out.slice(start)) as D1[];
+}
+
+/** The database by name, created if absent. Idempotent. */
+export async function ensureD1(bin: string, cwd: string, name: string): Promise<D1> {
+	const existing = (await d1List(bin, cwd)).find((db) => db.name === name);
+	if (existing) return existing;
+	const created = await wrangler(bin, ["d1", "create", name], cwd);
+	if (created.code !== 0) throw new Error(`wrangler d1 create ${name} failed:\n${created.out.trim()}`);
+	const found = (await d1List(bin, cwd)).find((db) => db.name === name);
+	if (!found) throw new Error(`created D1 "${name}" but it is not in wrangler d1 list`);
+	return found;
+}
+
+/** A queue by name. Already existing is fine. */
+export async function ensureQueue(bin: string, cwd: string, name: string): Promise<void> {
+	const ran = await wrangler(bin, ["queues", "create", name], cwd);
+	if (ran.code !== 0 && !/already exists|11009/i.test(ran.out)) {
+		throw new Error(`wrangler queues create ${name} failed:\n${ran.out.trim()}`);
+	}
+}

package/src/dist.ts

@@ -0,0 +1,157 @@
+import { cp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import color from "picocolors";
+import { generate } from "./generate/index";
+import { finishStrict } from "./generate/strict";
+import { box, line, row } from "./help";
+import { findProject } from "./project";
+
+/**
+ * `vc dist` — the deployable app, as a self-contained tree.
+ *
+ * A strict repository has no app in it: `.vc/app` is generated and
+ * gitignored, and it reaches the root through symlinks. Nothing can build
+ * that except a machine that has run `vc generate` first.
+ *
+ * So this materialises it: the generated app with every symlink replaced by
+ * the real thing, a package.json carrying the versions the repository
+ * resolved, and the lockfile beside it. The result is an ordinary Void app
+ * that `bun install && vp build && wrangler deploy` can take from a cold
+ * checkout — which is exactly what a CI runner, or Cloudflare's own build,
+ * has.
+ *
+ * The generated workflow pushes this tree to a branch (`void-dist`) on every
+ * push to main, so the thing Cloudflare builds is a plain Void app and the
+ * thing a person edits stays a manifest.
+ */
+
+export const DIST_DIR = join(".vc", "dist");
+export const DIST_BRANCH = "void-dist";
+
+/** Never copied into the distributed tree, whatever the layout put there. */
+const EXCLUDE = new Set(["node_modules", ".env", ".env.local", "dist", ".void", ".wrangler", ".git"]);
+
+const README = (domain: string) => `# ${domain} — generated
+
+Do not edit, and do not open a pull request against this branch. Every file
+here is written by \`vc dist\` from the manifest on \`main\`, and this branch is
+replaced wholesale on every push.
+
+It is an ordinary Void app so that a build machine needs nothing but a
+checkout:
+
+\`\`\`sh
+bun install
+bunx void prepare
+bunx vp build
+bunx wrangler deploy -c dist/ssr/wrangler.json
+\`\`\`
+
+Secrets are the worker's own (\`wrangler secret put\`), never files here. The
+committed migrations under \`db/migrations\` are what production applies.
+`;
+
+/**
+ * Copy a directory, following symlinks into real files and skipping what a
+ * build must not carry. `cp -r` would copy the symlinks themselves, which
+ * point outside the tree and break the moment it is checked out elsewhere.
+ */
+async function copyResolved(from: string, to: string): Promise<void> {
+	await mkdir(to, { recursive: true });
+	for (const entry of await readdir(from, { withFileTypes: true })) {
+		if (EXCLUDE.has(entry.name)) continue;
+		const source = join(from, entry.name);
+		const target = join(to, entry.name);
+		// `dereference` resolves the link; `recursive` walks a directory.
+		if (entry.isDirectory() || entry.isSymbolicLink()) {
+			const stat = await import("node:fs/promises").then((fs) => fs.stat(source).catch(() => null));
+			if (!stat) continue; // a dangling link is not an error worth failing a build for
+			if (stat.isDirectory()) {
+				await copyResolved(source, target);
+				continue;
+			}
+		}
+		await cp(source, target, { dereference: true });
+	}
+}
+
+export async function distCommand(args: string[]): Promise<number> {
+	const project = await findProject();
+	if (!project) {
+		console.error("vc: no voidcommerce.json here.");
+		return 1;
+	}
+	const outIndex = args.indexOf("--out");
+	const out = outIndex >= 0 ? args[outIndex + 1] : undefined;
+	if (outIndex >= 0 && !out) {
+		console.error("vc: --out needs a directory.");
+		return 1;
+	}
+	const target = join(project.root, out ?? DIST_DIR);
+
+	// Always regenerate: the point is that the tree matches the manifest.
+	await generate(project.root, project.manifest);
+	const prepared = await finishStrict(project.root);
+	if (prepared !== 0) return prepared;
+
+	await rm(target, { recursive: true, force: true });
+	await copyResolved(project.appDir, target);
+
+	// The app's package.json lists what the choices need, at "latest". The
+	// repository's own package.json holds what was actually resolved — pins,
+	// and links to packages that are not published. Those are what a cold
+	// install must reproduce, so they win.
+	const rootPkg = JSON.parse(await readFile(join(project.root, "package.json"), "utf8")) as Record<string, Record<string, string>>;
+	const appPkgPath = join(target, "package.json");
+	const appPkg = JSON.parse(await readFile(appPkgPath, "utf8")) as Record<string, unknown>;
+	const local: string[] = [];
+	for (const section of ["dependencies", "devDependencies"]) {
+		const merged = { ...((appPkg[section] as Record<string, string>) ?? {}) };
+		for (const [name, version] of Object.entries(rootPkg[section] ?? {})) {
+			if (name === "@saastemly/voidcommerce") continue; // the generator is not the app's dependency
+			if (name in merged || section === "devDependencies") merged[name] = version;
+			if (version.startsWith("file:") || version.startsWith("link:")) local.push(`${name}@${version}`);
+		}
+		appPkg[section] = Object.fromEntries(Object.entries(merged).sort());
+	}
+	if (rootPkg["patchedDependencies"]) appPkg["patchedDependencies"] = rootPkg["patchedDependencies"];
+	await writeFile(appPkgPath, `${JSON.stringify(appPkg, null, 2)}\n`, "utf8");
+
+	// The patches the pins refer to, and the lockfile, so the install is the
+	// one that was tested rather than whatever resolves today.
+	for (const file of ["bun.lock", "bun.lockb", "package-lock.json", "pnpm-lock.yaml"]) {
+		const source = join(project.root, file);
+		if (existsSync(source)) await cp(source, join(target, file));
+	}
+	if (existsSync(join(project.root, "patches"))) await copyResolved(join(project.root, "patches"), join(target, "patches"));
+	await writeFile(join(target, "README.md"), README(project.manifest.shop.domain), "utf8");
+	await writeFile(join(target, ".gitignore"), "node_modules\ndist\n.void\n.wrangler\n.env\n.env.local\n", "utf8");
+
+	console.log(`${color.green("✓")} ${relative(project.root, target) || target} — a self-contained Void app`);
+	if (local.length > 0) {
+		console.log(
+			color.yellow(
+				`\n! ${local.length} dependenc${local.length === 1 ? "y is" : "ies are"} local paths and will not install from a fresh checkout:\n    ${local.join("\n    ")}\n  Publish them, or point them at a registry, before a build machine uses this tree.`,
+			),
+		);
+	}
+	return 0;
+}
+
+export async function distHelp(): Promise<number> {
+	const width = 80;
+	console.log(
+		box("vc dist", [
+			line("The deployable app as a self-contained tree: symlinks resolved, the", width),
+			line("repository's resolved versions, the lockfile, the patches.", width),
+			line("", width),
+			...row("vc dist", `writes ${DIST_DIR}`, width, 2),
+			...row("vc dist --out <dir>", "writes it somewhere else", width, 2),
+			line("", width),
+			line(`The generated workflow pushes this to the \`${DIST_BRANCH}\` branch on every`, width),
+			line("push to main, so Cloudflare builds a plain Void app and you edit a manifest.", width),
+		], width),
+	);
+	return 0;
+}

package/src/generate/auth.ts

@@ -0,0 +1,386 @@
+import { type Manifest, has } from "../manifest";
+
+/**
+ * `auth.ts` — the plugin ring, wired from the manifest.
+ *
+ * ── Generated INTO a file you own ────────────────────────────────────────
+ *
+ * Void will not scan a `plugins/` directory — its convention set is closed —
+ * and a Vite plugin emitting a virtual module would be hidden machinery that
+ * makes a future merge into Void harder, not easier. So this is written where
+ * a reader can see it, the way `rails generate` writes into files you own.
+ * Regenerate from the manifest; do not hand-edit the marked region.
+ *
+ * Every choice the wizard made shows up here as a plugin call with the same
+ * comment the wizard showed. The file explains itself to the next reader.
+ */
+
+interface Line {
+	/** The import statement. */
+	import?: string | undefined;
+	/** The call inside the relevant plugins array. Empty for an import-only line. */
+	call: string;
+	/** Which array it goes in. */
+	ring: "auth" | "commerce";
+	/** One line of why. */
+	why: string;
+}
+
+/** Rates by country, so a fresh deploy is never tax-free. Standard VAT only. */
+const VAT: Record<string, { rate: number; name: string }> = {
+	DK: { rate: 2500, name: "Moms" },
+	SE: { rate: 2500, name: "Moms" },
+	NO: { rate: 2500, name: "MVA" },
+	FI: { rate: 2550, name: "ALV" },
+	DE: { rate: 1900, name: "MwSt" },
+	NL: { rate: 2100, name: "BTW" },
+	FR: { rate: 2000, name: "TVA" },
+	GB: { rate: 2000, name: "VAT" },
+	IE: { rate: 2300, name: "VAT" },
+	ES: { rate: 2100, name: "IVA" },
+	IT: { rate: 2200, name: "IVA" },
+	AT: { rate: 2000, name: "USt" },
+	BE: { rate: 2100, name: "BTW" },
+	PL: { rate: 2300, name: "VAT" },
+};
+
+const social = (manifest: Manifest, id: string, envPrefix: string) =>
+	has(manifest, id)
+		? `			${id}: { clientId: must(env, "${envPrefix}_CLIENT_ID"), clientSecret: must(env, "${envPrefix}_CLIENT_SECRET") },`
+		: null;
+
+export function renderAuthTs(manifest: Manifest): string {
+	const { shop } = manifest;
+	const lines: Line[] = [];
+	/**
+	 * The token route, when it was chosen. It wraps the PHYSICAL provider
+	 * rather than sitting beside it, because the buyer's choice lives on the
+	 * line: one provider reads it and sends the line down one road or the
+	 * other. `mintProvider` is the app's to configure — the default records
+	 * the intent and mints nothing, which is the honest state for a shop that
+	 * has not chosen a chain.
+	 */
+	const wantsNft = has(manifest, "nft");
+	const nftProvider = wantsNft
+		? `, nftOrPhysical({ mint: mintProvider, physical: ${has(manifest, "business-central") ? `erpFulfillment("${shop.currency.toUpperCase()}")` : "manualFulfillment()"} })`
+		: "";
+	const nftDefault = wantsNft ? `, defaultProvider: "nft-or-physical"` : "";
+
+	const vat = VAT[shop.country];
+
+	// ── auth ring ────────────────────────────────────────────────────────
+	lines.push({
+		import: `import { admin } from "better-auth/plugins/admin";`,
+		call: `admin()`,
+		ring: "auth",
+		why: "who may open the panel",
+	});
+	lines.push({
+		import: `import { systemUser } from "@saastemly/better-system-user";`,
+		call: `systemUser({ key: read(env, "SYSTEM_API_KEY"), email: "system@${shop.domain}", name: "${shop.name} system" })`,
+		ring: "auth",
+		why: "the deployment authenticates as itself — no human sign-in to bootstrap",
+	});
+	if (has(manifest, "magic-link"))
+		lines.push({
+			import: `import { magicLink } from "better-auth/plugins/magic-link";`,
+			call: `magicLink({ sendMagicLink: emailer.auth.sendMagicLink, expiresIn: 60 * 15 })`,
+			ring: "auth",
+			why: "one tap on the device the mail is open on; signs up too",
+		});
+	if (has(manifest, "email-otp"))
+		lines.push({
+			import: `import { emailOTP } from "better-auth/plugins/email-otp";`,
+			call: `emailOTP({ sendVerificationOTP: emailer.auth.sendVerificationOTP, otpLength: 6, expiresIn: 60 * 10, allowedAttempts: 3 })`,
+			ring: "auth",
+			why: "a code, for when the mail is on a different device; three tries",
+		});
+	if (has(manifest, "passkey"))
+		lines.push({
+			import: `import { passkey } from "@better-auth/passkey";`,
+			call: `passkey({ rpName: "${shop.name}", rpID: domain.host, origin: domain.appUrl })`,
+			ring: "auth",
+			why: "sign-in only; a passkey is created against an account that exists",
+		});
+	if (has(manifest, "username"))
+		lines.push({ import: `import { username } from "better-auth/plugins/username";`, call: `username()`, ring: "auth", why: "sign in by handle" });
+	if (has(manifest, "phone"))
+		lines.push({ import: `import { phoneNumber } from "better-auth/plugins/phone-number";`, call: `phoneNumber({ sendOTP: async () => { /* TODO: wire an SMS provider */ } })`, ring: "auth", why: "SMS codes — TODO wire a provider" });
+	if (has(manifest, "anonymous"))
+		lines.push({ import: `import { anonymous } from "better-auth/plugins/anonymous";`, call: `anonymous()`, ring: "auth", why: "a cart before an address" });
+	if (has(manifest, "api-key"))
+		lines.push({
+			import: `import { apiKey } from "@better-auth/api-key";`,
+			call: `apiKey({ enableSessionForAPIKeys: true, requireName: true, enableMetadata: true, rateLimit: { enabled: true, timeWindow: 60_000, maxRequests: 120 } })`,
+			ring: "auth",
+			why: "machine access; the default is 10 requests per DAY and surfaces as a 500",
+		});
+	if (has(manifest, "two-factor"))
+		lines.push({ import: `import { twoFactor } from "better-auth/plugins/two-factor";`, call: `twoFactor()`, ring: "auth", why: "TOTP for operators" });
+	if (has(manifest, "organization"))
+		lines.push({ import: `import { organization } from "better-auth/plugins/organization";`, call: `organization()`, ring: "auth", why: "teams that share a shop account" });
+	if (has(manifest, "multi-session"))
+		lines.push({ import: `import { multiSession } from "better-auth/plugins/multi-session";`, call: `multiSession()`, ring: "auth", why: "switch accounts without signing out" });
+	if (has(manifest, "jwt"))
+		lines.push({ import: `import { jwt } from "better-auth/plugins/jwt";`, call: `jwt()`, ring: "auth", why: "tokens for a service that cannot hold a cookie" });
+	if (has(manifest, "bearer"))
+		lines.push({ import: `import { bearer } from "better-auth/plugins/bearer";`, call: `bearer()`, ring: "auth", why: "the session token in a header" });
+	if (has(manifest, "haveibeenpwned"))
+		lines.push({ import: `import { haveIBeenPwned } from "better-auth/plugins/haveibeenpwned";`, call: `haveIBeenPwned()`, ring: "auth", why: "refuse a breached password" });
+	if (has(manifest, "one-time-token"))
+		lines.push({ import: `import { oneTimeToken } from "better-auth/plugins/one-time-token";`, call: `oneTimeToken()`, ring: "auth", why: "hand a session to another origin once" });
+	if (has(manifest, "generic-oauth"))
+		lines.push({ import: `import { genericOAuth } from "better-auth/plugins/generic-oauth";`, call: `genericOAuth({ config: [] /* TODO: your provider */ })`, ring: "auth", why: "an identity provider Better Auth does not ship" });
+	if (has(manifest, "oauth-proxy"))
+		lines.push({ import: `import { oAuthProxy } from "better-auth/plugins/oauth-proxy";`, call: `oAuthProxy()`, ring: "auth", why: "OAuth callbacks on preview URLs" });
+	if (has(manifest, "siwe"))
+		lines.push({ import: `import { siwe } from "better-auth/plugins/siwe";`, call: `siwe({ domain: domain.host, getNonce: async () => crypto.randomUUID(), verifyMessage: async () => false /* TODO */ })`, ring: "auth", why: "wallet sign-in — TODO verifyMessage" });
+	if (has(manifest, "device-authorization"))
+		lines.push({ import: `import { deviceAuthorization } from "better-auth/plugins/device-authorization";`, call: `deviceAuthorization()`, ring: "auth", why: "sign in on a TV or CLI" });
+	if (has(manifest, "custom-session"))
+		lines.push({ import: `import { customSession } from "better-auth/plugins/custom-session";`, call: `customSession(async ({ user, session }) => ({ user, session }))`, ring: "auth", why: "computed fields on every session" });
+	// Strict has no array to edit: launch content is content/*.json, snapshotted into lib/content.ts.
+	const strict = manifest.layout === "strict";
+	if (has(manifest, "blogs"))
+		lines.push({
+			import: `import { blogs } from "@saastemly/better-blogs";${strict ? `\nimport { posts as launchPosts } from "./lib/content.ts";` : ""}`,
+			call: `blogs({ defaultLocale: "${shop.locale}", posts: ${strict ? "launchPosts" : "[]"} })`,
+			ring: "auth",
+			why: strict ? "launch posts come from content/posts.json" : "launch posts go in the array; an operator edits rows afterwards",
+		});
+	if (has(manifest, "faqs"))
+		lines.push({
+			import: `import { faqs } from "@saastemly/better-faqs";${strict ? `\nimport { faqEntries } from "./lib/content.ts";` : ""}`,
+			call: `faqs({ defaultLocale: "${shop.locale}", entries: ${strict ? "faqEntries" : "[]"} })`,
+			ring: "auth",
+			why: strict ? "launch FAQ comes from content/faqs.json" : "launch FAQ goes in the array",
+		});
+	if (has(manifest, "cloudflare") || has(manifest, "simply"))
+		lines.push({
+			import: `import { dns } from "@saastemly/better-dns";\nimport { ${has(manifest, "cloudflare") ? "cloudflareDns" : "simplyDns"} } from "@saastemly/better-dns/providers/${has(manifest, "cloudflare") ? "cloudflare" : "simply"}";`,
+			call: has(manifest, "cloudflare")
+				? `dns({ providers: dnsToken ? { cloudflare: cloudflareDns({ apiToken: dnsToken }) } : {}, zones: dnsToken ? { [domain.zone]: "cloudflare" } : {}, records: dnsToken ? storefrontRecords(domain, read(env, "GITHUB_PAGES_HOST") ?? "") : [] })`
+				: `dns({ providers: dnsToken ? { simply: simplyDns({ apiKey: dnsToken }) } : {}, zones: dnsToken ? { [domain.zone]: "simply" } : {}, records: dnsToken ? storefrontRecords(domain, read(env, "GITHUB_PAGES_HOST") ?? "") : [] })`,
+			ring: "auth",
+			why: "the deploy points the domain; a sync never removes a record it did not declare",
+		});
+	lines.push({ import: `import { email } from "@saastemly/better-email";`, call: `email({ emailer })`, ring: "auth", why: "a log of every send — the difference between a shrug and the provider's own refusal" });
+	if (has(manifest, "admin")) {
+		lines.push({ import: `import { apiDashboard } from "@saastemly/better-admin-ui/server";`, call: `apiDashboard()`, ring: "auth", why: "the generated storefront and panel's server half" });
+	}
+
+	// ── commerce ring ────────────────────────────────────────────────────
+	const commerce = (id: string, call: string, why: string, imp?: string) => {
+		if (has(manifest, id)) lines.push({ import: imp ?? `import { ${camel(id)} } from "@saastemly/better-commerce/plugins/${id}";`, call, ring: "commerce", why });
+	};
+	commerce("catalog", `catalog()`, "products as rows; the panel grows Product screens");
+	commerce("catalog-import", `catalogImport({ sources: [] })`, "pushed from \`vc import\`; the worker carries no catalogue");
+	commerce("metafields", `metafields({ definitions: [] })`, "typed custom data on any row");
+	commerce("personalization", `personalization()`, "validated at add-to-cart, priced from rows never from the client");
+	commerce("inventory", `inventory()`, "stock and reservations");
+	commerce("bundles", `bundles({ bundles: [] })`, "kits at a set price");
+	commerce("price-lists", `priceLists()`, "per-group and per-date prices");
+	commerce("translations", `translations()`, "copy in more than one language");
+	commerce("search", `search({ provider: memorySearchProvider() })`, "memory locally; swap for Meilisearch", `import { search } from "@saastemly/better-commerce/plugins/search";\nimport { memorySearchProvider } from "@saastemly/better-commerce/providers/search";`);
+	commerce("regions", `regions({ regions: [{ id: "${shop.country.toLowerCase()}", name: "${shop.country}", currency: "${shop.currency}", countries: ["${shop.country}"], isDefault: true }] })`, "where you sell, in what currency");
+	commerce("sales-channels", `salesChannels({ channels: [{ id: "web", name: "Web", isDefault: true }] })`, "scope products per channel");
+	commerce("discounts", `discounts()`, "codes and campaigns");
+	commerce("gift-cards", `giftCards()`, "balance derived from the ledger", `import { giftCards, giftCardFulfillment } from "@saastemly/better-commerce/plugins/gift-cards";`);
+	commerce("loyalty", `loyalty()`, "earn on paid orders");
+	commerce("subscriptions", `subscriptions()`, "recurring orders");
+	commerce("draft-orders", `draftOrders()`, "an operator builds a cart for a buyer");
+	commerce("order-edits", `orderEdits()`, "change a paid order, charge or refund the difference");
+	commerce("returns", `returns()`, "the road to a refund");
+	commerce("wishlists", `wishlists()`, "prices resolved on read");
+	commerce("reviews", `reviews()`, "verified badge derived from a paid order");
+	commerce("customer-groups", `customerGroups()`, "segments with their own prices");
+	commerce("acp", `acp({ merchantDisplayName: "${shop.name}" })`, "agentic commerce", `import { acp } from "@saastemly/better-commerce/acp";`);
+	commerce(
+		"fulfillments",
+		`fulfillments({ providers: [authFulfillment(), creditsFulfillment()${has(manifest, "gift-cards") ? ", giftCardFulfillment()" : ""}${has(manifest, "business-central") ? `, erpFulfillment("${shop.currency.toUpperCase()}")` : ""}${nftProvider}]${nftDefault} })`,
+		"what happens when the money is confirmed",
+		`import { authFulfillment, creditsFulfillment, fulfillments, manualFulfillment } from "@saastemly/better-commerce/plugins/fulfillments";${has(manifest, "business-central") ? `\nimport { erpFulfillment } from "./lib/erp.ts";` : ""}`,
+	);
+	commerce(
+		"shipping-zones",
+		`shippingZones({ zones: [{ id: "domestic", name: "${shop.country}", countries: ["${shop.country}"], rank: 0 }], shippingOptions: [{ id: "standard", zoneId: "domestic", name: "Standard", priceType: "flat", amount: Number(must(env, "SHIPPING_DOMESTIC_MINOR")), currency: "${shop.currency}", rank: 0 }, { id: "free", zoneId: "domestic", name: "Free", priceType: "free", currency: "${shop.currency}", minSubtotal: Number(must(env, "SHIPPING_FREE_FROM_MINOR")), rank: 1 }] })`,
+		"quoted from required env; a shop with no option quotes FREE delivery silently",
+	);
+	/**
+	 * Tax is declared only when the shop is REGISTERED to charge it. A
+	 * business below its registration threshold that adds tax to a price is
+	 * collecting money it has no right to; one above it that does not is
+	 * paying the tax out of its own margin. Neither is a default worth
+	 * guessing, so the manifest answers it.
+	 */
+	const registered = shop.taxRegistered === true;
+	const askedLive = has(manifest, "stripe-tax");
+	commerce(
+		"tax-regions",
+		askedLive
+			? `taxRegions({ regions: [{ countryCode: "${shop.country}", name: "${shop.country}", rates: [] }], attachTax: false })`
+			: !registered
+			? `taxRegions({ regions: [{ countryCode: "${shop.country}", name: "${shop.country}", rates: [] }] })`
+			: vat
+				? `taxRegions({ regions: [{ countryCode: "${shop.country}", name: "${shop.country}", rates: [{ name: "${vat.name}", code: "vat", rate: ${vat.rate} }] }] })`
+				: `taxRegions({ regions: [{ countryCode: "${shop.country}", name: "${shop.country}", rates: [] }] /* TODO VERIFY: no standard rate known for ${shop.country} */ })`,
+		askedLive
+			? "Stripe is asked per basket, so an unregistered shop charges nothing and a registered one charges the buyer's own rate — with nothing here to keep up to date"
+			: !registered
+			? `NOT registered for ${vat?.name ?? "VAT"}: no tax is added, because a business below the threshold must not charge it. Set taxRegistered in voidcommerce.json when you register.`
+			: vat
+				? `${vat.rate / 100}% ${vat.name} declared in code, so a fresh deploy is never tax-free`
+				: "TODO VERIFY: registered, but no standard rate is known for this country — declare it",
+	);
+	// Import-only: the calculator is an argument to taxRegions(), not a plugin.
+	if (askedLive)
+		lines.push({
+			import: `import { taxCalculator } from "@saastemly/better-commerce/providers/tax";\nimport { stripeTax } from "@saastemly/better-commerce/providers/stripe-tax";`,
+			call: "",
+			ring: "commerce",
+			why: "",
+		});
+	commerce("notifications", `notifications({ provider: emailNotifications(emailer) })`, "order confirmations, queued and retried", `import { notifications } from "@saastemly/better-commerce/plugins/notifications";\nimport { emailNotifications } from "./lib/notifications.ts";`);
+	commerce("events", `events()`, "webhooks with retries");
+	commerce("workflows", `workflows()`, "multi-step operations that survive a crash");
+	commerce("files", `files({ provider: memoryFileProvider() })`, "uploads; swap for R2", `import { files } from "@saastemly/better-commerce/plugins/files";\nimport { memoryFileProvider } from "@saastemly/better-commerce/providers/file";`);
+	commerce("merchants", `merchants()`, "several sellers, with payouts");
+	if (has(manifest, "nft"))
+		lines.push({
+			import: `import { nft, nftOrPhysical } from "@saastemly/better-commerce/plugins/nft";\nimport { mintProvider } from "./lib/mint.ts";`,
+			call: `nft({ blurb: "Rather not have the object? Take an authentic, completely useless token of it instead. Nothing gets printed, nothing gets posted." })`,
+			ring: "commerce",
+			why: "the buyer chooses a parcel or a token; the catalogue is the same either way",
+		});
+	commerce("store", `store({ name: "${shop.name}", settings: { "support.email": { value: "info@${shop.domain}", public: true } } })`, "public settings the storefront reads");
+	commerce("runtime", `runtime({ cache: memoryCacheProvider(), lock: databaseLockProvider })`, "cache and locks", `import { runtime } from "@saastemly/better-commerce/plugins/runtime";\nimport { memoryCacheProvider } from "@saastemly/better-commerce/providers/cache";\nimport { databaseLockProvider } from "@saastemly/better-commerce/providers/locking";`);
+
+	const imports = [...new Set(lines.flatMap((line) => (line.import ? line.import.split("\n") : [])))].sort();
+	const render = (ring: Line["ring"]) =>
+		lines
+			// A line may carry only an import — the tax calculator is a value the
+			// plugin takes, not a plugin of its own.
+			.filter((line) => line.ring === ring && line.call !== "")
+			.map((line) => `			// ${line.why}\n			${line.call},`)
+			.join("\n");
+
+	const rail = has(manifest, "adyen") ? "adyen" : "stripe";
+
+	/**
+	 * Mail. Cloudflare's binding is the one transport with no credential at
+	 * all — the Worker's own account is the authorisation — so where it is
+	 * chosen there is nothing to put in a secret and nothing to rotate.
+	 * Neither provider exists locally, so MailDev stands in for both.
+	 */
+	// A shop with no DNS provider has no token to read, and naming one that is
+	// not in env.ts is a lie a reader has to disprove.
+	const dnsProvider = has(manifest, "cloudflare") ? "CLOUDFLARE_DNS_TOKEN" : has(manifest, "simply") ? "SIMPLY_API_KEY" : null;
+	const dnsDeclaration = dnsProvider ? `	const dnsToken = read(env, "${dnsProvider}");` : "";
+	const cloudflareMail = has(manifest, "cloudflare-email");
+	const mailProvider = cloudflareMail ? "Cloudflare" : "Resend";
+	const mailImport = cloudflareMail
+		? `import { cloudflareTransport } from "@saastemly/better-email/transports/cloudflare";`
+		: `import { resendTransport } from "@saastemly/better-email/transports/resend";`;
+	const mailBinding = cloudflareMail
+		? `// The Worker's own send_email binding. Read late: bindings are not always
+	// readable at module scope, and locally there is none at all.
+	const mail = (env as Record<string, unknown>)["EMAIL"] as Parameters<typeof cloudflareTransport>[0]["binding"];`
+		: `const resendKey = read(env, "RESEND_API_KEY");`;
+	const mailTransport = cloudflareMail
+		? `mail ? cloudflareTransport({ binding: mail }) : smtpTransport()`
+		: `resendKey ? resendTransport({ apiKey: resendKey }) : smtpTransport()`;
+	const mailTransportId = cloudflareMail ? `mail ? "cloudflare" : "maildev"` : `resendKey ? "resend" : "maildev"`;
+	const socials = [social(manifest, "google", "GOOGLE"), social(manifest, "apple", "APPLE"), social(manifest, "github", "GITHUB")].filter(Boolean);
+
+	return `// GENERATED by \`vc init\` from voidcommerce.json. Edit the manifest and
+// run \`vc init\` again; hand edits between the markers are overwritten.
+import { commerce } from "@saastemly/better-commerce";
+import { defineAuth } from "void/auth";
+import { createEmailer, logSends } from "@saastemly/better-email";
+import { getCurrentAuthContext } from "@better-auth/core/context";
+${mailImport}
+import { smtpTransport } from "@saastemly/better-email/transports/smtp";
+import { paymentProvider } from "./lib/payment.ts";
+import { shopDomain, storefrontRecords } from "./lib/domain.ts";
+${imports.join("\n")}
+
+type ConfigEnv = Record<string, unknown>;
+
+/** \`unset\` is the one documented value that reads as absent. Preflight refuses it. */
+const UNSET = "unset";
+const read = (env: ConfigEnv, key: string): string | undefined => {
+	const value = env[key];
+	if (typeof value !== "string" || value.length === 0) return undefined;
+	return value === UNSET ? undefined : value;
+};
+const must = (env: ConfigEnv, key: string): string => read(env, key) ?? "";
+
+export default defineAuth(({ defaults, env }) => {
+	const domain = shopDomain(must(env, "SHOP_DOMAIN") || "localhost.test", read(env, "SHOP_ZONE"));
+	${mailBinding}
+	const cronSecret = read(env, "COMMERCE_CRON_SECRET");
+${dnsDeclaration}
+
+	/** One transport for every email; MailDev locally, ${mailProvider} in production. */
+	const emailer = createEmailer({
+		appName: "${shop.name}",
+		from: read(env, "EMAIL_FROM") ?? "${shop.name} <noreply@${shop.domain}>",
+		locale: "${shop.locale.slice(0, 2)}" as never,
+		transport: ${mailTransport},
+		onSent: logSends(async () => {
+			try {
+				const endpoint = (await getCurrentAuthContext()) as unknown as { context?: { adapter?: unknown } };
+				return (endpoint.context?.adapter ?? null) as never;
+			} catch {
+				return null;
+			}
+		}, { transportId: ${mailTransportId} }),
+	});
+
+	return {
+		...defaults,
+		// Better Auth defaults this to NODE_ENV=production, which a Worker never sets.
+		rateLimit: { enabled: true, storage: "database" },
+		// Explicit, because the default is off and a version bump could flip it.
+		emailAndPassword: { enabled: ${has(manifest, "password")} },
+		socialProviders: {
+${socials.join("\n")}
+		},
+		account: { accountLinking: { enabled: true, trustedProviders: [${has(manifest, "google") ? '"google"' : ""}${has(manifest, "apple") ? ', "apple"' : ""}] } },
+		emailVerification: { sendVerificationEmail: emailer.auth.sendVerificationEmail, sendOnSignUp: false },
+		trustedOrigins: [...(Array.isArray(defaults.trustedOrigins) ? defaults.trustedOrigins : []), ...domain.frontendOrigins],
+		advanced: {
+			...defaults.advanced,
+			...(domain.frontendOrigins.length > 0 ? { defaultCookieAttributes: { sameSite: "none" as const, secure: true } } : {}),
+		},
+		plugins: [
+			...(Array.isArray(defaults.plugins) ? defaults.plugins : []),
+			// ── vc:auth ─────────────────────────────────────────────────
+${render("auth")}
+			// ── /vc:auth ────────────────────────────────────────────────
+			commerce({
+				provider: paymentProvider, // ${rail}
+				defaultCurrency: () => "${shop.currency}",${
+					askedLive
+						? `
+				// The rate is asked for per basket, so there is none to declare:
+				// no registration means no tax, and a registration means the
+				// buyer's own rate. taxRegions() keeps its tables and admin
+				// routes but does not claim this slot.
+				pricing: { tax: taxCalculator(stripeTax({ secretKey: must(env, "STRIPE_SECRET_KEY") })) },`
+						: ""
+				}
+				...(cronSecret ? { cron: { secret: cronSecret } } : {}),
+				plugins: [
+					// ── vc:commerce ─────────────────────────────────────
+${render("commerce").replace(/^/gm, "\t")}
+					// ── /vc:commerce ────────────────────────────────────
+				],
+			}),
+		],
+	};
+});
+`;
+}
+
+const camel = (id: string) => id.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());