@saastemly/voidcommerce 0.16.1 → 0.18.0

package/src/deploy/link.ts

@@ -3,7 +3,7 @@ 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 { cloudflareAccounts, getVariable, ghAuth, repoSlug, secretNames, setSecret, setVariable, variableNames, verifyCloudflareToken } from "./github";
 import { LOCAL_KEY_FILE, keyState, localPrivateKey, provisionKey, publicKeyFor } from "./keys";
 import { PRIVATE_KEY_VAR, SECRETS_FILE, committedPublicKeyInto, declaredSecretNames, initSecrets } from "./secrets";
 
@@ -91,17 +91,31 @@ export async function linkCommand(project: Project, args: string[]): Promise<num
 		// 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);
+			const sent = await setVariable(root, PRIVATE_KEY_VAR, parked);
 			if (!sent.ok) {
-				p.cancel(`GitHub refused the secret: ${sent.error ?? "unknown error"}`);
+				p.cancel(`GitHub refused the variable: ${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`);
+
+			// READ IT BACK before deleting the only other copy. "The write
+			// returned success" is not the same claim as "the key can be
+			// recovered", and it is the second one this file is about to bet
+			// the shop on. If it cannot be read, the local copy stays.
+			const readBack = await getVariable(root, PRIVATE_KEY_VAR);
+			if (readBack !== parked) {
+				p.log.warn(
+					`${color.yellow("!")} ${PRIVATE_KEY_VAR} was written to ${slug} but could not be read back,\n` +
+						`  so ${LOCAL_KEY_FILE} has been LEFT IN PLACE. It is currently the only copy\n` +
+						"  of the key that opens this shop — do not delete it until `vc keys --restore` works.",
+				);
+			} else {
+				rmSync(join(root, LOCAL_KEY_FILE), { force: true });
+				p.log.success(
+					`${color.green("✓")} the key moved to ${slug} and ${LOCAL_KEY_FILE} deleted — verified readable, so \`vc keys --restore\` can bring it back`,
+				);
+			}
 		} else {
 			const made = await provisionKey(project);
 			if (!made.ok) {

package/src/deploy/publish.ts

@@ -0,0 +1,145 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import color from "picocolors";
+import type { Project } from "../project";
+import { findGh, ghAuth, repoSlug, run } from "./github";
+import { linkCommand } from "./link";
+
+/**
+ * `vc publish` — make the repository, give it what it needs, push.
+ *
+ * ── Why this exists ──────────────────────────────────────────────────────
+ *
+ * The goal was always "publishing to GitHub is the deploy". `vc link` sat in
+ * front of that as a separate step, and it is worth being exact about what
+ * it was actually for, because two of its three jobs never needed a person:
+ *
+ *   DOTENV_PRIVATE_KEY_SECRETS   vc already holds it — automatic
+ *   CLOUDFLARE_ACCOUNT_ID        it is in the manifest — automatic
+ *   CLOUDFLARE_API_TOKEN         exists only in Cloudflare's dashboard
+ *
+ * Only the third needs a human, and it cannot be removed: there is no OIDC
+ * or workload identity federation from GitHub to the Cloudflare API, so
+ * something has to carry a token across, and only a person can fetch one.
+ * Everything else is ceremony that a command can do.
+ *
+ * So this is the one command. It creates the repository, sets all three,
+ * and pushes — and the push is what deploys. After it, `git push` is the
+ * whole loop forever, and `vc` is only needed to read or change a secret.
+ *
+ * ── The order matters ────────────────────────────────────────────────────
+ *
+ * The repository is created WITHOUT pushing, the credentials go on, and only
+ * then does the push happen. `gh repo create --push` would put main there
+ * first, which starts a deploy against a repository that has no key and no
+ * token — a red run, an email, and a shop that did not deploy, for no
+ * reason other than doing two things in the wrong order.
+ */
+
+export async function publishCommand(project: Project, args: string[]): Promise<number> {
+	const p = await import("@clack/prompts");
+	const root = project.root;
+	const gh = findGh();
+
+	p.intro(color.bgCyan(color.black(" vc publish ")));
+
+	const auth = await ghAuth(root);
+	if (!auth.ok || !gh) {
+		p.cancel(auth.reason ?? "the GitHub CLI is not installed. https://cli.github.com");
+		return 1;
+	}
+	if (!existsSync(join(root, ".git"))) {
+		p.cancel(`${root} is not a git repository. \`git init\` first, and commit what you have.`);
+		return 1;
+	}
+
+	// 1. The repository. Created without pushing: see above.
+	let slug = await repoSlug(root);
+	if (slug) {
+		p.log.info(`${slug} already exists — using it`);
+	} else {
+		const suggested = project.manifest.shop.domain.split(".")[0] ?? "shop";
+		const name = await p.text({
+			message: "Repository name",
+			initialValue: suggested,
+			validate: (value) => (/^[A-Za-z0-9._-]+$/.test(value.trim()) ? undefined : "letters, digits, dot, dash or underscore"),
+		});
+		if (p.isCancel(name)) {
+			p.cancel("nothing was created.");
+			return 1;
+		}
+		// PRIVATE by default and deliberately: the encryption key becomes a
+		// repository variable, so anyone who can read this repository can
+		// decrypt its secrets.
+		const visibility = await p.select({
+			message: "Visibility",
+			options: [
+				{ value: "--private", label: "Private", hint: "the key that opens your secrets is readable to anyone with access" },
+				{ value: "--public", label: "Public", hint: "only if this shop keeps no secrets at all" },
+			],
+			initialValue: "--private",
+		});
+		if (p.isCancel(visibility)) {
+			p.cancel("nothing was created.");
+			return 1;
+		}
+
+		const spinner = p.spinner();
+		spinner.start(`creating ${String(name)}`);
+		const created = await run(gh, ["repo", "create", String(name).trim(), "--source=.", String(visibility)], root);
+		if (created.code !== 0) {
+			spinner.stop(`${color.red("✗")} could not create it`);
+			p.cancel(created.out.trim().split("\n").slice(-2).join(" "));
+			return 1;
+		}
+		slug = await repoSlug(root);
+		spinner.stop(`${color.green("✓")} ${slug ?? String(name)} created, and set as origin`);
+	}
+
+	// 2. The credentials. Two are automatic; one is asked for.
+	p.log.step("giving the repository what the deploy needs");
+	const linked = await linkCommand(project, args);
+	if (linked !== 0) {
+		p.cancel("the repository exists but is not configured, so a push would not deploy. Fix the above and run `vc publish` again.");
+		return 1;
+	}
+
+	// 3. Anything `vc link` wrote — the public key, a fresh .env.secrets, the
+	// pinned account id — has to be IN the push, or the deploy reads a
+	// repository that disagrees with the one on this machine.
+	const dirty = (await run("git", ["status", "--porcelain"], root)).out.trim();
+	if (dirty) {
+		const staged = await run("git", ["add", "-A"], root);
+		const committed = await run("git", ["commit", "-m", "vc publish: link this shop to its repository"], root);
+		if (staged.code !== 0 || committed.code !== 0) {
+			p.cancel(`could not commit the changes vc link made:\n${committed.out.trim().split("\n").slice(-3).join("\n")}`);
+			return 1;
+		}
+		p.log.success(`${color.green("✓")} committed what linking changed`);
+	}
+
+	// 4. Push. This is the deploy.
+	const branch = (await run("git", ["rev-parse", "--abbrev-ref", "HEAD"], root)).out.trim() || "main";
+	const spinner = p.spinner();
+	spinner.start(`pushing ${branch}`);
+	const pushed = await run("git", ["push", "-u", "origin", `${branch}:main`], root);
+	if (pushed.code !== 0) {
+		spinner.stop(`${color.red("✗")} the push failed`);
+		p.cancel(pushed.out.trim().split("\n").slice(-4).join("\n"));
+		return 1;
+	}
+	spinner.stop(`${color.green("✓")} pushed to main`);
+
+	p.outro(
+		[
+			`${color.bold("Published.")} The deploy is running now.`,
+			"",
+			`  ${color.cyan(`https://github.com/${slug}/actions`)}`,
+			"",
+			`  From here ${color.cyan("git push")} is the whole loop. \`vc\` is only needed to`,
+			`  change a secret (${color.cyan("vc secrets set KEY")}) or read one back`,
+			`  (${color.cyan("vc keys --restore")}).`,
+		].join("\n"),
+	);
+	return 0;
+}

package/src/generate/ci.ts

@@ -50,7 +50,7 @@ export function renderDistWorkflow(manifest: Manifest): string {
 # The credentials come from the repository, set once by \`vc link\`:
 #
 #   secrets.CLOUDFLARE_API_TOKEN        deploys, and creates D1 + the queue
-#   secrets.${PRIVATE_KEY_VAR}   opens ${SECRETS_FILE}
+#   vars.${PRIVATE_KEY_VAR}      opens ${SECRETS_FILE} (a VARIABLE, so it can be read back)
 #   vars.CLOUDFLARE_ACCOUNT_ID          which account (an id, not a credential)
 #
 # Nothing here needs a Cloudflare dashboard visit and nothing needs wrangler
@@ -147,16 +147,25 @@ jobs:
     env:
       CLOUDFLARE_API_TOKEN: \${{ secrets.CLOUDFLARE_API_TOKEN }}
       CLOUDFLARE_ACCOUNT_ID: \${{ vars.CLOUDFLARE_ACCOUNT_ID }}
-      ${PRIVATE_KEY_VAR}: \${{ secrets.${PRIVATE_KEY_VAR} }}
+      ${PRIVATE_KEY_VAR}: \${{ vars.${PRIVATE_KEY_VAR} }}
     steps:
       - uses: actions/checkout@v6
       - uses: oven-sh/setup-bun@v2
 
       # Checked before anything is built, so a repository that was never
       # linked says so in five seconds rather than four minutes.
+      #
+      # And ${PRIVATE_KEY_VAR} is masked here, first thing. It is a
+      # VARIABLE rather than a secret so that a human can read it back —
+      # that is what makes a new laptop or a second person possible — but
+      # GitHub only masks SECRETS in logs automatically. Registering it with
+      # ::add-mask:: buys back the redaction without giving up recovery.
       - name: Are the credentials here?
         run: |
           set -euo pipefail
+          if [ -n "\${${PRIVATE_KEY_VAR}:-}" ]; then
+            echo "::add-mask::\${${PRIVATE_KEY_VAR}}"
+          fi
           missing=""
           [ -n "\${CLOUDFLARE_API_TOKEN:-}" ] || missing="$missing CLOUDFLARE_API_TOKEN"
           [ -n "\${${PRIVATE_KEY_VAR}:-}" ] || missing="$missing ${PRIVATE_KEY_VAR}"
@@ -219,18 +228,25 @@ You do not need wrangler on your machine, and you do not need to be logged
 into it. You do not need to open the Cloudflare dashboard after the one step
 below.
 
-## Once, before the first push
+## Once, to start
 
 \`\`\`sh
-gh repo create --source=. --private --push   # if there is no repo yet
-vc link
+vc publish
 \`\`\`
 
-\`vc link\` does three things and stores all of them on the GitHub repository:
+One command: it creates the repository, gives it what the deploy needs, and
+pushes — and the push is the deploy. After it, \`git push\` is the whole loop.
+
+Two of the three things it sets need nothing from you. The encryption key vc
+already holds; the account id is in \`voidcommerce.json\`. It asks only for a
+Cloudflare API token, because there is no OIDC between GitHub and Cloudflare
+and only a person can fetch one from the dashboard.
+
+It stores three things on the GitHub repository:
 
 | what | where | why |
 |---|---|---|
-| \`${PRIVATE_KEY_VAR}\` | repository **secret** | opens \`${SECRETS_FILE}\`. Generated by \`vc link\`, never written to disk |
+| \`${PRIVATE_KEY_VAR}\` | repository **variable** | opens \`${SECRETS_FILE}\`. A variable, not a secret, so you can get it back — see below |
 | \`CLOUDFLARE_API_TOKEN\` | repository **secret** | deploys, and creates D1 and the queue |
 | \`CLOUDFLARE_ACCOUNT_ID\` | repository **variable** | which account. An identifier, not a credential |
 
@@ -278,6 +294,24 @@ vc secrets set STRIPE_SECRET_KEY     # prompts; never touches your shell history
 vc secrets                           # what is set, what is missing
 \`\`\`
 
+### Getting the key back
+
+\`\`\`sh
+vc keys --restore
+\`\`\`
+
+\`${PRIVATE_KEY_VAR}\` is a repository **variable**, not a secret. GitHub
+secrets are write-only — \`gh secret\` has no read command — so a key kept
+there is gone the moment your local copy is, and with it every value in
+\`${SECRETS_FILE}\`. As a variable it can be read back, which is what makes a
+new laptop, a rebuild, or a second person possible at all.
+
+**That means anyone who can read this repository can decrypt its secrets.**
+Keep it private. It is also the answer to sharing: a colleague who is a
+collaborator can run \`vc keys --restore\` and work; removing them removes
+their access. The deploy workflow masks the value with \`::add-mask::\` the
+moment it reads it, because GitHub does not mask variables on its own.
+
 **This needs no credential.** dotenvx is asymmetric: encryption uses the public
 key committed at the top of the file, so anyone with a clone can set or rotate
 a secret. Nobody with a clone can read one. Only the deploy decrypts, with the
@@ -302,7 +336,7 @@ The same thing, from a checkout, if CI is ever not the answer:
 
 \`\`\`sh
 export CLOUDFLARE_API_TOKEN=…
-export ${PRIVATE_KEY_VAR}=…        # only if you kept a copy
+export ${PRIVATE_KEY_VAR}=…        # or run \`vc keys --restore\` first
 vc deploy --cloudflare --provision
 \`\`\`