@saastemly/voidcommerce 0.7.0 → 0.8.0

package/dist/cli.js

@@ -21,28 +21,36 @@ import {
   runVoid,
   version,
   voidAppsIn
-} from "./index-85m0qkmg.js";
+} from "./index-y6qzjd9h.js";
 import {
+  LOCAL_KEY_FILE,
   PRIVATE_KEY_VAR,
   SECRETS_FILE,
   cloudflareAccounts,
+  committedPublicKey,
   committedPublicKeyInto,
   declaredSecretNames,
+  encryptInto,
   envSummary,
   ghAuth,
+  ignoresKeyFile,
   initSecrets,
   keyState,
   keysCommand,
+  localPrivateKey,
+  plaintextSecretEntries,
   plaintextSecretNames,
   provisionKey,
+  publicKeyFor,
   repoSlug,
+  run,
   secretNames,
   secretsCommand,
   setSecret,
   setVariable,
   variableNames,
   verifyCloudflareToken
-} from "./index-6w8rwtsh.js";
+} from "./index-j5xjh6qp.js";
 import {
   LAYOUTS,
   oneOrigin,
@@ -60,8 +68,12 @@ import {
 
 // src/deploy/index.ts
 import color2 from "picocolors";
+import { existsSync } from "node:fs";
+import { join as join2 } from "node:path";
 
 // src/deploy/link.ts
+import { rmSync } from "node:fs";
+import { join } from "node:path";
 import color from "picocolors";
 var TOKEN_SECRET = "CLOUDFLARE_API_TOKEN";
 var ACCOUNT_VAR = "CLOUDFLARE_ACCOUNT_ID";
@@ -102,13 +114,27 @@ async function linkCommand(project, args) {
     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;
+    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);
+      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}`);
   }
   const existing = await secretNames(root);
   if (existing.has(TOKEN_SECRET) && !relink) {
@@ -335,21 +361,66 @@ async function guardCommand() {
   const project = await findProject();
   if (!project)
     return 0;
-  const bare = plaintextSecretNames(project.root);
+  const root = project.root;
+  if (existsSync(join2(root, LOCAL_KEY_FILE)) && !ignoresKeyFile(root)) {
+    console.error(`
+${color2.red("✗ refusing the commit")}: ${LOCAL_KEY_FILE} exists and is NOT gitignored.
+
+` + `  It holds the private key that opens every secret in this repository.
+` + `  Add ${LOCAL_KEY_FILE} to .gitignore before committing anything.
+`);
+    return 1;
+  }
+  const bare = plaintextSecretEntries(root);
   if (bare.length === 0)
     return 0;
-  console.error(`
-${color2.red("✗ refusing the commit")}: ${bare.length} value${bare.length === 1 ? "" : "s"} in ${SECRETS_FILE} ${bare.length === 1 ? "is" : "are"} not encrypted.
+  const publicKey = committedPublicKey(root);
+  if (!publicKey) {
+    console.error(`
+${color2.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.
 
-` + `    ${bare.join(`
+` + `    ${bare.map((entry) => entry.name).join(`
     `)}
 
-` + `  bunx dotenvx encrypt -f ${SECRETS_FILE}
+` + `  ${color2.cyan("vc keys --init")}  makes one — no GitHub repository needed yet.
 
 ` + color2.dim(`  Committing a secret in the clear cannot be undone by a later commit;
   the value stays in the history and must be treated as burned.
 `));
-  return 1;
+    return 1;
+  }
+  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(`
+${color2.red("✗ refusing the commit")}: ${sealed.error}
+`);
+      return 1;
+    }
+  }
+  const left = plaintextSecretNames(root);
+  if (left.length > 0) {
+    console.error(`
+${color2.red("✗ refusing the commit")}: ${left.join(", ")} could not be encrypted.
+`);
+    return 1;
+  }
+  if (staged) {
+    const added = await run("git", ["add", "--", SECRETS_FILE], root);
+    if (added.code !== 0) {
+      console.error(`
+${color2.red("✗ refusing the commit")}: ${SECRETS_FILE} was encrypted but could not be re-staged,
+` + `  so the commit would still carry the plaintext you staged. \`git add ${SECRETS_FILE}\`.
+`);
+      return 1;
+    }
+  }
+  console.log(`
+${color2.green("✓")} encrypted ${bare.length} value${bare.length === 1 ? "" : "s"} in ${SECRETS_FILE}${staged ? " and re-staged it" : ""}: ${bare.map((entry) => entry.name).join(", ")}
+` + color2.dim(`  Encryption needs only the public key, so this needs no credential.
+`));
+  return 0;
 }
 async function linkCliCommand(args) {
   const project = await findProject();
@@ -365,21 +436,19 @@ async function linkHelp() {
     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(color2.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(color2.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;
 }
@@ -387,7 +456,7 @@ async function linkHelp() {
 // src/init.ts
 import * as p2 from "@clack/prompts";
 import { mkdir } from "node:fs/promises";
-import { basename, join } from "node:path";
+import { basename, join as join3 } from "node:path";
 import color4 from "picocolors";
 
 // src/wizard.ts
@@ -616,7 +685,7 @@ async function init(args) {
       ["frontend", "the storefront — prerendered and served from the worker's own assets"]
     ];
     for (const [dir, starter] of parts) {
-      const target = join(root, dir);
+      const target = join3(root, dir);
       if (isVoidApp(target))
         continue;
       await mkdir(target, { recursive: true });
@@ -733,8 +802,8 @@ async function generateHelp() {
 }
 
 // src/scripts.ts
-import { existsSync, readFileSync } from "node:fs";
-import { join as join2, relative } from "node:path";
+import { existsSync as existsSync2, readFileSync } from "node:fs";
+import { join as join4, relative } from "node:path";
 function appScript(name) {
   return async (args) => {
     const project = await findProject();
@@ -743,8 +812,8 @@ function appScript(name) {
     const code = await ensureGenerated(project);
     if (code !== 0)
       return code;
-    const pkgPath = join2(project.appDir, "package.json");
-    const scripts = existsSync(pkgPath) ? JSON.parse(readFileSync(pkgPath, "utf8")).scripts ?? {} : {};
+    const pkgPath = join4(project.appDir, "package.json");
+    const scripts = existsSync2(pkgPath) ? JSON.parse(readFileSync(pkgPath, "utf8")).scripts ?? {} : {};
     if (!scripts[name]) {
       console.error(`vc: ${relative(process.cwd(), pkgPath) || "package.json"} has no "${name}" script — void init writes one.`);
       return 1;

package/dist/deploy/index.d.ts

@@ -21,7 +21,24 @@ export declare function secretsHelp(): Promise<number>;
 export declare function keysCliCommand(args: string[]): Promise<number>;
 export declare 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.
  */

package/dist/deploy/keys.d.ts

@@ -38,6 +38,19 @@ import type { Project } from "../project";
  * leaked. Those must be replaced at Stripe and everywhere else regardless.
  * 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 declare const LOCAL_KEY_FILE = ".env.keys";
+/** The private key parked locally, if there is one. */
+export declare function localPrivateKey(root: string): string | null;
 /** The public key the repository was encrypted under, from the committed file. */
 export declare function committedPublicKey(root: string): string | null;
 /** A fresh secp256k1 pair. The private half must reach GitHub and then be forgotten. */
@@ -69,9 +82,12 @@ export declare function keyState(project: Project): Promise<KeyState>;
 export declare function provisionKey(project: Project): Promise<{
     ok: true;
     publicKey: string;
+    parked: boolean;
 } | {
     ok: false;
     reason: string;
 }>;
+/** Is the local key file ignored by git? Checked before one is ever written. */
+export declare function ignoresKeyFile(root: string): boolean;
 /** `vc keys` — where the key is, and what is missing. */
 export declare function keysCommand(project: Project, args: string[]): Promise<number>;

package/dist/deploy/secrets.d.ts

@@ -68,6 +68,17 @@ export declare function committedPublicKeyInto(root: string, publicKey: string):
 export declare function declaredSecretNames(root: string): Set<string>;
 /** Is a declared value actually encrypted, or was it committed in the clear? */
 export declare function plaintextSecretNames(root: string): string[];
+/**
+ * The declared values that are NOT encrypted, with their values.
+ *
+ * Separate from `plaintextSecretNames` on purpose: names are safe to print
+ * and values never are, so the function that returns values is the one you
+ * have to go looking for.
+ */
+export declare function plaintextSecretEntries(root: string): Array<{
+    name: string;
+    value: string;
+}>;
 export interface DecryptedSecrets {
     /** A temp file in `.env` format, for `wrangler deploy --secrets-file`. */
     path: string;

package/dist/{index-6w8rwtsh.js → index-j5xjh6qp.js}

@@ -10,7 +10,7 @@ import {
 } from "./index-0v6na3yp.js";
 
 // src/deploy/keys.ts
-import { existsSync as existsSync3, readFileSync as readFileSync2 } from "node:fs";
+import { existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { join as join3 } from "node:path";
 import color2 from "picocolors";
 
@@ -353,6 +353,22 @@ function plaintextSecretNames(root) {
   }
   return bare;
 }
+function plaintextSecretEntries(root) {
+  const path = join2(root, SECRETS_FILE);
+  if (!existsSync2(path))
+    return [];
+  const out = [];
+  for (const line of readFileSync(path, "utf8").split(`
+`)) {
+    const match = /^\s*([A-Z][A-Z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    if (!match || match[1].startsWith("DOTENV_"))
+      continue;
+    const value = match[2].trim().replace(/^['"]|['"]$/g, "");
+    if (value && value !== "unset" && !value.startsWith("encrypted:"))
+      out.push({ name: match[1], value });
+  }
+  return out;
+}
 async function decryptSecrets(project) {
   const root = project.root;
   if (!existsSync2(join2(root, SECRETS_FILE)))
@@ -368,7 +384,7 @@ async function decryptSecrets(project) {
   }
   const expected = committedPublicKey(root);
   if (expected) {
-    const { publicKeyFor } = await import("./keys-92tcdjrc.js");
+    const { publicKeyFor } = await import("./keys-3zjezaxk.js");
     const derived = await publicKeyFor(privateKey);
     if (derived && derived.toLowerCase() !== expected.toLowerCase()) {
       return {
@@ -415,6 +431,8 @@ async function secretsCommand(project, args) {
     return initSecrets(project);
   if (args[0] === "set")
     return setSecretValue(project, args.slice(1));
+  if (args.includes("--sync"))
+    return syncSecrets(project);
   if (!existsSync2(join2(root, SECRETS_FILE))) {
     console.log(`
 ${color.yellow("No " + SECRETS_FILE + " yet.")} Secrets are set by hand with \`wrangler secret put\`,
@@ -607,8 +625,58 @@ function upsertLine(path, name, value) {
 `)}${name}=${value}
 `);
 }
+async function syncSecrets(project) {
+  const root = project.root;
+  const path = join2(root, SECRETS_FILE);
+  if (!existsSync2(path)) {
+    console.error(`
+vc: no ${SECRETS_FILE} yet. \`vc secrets --init\` writes one.
+`);
+    return 1;
+  }
+  const required = allEnvKeys(project.manifest).filter((key) => !key.plaintext);
+  const declared = declaredSecretNames(root);
+  const missing = required.filter((key) => !declared.has(key.key));
+  const extra = [...declared].filter((name) => !required.some((key) => key.key === name));
+  if (missing.length > 0) {
+    const body = readFileSync(path, "utf8").replace(/\n*$/, `
+`);
+    const added = missing.flatMap((key) => ["", `# ${key.breaks}${key.where ? ` — from: ${key.where}` : ""}`, `${key.key}=unset`]);
+    writeFileSync(path, `${body}${added.join(`
+`)}
+`);
+    console.log(`
+${color.green("+")} ${missing.length} key${missing.length === 1 ? "" : "s"} added to ${SECRETS_FILE}, as \`unset\`:
+`);
+    for (const key of missing)
+      console.log(`    ${color.cyan(`vc secrets set ${key.key}`)}  ${color.dim(key.where ?? "")}`);
+    console.log("");
+  } else {
+    console.log(`
+${color.green("✓")} every secret this shop needs is already declared.
+`);
+  }
+  if (extra.length > 0) {
+    console.log(`${color.yellow("!")} ${extra.length} declared key${extra.length === 1 ? " is" : "s are"} no longer required by this shop:
+    ${extra.join(`
+    `)}
+
+` + color.dim(`  Left alone — they cost nothing, and deleting a value you may still want
+  is not this command's call. Remove them by hand when you are sure.
+`));
+  }
+  return 0;
+}
 
 // src/deploy/keys.ts
+var LOCAL_KEY_FILE = ".env.keys";
+function localPrivateKey(root) {
+  const path = join3(root, LOCAL_KEY_FILE);
+  if (!existsSync3(path))
+    return null;
+  const match = new RegExp(`^\\s*${PRIVATE_KEY_VAR}\\s*=\\s*["']?([0-9a-fA-F]+)["']?`, "m").exec(readFileSync2(path, "utf8"));
+  return match?.[1] ?? null;
+}
 function committedPublicKey(root) {
   const path = join3(root, SECRETS_FILE);
   if (!existsSync3(path))
@@ -636,7 +704,7 @@ async function keyState(project) {
   const publicKey = committedPublicKey(project.root);
   const slug = await repoSlug(project.root);
   const names = slug ? await secretNames(project.root) : new Set;
-  const localKey = process.env[PRIVATE_KEY_VAR] ?? null;
+  const localKey = process.env[PRIVATE_KEY_VAR] ?? localPrivateKey(project.root);
   let mismatch;
   if (localKey && publicKey) {
     const derived = await publicKeyFor(localKey);
@@ -647,27 +715,41 @@ async function keyState(project) {
   return { publicKey, inGitHub: names.has(PRIVATE_KEY_VAR), slug, localKey, mismatch };
 }
 async function provisionKey(project) {
+  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 = await repoSlug(project.root);
-  if (!slug) {
+  const slug = auth.ok ? await repoSlug(project.root) : null;
+  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 };
+  }
+  if (!ignoresKeyFile(project.root)) {
     return {
       ok: false,
-      reason: `this checkout has no GitHub repository yet, and the key is stored on the repository.
-  Create one first:
-
-    gh repo create --source=. --private --push
-`
+      reason: `there is no GitHub repository yet, so the private key would have to wait in ${LOCAL_KEY_FILE} —
+` + `  and ${LOCAL_KEY_FILE} is NOT gitignored here. Add it to .gitignore first; committing it
+  would publish the key that opens every secret in the repository.`
     };
   }
-  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 };
+  writeFileSync2(join3(project.root, LOCAL_KEY_FILE), `${PRIVATE_KEY_VAR}="${pair.privateKey}"
+`, { mode: 384 });
+  return { ok: true, publicKey: pair.publicKey, parked: true };
+}
+function ignoresKeyFile(root) {
+  const path = join3(root, ".gitignore");
+  if (!existsSync3(path))
+    return false;
+  return readFileSync2(path, "utf8").split(`
+`).map((line) => line.trim()).some((line) => line === LOCAL_KEY_FILE || line === `/${LOCAL_KEY_FILE}` || line === ".env.keys*" || line === ".env*");
 }
 async function keysCommand(project, args) {
   if (args.includes("--rotate"))
@@ -682,7 +764,8 @@ Secrets are encrypted with a public key that is COMMITTED, and read with a`);
   const hasFile = existsSync3(join3(project.root, SECRETS_FILE));
   const publicNote = state.publicKey ? `${state.publicKey.slice(0, 20)}… in ${SECRETS_FILE}` : color2.dim(hasFile ? `${SECRETS_FILE} has no key yet — \`vc link\` makes one` : `no ${SECRETS_FILE} yet — \`vc secrets --init\``);
   console.log(`  ${state.publicKey ? color2.green("✓") : color2.dim("·")} public key   ${publicNote}`);
-  console.log(`  ${state.inGitHub ? color2.green("✓") : color2.red("✗")} private key  ${state.inGitHub ? `${PRIVATE_KEY_VAR} is set on ${state.slug}` : state.slug ? color2.red(`not set on ${state.slug} — \`vc keys --init\``) : color2.dim("no GitHub repository yet")}`);
+  const parked = localPrivateKey(project.root) !== null;
+  console.log(`  ${state.inGitHub || parked ? color2.green("✓") : color2.red("✗")} private key  ${state.inGitHub ? `${PRIVATE_KEY_VAR} is set on ${state.slug}` : parked ? color2.yellow(`waiting in ${LOCAL_KEY_FILE} — \`vc link\` moves it to GitHub and deletes it`) : state.slug ? color2.red(`not set on ${state.slug} — \`vc keys --init\``) : color2.dim("no key yet — `vc keys --init`")}`);
   if (state.mismatch) {
     console.error(`
 ${color2.red("✗")} ${state.mismatch}
@@ -716,7 +799,15 @@ vc: ${made.reason}
   }
   const fresh = !existsSync3(join3(project.root, SECRETS_FILE));
   committedPublicKeyInto(project.root, made.publicKey);
-  console.log(`
+  console.log(made.parked ? `
+${color2.green("✓")} key made; public half in ${SECRETS_FILE}, private half waiting in ${LOCAL_KEY_FILE}
+
+` + color2.yellow(`  ${LOCAL_KEY_FILE} is TEMPORARY. It is gitignored, but it is the one file that
+  opens every secret in this shop. \`vc link\` moves it onto the GitHub
+` + `  repository and deletes it — do that as soon as the repository exists.
+`) + (fresh ? `
+  Next: ${color2.cyan("vc secrets --init")} fills in the keys this shop needs.
+` : "") : `
 ${color2.green("✓")} ${PRIVATE_KEY_VAR} set on ${state.slug}; public key in ${SECRETS_FILE}
 ` + (fresh ? `
   Next: ${color2.cyan("vc secrets --init")} fills in the keys this shop needs.
@@ -794,4 +885,4 @@ ${color2.green("✓")} re-keyed under ${made.publicKey.slice(0, 20)}… and ${PR
   return 0;
 }
 
-export { allEnvKeys, renderEnvTs, renderEnvExample, renderEnvLocal, renderEnvProduction, envSummary, ghAuth, repoSlug, setSecret, secretNames, setVariable, variableNames, verifyCloudflareToken, cloudflareAccounts, committedPublicKey, generateKeypair, publicKeyFor, keyState, provisionKey, keysCommand, SECRETS_FILE, PRIVATE_KEY_VAR, committedPublicKeyInto, declaredSecretNames, plaintextSecretNames, decryptSecrets, secretsCommand, initSecrets };
+export { allEnvKeys, renderEnvTs, renderEnvExample, renderEnvLocal, renderEnvProduction, envSummary, ghAuth, repoSlug, setSecret, secretNames, setVariable, variableNames, verifyCloudflareToken, cloudflareAccounts, LOCAL_KEY_FILE, localPrivateKey, committedPublicKey, generateKeypair, publicKeyFor, keyState, provisionKey, ignoresKeyFile, keysCommand, SECRETS_FILE, PRIVATE_KEY_VAR, run2 as run, committedPublicKeyInto, declaredSecretNames, plaintextSecretNames, plaintextSecretEntries, decryptSecrets, secretsCommand, initSecrets, encryptInto };

package/dist/{index-85m0qkmg.js → index-y6qzjd9h.js}

@@ -9,7 +9,7 @@ import {
   renderEnvLocal,
   renderEnvProduction,
   renderEnvTs
-} from "./index-6w8rwtsh.js";
+} from "./index-j5xjh6qp.js";
 import {
   MANIFEST_FILE,
   has,
@@ -1344,7 +1344,7 @@ import color from "picocolors";
 // package.json
 var package_default = {
   name: "@saastemly/voidcommerce",
-  version: "0.7.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",
@@ -2501,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-85m0qkmg.js";
+} from "./index-y6qzjd9h.js";
 import {
   allEnvKeys,
   envSummary,
@@ -59,7 +59,7 @@ import {
   renderEnvLocal,
   renderEnvProduction,
   renderEnvTs
-} from "./index-6w8rwtsh.js";
+} from "./index-j5xjh6qp.js";
 import {
   LAYOUTS,
   MANIFEST_FILE,

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

@@ -1,19 +1,25 @@
 import {
+  LOCAL_KEY_FILE,
   committedPublicKey,
   generateKeypair,
+  ignoresKeyFile,
   keyState,
   keysCommand,
+  localPrivateKey,
   provisionKey,
   publicKeyFor
-} from "./index-6w8rwtsh.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/package.json

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

package/src/deploy/secrets.ts

@@ -141,6 +141,26 @@ export function plaintextSecretNames(root: string): string[] {
 	return bare;
 }
 
+/**
+ * The declared values that are NOT encrypted, with their values.
+ *
+ * Separate from `plaintextSecretNames` on purpose: names are safe to print
+ * and values never are, so the function that returns values is the one you
+ * have to go looking for.
+ */
+export function plaintextSecretEntries(root: string): Array<{ name: string; value: string }> {
+	const path = join(root, SECRETS_FILE);
+	if (!existsSync(path)) return [];
+	const out: Array<{ name: string; value: string }> = [];
+	for (const line of readFileSync(path, "utf8").split("\n")) {
+		const match = /^\s*([A-Z][A-Z0-9_]*)\s*=\s*(.*)$/.exec(line);
+		if (!match || match[1]!.startsWith("DOTENV_")) continue;
+		const value = match[2]!.trim().replace(/^['"]|['"]$/g, "");
+		if (value && value !== "unset" && !value.startsWith("encrypted:")) out.push({ name: match[1]!, value });
+	}
+	return out;
+}
+
 export interface DecryptedSecrets {
 	/** A temp file in `.env` format, for `wrangler deploy --secrets-file`. */
 	path: string;
@@ -230,6 +250,7 @@ export async function secretsCommand(project: Project, args: string[]): Promise<
 
 	if (args.includes("--init")) return initSecrets(project);
 	if (args[0] === "set") return setSecretValue(project, args.slice(1));
+	if (args.includes("--sync")) return syncSecrets(project);
 
 	if (!existsSync(join(root, SECRETS_FILE))) {
 		console.log(
@@ -446,3 +467,50 @@ function upsertLine(path: string, name: string, value: string): void {
 	const pattern = new RegExp(`^\\s*${name}\\s*=.*$`, "m");
 	writeFileSync(path, pattern.test(body) ? body.replace(pattern, `${name}=${value}`) : `${body.replace(/\n*$/, "\n")}${name}=${value}\n`);
 }
+
+
+/**
+ * `vc secrets --sync` — add the keys this shop needs and does not declare.
+ *
+ * The manifest changes: a carrier is swapped, a plugin is added, and the set
+ * of required secrets moves with it. Without this the only way to declare a
+ * new one is to remember its exact name and type it in by hand, which is how
+ * a shop ends up deploying without a key it needed.
+ *
+ * Strictly additive. It never deletes a key that is no longer required,
+ * because "no longer required" and "safe to throw away" are different
+ * claims — the value may still be wanted, and it is not this command's to
+ * destroy. Extras are reported instead.
+ */
+async function syncSecrets(project: Project): Promise<number> {
+	const root = project.root;
+	const path = join(root, SECRETS_FILE);
+	if (!existsSync(path)) {
+		console.error(`\nvc: no ${SECRETS_FILE} yet. \`vc secrets --init\` writes one.\n`);
+		return 1;
+	}
+	const required = allEnvKeys(project.manifest).filter((key) => !key.plaintext);
+	const declared = declaredSecretNames(root);
+	const missing = required.filter((key) => !declared.has(key.key));
+	const extra = [...declared].filter((name) => !required.some((key) => key.key === name));
+
+	if (missing.length > 0) {
+		const body = readFileSync(path, "utf8").replace(/\n*$/, "\n");
+		const added = missing.flatMap((key) => ["", `# ${key.breaks}${key.where ? ` — from: ${key.where}` : ""}`, `${key.key}=unset`]);
+		writeFileSync(path, `${body}${added.join("\n")}\n`);
+		console.log(`\n${color.green("+")} ${missing.length} key${missing.length === 1 ? "" : "s"} added to ${SECRETS_FILE}, as \`unset\`:\n`);
+		for (const key of missing) console.log(`    ${color.cyan(`vc secrets set ${key.key}`)}  ${color.dim(key.where ?? "")}`);
+		console.log("");
+	} else {
+		console.log(`\n${color.green("✓")} every secret this shop needs is already declared.\n`);
+	}
+
+	if (extra.length > 0) {
+		console.log(
+			`${color.yellow("!")} ${extra.length} declared key${extra.length === 1 ? " is" : "s are"} no longer required by this shop:\n` +
+				`    ${extra.join("\n    ")}\n\n` +
+				color.dim("  Left alone — they cost nothing, and deleting a value you may still want\n  is not this command's call. Remove them by hand when you are sure.\n"),
+		);
+	}
+	return 0;
+}

package/src/generate/index.ts

@@ -374,9 +374,17 @@ async function generateStrictRoot(root: string, manifest: Manifest, result: Gene
 		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,