@saastemly/voidcommerce 0.4.0 → 0.6.0

package/dist/cli.js

@@ -1,13 +1,10 @@
 import {
-  PRIVATE_KEY_VAR,
-  SECRETS_FILE,
   box,
   captureVoid,
   deployCloudflare,
   distCommand,
   distHelp,
   ensureGenerated,
-  envSummary,
   findProject,
   finishStrict,
   fullHelp,
@@ -16,31 +13,182 @@ import {
   importHelp,
   initHelp,
   isVoidApp,
-  keysCommand,
   line,
-  plaintextSecretNames,
   preflight,
   printPreflight,
   row,
   runInherit,
   runVoid,
-  secretsCommand,
   version,
   voidAppsIn
-} from "./index-yzezvy5h.js";
+} from "./index-f1wds190.js";
+import {
+  PRIVATE_KEY_VAR,
+  SECRETS_FILE,
+  cloudflareAccounts,
+  committedPublicKeyInto,
+  declaredSecretNames,
+  envSummary,
+  ghAuth,
+  initSecrets,
+  keyState,
+  keysCommand,
+  plaintextSecretNames,
+  provisionKey,
+  repoSlug,
+  secretNames,
+  secretsCommand,
+  setSecret,
+  setVariable,
+  variableNames,
+  verifyCloudflareToken
+} from "./index-2qt2yh3z.js";
 import {
   LAYOUTS,
+  oneOrigin,
   readManifest,
   validate,
+  writeManifest,
   zoneOf
-} from "./index-pz6m2hkm.js";
+} from "./index-xx5p4b8d.js";
 import {
   GROUPS
 } from "./index-844b3qn9.js";
-import"./index-0v6na3yp.js";
+import {
+  __require
+} from "./index-0v6na3yp.js";
 
 // src/deploy/index.ts
+import color2 from "picocolors";
+
+// src/deploy/link.ts
 import color from "picocolors";
+var TOKEN_SECRET = "CLOUDFLARE_API_TOKEN";
+var ACCOUNT_VAR = "CLOUDFLARE_ACCOUNT_ID";
+var SCOPES = [
+  ["Account · Workers Scripts: Edit", "deploy the worker"],
+  ["Account · D1: Edit", "create the database and apply migrations"],
+  ["Account · Queues: Edit", "create the order queue"],
+  ["Account · Workers KV Storage: Edit", "sessions and caches"],
+  ["Account · Workers R2 Storage: Edit", "product images"],
+  ["Account · Account Settings: Read", "confirm which account this is"],
+  ["Zone · Workers Routes: Edit", "answer on your domain"],
+  ["User · User Details: Read", "wrangler asks at startup"]
+];
+async function linkCommand(project, args) {
+  const p = await import("@clack/prompts");
+  const root = project.root;
+  const relink = args.includes("--force");
+  p.intro(color.bgCyan(color.black(" vc link ")));
+  const auth = await ghAuth(root);
+  if (!auth.ok) {
+    p.cancel(auth.reason ?? "gh is unavailable");
+    return 1;
+  }
+  const slug = await repoSlug(root);
+  if (!slug) {
+    p.cancel(`this checkout has no GitHub repository, and everything below is stored on one.
+
+    ${color.cyan("gh repo create --source=. --private --push")}
+
+  then run \`vc link\` again.`);
+    return 1;
+  }
+  p.log.success(`${color.green("✓")} ${slug}, as ${auth.user ?? "you"}`);
+  const keys = await keyState(project);
+  if (keys.inGitHub && !relink) {
+    p.log.info(`${PRIVATE_KEY_VAR} is already set — leaving it alone (--force replaces it, which orphans ${SECRETS_FILE})`);
+  } else if (keys.inGitHub && relink) {
+    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;
+    }
+    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) {
+    p.log.info(`${TOKEN_SECRET} is already set — pass --force to replace it`);
+  } else {
+    p.log.step(`A Cloudflare API token, from ${color.cyan("https://dash.cloudflare.com/profile/api-tokens")} → Create Token → Custom token`);
+    console.log(SCOPES.map(([scope, why]) => `      ${scope.padEnd(38)} ${color.dim(why)}`).join(`
+`));
+    console.log(color.dim(`
+      The token Cloudflare generates for its own Workers Builds will NOT do:
+      it has no D1 and no Queues permission, so it cannot create the database.
+`));
+    const token = await p.password({
+      message: "Paste it (nothing is written to disk)",
+      validate: (input) => input && input.length >= 20 ? undefined : "that is too short to be a Cloudflare token"
+    });
+    if (p.isCancel(token)) {
+      p.cancel("nothing was stored.");
+      return 1;
+    }
+    const spinner = p.spinner();
+    spinner.start("asking Cloudflare whether that token is real");
+    const verified = await verifyCloudflareToken(String(token));
+    if (!verified.ok) {
+      spinner.stop(`${color.red("✗")} Cloudflare rejected it: ${verified.detail}`);
+      p.cancel("nothing was stored.");
+      return 1;
+    }
+    const accounts = await cloudflareAccounts(String(token));
+    spinner.stop(`${color.green("✓")} the token is active and sees ${accounts.length} account${accounts.length === 1 ? "" : "s"}`);
+    let accountId = project.manifest.cloudflare?.accountId ?? "";
+    if (accounts.length === 1) {
+      accountId = accounts[0].id;
+      p.log.info(`account "${accounts[0].name}"`);
+    } else if (accounts.length > 1) {
+      const picked = await p.select({
+        message: "Which account is this shop in?",
+        options: accounts.map((account) => ({ value: account.id, label: account.name, hint: account.id }))
+      });
+      if (p.isCancel(picked)) {
+        p.cancel("nothing was stored.");
+        return 1;
+      }
+      accountId = String(picked);
+    }
+    const stored = await setSecret(root, TOKEN_SECRET, String(token));
+    if (!stored.ok) {
+      p.cancel(`GitHub refused the secret: ${stored.error ?? "unknown error"}`);
+      return 1;
+    }
+    p.log.success(`${color.green("✓")} ${TOKEN_SECRET} stored on ${slug}`);
+    if (accountId) {
+      const varred = await setVariable(root, ACCOUNT_VAR, accountId);
+      if (varred.ok)
+        p.log.success(`${color.green("✓")} ${ACCOUNT_VAR} set as a repository variable`);
+      project.manifest.cloudflare = { ...project.manifest.cloudflare, accountId };
+      await writeManifest(root, project.manifest);
+    }
+  }
+  if (declaredSecretNames(root).size === 0) {
+    p.log.step(`writing ${SECRETS_FILE}`);
+    await initSecrets(project);
+  }
+  const secrets = await secretNames(root);
+  const vars = await variableNames(root);
+  p.outro([
+    `${color.bold("Ready.")} From here, ${color.cyan("git push")} is the deploy.`,
+    "",
+    `  ${secrets.has(PRIVATE_KEY_VAR) ? color.green("✓") : color.red("✗")} ${PRIVATE_KEY_VAR}   ${color.dim("reads the shop's secrets")}`,
+    `  ${secrets.has(TOKEN_SECRET) ? color.green("✓") : color.red("✗")} ${TOKEN_SECRET}      ${color.dim("deploys to Cloudflare")}`,
+    `  ${vars.has(ACCOUNT_VAR) ? color.green("✓") : color.dim("·")} ${ACCOUNT_VAR}     ${color.dim("which account")}`,
+    "",
+    `  Set the shop's own secrets with ${color.cyan("vc secrets set KEY")} — that needs no`,
+    `  credential at all, because encryption uses the public key in the repository.`
+  ].join(`
+`));
+  return 0;
+}
+
+// src/deploy/index.ts
 async function deployCommand(args) {
   const own = new Set(["--cloudflare", "--provision", "--force"]);
   const cloudflare = args.includes("--cloudflare");
@@ -63,12 +211,12 @@ async function deployCommand(args) {
   const check = await preflight(project, "void");
   printPreflight(project, check, "void");
   if (!check.ready && check.remote !== null && !args.includes("--force")) {
-    console.error(`${color.red("✗")} refusing to deploy a shop that is not ready for customers. Fix the above, or pass --force.
+    console.error(`${color2.red("✗")} refusing to deploy a shop that is not ready for customers. Fix the above, or pass --force.
 `);
     return 1;
   }
   if (!check.ready && check.remote === null) {
-    console.log(color.dim(`Secrets could not be verified here; void's own deploy gate is the next check.
+    console.log(color2.dim(`Secrets could not be verified here; void's own deploy gate is the next check.
 `));
   }
   return runVoid(["deploy", ...voids], project.appDir);
@@ -91,15 +239,18 @@ async function deployHelp() {
     line("vc's preflight — every required key set, the hostnames right — then", width),
     line("void deploy, untouched. Or, with --cloudflare, your own account via wrangler.", width),
     line("", width),
-    line(color.bold("Usage"), width),
+    line(color2.bold("Usage"), width),
     ...row("vc deploy [void's flags]", "preflight, then void deploy — the Void platform, void's login", width, 2),
     ...row("vc deploy --cloudflare", "wrangler, your Cloudflare account, no Void login: preflight, build, scrub baked secrets, migrate D1, deploy", width, 2),
     ...row("vc deploy --cloudflare --provision", "first time: create the D1 database and the queue, record them", width, 2),
     ...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)
+    line(color2.bold("Needs, for --cloudflare"), width),
+    ...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*$/, `
@@ -133,14 +284,16 @@ async function secretsHelp() {
     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),
@@ -154,23 +307,27 @@ async function keysCliCommand(args) {
     console.error("vc: no voidcommerce.json here.");
     return 1;
   }
-  return keysCommand(project.manifest, project.root, args);
+  return keysCommand(project, args);
 }
 async function keysHelp() {
   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;
 }
@@ -182,28 +339,60 @@ async function guardCommand() {
   if (bare.length === 0)
     return 0;
   console.error(`
-${color.red("✗ refusing the commit")}: ${bare.length} value${bare.length === 1 ? "" : "s"} in ${SECRETS_FILE} ${bare.length === 1 ? "is" : "are"} not encrypted.
+${color2.red("✗ refusing the commit")}: ${bare.length} value${bare.length === 1 ? "" : "s"} in ${SECRETS_FILE} ${bare.length === 1 ? "is" : "are"} not encrypted.
 
 ` + `    ${bare.join(`
     `)}
 
 ` + `  bunx dotenvx encrypt -f ${SECRETS_FILE}
 
-` + color.dim(`  Committing a secret in the clear cannot be undone by a later commit;
+` + 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;
 }
+async function linkCliCommand(args) {
+  const project = await findProject();
+  if (!project) {
+    console.error("vc: no voidcommerce.json here.");
+    return 1;
+  }
+  return linkCommand(project, args);
+}
+async function linkHelp() {
+  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(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),
+    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)
+  ], width));
+  return 0;
+}
 
 // src/init.ts
 import * as p2 from "@clack/prompts";
 import { mkdir } from "node:fs/promises";
 import { basename, join } from "node:path";
-import color3 from "picocolors";
+import color4 from "picocolors";
 
 // src/wizard.ts
 import * as p from "@clack/prompts";
-import color2 from "picocolors";
+import color3 from "picocolors";
 var bail = () => {
   p.cancel("Nothing was written.");
   process.exit(0);
@@ -225,8 +414,8 @@ async function askGroup(group2, previous, alsoRequired = []) {
   const required = group2.choices.filter((choice) => requiredIds.has(choice.id));
   const optional = group2.choices.filter((choice) => !requiredIds.has(choice.id));
   const message = group2.title + (group2.intro ? `
-${color2.dim(group2.intro)}` : "") + (required.length ? `
-${color2.dim(`Included: ${required.map((choice) => choice.label).join(", ")}`)}` : "");
+${color3.dim(group2.intro)}` : "") + (required.length ? `
+${color3.dim(`Included: ${required.map((choice) => choice.label).join(", ")}`)}` : "");
   if (optional.length === 0) {
     p.log.info(message);
     return required.map((choice) => choice.id);
@@ -248,6 +437,7 @@ ${color2.dim(`Included: ${required.map((choice) => choice.label).join(", ")}`)}`
 async function runWizard(existing, layout) {
   const monorepo = layout === "monorepo";
   const frontend = layout !== "app";
+  const onPages = !oneOrigin(layout);
   const shop = unwrap(await p.group({
     name: () => p.text({
       message: "Shop name",
@@ -256,7 +446,7 @@ async function runWizard(existing, layout) {
       validate: (value) => value.trim() ? undefined : "A shop has a name."
     }),
     domain: () => p.text({
-      message: `Domain ${color2.dim(monorepo ? "— the storefront; api.<domain> is the worker; the CORS list and DNS records derive from it" : "— the shop answers here; the worker's custom domain")}`,
+      message: `Domain ${color3.dim(monorepo ? "— the storefront; api.<domain> is the worker; the CORS list and DNS records derive from it" : "— the shop answers here; the worker's custom domain")}`,
       placeholder: "northwind.com",
       initialValue: existing?.shop.domain ?? "",
       validate: (value) => /^[a-z0-9-]+(\.[a-z0-9-]+)+\.[a-z]{2,}$|^[a-z0-9-]+\.[a-z]{2,}$/i.test(value.trim()) ? undefined : "A hostname, like northwind.com or shop.northwind.com."
@@ -267,7 +457,7 @@ async function runWizard(existing, layout) {
       if (!domain || domain === guess)
         return Promise.resolve(undefined);
       return p.text({
-        message: `DNS zone ${color2.dim(`— ${domain} lives inside it; records go here, and this zone must be on your DNS provider`)}`,
+        message: `DNS zone ${color3.dim(`— ${domain} lives inside it; records go here, and this zone must be on your DNS provider`)}`,
         placeholder: guess,
         initialValue: existing?.shop.zone ?? guess,
         validate: (value) => {
@@ -279,13 +469,13 @@ async function runWizard(existing, layout) {
       });
     },
     country: () => p.text({
-      message: `Country ${color2.dim("— sets the declared VAT rate and the default region")}`,
+      message: `Country ${color3.dim("— sets the declared VAT rate and the default region")}`,
       placeholder: "US",
       initialValue: existing?.shop.country ?? "",
       validate: (value) => /^[A-Za-z]{2}$/.test(value.trim()) ? undefined : "ISO-3166 alpha-2, like DK."
     }),
     taxRegistered: () => p.select({
-      message: `Registered to charge tax? ${color2.dim("— a business below its registration threshold must NOT add tax to a price, and one above it must")}`,
+      message: `Registered to charge tax? ${color3.dim("— a business below its registration threshold must NOT add tax to a price, and one above it must")}`,
       options: [
         { value: "no", label: "Not registered", hint: "prices are what the customer pays; no tax is added. The common case for a new shop" },
         { value: "yes", label: "Registered", hint: "the country's standard rate is declared and added" }
@@ -299,14 +489,14 @@ async function runWizard(existing, layout) {
       validate: (value) => /^[A-Za-z]{3}$/.test(value.trim()) ? undefined : "ISO-4217, like dkk."
     }),
     locale: () => p.text({
-      message: `Locale ${color2.dim("— the language of emails and launch content")}`,
+      message: `Locale ${color3.dim("— the language of emails and launch content")}`,
       placeholder: "en",
       initialValue: existing?.shop.locale ?? "",
       validate: (value) => /^[a-z]{2}(-[A-Z]{2})?$/.test(value.trim()) ? undefined : "like da, or en-GB."
     }),
-    ...frontend ? {
+    ...onPages ? {
       pagesHost: () => p.text({
-        message: `GitHub Pages host ${color2.dim("— where the storefront is published; leave blank if you serve the branch elsewhere")}`,
+        message: `GitHub Pages host ${color3.dim("— where the storefront is published; leave blank if you serve the branch elsewhere")}`,
         placeholder: "northwind.github.io",
         initialValue: existing?.shop.pagesHost ?? "",
         validate: (value) => !value.trim() || /^[a-z0-9-]+\.github\.io$/i.test(value.trim()) ? undefined : "<owner>.github.io, or blank"
@@ -317,7 +507,7 @@ async function runWizard(existing, layout) {
   for (const group2 of GROUPS) {
     if (group2.id === "ui" && layout === "strict") {
       p.log.info(`${group2.title}
-${color2.dim("The generated storefront and panel. Strict has no custom code to host anything else.")}`);
+${color3.dim("The generated storefront and panel. Strict has no custom code to host anything else.")}`);
       chosen[group2.id] = ["admin"];
       continue;
     }
@@ -335,21 +525,21 @@ ${color2.dim("The generated storefront and panel. Strict has no custom code to h
       locale: shop.locale.trim(),
       taxRegistered: shop.taxRegistered === "yes",
       zone: shop.zone?.trim().toLowerCase() || undefined,
-      pagesHost: frontend ? shop.pagesHost?.trim().toLowerCase() || undefined : undefined
+      pagesHost: onPages ? shop.pagesHost?.trim().toLowerCase() || undefined : undefined
     },
     chosen
   };
 }
 function summarise(manifest) {
   const lines = [
-    `${color2.dim("Layout".padEnd(34))} ${LAYOUTS.find((l) => l.id === manifest.layout)?.label ?? manifest.layout}`
+    `${color3.dim("Layout".padEnd(34))} ${LAYOUTS.find((l) => l.id === manifest.layout)?.label ?? manifest.layout}`
   ];
   for (const group2 of GROUPS) {
     const ids = manifest.chosen[group2.id] ?? [];
     if (ids.length === 0)
       continue;
     const labels = ids.map((id) => group2.choices.find((choice) => choice.id === id)?.label ?? id).join(", ");
-    lines.push(`${color2.dim(group2.title.padEnd(34))} ${labels}`);
+    lines.push(`${color3.dim(group2.title.padEnd(34))} ${labels}`);
   }
   return lines.join(`
 `);
@@ -390,10 +580,10 @@ async function init(args) {
   if (flags.voids.length > 0)
     return runVoid(["init", ...flags.voids]);
   let root = process.cwd();
-  p2.intro(color3.bgCyan(color3.black(" voidcommerce ")));
+  p2.intro(color4.bgCyan(color4.black(" voidcommerce ")));
   const existing = await readManifest(root);
   if (existing) {
-    p2.log.info(`Found ${color3.cyan("voidcommerce.json")} for ${color3.bold(existing.shop.name)} — answers are pre-filled; the layout (${existing.layout}) is fixed.`);
+    p2.log.info(`Found ${color4.cyan("voidcommerce.json")} for ${color4.bold(existing.shop.name)} — answers are pre-filled; the layout (${existing.layout}) is fixed.`);
     if (flags.layout && flags.layout !== existing.layout) {
       p2.log.error(`This shop is laid out as "${existing.layout}". The layout cannot change after init — moving files is not a regeneration.`);
       return 1;
@@ -401,10 +591,10 @@ async function init(args) {
   }
   const layout = existing?.layout ?? flags.layout ?? await askLayout();
   if (layout === "strict") {
-    p2.log.step(`Strict: the app will be generated under ${color3.cyan(".vc/app")} — nothing there is yours to edit.`);
+    p2.log.step(`Strict: the app will be generated under ${color4.cyan(".vc/app")} — nothing there is yours to edit.`);
   } else if (layout === "app") {
     if (!isVoidApp(root)) {
-      p2.log.step(`No Void app here yet — ${color3.cyan("void init")} first, then the shop.`);
+      p2.log.step(`No Void app here yet — ${color4.cyan("void init")} first, then the shop.`);
       const before = new Set(voidAppsIn(root));
       const code = await runVoid(["init"]);
       if (code !== 0)
@@ -417,20 +607,20 @@ async function init(args) {
         }
         root = created[0];
         process.chdir(root);
-        p2.log.step(`Continuing in ${color3.cyan(`${basename(root)}/`)}`);
+        p2.log.step(`Continuing in ${color4.cyan(`${basename(root)}/`)}`);
       }
     }
   } else {
     const parts = [
       ["api", "the D1 starter — this is the worker"],
-      ["frontend", "Static Pages — this is prerendered for GitHub Pages"]
+      ["frontend", "the storefront — prerendered and served from the worker's own assets"]
     ];
     for (const [dir, starter] of parts) {
       const target = join(root, dir);
       if (isVoidApp(target))
         continue;
       await mkdir(target, { recursive: true });
-      p2.log.step(`${color3.cyan("void init")} in ${color3.cyan(`${dir}/`)} — choose ${starter}.`);
+      p2.log.step(`${color4.cyan("void init")} in ${color4.cyan(`${dir}/`)} — choose ${starter}.`);
       const code = await runVoid(["init"], target);
       if (code !== 0)
         return code;
@@ -448,7 +638,7 @@ async function init(args) {
   if (problems.length > 0) {
     p2.log.error("These answers contradict each other:");
     for (const problem of problems)
-      p2.log.message(`  ${color3.red("✗")} ${problem}`);
+      p2.log.message(`  ${color4.red("✗")} ${problem}`);
     p2.cancel("Nothing was written.");
     return 1;
   }
@@ -464,15 +654,16 @@ async function init(args) {
   spinner2.stop("Generated");
   const { secrets, plaintext } = envSummary(manifest);
   p2.note([
-    ...result.written.map((file) => `${color3.green("+")} ${file}`),
-    ...result.kept.map((file) => `${color3.dim("=")} ${file} ${color3.dim("(kept — yours)")}`)
+    ...result.written.map((file) => `${color4.green("+")} ${file}`),
+    ...result.kept.map((file) => `${color4.dim("=")} ${file} ${color4.dim("(kept — yours)")}`),
+    ...result.retired.map((file) => `${color4.red("-")} ${file} ${color4.dim("(retired — no longer generated)")}`)
   ].join(`
 `), "Files");
   p2.note([
-    `${color3.bold(String(secrets.length))} secrets  ${color3.dim("→ wrangler secret put <NAME>")}`,
+    `${color4.bold(String(secrets.length))} secrets  ${color4.dim("→ wrangler secret put <NAME>")}`,
     ...secrets.map((key) => `  ${key}`),
     "",
-    `${color3.bold(String(plaintext.length))} plaintext ${color3.dim("→ .env.production, already written")}`,
+    `${color4.bold(String(plaintext.length))} plaintext ${color4.dim("→ .env.production, already written")}`,
     ...plaintext.map((key) => `  ${key}`)
   ].join(`
 `), "Before going live");
@@ -482,21 +673,21 @@ async function init(args) {
       return code;
   }
   const next = layout === "app" ? [
-    `  ${color3.cyan("bun install")}`,
-    `  ${color3.cyan("bun run maildev")}      ${color3.dim("local inbox at http://localhost:1080")}`,
-    `  ${color3.cyan("vc dev")}`,
-    `  ${color3.cyan("vc preflight")}        ${color3.dim("what is still missing, and why it matters")}`
+    `  ${color4.cyan("bun install")}`,
+    `  ${color4.cyan("bun run maildev")}      ${color4.dim("local inbox at http://localhost:1080")}`,
+    `  ${color4.cyan("vc dev")}`,
+    `  ${color4.cyan("vc preflight")}        ${color4.dim("what is still missing, and why it matters")}`
   ] : layout === "strict" ? [
-    `  ${color3.cyan("bun install")}`,
-    `  ${color3.cyan("vc generate")}         ${color3.dim("the app under .vc/app, void's artifacts, the migrations")}`,
-    `  ${color3.cyan("bun run maildev")}      ${color3.dim("local inbox at http://localhost:1080")}`,
-    `  ${color3.cyan("vc dev")}               ${color3.dim("runs in .vc/app")}`
+    `  ${color4.cyan("bun install")}`,
+    `  ${color4.cyan("vc generate")}         ${color4.dim("the app under .vc/app, void's artifacts, the migrations")}`,
+    `  ${color4.cyan("bun run maildev")}      ${color4.dim("local inbox at http://localhost:1080")}`,
+    `  ${color4.cyan("vc dev")}               ${color4.dim("runs in .vc/app")}`
   ] : [
-    `  ${color3.cyan("bun install")}          ${color3.dim("one install for both workspaces")}`,
-    `  ${color3.cyan("bun run maildev")}      ${color3.dim("local inbox at http://localhost:1080")}`,
-    `  ${color3.cyan("bun run dev:api")}      ${color3.dim("the worker, with the panel")}`,
-    `  ${color3.cyan("bun run dev:frontend")} ${color3.dim("the storefront, against the local API")}`,
-    `  ${color3.cyan("bun run preflight")}    ${color3.dim("what is still missing, and why it matters")}`
+    `  ${color4.cyan("bun install")}          ${color4.dim("one install for both workspaces")}`,
+    `  ${color4.cyan("bun run maildev")}      ${color4.dim("local inbox at http://localhost:1080")}`,
+    `  ${color4.cyan("bun run dev:api")}      ${color4.dim("the worker, with the panel")}`,
+    `  ${color4.cyan("bun run dev:frontend")} ${color4.dim("the storefront, against the local API")}`,
+    `  ${color4.cyan("bun run preflight")}    ${color4.dim("what is still missing, and why it matters")}`
   ];
   p2.outro(["Next:", ...next].join(`
 `));
@@ -505,7 +696,7 @@ async function init(args) {
 
 // src/regenerate.ts
 import * as p3 from "@clack/prompts";
-import color4 from "picocolors";
+import color5 from "picocolors";
 async function generateCommand() {
   const project = await findProject();
   if (!project) {
@@ -521,8 +712,9 @@ async function generateCommand() {
   }
   const result = await generate(project.root, project.manifest);
   p3.log.step([
-    ...result.written.map((file) => `${color4.green("+")} ${file}`),
-    ...result.kept.map((file) => `${color4.dim("=")} ${file} ${color4.dim("(kept)")}`)
+    ...result.written.map((file) => `${color5.green("+")} ${file}`),
+    ...result.kept.map((file) => `${color5.dim("=")} ${file} ${color5.dim("(kept)")}`),
+    ...result.retired.map((file) => `${color5.red("-")} ${file} ${color5.dim("(retired — no longer generated)")}`)
   ].join(`
 `));
   return project.manifest.layout === "strict" ? finishStrict(project.root) : 0;
@@ -587,6 +779,7 @@ var EXTENDED = {
   preflight: { run: preflightCommand, help: preflightHelp },
   secrets: { run: secretsCliCommand, help: secretsHelp },
   keys: { run: keysCliCommand, help: keysHelp },
+  link: { run: linkCliCommand, help: linkHelp },
   guard: { run: guardCommand, help: async () => guardCommand() },
   dev: { run: appScript("dev"), help: appScriptHelp("dev") },
   build: { run: appScript("build"), help: appScriptHelp("build") },