@saastemly/voidcommerce 0.1.0

package/src/generate/support.ts

@@ -0,0 +1,252 @@
+import { type Layout, type Manifest, has } from "../manifest";
+
+/**
+ * The small modules `auth.ts` imports: the domain, the payment rail, the
+ * notification bridge, and the ERP when one was chosen.
+ *
+ * Each is written once and then OWNED by the app — they are the files a shop
+ * edits when it grows past the wizard, so they are not regenerated. `auth.ts`
+ * is the only file with a marked region.
+ */
+
+export function renderDomainTs(layout: Layout): string {
+	const derive =
+		layout === "app"
+			? `	// One app: the worker IS the site. No separate API host, and no other
+	// origin to trust. It answers on www too, but only at a zone's apex —
+	// www.shop.example.com is not a name anybody types.
+	const hosts = apex ? [host, www] : [host];
+	return { host, zone, apex, api: host, www, hosts, appUrl: \`https://\${host}\`, frontendOrigins: [] };`
+			: `	// The worker is the API; the storefront is elsewhere and must be trusted.
+	const api = \`api.\${host}\`;
+	const frontendOrigins = apex ? [\`https://\${host}\`, \`https://\${www}\`] : [\`https://\${host}\`];
+	return { host, zone, apex, api, www, hosts: [api], appUrl: \`https://\${api}\`, frontendOrigins };`;
+	return `/**
+ * The shop's domain, and everything derived from it.
+ *
+ * One variable. \`SHOP_DOMAIN\` gives ${layout === "app" ? "the worker's hostnames" : "api.<domain> for the worker and the\n * storefront's origins"}, the app's public origin, and the
+ * CORS and CSRF allow-list. They were four settings that had to agree and
+ * nothing checked that they did.
+ *
+ * The domain need not be a registrable apex: \`tshirt.saastemly.com\` is a
+ * shop inside the zone \`saastemly.com\`, which is where its DNS records go.
+ * \`SHOP_ZONE\` names that zone; unset, the domain is its own.
+ */
+export interface ShopDomain {
+	/** The shop's public hostname. */
+	host: string;
+	/** The DNS zone that contains it — where records are written. */
+	zone: string;
+	/** Is the host the zone's apex? Only then is there a www. */
+	apex: boolean;
+	/** Where the worker answers. */
+	api: string;
+	www: string;
+	/** Every hostname the worker should answer on. */
+	hosts: string[];
+	appUrl: string;
+	frontendOrigins: string[];
+}
+
+const clean = (value: string): string =>
+	value.trim().replace(/^https?:\\/\\//, "").replace(/\\/.*$/, "").replace(/\\.$/, "").toLowerCase();
+
+export function shopDomain(input: string, zoneInput?: string): ShopDomain {
+	const host = clean(input).replace(/^www\\./, "");
+	const zone = zoneInput ? clean(zoneInput) : host.split(".").slice(-2).join(".");
+	const apex = host === zone;
+	const www = \`www.\${host}\`;
+${derive}
+}
+
+/** GitHub Pages' published addresses for an apex. Theirs, not yours. */
+export const GITHUB_PAGES_A = ["185.199.108.153", "185.199.109.153", "185.199.110.153", "185.199.111.153"] as const;
+export const GITHUB_PAGES_AAAA = ["2606:50c0:8000::153", "2606:50c0:8001::153", "2606:50c0:8002::153", "2606:50c0:8003::153"] as const;
+
+/**
+ * The storefront's records. DNS-only, never proxied: GitHub issues the
+ * certificate itself and validates by reaching the origin. The API hostname
+ * is NOT here — it is a Cloudflare custom domain in wrangler.jsonc.${
+	layout === "app" ? "\n * One app has no storefront elsewhere, so this is always empty." : ""
+}
+ */
+export function storefrontRecords(domain: ShopDomain, pagesHost: string) {
+	if (!pagesHost${layout === "app" ? " || domain.frontendOrigins.length === 0" : ""}) return [];
+	// The record's name is relative to the zone: "@" at the apex, otherwise the
+	// labels in front of it.
+	const name = domain.apex ? "@" : domain.host.slice(0, -(domain.zone.length + 1));
+	return [
+		...GITHUB_PAGES_A.map((value, i) => ({ key: \`pages-a-\${i}\`, zone: domain.zone, name, type: "A" as const, value, proxied: false })),
+		...GITHUB_PAGES_AAAA.map((value, i) => ({ key: \`pages-aaaa-\${i}\`, zone: domain.zone, name, type: "AAAA" as const, value, proxied: false })),
+		// www only exists at an apex; a shop at shop.example.com has no www.
+		...(domain.apex ? [{ key: "pages-www", zone: domain.zone, name: "www", type: "CNAME" as const, value: pagesHost, proxied: false }] : []),
+	];
+}
+`;
+}
+
+export function renderPaymentTs(manifest: Manifest): string {
+	const currency = manifest.shop.currency.toUpperCase();
+	if (has(manifest, "adyen")) {
+		return `import { adyenProvider } from "@saastemly/better-commerce/providers/adyen";
+import { memoryProvider } from "@saastemly/better-commerce/providers/memory";
+import { env } from "void/env";
+
+/**
+ * Adyen. One rail, no fallback to choose between. Locally the memory provider
+ * stands in when the credentials read as \`unset\` — preflight refuses that
+ * state in production.
+ */
+const read = (key: string): string => {
+	try {
+		const value = (env as Record<string, unknown>)[key];
+		return typeof value === "string" && value !== "unset" ? value : "";
+	} catch {
+		return "";
+	}
+};
+
+const adyen = { apiKey: read("ADYEN_API_KEY"), merchantAccount: read("ADYEN_MERCHANT_ACCOUNT"), hmacKey: read("ADYEN_HMAC_KEY") };
+const configured = Boolean(adyen.apiKey && adyen.merchantAccount && adyen.hmacKey);
+
+export const devPaymentProvider = configured ? null : memoryProvider({ webhookSecret: read("COMMERCE_WEBHOOK_SECRET") || "whsec_dev_secret" });
+
+export const paymentProvider =
+	devPaymentProvider ??
+	adyenProvider({
+		...adyen,
+		environment: read("ADYEN_ENVIRONMENT") === "live" ? "live" : "test",
+		...(read("ADYEN_LIVE_PREFIX") ? { livePrefix: read("ADYEN_LIVE_PREFIX") } : {}),
+		refundCurrency: "${currency}",
+	});
+`;
+	}
+	return `import { memoryProvider } from "@saastemly/better-commerce/providers/memory";
+import { stripeProvider } from "@saastemly/better-commerce/providers/stripe";
+import { env } from "void/env";
+
+/** Stripe. Locally the memory provider stands in when the key reads as \`unset\`. */
+const read = (key: string): string => {
+	try {
+		const value = (env as Record<string, unknown>)[key];
+		return typeof value === "string" && value !== "unset" ? value : "";
+	} catch {
+		return "";
+	}
+};
+
+const secretKey = read("STRIPE_SECRET_KEY");
+const webhookSecret = read("COMMERCE_WEBHOOK_SECRET") || "whsec_dev_secret";
+
+export const devPaymentProvider = secretKey ? null : memoryProvider({ webhookSecret });
+export const paymentProvider = devPaymentProvider ?? stripeProvider({ secretKey, webhookSecret });
+`;
+}
+
+export function renderNotificationsTs(): string {
+	return `import type { NotificationProvider } from "@saastemly/better-commerce/providers/notification";
+import type { Emailer } from "@saastemly/better-email";
+
+/**
+ * betterCommerce's notifications through the ONE emailer, so an order
+ * confirmation goes out with the same sender and lands in the same log as a
+ * sign-in code.
+ */
+export const emailNotifications = (emailer: Emailer): NotificationProvider => ({
+	id: "email",
+	channels: ["email"],
+	transport: emailer.transport.transport === "none" ? "none" : "live",
+	async send(message) {
+		if (message.channel !== "email") return { id: "", status: "failed", error: "email only" };
+		// \`data\` is the rendered content: subject, text, and html when a template made one.
+		const result = await emailer.send({
+			to: message.to,
+			subject: message.data.subject,
+			text: message.data.text,
+			...(message.data.html ? { html: message.data.html } : {}),
+			kind: \`notification:\${message.template}\`,
+		});
+		return { id: result.id, status: result.status, ...(result.error ? { error: result.error } : {}) };
+	},
+});
+`;
+}
+
+/**
+ * Which chain, and who mints. Written once, then yours.
+ *
+ * The default mints NOTHING and says so: a shop that has not chosen a chain
+ * has not chosen one, and a fulfilment row claiming a token exists when it
+ * does not is a lie with a customer attached. Swap `recordedMint()` for a
+ * real provider when you have decided, and every past order keeps working
+ * because the choice lives on the line, not in the catalogue.
+ */
+export function renderMintTs(): string {
+	return `import { type MintProvider, recordedMint } from "@saastemly/better-commerce/plugins/nft";
+
+/**
+ * Where a token comes from.
+ *
+ * \`recordedMint()\` is the honest default: the order is taken, the buyer's
+ * destination is recorded, the fulfilment sits \`pending\`, and nobody is told
+ * a token exists. Replace it when you have chosen a chain and a minter.
+ *
+ * OpenSea does not mint. Its API has an endpoint called \`mint\`, and what it
+ * returns is unsigned transaction data for somebody else to sign — so the
+ * only real question is who holds a key. Three shapes fit:
+ *
+ *   custodial API   one authenticated call per mint, no key here. Crossmint
+ *                   takes an EMAIL as the recipient, so a buyer who has never
+ *                   held a wallet still gets something:
+ *
+ *                     import { crossmintMint } from "@saastemly/better-commerce/providers/crossmint";
+ *                     export const mintProvider = crossmintMint({
+ *                       apiKey: env.CROSSMINT_API_KEY, chain: "base",
+ *                     });
+ *
+ *   own contract    you hold a key and sign in the worker. It lives as a
+ *                   secret, which is a real thing to weigh: a leaked key is
+ *                   not a leaked password, it is the collection. Cheapest per
+ *                   mint, and yours to keep.
+ *   signed voucher  you sign an offer and the buyer redeems it, paying the
+ *                   gas. Costs nothing per mint and needs no key at runtime,
+ *                   but the buyer needs a wallet AND has to pay — which is
+ *                   most of the audience for a "take a useless token" offer.
+ *
+ * A collection appears on OpenSea by itself once a standard contract mints on
+ * a chain OpenSea indexes; none of these needs an OpenSea account.
+ *
+ * Whichever it is, \`mint()\` must RETURN a failure rather than throw: it runs
+ * after payment, and an exception there strands a paid order.
+ */
+export const mintProvider: MintProvider = recordedMint();
+`;
+}
+
+export function renderErpTs(): string {
+	return `import { businessCentralProvider } from "@saastemly/better-commerce/providers/business-central";
+import type { FulfillmentProvider } from "@saastemly/better-commerce/plugins/fulfillments";
+import { env } from "void/env";
+
+/** A paid order becomes a Business Central sales order. Inert until all four credentials are real. */
+const read = (key: string): string => {
+	try {
+		const value = (env as Record<string, unknown>)[key];
+		return typeof value === "string" && value !== "unset" ? value : "";
+	} catch {
+		return "";
+	}
+};
+
+export const erpFulfillment = (currency: string): FulfillmentProvider =>
+	businessCentralProvider({
+		tenantId: read("BC_TENANT_ID"),
+		clientId: read("BC_CLIENT_ID"),
+		clientSecret: read("BC_CLIENT_SECRET"),
+		companyId: read("BC_COMPANY_ID"),
+		environment: read("BC_ENVIRONMENT") || "production",
+		// BC prices are in the company's local currency.
+		currency,
+	}).fulfillment();
+`;
+}

package/src/help.ts

@@ -0,0 +1,172 @@
+import color from "picocolors";
+import pkg from "../package.json" with { type: "json" };
+import { captureVoid } from "./void";
+
+/**
+ * Help that extends void's rather than replacing it.
+ *
+ * `vc --help` is void's help with a `shop` group merged into its Commands
+ * box. `vc init --help` is void's init help with a second box under it. Only
+ * when void cannot be asked does vc print its own text alone — and says why.
+ */
+
+/** What vc adds. One row per extended command; the merge reads this. */
+export const EXTENDED_ROWS: Array<[command: string, summary: string]> = [
+	["vc init", "one app, api + frontend monorepo, or strict; void init, then a form for the shop: who signs in, every Better Auth and betterCommerce plugin, payment, tax, carriers, email, DNS"],
+	["vc generate", "the files from voidcommerce.json without the form — in strict, the whole app under .vc/app"],
+	["vc dev | build | preview", "the app's own script, run where the app is — api/ for a monorepo, .vc/app for strict"],
+	["vc dist", "the deployable app as a self-contained tree — what the void-dist branch carries"],
+	["vc import", "push data/ and content/ into the running shop, as the shop itself — an upsert, safe on every deploy"],
+	["vc preflight", "is the shop ready to advertise on? every required key, and what breaks without it"],
+	["vc deploy", "preflight, then void deploy; or --cloudflare: wrangler, your own account, no Void login"],
+];
+
+const ANSI = /\x1b\[[0-9;]*[a-zA-Z]/g;
+const strip = (line: string) => line.replace(ANSI, "");
+const visible = (line: string) => strip(line).length;
+/** The text between a box line's borders, trailing space removed. */
+const inner = (line: string) => strip(line).replace(/^│/, "").replace(/│$/, "").trimEnd();
+
+const COMMAND_WIDTH = 34;
+
+function wrap(text: string, width: number): string[] {
+	const lines: string[] = [];
+	let current = "";
+	for (const raw of text.split(/\s+/).filter(Boolean)) {
+		// A word wider than the column is split, so no line ever crosses the border.
+		const pieces = raw.match(new RegExp(`.{1,${width}}`, "g")) ?? [raw];
+		for (const word of pieces) {
+			if (current && current.length + 1 + word.length > width) {
+				lines.push(current);
+				current = word;
+			} else {
+				current = current ? `${current} ${word}` : word;
+			}
+		}
+	}
+	if (current) lines.push(current);
+	return lines;
+}
+
+/** One box line: `│  text…│`, padded to the box's width. */
+export function line(text: string, width: number): string {
+	return `│${`  ${text}`.padEnd(width - 2)}│`;
+}
+
+/**
+ * A command and its description in void's two-column layout, wrapped at the
+ * description column. A box too narrow for two columns, or a command too long
+ * for its column, stacks the description beneath the command instead.
+ */
+export function row(command: string, description: string, width: number, indent = 0): string[] {
+	const pad = " ".repeat(indent);
+	const usable = width - 4 - indent;
+	const twoColumn = command.length + indent < COMMAND_WIDTH && usable - COMMAND_WIDTH >= 20;
+	// One space of margin before the border, as void leaves.
+	if (twoColumn) {
+		const parts = wrap(description, usable - COMMAND_WIDTH - 1);
+		if (parts.length === 0) parts.push("");
+		return parts.map((part, i) => line(pad + (i === 0 ? command : "").padEnd(COMMAND_WIDTH) + part, width));
+	}
+	const parts = wrap(description, Math.max(10, usable - 5));
+	return [line(pad + command, width), ...parts.map((part) => line(`${pad}    ${part}`, width))];
+}
+
+/** A clack-style box like void's own: `◇  title ───╮`, lines, `├───╯`. */
+export function box(title: string, body: string[], width: number): string {
+	const head = `◇  ${title} `;
+	return [
+		"│",
+		`${head}${"─".repeat(Math.max(0, width - head.length - 1))}╮`,
+		line("", width),
+		...body,
+		line("", width),
+		`├${"─".repeat(width - 2)}╯`,
+	].join("\n");
+}
+
+/**
+ * Void's help with vc's rows merged into the Commands box, as a `shop` group
+ * ahead of void's `help` group. Null when the output is not the box we know —
+ * then the caller prints void's help untouched and vc's after it.
+ */
+export function mergeHelp(voidHelp: string): string | null {
+	const lines = voidHelp.split("\n");
+	const start = lines.findIndex((l) => strip(l).startsWith("◇  Commands"));
+	if (start < 0) return null;
+	const end = lines.findIndex((l, i) => i > start && strip(l).startsWith("├"));
+	if (end < 0) return null;
+	const width = visible(lines[start]!);
+
+	let at = lines.findIndex((l, i) => i > start && i < end && inner(l) === "  help");
+	if (at < 0) at = end;
+
+	const group = [
+		line(color.bold("shop"), width + (color.bold("shop").length - "shop".length)),
+		...EXTENDED_ROWS.flatMap(([command, summary]) => row(command, summary, width)),
+		line("", width),
+	];
+	return [...lines.slice(0, at), ...group, ...lines.slice(at)].join("\n");
+}
+
+/** What vc prints when void cannot be asked. */
+export function standaloneHelp(reason: string): string {
+	return [
+		"",
+		`${color.bold("vc")} — Void, with a shop in it.   ${color.dim(reason)}`,
+		"",
+		...EXTENDED_ROWS.map(([command, summary]) => `  ${color.cyan(command.padEnd(12))} ${summary}`),
+		`  ${color.dim("vc <anything>")} passes through to void: dev, build, deploy, db, gen …`,
+		"",
+	].join("\n");
+}
+
+export async function fullHelp(): Promise<number> {
+	const captured = await captureVoid(["--help"]);
+	if (!captured) {
+		console.log(standaloneHelp("void is not installed here: bun add -d void"));
+		return 0;
+	}
+	const merged = mergeHelp(captured.out);
+	if (merged) {
+		process.stdout.write(merged);
+	} else {
+		process.stdout.write(captured.out);
+		console.log(standaloneHelp("and, from vc:"));
+	}
+	return captured.code;
+}
+
+/** `vc init --help`: void's init help, then what vc adds, in the same style. */
+export async function initHelp(): Promise<number> {
+	const captured = await captureVoid(["init", "--help"]);
+	const width = captured ? Math.max(40, ...captured.out.split("\n").map(visible)) : 80;
+	const ours = box("vc init", [
+		line("Everything void init does, then a form for the shop.", width),
+		line("", width),
+		line(color.bold("Usage"), width),
+		...row("vc init", "asks the layout, runs void init where it is needed, then the form", width, 2),
+		...row("vc init --layout app", "one Void app: API and the generated storefront and panel, on Workers", width, 2),
+		...row("vc init --layout monorepo", "api/ on Workers with the panel, frontend/ on GitHub Pages", width, 2),
+		...row("vc init --layout strict", "experimental: only the manifest, data, content, branding and migrations are yours; the app is generated under .vc/app", width, 2),
+		...row("vc init --agents | --tsconfig | --github", "void's partial modes, handed to void unchanged", width, 2),
+		line("", width),
+		line(color.bold("Writes"), width),
+		...row("voidcommerce.json", "the answers; run vc init again to change them", width, 2),
+		...row("auth.ts, env.ts, .env.example", "regenerated from the answers each time", width, 2),
+		...row(".env.production, lib/deploy/", "", width, 2),
+		...row(".env, lib/domain.ts, lib/payment.ts", "written once, then yours — never overwritten", width, 2),
+		...row("lib/notifications.ts, lib/erp.ts", "", width, 2),
+	], width);
+	// void's box may or may not end in a newline; ours starts on its own line either way.
+	if (captured) process.stdout.write(captured.out.replace(/\n*$/, "\n"));
+	console.log(ours);
+	return captured?.code ?? 0;
+}
+
+export async function version(): Promise<number> {
+	const captured = await captureVoid(["--version"]);
+	console.log(`vc ${pkg.version}`);
+	console.log(captured ? `void ${captured.out.trim()}` : "void not installed here");
+	return 0;
+}

package/src/import.ts

@@ -0,0 +1,237 @@
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import color from "picocolors";
+import { box, line, row } from "./help";
+import { has } from "./manifest";
+import { type Project, findProject } from "./project";
+import { productionEnv } from "./deploy/preflight";
+
+/**
+ * `vc import` — push what is in the repository into the running shop.
+ *
+ * ── Why the catalogue is not a migration ─────────────────────────────────
+ *
+ * The obvious place for products is a seed or a data migration, and it is
+ * the wrong place. A catalogue is not schema: it changes on a different
+ * clock, it is edited by people who do not deploy, and putting it in
+ * `db/migrations/` makes every future deploy re-verify megabytes of SQL that
+ * has nothing to do with the schema.
+ *
+ * So it is data in the repository and an UPSERT over HTTP. The same
+ * operation runs in development and in production, which is the actual
+ * argument: a seed script that only ever ran on a developer's machine is a
+ * second, weaker copy of the real thing, and it is always the copy that has
+ * the bug.
+ *
+ * ── Who it authenticates as ──────────────────────────────────────────────
+ *
+ * The deployment, not a person. `SYSTEM_API_KEY` is the system identity's
+ * key, so filling a shop needs nobody to sign in anywhere — which is what
+ * makes "deploy means live" true rather than aspirational.
+ */
+
+/** What the catalogue push answers with — a report, nested by what was written. */
+interface Counts {
+	created?: number;
+	updated?: number;
+	unchanged?: number;
+	written?: number;
+}
+interface Pushed {
+	report?: { categories?: Counts; products?: Counts; prices?: Counts; addons?: Counts };
+	/** The content imports answer flatter than the catalogue does. */
+	created?: number;
+	updated?: number;
+	error?: string;
+}
+
+/** "3 created, 1 updated" — and nothing at all when nothing happened. */
+function describe(counts: Counts | undefined): string {
+	if (!counts) return "";
+	const parts = [
+		counts.created ? `${counts.created} created` : "",
+		counts.updated ? `${counts.updated} updated` : "",
+		counts.written ? `${counts.written} written` : "",
+		counts.unchanged ? `${counts.unchanged} unchanged` : "",
+	].filter(Boolean);
+	return parts.join(", ") || "nothing to do";
+}
+
+/** Where the shop is, in order of what a person most likely means. */
+function resolveTarget(project: Project, args: string[]): { url: string; how: string } {
+	const flag = args.indexOf("--url");
+	if (flag >= 0 && args[flag + 1]) return { url: args[flag + 1]!.replace(/\/$/, ""), how: "--url" };
+	if (process.env["APP_URL"]) return { url: process.env["APP_URL"].replace(/\/$/, ""), how: "APP_URL" };
+	if (args.includes("--local")) return { url: "http://127.0.0.1:5173", how: "--local" };
+
+	// .env.production carries the domain as a committed plaintext value.
+	const domain = productionEnv(project.appDir).get("SHOP_DOMAIN") ?? project.manifest.shop.domain;
+	const host = project.manifest.layout === "app" ? domain : `api.${domain}`;
+	return { url: `https://${host}`, how: "the shop's own domain" };
+}
+
+async function post(url: string, key: string, body: unknown): Promise<{ ok: boolean; status: number; body: Pushed & { error?: string } }> {
+	let response: Response;
+	try {
+		response = await fetch(url, {
+			method: "POST",
+			headers: { "content-type": "application/json", "x-system-key": key },
+			body: JSON.stringify(body),
+		});
+	} catch (error) {
+		return { ok: false, status: 0, body: { error: error instanceof Error ? error.message : String(error) } };
+	}
+	const parsed = (await response.json().catch(() => ({}))) as Pushed & { message?: string };
+	return { ok: response.ok, status: response.status, body: { ...parsed, error: parsed.error ?? parsed.message } };
+}
+
+/** Read a JSON file, or nothing if there is none. */
+async function readJson<T>(path: string): Promise<T | null> {
+	if (!existsSync(path)) return null;
+	try {
+		return JSON.parse(await readFile(path, "utf8")) as T;
+	} catch (error) {
+		throw new Error(`${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+export async function importCommand(args: string[]): Promise<number> {
+	const project = await findProject();
+	if (!project) {
+		console.error("vc: no voidcommerce.json here.");
+		return 1;
+	}
+	const dry = args.includes("--dry-run");
+	const key = process.env["SYSTEM_API_KEY"];
+	if (!key && !dry) {
+		console.error(
+			"vc: SYSTEM_API_KEY is not in this shell.\n\n" +
+				"  It is the deployment's own identity, so the import authenticates as the\n" +
+				"  shop rather than as you. It is a worker secret; export it here:\n\n" +
+				"    SYSTEM_API_KEY=… vc import\n",
+		);
+		return 1;
+	}
+
+	const { url, how } = resolveTarget(project, args);
+	if (!dry) console.log(`${color.dim("→")} ${url} ${color.dim(`(${how})`)}\n`);
+
+	/**
+	 * Who does the shop think we are? Asked once, up front: a wrong key is
+	 * otherwise a 401 on every push, which is four confusing failures instead
+	 * of one clear one. Skipped entirely for a dry run, which reads files and
+	 * needs no shop to be running.
+	 */
+	if (!dry) {
+		let whoami: Response;
+		try {
+			whoami = await fetch(`${url}/api/auth/system/whoami`, { headers: { "x-system-key": key! } });
+		} catch (error) {
+			console.error(
+				`${color.red("✗")} could not reach ${url}: ${error instanceof Error ? error.message : String(error)}\n` +
+					`  Is the shop running? \`vc dev\` serves it locally; --local points here.\n`,
+			);
+			return 1;
+		}
+		if (!whoami.ok) {
+			console.error(
+				`${color.red("✗")} the shop refused the system key (HTTP ${whoami.status}).\n` +
+					`  Is SYSTEM_API_KEY the one this deployment was given?\n`,
+			);
+			return 1;
+		}
+		console.log(`${color.green("✓")} authenticated as the system identity`);
+	}
+
+	const root = project.root;
+	const products = await readJson<unknown[]>(join(root, "data", "catalog.json"));
+	const categories = await readJson<unknown[]>(join(root, "data", "categories.json"));
+	const faqs = has(project.manifest, "faqs") ? await readJson<unknown[]>(join(root, "content", "faqs.json")) : null;
+	const posts = has(project.manifest, "blogs") ? await readJson<unknown[]>(join(root, "content", "posts.json")) : null;
+
+	if (!products && !faqs?.length && !posts?.length) {
+		console.log(
+			`\n${color.yellow("Nothing to import.")} data/catalog.json is absent and the content files are empty.\n` +
+				`Products go in data/catalog.json as a JSON array; \`vc import --dry-run\` checks it without pushing.\n`,
+		);
+		return 0;
+	}
+
+	if (dry) {
+		console.log(`\n${color.dim("--dry-run: nothing was pushed.")}`);
+		console.log(`  ${products?.length ?? 0} products, ${categories?.length ?? 0} categories`);
+		console.log(`  ${faqs?.length ?? 0} FAQ entries, ${posts?.length ?? 0} posts\n`);
+		return 0;
+	}
+
+	let failed = false;
+
+	if (products) {
+		/**
+		 * Categories travel WITH the products in one call, because a product
+		 * naming a category that does not exist yet is the ordering bug this
+		 * would otherwise have.
+		 */
+		const result = await post(`${url}/api/auth/commerce/admin/catalog-import/push`, key!, {
+			source: "devprints",
+			...(categories ? { categories } : {}),
+			products,
+			// Never true by default: a partial file would deactivate a shop's
+			// entire catalogue, and the file is edited by hand.
+			...(args.includes("--deactivate-missing") ? { deactivateMissing: true } : {}),
+		});
+		if (result.ok) {
+			// The push answers with a report per thing it wrote, and reading it
+			// at the top level is how this said "0 created" while writing seven.
+			const report = result.body.report ?? {};
+			console.log(`${color.green("✓")} products:   ${describe(report.products)}`);
+			if (report.categories) console.log(`${color.green("✓")} categories: ${describe(report.categories)}`);
+			if (report.prices) console.log(`${color.green("✓")} prices:     ${describe(report.prices)}`);
+			if (report.addons) console.log(`${color.green("✓")} addons:     ${describe(report.addons)}`);
+		} else {
+			console.error(`${color.red("✗")} catalogue: ${result.body.error ?? `HTTP ${result.status}`}`);
+			failed = true;
+		}
+	}
+
+	for (const [label, rows, path] of [
+		["FAQ", faqs, "/api/auth/faqs/import"],
+		["posts", posts, "/api/auth/blog/import"],
+	] as const) {
+		if (!rows?.length) continue;
+		const result = await post(`${url}${path}`, key!, { entries: rows, posts: rows });
+		if (result.ok) {
+			console.log(`${color.green("✓")} ${label}: ${describe(result.body)}`);
+		} else {
+			console.error(`${color.red("✗")} ${label}: ${result.body.error ?? `HTTP ${result.status}`}`);
+			failed = true;
+		}
+	}
+
+	if (failed) {
+		console.error(`\n${color.red("Some of it did not land.")} The import is an upsert, so fixing the cause and running it again is safe.\n`);
+		return 1;
+	}
+	console.log(`\n${color.green("Imported.")} It is an upsert, so running it again costs one pass and changes nothing.\n`);
+	return 0;
+}
+
+export async function importHelp(): Promise<number> {
+	const width = 80;
+	console.log(
+		box("vc import", [
+			line("Push data/ and content/ into the running shop, as the shop itself.", width),
+			line("", width),
+			...row("SYSTEM_API_KEY=… vc import", "to the shop's own domain", width, 2),
+			...row("… vc import --local", "to http://127.0.0.1:5173, for a dev server", width, 2),
+			...row("… vc import --url <url>", "somewhere else; APP_URL does the same", width, 2),
+			...row("vc import --dry-run", "count what would be pushed, push nothing", width, 2),
+			...row("… vc import --deactivate-missing", "also switch off products absent from the file — never the default, because a partial file would empty the shop", width, 2),
+			line("", width),
+			line("An upsert, so it is safe on every deploy and costs one pass when nothing", width),
+			line("changed. It authenticates as the system identity, so nobody signs in.", width),
+		], width),
+	);
+	return 0;
+}