@saastemly/voidcommerce 0.1.0

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * voidcommerce — the library half of `vc`.
+ *
+ * The CLI is `bin/vc`. This is what a generator, a test, or Void itself one
+ * day, imports: the catalogue of choices, the manifest they are recorded in,
+ * and the generators that turn a manifest into files.
+ */
+export * from "./catalog";
+export * from "./manifest";
+export { generate, type GenerateResult } from "./generate/index";
+export { renderAuthTs } from "./generate/auth";
+export {
+	allEnvKeys,
+	envSummary,
+	renderEnvExample,
+	renderEnvLocal,
+	renderEnvProduction,
+	renderEnvTs,
+} from "./generate/env";
+export { renderRequirementsTs } from "./generate/requirements";
+export { renderDomainTs } from "./generate/support";
+export * from "./generate/strict";
+export { findProject, type Project } from "./project";
+export { parseJsonc, upsertJsonc } from "./deploy/jsonc";
+export { parseWhoAmI, findWrangler } from "./deploy/wrangler";
+export { preflight, printPreflight, productionEnv, routeProblem } from "./deploy/preflight";
+export { deployCloudflare } from "./deploy/cloudflare";
+export {
+	FRONTEND_BRANCH,
+	renderFrontendApiTs,
+	renderFrontendEnvProduction,
+	renderFrontendWorkflow,
+	renderStorefrontPage,
+} from "./generate/frontend";
+export { distCommand, DIST_BRANCH, DIST_DIR } from "./dist";
+export { renderDistWorkflow, renderDeployReadme } from "./generate/ci";
+export { importCommand } from "./import";

package/src/init.ts

@@ -0,0 +1,187 @@
+import * as p from "@clack/prompts";
+import { mkdir } from "node:fs/promises";
+import { basename, join } from "node:path";
+import color from "picocolors";
+import { generate } from "./generate/index";
+import { envSummary } from "./generate/env";
+import { finishStrict } from "./generate/strict";
+import { type Layout, LAYOUTS, readManifest, validate } from "./manifest";
+import { isVoidApp, runVoid, voidAppsIn } from "./void";
+import { askLayout, runWizard, summarise } from "./wizard";
+
+/**
+ * `vc init` extends `void init`; it does not replace it.
+ *
+ * The layout comes first, because it decides where void's own wizard runs:
+ * once here for one app, or once each in api/ and frontend/ for a monorepo.
+ * void lays the app(s) down — vite config, pages, db — exactly as it would
+ * without vc. Then vc's form runs on top. Where the app exists, only the
+ * form runs, pre-filled from voidcommerce.json. Void's partial modes
+ * (`--agents`, `--tsconfig`, `--github`) do one thing and are handed to void
+ * unchanged.
+ */
+
+/** vc's own flags, split from whatever is void's. */
+function parseFlags(args: string[]): { layout?: Layout; link?: string; voids: string[]; problem?: string } {
+	const voids: string[] = [];
+	let layout: Layout | undefined;
+	let link: string | undefined;
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i]!;
+		const linked = arg.startsWith("--link=") ? arg.slice("--link=".length) : arg === "--link" ? args[++i] : undefined;
+		if (linked !== undefined) {
+			if (!linked) return { voids, problem: "--link needs a directory holding the betterCommerce packages" };
+			link = linked;
+			continue;
+		}
+		const value = arg.startsWith("--layout=") ? arg.slice("--layout=".length) : arg === "--layout" ? args[++i] : undefined;
+		if (value === undefined) {
+			voids.push(arg);
+			continue;
+		}
+		if (!LAYOUTS.some((l) => l.id === value)) {
+			return { voids, problem: `--layout must be one of ${LAYOUTS.map((l) => l.id).join(", ")}, not "${value ?? ""}"` };
+		}
+		layout = value as Layout;
+	}
+	return { layout, link, voids };
+}
+
+export async function init(args: string[]): Promise<number> {
+	const flags = parseFlags(args);
+	if (flags.problem) {
+		console.error(`vc: ${flags.problem}`);
+		return 1;
+	}
+	if (flags.voids.length > 0) return runVoid(["init", ...flags.voids]);
+
+	let root = process.cwd();
+	p.intro(color.bgCyan(color.black(" voidcommerce ")));
+
+	const existing = await readManifest(root);
+	if (existing) {
+		p.log.info(
+			`Found ${color.cyan("voidcommerce.json")} for ${color.bold(existing.shop.name)} — answers are pre-filled; the layout (${existing.layout}) is fixed.`,
+		);
+		if (flags.layout && flags.layout !== existing.layout) {
+			p.log.error(`This shop is laid out as "${existing.layout}". The layout cannot change after init — moving files is not a regeneration.`);
+			return 1;
+		}
+	}
+	const layout = existing?.layout ?? flags.layout ?? (await askLayout());
+
+	if (layout === "strict") {
+		// Nothing to lay down: the app is generated, void init included.
+		p.log.step(`Strict: the app will be generated under ${color.cyan(".vc/app")} — nothing there is yours to edit.`);
+	} else if (layout === "app") {
+		if (!isVoidApp(root)) {
+			p.log.step(`No Void app here yet — ${color.cyan("void init")} first, then the shop.`);
+			const before = new Set(voidAppsIn(root));
+			const code = await runVoid(["init"]);
+			if (code !== 0) return code;
+			if (!isVoidApp(root)) {
+				// void init may have chosen a subfolder. Follow it if it made exactly one.
+				const created = voidAppsIn(root).filter((dir) => !before.has(dir));
+				if (created.length !== 1) {
+					console.error(`vc: void init did not leave a Void app in ${root}, so there is nothing to build a shop on.`);
+					return 1;
+				}
+				root = created[0]!;
+				process.chdir(root);
+				p.log.step(`Continuing in ${color.cyan(`${basename(root)}/`)}`);
+			}
+		}
+	} else {
+		const parts: Array<[dir: string, starter: string]> = [
+			["api", "the D1 starter — this is the worker"],
+			["frontend", "Static Pages — this is prerendered for GitHub Pages"],
+		];
+		for (const [dir, starter] of parts) {
+			const target = join(root, dir);
+			if (isVoidApp(target)) continue;
+			await mkdir(target, { recursive: true });
+			p.log.step(`${color.cyan("void init")} in ${color.cyan(`${dir}/`)} — choose ${starter}.`);
+			const code = await runVoid(["init"], target);
+			if (code !== 0) return code;
+			if (!isVoidApp(target)) {
+				console.error(`vc: void init did not leave a Void app in ${dir}/, so there is nothing to build on.`);
+				return 1;
+			}
+		}
+	}
+
+	const manifest = await runWizard(existing, layout);
+	// Until the packages are published, a checkout supplies them.
+	const link = flags.link ?? existing?.link;
+	if (link) manifest.link = link;
+
+	const problems = validate(manifest);
+	if (problems.length > 0) {
+		p.log.error("These answers contradict each other:");
+		for (const problem of problems) p.log.message(`  ${color.red("✗")} ${problem}`);
+		p.cancel("Nothing was written.");
+		return 1;
+	}
+
+	p.note(summarise(manifest), `${manifest.shop.name} · ${manifest.shop.domain}`);
+
+	const go = await p.confirm({ message: "Write the files?", initialValue: true });
+	if (p.isCancel(go) || !go) {
+		p.cancel("Nothing was written.");
+		return 0;
+	}
+
+	const spinner = p.spinner();
+	spinner.start("Generating");
+	const result = await generate(root, manifest);
+	spinner.stop("Generated");
+
+	const { secrets, plaintext } = envSummary(manifest);
+	p.note(
+		[
+			...result.written.map((file) => `${color.green("+")} ${file}`),
+			...result.kept.map((file) => `${color.dim("=")} ${file} ${color.dim("(kept — yours)")}`),
+		].join("\n"),
+		"Files",
+	);
+	p.note(
+		[
+			`${color.bold(String(secrets.length))} secrets  ${color.dim("→ wrangler secret put <NAME>")}`,
+			...secrets.map((key) => `  ${key}`),
+			"",
+			`${color.bold(String(plaintext.length))} plaintext ${color.dim("→ .env.production, already written")}`,
+			...plaintext.map((key) => `  ${key}`),
+		].join("\n"),
+		"Before going live",
+	);
+
+	if (layout === "strict") {
+		const code = await finishStrict(root);
+		if (code !== 0) return code;
+	}
+
+	const next =
+		layout === "app"
+			? [
+					`  ${color.cyan("bun install")}`,
+					`  ${color.cyan("bun run maildev")}      ${color.dim("local inbox at http://localhost:1080")}`,
+					`  ${color.cyan("vc dev")}`,
+					`  ${color.cyan("vc preflight")}        ${color.dim("what is still missing, and why it matters")}`,
+				]
+			: layout === "strict"
+				? [
+						`  ${color.cyan("bun install")}`,
+						`  ${color.cyan("vc generate")}         ${color.dim("the app under .vc/app, void's artifacts, the migrations")}`,
+						`  ${color.cyan("bun run maildev")}      ${color.dim("local inbox at http://localhost:1080")}`,
+						`  ${color.cyan("vc dev")}               ${color.dim("runs in .vc/app")}`,
+					]
+				: [
+					`  ${color.cyan("bun install")}          ${color.dim("one install for both workspaces")}`,
+					`  ${color.cyan("bun run maildev")}      ${color.dim("local inbox at http://localhost:1080")}`,
+					`  ${color.cyan("bun run dev:api")}      ${color.dim("the worker, with the panel")}`,
+					`  ${color.cyan("bun run dev:frontend")} ${color.dim("the storefront, against the local API")}`,
+					`  ${color.cyan("bun run preflight")}    ${color.dim("what is still missing, and why it matters")}`,
+				];
+	p.outro(["Next:", ...next].join("\n"));
+	return 0;
+}

package/src/manifest.ts

@@ -0,0 +1,303 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { CHOICES, GROUPS } from "./catalog";
+
+/**
+ * `voidcommerce.json` — what this shop is made of.
+ *
+ * ── Why a manifest and not just generated files ─────────────────────────
+ *
+ * A wizard that writes `auth.ts` once and forgets what it asked is a
+ * scaffolder: useful on day one, useless on day thirty when you want to add
+ * subscriptions and cannot remember which of the forty checkboxes you ticked.
+ *
+ * The manifest is the answers. Every generated file derives from it, so
+ * `vc init` on an existing project means "edit the answers and regenerate",
+ * and `vc gen` can read it to know what the shop already has. It is the
+ * Rails `config/` — the thing that makes the rest reproducible.
+ */
+
+export const MANIFEST_FILE = "voidcommerce.json";
+
+/**
+ * How the shop is laid out — on disk and on the internet.
+ *
+ *   app       One Void app: the API and the generated storefront and panel,
+ *             on Cloudflare Workers at <domain> and www.<domain>.
+ *   monorepo  api/       a Void app on Workers at api.<domain>, with the panel
+ *             frontend/  a static Void site on GitHub Pages at <domain>
+ *
+ *   strict    EXPERIMENTAL. A monorepo turned inside out. The REPOSITORY
+ *             ROOT is the storefront — its package.json, its pages, yours to
+ *             edit — and the worker is generated underneath it at .vc/app
+ *             from the manifest, gitignored, never hand-edited. Hosted the
+ *             way a monorepo is: the worker on api.<domain>, the storefront
+ *             on <domain>.
+ *
+ * The first question, because it decides where `void init` runs and what
+ * the domain means. It cannot change after init: moving files is not a
+ * regeneration.
+ */
+export type Layout = "app" | "monorepo" | "strict";
+
+export const LAYOUTS: Array<{ id: Layout; label: string; hint: string }> = [
+	{
+		id: "app",
+		label: "One app",
+		hint: "the API and the generated storefront and panel in one Void app on Cloudflare Workers, at your domain",
+	},
+	{
+		id: "monorepo",
+		label: "Monorepo: api + frontend",
+		hint: "api/ on Workers at api.<domain> with the panel; frontend/ a static site on GitHub Pages at <domain>",
+	},
+	{
+		id: "strict",
+		label: "Strict (experimental)",
+		hint: "the root IS the storefront, sharing one package.json; the worker is generated under .vc/app from the manifest and never hand-edited",
+	},
+];
+
+/**
+ * One worker that IS the site, with no storefront anywhere else.
+ *
+ * Only `app`. A monorepo has `frontend/`; strict has the storefront at the
+ * ROOT — what a person edits there is the shop front, and the worker is
+ * generated underneath it. Both put the worker on `api.<domain>` and the
+ * storefront on the domain itself.
+ */
+export const isSingleApp = (layout: Layout): boolean => layout === "app";
+
+/** Does this layout carry a storefront of its own, and so a second origin to trust? */
+export const hasFrontend = (layout: Layout): boolean => layout !== "app";
+
+/**
+ * Public suffixes whose second label is not a registrable name, so
+ * `shop.example.co.uk` is a subdomain of `example.co.uk`, not of `co.uk`.
+ * A short list on purpose: it only picks the DEFAULT the wizard offers, and
+ * the answer is written into the manifest where a person can correct it.
+ */
+const TWO_LABEL_SUFFIXES = new Set(["co", "com", "net", "org", "ac", "gov", "edu", "or", "ne", "in"]);
+
+/** The zone a hostname most likely belongs to: the registrable domain. */
+export function zoneOf(domain: string): string {
+	const labels = domain.trim().toLowerCase().replace(/\.$/, "").split(".");
+	if (labels.length <= 2) return labels.join(".");
+	const take = TWO_LABEL_SUFFIXES.has(labels[labels.length - 2] ?? "") && (labels[labels.length - 1] ?? "").length <= 3 ? 3 : 2;
+	return labels.slice(-take).join(".");
+}
+
+/** The zone this shop's records go in. */
+export function zone(manifest: Manifest): string {
+	return manifest.shop.zone || zoneOf(manifest.shop.domain);
+}
+
+/** Is the shop at the zone's apex? Only then is there a `www` to answer on. */
+export function isApex(manifest: Manifest): boolean {
+	return manifest.shop.domain === zone(manifest);
+}
+
+/** Every hostname the worker answers on — the wrangler routes, in order. */
+export function workerHosts(manifest: Manifest): string[] {
+	const { domain } = manifest.shop;
+	if (!isSingleApp(manifest.layout)) return [`api.${domain}`];
+	return isApex(manifest) ? [domain, `www.${domain}`] : [domain];
+}
+
+/** What a layout adds to the choices, whatever was ticked. */
+const LAYOUT_IMPLIES: Record<Layout, Record<string, string[]>> = {
+	app: {},
+	// The frontend IS a custom storefront; it needs the kit.
+	monorepo: { ui: ["custom"] },
+	// The storefront at the root is custom code and needs the kit; the panel
+	// is still generated, and still mounted on the worker.
+	strict: { ui: ["admin", "custom"] },
+};
+
+export interface Manifest {
+	/** Schema version, for the day the shape changes. */
+	version: 1;
+	layout: Layout;
+	shop: {
+		name: string;
+		/** `deki.dk`, or `tshirt.saastemly.com` — the shop's public hostname; everything derives from it. */
+		domain: string;
+		/**
+		 * The DNS zone that CONTAINS the domain: `deki.dk` for an apex,
+		 * `saastemly.com` for `tshirt.saastemly.com`. Records are written here,
+		 * and a Worker custom domain needs this zone on Cloudflare. Absent
+		 * means the domain is its own zone.
+		 */
+		zone?: string | undefined;
+		/** `DK` — drives the declared VAT rate and the default region. */
+		country: string;
+		/** `dkk` */
+		currency: string;
+		/** `da` — copy in emails and launch content. */
+		locale: string;
+		/**
+		 * Is the shop registered for VAT (or its local equivalent)?
+		 *
+		 * Not a preference. A business below the registration threshold must
+		 * NOT add tax to a price, and one above it must. Getting this wrong is
+		 * unlawful in both directions, and it is invisible in a generated
+		 * `auth.ts` unless something asks — so this asks, and there is no
+		 * default that is safe to assume.
+		 */
+		taxRegistered?: boolean | undefined;
+		/** `saastemly.github.io` — the monorepo's frontend lives on GitHub Pages; the www record points here. */
+		pagesHost?: string | undefined;
+	};
+	/** Chosen ids from each group, keyed by group id. */
+	chosen: Record<string, string[]>;
+	/**
+	 * Where the betterCommerce packages come from, when not from npm.
+	 * `vc init --link ../` writes `file:../better-commerce` and friends, so a
+	 * checkout of the whole suite installs. Absent means the registry.
+	 */
+	link?: string | undefined;
+	/**
+	 * What `vc deploy --cloudflare --provision` created. Recorded here so a
+	 * regenerated wrangler.jsonc (strict) carries the real ids.
+	 */
+	cloudflare?: {
+		accountId?: string;
+		d1?: { name: string; id: string };
+	};
+}
+
+/** Everything a group's `required` choices and the layout imply, whatever was ticked. */
+export function withRequired(chosen: Record<string, string[]>, layout: Layout = "app"): Record<string, string[]> {
+	const out: Record<string, string[]> = {};
+	for (const group of GROUPS) {
+		const picked = new Set([...(chosen[group.id] ?? []), ...(LAYOUT_IMPLIES[layout][group.id] ?? [])]);
+		for (const choice of group.choices) {
+			if (choice.required) picked.add(choice.id);
+		}
+		// A choice that requires another pulls it in, so the generator never
+		// sees `username` without `password`.
+		for (const id of [...picked]) {
+			for (const dependency of CHOICES.get(id)?.requires ?? []) picked.add(dependency);
+		}
+		out[group.id] = group.choices.filter((choice) => picked.has(choice.id)).map((c) => c.id);
+	}
+	return out;
+}
+
+/** Is a choice in the manifest, in any group? */
+export function has(manifest: Manifest, id: string): boolean {
+	return Object.values(withRequired(manifest.chosen, manifest.layout)).some((ids) => ids.includes(id));
+}
+
+/** The chosen ids of one group — for ids like `none` that several groups use. */
+export function chosenIn(manifest: Manifest, groupId: string): string[] {
+	return withRequired(manifest.chosen, manifest.layout)[groupId] ?? [];
+}
+
+/** Every env key the chosen set needs, deduplicated, in group order. */
+export function envKeysOf(manifest: Manifest) {
+	const seen = new Set<string>();
+	const keys: NonNullable<NonNullable<ReturnType<typeof CHOICES.get>>["env"]>[number][] = [];
+	for (const ids of Object.values(withRequired(manifest.chosen, manifest.layout))) {
+		for (const id of ids) {
+			for (const key of CHOICES.get(id)?.env ?? []) {
+				if (seen.has(key.key)) continue;
+				seen.add(key.key);
+				keys.push(key);
+			}
+		}
+	}
+	return keys;
+}
+
+/** The packages this suite publishes, which a checkout can supply instead of npm. */
+export const OWN_PACKAGES = [
+	"@saastemly/better-admin-ui",
+	"@saastemly/better-blogs",
+	"@saastemly/better-commerce",
+	"@saastemly/better-commerce-ui",
+	"@saastemly/better-dns",
+	"@saastemly/better-email",
+	"@saastemly/better-faqs",
+	"@saastemly/better-system-user",
+	"@saastemly/voidcommerce",
+];
+
+/** What a dependency on `name` should say: a link into the checkout, or a version. */
+export function specifier(manifest: Manifest, name: string, version = "latest"): string {
+	if (!manifest.link || !OWN_PACKAGES.includes(name)) return version;
+	const base = manifest.link.replace(/\/+$/, "");
+	// The package is scoped; the DIRECTORY it lives in is not. `../better-dns`,
+	// never `../@saastemly/better-dns`.
+	const directory = name.replace(/^@[^/]+\//, "");
+	return `file:${base}/${directory}`;
+}
+
+/** Every npm package the chosen set needs — for the app, or the monorepo's api/. */
+export function packagesOf(manifest: Manifest): string[] {
+	const out = new Set<string>(["better-auth", "@saastemly/better-commerce"]);
+	for (const ids of Object.values(withRequired(manifest.chosen, manifest.layout))) {
+		for (const id of ids) for (const pkg of CHOICES.get(id)?.packages ?? []) out.add(pkg);
+	}
+	// The kit is the frontend's dependency, not the API's.
+	if (manifest.layout === "monorepo") {
+		for (const pkg of CHOICES.get("custom")?.packages ?? []) out.delete(pkg);
+	}
+	return [...out].sort();
+}
+
+export async function readManifest(root: string): Promise<Manifest | null> {
+	try {
+		const parsed = JSON.parse(await readFile(join(root, MANIFEST_FILE), "utf8")) as Manifest;
+		if (parsed.version !== 1) throw new Error(`unknown manifest version ${String(parsed.version)}`);
+		// Manifests written before the layout question: a Pages host meant a separate frontend.
+		parsed.layout ??= parsed.shop.pagesHost ? "monorepo" : "app";
+		return parsed;
+	} catch (error) {
+		if ((error as { code?: string }).code === "ENOENT") return null;
+		throw error;
+	}
+}
+
+export async function writeManifest(root: string, manifest: Manifest): Promise<void> {
+	await writeFile(join(root, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+
+/** Refuse a manifest that contradicts the catalogue's rules or its own layout. */
+export function validate(manifest: Manifest): string[] {
+	const problems: string[] = [];
+	const chosen = withRequired(manifest.chosen, manifest.layout);
+	for (const group of GROUPS) {
+		const ids = chosen[group.id] ?? [];
+		if (group.kind === "select" && ids.length !== 1) {
+			problems.push(`${group.title}: exactly one choice is needed, got ${ids.length}`);
+		}
+		for (const id of ids) {
+			for (const conflict of CHOICES.get(id)?.conflicts ?? []) {
+				if (ids.includes(conflict)) problems.push(`${group.title}: ${id} cannot be used with ${conflict}`);
+			}
+		}
+	}
+	if (!/^[a-z0-9.-]+\.[a-z]{2,}$/i.test(manifest.shop.domain)) {
+		problems.push(`domain "${manifest.shop.domain}" does not look like a hostname`);
+	} else if (manifest.shop.zone && manifest.shop.domain !== manifest.shop.zone && !manifest.shop.domain.endsWith(`.${manifest.shop.zone}`)) {
+		problems.push(`domain "${manifest.shop.domain}" is not inside the zone "${manifest.shop.zone}" — records would be written to a zone that does not contain it`);
+	}
+	if (!/^[A-Z]{2}$/.test(manifest.shop.country)) {
+		problems.push(`country "${manifest.shop.country}" must be an ISO-3166 alpha-2 code`);
+	}
+
+	const dns = chosen["dns"] ?? [];
+	// Every layout puts the worker on a Cloudflare custom domain, and Cloudflare
+	// creates that record in its own zone. A zone hosted elsewhere cannot have
+	// one, so a second DNS provider is not a preference — it is a contradiction.
+	if (dns.includes("simply")) {
+		problems.push(
+			`DNS at Simply.com cannot host ${workerHosts(manifest)[0]} — a Worker custom domain is created by Cloudflare, in a zone on Cloudflare`,
+		);
+	}
+	if (hasFrontend(manifest.layout) && manifest.shop.pagesHost && !/^[a-z0-9-]+\.github\.io$/i.test(manifest.shop.pagesHost)) {
+		problems.push(`Pages host "${manifest.shop.pagesHost}" should be <owner>.github.io`);
+	}
+	return problems;
+}

package/src/project.ts

@@ -0,0 +1,63 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { generate } from "./generate/index";
+import { STRICT_APP, finishStrict } from "./generate/strict";
+import { type Manifest, readManifest } from "./manifest";
+
+/**
+ * The project vc is standing in, if any.
+ *
+ * The manifest names the root. Where void's commands run follows the layout:
+ * the root itself for one app; api/ for a monorepo — from the root or from
+ * inside api/; the artifact under .vc/app for strict, generated first if it
+ * is not there.
+ */
+export interface Project {
+	root: string;
+	manifest: Manifest;
+	/** Where void's commands run. */
+	appDir: string;
+	/** Strict only: the artifact has not been generated yet. */
+	needsGenerate: boolean;
+}
+
+export async function findProject(cwd = process.cwd()): Promise<Project | null> {
+	// The manifest is here, or a few levels up (a monorepo's api/).
+	let root = cwd;
+	let manifest: Manifest | null = null;
+	for (let hops = 0; hops < 3 && root; hops++) {
+		manifest = await readManifest(root);
+		if (manifest) break;
+		const parent = dirname(root);
+		if (parent === root) break;
+		root = parent;
+	}
+	if (!manifest) return null;
+
+	switch (manifest.layout) {
+		case "monorepo": {
+			const api = join(root, "api");
+			// Inside frontend/ you are on your own: that is a plain Void app.
+			if (cwd !== root && cwd !== api) return null;
+			return { root, manifest, appDir: api, needsGenerate: false };
+		}
+		case "strict": {
+			if (cwd !== root) return null;
+			const appDir = join(root, STRICT_APP);
+			return { root, manifest, appDir, needsGenerate: !existsSync(join(appDir, "auth.ts")) };
+		}
+		default:
+			if (cwd !== root) return null;
+			return { root, manifest, appDir: root, needsGenerate: false };
+	}
+}
+
+/** A strict artifact that is not there yet is generated before anything runs in it. */
+export async function ensureGenerated(project: Project): Promise<number> {
+	if (!project.needsGenerate) return 0;
+	console.log("vc: no app under .vc/app yet — generating it from voidcommerce.json.");
+	await generate(project.root, project.manifest);
+	const code = await finishStrict(project.root);
+	if (code === 0) project.needsGenerate = false;
+	return code;
+}

package/src/regenerate.ts

@@ -0,0 +1,51 @@
+import * as p from "@clack/prompts";
+import color from "picocolors";
+import { generate } from "./generate/index";
+import { finishStrict } from "./generate/strict";
+import { box, line, row } from "./help";
+import { validate } from "./manifest";
+import { findProject } from "./project";
+
+/**
+ * `vc generate` — the files from the manifest, without the form.
+ *
+ * In one-app and monorepo layouts it rewrites the regenerated files and
+ * keeps the owned ones. In strict it is the whole app: every file under
+ * .vc/app, then void's own artifacts and the migrations.
+ */
+export async function generateCommand(): Promise<number> {
+	const project = await findProject();
+	if (!project) {
+		console.error("vc: no voidcommerce.json here. `vc init` writes one.");
+		return 1;
+	}
+	const problems = validate(project.manifest);
+	if (problems.length > 0) {
+		console.error("vc: voidcommerce.json contradicts itself:");
+		for (const problem of problems) console.error(`  ✗ ${problem}`);
+		return 1;
+	}
+	const result = await generate(project.root, project.manifest);
+	p.log.step(
+		[
+			...result.written.map((file) => `${color.green("+")} ${file}`),
+			...result.kept.map((file) => `${color.dim("=")} ${file} ${color.dim("(kept)")}`),
+		].join("\n"),
+	);
+	return project.manifest.layout === "strict" ? finishStrict(project.root) : 0;
+}
+
+export async function generateHelp(): Promise<number> {
+	const width = 80;
+	console.log(
+		box("vc generate", [
+			line("The files from voidcommerce.json, without the form.", width),
+			line("", width),
+			...row("one app, monorepo", "rewrites the regenerated files; files you own are kept", width, 2),
+			...row("strict", "rewrites the whole app under .vc/app, then runs void prepare and void db generate", width, 2),
+			line("", width),
+			line("vc runs this itself when a strict root has no app yet.", width),
+		], width),
+	);
+	return 0;
+}