@shop-on/theme-cli 0.0.0-stage → 0.2.0

package/dist/LICENSE.md

@@ -0,0 +1,39 @@
+# Cody Theme Development License
+
+Copyright (c) 2026 Cody LLC. All rights reserved except as granted below.
+
+"The Software" is this package, its source, and its documentation. "The
+Platform" is Cody, the commerce platform operated by Cody LLC.
+
+## 1. Grant
+
+You may use, copy and modify the Software, and distribute modified copies, solely
+to develop, test, and distribute themes, apps and other extensions that run on
+the Platform.
+
+## 2. Restrictions
+
+You may not:
+
+1. use the Software, or anything derived from it, with any commerce platform,
+   storefront or hosting service other than the Platform;
+2. use the Software to build a product that competes with the Platform;
+3. sublicense the Software, or distribute it other than as part of a theme,
+   app or extension for the Platform;
+4. remove or alter this license or any copyright notice in the Software.
+
+## 3. Your work
+
+Themes, apps and extensions you build with the Software are yours. The parts of
+the Software they include stay under this license.
+
+## 4. Termination
+
+This license ends automatically if you break any of its terms. You must then
+stop using the Software and delete your copies of it.
+
+## 5. No warranty
+
+The Software is provided "as is", without warranty of any kind. Cody LLC is not
+liable for any claim, damages or other liability arising from the Software or
+its use.

package/dist/audit/command.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+import { MissingEnvError, loadThemeEnv } from "./env.mjs";
+import { openBrowser } from "./lighthouse.mjs";
+import { average, pageScore, verdict } from "./score.mjs";
+import { BAR, formatReport } from "./report.mjs";
+import { auditRoutes, checkRoutes } from "./routes.mjs";
+import { startBuiltServer } from "./server.mjs";
+import { fetchStoreData, storeProblems } from "./store.mjs";
+import { runThemeBuild } from "../theme/build.mjs";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { parseArgs, styleText } from "node:util";
+//#region src/audit/command.ts
+const USAGE = `usage: shop-on theme audit [--theme <dir>] [--runs 3] [--json] [--skip-build]
+
+  --theme <dir>   the theme to audit (default: the current directory)
+  --runs <n>      Lighthouse runs per page and form factor; the median counts (default: 3)
+  --json          print the report as JSON, for CI
+  --skip-build    serve the existing .output instead of running \`pnpm build\``;
+const LIGHTHOUSE_PAGES = [
+	"index",
+	"product",
+	"collection"
+];
+const FORM_FACTORS = ["mobile", "desktop"];
+const progress = (text) => styleText("dim", `› ${text}`);
+const processIo = {
+	out: (text) => process.stdout.write(`${text}\n`),
+	err: (text) => process.stderr.write(`${text}\n`)
+};
+const defaultDeps = {
+	fetchStoreData,
+	build: runThemeBuild,
+	startServer: startBuiltServer,
+	openBrowser
+};
+/** Runs the audit and returns the exit code. */
+async function runAudit({ argv, cwd = process.cwd(), io = processIo, deps: overrides = {}, processEnv = process.env }) {
+	const deps = {
+		...defaultDeps,
+		...overrides
+	};
+	let values;
+	try {
+		({values} = parseArgs({
+			args: argv,
+			options: {
+				theme: { type: "string" },
+				runs: {
+					type: "string",
+					default: "3"
+				},
+				json: {
+					type: "boolean",
+					default: false
+				},
+				"skip-build": {
+					type: "boolean",
+					default: false
+				},
+				help: {
+					type: "boolean",
+					short: "h",
+					default: false
+				}
+			}
+		}));
+	} catch (err) {
+		io.err(`${err.message}\n\n${USAGE}`);
+		return 2;
+	}
+	if (values.help) {
+		io.out(USAGE);
+		return 0;
+	}
+	const runs = Number(values.runs);
+	if (!Number.isInteger(runs) || runs < 1) {
+		io.err(`--runs must be a whole number of 1 or more\n\n${USAGE}`);
+		return 2;
+	}
+	const themeDir = path.resolve(cwd, values.theme ?? ".");
+	const report = {
+		ok: false,
+		problems: [],
+		routes: [],
+		skippedRoutes: [],
+		lighthouse: null
+	};
+	const finish = () => {
+		report.ok = report.problems.length === 0;
+		io.out(values.json ? JSON.stringify(report, null, 2) : formatReport(report));
+		return report.ok ? 0 : 1;
+	};
+	const fail = (...problems) => {
+		report.problems.push(...problems);
+		return finish();
+	};
+	if (!existsSync(path.join(themeDir, "package.json"))) return fail(`${themeDir} is not a theme: it has no package.json`);
+	let env;
+	try {
+		({env} = loadThemeEnv(themeDir, processEnv));
+	} catch (err) {
+		if (err instanceof MissingEnvError) return fail(`the theme's storefront credentials are incomplete: ${err.message}`);
+		throw err;
+	}
+	io.err(progress(`reading the store at ${env.STOREFRONT_API_URL}`));
+	let store;
+	try {
+		store = await deps.fetchStoreData(env);
+	} catch (err) {
+		return fail(err.message);
+	}
+	const missing = storeProblems(store);
+	if (missing.length) return fail(...missing.map((m) => `store ${env.STORE_SLUG}: ${m}`));
+	const cleanups = [];
+	const cleanUp = () => Promise.allSettled(cleanups.splice(0).reverse().map((c) => c()));
+	const exitCode = (signal) => signal === "SIGINT" ? 130 : 143;
+	const force = (signal) => process.exit(exitCode(signal));
+	const onSignal = (signal) => {
+		process.on("SIGINT", force);
+		process.on("SIGTERM", force);
+		cleanUp().finally(() => process.exit(exitCode(signal)));
+	};
+	process.once("SIGINT", onSignal);
+	process.once("SIGTERM", onSignal);
+	try {
+		if (!values["skip-build"]) {
+			io.err(progress("building"));
+			const code = await deps.build(themeDir);
+			if (code !== 0) return fail(`the build failed (exit ${code})`);
+		}
+		io.err(progress("starting the built server"));
+		let server;
+		try {
+			server = await deps.startServer(themeDir, env);
+		} catch (err) {
+			return fail(`the built server did not start: ${err.message}`);
+		}
+		cleanups.push(() => server.stop());
+		const { routes, skipped } = auditRoutes(store);
+		report.routes = await checkRoutes(server.url, routes);
+		report.skippedRoutes = skipped;
+		for (const r of report.routes.filter((r) => !r.ok)) report.problems.push(`${r.template} ${r.path} answered ${r.status ?? r.error}, expected ${r.expect}`);
+		const pages = LIGHTHOUSE_PAGES.map((page) => report.routes.find((r) => r.template === page));
+		if (pages.some((p) => !p.ok)) {
+			report.problems.push("Lighthouse skipped: a page it measures did not answer 200");
+			return finish();
+		}
+		const browser = await deps.openBrowser();
+		cleanups.push(() => browser.close());
+		const measured = [];
+		for (const page of pages) for (const formFactor of FORM_FACTORS) {
+			const url = new URL(page.path, server.url).href;
+			const entry = {
+				page: page.template,
+				url,
+				formFactor,
+				runs: []
+			};
+			for (let i = 1; i <= runs; i++) {
+				io.err(progress(`lighthouse ${page.template} ${formFactor} ${i}/${runs}`));
+				entry.runs.push(await browser.run(url, formFactor));
+			}
+			measured.push(entry);
+		}
+		const scored = measured.map(pageScore);
+		const avg = average(scored);
+		report.lighthouse = {
+			runs,
+			pages: scored,
+			average: avg,
+			bar: BAR
+		};
+		report.problems.push(...verdict(avg));
+		return finish();
+	} catch (err) {
+		return fail(err.message);
+	} finally {
+		process.off("SIGINT", onSignal);
+		process.off("SIGTERM", onSignal);
+		await cleanUp();
+	}
+}
+//#endregion
+export { USAGE, processIo, runAudit };

package/dist/audit/env.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { parseEnv } from "node:util";
+//#region src/audit/env.ts
+/** What the theme server reads from its environment — the starter's `.env.example`. */
+const THEME_ENV_KEYS = [
+	"STOREFRONT_API_URL",
+	"STOREFRONT_CLIENT_ID",
+	"STOREFRONT_CLIENT_SECRET",
+	"STORE_SLUG",
+	"STOREFRONT_CUSTOMER_SESSION_SECRET"
+];
+var MissingEnvError = class extends Error {
+	missing;
+	files;
+	constructor(missing, files) {
+		const where = files.length ? files.join(", ") : "no .env file found";
+		super(`missing ${missing.join(", ")} (read: ${where})`);
+		this.missing = missing;
+		this.files = files;
+		this.name = "MissingEnvError";
+	}
+};
+/**
+* The `.env` files `pnpm dev` reads for this theme, in precedence order: the
+* theme's own, then — for a theme inside a pnpm workspace (this repo's
+* `themes/*`) — the workspace root's. Same rule as `createThemeViteConfig`.
+*/
+function themeEnvFiles(themeDir) {
+	return [".env", ...existsSync(path.join(themeDir, "../../pnpm-workspace.yaml")) ? ["../../.env"] : []].map((f) => path.resolve(themeDir, f));
+}
+/**
+* The theme server's variables only: the process environment first (CI sets
+* them there), then the first `.env` file that sets each one. Throws naming
+* the missing variables, never a value.
+*/
+function loadThemeEnv(themeDir, processEnv = process.env) {
+	const files = themeEnvFiles(themeDir).filter((f) => existsSync(f));
+	const parsed = files.map((f) => parseEnv(readFileSync(f, "utf-8")));
+	const env = {};
+	for (const key of THEME_ENV_KEYS) {
+		const value = processEnv[key] || parsed.find((p) => p[key])?.[key];
+		if (value) env[key] = value;
+	}
+	const missing = THEME_ENV_KEYS.filter((key) => !env[key]);
+	if (missing.length) throw new MissingEnvError(missing, files);
+	return {
+		env,
+		files
+	};
+}
+/** The values to scrub from anything a child process printed. */
+function secretValues(env) {
+	return [
+		env.STOREFRONT_CLIENT_ID,
+		env.STOREFRONT_CLIENT_SECRET,
+		env.STOREFRONT_CUSTOMER_SESSION_SECRET
+	];
+}
+function redact(text, secrets) {
+	return secrets.filter(Boolean).reduce((out, s) => out.split(s).join("[redacted]"), text);
+}
+//#endregion
+export { MissingEnvError, THEME_ENV_KEYS, loadThemeEnv, redact, secretValues, themeEnvFiles };

package/dist/audit/lighthouse.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+//#region src/audit/lighthouse.ts
+/**
+* Headless Chrome plus Lighthouse, both loaded on first use so the rest of the
+* CLI never pays for them. Chrome is launched once; Lighthouse resets storage
+* before every run, so runs don't share a warm cache.
+*/
+async function openBrowser() {
+	const [{ launch }, { default: lighthouse, defaultConfig, desktopConfig }, constants] = await Promise.all([
+		import("chrome-launcher"),
+		import("lighthouse"),
+		import("lighthouse/core/config/constants.js")
+	]);
+	const chrome = await launch({
+		chromeFlags: [
+			"--headless=new",
+			"--no-first-run",
+			"--no-default-browser-check"
+		],
+		handleSIGINT: false,
+		logLevel: "silent"
+	});
+	const presets = {
+		mobile: defaultConfig,
+		desktop: desktopConfig
+	};
+	const config = (formFactor) => ({
+		...presets[formFactor],
+		settings: {
+			...presets[formFactor].settings,
+			formFactor,
+			screenEmulation: constants.screenEmulationMetrics[formFactor],
+			onlyCategories: ["performance", "accessibility"]
+		}
+	});
+	return {
+		async run(url, formFactor) {
+			const result = await lighthouse(url, {
+				port: chrome.port,
+				logLevel: "error",
+				output: "json"
+			}, config(formFactor));
+			if (!result) throw new Error(`lighthouse returned nothing for ${url}`);
+			return scoresOf(result.lhr, formFactor);
+		},
+		async close() {
+			chrome.kill();
+		}
+	};
+}
+/** A run's scores, after checking the report ran the way it was asked to. */
+function scoresOf(lhr, formFactor) {
+	if (lhr.runtimeError) throw new Error(`lighthouse ${lhr.finalDisplayedUrl}: ${lhr.runtimeError.message}`);
+	const { screenEmulation, formFactor: ran } = lhr.configSettings;
+	if (screenEmulation.disabled || ran !== formFactor || screenEmulation.mobile !== (formFactor === "mobile")) throw new Error(`lighthouse ran without ${formFactor} screen emulation (formFactor ${ran}, emulation ${screenEmulation.disabled ? "disabled" : `${screenEmulation.width}px`})`);
+	const score = (id) => {
+		const value = lhr.categories[id]?.score;
+		if (value == null) throw new Error(`lighthouse ${lhr.finalDisplayedUrl}: no ${id} score`);
+		return Math.round(value * 100);
+	};
+	return {
+		performance: score("performance"),
+		accessibility: score("accessibility")
+	};
+}
+//#endregion
+export { openBrowser, scoresOf };

package/dist/audit/report.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { display } from "./score.mjs";
+import { styleText } from "node:util";
+//#region src/audit/report.ts
+const BAR = {
+	performance: 60,
+	accessibility: 90
+};
+const scoreCell = (value, bar, width) => styleText(value < bar ? "red" : "green", String(display(value)).padStart(width));
+function formatReport(report) {
+	const out = [styleText("bold", "Routes")];
+	const label = Math.max(...report.routes.map((r) => r.template.length), 0);
+	for (const r of report.routes) {
+		const mark = r.ok ? styleText("green", "✓") : styleText("red", "✖");
+		const status = r.status === null ? styleText("red", "ERR") : String(r.status);
+		const why = r.ok ? "" : styleText("dim", ` expected ${r.expect}${r.error ? `: ${r.error}` : ""}`);
+		out.push(`  ${mark} ${status} ${styleText("yellow", r.template.padEnd(label))} ${styleText("cyan", r.path)}${why}`);
+	}
+	for (const s of report.skippedRoutes) out.push(styleText("dim", `  - skipped ${s.template}: ${s.reason}`));
+	if (report.lighthouse) {
+		const { pages, average, runs } = report.lighthouse;
+		out.push("", styleText("bold", `Lighthouse (median of ${runs} run${runs === 1 ? "" : "s"})`));
+		out.push(styleText("dim", `  ${"page".padEnd(12)} ${"form".padEnd(8)} ${"perf".padStart(5)} ${"a11y".padStart(5)}`));
+		for (const p of pages) out.push(`  ${styleText("yellow", p.page.padEnd(12))} ${p.formFactor.padEnd(8)} ${scoreCell(p.performance, 60, 5)} ${scoreCell(p.accessibility, 90, 5)}`);
+		out.push(`  ${styleText("bold", "average".padEnd(21))} ${scoreCell(average.performance, 60, 5)} ${scoreCell(average.accessibility, 90, 5)}` + styleText("dim", `   bar: perf ≥ 60, a11y ≥ 90`));
+	}
+	out.push("");
+	if (report.ok) out.push(styleText(["green", "bold"], "✓ meets the quality bar"));
+	else {
+		for (const p of report.problems) out.push(`${styleText("red", "✖")} ${p}`);
+		const n = report.problems.length;
+		out.push(styleText(["red", "bold"], `✖ ${n} problem${n === 1 ? "" : "s"}`));
+	}
+	return out.join("\n");
+}
+//#endregion
+export { BAR, formatReport };

package/dist/audit/routes.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+//#region src/audit/routes.ts
+/** An unknown path, so a theme that answers 200 for everything is caught. */
+const UNKNOWN_PATH = "/shop-on-audit-no-such-page";
+/**
+* Every root template the starter skeleton defines, at a URL this store can
+* fill. `password` is left out: it renders only while protection is on, and
+* the audit refuses to run then.
+*/
+function auditRoutes(store) {
+	const routes = [{
+		template: "index",
+		path: "/",
+		expect: 200
+	}];
+	const skipped = [];
+	const add = (template, handle, path) => {
+		if (handle) routes.push({
+			template,
+			path: path(encodeURIComponent(handle)),
+			expect: 200
+		});
+		else skipped.push({
+			template,
+			reason: `the store has no ${template}`
+		});
+	};
+	add("product", store.product, (h) => `/products/${h}`);
+	add("collection", store.collection, (h) => `/collections/${h}`);
+	routes.push({
+		template: "list-collections",
+		path: "/collections",
+		expect: 200
+	});
+	routes.push({
+		template: "search",
+		path: `/search?q=${encodeURIComponent(store.product ?? "a")}`,
+		expect: 200
+	});
+	routes.push({
+		template: "cart",
+		path: "/cart",
+		expect: 200
+	});
+	add("page", store.page, (h) => `/pages/${h}`);
+	add("blog", store.blog, (h) => `/blogs/${h}`);
+	add("article", store.article, (h) => `/blogs/${encodeURIComponent(store.blog ?? "")}/articles/${h}`);
+	add("policy", store.policy, (h) => `/policies/${h}`);
+	routes.push({
+		template: "404",
+		path: UNKNOWN_PATH,
+		expect: 404
+	});
+	return {
+		routes,
+		skipped
+	};
+}
+/**
+* Exactly the expected status passes. A redirect is a failure, not a pass: a
+* template that bounces to `/` or `/password` never rendered.
+*/
+function evaluateRoute(route, outcome) {
+	if (outcome instanceof Error) return {
+		...route,
+		status: null,
+		error: outcome.message,
+		ok: false
+	};
+	return {
+		...route,
+		status: outcome,
+		ok: outcome === route.expect
+	};
+}
+async function checkRoutes(baseUrl, routes, fetchImpl = fetch) {
+	const results = [];
+	for (const route of routes) {
+		const outcome = await fetchImpl(new URL(route.path, baseUrl), {
+			redirect: "manual",
+			signal: AbortSignal.timeout(3e4)
+		}).then(async (res) => {
+			await res.body?.cancel();
+			return res.status;
+		}, (err) => err instanceof Error ? err : new Error(String(err)));
+		results.push(evaluateRoute(route, outcome));
+	}
+	return results;
+}
+//#endregion
+export { UNKNOWN_PATH, auditRoutes, checkRoutes, evaluateRoute };

package/dist/audit/score.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+* The median, so one outlier run (a GC pause, a cold cache) can't move the
+* result: a single run varies 5–10 points. An even count takes the mean of the
+* middle two.
+*/
+function median(values) {
+	if (!values.length) throw new Error("median of no values");
+	const sorted = [...values].sort((a, b) => a - b);
+	const mid = Math.floor(sorted.length / 2);
+	return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+/** Each category's median per page and form factor, taken independently. */
+function pageScore(p) {
+	return {
+		...p,
+		performance: median(p.runs.map((r) => r.performance)),
+		accessibility: median(p.runs.map((r) => r.accessibility))
+	};
+}
+function average(scores) {
+	if (!scores.length) throw new Error("average of no scores");
+	const mean = (pick) => scores.reduce((sum, s) => sum + pick(s), 0) / scores.length;
+	return {
+		performance: mean((s) => s.performance),
+		accessibility: mean((s) => s.accessibility)
+	};
+}
+/** What falls short of the bar, one line each; empty when it clears. */
+function verdict(avg) {
+	const failures = [];
+	if (avg.performance < 60) failures.push(`performance ${display(avg.performance)} is under 60`);
+	if (avg.accessibility < 90) failures.push(`accessibility ${display(avg.accessibility)} is under 90`);
+	return failures;
+}
+/**
+* One decimal for display, rounded DOWN: a 59.96 average fails, so it must not
+* print as a passing 60. The verdict compares the exact mean.
+*/
+const display = (n) => Math.floor(n * 10 + 1e-9) / 10;
+//#endregion
+export { average, display, median, pageScore, verdict };