@saastemly/voidcommerce 0.6.0 → 0.8.0

package/dist/{index-f1wds190.js → index-y6qzjd9h.js}

@@ -9,7 +9,7 @@ import {
   renderEnvLocal,
   renderEnvProduction,
   renderEnvTs
-} from "./index-2qt2yh3z.js";
+} from "./index-j5xjh6qp.js";
 import {
   MANIFEST_FILE,
   has,
@@ -22,10 +22,10 @@ import {
   workerHosts,
   writeManifest,
   zone
-} from "./index-xx5p4b8d.js";
+} from "./index-tjy6yygc.js";
 import {
   CHOICES
-} from "./index-844b3qn9.js";
+} from "./index-mnb7fz2t.js";
 import {
   __require
 } from "./index-0v6na3yp.js";
@@ -48,10 +48,17 @@ var VAT = {
   PL: { rate: 2300, name: "VAT" }
 };
 var social = (manifest, id, envPrefix) => has(manifest, id) ? `			${id}: { clientId: must(env, "${envPrefix}_CLIENT_ID"), clientSecret: must(env, "${envPrefix}_CLIENT_SECRET") },` : null;
+var WIRED_CARRIERS = ["royal-mail", "dhl-express", "shippo", "easypost", "ups", "fedex", "nft"];
+var needsShippingConfig = (id) => WIRED_CARRIERS.includes(id) && id !== "nft";
 function renderAuthTs(manifest) {
   const { shop } = manifest;
   const lines = [];
   const CARRIER_CALLS = {
+    "royal-mail": {
+      label: "Royal Mail",
+      call: `royalMailProvider({ apiKey: must(env, "CLICK_DROP_AUTH_KEY"), services: royalMailServices, currency: "${shop.currency}", carrierName: "Royal Mail" })`,
+      import: `import { royalMailProvider } from "@saastemly/better-commerce/providers/royal-mail";`
+    },
     "dhl-express": {
       label: "DHL Express",
       call: `dhlExpressProvider({ apiKey: must(env, "DHL_API_KEY"), apiSecret: must(env, "DHL_API_SECRET"), accountNumber: must(env, "DHL_ACCOUNT_NUMBER"), from: shipFrom })`,
@@ -86,8 +93,12 @@ import { mintProvider, destinationFor } from "./lib/mint.ts";`
   };
   const carriers = Object.keys(CARRIER_CALLS).filter((id) => has(manifest, id));
   const carrierImports = carriers.map((id) => CARRIER_CALLS[id].import);
-  if (carriers.some((id) => id !== "nft"))
-    carrierImports.push(`import { shipFrom } from "./lib/shipping.ts";`);
+  const shipping = [
+    ...carriers.some((id) => id !== "nft" && id !== "royal-mail") ? ["shipFrom"] : [],
+    ...carriers.includes("royal-mail") ? ["royalMailServices"] : []
+  ];
+  if (shipping.length > 0)
+    carrierImports.push(`import { ${shipping.join(", ")} } from "./lib/shipping.ts";`);
   const wantsNft = has(manifest, "nft");
   const carrierFulfillment = carriers.length ? `, deliveryFulfillment([${carriers.map((id) => CARRIER_CALLS[id].call).join(", ")}])` : "";
   const nftDefault = carriers.length ? `, defaultProvider: "delivery:${carriers.join("+")}"` : "";
@@ -1333,7 +1344,7 @@ import color from "picocolors";
 // package.json
 var package_default = {
   name: "@saastemly/voidcommerce",
-  version: "0.6.0",
+  version: "0.8.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",
@@ -2181,13 +2192,18 @@ export async function destinationFor(orderId: string): Promise<string | null> {
 `;
 }
 function renderShippingTs(manifest) {
-  return `import type { DeliveryAddress } from "@saastemly/better-commerce/providers/delivery";
-
+  const royalMail = has(manifest, "royal-mail");
+  const origin = ["dhl-express", "shippo", "easypost", "ups", "fedex"].some((id) => has(manifest, id));
+  const imports = [
+    ...origin ? [`import type { DeliveryAddress } from "@saastemly/better-commerce/providers/delivery";`] : [],
+    ...royalMail ? [`import type { RoyalMailService } from "@saastemly/better-commerce/providers/royal-mail";`] : []
+  ];
+  const originBlock = `
 /**
  * The address every parcel is quoted and shipped FROM.
  *
- * TODO VERIFY: this is a placeholder. A carrier quotes against it, and DHL
- * refuses a shipment whose origin has no \`name\` and \`phone\`.
+ * TODO VERIFY: this is a placeholder. A carrier quotes against it, and most
+ * refuse a shipment whose origin has no \`name\` and \`phone\`.
  */
 export const shipFrom: DeliveryAddress = {
 	name: "${manifest.shop.name}",
@@ -2198,6 +2214,9 @@ export const shipFrom: DeliveryAddress = {
 	phone: "TODO VERIFY: +44…",
 };
 `;
+  return `${imports.join(`
+`)}
+${origin ? originBlock : ""}${royalMail ? ROYAL_MAIL_SERVICES() : ""}`;
 }
 function renderErpTs() {
   return `import { businessCentralProvider } from "@saastemly/better-commerce/providers/business-central";
@@ -2226,6 +2245,44 @@ export const erpFulfillment = (currency: string): FulfillmentProvider =>
 	}).fulfillment();
 `;
 }
+var ROYAL_MAIL_SERVICES = () => `
+/**
+ * What this shop charges for Royal Mail, by total parcel weight.
+ *
+ * TODO VERIFY: every \`amount\` below is a placeholder in pence. Replace them
+ * with your own OBA rate card — Click & Drop → Settings → Shipping services
+ * lists exactly which services your account has, and the codes here must be
+ * among them. Service codes are account-specific: the published list is from
+ * 2021 and Royal Mail warn that "available services are unique to your OBA
+ * account and individual service agreements".
+ *
+ * The band whose \`maxGrams\` first covers the parcel wins, so order does not
+ * matter. A parcel heavier than every band gets no rate at all rather than a
+ * wrong one, and Click & Drop refuses anything over 30 kg.
+ */
+export const royalMailServices: RoyalMailService[] = [
+	{
+		code: "TPN24",
+		name: "Tracked 24",
+		estimatedDays: 1,
+		bands: [
+			{ maxGrams: 1000, amount: 0 /* TODO VERIFY */ },
+			{ maxGrams: 2000, amount: 0 /* TODO VERIFY */ },
+			{ maxGrams: 5000, amount: 0 /* TODO VERIFY */ },
+		],
+	},
+	{
+		code: "TPS48",
+		name: "Tracked 48",
+		estimatedDays: 2,
+		bands: [
+			{ maxGrams: 1000, amount: 0 /* TODO VERIFY */ },
+			{ maxGrams: 2000, amount: 0 /* TODO VERIFY */ },
+			{ maxGrams: 5000, amount: 0 /* TODO VERIFY */ },
+		],
+	},
+];
+`;
 
 // src/generate/index.ts
 async function exists(path) {
@@ -2314,7 +2371,7 @@ async function generateApi(root, dir, manifest, result, opts) {
   if (has(manifest, "nft")) {
     await put(root, at("lib/mint.ts"), renderMintTs(), result, own);
   }
-  if (["dhl-express", "shippo", "easypost", "ups", "fedex"].some((id) => has(manifest, id))) {
+  if (WIRED_CARRIERS.some((id) => needsShippingConfig(id) && has(manifest, id))) {
     await put(root, at("lib/shipping.ts"), renderShippingTs(manifest), result, own);
   }
   if (has(manifest, "business-central")) {
@@ -2444,9 +2501,17 @@ dist
 `, result, "own");
   await put(root, "patches/void@0.10.13.patch", renderVoidPatch(), result, "regenerate");
   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.
+# Generated by \`vc init\`.
+#
+# Encrypts any value sitting in the clear in .env.secrets, and re-stages the
+# file so the COMMIT carries the ciphertext rather than what you staged.
+# Encryption needs only the public key in that file, so this needs no
+# credential and works on a fresh clone.
+#
+# It refuses only when it cannot fix the problem itself: no key yet
+# (\`vc keys --init\`), or a .env.keys that is not gitignored. A secret
+# committed in the clear cannot be un-committed — the value stays in the
+# history and has to be treated as burned.
 bunx vc guard
 `, result, "regenerate");
   await put(root, ".github/workflows/deploy.yml", renderDistWorkflow(manifest), result, "regenerate");

package/dist/index.js

@@ -51,7 +51,7 @@ import {
   routeProblem,
   strictDependencies,
   upsertJsonc
-} from "./index-f1wds190.js";
+} from "./index-y6qzjd9h.js";
 import {
   allEnvKeys,
   envSummary,
@@ -59,7 +59,7 @@ import {
   renderEnvLocal,
   renderEnvProduction,
   renderEnvTs
-} from "./index-2qt2yh3z.js";
+} from "./index-j5xjh6qp.js";
 import {
   LAYOUTS,
   MANIFEST_FILE,
@@ -80,7 +80,7 @@ import {
   writeManifest,
   zone,
   zoneOf
-} from "./index-xx5p4b8d.js";
+} from "./index-tjy6yygc.js";
 import {
   AUTH_PLUGINS,
   CARRIERS,
@@ -97,7 +97,7 @@ import {
   SIGN_IN,
   TAX,
   UI
-} from "./index-844b3qn9.js";
+} from "./index-mnb7fz2t.js";
 import"./index-0v6na3yp.js";
 export {
   zoneOf,

package/dist/{keys-qwvt324e.js → keys-3zjezaxk.js}

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

package/dist/manifest.js

@@ -18,8 +18,8 @@ import {
   writeManifest,
   zone,
   zoneOf
-} from "./index-xx5p4b8d.js";
-import"./index-844b3qn9.js";
+} from "./index-tjy6yygc.js";
+import"./index-mnb7fz2t.js";
 import"./index-0v6na3yp.js";
 export {
   zoneOf,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saastemly/voidcommerce",
-  "version": "0.6.0",
+  "version": "0.8.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/catalog.ts

@@ -519,7 +519,18 @@ export const CARRIERS: Group = {
 		{ id: "fedex", label: "FedEx", hint: "your own FedEx account, for negotiated rates an aggregator cannot see", env: [{ key: "FEDEX_CLIENT_ID", breaks: "FedEx rates are not quoted" }, { key: "FEDEX_CLIENT_SECRET", breaks: "the same" }, { key: "FEDEX_ACCOUNT_NUMBER", breaks: "FedEx has no account to bill the transport to" }] },
 		{ id: "dhl-express", label: "DHL Express", hint: "international express, and the one worth having for a shop that posts abroad", env: [{ key: "DHL_API_KEY", breaks: "DHL rates are not quoted" }, { key: "DHL_API_SECRET", breaks: "the same" }, { key: "DHL_ACCOUNT_NUMBER", breaks: "DHL has no account to bill the transport to" }] },
 		{ id: "usps", label: "USPS", hint: "US domestic post — the cheapest way to ship a small parcel inside the US", env: [{ key: "USPS_CLIENT_ID", breaks: "USPS rates are not quoted" }, { key: "USPS_CLIENT_SECRET", breaks: "the same" }] },
-		{ id: "royal-mail", label: "Royal Mail", hint: "UK post, for a shop whose customers are mostly in Britain", env: [{ key: "ROYAL_MAIL_CLIENT_ID", breaks: "Royal Mail rates are not quoted" }] },
+		{
+			id: "royal-mail",
+			label: "Royal Mail (Click & Drop)",
+			hint: "UK post. Needs an OBA business account — Click & Drop generates labels through the API only for those. Prices come from your own tariff table, because no Royal Mail API quotes rates",
+			env: [
+				{
+					key: "CLICK_DROP_AUTH_KEY",
+					breaks: "no label and no tracking number: orders are created in Click & Drop but never despatched",
+					where: "Click & Drop → Settings → Integrations → Click & Drop API",
+				},
+			],
+		},
 		{ id: "aramex", label: "Aramex", hint: "the carrier to reach the Gulf and wider Middle East reliably", env: [{ key: "ARAMEX_API_KEY", breaks: "Aramex rates are not quoted" }] },
 		{ id: "doordash-drive", label: "DoorDash Drive", hint: "same-day local delivery", env: [{ key: "DOORDASH_DEVELOPER_ID", breaks: "DoorDash is not offered" }] },
 		{ id: "stuart", label: "Stuart", hint: "same-day courier, Europe", env: [{ key: "STUART_CLIENT_ID", breaks: "Stuart is not offered" }] },

package/src/deploy/index.ts

@@ -4,8 +4,10 @@ import { findProject } from "../project";
 import { captureVoid, runVoid } from "../void";
 import { deployCloudflare } from "./cloudflare";
 import { preflight, printPreflight } from "./preflight";
-import { PRIVATE_KEY_VAR, SECRETS_FILE, plaintextSecretNames, secretsCommand } from "./secrets";
-import { keysCommand } from "./keys";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { PRIVATE_KEY_VAR, SECRETS_FILE, encryptInto, plaintextSecretEntries, plaintextSecretNames, run, secretsCommand } from "./secrets";
+import { LOCAL_KEY_FILE, committedPublicKey, ignoresKeyFile, keysCommand } from "./keys";
 import { linkCommand } from "./link";
 
 /**
@@ -178,27 +180,97 @@ export async function keysHelp(): Promise<number> {
 }
 
 /**
- * The pre-commit gate: refuse a commit that would put a secret in the clear.
+ * The pre-commit gate: ENCRYPT anything in the clear, then let the commit through.
+ *
+ * ── Why this encrypts rather than refuses ────────────────────────────────
+ *
+ * It used to refuse, and refusing was the wrong shape. Encryption needs only
+ * the public key, which is committed right there in the file — so the hook
+ * can simply fix the problem instead of handing it back. A person who typed
+ * a real key into `.env.secrets` with an editor gets it sealed rather than a
+ * lecture, which is what actually keeps secrets out of history: a gate you
+ * have to satisfy by hand is a gate people learn to pass with --no-verify.
+ *
+ * ── The part that is easy to get wrong ───────────────────────────────────
+ *
+ * Git commits the INDEX, not the working tree. Encrypting the file on disk
+ * would leave the STAGED plaintext exactly where it was, and the commit
+ * would carry it anyway — the hook would report success while doing nothing.
+ * So a file that was staged is re-staged after encrypting, and the result is
+ * verified before the commit is allowed.
  *
  * Exit code is the whole interface — a hook cares about nothing else.
  */
 export async function guardCommand(): Promise<number> {
 	const project = await findProject();
 	if (!project) return 0; // Not a shop; nothing to guard.
-	const bare = plaintextSecretNames(project.root);
+	const root = project.root;
+
+	// A key file that is not ignored is a worse leak than any single value:
+	// it opens every secret in the repository, including ones already rotated.
+	if (existsSync(join(root, LOCAL_KEY_FILE)) && !ignoresKeyFile(root)) {
+		console.error(
+			`\n${color.red("✗ refusing the commit")}: ${LOCAL_KEY_FILE} exists and is NOT gitignored.\n\n` +
+				`  It holds the private key that opens every secret in this repository.\n` +
+				`  Add ${LOCAL_KEY_FILE} to .gitignore before committing anything.\n`,
+		);
+		return 1;
+	}
+
+	const bare = plaintextSecretEntries(root);
 	if (bare.length === 0) return 0;
-	console.error(
-		`\n${color.red("✗ refusing the commit")}: ${bare.length} value${bare.length === 1 ? "" : "s"} in ${SECRETS_FILE} ${
-			bare.length === 1 ? "is" : "are"
-		} not encrypted.\n\n` +
-			`    ${bare.join("\n    ")}\n\n` +
-			`  bunx dotenvx encrypt -f ${SECRETS_FILE}\n\n` +
-			color.dim("  Committing a secret in the clear cannot be undone by a later commit;\n  the value stays in the history and must be treated as burned.\n"),
+
+	const publicKey = committedPublicKey(root);
+	if (!publicKey) {
+		console.error(
+			`\n${color.red("✗ refusing the commit")}: ${bare.length} value${bare.length === 1 ? "" : "s"} in ${SECRETS_FILE} ${
+				bare.length === 1 ? "is" : "are"
+			} in the clear, and there is no key to encrypt ${bare.length === 1 ? "it" : "them"} with.\n\n` +
+				`    ${bare.map((entry) => entry.name).join("\n    ")}\n\n` +
+				`  ${color.cyan("vc keys --init")}  makes one — no GitHub repository needed yet.\n\n` +
+				color.dim("  Committing a secret in the clear cannot be undone by a later commit;\n  the value stays in the history and must be treated as burned.\n"),
+		);
+		return 1;
+	}
+
+	// Was it staged? Decides whether the commit is carrying the plaintext.
+	const staged = (await run("git", ["diff", "--cached", "--name-only", "--", SECRETS_FILE], root)).out.trim().length > 0;
+
+	for (const entry of bare) {
+		const sealed = await encryptInto(root, publicKey, entry.name, entry.value);
+		if (!sealed.ok) {
+			console.error(`\n${color.red("✗ refusing the commit")}: ${sealed.error}\n`);
+			return 1;
+		}
+	}
+
+	// Never trust the loop: re-read and check. This is the last thing standing
+	// between a live credential and a permanent record of it.
+	const left = plaintextSecretNames(root);
+	if (left.length > 0) {
+		console.error(`\n${color.red("✗ refusing the commit")}: ${left.join(", ")} could not be encrypted.\n`);
+		return 1;
+	}
+
+	if (staged) {
+		const added = await run("git", ["add", "--", SECRETS_FILE], root);
+		if (added.code !== 0) {
+			console.error(
+				`\n${color.red("✗ refusing the commit")}: ${SECRETS_FILE} was encrypted but could not be re-staged,\n` +
+					`  so the commit would still carry the plaintext you staged. \`git add ${SECRETS_FILE}\`.\n`,
+			);
+			return 1;
+		}
+	}
+
+	console.log(
+		`\n${color.green("✓")} encrypted ${bare.length} value${bare.length === 1 ? "" : "s"} in ${SECRETS_FILE}${staged ? " and re-staged it" : ""}: ${bare
+			.map((entry) => entry.name)
+			.join(", ")}\n` + color.dim(`  Encryption needs only the public key, so this needs no credential.\n`),
 	);
-	return 1;
+	return 0;
 }
 
-
 /** `vc link` — GitHub holds the credentials; this is what puts them there. */
 export async function linkCliCommand(args: string[]): Promise<number> {
 	const project = await findProject();
@@ -216,21 +288,19 @@ export async function linkHelp(): Promise<number> {
 			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", "store the encryption key and the Cloudflare token on the repository", 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),
+			...row(PRIVATE_KEY_VAR, "a repository SECRET. A key already waiting locally is MOVED here and the local copy deleted", width, 2),
+			...row("CLOUDFLARE_API_TOKEN", "a repository SECRET, checked against the Cloudflare API before it is stored", width, 2),
+			...row("CLOUDFLARE_ACCOUNT_ID", "a repository VARIABLE — an identifier, not a credential", 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),
+			line("Cloudflare. So it is typed once, here, and never stored on this machine.", width),
 		], width),
 	);
 	return 0;

package/src/deploy/keys.ts

@@ -45,6 +45,26 @@ import { PRIVATE_KEY_VAR, SECRETS_FILE, committedPublicKeyInto, findDotenvx, run
  * Re-entering them is not extra work — it is the work.
  */
 
+/**
+ * Where a private key waits before the repository exists.
+ *
+ * Encryption needs only the public key, so a shop can be filled in with real
+ * secrets long before anyone has made a GitHub repo to put the private half
+ * on. Refusing to make a key until then would block exactly that, so
+ * `vc keys --init` will write one here instead — 0600, gitignored, and
+ * TEMPORARY: `vc link` uploads this key to the repository and deletes the
+ * file, which is how the end state stays "no private key on disk".
+ */
+export const LOCAL_KEY_FILE = ".env.keys";
+
+/** The private key parked locally, if there is one. */
+export function localPrivateKey(root: string): string | null {
+	const path = join(root, LOCAL_KEY_FILE);
+	if (!existsSync(path)) return null;
+	const match = new RegExp(`^\\s*${PRIVATE_KEY_VAR}\\s*=\\s*["']?([0-9a-fA-F]+)["']?`, "m").exec(readFileSync(path, "utf8"));
+	return match?.[1] ?? null;
+}
+
 /** The public key the repository was encrypted under, from the committed file. */
 export function committedPublicKey(root: string): string | null {
 	const path = join(root, SECRETS_FILE);
@@ -89,7 +109,7 @@ export async function keyState(project: Project): Promise<KeyState> {
 	const publicKey = committedPublicKey(project.root);
 	const slug = await repoSlug(project.root);
 	const names = slug ? await secretNames(project.root) : new Set<string>();
-	const localKey = process.env[PRIVATE_KEY_VAR] ?? null;
+	const localKey = process.env[PRIVATE_KEY_VAR] ?? localPrivateKey(project.root);
 
 	let mismatch: string | undefined;
 	if (localKey && publicKey) {
@@ -108,28 +128,51 @@ export async function keyState(project: Project): Promise<KeyState> {
  * private key is deliberately not returned and not logged: it exists as a
  * local variable for the length of one `gh` call and then goes out of scope.
  */
-export async function provisionKey(project: Project): Promise<{ ok: true; publicKey: string } | { ok: false; reason: string }> {
+export async function provisionKey(project: Project): Promise<{ ok: true; publicKey: string; parked: boolean } | { ok: false; reason: string }> {
+	// An existing key is REUSED, never replaced: a new one would orphan
+	// everything the old one has already encrypted.
+	const parked = localPrivateKey(project.root);
+	if (parked) {
+		const publicKey = await publicKeyFor(parked);
+		if (publicKey) return { ok: true, publicKey, parked: true };
+	}
+
+	const pair = await generateKeypair();
+	if (!pair) return { ok: false, reason: "@dotenvx/dotenvx is not installed here. `bun add -d @dotenvx/dotenvx`" };
+
 	const auth = await ghAuth(project.root);
-	if (!auth.ok) return { ok: false, reason: auth.reason ?? "gh is unavailable" };
+	const slug = auth.ok ? await repoSlug(project.root) : null;
 
-	const slug = await repoSlug(project.root);
-	if (!slug) {
+	if (slug) {
+		const sent = await setSecret(project.root, PRIVATE_KEY_VAR, pair.privateKey);
+		if (!sent.ok) return { ok: false, reason: `GitHub refused the secret: ${sent.error ?? "unknown error"}` };
+		return { ok: true, publicKey: pair.publicKey, parked: false };
+	}
+
+	// No repository yet. Park the key rather than refusing: the alternative is
+	// that nobody can put a secret in the shop until they have made a repo,
+	// which is the wrong order to force on anyone.
+	if (!ignoresKeyFile(project.root)) {
 		return {
 			ok: false,
 			reason:
-				"this checkout has no GitHub repository yet, and the key is stored on the repository.\n" +
-				"  Create one first:\n\n" +
-				"    gh repo create --source=. --private --push\n",
+				`there is no GitHub repository yet, so the private key would have to wait in ${LOCAL_KEY_FILE} —\n` +
+				`  and ${LOCAL_KEY_FILE} is NOT gitignored here. Add it to .gitignore first; committing it\n` +
+				"  would publish the key that opens every secret in the repository.",
 		};
 	}
+	writeFileSync(join(project.root, LOCAL_KEY_FILE), `${PRIVATE_KEY_VAR}="${pair.privateKey}"\n`, { mode: 0o600 });
+	return { ok: true, publicKey: pair.publicKey, parked: true };
+}
 
-	const pair = await generateKeypair();
-	if (!pair) return { ok: false, reason: "@dotenvx/dotenvx is not installed here. `bun add -d @dotenvx/dotenvx`" };
-
-	const sent = await setSecret(project.root, PRIVATE_KEY_VAR, pair.privateKey);
-	if (!sent.ok) return { ok: false, reason: `GitHub refused the secret: ${sent.error ?? "unknown error"}` };
-
-	return { ok: true, publicKey: pair.publicKey };
+/** Is the local key file ignored by git? Checked before one is ever written. */
+export function ignoresKeyFile(root: string): boolean {
+	const path = join(root, ".gitignore");
+	if (!existsSync(path)) return false;
+	return readFileSync(path, "utf8")
+		.split("\n")
+		.map((line) => line.trim())
+		.some((line) => line === LOCAL_KEY_FILE || line === `/${LOCAL_KEY_FILE}` || line === ".env.keys*" || line === ".env*");
 }
 
 /** `vc keys` — where the key is, and what is missing. */
@@ -149,9 +192,16 @@ export async function keysCommand(project: Project, args: string[]): Promise<num
 		? `${state.publicKey.slice(0, 20)}… in ${SECRETS_FILE}`
 		: color.dim(hasFile ? `${SECRETS_FILE} has no key yet — \`vc link\` makes one` : `no ${SECRETS_FILE} yet — \`vc secrets --init\``);
 	console.log(`  ${state.publicKey ? color.green("✓") : color.dim("·")} public key   ${publicNote}`);
+	const parked = localPrivateKey(project.root) !== null;
 	console.log(
-		`  ${state.inGitHub ? color.green("✓") : color.red("✗")} private key  ${
-			state.inGitHub ? `${PRIVATE_KEY_VAR} is set on ${state.slug}` : state.slug ? color.red(`not set on ${state.slug} — \`vc keys --init\``) : color.dim("no GitHub repository yet")
+		`  ${state.inGitHub || parked ? color.green("✓") : color.red("✗")} private key  ${
+			state.inGitHub
+				? `${PRIVATE_KEY_VAR} is set on ${state.slug}`
+				: parked
+					? color.yellow(`waiting in ${LOCAL_KEY_FILE} — \`vc link\` moves it to GitHub and deletes it`)
+					: state.slug
+						? color.red(`not set on ${state.slug} — \`vc keys --init\``)
+						: color.dim("no key yet — `vc keys --init`")
 		}`,
 	);
 
@@ -171,7 +221,7 @@ export async function keysCommand(project: Project, args: string[]): Promise<num
 	return 0;
 }
 
-/** Generate a key, store it on the repository, and put the public half in the file. */
+/** Generate a key, put the public half in the file, and say where the private half went. */
 async function initKey(project: Project): Promise<number> {
 	const state = await keyState(project);
 	if (state.inGitHub && state.publicKey) {
@@ -188,15 +238,19 @@ async function initKey(project: Project): Promise<number> {
 		return 1;
 	}
 
-	// ALWAYS written, creating the file if need be. A private key on GitHub
-	// with no public half in the repository is a key nobody can encrypt to,
-	// and the next command would quietly generate a second one — orphaning
-	// this one and anything already sealed with it.
 	const fresh = !existsSync(join(project.root, SECRETS_FILE));
 	committedPublicKeyInto(project.root, made.publicKey);
 	console.log(
-		`\n${color.green("✓")} ${PRIVATE_KEY_VAR} set on ${state.slug}; public key in ${SECRETS_FILE}\n` +
-			(fresh ? `\n  Next: ${color.cyan("vc secrets --init")} fills in the keys this shop needs.\n` : "\n"),
+		made.parked
+			? `\n${color.green("✓")} key made; public half in ${SECRETS_FILE}, private half waiting in ${LOCAL_KEY_FILE}\n\n` +
+					color.yellow(
+						`  ${LOCAL_KEY_FILE} is TEMPORARY. It is gitignored, but it is the one file that\n` +
+							`  opens every secret in this shop. \`vc link\` moves it onto the GitHub\n` +
+							"  repository and deletes it — do that as soon as the repository exists.\n",
+					) +
+					(fresh ? `\n  Next: ${color.cyan("vc secrets --init")} fills in the keys this shop needs.\n` : "")
+			: `\n${color.green("✓")} ${PRIVATE_KEY_VAR} set on ${state.slug}; public key in ${SECRETS_FILE}\n` +
+					(fresh ? `\n  Next: ${color.cyan("vc secrets --init")} fills in the keys this shop needs.\n` : "\n"),
 	);
 	return 0;
 }

package/src/deploy/link.ts

@@ -1,8 +1,10 @@
+import { rmSync } from "node:fs";
+import { join } from "node:path";
 import color from "picocolors";
 import { writeManifest } from "../manifest";
 import type { Project } from "../project";
 import { cloudflareAccounts, ghAuth, repoSlug, secretNames, setSecret, setVariable, variableNames, verifyCloudflareToken } from "./github";
-import { keyState, provisionKey } from "./keys";
+import { LOCAL_KEY_FILE, keyState, localPrivateKey, provisionKey, publicKeyFor } from "./keys";
 import { PRIVATE_KEY_VAR, SECRETS_FILE, committedPublicKeyInto, declaredSecretNames, initSecrets } from "./secrets";
 
 /**
@@ -83,13 +85,30 @@ export async function linkCommand(project: Project, args: string[]): Promise<num
 		p.log.warn(`--force: replacing ${PRIVATE_KEY_VAR} makes every value in ${SECRETS_FILE} unreadable. Use \`vc keys --rotate\` to re-encrypt instead.`);
 		return 1;
 	} else {
-		const made = await provisionKey(project);
-		if (!made.ok) {
-			p.cancel(made.reason);
-			return 1;
+		// A key parked by `vc keys --init` before this repository existed is
+		// ADOPTED, not replaced: it may already have encrypted the whole shop.
+		const parked = localPrivateKey(root);
+		if (parked) {
+			const sent = await setSecret(root, PRIVATE_KEY_VAR, parked);
+			if (!sent.ok) {
+				p.cancel(`GitHub refused the secret: ${sent.error ?? "unknown error"}`);
+				return 1;
+			}
+			const publicKey = await publicKeyFor(parked);
+			if (publicKey) committedPublicKeyInto(root, publicKey);
+			// Only now, once GitHub has it: deleting first would lose the key
+			// outright if the upload failed.
+			rmSync(join(root, LOCAL_KEY_FILE), { force: true });
+			p.log.success(`${color.green("✓")} the key waiting in ${LOCAL_KEY_FILE} moved to GitHub, and the file deleted`);
+		} else {
+			const made = await provisionKey(project);
+			if (!made.ok) {
+				p.cancel(made.reason);
+				return 1;
+			}
+			committedPublicKeyInto(root, made.publicKey);
+			p.log.success(`${color.green("✓")} ${PRIVATE_KEY_VAR} generated and stored on GitHub; public half in ${SECRETS_FILE}`);
 		}
-		committedPublicKeyInto(root, made.publicKey);
-		p.log.success(`${color.green("✓")} ${PRIVATE_KEY_VAR} generated and stored on GitHub; public half in ${SECRETS_FILE}`);
 	}
 
 	// 3. The Cloudflare token — the one thing that cannot be derived.