@saastemly/voidcommerce 0.3.0 → 0.5.0

package/src/generate/ci.ts

@@ -1,57 +1,75 @@
 import { DIST_BRANCH, DIST_DIR } from "../dist";
 import type { Manifest } from "../manifest";
+import { PRIVATE_KEY_VAR, SECRETS_FILE } from "../deploy/secrets";
 
 /**
- * The workflow that turns a push into a deploy.
+ * The workflow that turns a push into a live shop.
  *
- * ── Why a branch and not a build ─────────────────────────────────────────
+ * ── Why GitHub Actions deploys, and not Cloudflare's own 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.
+ * Cloudflare's Workers Builds can watch a repository, and for a while that
+ * was the plan. Three things make it the wrong end to drive from.
  *
- * 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.
+ * The build secret. `.env.secrets` is ciphertext, so something must hold
+ * the key that opens it. Workers Builds takes build variables ONLY from the
+ * dashboard — there is no repository file for them — so the one credential
+ * that makes push-to-deploy work would have to be pasted into a web page.
+ *
+ * The token. The API token Cloudflare generates for its own builds has no
+ * D1 and no Queues permission, so it cannot create this shop's database.
+ * Replacing it is another dashboard visit.
+ *
+ * The bootstrap. Connecting the repository is itself a dashboard step, on a
+ * Worker that has to exist first.
+ *
+ * GitHub already has what is needed. A person who can push is logged into
+ * `gh`, and `gh` can write repository secrets from the terminal — so
+ * `vc link` puts the key and the token there in one command, and this
+ * workflow spends them. Nothing is typed into a web page except the token
+ * itself, once, because Cloudflare will not issue one any other way.
+ *
+ * ── The `void-dist` branch is still built ────────────────────────────────
+ *
+ * It is no longer the deploy path, but it stays: a plain Void app with a
+ * committed lockfile and `wrangler.jsonc` that anything can build from a
+ * cold checkout. It is what makes the deploy reproducible by hand, and it
+ * is the escape hatch for anyone who does want Cloudflare's build after all.
+ *
+ * @see https://developers.cloudflare.com/workers/ci-cd/builds/configuration/#api-token
  */
 export function renderDistWorkflow(manifest: Manifest): string {
-	const worker = manifest.shop.domain.split(".")[0];
-	return `name: Build the deployable app
+	return `name: Deploy the shop
 
 # 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.
+# A push to main regenerates the Void app from the manifest, publishes it to
+# \`${DIST_BRANCH}\` as a standalone tree, and deploys it to Cloudflare.
+#
+# The credentials come from the repository, set once by \`vc link\`:
+#
+#   secrets.CLOUDFLARE_API_TOKEN        deploys, and creates D1 + the queue
+#   secrets.${PRIVATE_KEY_VAR}   opens ${SECRETS_FILE}
+#   vars.CLOUDFLARE_ACCOUNT_ID          which account (an id, not a credential)
 #
-# 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.
+# Nothing here needs a Cloudflare dashboard visit and nothing needs wrangler
+# on your machine. See DEPLOY.md.
 on:
   push:
     branches: [main, master]
   workflow_dispatch:
 
-# A later push wins: an older tree must never overwrite a newer one.
+# A later push wins: an older tree must never overwrite a newer one, and two
+# deploys must never race for the same worker.
 concurrency:
-  group: ${DIST_BRANCH}-\${{ github.repository }}
+  group: deploy-\${{ github.repository }}
   cancel-in-progress: true
 
-# contents: write is what lets GITHUB_TOKEN force-push the branch. Nothing else.
 permissions:
   contents: write
 
 jobs:
-  build:
+  # ── Regenerate, and publish the standalone tree ────────────────────────
+  dist:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
@@ -92,6 +110,50 @@ jobs:
           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}
+
+  # ── Deploy it ──────────────────────────────────────────────────────────
+  deploy:
+    needs: dist
+    runs-on: ubuntu-latest
+    environment:
+      name: production
+      url: https://${manifest.shop.domain}
+    env:
+      CLOUDFLARE_API_TOKEN: \${{ secrets.CLOUDFLARE_API_TOKEN }}
+      CLOUDFLARE_ACCOUNT_ID: \${{ vars.CLOUDFLARE_ACCOUNT_ID }}
+      ${PRIVATE_KEY_VAR}: \${{ secrets.${PRIVATE_KEY_VAR} }}
+    steps:
+      - uses: actions/checkout@v6
+      - uses: oven-sh/setup-bun@v2
+
+      # Checked before anything is built, so a repository that was never
+      # linked says so in five seconds rather than four minutes.
+      - name: Are the credentials here?
+        run: |
+          set -euo pipefail
+          missing=""
+          [ -n "\${CLOUDFLARE_API_TOKEN:-}" ] || missing="$missing CLOUDFLARE_API_TOKEN"
+          [ -n "\${${PRIVATE_KEY_VAR}:-}" ] || missing="$missing ${PRIVATE_KEY_VAR}"
+          if [ -n "$missing" ]; then
+            echo "::error::this repository has no$missing. Run 'vc link' once, from a checkout."
+            exit 1
+          fi
+
+      - run: bun install --frozen-lockfile
+
+      # One command: preflight, provision D1 and the queue if they are not
+      # there, build, strip the values Void bakes into the worker's plaintext
+      # vars, apply the committed migrations, and deploy with the decrypted
+      # secrets attached to the version. Provisioning is idempotent — it looks
+      # a resource up by name before creating it — so this is safe every run.
+      - name: vc deploy --cloudflare --provision
+        run: bunx vc deploy --cloudflare --provision
+
+      # An upsert, so it is safe on every deploy and costs one pass when
+      # nothing in data/ has changed. A failure here does not un-deploy a
+      # working shop, so it warns rather than failing the run.
+      - name: Push the catalogue
+        run: bunx vc import || echo "::warning::the catalogue did not import; the shop is up but its products may be stale"
 `;
 }
 
@@ -103,131 +165,116 @@ export function renderDeployReadme(manifest: Manifest, zone: string, hosts: stri
 \`${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
+## The loop
 
 \`\`\`sh
-vc deploy --cloudflare --provision
+git push
 \`\`\`
 
-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.**
+That is the deploy. GitHub Actions regenerates the app from
+\`voidcommerce.json\`, publishes a standalone copy to \`${DIST_BRANCH}\`, creates the
+database and queue if they are not there, applies the migrations, and deploys
+the worker with this repository's secrets attached.
 
-### 3. The secrets
+You do not need wrangler on your machine, and you do not need to be logged
+into it. You do not need to open the Cloudflare dashboard after the one step
+below.
 
-They live in the repository, encrypted:
+## Once, before the first push
 
 \`\`\`sh
-vc secrets --init                       # every required key, as \`unset\`
-# put the real values in, then
-bunx dotenvx encrypt -f .env.secrets    # ciphertext; commit this
+gh repo create --source=. --private --push   # if there is no repo yet
+vc link
 \`\`\`
 
-\`.env.secrets\` is committed and \`.env.keys\` is not. The deploy decrypts it and
-hands the values to \`wrangler deploy --secrets-file\`, which stores them as
-real Worker secrets — not as plaintext \`vars\`, which anyone with dashboard
-access can read.
-
-That turns one \`wrangler secret put\` per value into one build variable, set
-once in step 5. It also means the shop rebuilds from a checkout.
+\`vc link\` does three things and stores all of them on the GitHub repository:
 
-**Know the tradeoff.** Ciphertext in git is permanent: if the private key ever
-leaks, every secret in the history is readable, including ones you rotated.
-\`wrangler secret put\` does not have that property, and stays available for
-anything you would rather never commit. \`vc preflight\` counts a secret the
-repository declares as present, and refuses any value committed in the clear.
+| what | where | why |
+|---|---|---|
+| \`${PRIVATE_KEY_VAR}\` | repository **secret** | opens \`${SECRETS_FILE}\`. Generated by \`vc link\`, never written to disk |
+| \`CLOUDFLARE_API_TOKEN\` | repository **secret** | deploys, and creates D1 and the queue |
+| \`CLOUDFLARE_ACCOUNT_ID\` | repository **variable** | which account. An identifier, not a credential |
 
-### 4. An API token the build can use
+It will ask you to paste a Cloudflare API token. That is the only manual step
+in the whole setup, and it is worth saying exactly why it cannot be removed:
 
-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.
+> **GitHub cannot mint a Cloudflare credential.** There is no OIDC or workload
+> identity federation between them — the feature request has been open since
+> 2025 with no commitment, and Cloudflare's own CI guidance still says to store
+> a token in your CI provider's secrets. The Cloudflare GitHub App does not
+> help either: it grants *Cloudflare* access to your *repository*, not the
+> reverse. Something has to authorise creating a database in your account, and
+> only Cloudflare can issue that authorisation.
 
-Create a token at **My Profile → API Tokens** with:
+Create the token at **My Profile → API Tokens → Create Token → Custom token**:
 
-| 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 |
+| scope | permission | for |
+|---|---|---|
+| Account | Workers Scripts: Edit | deploying the worker |
+| Account | D1: Edit | creating the database, applying migrations |
+| Account | Queues: Edit | the order queue |
+| Account | Workers KV Storage: Edit | sessions and caches |
+| Account | Workers R2 Storage: Edit | product images |
+| Account | Account Settings: Read | confirming which account |
+| Zone | Workers Routes: Edit (${zone}) | answering on your domain |
+| User | User Details: Read, Memberships: Read | wrangler asks at startup |
 
-Then select it in the build settings below. Use the same token for every
-deploy of this Worker; permissions are whatever that token has.
+The token Cloudflare generates for its own Workers Builds will **not** do: it
+has no D1 and no Queues permission, so it cannot create this shop's database.
 
-### 5. Connect the repository
+### The zone
 
-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.
+\`${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 ")}.
 
-| setting | value |
-|---|---|
-| branch | \`${DIST_BRANCH}\` |
-| root directory | \`/\` |
-| build command | \`bun install && bunx void prepare && bunx vp build\` |
-| deploy command | see below |
-| build variable | \`DOTENV_PRIVATE_KEY_SECRETS\`, marked as a secret — the one value that is not in the repository |
-| API token | the one from step 4 |
+## Secrets
 
-The deploy command, on one line:
+They live in the repository, encrypted, in \`${SECRETS_FILE}\`:
 
 \`\`\`sh
-bunx dotenvx decrypt -f .env.secrets --stdout > .vc-secrets.env && bunx wrangler d1 migrations apply DB --remote && bunx wrangler deploy -c dist/ssr/wrangler.json --secrets-file .vc-secrets.env
+vc secrets set STRIPE_SECRET_KEY     # prompts; never touches your shell history
+vc secrets                           # what is set, what is missing
 \`\`\`
 
-Plain \`sh\`, so it does not rely on process substitution. The decrypted file
-exists only inside the build sandbox, and \`--secrets-file\` applies additively:
-a secret it does not name is left alone rather than deleted.
+**This needs no credential.** dotenvx is asymmetric: encryption uses the public
+key committed at the top of the file, so anyone with a clone can set or rotate
+a secret. Nobody with a clone can read one. Only the deploy decrypts, with the
+private key that lives in GitHub Actions.
 
-The migration command names the **binding** (\`DB\`), not the database, so it
-still points at the right database if the name ever differs.
+A pre-commit hook refuses a commit that would put a value in the clear, because
+that cannot be undone by a later commit — the value stays in the history.
 
-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.
+**Know the tradeoff.** Ciphertext in git is permanent: if the private key ever
+leaks, every secret in the history is readable, including ones you rotated.
+\`wrangler secret put\` does not have that property, and stays available for
+anything you would rather never commit at all.
 
-### 6. The catalogue
+## 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.
+\`vc import\` pushes \`data/\` into the running shop, and the workflow runs it on
+every deploy. It is an upsert, so it costs one pass when nothing has changed.
 
-## Without Cloudflare's build
+## Doing it by hand
 
-The same thing by hand, from a checkout of either branch:
+The same thing, from a checkout, if CI is ever not the answer:
 
 \`\`\`sh
-vc deploy --cloudflare
+export CLOUDFLARE_API_TOKEN=…
+export ${PRIVATE_KEY_VAR}=…        # only if you kept a copy
+vc deploy --cloudflare --provision
 \`\`\`
 
-which preflights, builds, strips the baked development values out of the
-worker's vars, applies the remote migrations, and deploys exactly what it
-verified.
+which preflights, provisions, builds, strips the baked development values out
+of the worker's vars, applies the remote migrations, and deploys exactly what
+it verified.
+
+## If you would rather use Cloudflare's own build
+
+Point Workers Builds at the \`${DIST_BRANCH}\` branch — it is a plain Void app with
+a committed lockfile. The Worker must be named \`${worker}\`, matching the \`name\`
+in its \`wrangler.jsonc\`. You will need to set \`${PRIVATE_KEY_VAR}\` as a
+build secret in the dashboard, and replace the auto-generated API token with
+one that has D1 and Queues. That is the path \`vc link\` exists to avoid.
 `;
 }

package/src/generate/index.ts

@@ -1,4 +1,4 @@
-import { cp, mkdir, readFile, readdir, symlink, writeFile } from "node:fs/promises";
+import { cp, mkdir, readFile, readdir, rm, symlink, writeFile } from "node:fs/promises";
 import { existsSync, lstatSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { CHOICES } from "../catalog";
@@ -75,6 +75,8 @@ import { renderDomainTs, renderErpTs, renderMintTs, renderNotificationsTs, rende
 export interface GenerateResult {
 	written: string[];
 	kept: string[];
+	/** Generated files that no longer belong, and were deleted. */
+	retired: string[];
 	packages: string[];
 }
 
@@ -98,6 +100,20 @@ async function put(root: string, file: string, content: string, result: Generate
 	result.written.push(file);
 }
 
+/**
+ * Delete a file this generator used to write and no longer should.
+ *
+ * Renaming a generated file leaves the old one behind, and a stale GitHub
+ * workflow is not inert — it still runs on every push. So a rename has to
+ * be a write AND a delete, and the delete has to be reported.
+ */
+async function retire(root: string, file: string, result: GenerateResult) {
+	const path = join(root, file);
+	if (!(await exists(path))) return;
+	await rm(path, { force: true });
+	result.retired.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);
@@ -125,7 +141,7 @@ async function link(root: string, file: string, target: string, result: Generate
 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) };
+	const result: GenerateResult = { written: [], kept: [], retired: [], packages: packagesOf(manifest) };
 
 	await writeManifest(root, manifest);
 	result.written.push(MANIFEST_FILE);
@@ -320,6 +336,10 @@ async function generateStrictRoot(root: string, manifest: Manifest, result: Gene
 			scripts["deploy"] ??= "vc deploy";
 			scripts["import:catalog"] ??= "vc import";
 			scripts["maildev"] ??= "maildev --smtp 1025 --web 1080";
+			scripts["secrets"] ??= "vc secrets";
+			// husky installs the hook on `bun install`, so a fresh clone is
+			// guarded without anybody remembering to run anything.
+			scripts["prepare"] ??= "husky";
 			pkg["scripts"] = scripts;
 		},
 		result,
@@ -336,7 +356,27 @@ async function generateStrictRoot(root: string, manifest: Manifest, result: Gene
 		"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");
+	/**
+	 * The hook lives in `.husky/`, which is COMMITTED, so the guard travels
+	 * with the repository instead of being something each clone remembers to
+	 * install. A secret committed in the clear cannot be un-committed.
+	 */
+	await put(
+		root,
+		".husky/pre-commit",
+		`#!/usr/bin/env sh
+# Generated by \`vc init\`. Refuses a commit that would put a secret in the
+# clear in .env.secrets — which cannot be undone by a later commit,
+# because the value stays in the history.
+bunx vc guard
+`,
+		result,
+		"regenerate",
+	);
+	await put(root, ".github/workflows/deploy.yml", renderDistWorkflow(manifest), result, "regenerate");
+	// Renamed when GitHub Actions took over the deploy from Cloudflare's own
+	// build. Two workflows on the same push would deploy the shop twice.
+	await retire(root, ".github/workflows/void-dist.yml", result);
 	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");

package/src/generate/strict.ts

@@ -66,6 +66,8 @@ export function strictDependencies(manifest: Manifest): {
 		// The repository's secrets are encrypted with this; a build needs it to
 		// hand them to wrangler.
 		"@dotenvx/dotenvx",
+		// Installs the committed pre-commit hook on every fresh clone.
+		"husky",
 		"@rolldown/plugin-babel",
 		"@tailwindcss/vite",
 		"@types/node",

package/src/init.ts

@@ -141,6 +141,7 @@ export async function init(args: string[]): Promise<number> {
 		[
 			...result.written.map((file) => `${color.green("+")} ${file}`),
 			...result.kept.map((file) => `${color.dim("=")} ${file} ${color.dim("(kept — yours)")}`),
+			...result.retired.map((file) => `${color.red("-")} ${file} ${color.dim("(retired — no longer generated)")}`),
 		].join("\n"),
 		"Files",
 	);

package/src/regenerate.ts

@@ -30,6 +30,7 @@ export async function generateCommand(): Promise<number> {
 		[
 			...result.written.map((file) => `${color.green("+")} ${file}`),
 			...result.kept.map((file) => `${color.dim("=")} ${file} ${color.dim("(kept)")}`),
+			...result.retired.map((file) => `${color.red("-")} ${file} ${color.dim("(retired — no longer generated)")}`),
 		].join("\n"),
 	);
 	return project.manifest.layout === "strict" ? finishStrict(project.root) : 0;