@saastemly/voidcommerce 0.4.0 → 0.6.0

package/dist/{index-pz6m2hkm.js → index-xx5p4b8d.js}

@@ -21,11 +21,12 @@ var LAYOUTS = [
   {
     id: "strict",
     label: "Strict (experimental)",
-    hint: "the root IS the storefront, sharing one package.json; the worker is generated under .vc/app from the manifest and never hand-edited"
+    hint: "the root IS the storefront, sharing one package.json; the worker is generated under .vc/app and serves the storefront from its own assets — one origin, one deploy"
   }
 ];
 var isSingleApp = (layout) => layout === "app";
 var hasFrontend = (layout) => layout !== "app";
+var oneOrigin = (layout) => layout !== "monorepo";
 var TWO_LABEL_SUFFIXES = new Set(["co", "com", "net", "org", "ac", "gov", "edu", "or", "ne", "in"]);
 function zoneOf(domain) {
   const labels = domain.trim().toLowerCase().replace(/\.$/, "").split(".");
@@ -42,7 +43,7 @@ function isApex(manifest) {
 }
 function workerHosts(manifest) {
   const { domain } = manifest.shop;
-  if (!isSingleApp(manifest.layout))
+  if (!oneOrigin(manifest.layout))
     return [`api.${domain}`];
   return isApex(manifest) ? [domain, `www.${domain}`] : [domain];
 }
@@ -163,10 +164,10 @@ function validate(manifest) {
   if (dns.includes("simply")) {
     problems.push(`DNS at Simply.com cannot host ${workerHosts(manifest)[0]} — a Worker custom domain is created by Cloudflare, in a zone on Cloudflare`);
   }
-  if (hasFrontend(manifest.layout) && manifest.shop.pagesHost && !/^[a-z0-9-]+\.github\.io$/i.test(manifest.shop.pagesHost)) {
+  if (!oneOrigin(manifest.layout) && manifest.shop.pagesHost && !/^[a-z0-9-]+\.github\.io$/i.test(manifest.shop.pagesHost)) {
     problems.push(`Pages host "${manifest.shop.pagesHost}" should be <owner>.github.io`);
   }
   return problems;
 }
 
-export { MANIFEST_FILE, LAYOUTS, isSingleApp, hasFrontend, zoneOf, zone, isApex, workerHosts, withRequired, has, chosenIn, envKeysOf, OWN_PACKAGES, specifier, packagesOf, readManifest, writeManifest, validate };
+export { MANIFEST_FILE, LAYOUTS, isSingleApp, hasFrontend, oneOrigin, zoneOf, zone, isApex, workerHosts, withRequired, has, chosenIn, envKeysOf, OWN_PACKAGES, specifier, packagesOf, readManifest, writeManifest, validate };

package/dist/index.js

@@ -9,10 +9,8 @@ import {
   MIGRATIONS_README,
   STRICT_APP,
   VOID_VERSION,
-  allEnvKeys,
   deployCloudflare,
   distCommand,
-  envSummary,
   findProject,
   findWrangler,
   finishStrict,
@@ -34,10 +32,6 @@ import {
   renderDeployReadme,
   renderDistWorkflow,
   renderDomainTs,
-  renderEnvExample,
-  renderEnvLocal,
-  renderEnvProduction,
-  renderEnvTs,
   renderFrontendApiTs,
   renderFrontendEnvProduction,
   renderFrontendWorkflow,
@@ -57,7 +51,15 @@ import {
   routeProblem,
   strictDependencies,
   upsertJsonc
-} from "./index-yzezvy5h.js";
+} from "./index-f1wds190.js";
+import {
+  allEnvKeys,
+  envSummary,
+  renderEnvExample,
+  renderEnvLocal,
+  renderEnvProduction,
+  renderEnvTs
+} from "./index-2qt2yh3z.js";
 import {
   LAYOUTS,
   MANIFEST_FILE,
@@ -68,6 +70,7 @@ import {
   hasFrontend,
   isApex,
   isSingleApp,
+  oneOrigin,
   packagesOf,
   readManifest,
   specifier,
@@ -77,7 +80,7 @@ import {
   writeManifest,
   zone,
   zoneOf
-} from "./index-pz6m2hkm.js";
+} from "./index-xx5p4b8d.js";
 import {
   AUTH_PLUGINS,
   CARRIERS,
@@ -145,6 +148,7 @@ export {
   parseWhoAmI,
   parseJsonc,
   packagesOf,
+  oneOrigin,
   isSingleApp,
   isApex,
   importCommand,

package/dist/keys-qwvt324e.js

@@ -0,0 +1,19 @@
+import {
+  committedPublicKey,
+  generateKeypair,
+  keyState,
+  keysCommand,
+  provisionKey,
+  publicKeyFor
+} from "./index-2qt2yh3z.js";
+import"./index-xx5p4b8d.js";
+import"./index-844b3qn9.js";
+import"./index-0v6na3yp.js";
+export {
+  publicKeyFor,
+  provisionKey,
+  keysCommand,
+  keyState,
+  generateKeypair,
+  committedPublicKey
+};

package/dist/manifest.d.ts

@@ -24,9 +24,10 @@ export declare const MANIFEST_FILE = "voidcommerce.json";
  *   strict    EXPERIMENTAL. A monorepo turned inside out. The REPOSITORY
  *             ROOT is the storefront — its package.json, its pages, yours to
  *             edit — and the worker is generated underneath it at .vc/app
- *             from the manifest, gitignored, never hand-edited. Hosted the
- *             way a monorepo is: the worker on api.<domain>, the storefront
- *             on <domain>.
+ *             from the manifest, gitignored, never hand-edited. ONE worker
+ *             serves both at <domain>: the storefront's prerendered tree is
+ *             folded into the worker's assets at build time, so there is one
+ *             origin, one deploy, and one certificate Cloudflare issues.
  *
  * The first question, because it decides where `void init` runs and what
  * the domain means. It cannot change after init: moving files is not a
@@ -47,8 +48,26 @@ export declare const LAYOUTS: Array<{
  * storefront on the domain itself.
  */
 export declare const isSingleApp: (layout: Layout) => boolean;
-/** Does this layout carry a storefront of its own, and so a second origin to trust? */
+/** Does this layout carry a storefront of its own, in the repository? */
 export declare const hasFrontend: (layout: Layout) => boolean;
+/**
+ * Does ONE worker serve both the storefront and the API?
+ *
+ * `app` always did — it generates its storefront into the worker. `strict`
+ * now does too: the root's prerendered tree is merged into the worker's own
+ * assets directory at build time, so there is one origin, one hostname, one
+ * deploy, and one certificate that Cloudflare issues itself.
+ *
+ * That deletes the whole GitHub Pages half — the A/AAAA records, the CNAME
+ * file, the base-path rewriting — and with it a trap worth naming: GitHub
+ * treats any Cloudflare IP as ineligible for a certificate, so a proxied
+ * record silently stops issuance AND renewal about ninety days later, while
+ * GitHub's own health check still reports green.
+ *
+ * `monorepo` keeps the split, because there the frontend is a separate app
+ * that a person may well want hosted separately.
+ */
+export declare const oneOrigin: (layout: Layout) => boolean;
 /** The zone a hostname most likely belongs to: the registrable domain. */
 export declare function zoneOf(domain: string): string;
 /** The zone this shop's records go in. */
@@ -88,7 +107,10 @@ export interface Manifest {
          * default that is safe to assume.
          */
         taxRegistered?: boolean | undefined;
-        /** `saastemly.github.io` — the monorepo's frontend lives on GitHub Pages; the www record points here. */
+        /**
+         * `saastemly.github.io` — only a MONOREPO has a storefront on GitHub
+         * Pages. In `app` and `strict` the worker serves it, so this is unused.
+         */
         pagesHost?: string | undefined;
     };
     /** Chosen ids from each group, keyed by group id. */

package/dist/manifest.js

@@ -8,6 +8,7 @@ import {
   hasFrontend,
   isApex,
   isSingleApp,
+  oneOrigin,
   packagesOf,
   readManifest,
   specifier,
@@ -17,7 +18,7 @@ import {
   writeManifest,
   zone,
   zoneOf
-} from "./index-pz6m2hkm.js";
+} from "./index-xx5p4b8d.js";
 import"./index-844b3qn9.js";
 import"./index-0v6na3yp.js";
 export {
@@ -30,6 +31,7 @@ export {
   specifier,
   readManifest,
   packagesOf,
+  oneOrigin,
   isSingleApp,
   isApex,
   hasFrontend,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saastemly/voidcommerce",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Void, with a shop in it. `vc init` walks you through Better Auth, betterCommerce and every plugin; everything else passes through to `void`.",
   "type": "module",
   "license": "MIT",

package/src/cli.ts

@@ -1,4 +1,16 @@
-import { deployCommand, deployHelp, guardCommand, keysCliCommand, keysHelp, preflightCommand, preflightHelp, secretsCliCommand, secretsHelp } from "./deploy/index";
+import {
+	deployCommand,
+	deployHelp,
+	guardCommand,
+	keysCliCommand,
+	keysHelp,
+	linkCliCommand,
+	linkHelp,
+	preflightCommand,
+	preflightHelp,
+	secretsCliCommand,
+	secretsHelp,
+} from "./deploy/index";
 import { distCommand, distHelp } from "./dist";
 import { importCommand, importHelp } from "./import";
 import { fullHelp, initHelp, version } from "./help";
@@ -40,6 +52,7 @@ export const EXTENDED: Record<string, Extended> = {
 	preflight: { run: preflightCommand, help: preflightHelp },
 	secrets: { run: secretsCliCommand, help: secretsHelp },
 	keys: { run: keysCliCommand, help: keysHelp },
+	link: { run: linkCliCommand, help: linkHelp },
 	// Called by the generated pre-commit hook; exit code is the interface.
 	guard: { run: guardCommand, help: async () => guardCommand() },
 	dev: { run: appScript("dev"), help: appScriptHelp("dev") },

package/src/deploy/cloudflare.ts

@@ -1,8 +1,8 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import color from "picocolors";
 import { allEnvKeys } from "../generate/env";
-import { hasFrontend, workerHosts, writeManifest } from "../manifest";
+import { hasFrontend, isSingleApp, oneOrigin, workerHosts, writeManifest } from "../manifest";
 import type { Project } from "../project";
 import { parseJsonc, upsertJsonc } from "./jsonc";
 import { preflight, printPreflight } from "./preflight";
@@ -130,10 +130,46 @@ export async function deployCloudflare(project: Project, opts: CloudflareOptions
 	// 4. build.
 	const builder = findBuilder(app);
 	if (!builder) return fail("no build tool: neither vite-plus nor vite is installed.");
-	console.log(`\n▸ ${builder.label}`);
+
+	// In strict the STOREFRONT is a second Void app, at the repository root,
+	// and it has to be built first: its prerendered tree is folded into the
+	// worker's assets below, and the worker's build is what emits the config
+	// that names that directory.
+	const merging = oneOrigin(project.manifest.layout) && !isSingleApp(project.manifest.layout);
+	if (merging) {
+		console.log(`\n▸ ${builder.label} ${color.dim("(the storefront)")}`);
+		const storefront = await wrangler(builder.cmd, ["build"], project.root, true);
+		if (storefront.code !== 0) return fail(`the storefront build failed (exit ${storefront.code}).`);
+	}
+
+	console.log(`\n▸ ${builder.label}${merging ? color.dim(" (the worker)") : ""}`);
 	const built = await wrangler(builder.cmd, ["build"], app, true);
 	if (built.code !== 0) return fail(`the build failed (exit ${built.code}).`);
 
+	// 4b. Fold the storefront into the worker's assets.
+	//
+	// Void's worker already serves static assets: it runs first for every
+	// request and calls `env.ASSETS.fetch` only when its own router 404s. So
+	// the storefront's prerendered files land in the same directory and are
+	// reached by exactly that fallback — no routing rules, no second origin.
+	//
+	// Filenames are content-hashed, so the two trees merge without collision.
+	// `.vite/manifest.json` is the one exception and is build metadata that
+	// should never be uploaded at all.
+	if (merging) {
+		const from = join(project.root, "dist", "client");
+		const into = join(app, "dist", "client");
+		if (!existsSync(from)) return fail(`the storefront build emitted no ${from} — is the root a Void app with output "static"?`);
+		if (!existsSync(into)) return fail(`the worker build emitted no ${into}; there is nothing to merge into.`);
+		const merged = mergeTree(from, into, new Set([".vite"]));
+		// The worker owns "/" only if it has a page for it. It must not, or the
+		// shop's front door is unreachable — so this is checked, not assumed.
+		if (!existsSync(join(into, "index.html"))) {
+			return fail("the storefront produced no index.html, so the shop has no front page.");
+		}
+		console.log(`${color.green("✓")} folded ${merged} storefront file${merged === 1 ? "" : "s"} into the worker's assets`);
+	}
+
 	// 5. scrub.
 	const emittedPath = join(app, "dist", "ssr", "wrangler.json");
 	if (!existsSync(emittedPath)) return fail(`the build emitted no ${emittedPath} — is this a Void app on the Cloudflare target?`);
@@ -183,6 +219,34 @@ export async function deployCloudflare(project: Project, opts: CloudflareOptions
 	const domain = project.manifest.shop.domain;
 	const url = `https://${workerHosts(project.manifest)[0]}`;
 	console.log(`\n${color.green("Live:")} ${url}`);
-	if (hasFrontend(project.manifest.layout)) console.log(color.dim("The storefront deploys itself from GitHub Actions on push."));
+	if (hasFrontend(project.manifest.layout) && !oneOrigin(project.manifest.layout)) {
+		console.log(color.dim("The storefront deploys itself from GitHub Actions on push."));
+	}
 	return 0;
 }
+
+
+/**
+ * Copy one built tree over another, skipping named directories.
+ *
+ * Deliberately additive rather than a replace: the worker's own client
+ * bundles are already in the target and must survive. Returns how many files
+ * were written, so the deploy can say so rather than claiming success
+ * silently.
+ */
+function mergeTree(from: string, into: string, skip: Set<string>): number {
+	let count = 0;
+	for (const entry of readdirSync(from, { withFileTypes: true })) {
+		if (skip.has(entry.name)) continue;
+		const source = join(from, entry.name);
+		const target = join(into, entry.name);
+		if (entry.isDirectory()) {
+			mkdirSync(target, { recursive: true });
+			count += mergeTree(source, target, skip);
+		} else {
+			copyFileSync(source, target);
+			count += 1;
+		}
+	}
+	return count;
+}

package/src/deploy/github.ts

@@ -0,0 +1,198 @@
+import { spawn } from "node:child_process";
+import { delimiter, join } from "node:path";
+import { existsSync } from "node:fs";
+
+/**
+ * GitHub as the root of trust.
+ *
+ * ── Why GitHub and not Cloudflare ────────────────────────────────────────
+ *
+ * The shop's credentials have to be reachable by whatever deploys it, and
+ * whatever deploys it has to be reachable by a push. The first design
+ * derived the encryption key from a Cloudflare API token, which put the
+ * bootstrap in the wrong order: the token authorises a worker that does not
+ * exist yet, and getting one means `wrangler login` — the exact step this is
+ * supposed to remove.
+ *
+ * GitHub is already there. A person who can push is logged into `gh`, and
+ * `gh` can write repository secrets. So GitHub holds the credentials, GitHub
+ * Actions is the thing that deploys, and the local machine holds nothing.
+ *
+ * ── What this cannot do, stated plainly ──────────────────────────────────
+ *
+ * It cannot mint a Cloudflare credential. There is no OIDC or workload
+ * identity federation from GitHub Actions to the Cloudflare API — the
+ * request has been open since 2025 with no Cloudflare commitment, and the
+ * official CI guidance is still "store an API token in your CI provider's
+ * secrets". The Cloudflare GitHub App runs one way: it grants Cloudflare
+ * access to the repository, not the repository access to Cloudflare.
+ *
+ * So exactly one long-lived Cloudflare token must exist, and this module's
+ * job is to make sure it exists in ONE place — GitHub's encrypted secrets —
+ * rather than on a laptop, in a shell profile, or in `~/.wrangler`.
+ *
+ * @see https://developers.cloudflare.com/workers/ci-cd/external-cicd/github-actions/
+ * @see https://github.com/cloudflare/workers-sdk/discussions/11434
+ */
+
+export interface GhAuth {
+	/** Logged in, with a token that can write repository secrets. */
+	ok: boolean;
+	user?: string | undefined;
+	scopes?: string[] | undefined;
+	reason?: string | undefined;
+}
+
+/** The scope `gh secret set` needs on a repository. */
+const REPO_SCOPE = "repo";
+
+export function findGh(): string | null {
+	for (const entry of (process.env["PATH"] ?? "").split(delimiter).filter(Boolean)) {
+		if (existsSync(join(entry, "gh"))) return join(entry, "gh");
+	}
+	return null;
+}
+
+export function run(
+	cmd: string,
+	args: string[],
+	cwd: string,
+	stdin?: string,
+): Promise<{ code: number; out: string }> {
+	return new Promise((resolve) => {
+		const child = spawn(cmd, args, { cwd, stdio: ["pipe", "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 }));
+		// Always closed: a `gh` subcommand that reads stdin and never sees EOF
+		// hangs forever, and one that does not read it does not mind.
+		child.stdin?.end(stdin ?? "");
+	});
+}
+
+/** Is `gh` here, logged in, and scoped to write secrets? */
+export async function ghAuth(cwd: string): Promise<GhAuth> {
+	const gh = findGh();
+	if (!gh) {
+		return { ok: false, reason: "the GitHub CLI is not installed. https://cli.github.com — then `gh auth login`." };
+	}
+	const status = await run(gh, ["auth", "status"], cwd);
+	if (status.code !== 0) {
+		return { ok: false, reason: "gh is not logged in. Run `gh auth login`." };
+	}
+	const user = /Logged in to \S+ account (\S+)/.exec(status.out)?.[1];
+	const scopes = /Token scopes: (.+)/
+		.exec(status.out)?.[1]
+		?.split(",")
+		.map((scope) => scope.trim().replace(/^'|'$/g, ""));
+	if (scopes && !scopes.includes(REPO_SCOPE)) {
+		return {
+			ok: false,
+			user,
+			scopes,
+			reason: `gh is logged in as ${user ?? "you"} but its token lacks the \`${REPO_SCOPE}\` scope, which writing repository secrets needs.\n  Run \`gh auth refresh -s ${REPO_SCOPE}\`.`,
+		};
+	}
+	return { ok: true, user, scopes };
+}
+
+/** `owner/repo` for this checkout, or null when there is no GitHub remote yet. */
+export async function repoSlug(cwd: string): Promise<string | null> {
+	const gh = findGh();
+	if (!gh) return null;
+	const viewed = await run(gh, ["repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"], cwd);
+	if (viewed.code !== 0) return null;
+	const slug = viewed.out.trim();
+	return /^[^/\s]+\/[^/\s]+$/.test(slug) ? slug : null;
+}
+
+/**
+ * Write a repository secret, with the value on STDIN.
+ *
+ * Never as an argument: an argument is visible in `ps` to every other
+ * process on the machine for as long as the call runs, and this is called
+ * with private keys.
+ */
+export async function setSecret(cwd: string, name: string, value: string): Promise<{ ok: boolean; error?: string }> {
+	const gh = findGh();
+	if (!gh) return { ok: false, error: "gh is not installed" };
+	const result = await run(gh, ["secret", "set", name], cwd, value);
+	return result.code === 0 ? { ok: true } : { ok: false, error: result.out.trim().split("\n").slice(-2).join(" ") };
+}
+
+/** Repository secret NAMES. GitHub never gives a value back, by design. */
+export async function secretNames(cwd: string): Promise<Set<string>> {
+	const gh = findGh();
+	if (!gh) return new Set();
+	const listed = await run(gh, ["secret", "list", "--json", "name", "-q", ".[].name"], cwd);
+	if (listed.code !== 0) return new Set();
+	return new Set(
+		listed.out
+			.split("\n")
+			.map((line) => line.trim())
+			.filter(Boolean),
+	);
+}
+
+/** A repository VARIABLE — readable, for things that are configuration rather than credentials. */
+export async function setVariable(cwd: string, name: string, value: string): Promise<{ ok: boolean; error?: string }> {
+	const gh = findGh();
+	if (!gh) return { ok: false, error: "gh is not installed" };
+	const result = await run(gh, ["variable", "set", name, "--body", value], cwd);
+	return result.code === 0 ? { ok: true } : { ok: false, error: result.out.trim().split("\n").slice(-2).join(" ") };
+}
+
+export async function variableNames(cwd: string): Promise<Set<string>> {
+	const gh = findGh();
+	if (!gh) return new Set();
+	const listed = await run(gh, ["variable", "list", "--json", "name", "-q", ".[].name"], cwd);
+	if (listed.code !== 0) return new Set();
+	return new Set(
+		listed.out
+			.split("\n")
+			.map((line) => line.trim())
+			.filter(Boolean),
+	);
+}
+
+/**
+ * Ask Cloudflare whether a token is real, before it is stored anywhere.
+ *
+ * A token that is wrong should be caught at the moment it is typed, by the
+ * person who has it, and not two minutes into a CI run by someone reading a
+ * log. This is the one Cloudflare call vc makes with the token in hand.
+ *
+ * @see https://developers.cloudflare.com/fundamentals/api/reference/verify-token/
+ */
+export async function verifyCloudflareToken(token: string): Promise<{ ok: boolean; detail: string }> {
+	try {
+		const response = await fetch("https://api.cloudflare.com/client/v4/user/tokens/verify", {
+			headers: { Authorization: `Bearer ${token}` },
+		});
+		const body = (await response.json()) as { success?: boolean; result?: { status?: string }; errors?: Array<{ message?: string }> };
+		if (body.success && body.result?.status === "active") return { ok: true, detail: "active" };
+		const message = body.errors?.[0]?.message ?? `HTTP ${response.status}`;
+		return { ok: false, detail: message };
+	} catch (error) {
+		return { ok: false, detail: `could not reach the Cloudflare API: ${String(error)}` };
+	}
+}
+
+/** The accounts a token can see, so the account id never has to be typed. */
+export async function cloudflareAccounts(token: string): Promise<Array<{ id: string; name: string }>> {
+	try {
+		const response = await fetch("https://api.cloudflare.com/client/v4/accounts?per_page=50", {
+			headers: { Authorization: `Bearer ${token}` },
+		});
+		const body = (await response.json()) as { success?: boolean; result?: Array<{ id: string; name: string }> };
+		return body.success && Array.isArray(body.result) ? body.result.map((a) => ({ id: a.id, name: a.name })) : [];
+	} catch {
+		return [];
+	}
+}

package/src/deploy/index.ts

@@ -6,6 +6,7 @@ import { deployCloudflare } from "./cloudflare";
 import { preflight, printPreflight } from "./preflight";
 import { PRIVATE_KEY_VAR, SECRETS_FILE, plaintextSecretNames, secretsCommand } from "./secrets";
 import { keysCommand } from "./keys";
+import { linkCommand } from "./link";
 
 /**
  * `vc deploy` extends `void deploy`: vc's preflight first, then void's
@@ -79,8 +80,11 @@ export async function deployHelp(): Promise<number> {
 		...row("vc deploy --cloudflare --force", "deploy a shop preflight says is not ready — deliberately", width, 2),
 		line("", width),
 		line(color.bold("Needs, for --cloudflare"), width),
-		...row("wrangler login", "or CLOUDFLARE_API_TOKEN; the account is pinned for you when there is one", width, 2),
-		...row("wrangler secret put <KEY>", "each secret, on the worker — preflight lists them", width, 2),
+		...row("CLOUDFLARE_API_TOKEN", "in the environment; the account is pinned for you when there is one", width, 2),
+		...row(PRIVATE_KEY_VAR, "to decrypt the shop's own secrets", width, 2),
+		line("", width),
+		line("Normally neither is on your machine: `vc link` puts both on the GitHub", width),
+		line("repository and the workflow runs this command for you on every push.", width),
 	], width);
 	if (captured) process.stdout.write(captured.out.replace(/\n*$/, "\n"));
 	console.log(ours);
@@ -119,14 +123,16 @@ export async function secretsHelp(): Promise<number> {
 			line(`Secrets that live in the repository, encrypted, in ${SECRETS_FILE}.`, width),
 			line("", width),
 			...row("vc secrets", "what this shop needs, and whether it is declared and encrypted", width, 2),
-			...row("vc secrets --init", `write ${SECRETS_FILE} with every required key as \`unset\``, width, 2),
-			...row(`dotenvx set KEY '…' -f ${SECRETS_FILE}`, "set one, without decrypting the file", width, 2),
-			...row(`dotenvx encrypt -f ${SECRETS_FILE}`, "encrypt anything still in the clear", width, 2),
+			...row("vc secrets --init", `write ${SECRETS_FILE} and make this shop's key`, width, 2),
+			...row("vc secrets set KEY", "set one value — prompts, so it never reaches your shell history", width, 2),
+			...row("echo v | vc secrets set KEY", "the same, from a pipe, for scripts", width, 2),
 			line("", width),
 			line("The file is COMMITTED: values are ciphertext, key names are not, so a", width),
 			line("diff shows which secret changed without showing what it changed to.", width),
-			line(`The private key stays out — .env.keys locally, and ${PRIVATE_KEY_VAR}`, width),
-			line("as one build variable where the deploy runs.", width),
+			line("", width),
+			line("Setting one needs NO credential. dotenvx is asymmetric, so encryption uses", width),
+			line(`the public key already in ${SECRETS_FILE}. The private key is a GitHub`, width),
+			line(`Actions secret, ${PRIVATE_KEY_VAR}, and only the deploy uses it.`, width),
 			line("", width),
 			line("Tradeoff worth knowing: ciphertext in git is permanent, so a leaked key", width),
 			line("exposes rotated secrets too. `wrangler secret put` does not have that", width),
@@ -143,25 +149,29 @@ export async function keysCliCommand(args: string[]): Promise<number> {
 		console.error("vc: no voidcommerce.json here.");
 		return 1;
 	}
-	return keysCommand(project.manifest, project.root, args);
+	return keysCommand(project, args);
 }
 
 export async function keysHelp(): Promise<number> {
 	const width = 80;
 	console.log(
 		box("vc keys", [
-			line("The key that encrypts this repository's secrets is DERIVED from", width),
-			line("CLOUDFLARE_API_TOKEN, salted with the account id. Nothing is stored.", width),
+			line("Secrets are encrypted with a PUBLIC key that is committed, and read with", width),
+			line("a PRIVATE key that lives only in GitHub Actions.", width),
+			line("", width),
+			...row("vc keys", "where the key is, and what is missing", width, 2),
+			...row("vc keys --init", "generate one and store it on the GitHub repository", width, 2),
+			...row("vc keys --rotate", "re-key and re-encrypt, if you hold the current private key", width, 2),
 			line("", width),
-			...row("vc keys", "what this token derives, and whether it matches the repository", width, 2),
-			...row("vc keys --rotate", "re-encrypt under a new token, while the old one still works", width, 2),
+			line("Because the encryption is asymmetric, SETTING a secret needs no credential", width),
+			line("at all: `vc secrets set KEY` encrypts with the public key in the repository.", width),
+			line("A contributor with only a clone can rotate the Stripe key and cannot read", width),
+			line("the one already there. Only the deploy decrypts.", width),
 			line("", width),
-			line("Whoever can deploy the worker can read its secrets, and nobody else can.", width),
-			line("The price: rotating the token orphans every encrypted value, a second", width),
-			line("admin's token derives a different key, and the build must use the same", width),
-			line("token the values were encrypted under. `vc keys` checks the derived", width),
-			line("public key against the committed one, so a mismatch is a clear refusal", width),
-			line("rather than a decryption error nobody can place.", width),
+			line("GitHub will not hand a secret back once set, so re-keying without a local", width),
+			line("copy means entering the values again. That is the right trade: a key worth", width),
+			line("rotating is a key that may have leaked, and leaked values need replacing", width),
+			line("at the source anyway.", width),
 		], width),
 	);
 	return 0;
@@ -187,3 +197,41 @@ export async function guardCommand(): Promise<number> {
 	);
 	return 1;
 }
+
+
+/** `vc link` — GitHub holds the credentials; this is what puts them there. */
+export async function linkCliCommand(args: string[]): Promise<number> {
+	const project = await findProject();
+	if (!project) {
+		console.error("vc: no voidcommerce.json here.");
+		return 1;
+	}
+	return linkCommand(project, args);
+}
+
+export async function linkHelp(): Promise<number> {
+	const width = 80;
+	console.log(
+		box("vc link", [
+			line("Put this shop's credentials on its GitHub repository, once, so that", width),
+			line("every deploy after this is a `git push`.", width),
+			line("", width),
+			...row("vc link", "generate the encryption key, take the Cloudflare token, store both", width, 2),
+			...row("vc link --force", "replace what is already there", width, 2),
+			line("", width),
+			line(color.bold("What it stores, and where"), width),
+			...row("DOTENV_PRIVATE_KEY_SECRETS", "generated here, never written to disk — a repository SECRET", width, 2),
+			...row("CLOUDFLARE_API_TOKEN", "yours, checked against the Cloudflare API first — a repository SECRET", width, 2),
+			...row("CLOUDFLARE_ACCOUNT_ID", "an identifier, not a credential — a repository VARIABLE", width, 2),
+			line("", width),
+			line(color.bold("Why one token still has to be typed"), width),
+			line("GitHub cannot mint a Cloudflare credential. There is no OIDC federation", width),
+			line("between them, and the Cloudflare GitHub App runs the other way: it grants", width),
+			line("Cloudflare access to your repository, not your repository access to", width),
+			line("Cloudflare. Something must authorise creating a database in your account,", width),
+			line("and only Cloudflare can issue that. So it is typed once, here, and never", width),
+			line("stored on this machine.", width),
+		], width),
+	);
+	return 0;
+}