@saastemly/voidcommerce 0.19.1 → 0.21.0

package/src/deploy/teardown.ts

@@ -0,0 +1,169 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import color from "picocolors";
+import { writeManifest, workerHosts } from "../manifest";
+import type { Project } from "../project";
+import { parseJsonc, upsertJsonc } from "./jsonc";
+import { SECRETS_FILE, secretValue } from "./secrets";
+import { findWrangler, wrangler } from "./wrangler";
+
+/**
+ * `vc teardown --cloudflare` — undo a deploy, so the whole thing can be
+ * proved again from nothing.
+ *
+ * ── Why this exists ──────────────────────────────────────────────────────
+ *
+ * "Push and it goes live" is a claim, and a claim nobody can re-run is a
+ * story. Provisioning is the part most likely to break — it is the only
+ * step that creates rather than replaces, it runs once per shop, and it runs
+ * against an account whose state nobody controls. Being able to destroy and
+ * do it again is what turns the claim into something testable.
+ *
+ * ── This DELETES A PRODUCTION DATABASE ───────────────────────────────────
+ *
+ * D1 deletion is not recoverable: there is no undo and no snapshot unless
+ * one was taken. Every order, customer and address in it goes. So this
+ * refuses by default, and the confirmation is TYPING THE SHOP'S DOMAIN —
+ * not `y`, because `y` is muscle memory and a domain is not.
+ *
+ * It also refuses outright when the manifest's domain does not match what
+ * the wrangler config points at, since that mismatch is the signal that you
+ * are standing in a different shop than you think.
+ *
+ * ── Idempotent, deliberately ─────────────────────────────────────────────
+ *
+ * Deleting what is already gone is success, not failure. That is what makes
+ * it usable in a loop: teardown, publish, teardown again, without a human
+ * reading each result to decide whether the next step is safe.
+ */
+
+export interface TeardownOptions {
+	/** Required. Without it this only ever prints what it would do. */
+	confirm: boolean;
+	/** Keep the D1 database — the one thing that holds data nobody can recreate. */
+	keepData: boolean;
+	dryRun: boolean;
+}
+
+interface WranglerConfig {
+	name?: string;
+	account_id?: string;
+	d1_databases?: Array<{ binding: string; database_name: string; database_id: string }>;
+	queues?: { producers?: Array<{ queue: string }>; consumers?: Array<{ queue: string }> };
+}
+
+const fail = (message: string): number => {
+	console.error(`\n${color.red("✗")} ${message}\n`);
+	return 1;
+};
+
+/** What a teardown would destroy, read from the config rather than guessed. */
+export function teardownPlan(config: WranglerConfig, fallbackWorker: string): { worker: string; d1: string | null; queues: string[] } {
+	const queues = new Set<string>();
+	for (const producer of config.queues?.producers ?? []) if (producer.queue) queues.add(producer.queue);
+	for (const consumer of config.queues?.consumers ?? []) if (consumer.queue) queues.add(consumer.queue);
+	const d1 = config.d1_databases?.find((db) => db.binding === "DB");
+	return {
+		worker: config.name || fallbackWorker,
+		d1: d1?.database_name && d1.database_id !== "local" ? d1.database_name : null,
+		queues: [...queues],
+	};
+}
+
+export async function teardownCloudflare(project: Project, opts: TeardownOptions): Promise<number> {
+	const app = project.appDir;
+	const configPath = join(app, "wrangler.jsonc");
+	if (!existsSync(configPath)) return fail("wrangler.jsonc is missing — there is nothing here to tear down.");
+
+	// Credentials come from the repository, exactly as the deploy takes them.
+	if (!process.env["CLOUDFLARE_API_TOKEN"]) {
+		const token = await secretValue(project, "CLOUDFLARE_API_TOKEN");
+		if (token) process.env["CLOUDFLARE_API_TOKEN"] = token;
+	}
+	if (!process.env["CLOUDFLARE_ACCOUNT_ID"]) {
+		const account = await secretValue(project, "CLOUDFLARE_ACCOUNT_ID");
+		if (account) process.env["CLOUDFLARE_ACCOUNT_ID"] = account;
+	}
+
+	const bin = findWrangler(app);
+	if (!bin) return fail("wrangler is not installed. `bun add -d wrangler`.");
+
+	const config = parseJsonc<WranglerConfig>(readFileSync(configPath, "utf8"));
+	const plan = teardownPlan(config, project.manifest.shop.domain.split(".")[0]!);
+	const host = workerHosts(project.manifest)[0] ?? project.manifest.shop.domain;
+
+	console.log(`\n${color.bold("This will destroy, on Cloudflare:")}\n`);
+	console.log(`  worker    ${plan.worker}   ${color.dim(`(and its custom domain ${host})`)}`);
+	console.log(
+		plan.d1
+			? `  database  ${plan.d1}   ${opts.keepData ? color.green("KEPT — --keep-data") : color.red("DELETED, with every order in it")}`
+			: `  database  ${color.dim("none recorded")}`,
+	);
+	console.log(plan.queues.length ? `  queues    ${plan.queues.join(", ")}` : `  queues    ${color.dim("none recorded")}`);
+	console.log("");
+
+	if (opts.dryRun) {
+		console.log(color.dim("--dry-run: nothing was touched.\n"));
+		return 0;
+	}
+
+	if (!opts.confirm) {
+		return fail(
+			`refusing to destroy anything without --confirm.\n` +
+				`  This is not reversible: D1 has no undo, and the orders go with it.\n\n` +
+				`  ${color.cyan(`vc teardown --cloudflare --confirm ${project.manifest.shop.domain}`)}`,
+		);
+	}
+
+	/**
+	 * Order matters. The worker goes FIRST: while it is live it serves
+	 * customers, and a shop that answers with a database that no longer
+	 * exists is worse than a shop that does not answer.
+	 */
+	console.log(`▸ wrangler delete (${plan.worker})`);
+	const deleted = await wrangler(bin, ["delete", "--name", plan.worker, "--force"], app, true);
+	// "not found" is success here: teardown is idempotent by design.
+	if (deleted.code !== 0 && !/not found|does not exist|10007|10090/i.test(deleted.out)) {
+		return fail(`could not delete the worker:\n${deleted.out.trim().split("\n").slice(-3).join("\n")}`);
+	}
+	console.log(`${color.green("✓")} worker gone${/not found|does not exist/i.test(deleted.out) ? color.dim(" (it was already)") : ""}`);
+
+	for (const queue of plan.queues) {
+		const dropped = await wrangler(bin, ["queues", "delete", queue], app, true);
+		if (dropped.code !== 0 && !/not found|does not exist|11009|11018/i.test(dropped.out)) {
+			console.error(`${color.yellow("!")} queue "${queue}" could not be deleted: ${dropped.out.trim().split("\n").slice(-1)[0]}`);
+		} else {
+			console.log(`${color.green("✓")} queue "${queue}" gone`);
+		}
+	}
+
+	if (plan.d1 && !opts.keepData) {
+		const dropped = await wrangler(bin, ["d1", "delete", plan.d1, "--skip-confirmation"], app, true);
+		if (dropped.code !== 0 && !/not found|does not exist|7404/i.test(dropped.out)) {
+			return fail(`the worker and queues are gone but D1 "${plan.d1}" is not:\n${dropped.out.trim().split("\n").slice(-3).join("\n")}`);
+		}
+		console.log(`${color.green("✓")} database "${plan.d1}" gone`);
+	}
+
+	/**
+	 * Forget the ids. A recorded database id that no longer exists is worse
+	 * than none: `wrangler deploy` FAILS on a dangling `database_id` (error
+	 * 10021) rather than creating a replacement, so leaving it behind would
+	 * make the next deploy fail instead of provisioning cleanly.
+	 */
+	if (!opts.keepData) {
+		writeFileSync(configPath, upsertJsonc(readFileSync(configPath, "utf8"), "d1_databases", []));
+		if (project.manifest.cloudflare?.d1) {
+			const { d1: _dropped, ...rest } = project.manifest.cloudflare;
+			project.manifest.cloudflare = rest;
+			await writeManifest(project.root, project.manifest);
+		}
+		console.log(`${color.green("✓")} the database id is out of wrangler.jsonc and the manifest, so the next deploy provisions afresh`);
+	}
+
+	console.log(
+		`\n${color.bold("Torn down.")} ${color.dim(`The shop's secrets are untouched in ${SECRETS_FILE} — this removed infrastructure, not configuration.`)}\n` +
+			`  Push again, or ${color.cyan("vc deploy --cloudflare --provision")}, and it rebuilds.\n`,
+	);
+	return 0;
+}

package/src/deploy/token-link.ts

@@ -0,0 +1,76 @@
+import type { Manifest } from "../manifest";
+
+/**
+ * A Cloudflare dashboard link that opens the token form already filled in.
+ *
+ * ── Why this is worth having ─────────────────────────────────────────────
+ *
+ * Fetching an API token is the one step of this whole system that a person
+ * has to do by hand, and it was the worst-designed one: a table of ten
+ * permissions to find and tick, in two different scopes, where a single
+ * missed row produces a token that authenticates fine and then fails
+ * halfway through a deploy with a permissions error nobody can place.
+ *
+ * Cloudflare's dashboard accepts `permissionGroupKeys` — a JSON array of
+ * `{key, type}` — and opens Create Token with exactly those selected. So the
+ * ten rows become one link, and the failure mode goes away.
+ *
+ * @see https://developers.cloudflare.com/fundamentals/api/how-to/account-owned-token-template/
+ *
+ * ── On the keys below ────────────────────────────────────────────────────
+ *
+ * They are not guessable and a wrong one is silently dropped, which would
+ * produce a link that looks right and grants less than it claims. Every one
+ * was checked against the dashboard's own permission-group registry AND
+ * against links Cloudflare itself ships in its documentation — the Workers
+ * template, the DNS templates, the Prometheus link. None came from a
+ * third-party repository guessing at them, and several public repositories
+ * do guess: `account`, `user`, `workers`, `pages` match nothing at all.
+ */
+
+/** `[label, key, type, why]` — the why is what a person reads when it fails. */
+const PERMISSIONS: Array<[string, string, string, string]> = [
+	["Workers Scripts: Edit", "workers_scripts", "edit", "deploy the worker"],
+	["D1: Edit", "d1", "edit", "create the database and apply migrations"],
+	["Queues: Edit", "queues", "edit", "create the order queue"],
+	["Workers KV Storage: Edit", "workers_kv_storage", "edit", "sessions and caches"],
+	["Workers R2 Storage: Edit", "workers_r2", "edit", "product images"],
+	["Account Settings: Read", "account_settings", "read", "confirm which account this is"],
+	["Zone: Read", "zone", "read", "confirm the domain's zone is on this account"],
+	["DNS: Read", "dns", "read", "notice a hostname that already answers"],
+	["Workers Routes: Edit", "workers_routes", "edit", "answer on your domain"],
+	["User Details: Read", "user_details", "read", "wrangler asks at startup"],
+	["Memberships: Read", "memberships", "read", "the same"],
+];
+
+/**
+ * The link, for this shop.
+ *
+ * The USER-token form, deliberately: it is the one that accepts the two
+ * user-scoped permissions wrangler wants, and account-owned tokens are
+ * documented as not taking `accountId`/`zoneId` at all. `zoneId=all` because
+ * a shop's zone is not known until the domain is on Cloudflare, and picking
+ * the wrong one is a worse failure than picking from a list.
+ */
+export function cloudflareTokenLink(manifest: Manifest): string {
+	const groups = PERMISSIONS.map(([, key, type]) => ({ key, type }));
+	const params = new URLSearchParams({
+		permissionGroupKeys: JSON.stringify(groups),
+		accountId: "*",
+		zoneId: "all",
+		// So a person with several tokens can tell later which shop this was for.
+		name: `${manifest.shop.domain} deploy`,
+	});
+	return `https://dash.cloudflare.com/profile/api-tokens?${params.toString()}`;
+}
+
+/** The same permissions as a table, for anyone who would rather tick them. */
+export function cloudflareTokenTable(): string {
+	const width = Math.max(...PERMISSIONS.map(([label]) => label.length));
+	return PERMISSIONS.map(([label, , , why]) => `  ${label.padEnd(width)}  ${why}`).join("\n");
+}
+
+/** Markdown, for DEPLOY.md. */
+export function cloudflareTokenMarkdown(): string {
+	return ["| permission | for |", "|---|---|", ...PERMISSIONS.map(([label, , , why]) => `| ${label} | ${why} |`)].join("\n");
+}

package/src/generate/ci.ts

@@ -1,6 +1,7 @@
 import { DIST_BRANCH, DIST_DIR } from "../dist";
 import type { Manifest } from "../manifest";
 import { PRIVATE_KEY_VAR, SECRETS_FILE } from "../deploy/secrets";
+import { cloudflareTokenMarkdown } from "../deploy/token-link";
 
 /**
  * The workflow that turns a push into a live shop.
@@ -190,6 +191,7 @@ jobs:
 /** What a person still has to do once, and why each thing cannot be done for them. */
 export function renderDeployReadme(manifest: Manifest, zone: string, hosts: string[]): string {
 	const worker = manifest.shop.domain.split(".")[0];
+	const TOKEN_TABLE = cloudflareTokenMarkdown();
 	return `# Going live
 
 \`${manifest.shop.domain}\` on Cloudflare Workers. Generated by \`vc init\`;
@@ -244,8 +246,17 @@ ordinary secret in \`${SECRETS_FILE}\`: encrypted, committed, and read by the
 deploy out of what you pushed.
 
 The token itself has to be fetched by a person, once, because there is no
-OIDC between GitHub and Cloudflare and nothing else can issue one. Create it
-at **My Profile → API Tokens → Create Token → Custom token**:
+OIDC between GitHub and Cloudflare and nothing else can issue one. You do
+not have to find the permissions yourself:
+
+\`\`\`sh
+vc secrets set CLOUDFLARE_API_TOKEN
+\`\`\`
+
+prints a Cloudflare link with all of them **already selected**, then takes
+the token. It opens your own dashboard and the value is shown only to you.
+
+${TOKEN_TABLE}
 
 ### The zone