@saastemly/voidcommerce 0.1.0

package/src/generate/index.ts

@@ -0,0 +1,390 @@
+import { cp, mkdir, readFile, readdir, symlink, writeFile } from "node:fs/promises";
+import { existsSync, lstatSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CHOICES } from "../catalog";
+import { MANIFEST_FILE, type Manifest, has, isSingleApp, packagesOf, specifier, workerHosts, writeManifest, zone } from "../manifest";
+import { renderAuthTs } from "./auth";
+import {
+	envSummary,
+	renderEnvExample,
+	renderEnvLocal,
+	renderEnvProduction,
+	renderEnvTs,
+} from "./env";
+import {
+	FRONTEND_BRANCH,
+	renderFrontendApiTs,
+	renderFrontendEnvProduction,
+	renderFrontendTsconfig,
+	renderFrontendViteConfig,
+	renderFrontendVoidJson,
+	renderFrontendWorkflow,
+	renderStorefrontPage,
+} from "./frontend";
+import { renderDeployReadme, renderDistWorkflow } from "./ci";
+import { renderRequirementsTs } from "./requirements";
+import {
+	BRANDING_README,
+	CLIENT_ONLY,
+	DATA_README,
+	INDEX_PAGE,
+	MIGRATIONS_README,
+	STRICT_APP,
+	renderAppCss,
+	renderAuthClient,
+	renderContentTs,
+	renderCron,
+	renderDashboardPage,
+	renderDbSchema,
+	renderDbSeed,
+	renderIndexServer,
+	renderLayoutTsx,
+	renderLiveRoute,
+	renderLiveStream,
+	renderQueue,
+	renderSignInPage,
+	renderStrictAppPackageJson,
+	renderStrictTsconfig,
+	renderViteConfig,
+	renderVoidJson,
+	renderVoidPatch,
+	strictDependencies,
+} from "./strict";
+import { renderDomainTs, renderErpTs, renderMintTs, renderNotificationsTs, renderPaymentTs } from "./support";
+
+/**
+ * Turn a manifest into files.
+ *
+ * Two kinds of file, and the difference matters:
+ *
+ *   REGENERATED — `auth.ts`, `env.ts`, `.env.example`, `.env.production`,
+ *   `lib/deploy/requirements.ts`, the Pages workflow. Derived entirely from
+ *   the manifest; edit the manifest, not the file.
+ *
+ *   OWNED — `lib/domain.ts`, `lib/payment.ts`, `lib/notifications.ts`,
+ *   `lib/erp.ts`, `.env`, the frontend's `lib/api.ts`. Written once if
+ *   absent, then yours. They are what a shop edits when it grows past the
+ *   wizard, and overwriting them would destroy that work.
+ *
+ * Where the files go follows the layout: one app writes at the root; a
+ * monorepo writes api/ and frontend/ and a root that holds both; strict
+ * writes the whole app under .vc/app, where NOTHING is owned — the point of
+ * strict is that the manifest is the only source.
+ */
+
+export interface GenerateResult {
+	written: string[];
+	kept: string[];
+	packages: string[];
+}
+
+async function exists(path: string): Promise<boolean> {
+	try {
+		await readFile(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function put(root: string, file: string, content: string, result: GenerateResult, mode: "regenerate" | "own") {
+	const path = join(root, file);
+	if (mode === "own" && (await exists(path))) {
+		result.kept.push(file);
+		return;
+	}
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, content, "utf8");
+	result.written.push(file);
+}
+
+/** Read a JSON file if present, let the caller add to it, write it back. Everything else in it is kept. */
+async function mergeJson(root: string, file: string, fallback: Record<string, unknown>, mutate: (json: Record<string, unknown>) => void, result: GenerateResult) {
+	const path = join(root, file);
+	const json = (await exists(path)) ? (JSON.parse(await readFile(path, "utf8")) as Record<string, unknown>) : { ...fallback };
+	mutate(json);
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, `${JSON.stringify(json, null, 2)}\n`, "utf8");
+	result.written.push(file);
+}
+
+/** A symlink, if nothing is there yet. Never replaces a real file. */
+async function link(root: string, file: string, target: string, result: GenerateResult) {
+	const path = join(root, file);
+	try {
+		lstatSync(path);
+		result.kept.push(file);
+		return;
+	} catch {
+		await mkdir(dirname(path), { recursive: true });
+		await symlink(target, path);
+		result.written.push(`${file} → ${target}`);
+	}
+}
+
+const sorted = (record: Record<string, string>) => Object.fromEntries(Object.entries(record).sort());
+
+export async function generate(root: string, manifest: Manifest): Promise<GenerateResult> {
+	const result: GenerateResult = { written: [], kept: [], packages: packagesOf(manifest) };
+
+	await writeManifest(root, manifest);
+	result.written.push(MANIFEST_FILE);
+
+	switch (manifest.layout) {
+		case "app":
+			await generateApi(root, "", manifest, result, { ownable: true, env: true });
+			break;
+		case "monorepo":
+			await generateApi(root, "api", manifest, result, { ownable: true, env: true });
+			await generateFrontend(root, "frontend", manifest, result);
+			await generateRoot(root, manifest, result);
+			break;
+		case "strict":
+			await generateStrictRoot(root, manifest, result);
+			// The storefront IS the repository root, sharing its package.json.
+			await generateFrontend(root, "", manifest, result);
+			await generateApi(root, STRICT_APP, manifest, result, { ownable: false, env: false });
+			await generateStrictApp(root, STRICT_APP, manifest, result);
+			break;
+	}
+	return result;
+}
+
+/**
+ * The worker — the whole app in one-app layout, api/ in a monorepo, .vc/app
+ * in strict. `ownable` is false where nothing may be hand-edited; `env` is
+ * false where `.env` is reached by symlink instead.
+ */
+async function generateApi(root: string, dir: string, manifest: Manifest, result: GenerateResult, opts: { ownable: boolean; env: boolean }) {
+	const at = (file: string) => join(dir, file);
+	const own = opts.ownable ? "own" : "regenerate";
+	const single = isSingleApp(manifest.layout);
+
+	await put(root, at("auth.ts"), renderAuthTs(manifest), result, "regenerate");
+	await put(root, at("env.ts"), renderEnvTs(manifest), result, "regenerate");
+	await put(root, at(".env.example"), renderEnvExample(manifest), result, "regenerate");
+	await put(root, at(".env.production"), renderEnvProduction(manifest), result, "regenerate");
+	await put(root, at("lib/deploy/requirements.ts"), renderRequirementsTs(manifest), result, "regenerate");
+
+	if (opts.env) await put(root, at(".env"), renderEnvLocal(manifest), result, "own");
+	await put(root, at("lib/domain.ts"), renderDomainTs(manifest.layout), result, own);
+	await put(root, at("lib/payment.ts"), renderPaymentTs(manifest), result, own);
+	await put(root, at("lib/notifications.ts"), renderNotificationsTs(), result, own);
+	if (has(manifest, "nft")) {
+		await put(root, at("lib/mint.ts"), renderMintTs(), result, own);
+	}
+	if (has(manifest, "business-central")) {
+		await put(root, at("lib/erp.ts"), renderErpTs(), result, own);
+	}
+
+	const name = manifest.shop.domain.split(".")[0]!;
+	const hosts = workerHosts(manifest);
+	const routes = `[\n${hosts.map((host) => `    { "pattern": "${host}", "custom_domain": true }`).join(",\n")}\n  ]`;
+	// Cloudflare Email Service is reached through a binding, not a key.
+	const sendEmail = has(manifest, "cloudflare-email")
+		? `,
+  // Cloudflare Email Service. The binding IS the credential; the sending
+  // domain is onboarded once in the dashboard, which writes its own SPF,
+  // DKIM, DMARC and bounce records.
+  "send_email": [{ "name": "EMAIL" }]`
+		: "";
+	const cf = manifest.cloudflare;
+	const d1 = cf?.d1
+		? `,
+  // Created by \`vc deploy --cloudflare --provision\`; the id is what the deploy binds.
+  "d1_databases": [
+    { "binding": "DB", "database_name": "${cf.d1.name}", "database_id": "${cf.d1.id}", "migrations_dir": "./db/migrations" }
+  ]`
+		: "";
+	await put(
+		root,
+		at("wrangler.jsonc"),
+		`{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "${single ? name : `${name}-api`}",
+  // Pin the account. A multi-account token makes wrangler prompt, which CI cannot answer.
+  "account_id": "${cf?.accountId ?? ""}",
+  // The worker's hostname${hosts.length > 1 ? "s" : ""}. Cloudflare custom domain${hosts.length > 1 ? "s" : ""}, not DNS records this
+  // app writes — Cloudflare creates the record and the certificate itself.
+  // The zone (${zone(manifest)}) must be on Cloudflare; \`vc preflight\` checks the names.
+  "routes": ${routes}${sendEmail}${d1}
+}
+`,
+		result,
+		own,
+	);
+
+	if (manifest.layout === "strict") return; // its package.json is the artifact's, written by generateStrictApp
+
+	await mergeJson(
+		root,
+		at("package.json"),
+		{ name: single ? name : `${name}-api`, type: "module", private: true },
+		(pkg) => {
+			const deps = { ...((pkg["dependencies"] as Record<string, string>) ?? {}) };
+			for (const dep of result.packages) deps[dep] ??= specifier(manifest, dep);
+			pkg["dependencies"] = sorted(deps);
+			const scripts = { ...((pkg["scripts"] as Record<string, string>) ?? {}) };
+			scripts["preflight"] ??= "vc preflight";
+			scripts["deploy"] ??= "vc deploy";
+			scripts["import:catalog"] ??= "vc import";
+			scripts["maildev"] ??= "maildev --smtp 1025 --web 1080";
+			pkg["scripts"] = scripts;
+		},
+		result,
+	);
+}
+
+/** The static storefront on GitHub Pages. Only in a monorepo. */
+async function generateFrontend(root: string, dir: string, manifest: Manifest, result: GenerateResult) {
+	const at = (file: string) => join(dir, file);
+
+	await put(root, at("lib/api.ts"), renderFrontendApiTs(manifest), result, "own");
+	await put(root, at(".env.production"), renderFrontendEnvProduction(manifest), result, "regenerate");
+	await put(root, at("vite.config.ts"), renderFrontendViteConfig(), result, "own");
+	await put(root, at("void.json"), renderFrontendVoidJson(), result, "own");
+	await put(root, at("tsconfig.json"), renderFrontendTsconfig(), result, "own");
+	await put(root, at("pages/index.tsx"), renderStorefrontPage(manifest), result, "own");
+	await put(root, ".github/workflows/frontend-static.yml", renderFrontendWorkflow(manifest, dir), result, "regenerate");
+
+	// A monorepo's frontend is its own workspace; strict's shares the root's
+	// one package.json, which generateStrictRoot has already written.
+	if (dir === "") return;
+	await mergeJson(
+		root,
+		at("package.json"),
+		{ name: `${manifest.shop.domain.split(".")[0]}-frontend`, type: "module", private: true },
+		(pkg) => {
+			const deps = { ...((pkg["dependencies"] as Record<string, string>) ?? {}) };
+			for (const dep of ["better-auth", "@saastemly/better-commerce", ...(CHOICES.get("custom")?.packages ?? [])]) deps[dep] ??= specifier(manifest, dep);
+			pkg["dependencies"] = sorted(deps);
+			const dev = { ...((pkg["devDependencies"] as Record<string, string>) ?? {}) };
+			for (const dep of ["@hono/node-server", "@void/react", "vite", "vite-plus", "void"]) dev[dep] ??= "latest";
+			pkg["devDependencies"] = sorted(dev);
+		},
+		result,
+	);
+}
+
+/** The monorepo root: one install, and scripts that reach into both. */
+async function generateRoot(root: string, manifest: Manifest, result: GenerateResult) {
+	await mergeJson(
+		root,
+		"package.json",
+		{ name: manifest.shop.domain.split(".")[0], type: "module", private: true },
+		(pkg) => {
+			pkg["workspaces"] = ["api", "frontend"];
+			const scripts = { ...((pkg["scripts"] as Record<string, string>) ?? {}) };
+			scripts["dev:api"] ??= "cd api && vc dev";
+			scripts["dev:frontend"] ??= "cd frontend && vc dev";
+			scripts["preflight"] ??= "cd api && vc preflight";
+			scripts["deploy"] ??= "cd api && vc deploy";
+			scripts["import:catalog"] ??= "cd api && vc import";
+			scripts["maildev"] ??= "cd api && bun run maildev";
+			pkg["scripts"] = scripts;
+		},
+		result,
+	);
+	await put(root, ".gitignore", "node_modules\ndist\n.void\n.wrangler\n*.tsbuildinfo\n.DS_Store\n", result, "own");
+}
+
+/** The strict repository: the manifest, one install, and what the manifest cannot express. */
+async function generateStrictRoot(root: string, manifest: Manifest, result: GenerateResult) {
+	const deps = strictDependencies(manifest);
+	await mergeJson(
+		root,
+		"package.json",
+		{ name: manifest.shop.domain.split(".")[0], type: "module", private: true },
+		(pkg) => {
+			// What is there wins: a pinned version or a `file:` link to a local
+			// package is the person's decision, and regenerating must not undo it.
+			// Only names the choices need and the file lacks are added.
+			pkg["dependencies"] = sorted({ ...deps.dependencies, ...((pkg["dependencies"] as Record<string, string>) ?? {}) });
+			pkg["devDependencies"] = sorted({ ...deps.devDependencies, ...((pkg["devDependencies"] as Record<string, string>) ?? {}) });
+			pkg["patchedDependencies"] = { ...deps.patchedDependencies, ...((pkg["patchedDependencies"] as Record<string, string>) ?? {}) };
+			const scripts = { ...((pkg["scripts"] as Record<string, string>) ?? {}) };
+			scripts["generate"] ??= "vc generate";
+			scripts["dist"] ??= "vc dist";
+			// `dev` is the shop — the worker with the panel. The storefront is
+			// the root's own Void app, so it is vp's to run.
+			scripts["dev"] ??= "vc dev";
+			scripts["build"] ??= "vc build";
+			scripts["dev:storefront"] ??= "vp dev";
+			scripts["build:storefront"] ??= "vp build";
+			scripts["typecheck"] ??= `vc generate && tsc -p ${STRICT_APP}`;
+			scripts["preflight"] ??= "vc preflight";
+			scripts["deploy"] ??= "vc deploy";
+			scripts["import:catalog"] ??= "vc import";
+			scripts["maildev"] ??= "maildev --smtp 1025 --web 1080";
+			pkg["scripts"] = scripts;
+		},
+		result,
+	);
+	// `.void` and `dist` are the STOREFRONT's build artifacts at the root now;
+	// `.vc` holds the generated worker and its own.
+	await put(root, ".gitignore", "node_modules\n.vc\n.void\n.wrangler\n.env\n.env.local\ndist\n*.tsbuildinfo\n.DS_Store\n", result, "own");
+	await put(root, "patches/void@0.10.13.patch", renderVoidPatch(), result, "regenerate");
+	await put(root, ".github/workflows/void-dist.yml", renderDistWorkflow(manifest), result, "regenerate");
+	await put(root, "DEPLOY.md", renderDeployReadme(manifest, zone(manifest), workerHosts(manifest)), result, "regenerate");
+	await put(root, ".env", renderEnvLocal(manifest), result, "own");
+	await put(root, "data/README.md", DATA_README, result, "own");
+	await put(root, "branding/README.md", BRANDING_README, result, "own");
+	await put(root, "migrations/README.md", MIGRATIONS_README, result, "own");
+	if (has(manifest, "faqs")) await put(root, "content/faqs.json", "[]\n", result, "own");
+	if (has(manifest, "blogs")) await put(root, "content/posts.json", "[]\n", result, "own");
+}
+
+/** The strict artifact: a complete Void app, every file regenerated. */
+async function generateStrictApp(root: string, dir: string, manifest: Manifest, result: GenerateResult) {
+	const at = (file: string) => join(dir, file);
+	const gen = "regenerate";
+
+	// Reach the root's install, env and migrations rather than carrying copies.
+	await link(root, at("node_modules"), join("..", "..", "node_modules"), result);
+	await link(root, at(".env"), join("..", "..", ".env"), result);
+	await link(root, at("db/migrations"), join("..", "..", "..", "migrations"), result);
+
+	await put(root, at("package.json"), renderStrictAppPackageJson(manifest), result, gen);
+	await put(root, at("vite.config.ts"), renderViteConfig(manifest), result, gen);
+	await put(root, at("tsconfig.json"), renderStrictTsconfig(), result, gen);
+	await put(root, at("void.json"), renderVoidJson(), result, gen);
+	await put(root, at("db/schema.ts"), renderDbSchema(), result, gen);
+	await put(root, at("db/seed.ts"), renderDbSeed(), result, gen);
+	await put(root, at("pages/layout.tsx"), renderLayoutTsx(), result, gen);
+	await put(root, at("pages/app.css"), renderAppCss(), result, gen);
+	await put(root, at("pages/index.server.ts"), renderIndexServer(), result, gen);
+	await put(root, at("pages/index.tsx"), INDEX_PAGE, result, gen);
+	await put(root, at("pages/api-dashboard/index.tsx"), renderDashboardPage(manifest), result, gen);
+	await put(root, at("pages/api-dashboard/index.server.ts"), CLIENT_ONLY, result, gen);
+	await put(root, at("pages/sign-in/index.tsx"), renderSignInPage(manifest), result, gen);
+	await put(root, at("pages/sign-in/index.server.ts"), CLIENT_ONLY, result, gen);
+	await put(root, at("lib/auth-client.ts"), renderAuthClient(manifest), result, gen);
+	await put(root, at("crons/commerce-ticks.ts"), renderCron(), result, gen);
+	await put(root, at("queues/commerce.ts"), renderQueue(), result, gen);
+	await put(root, at("src/live.ts"), renderLiveStream(), result, gen);
+	await put(root, at("routes/live.ts"), renderLiveRoute(), result, gen);
+
+	// Inputs the manifest cannot express: snapshot them into the artifact.
+	if (has(manifest, "faqs") || has(manifest, "blogs")) {
+		await mkdir(join(root, at("content")), { recursive: true });
+		for (const file of ["faqs.json", "posts.json"]) {
+			const source = join(root, "content", file);
+			if (existsSync(source)) {
+				await cp(source, join(root, at(`content/${file}`)));
+				result.written.push(at(`content/${file}`));
+			}
+		}
+		await put(root, at("lib/content.ts"), renderContentTs(manifest), result, gen);
+	}
+	const branding = join(root, "branding");
+	if (existsSync(branding)) {
+		const files = (await readdir(branding)).filter((name) => name !== "README.md");
+		if (files.length > 0) {
+			await mkdir(join(root, at("public/branding")), { recursive: true });
+			for (const file of files) await cp(join(branding, file), join(root, at(`public/branding/${file}`)), { recursive: true });
+			result.written.push(`${at("public/branding/")} (${files.length} files)`);
+		}
+	}
+}
+
+export { envSummary };

package/src/generate/requirements.ts

@@ -0,0 +1,48 @@
+import type { Manifest } from "../manifest";
+import { allEnvKeys } from "./env";
+
+/**
+ * `lib/deploy/requirements.ts` — the preflight manifest.
+ *
+ * Every key in `env.ts` is required, which stops one being silently absent.
+ * It cannot stop one being PRESENT and meaningless: the `unset` sentinel lets
+ * a developer run the app without an Adyen account, and a deployment carrying
+ * it would start perfectly, take an order, and never charge anyone.
+ *
+ * This is the second gate, and the one that says WHY — because a list of key
+ * names tells an operator nothing about which one is urgent.
+ */
+export function renderRequirementsTs(manifest: Manifest): string {
+	const keys = allEnvKeys(manifest);
+	const entries = keys.map(
+		(key) =>
+			`	{ key: ${JSON.stringify(key.key)}, breaks: ${JSON.stringify(key.breaks)}${key.where ? `, where: ${JSON.stringify(key.where)}` : ""}${key.plaintext ? ", plaintext: true" : ""} },`,
+	);
+	return `// GENERATED by \`vc init\` from voidcommerce.json.
+/**
+ * What "live" requires, and what breaks without each thing.
+ *
+ * \`vc deploy\` refuses on any missing entry; \`vc preflight\` prints the same
+ * list with what is set. The \`unset\` sentinel counts as missing.
+ */
+export const UNSET = "unset";
+
+export interface Requirement {
+	key: string;
+	breaks: string;
+	where?: string;
+	plaintext?: boolean;
+}
+
+export const REQUIREMENTS: Requirement[] = [
+${entries.join("\n")}
+];
+
+export function check(present: Map<string, string | undefined>): Requirement[] {
+	return REQUIREMENTS.filter((requirement) => {
+		const value = present.get(requirement.key);
+		return !present.has(requirement.key) || value === "" || value === UNSET;
+	});
+}
+`;
+}