@saastemly/voidcommerce 0.1.0

package/src/scripts.ts

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { box, line, row } from "./help";
+import { ensureGenerated, findProject } from "./project";
+import { runInherit, runVoid } from "./void";
+
+/**
+ * `vc dev`, `vc build`, `vc preview` — the app's own scripts, where the app is.
+ *
+ * void has no `dev` command: `void init` writes `dev`, `build` and `preview`
+ * into the app's package.json (`vp dev`, or `vite dev`), and that is what
+ * runs. vc adds nothing to them but the WHERE — a monorepo's api/ from the
+ * root, a strict artifact under .vc/app, generated first if it is not there.
+ * Outside a project they go to void, which says what it thinks of them.
+ */
+export type AppScript = "dev" | "build" | "preview";
+
+export function appScript(name: AppScript) {
+	return async (args: string[]): Promise<number> => {
+		const project = await findProject();
+		if (!project) return runVoid([name, ...args]);
+		const code = await ensureGenerated(project);
+		if (code !== 0) return code;
+		const pkgPath = join(project.appDir, "package.json");
+		const scripts = existsSync(pkgPath)
+			? ((JSON.parse(readFileSync(pkgPath, "utf8")) as { scripts?: Record<string, string> }).scripts ?? {})
+			: {};
+		if (!scripts[name]) {
+			console.error(`vc: ${relative(process.cwd(), pkgPath) || "package.json"} has no "${name}" script — void init writes one.`);
+			return 1;
+		}
+		return runInherit(process.execPath, ["run", name, ...args], project.appDir);
+	};
+}
+
+export function appScriptHelp(name: AppScript) {
+	return async (): Promise<number> => {
+		const width = 80;
+		console.log(
+			box(`vc ${name}`, [
+				line(`The app's own "${name}" script, run where the app is.`, width),
+				line("", width),
+				...row("one app", "here", width, 2),
+				...row("monorepo", "api/, from the root or from inside api/", width, 2),
+				...row("strict", ".vc/app, generated first if it is not there", width, 2),
+				line("", width),
+				line("Arguments pass through to the script. void has no such command;", width),
+				line("void init writes this script into the app's package.json.", width),
+			], width),
+		);
+		return 0;
+	};
+}

package/src/void.ts

@@ -0,0 +1,115 @@
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { constants as os } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+
+/**
+ * The `void` binary, and the two ways vc uses it.
+ *
+ * `runVoid` hands the terminal over — for everything vc passes through, and
+ * for `void init` when vc extends it. `captureVoid` reads what void would
+ * have printed, so vc can merge its own lines into void's help rather than
+ * replace it.
+ *
+ * Void is the app's dependency, not vc's, so the nearest node_modules wins,
+ * then PATH, then `bunx void` — the way Void's own docs say to invoke it.
+ */
+
+export interface VoidBin {
+	cmd: string;
+	prefix: string[];
+}
+
+export function findVoid(from = process.cwd()): VoidBin | null {
+	let dir = from;
+	for (;;) {
+		const local = join(dir, "node_modules", ".bin", "void");
+		if (existsSync(local)) return { cmd: local, prefix: [] };
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	if (onPath("void")) return { cmd: "void", prefix: [] };
+	if (onPath("bunx")) return { cmd: "bunx", prefix: ["void"] };
+	return null;
+}
+
+function onPath(bin: string): boolean {
+	return (process.env["PATH"] ?? "")
+		.split(delimiter)
+		.filter(Boolean)
+		.some((dir) => existsSync(join(dir, bin)));
+}
+
+export const VOID_MISSING = "`void` is not installed here. `bun add -d void` — Void recommends a local install — then try again.";
+
+/** Hand the terminal to void. Resolves with the exit code void would have had. */
+export function runVoid(args: string[], cwd = process.cwd()): Promise<number> {
+	const bin = findVoid(cwd);
+	if (!bin) {
+		console.error(VOID_MISSING);
+		return Promise.resolve(1);
+	}
+	return runInherit(bin.cmd, [...bin.prefix, ...args], cwd);
+}
+
+/** Hand the terminal to any command, forwarding signals, resolving with its exit code. */
+export function runInherit(cmd: string, args: string[], cwd: string): Promise<number> {
+	return new Promise((resolve) => {
+		const child = spawn(cmd, args, { cwd, stdio: "inherit" });
+		// A signal to vc is a signal to void: Ctrl-C must not leave a wizard running.
+		const signals: NodeJS.Signals[] = ["SIGINT", "SIGTERM", "SIGHUP"];
+		const forward = signals.map((signal) => [signal, () => child.kill(signal)] as const);
+		for (const [signal, handler] of forward) process.on(signal, handler);
+		child.on("error", () => {
+			console.error(VOID_MISSING);
+			resolve(1);
+		});
+		child.on("exit", (code, signal) => {
+			for (const [name, handler] of forward) process.off(name, handler);
+			resolve(code ?? (signal ? 128 + (os.signals[signal] ?? 0) : 1));
+		});
+	});
+}
+
+/** What void prints for `args`, or null when void is not here. Stdout then stderr, as void ordered them. */
+export function captureVoid(args: string[], cwd = process.cwd()): Promise<{ code: number; out: string } | null> {
+	const bin = findVoid(cwd);
+	if (!bin) return Promise.resolve(null);
+	const wantColor = Boolean(process.stdout.isTTY) && !process.env["NO_COLOR"];
+	return new Promise((resolve) => {
+		const child = spawn(bin.cmd, [...bin.prefix, ...args], {
+			cwd,
+			stdio: ["ignore", "pipe", "pipe"],
+			env: { ...process.env, ...(wantColor ? { FORCE_COLOR: "1" } : {}) },
+		});
+		let out = "";
+		child.stdout.on("data", (chunk) => {
+			out += chunk;
+		});
+		child.stderr.on("data", (chunk) => {
+			out += chunk;
+		});
+		child.on("error", () => resolve(null));
+		child.on("exit", (code) => resolve({ code: code ?? 1, out }));
+	});
+}
+
+/** A directory Void already knows: its Vite config imports void, or it carries a void.json. */
+export function isVoidApp(dir: string): boolean {
+	if (existsSync(join(dir, "void.json"))) return true;
+	for (const name of ["vite.config.ts", "vite.config.mts", "vite.config.js", "vite.config.mjs"]) {
+		const path = join(dir, name);
+		if (!existsSync(path)) continue;
+		if (/from\s+["']void["']|voidPlugin\s*\(/.test(readFileSync(path, "utf8"))) return true;
+	}
+	return false;
+}
+
+/** The Void apps directly under `dir` — for when `void init` chose to make a subfolder. */
+export function voidAppsIn(dir: string): string[] {
+	return readdirSync(dir, { withFileTypes: true })
+		.filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules")
+		.map((entry) => join(dir, entry.name))
+		.filter(isVoidApp);
+}

package/src/wizard.ts

@@ -0,0 +1,234 @@
+import * as p from "@clack/prompts";
+import color from "picocolors";
+import { GROUPS, type Group } from "./catalog";
+import { LAYOUTS, type Layout, type Manifest, zoneOf } from "./manifest";
+
+/**
+ * The forms.
+ *
+ * ── The shape of a good wizard ───────────────────────────────────────────
+ *
+ * `void init` asks three questions and stops, which is right for Void — a
+ * Void app can be anything. A shop cannot be anything: it has a payment rail
+ * or it does not trade, it has email or nobody can sign in, it has a tax rate
+ * or it sells unlawfully. So this asks about all of it, in the order a person
+ * would think about it — how it is laid out, who signs in, what you sell, how
+ * you get paid, how it ships, where the domain lives — and every choice says
+ * what it is FOR.
+ *
+ * The layout is asked FIRST and on its own, because it decides where
+ * `void init` has to run before the rest of the form makes sense.
+ *
+ * Required choices are shown ticked and cannot be unticked, so the person
+ * sees what they are getting rather than discovering it in `auth.ts`.
+ * Recommended choices are ticked by default, because a shop that starts with
+ * reviews and wishlists off has to remember to turn them on, and never does.
+ *
+ * Cancelling anywhere exits cleanly with nothing written. A half-written
+ * manifest is worse than none.
+ */
+
+const bail = (): never => {
+	p.cancel("Nothing was written.");
+	process.exit(0);
+};
+
+const unwrap = <T>(value: T | symbol): T => {
+	if (p.isCancel(value)) bail();
+	return value as T;
+};
+
+/** The first question. */
+export async function askLayout(): Promise<Layout> {
+	return unwrap(
+		await p.select<Layout>({
+			message: "Layout",
+			options: LAYOUTS.map((layout) => ({ value: layout.id, label: layout.label, hint: layout.hint })),
+			initialValue: "app",
+		}),
+	);
+}
+
+/**
+ * One group as a prompt.
+ *
+ * Multiselect prompts cannot mark an option as both selected and disabled,
+ * so a required choice is shown in the intro line and added afterwards
+ * rather than drawn as a tick the person cannot undo. `alsoRequired` is what
+ * the layout adds — the monorepo's frontend needs the storefront kit.
+ */
+async function askGroup(group: Group, previous: string[] | undefined, alsoRequired: string[] = []): Promise<string[]> {
+	const requiredIds = new Set([...group.choices.filter((choice) => choice.required).map((c) => c.id), ...alsoRequired]);
+	const required = group.choices.filter((choice) => requiredIds.has(choice.id));
+	const optional = group.choices.filter((choice) => !requiredIds.has(choice.id));
+
+	const message =
+		group.title +
+		(group.intro ? `\n${color.dim(group.intro)}` : "") +
+		(required.length
+			? `\n${color.dim(`Included: ${required.map((choice) => choice.label).join(", ")}`)}`
+			: "");
+
+	if (optional.length === 0) {
+		p.log.info(message);
+		return required.map((choice) => choice.id);
+	}
+
+	const options = optional.map((choice) => ({
+		value: choice.id,
+		label: choice.label,
+		hint: choice.hint,
+	}));
+
+	if (group.kind === "select") {
+		const initial =
+			previous?.[0] ?? optional.find((choice) => choice.recommended)?.id ?? optional[0]!.id;
+		const picked = unwrap(await p.select({ message, options, initialValue: initial }));
+		return [...required.map((choice) => choice.id), picked];
+	}
+
+	const initial = previous ?? optional.filter((choice) => choice.recommended).map((c) => c.id);
+	const picked = unwrap(
+		await p.multiselect({ message, options, initialValues: initial, required: false }),
+	);
+	return [...required.map((choice) => choice.id), ...picked];
+}
+
+/** The rest of the form, once the layout is known and the Void app(s) exist. */
+export async function runWizard(existing: Manifest | null, layout: Layout): Promise<Manifest> {
+	const monorepo = layout === "monorepo";
+	const frontend = layout !== "app";
+
+	const shop = unwrap(
+		await p.group(
+			{
+				name: () =>
+					p.text({
+						message: "Shop name",
+						placeholder: "Northwind",
+						initialValue: existing?.shop.name ?? "",
+						validate: (value) => (value.trim() ? undefined : "A shop has a name."),
+					}),
+				domain: () =>
+					p.text({
+						message: `Domain ${color.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.",
+					}),
+				// Only a shop that is not its own registrable domain has a zone to
+				// name — and it must, because that is where records go and which
+				// zone Cloudflare needs for the worker's custom domain.
+				zone: ({ results }) => {
+					const domain = (results.domain ?? "").trim().toLowerCase();
+					const guess = zoneOf(domain);
+					if (!domain || domain === guess) return Promise.resolve(undefined);
+					return p.text({
+						message: `DNS zone ${color.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) => {
+							const zone = value.trim().toLowerCase();
+							if (!zone) return "The zone that contains the domain.";
+							return domain === zone || domain.endsWith(`.${zone}`) ? undefined : `${domain} is not inside ${zone}.`;
+						},
+					});
+				},
+				country: () =>
+					p.text({
+						message: `Country ${color.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? ${color.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" },
+						],
+						initialValue: existing?.shop.taxRegistered ? "yes" : "no",
+					}),
+				currency: () =>
+					p.text({
+						message: "Currency",
+						placeholder: "usd",
+						initialValue: existing?.shop.currency ?? "",
+						validate: (value) => (/^[A-Za-z]{3}$/.test(value.trim()) ? undefined : "ISO-4217, like dkk."),
+					}),
+				locale: () =>
+					p.text({
+						message: `Locale ${color.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
+					? {
+							pagesHost: () =>
+								p.text({
+									message: `GitHub Pages host ${color.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",
+								}),
+						}
+					: {}),
+			},
+			{ onCancel: bail },
+		),
+	);
+
+	const chosen: Record<string, string[]> = {};
+	for (const group of GROUPS) {
+		if (group.id === "ui" && layout === "strict") {
+			// Strict has no custom code, so the generated interface is the only one.
+			p.log.info(`${group.title}\n${color.dim("The generated storefront and panel. Strict has no custom code to host anything else.")}`);
+			chosen[group.id] = ["admin"];
+			continue;
+		}
+		const alsoRequired = monorepo && group.id === "ui" ? ["custom"] : [];
+		chosen[group.id] = await askGroup(group, existing?.chosen[group.id], alsoRequired);
+	}
+
+	return {
+		version: 1,
+		layout,
+		shop: {
+			name: shop.name.trim(),
+			domain: shop.domain.trim().toLowerCase(),
+			country: shop.country.trim().toUpperCase(),
+			currency: shop.currency.trim().toLowerCase(),
+			locale: shop.locale.trim(),
+			taxRegistered: (shop as { taxRegistered?: string }).taxRegistered === "yes",
+			zone: (shop as { zone?: string }).zone?.trim().toLowerCase() || undefined,
+			pagesHost: frontend ? (shop as { pagesHost?: string }).pagesHost?.trim().toLowerCase() || undefined : undefined,
+		},
+		chosen,
+	};
+}
+
+/** A closing summary the person can read before anything is written. */
+export function summarise(manifest: Manifest): string {
+	const lines: string[] = [
+		`${color.dim("Layout".padEnd(34))} ${LAYOUTS.find((l) => l.id === manifest.layout)?.label ?? manifest.layout}`,
+	];
+	for (const group of GROUPS) {
+		const ids = manifest.chosen[group.id] ?? [];
+		if (ids.length === 0) continue;
+		const labels = ids
+			.map((id) => group.choices.find((choice) => choice.id === id)?.label ?? id)
+			.join(", ");
+		lines.push(`${color.dim(group.title.padEnd(34))} ${labels}`);
+	}
+	return lines.join("\n");
+}