@saastemly/voidcommerce 0.1.0

package/src/generate/ci.ts

@@ -0,0 +1,208 @@
+import { DIST_BRANCH, DIST_DIR } from "../dist";
+import type { Manifest } from "../manifest";
+
+/**
+ * The workflow that turns a push into a deploy.
+ *
+ * ── Why a branch and not a build ─────────────────────────────────────────
+ *
+ * Cloudflare's Workers Builds watches a repository and builds what it finds.
+ * A strict repository has no app in it — `.vc/app` is generated and
+ * gitignored — and Cloudflare documents nothing about a build command that
+ * writes the source it then builds. The install step's ordering against a
+ * generated `package.json` is undocumented, which is not a thing to guess at
+ * in the path that puts a shop on the internet.
+ *
+ * So the generator runs in GitHub Actions, where it is ordinary, and pushes
+ * the result to its own branch. `main` stays the manifest and the data;
+ * `void-dist` is a plain Void app with a committed `package.json`, lockfile
+ * and `wrangler.jsonc` that anything can build from a cold checkout.
+ * Cloudflare is pointed at that branch and needs to know nothing about
+ * voidcommerce — which also means the deploy path is one a person can run by
+ * hand when CI is not the answer.
+ */
+export function renderDistWorkflow(manifest: Manifest): string {
+	const worker = manifest.shop.domain.split(".")[0];
+	return `name: Build the deployable app
+
+# Generated by \`vc init\` from voidcommerce.json.
+#
+# Every push to main regenerates the Void app from the manifest and force-pushes
+# it to \`${DIST_BRANCH}\`. Cloudflare's Workers Builds watches THAT branch and
+# deploys it, so a push here is a deploy — and no Cloudflare credential is
+# stored in GitHub.
+#
+# The Cloudflare side is configured once, in the dashboard, for the Worker
+# named \`${worker}\` (Settings → Builds). DEPLOY.md has the settings and the
+# one non-obvious part: the build's API token needs D1:Edit, which the token
+# Cloudflare generates for you does not have.
+on:
+  push:
+    branches: [main, master]
+  workflow_dispatch:
+
+# A later push wins: an older tree must never overwrite a newer one.
+concurrency:
+  group: ${DIST_BRANCH}-\${{ github.repository }}
+  cancel-in-progress: true
+
+# contents: write is what lets GITHUB_TOKEN force-push the branch. Nothing else.
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: oven-sh/setup-bun@v2
+
+      - run: bun install --frozen-lockfile
+
+      # Regenerates the app from voidcommerce.json, runs void's own prepare and
+      # migration generation, then resolves the symlinks into a tree that stands
+      # on its own.
+      - run: bunx vc dist
+
+      # A migration generated here and not committed would be applied under a
+      # new name on the next run, against tables that already exist. The
+      # migrations belong to the repository, so this fails rather than
+      # inventing one.
+      - name: Refuse to ship a migration that is not committed
+        run: |
+          set -euo pipefail
+          if [ -n "$(git status --porcelain migrations/)" ]; then
+            echo "::error::vc generate wrote a migration that is not committed."
+            git status --porcelain migrations/
+            echo "Run 'vc generate' locally, review it, and commit it."
+            exit 1
+          fi
+
+      - name: Publish to ${DIST_BRANCH}
+        env:
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          cd ${DIST_DIR}
+          # A fresh single-commit history each run: the branch is build output,
+          # so it is replaced rather than accumulating commits.
+          git init -q -b ${DIST_BRANCH}
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git commit -q -m "\${{ github.sha }} — ${manifest.shop.domain}"
+          git push -f "https://x-access-token:\${GITHUB_TOKEN}@github.com/\${{ github.repository }}.git" ${DIST_BRANCH}
+`;
+}
+
+/** What a person still has to do once, and why each thing cannot be done for them. */
+export function renderDeployReadme(manifest: Manifest, zone: string, hosts: string[]): string {
+	const worker = manifest.shop.domain.split(".")[0];
+	return `# Going live
+
+\`${manifest.shop.domain}\` on Cloudflare Workers. Generated by \`vc init\`;
+regenerate with \`vc generate\`.
+
+## The loop, once it is set up
+
+Push to \`main\`. GitHub Actions regenerates the app from \`voidcommerce.json\`
+and force-pushes it to \`${DIST_BRANCH}\`; Cloudflare's Workers Builds builds that
+branch and deploys it. Nothing else runs.
+
+Your secrets survive every deploy — \`wrangler deploy\` never deletes a secret.
+Plaintext \`vars\` are replaced from \`.env.production\` on each deploy, which is
+why no credential is allowed in that file.
+
+## Once, before the first push
+
+Each of these either creates something in your Cloudflare account or holds a
+credential, so none of them can live in a repository.
+
+### 1. The zone
+
+\`${zone}\` must be on Cloudflare. A Worker custom domain is a record Cloudflare
+creates in its own zone, so a domain hosted anywhere else cannot have one. The
+worker answers on ${hosts.map((h) => `\`${h}\``).join(" and ")}.
+
+### 2. The database, the queue, and the account id
+
+\`\`\`sh
+vc deploy --cloudflare --provision
+\`\`\`
+
+Idempotent: it creates nothing that already exists. It pins your account id,
+creates the D1 database and the queue, and records both in \`wrangler.jsonc\`
+and \`voidcommerce.json\` so every later generate carries the real ids.
+**Commit that change.**
+
+### 3. The secrets
+
+\`\`\`sh
+vc preflight --cloudflare
+\`\`\`
+
+lists every required key, says what breaks without it, and prints the
+\`wrangler secret put\` line. On a Worker that has never been deployed, setting
+the first secret is what creates it.
+
+### 4. An API token the build can use
+
+This is the one non-obvious step. Cloudflare generates an API token for
+Workers Builds automatically, and **that token has no D1 permission** — its
+scopes are Workers Scripts, KV, R2, Workers Routes and account/user reads. The
+deploy command below applies database migrations, so it needs more.
+
+Create a token at **My Profile → API Tokens** with:
+
+| scope | permission |
+|---|---|
+| Account | Workers Scripts: Edit |
+| Account | D1: Edit |
+| Account | Workers KV Storage: Edit, Workers R2 Storage: Edit |
+| Account | Queues: Edit |
+| Account | Account Settings: Read |
+| Zone | Workers Routes: Edit (${zone}) |
+| User | User Details: Read, Memberships: Read |
+
+Then select it in the build settings below. Use the same token for every
+deploy of this Worker; permissions are whatever that token has.
+
+### 5. Connect the repository
+
+In the Cloudflare dashboard, on the Worker named \`${worker}\`, under
+**Settings → Builds → Connect**. The Worker's name must equal the \`name\` in
+the \`wrangler.jsonc\` at the root directory, or the build fails.
+
+| setting | value |
+|---|---|
+| branch | \`${DIST_BRANCH}\` |
+| root directory | \`/\` |
+| build command | \`bun install && bunx void prepare && bunx vp build\` |
+| deploy command | \`bunx wrangler d1 migrations apply DB --remote && bunx wrangler deploy -c dist/ssr/wrangler.json\` |
+| API token | the one from step 4 |
+
+The migration command names the **binding** (\`DB\`), not the database, so it
+still points at the right database if the name ever differs.
+
+Cloudflare's build image has Bun; pin its version with a \`BUN_VERSION\` build
+variable if you ever need to. The free plan allows 3,000 build minutes a month
+and one build at a time.
+
+### 6. The catalogue
+
+\`vc import\` pushes \`data/\` into the running shop. It is an upsert, so it is
+safe on every deploy and costs one pass when nothing changed.
+
+## Without Cloudflare's build
+
+The same thing by hand, from a checkout of either branch:
+
+\`\`\`sh
+vc deploy --cloudflare
+\`\`\`
+
+which preflights, builds, strips the baked development values out of the
+worker's vars, applies the remote migrations, and deploys exactly what it
+verified.
+`;
+}

package/src/generate/env.ts

@@ -0,0 +1,164 @@
+import { type EnvKey } from "../catalog";
+import { type Manifest, envKeysOf, has, hasFrontend, isApex, zone } from "../manifest";
+
+/**
+ * `env.ts`, `.env.example` and `.env.production` — from the manifest.
+ *
+ * Every key is REQUIRED, with no default. A default is compiled into the
+ * worker's vars and shadows the real secret; Void's own deploy gate calls a
+ * required key absent from the vars "the only state a remote secret can
+ * discharge". Locally, `unset` is the one documented value that reads as
+ * absent, and preflight refuses it.
+ */
+
+/** Keys every shop has, whatever else was chosen. */
+const BASE: EnvKey[] = [
+	{
+		key: "SHOP_DOMAIN",
+		breaks: "everything derived from it is wrong at once — no public origin, the storefront rejected as untrusted, no DNS records",
+		plaintext: true,
+	},
+	{
+		key: "COMMERCE_CRON_SECRET",
+		breaks: "the scheduler cannot authenticate, so every background job stops",
+		where: "openssl rand -base64 32",
+	},
+	{
+		key: "COMMERCE_WEBHOOK_SECRET",
+		breaks: "payment webhooks cannot be verified, so no order ever becomes paid",
+		where: "the payment provider's dashboard",
+	},
+	{
+		key: "SHIPPING_DOMESTIC_MINOR",
+		breaks: "delivery is quoted at nothing, and every order loses the carrier cost",
+		plaintext: true,
+		dev: "4900",
+		where: "your carrier agreement, in minor units ex VAT",
+	},
+	{
+		key: "SHIPPING_FREE_FROM_MINOR",
+		breaks: "the free-delivery threshold is undefined",
+		plaintext: true,
+		dev: "100000",
+	},
+];
+
+export function allEnvKeys(manifest: Manifest): EnvKey[] {
+	const keys = [...BASE, ...envKeysOf(manifest)];
+	// Only a shop that is not its zone's apex needs to name the zone: records
+	// go there, and the worker's custom domain needs that zone on Cloudflare.
+	if (!isApex(manifest)) {
+		keys.splice(1, 0, {
+			key: "SHOP_ZONE",
+			breaks: "DNS records are written to the wrong zone, or to none",
+			plaintext: true,
+		});
+	}
+	// Only a layout with a storefront has somewhere to point the records.
+	if (hasFrontend(manifest.layout) && manifest.shop.pagesHost) {
+		keys.splice(1, 0, {
+			key: "GITHUB_PAGES_HOST",
+			breaks: "the www record has nothing to point at",
+			plaintext: true,
+		});
+	}
+	return keys;
+}
+
+const NUMERIC = new Set(["SHIPPING_DOMESTIC_MINOR", "SHIPPING_FREE_FROM_MINOR"]);
+
+export function renderEnvTs(manifest: Manifest): string {
+	const keys = allEnvKeys(manifest);
+	const lines = keys.map((key) => {
+		const helper = NUMERIC.has(key.key) ? "number()" : "string()";
+		const doc = [`	/** ${key.breaks}${key.where ? ` — from: ${key.where}` : ""} */`];
+		return `${doc.join("\n")}\n	${key.key}: ${helper},`;
+	});
+	return `import { defineEnv, number, string } from "void/env";
+
+/**
+ * Every env key the app reads. All of them are REQUIRED.
+ *
+ * Generated by \`vc init\` from voidcommerce.json — edit the manifest and
+ * regenerate rather than editing this by hand.
+ *
+ * Nothing is optional: an integration this shop supports is one the
+ * deployment sets up. No key has a default, because a default is compiled
+ * into the worker's vars and shadows the real secret. Locally, the literal
+ * value \`unset\` is the one documented way to say "I do not have this yet",
+ * and \`vc preflight\` refuses it.
+ */
+export default defineEnv({
+${lines.join("\n")}
+});
+`;
+}
+
+export function renderEnvExample(manifest: Manifest): string {
+	const keys = allEnvKeys(manifest);
+	return [
+		"# Every key is required. Copy to .env for local development.",
+		"# `unset` is the one value that reads as absent — for a credential you do not have yet.",
+		"",
+		...keys.map((key) => `${key.key}=${key.dev ?? (key.plaintext ? "" : "unset")}`),
+		"",
+	].join("\n");
+}
+
+export function renderEnvLocal(manifest: Manifest): string {
+	const keys = allEnvKeys(manifest);
+	const local: Record<string, string> = {
+		SHOP_DOMAIN: `${manifest.shop.domain.split(".")[0]}.test`,
+		GITHUB_PAGES_HOST: manifest.shop.pagesHost ?? "",
+		SHOP_ZONE: zone(manifest),
+		COMMERCE_CRON_SECRET: "dev-cron-secret-not-for-production",
+		COMMERCE_WEBHOOK_SECRET: "whsec_dev_secret",
+		SYSTEM_API_KEY: "dev-system-key-0123456789abcdefghijklmnopqrstuvwxyz",
+		EMAIL_FROM: `"${manifest.shop.name} <noreply@${manifest.shop.domain}>"`,
+	};
+	return [
+		"# Local development. Gitignored; .env.example documents every key.",
+		"",
+		...keys.map((key) => `${key.key}=${local[key.key] ?? key.dev ?? "unset"}`),
+		// One file for both halves in a strict repo, where the storefront and
+		// the worker share a root. The worker takes 5173 because it is started
+		// first; the storefront lands on the next free port and calls back here.
+		...(hasFrontend(manifest.layout)
+			? ["", "# The storefront, reaching the worker. Start the worker first.", "VITE_API_ORIGIN=http://localhost:5173"]
+			: []),
+		"",
+	].join("\n");
+}
+
+export function renderEnvProduction(manifest: Manifest): string {
+	const keys = allEnvKeys(manifest).filter((key) => key.plaintext);
+	const values: Record<string, string> = {
+		SHOP_DOMAIN: manifest.shop.domain,
+		GITHUB_PAGES_HOST: manifest.shop.pagesHost ?? "",
+		SHOP_ZONE: zone(manifest),
+		EMAIL_FROM: `"${manifest.shop.name} <noreply@${manifest.shop.domain}>"`,
+		ADYEN_ENVIRONMENT: "live",
+		BC_ENVIRONMENT: "production",
+	};
+	return [
+		"# Production values that are NOT secrets.",
+		"#",
+		"# On `void deploy --backend cloudflare` every .env* file is baked into the",
+		"# worker's vars as PLAINTEXT, so this holds only values safe to commit. Every",
+		"# credential is `wrangler secret put <NAME>` instead.",
+		"",
+		...keys.map((key) => `${key.key}=${values[key.key] ?? key.dev ?? ""}`),
+		"",
+	].join("\n");
+}
+
+/** So the generator can say what it decided. */
+export function envSummary(manifest: Manifest): { secrets: string[]; plaintext: string[] } {
+	const keys = allEnvKeys(manifest);
+	return {
+		secrets: keys.filter((key) => !key.plaintext).map((key) => key.key),
+		plaintext: keys.filter((key) => key.plaintext).map((key) => key.key),
+	};
+}
+
+export { has };

package/src/generate/frontend.ts

@@ -0,0 +1,275 @@
+import type { Manifest } from "../manifest";
+
+/**
+ * The storefront: a static Void site that talks to the worker over HTTP.
+ *
+ * Two layouts have one, and the only difference is where it sits.
+ *
+ *   monorepo   `frontend/`, its own workspace beside `api/`
+ *   strict     the REPOSITORY ROOT, sharing the one package.json
+ *
+ * Strict's placement is the interesting one. What a person edits in a strict
+ * repository is the storefront, so the storefront is what the repository
+ * looks like: its Vite config, its pages, its package.json. The backend is
+ * generated underneath it at `.vc/app` and is nobody's to edit. So the repo
+ * is, in technicality, a frontend app that builds a backend app — and in
+ * practice a monorepo without the ceremony of being one.
+ *
+ * Void prerenders it (`output: "static"`), and a workflow publishes the built
+ * tree to a branch that GitHub Pages — or Cloudflare Pages — serves as-is.
+ */
+
+/** Where the frontend's build output lands, relative to its own directory. */
+export const FRONTEND_OUT = "dist/client";
+export const FRONTEND_BRANCH = "frontend-static";
+
+export function renderFrontendApiTs(manifest: Manifest): string {
+	return `/// <reference types="vite/client" />
+import { createAuthClient } from "better-auth/react";
+import { commerceClient } from "@saastemly/better-commerce/client";
+
+/**
+ * The one client the storefront talks through.
+ *
+ * The API is another origin — api.${manifest.shop.domain} — so its address is
+ * baked at build time: .env.production for the build, .env locally. There is
+ * no fallback. A storefront that silently points nowhere is worse than one
+ * that refuses to build.
+ */
+const origin = import.meta.env.VITE_API_ORIGIN as string | undefined;
+if (!origin) throw new Error("VITE_API_ORIGIN is not set — .env locally, .env.production for the build.");
+
+export const API_ORIGIN: string = origin;
+export const api = createAuthClient({ baseURL: API_ORIGIN, plugins: [commerceClient()] });
+`;
+}
+
+export function renderFrontendEnvProduction(manifest: Manifest): string {
+	return `# Baked into the storefront build. Generated by \`vc init\` from voidcommerce.json.
+VITE_API_ORIGIN=https://api.${manifest.shop.domain}
+`;
+}
+
+/** The Vite config for a static Void site. Deliberately small: this is yours. */
+export function renderFrontendViteConfig(): string {
+	return `import { defineConfig } from "vite";
+import { voidPlugin } from "void";
+import { voidReact } from "@void/react/plugin";
+
+/** The storefront. The API is a different origin, so nothing is proxied here. */
+export default defineConfig({
+  plugins: [voidPlugin(), voidReact()],
+});
+`;
+}
+
+/**
+ * `target: node` because Void 0.10.13's Cloudflare prerender calls miniflare
+ * with the single-worker shorthand that the miniflare its own dependencies
+ * pin rejects. The node target prerenders directly, and needs
+ * `@hono/node-server`. It also disables Cloudflare bindings, which a static
+ * export could not use anyway.
+ */
+export function renderFrontendVoidJson(): string {
+	return `{
+  "$schema": "./node_modules/void/schema.json",
+  "target": "node",
+  "output": "static"
+}
+`;
+}
+
+export function renderFrontendTsconfig(): string {
+	return `{
+  "extends": "./.void/tsconfig.json",
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["vite/client"],
+    "jsx": "react-jsx",
+    "paths": { "@/*": ["./*"] }
+  },
+  "include": ["pages", "lib", "src"]
+}
+`;
+}
+
+/** A storefront that actually shows the catalogue, so the first build proves the wiring. */
+export function renderStorefrontPage(manifest: Manifest): string {
+	const { name, currency } = manifest.shop;
+	return `import { useEffect, useState } from "react";
+import { api } from "@/lib/api";
+
+/**
+ * The shop front.
+ *
+ * Yours to replace — this is a starting point, not a framework. What it is
+ * here to prove is the wiring: the catalogue comes from the worker over HTTP,
+ * with no server code on this side, which is what makes the whole storefront
+ * a static export.
+ *
+ * Prices arrive in MINOR units (øre, cents) because that is the only way to
+ * add money without losing it to floating point.
+ */
+interface Product {
+	id: string;
+	title: string;
+	handle?: string;
+	description?: string;
+	priceMinor?: number;
+	currency?: string;
+}
+
+const money = (minor: number, currency: string) =>
+	new Intl.NumberFormat(undefined, { style: "currency", currency: currency.toUpperCase() }).format(minor / 100);
+
+export default function StorefrontPage() {
+	const [products, setProducts] = useState<Product[] | null>(null);
+	const [error, setError] = useState<string | null>(null);
+
+	useEffect(() => {
+		// The catalogue is public: no session, no key. A visitor sees it.
+		api.$fetch("/commerce/products", { method: "GET" })
+			.then((result) => {
+				const data = (result as { data?: { products?: Product[] } }).data;
+				setProducts(data?.products ?? []);
+			})
+			.catch((cause: unknown) => setError(cause instanceof Error ? cause.message : String(cause)));
+	}, []);
+
+	return (
+		<main style={{ maxWidth: "60rem", margin: "0 auto", padding: "2rem 1rem", fontFamily: "system-ui, sans-serif" }}>
+			<h1>${name}</h1>
+			{error && <p role="alert">The catalogue could not be loaded: {error}</p>}
+			{!products && !error && <p>Loading the catalogue…</p>}
+			{products?.length === 0 && <p>No products yet. Run <code>vc import</code> to push <code>data/</code> into the shop.</p>}
+			<ul style={{ display: "grid", gridTemplateColumns: "repeat(auto-fill, minmax(14rem, 1fr))", gap: "1.5rem", listStyle: "none", padding: 0 }}>
+				{products?.map((product) => (
+					<li key={product.id}>
+						<h2 style={{ fontSize: "1rem", margin: "0 0 .25rem" }}>{product.title}</h2>
+						{product.description && <p style={{ margin: "0 0 .5rem", opacity: 0.8 }}>{product.description}</p>}
+						{typeof product.priceMinor === "number" && <p style={{ margin: 0 }}>{money(product.priceMinor, product.currency ?? "${currency}")}</p>}
+					</li>
+				))}
+			</ul>
+		</main>
+	);
+}
+`;
+}
+
+/**
+ * Publishes the storefront to a branch on every push.
+ *
+ * The branch holds build output only, so it is force-pushed as a single
+ * orphan commit rather than accumulating history. GitHub Pages serves it from
+ * `/`, and the CNAME file in it sets the domain — so a green run is a live
+ * deploy with no Pages environment to configure. Cloudflare Pages can be
+ * pointed at the same branch instead.
+ */
+export function renderFrontendWorkflow(manifest: Manifest, dir: string): string {
+	const at = dir ? `\n        working-directory: ${dir}` : "";
+	const out = dir ? `${dir}/${FRONTEND_OUT}` : FRONTEND_OUT;
+	const paths = dir
+		? `      - "${dir}/**"\n      - "package.json"\n      - "bun.lock"`
+		: `      - "pages/**"\n      - "lib/**"\n      - "src/**"\n      - "public/**"\n      - "vite.config.ts"\n      - "void.json"\n      - "package.json"\n      - "bun.lock"`;
+	return `name: Publish the storefront
+
+# Generated by \`vc init\` from voidcommerce.json.
+#
+# Builds the storefront and force-pushes the prerendered tree to
+# \`${FRONTEND_BRANCH}\`. Point GitHub Pages (or Cloudflare Pages) at that branch
+# and a push here is a live storefront. The worker deploys separately, from
+# \`void-dist\`.
+on:
+  push:
+    branches: [main, master]
+    paths:
+${paths}
+      - ".github/workflows/frontend-static.yml"
+  workflow_dispatch:
+
+# A later push wins: an older build must never overwrite a newer one.
+concurrency:
+  group: ${FRONTEND_BRANCH}-\${{ github.repository }}
+  cancel-in-progress: true
+
+# contents: write is what lets GITHUB_TOKEN force-push the branch.
+permissions:
+  contents: write
+
+env:
+  # Served from the root at the custom domain. Set a BASE_PATH repository
+  # variable to "/<repo>/" only while the site is still at <owner>.github.io/<repo>/.
+  BASE_PATH: \${{ vars.BASE_PATH || '/' }}
+  # The publish step force-pushes, which would otherwise wipe the CNAME file
+  # GitHub keeps in the branch.
+  CNAME: ${manifest.shop.domain}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: oven-sh/setup-bun@v2
+
+      - run: bun install --frozen-lockfile
+
+      # Generates .void/* codegen without booting Vite.
+      - run: bunx void prepare${at}
+
+      # void.json sets output: "static", so this prerenders every page to HTML
+      # under ${FRONTEND_OUT} alongside the client bundle.
+      - run: bunx vp build${at}
+
+      - name: Rewrite absolute URLs onto the Pages base path${at}
+        run: |
+          set -euo pipefail
+          BASE="\${BASE_PATH%/}/"
+          if [ "$BASE" = "/" ]; then
+            echo "BASE_PATH is /, nothing to rewrite."
+            exit 0
+          fi
+          # Void emits root-absolute URLs (/assets/..., /_void/...) and has no
+          # Vite \`base\` support, so they are rewritten here for the subpath a
+          # project site is served from.
+          find ${FRONTEND_OUT} -type f \\( -name '*.html' -o -name '*.js' -o -name '*.css' \\) -print0 \\
+            | xargs -0 -r sed -i \\
+                -e "s|\\"/assets/|\\"\${BASE}assets/|g" \\
+                -e "s|'/assets/|'\${BASE}assets/|g" \\
+                -e "s|\\"/_void/|\\"\${BASE}_void/|g" \\
+                -e "s|'/_void/|'\${BASE}_void/|g"
+          echo "Rewrote absolute URLs onto \${BASE}"
+
+      - name: Prepare the published tree${at}
+        run: |
+          set -euo pipefail
+          # Without .nojekyll, Pages runs Jekyll and drops _void/ (and every
+          # other underscore-prefixed path) from the served site.
+          touch ${FRONTEND_OUT}/.nojekyll
+          # Unknown paths fall back to the prerendered entry page so the client
+          # router can take over instead of showing GitHub's 404.
+          [ -f ${FRONTEND_OUT}/index.html ] && cp ${FRONTEND_OUT}/index.html ${FRONTEND_OUT}/404.html
+          echo "\${CNAME}" > ${FRONTEND_OUT}/CNAME
+          ls -la ${FRONTEND_OUT}
+
+      - name: Publish to ${FRONTEND_BRANCH}
+        env:
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          cd ${out}
+          # A fresh single-commit history each run: the branch is build output.
+          git init -q -b ${FRONTEND_BRANCH}
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git commit -q -m "Storefront \${GITHUB_SHA}"
+          git push -f "https://x-access-token:\${GITHUB_TOKEN}@github.com/\${{ github.repository }}.git" ${FRONTEND_BRANCH}
+`;
+}