@menapo/vicss 0.0.0-stage → 1.1.0

package/dist/cli.js

@@ -0,0 +1,1311 @@
+#!/usr/bin/env node
+import { $ as isPaletteAtom, Ct as isArbitrary, D as flatLayerName, O as layerName, _ as normalizeStyle, _t as VicssError, b as resolveSystem, bt as compareStrings, c as paletteProblem, f as printTokens, l as printAtoms, t as baseTokens } from "./print-B_mn7wBu.js";
+import { _ as isSfc, c as moduleLoader, g as frameworkOf, h as extractScripts, l as resolveFile, m as detectFramework, p as configuredJsxSource, v as compileModule, y as createModuleCache } from "./pool-F3qb30Fy.js";
+import { u as baseAtoms } from "./theme-zBcr5DHi.js";
+import { C as CompileCache, D as generateTypes, _ as critical, c as scan, f as loadLibraries, h as withLibraries, i as writeIfChanged, k as codeFrame, n as snapshotRoot, p as ownPackageName, r as typesFile, t as snapshotFile, x as hashesProblem } from "./types-file-D6Iu4kzv.js";
+import { r as snapshotText } from "./snapshot-DAJ8FLU4.js";
+import { n as loadSystem, t as CONFIG_FILES } from "./config-loader-1kWS0cRU.js";
+import { createRequire } from "node:module";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { BuildEnvironment, createIdResolver, createServer, loadConfigFromFile, normalizePath, resolveConfig } from "vite";
+import process from "node:process";
+//#region src/cli/project.ts
+/**
+* What the commands share: the project's design system, loaded as the
+* plugin loads it, and a compiler that resolves imports the way the app's
+* Vite config does, so a constant read through an alias compiles in the
+* CLI as it does in the build.
+*/
+/** `--config <file>`, relative to the root; else the first `vicss.config.*` there. */
+function loadProject(io, config) {
+	return loadSystem(normalizePath(io.cwd), config, (message) => io.stderr(`${message}\n`));
+}
+/** The app's `vite.config.*`, or null when it has none; throws when it cannot be read. */
+async function loadViteConfig(root) {
+	return (await loadConfigFromFile({
+		command: "build",
+		mode: "production"
+	}, void 0, root, "silent"))?.config ?? null;
+}
+/**
+* The options the app's Vite config gives vicss's plugin, which exposes them
+* as its `api`; empty without a config or the plugin.
+*/
+async function pluginOptions(config) {
+	return await registeredOptions(config) ?? {};
+}
+/** The options of the vicss plugin the Vite config registers, or undefined when it registers none. */
+async function registeredOptions(config) {
+	for (const plugin of await flatPlugins(config?.plugins ?? [])) {
+		const api = plugin.name === "vicss" ? plugin.api : void 0;
+		if (typeof api === "object" && api !== null && "options" in api) return api.options;
+	}
+}
+/**
+* What the app's plugin would detect (PLAN §5.12): its `framework` option,
+* else the root `package.json`'s dependencies, else vanilla; JSX by the Vite
+* config's or tsconfig's import source.
+*/
+function frameworkSettings(root, config, options) {
+	return {
+		scripts: options.framework ?? detectFramework(root) ?? "vanilla",
+		jsxImportSource: configuredJsxSource(config ?? {}, root)
+	};
+}
+/**
+* The plugin's options and frameworks for `vicss types`, which writes what
+* the plugin writes: the `framework` it registers and its `types.output`.
+* A Vite config that cannot be read leaves the defaults.
+*/
+async function projectSettings(io) {
+	const root = normalizePath(io.cwd);
+	let config = null;
+	try {
+		config = await loadViteConfig(root);
+	} catch {}
+	const registered = await registeredOptions(config);
+	const options = registered ?? {};
+	return {
+		options,
+		frameworks: frameworkSettings(root, config, options),
+		registered: registered !== void 0
+	};
+}
+/**
+* Resolution as the app's build resolves: through the plugins and `resolve`
+* options of its `vite.config.*` (aliases, `vite-tsconfig-paths`, a custom
+* `resolveId`), less vicss's own plugin. They run in a dev server with no
+* HTTP server, watcher or dependency scan, so plugins applied only to builds
+* (`apply: "build"`) are left out. Without a Vite config, or when it cannot
+* be loaded, Vite's own resolver with its defaults, after a note.
+*/
+async function createResolver(io) {
+	const root = normalizePath(io.cwd);
+	const note = (what, error) => io.stderr(`vicss: ${what}, so imports resolve without its plugins and aliases: ${error instanceof Error ? error.message : String(error)}\n`);
+	let viteConfig = null;
+	try {
+		viteConfig = await loadViteConfig(root);
+	} catch (error) {
+		note("could not read the Vite config", error);
+	}
+	const frameworks = frameworkSettings(root, viteConfig, await pluginOptions(viteConfig));
+	if (viteConfig) {
+		const config = viteConfig;
+		try {
+			const server = await createServer({
+				...config,
+				configFile: false,
+				root: normalizePath(path.resolve(root, config.root ?? ".")),
+				mode: "production",
+				logLevel: "silent",
+				clearScreen: false,
+				appType: "custom",
+				plugins: (await flatPlugins(config.plugins ?? [])).filter((plugin) => !isVicss(plugin)),
+				server: {
+					...config.server,
+					middlewareMode: true,
+					ws: false,
+					watch: null,
+					hmr: false
+				},
+				optimizeDeps: {
+					...config.optimizeDeps,
+					noDiscovery: true,
+					include: []
+				}
+			});
+			const container = server.environments.client.pluginContainer;
+			return {
+				resolve: async (source, importer) => await container.resolveId(source, importer) ?? null,
+				frameworks,
+				close: () => server.close()
+			};
+		} catch (error) {
+			note("could not start the Vite config's plugins", error);
+		}
+	}
+	const config = await resolveConfig({
+		root,
+		configFile: false,
+		logLevel: "silent",
+		...viteConfig?.resolve ? { resolve: viteConfig.resolve } : {}
+	}, "build");
+	const environment = new BuildEnvironment("client", config);
+	const resolveId = createIdResolver(config, {});
+	return {
+		resolve: async (source, importer) => {
+			const id = await resolveId(environment, source, importer);
+			return id === void 0 ? null : { id };
+		},
+		frameworks,
+		close: async () => {}
+	};
+}
+/** `plugins` as Vite flattens them: nested arrays and promises, falsy entries dropped. */
+async function flatPlugins(options) {
+	const out = [];
+	for (const item of options) {
+		const option = await item;
+		if (Array.isArray(option)) out.push(...await flatPlugins(option));
+		else if (option) out.push(option);
+	}
+	return out;
+}
+/** vicss's own plugins: the CLI compiles itself, and they would write the types file. */
+const isVicss = (plugin) => plugin.name === "vicss" || plugin.name.startsWith("vicss:");
+/** Every call one file's compile refused, thrown together once the file is done. */
+var FileErrors = class extends Error {
+	errors;
+	constructor(errors) {
+		super(errors.map((error) => error.message).join("\n"));
+		this.name = "FileErrors";
+		this.errors = errors;
+	}
+};
+function createCompiler(system, resolve, root, inspect, frameworks = {
+	scripts: "vanilla",
+	jsxImportSource: void 0
+}) {
+	const cache = createModuleCache();
+	const warnings = /* @__PURE__ */ new Map();
+	const pkg = ownPackageName(root);
+	return {
+		warnings,
+		async compile(id, code, script) {
+			const resolutions = {};
+			const own = [];
+			const errors = [];
+			const result = await compileModule(code, {
+				system,
+				id,
+				root,
+				...pkg ? { package: pkg } : {},
+				importSources: system.config.importSources ?? [],
+				loadModule: moduleLoader(resolve, resolutions),
+				framework: frameworkOf(id, code, frameworks),
+				...script ? {
+					lang: script.lang,
+					functionBody: script.functionBody === true
+				} : {},
+				sourceMap: false,
+				cache,
+				warn: (message, warning) => own.push({
+					message,
+					...warning
+				}),
+				onError: (error) => errors.push(error)
+			});
+			if (own.length > 0) warnings.set(id, [...warnings.get(id) ?? [], ...own]);
+			inspect?.(id, result);
+			if (errors.length > 0) throw new FileErrors(errors);
+			return {
+				...result,
+				resolutions,
+				warnings: own.map((w) => w.message)
+			};
+		}
+	};
+}
+/**
+* Runs `write`, which writes `file`, and reports a failure (a missing
+* permission, a file where a directory should be) as `vicss: cannot write …`
+* rather than a stack trace. Returns whether it succeeded.
+*/
+function writeOutput(io, file, write) {
+	try {
+		write();
+		return true;
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		io.stderr(`vicss: cannot write ${relativeTo(normalizePath(io.cwd), normalizePath(file))}: ${reason}\n`);
+		return false;
+	}
+}
+/** `src/card.ts` for an id under the root; other ids as they are. */
+function relativeTo(root, file) {
+	const rel = path.relative(root, file);
+	return rel && !rel.startsWith("..") && !path.isAbsolute(rel) ? normalizePath(rel) : file;
+}
+//#endregion
+//#region src/cli/report.ts
+/**
+* Diagnostics as the CLI prints them: `file:line:column severity
+* vicss(CODE): message`, the hint and a code frame, as JSON, or as GitHub
+* Actions annotations, which put each one on its line in a pull request.
+*/
+/** The diagnostics of anything a command caught: one, or one per call a file refused. */
+function diagnosticsOf(error, root, severity = "error", file) {
+	return error instanceof FileErrors ? error.errors.map((each) => diagnosticOf(each, root, severity, file)) : [diagnosticOf(error, root, severity, file)];
+}
+/** A diagnostic for anything a command caught; other errors become `INTERNAL`. */
+function diagnosticOf(error, root, severity = "error", file) {
+	if (!(error instanceof VicssError)) return {
+		severity,
+		code: "INTERNAL",
+		message: error instanceof Error ? error.message : String(error),
+		file: file && relativeTo(root, file)
+	};
+	const loc = error.loc;
+	const at = loc?.file ?? file;
+	return {
+		severity,
+		code: error.code,
+		message: error.message,
+		hint: error.hint,
+		file: at && relativeTo(root, at),
+		line: loc?.line,
+		column: loc?.column,
+		frame: loc && frameOf(loc.file, loc.line, loc.column)
+	};
+}
+function frameOf(file, line, column) {
+	try {
+		return codeFrame(readFileSync(file.replace(/[?#].*$/, ""), "utf8"), line, column);
+	} catch {
+		return;
+	}
+}
+function where(d) {
+	if (d.file === void 0) return "";
+	if (d.line === void 0) return `${d.file} `;
+	return `${d.file}:${d.line}:${(d.column ?? 0) + 1} `;
+}
+/** Text for a terminal or a CI log. */
+function formatText(d) {
+	const lines = [`${where(d)}${d.severity} vicss(${d.code}): ${d.message}`];
+	if (d.hint) lines.push(...d.hint.split("\n").map((line) => `  ${line}`));
+	if (d.frame) lines.push("", ...d.frame.split("\n").map((line) => `  ${line}`));
+	return `${lines.join("\n")}\n`;
+}
+/**
+* A GitHub Actions workflow command (`::error file=…,line=…::message`).
+* Data escapes `%`, CR and LF; properties also `:` and `,`.
+*/
+function formatAnnotation(d, fileOf = (file) => file) {
+	const data = (text) => text.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
+	const property = (text) => data(text).replaceAll(":", "%3A").replaceAll(",", "%2C");
+	const props = [
+		d.file !== void 0 && `file=${property(fileOf(d.file))}`,
+		d.line !== void 0 && `line=${d.line}`,
+		d.line !== void 0 && `col=${(d.column ?? 0) + 1}`,
+		`title=${property(`vicss(${d.code})`)}`
+	].filter(Boolean);
+	const message = d.hint ? `${d.message}\n${d.hint}` : d.message;
+	return `::${d.severity} ${props.join(",")}::${data(message)}\n`;
+}
+/** Plain data for `--json`. */
+function toJson(d) {
+	return {
+		severity: d.severity,
+		code: d.code,
+		message: d.message,
+		...d.hint === void 0 ? {} : { hint: d.hint },
+		...d.file === void 0 ? {} : { file: d.file },
+		...d.line === void 0 ? {} : {
+			line: d.line,
+			column: (d.column ?? 0) + 1
+		}
+	};
+}
+//#endregion
+//#region src/cli/check.ts
+/**
+* `vicss check` (PLAN §5.15): the CI gate. It compiles `include` as the
+* build's pre-scan does, `.vue`, `.svelte` and `.astro` files by their
+* scripts (§5.4), but reports every error rather than the first, with the
+* ordering invariant over all files and the installed libraries' manifests
+* (§5.13), their contract with the design system, the budget of values
+* outside the scales (D8), the share of hashed atoms (PLAN §6) and tokens
+* nothing uses.
+*/
+/**
+* PLAN §6: a warning above this share of hashed atoms (values outside the
+* scales, and long or unusual literals), as a design system erodes.
+*/
+const HASHED_BUDGET = .1;
+/** Unused tokens named in a message; `--json` lists them all. */
+const LISTED = 12;
+const EMPTY = {
+	files: 0,
+	atoms: 0,
+	bases: 0,
+	libraries: [],
+	arbitrary: {
+		count: 0,
+		byFile: {}
+	},
+	hashed: {
+		count: 0,
+		share: 0,
+		byFile: {}
+	},
+	unusedTokens: [],
+	diagnostics: []
+};
+async function check(io, options) {
+	const root = normalizePath(io.cwd);
+	let report;
+	try {
+		report = await run$1(io, root, options);
+	} catch (error) {
+		report = {
+			...EMPTY,
+			diagnostics: [diagnosticOf(error, root)]
+		};
+	}
+	write(io, options, report);
+	return report.diagnostics.some((d) => d.severity === "error") ? 1 : 0;
+}
+async function run$1(io, root, options) {
+	const { system, config } = await loadProject(io, options.config);
+	const resolver = await createResolver(io);
+	try {
+		return await checkWith(root, options, system, resolver, presetTokens(config));
+	} finally {
+		await resolver.close();
+	}
+}
+async function checkWith(root, options, system, { resolve, frameworks }, fromPresets = /* @__PURE__ */ new Set()) {
+	const arbitrary = {};
+	const hashedByFile = {};
+	const compiler = createCompiler(system, resolve, root, (id, compiled) => {
+		const rel = relativeTo(root, id);
+		if (compiled.arbitrary > 0) arbitrary[rel] = (arbitrary[rel] ?? 0) + compiled.arbitrary;
+		const hashed = withBases(compiled).filter(isArbitrary).length;
+		if (hashed > 0) hashedByFile[rel] = (hashedByFile[rel] ?? 0) + hashed;
+	}, frameworks);
+	const result = await scan({
+		root,
+		system,
+		configHash: system.hash,
+		importSources: system.config.importSources ?? [],
+		cache: new CompileCache(),
+		resolve: (source, importer) => resolveFile(resolve, source, importer),
+		keepGoing: true,
+		compile: (id, code, script) => compiler.compile(id, code, script)
+	});
+	const diagnostics = result.failures.flatMap((failure) => diagnosticsOf(failure.error, root, "error", failure.id));
+	let libraries = [];
+	let sheet = result;
+	try {
+		libraries = loadLibraries(root, system);
+		sheet = withLibraries(result, libraries, system);
+	} catch (error) {
+		diagnostics.push(...diagnosticsOf(error, root, "error"));
+	}
+	const palette = paletteProblem({
+		system,
+		atoms: sheet.atoms,
+		rules: sheet.rules,
+		referenced: sheet.tokens,
+		tokens: "used"
+	});
+	if (palette) diagnostics.push(...diagnosticsOf(palette, root, "error"));
+	for (const [id, warnings] of compiler.warnings) for (const warning of warnings) diagnostics.push(warningOf(warning, root, id));
+	const offScale = Object.values(arbitrary).reduce((sum, n) => sum + n, 0);
+	if (options.maxArbitrary !== void 0 && offScale > options.maxArbitrary) diagnostics.push({
+		severity: "error",
+		code: "ARBITRARY_BUDGET",
+		message: `${offScale} values are outside the scales; the budget is ${options.maxArbitrary} (--max-arbitrary)`,
+		hint: `By file: ${counts(arbitrary)}. Add tokens for the values the design system lacks.`
+	});
+	const every = withBases(result);
+	const hashed = every.filter(isArbitrary).length;
+	const share = every.length === 0 ? 0 : hashed / every.length;
+	if (share > .1) diagnostics.push({
+		severity: "warning",
+		code: "HASHED_ATOMS",
+		message: `${percent(share)} of the atoms (${hashed} of ${every.length}) get hashed class names (\`~…\`): values outside the scales and long or unusual literals; the budget is ${HASHED_BUDGET * 100} %`,
+		hint: `By file: ${counts(hashedByFile)}.`
+	});
+	const unusedTokens = unused(system, sheet).filter((key) => !fromPresets.has(key));
+	if (unusedTokens.length > 0) {
+		const more = unusedTokens.length - LISTED;
+		const verb = unusedTokens.length === 1 ? "token is" : "tokens are";
+		diagnostics.push({
+			severity: "warning",
+			code: "UNUSED_TOKENS",
+			message: `${unusedTokens.length} ${verb} defined but never used: ${unusedTokens.slice(0, LISTED).join(", ")}${more > 0 ? ` and ${more} more` : ""}`,
+			hint: "No style, globalCss rule, keyframe, theme() or token() reads them, so they stay out of the CSS."
+		});
+	}
+	const own = new Set(result.atoms.map((atom) => atom.className));
+	return {
+		files: result.files.length,
+		atoms: result.atoms.length,
+		bases: result.rules.filter((rule) => rule.kind === "base").length,
+		libraries: libraries.map((library) => ({
+			name: library.name,
+			atoms: library.atoms.filter((atom) => !own.has(atom.className)).length
+		})),
+		arbitrary: {
+			count: offScale,
+			byFile: arbitrary
+		},
+		hashed: {
+			count: hashed,
+			share,
+			byFile: hashedByFile
+		},
+		unusedTokens,
+		diagnostics: sorted(diagnostics)
+	};
+}
+/** Atoms and the atoms the flattened bases among the rules stand for, one per class. */
+function withBases(styles) {
+	const own = new Set(styles.atoms.map((atom) => atom.className));
+	return [...styles.atoms, ...baseAtoms(styles.rules).filter((atom) => !own.has(atom.className))];
+}
+/** A strictness "warn" report: its message without the hint the compiler appended. */
+function warningOf(warning, root, id) {
+	const { hint, loc } = warning;
+	const suffix = hint === void 0 ? "" : `. ${hint}`;
+	const message = suffix && warning.message.endsWith(suffix) ? warning.message.slice(0, -suffix.length) : warning.message;
+	return {
+		severity: "warning",
+		code: warning.code,
+		message,
+		hint,
+		file: relativeTo(root, loc?.file ?? id),
+		line: loc?.line,
+		column: loc?.column,
+		frame: loc && frameOf(loc.file, loc.line, loc.column)
+	};
+}
+/**
+* `scale.path` of every token nothing uses, in table order: what the sheet
+* leaves out, less the breakpoints and containers a condition in use is made
+* from, which shape queries rather than reaching the CSS as properties.
+*/
+/**
+* The tokens the config's presets define. A preset's scales belong to its
+* author: an app that uses ten of Tailwind's colours can do nothing about the
+* other two hundred, so only the tokens the config declares are reported.
+*/
+function presetTokens(config) {
+	if (!config.presets?.length) return /* @__PURE__ */ new Set();
+	try {
+		const { tokens } = resolveSystem({ presets: config.presets });
+		return new Set([...tokens.values()].flatMap((table) => [...table.values()].map((token) => `${token.scale}.${token.path}`)));
+	} catch {
+		return /* @__PURE__ */ new Set();
+	}
+}
+function unused(system, result) {
+	const used = new Set(baseTokens({
+		system,
+		atoms: result.atoms,
+		rules: result.rules,
+		referenced: result.tokens,
+		tokens: "used"
+	}).map((token) => `${token.scale}.${token.path}`));
+	for (const name of conditionsInUse(system, result)) for (const ref of system.conditions.get(name)?.tokens ?? []) used.add(`${ref.scale}.${ref.path}`);
+	return [...system.tokens.values()].flatMap((table) => [...table.values()].filter((token) => !token.palette).map((token) => `${token.scale}.${token.path}`).filter((key) => !used.has(key)));
+}
+/** Condition names the styles, `globalCss` and the semantic tokens' modes use. */
+function conditionsInUse(system, result) {
+	const names = /* @__PURE__ */ new Set();
+	for (const atom of withBases(result)) for (const name of atom.chain) names.add(name);
+	for (const [selector, style] of Object.entries(system.config.globalCss ?? {})) {
+		if (style === void 0) continue;
+		const atoms = normalizeStyle(style, {
+			system,
+			root: `globalCss[${selector}]`,
+			privateAccess: true
+		});
+		for (const atom of atoms) for (const name of atom.chain) names.add(name);
+	}
+	for (const table of system.tokens.values()) for (const token of table.values()) for (const mode of Object.keys(token.modes ?? {})) names.add(mode);
+	return names;
+}
+/** Errors first, then by file and line. */
+function sorted(diagnostics) {
+	const rank = (d) => d.severity === "error" ? 0 : 1;
+	return diagnostics.sort((a, b) => rank(a) - rank(b) || compareStrings(a.file ?? "￿", b.file ?? "￿") || (a.line ?? 0) - (b.line ?? 0) || (a.column ?? 0) - (b.column ?? 0));
+}
+const percent = (share) => `${(share * 100).toFixed(1)} %`;
+function counts(byFile) {
+	const entries = Object.entries(byFile).sort(([a], [b]) => compareStrings(a, b));
+	return entries.length === 0 ? "none" : entries.map(([file, n]) => `${file} ${n}`).join(", ");
+}
+/**
+* GitHub reads an annotation's file relative to the repository, which a
+* project in a monorepo package is not the root of: relative to
+* `GITHUB_WORKSPACE` when the file is inside it, else absolute.
+*/
+function workspacePath(root, workspace, file) {
+	const absolute = normalizePath(path.resolve(root, file));
+	if (workspace === void 0 || workspace === "") return file;
+	const rel = path.relative(workspace, absolute);
+	return rel && !rel.startsWith("..") && !path.isAbsolute(rel) ? normalizePath(rel) : absolute;
+}
+function write(io, options, report) {
+	if (options.json) {
+		const { diagnostics, ...rest } = report;
+		const json = {
+			...rest,
+			arbitrary: {
+				...rest.arbitrary,
+				...options.maxArbitrary === void 0 ? {} : { max: options.maxArbitrary }
+			},
+			errors: diagnostics.filter((d) => d.severity === "error").map(toJson),
+			warnings: diagnostics.filter((d) => d.severity === "warning").map(toJson)
+		};
+		io.stdout(`${JSON.stringify(json, null, 2)}\n`);
+		return;
+	}
+	for (const diagnostic of report.diagnostics) if (diagnostic.severity === "error") io.stderr(formatText(diagnostic));
+	else io.stdout(formatText(diagnostic));
+	if (io.env["GITHUB_ACTIONS"]) {
+		const root = normalizePath(io.cwd);
+		const workspace = io.env["GITHUB_WORKSPACE"];
+		for (const diagnostic of report.diagnostics) io.stdout(formatAnnotation(diagnostic, (file) => workspacePath(root, workspace, file)));
+	}
+	const errors = report.diagnostics.filter((d) => d.severity === "error").length;
+	const warnings = report.diagnostics.length - errors;
+	const budget = options.maxArbitrary === void 0 ? "" : ` (budget ${options.maxArbitrary})`;
+	const libraries = report.libraries.map((library) => `${library.atoms} from ${library.name}`);
+	const fromLibraries = libraries.length === 0 ? "" : ` (+ ${libraries.join(", ")})`;
+	const bases = report.bases === 0 ? "" : `, ${report.bases} flattened base${report.bases === 1 ? "" : "s"}`;
+	io.stdout(`vicss check: ${report.files} files, ${report.atoms} atoms${fromLibraries}${bases}, ${report.arbitrary.count} values outside the scales${budget}, ${report.hashed.count} hashed atoms (${percent(report.hashed.share)}); ${errors} error${errors === 1 ? "" : "s"}, ${warnings} warning${warnings === 1 ? "" : "s"}\n`);
+}
+//#endregion
+//#region src/cli/critical.ts
+/**
+* `vicss critical <dir>` (PLAN D16): critical CSS for the pages a framework
+* writes after `vite build`, which the plugin's HTML hook never sees. It
+* reads only the output, so it needs neither the config nor a scan.
+*/
+const kB = (bytes) => `${(bytes / 1e3).toFixed(2)} kB`;
+async function criticalCommand(io, dir, options) {
+	const { json, ...rest } = options;
+	let result;
+	try {
+		result = await critical(path.resolve(io.cwd, dir), rest);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		io.stderr(`error vicss(CRITICAL): ${message.replace(/^vicss: /, "")}\n`);
+		return 1;
+	}
+	if (json) {
+		const pages = result.pages.map(({ html: _html, ...page }) => ({
+			...page,
+			..._html === void 0 ? {} : { inlined: true }
+		}));
+		io.stdout(`${JSON.stringify({
+			...result,
+			pages
+		}, null, 2)}\n`);
+		return 0;
+	}
+	const width = Math.max(0, ...result.pages.map((page) => page.page.length));
+	for (const page of result.pages) {
+		const name = page.page.padEnd(width);
+		io.stdout(page.html === void 0 ? `${name}  left as it was: ${page.skipped}\n` : `${name}  ${kB(page.bytes)} │ gzip: ${kB(page.gzip)}  ${page.hashes.length} inline style${page.hashes.length === 1 ? "" : "s"}\n`);
+	}
+	for (const warning of result.warnings) io.stdout(`warning vicss(CRITICAL): ${warning}\n`);
+	io.stdout(`${result.summary.replace(/^vicss: /, "vicss critical: ")}${options.dryRun ? " (dry run: nothing written)" : ""}\n`);
+	return 0;
+}
+//#endregion
+//#region src/cli/init.ts
+/**
+* `vicss init` and `vicss types` (PLAN §5.15): a starting config and the
+* generated `vicss.d.ts`, which `vicss types` rewrites in CI where no dev
+* server or build has written it, with the lint snapshot next to it.
+*/
+/**
+* A small design system to start from when no preset or token file gives one
+* (PLAN §4.1), its semantic tokens written with typed references (D32).
+*/
+const STARTER = `export default defineConfig(
+  {
+    tokens: {
+      colors: {
+        white: "#fff",
+        gray: { 50: "oklch(98.5% 0 0)", 900: "oklch(21% 0.034 264)", 950: "oklch(13% 0.028 262)" },
+        blue: { 600: "oklch(54.6% 0.245 263)" },
+      },
+      // A linear scale: padding: 4 is calc(var(--spacing) * 4).
+      spacing: { step: "0.25rem" },
+      radii: { sm: "0.25rem", md: "0.375rem", lg: "0.5rem", full: "9999px" },
+      breakpoints: { sm: "40rem", md: "48rem", lg: "64rem", xl: "80rem" },
+    },
+    // A modern reset in the vicss.reset layer.
+    reset: true,
+  },
+  // Meaning, not colour: components use these, and modes switch them. The
+  // tokens above arrive typed: colors.gray[950] is "{colors.gray.950}".
+  ({ colors }) => ({
+    semanticTokens: {
+      colors: {
+        surface: { base: colors.white, _dark: colors.gray[950] },
+        text: { base: colors.gray[900], _dark: colors.gray[50] },
+        accent: colors.blue[600],
+      },
+    },
+  }),
+);
+`;
+function configSource(preset, dtcg) {
+	const imports = [
+		"defineConfig",
+		...dtcg ? ["dtcg"] : [],
+		...preset === "tailwind" ? ["tailwind"] : []
+	];
+	const presets = [...preset === "tailwind" ? ["tailwind"] : [], ...dtcg ? [`dtcg(${JSON.stringify(dtcg)})`] : []];
+	const head = [`import { ${imports.join(", ")} } from "@menapo/vicss/config";`, ""];
+	if (presets.length === 0) return [...head, STARTER].join("\n");
+	return [
+		...head,
+		"export default defineConfig({",
+		`  presets: [${presets.join(", ")}],`,
+		"  // A modern reset in the vicss.reset layer.",
+		"  reset: true,",
+		"});",
+		""
+	].join("\n");
+}
+const PLUGIN_SNIPPET = `Add the plugin to vite.config.ts:
+
+  import { vicss } from "@menapo/vicss/vite";
+
+  export default defineConfig({
+    plugins: [vicss()],
+  });
+`;
+async function init(io, options) {
+	const root = normalizePath(io.cwd);
+	const existing = CONFIG_FILES.find((name) => existsSync(path.join(root, name)));
+	if (existing && !options.force) {
+		io.stderr(`vicss: ${existing} already exists. Pass --force to replace it with vicss.config.ts.\n`);
+		return 1;
+	}
+	let dtcg;
+	if (options.dtcg !== void 0) {
+		const file = path.resolve(root, options.dtcg);
+		if (!existsSync(file)) {
+			io.stderr(`vicss: ${options.dtcg} does not exist.\n`);
+			return 1;
+		}
+		const rel = normalizePath(path.relative(root, file));
+		dtcg = rel.startsWith(".") ? rel : `./${rel}`;
+	}
+	const preset = options.preset ?? (dtcg ? "none" : "tailwind");
+	const config = path.join(root, "vicss.config.ts");
+	if (!writeOutput(io, config, () => writeFileSync(config, configSource(preset, dtcg)))) return 1;
+	io.stdout("Wrote vicss.config.ts.\n");
+	const settings = await projectSettings(io);
+	const code = await types(io, {
+		config: void 0,
+		out: void 0
+	}, settings);
+	if (!settings.registered) io.stdout(`\n${PLUGIN_SNIPPET}`);
+	return code;
+}
+async function types(io, options, settings) {
+	const root = normalizePath(io.cwd);
+	let text;
+	let snapshot;
+	settings ??= await projectSettings(io);
+	const output = settings.options.types === false ? void 0 : settings.options.types?.output;
+	const file = typesFile(root, options.out ?? output);
+	const lintFile = snapshotFile(file);
+	try {
+		const { system } = await loadProject(io, options.config);
+		text = generateTypes(system, { framework: settings.frameworks.scripts });
+		snapshot = snapshotText(system, { root: snapshotRoot(lintFile, root) });
+	} catch (error) {
+		io.stderr(formatText(diagnosticOf(error, root)));
+		return 1;
+	}
+	for (const [target, content] of [[file, text], [lintFile, snapshot]]) {
+		const rel = relativeTo(root, target);
+		let wrote = false;
+		if (!writeOutput(io, target, () => wrote = writeIfChanged(target, content))) return 1;
+		io.stdout(wrote ? `Wrote ${rel}.\n` : `${rel} is up to date.\n`);
+	}
+	return 0;
+}
+//#endregion
+//#region src/cli/inspect.ts
+/**
+* `vicss inspect <file>` (PLAN §5.14): the atoms a module compiles to, with
+* the condition chain and sub-layer that decide each one's precedence, and
+* the CSS the build emits for them. A `.vue`, `.svelte` or `.astro` file is
+* read by its scripts, as the build's pre-scan reads it (§5.4).
+*/
+async function inspect(io, file, options) {
+	const root = normalizePath(io.cwd);
+	const id = normalizePath(path.resolve(root, file));
+	try {
+		let code;
+		try {
+			code = readFileSync(id, "utf8");
+		} catch {
+			io.stderr(`vicss: cannot read ${file}.\n`);
+			return 1;
+		}
+		const { system } = await loadProject(io, options.config);
+		const resolver = await createResolver(io);
+		const compiler = createCompiler(system, resolver.resolve, root, void 0, resolver.frameworks);
+		const result = await compileFile(compiler, id, code).finally(() => resolver.close());
+		const rel = relativeTo(root, id);
+		const rules = result.rules.length;
+		io.stdout(`${rel}: ${result.atoms.length} atom${result.atoms.length === 1 ? "" : "s"}${rules > 0 ? `, ${rules} rule${rules === 1 ? "" : "s"}` : ""}\n`);
+		if (result.atoms.length === 0 && rules === 0) return 0;
+		const chainOf = (atom) => atom.chain.length === 0 ? "base" : atom.chain.join(":");
+		const propertyOf = (atom) => isPaletteAtom(atom) ? "colorPalette" : atom.property;
+		const rows = [...result.atoms.map((atom) => [
+			atom.className,
+			propertyOf(atom),
+			atom.value,
+			chainOf(atom),
+			layerName(atom.chain, atom.tier, system)
+		]), ...result.rules.flatMap((rule) => (rule.atoms ?? []).map((atom) => [
+			rule.id,
+			propertyOf(atom),
+			atom.value,
+			chainOf(atom),
+			flatLayerName(atom.chain, system)
+		]))];
+		if (rows.length > 0) io.stdout(`\n${table([
+			"class",
+			"property",
+			"value",
+			"chain",
+			"layer"
+		], rows)}`);
+		const css = [printAtoms(result.atoms, system, result.rules), ...result.rules.filter((rule) => rule.kind !== "base").map((rule) => rule.css)].filter(Boolean).join("\n");
+		io.stdout(`\nCSS\n${css}\n`);
+		for (const warning of compiler.warnings.get(id) ?? []) io.stderr(`warning: ${warning.message}\n`);
+		return 0;
+	} catch (error) {
+		for (const diagnostic of diagnosticsOf(error, root, "error", id)) io.stderr(formatText(diagnostic));
+		return 1;
+	}
+}
+/**
+* A module's atoms and rules; a framework file's, of all its scripts, one
+* per class and rule id. The template is the framework's output, which the
+* build compiles but nothing here has: a style written there is the build's
+* error to report.
+*/
+async function compileFile(compiler, id, code) {
+	if (!isSfc(id)) return compiler.compile(id, code);
+	const atoms = /* @__PURE__ */ new Map();
+	const rules = /* @__PURE__ */ new Map();
+	for (const { code: script, ...options } of extractScripts(id, code)) {
+		const result = await compiler.compile(id, script, options);
+		for (const atom of result.atoms) if (!atoms.has(atom.className)) atoms.set(atom.className, atom);
+		for (const rule of result.rules) if (!rules.has(rule.id)) rules.set(rule.id, rule);
+	}
+	return {
+		atoms: [...atoms.values()].sort((a, b) => compareStrings(a.className, b.className)),
+		rules: [...rules.values()].sort((a, b) => compareStrings(a.id, b.id))
+	};
+}
+/** Columns padded to their widest cell. */
+function table(head, rows) {
+	const widths = head.map((title, i) => Math.max(title.length, ...rows.map((row) => row[i].length)));
+	const line = (cells) => cells.map((cell, i) => i === cells.length - 1 ? cell : cell.padEnd(widths[i])).join("  ");
+	return `${[line(head), ...rows.map(line)].join("\n")}\n`;
+}
+//#endregion
+//#region src/cli/tokens.ts
+/**
+* `vicss tokens export` (PLAN §5.15): the resolved design system for other
+* tools. `css` is the token layer vicss itself prints (every token, with
+* modes); `json` is a flat table per scale; `dtcg` a DTCG 2025.10
+* `.tokens.json` that `dtcg()` reads back, modes included (in vicss's
+* `$extensions`), text styles left out.
+*/
+async function exportTokens(io, options) {
+	const root = normalizePath(io.cwd);
+	let text;
+	try {
+		const { system } = await loadProject(io, options.config);
+		text = options.format === "css" ? `${printTokens(system)}\n` : `${JSON.stringify(options.format === "json" ? tokenTable(system) : dtcgTokens(system), null, 2)}\n`;
+		const styles = [...system.textStyles.keys()];
+		if (options.format === "dtcg" && styles.length > 0) {
+			const count = styles.length === 1 ? "1 text style" : `${styles.length} text styles`;
+			io.stderr(`vicss: ${count} (${styles.join(", ")}) ${styles.length === 1 ? "is" : "are"} not exported: keep them in vicss.config.ts beside dtcg().\n`);
+		}
+	} catch (error) {
+		io.stderr(formatText(diagnosticOf(error, root)));
+		return 1;
+	}
+	if (options.out === void 0) {
+		io.stdout(text);
+		return 0;
+	}
+	const file = path.resolve(root, options.out);
+	if (!writeOutput(io, file, () => {
+		mkdirSync(path.dirname(file), { recursive: true });
+		writeFileSync(file, text);
+	})) return 1;
+	io.stdout(`Wrote ${relativeTo(root, normalizePath(file))}.\n`);
+	return 0;
+}
+/** Scale → path → its custom property and CSS value, with a value per mode. */
+function tokenTable(system) {
+	const out = {};
+	for (const [scale, table] of system.tokens) {
+		const tokens = [...table.values()].filter((token) => !token.palette);
+		if (tokens.length === 0) continue;
+		out[scale] = Object.fromEntries(tokens.map((token) => [token.path, {
+			cssVar: token.cssVar,
+			value: token.value,
+			...token.modes ? { modes: token.modes } : {},
+			...token.semantic ? { semantic: true } : {},
+			...token.private ? { private: true } : {}
+		}]));
+	}
+	return out;
+}
+/** `$extensions` key whose `value` holds a CSS value, as `dtcg()` reads it. */
+const EXTENSION = "dev.menapo.vicss";
+/** Values per mode, which a `.tokens.json` file cannot express without a resolver. */
+const MODES_EXTENSION = "dev.menapo.vicss.modes";
+/** `true` on a token app styles may not name (`tokenVisibility`), which `dtcg()` reads back. */
+const PRIVATE_EXTENSION = "dev.menapo.vicss.private";
+const DTCG_TYPES = {
+	colors: "color",
+	spacing: "dimension",
+	sizes: "dimension",
+	radii: "dimension",
+	fonts: "fontFamily",
+	fontSizes: "dimension",
+	fontWeights: "fontWeight",
+	lineHeights: "number",
+	letterSpacings: "dimension",
+	shadows: "shadow",
+	textShadows: "shadow",
+	durations: "duration",
+	easings: "cubicBezier",
+	zIndices: "number",
+	opacities: "number",
+	blurs: "dimension",
+	aspectRatios: "number",
+	breakpoints: "dimension",
+	containers: "dimension"
+};
+/**
+* One group per scale, named like the scale so `dtcg()` places it again,
+* and a token per path, typed by its scale. A value in a format the DTCG
+* types define is written in it; any other CSS value (oklch(), calc(), a
+* shadow) is the `$value` as a string and vicss's `$extensions` entry,
+* which `dtcg()` reads instead.
+* Aliases stay aliases (`{colors.blue.600}`). Values per mode go in
+* `$extensions["dev.menapo.vicss.modes"]`: modes need a resolver document.
+*/
+function dtcgTokens(system) {
+	const byVar = /* @__PURE__ */ new Map();
+	for (const table of system.tokens.values()) for (const token of table.values()) byVar.set(token.cssVar, token);
+	const references = (css) => css.replace(/var\((--[\w-]+)\)/g, (match, name) => {
+		const target = byVar.get(name);
+		return target ? `{${target.scale}.${target.path}}` : match;
+	});
+	const root = {};
+	for (const [scale, table] of system.tokens) for (const token of table.values()) {
+		if (token.palette) continue;
+		const node = {};
+		const css = references(token.value);
+		const literal = /^\{[^{}]+\}$/.test(css) ? css : typed(scale, css);
+		node.$type = DTCG_TYPES[scale];
+		if (literal === void 0) {
+			node.$value = css;
+			node.$extensions = { [EXTENSION]: { value: css } };
+		} else node.$value = literal;
+		if (token.modes) {
+			const modes = Object.fromEntries(Object.entries(token.modes).map(([mode, value]) => [mode, references(value)]));
+			node.$extensions = {
+				...node.$extensions,
+				[MODES_EXTENSION]: modes
+			};
+		}
+		if (token.private) node.$extensions = {
+			...node.$extensions,
+			[PRIVATE_EXTENSION]: true
+		};
+		place(root, [scale, ...token.path.split(".")], node);
+	}
+	return root;
+}
+/** Puts `node` at `segments`; a group that is also a token keeps the token as `$root`. */
+function place(root, segments, node) {
+	let group = root;
+	for (const segment of segments.slice(0, -1)) {
+		let next = group[segment];
+		if (next === void 0 || typeof next !== "object" || next === null || Array.isArray(next)) {
+			next = {};
+			group[segment] = next;
+		} else if ("$value" in next) {
+			next = { $root: next };
+			group[segment] = next;
+		}
+		group = next;
+	}
+	const last = segments.at(-1);
+	const existing = group[last];
+	if (existing && typeof existing === "object" && !Array.isArray(existing) && !("$value" in existing)) existing.$root = node;
+	else group[last] = node;
+}
+const DIMENSION = /^(-?(?:\d+\.?\d*|\.\d+))(px|rem)$/;
+const DURATION = /^(\d+\.?\d*|\.\d+)(ms|s)$/;
+const NUMBER = /^-?(?:\d+\.?\d*|\.\d+)$/;
+/** The DTCG form of a CSS value of `scale`'s type, or undefined when it has none. */
+function typed(scale, css) {
+	const value = css.trim();
+	switch (DTCG_TYPES[scale]) {
+		case "dimension": {
+			if (value === "0") return {
+				value: 0,
+				unit: "px"
+			};
+			const match = DIMENSION.exec(value);
+			return match ? {
+				value: Number(match[1]),
+				unit: match[2]
+			} : void 0;
+		}
+		case "duration": {
+			const match = DURATION.exec(value);
+			return match ? {
+				value: Number(match[1]),
+				unit: match[2]
+			} : void 0;
+		}
+		case "number":
+		case "fontWeight": return NUMBER.test(value) ? Number(value) : void 0;
+		case "fontFamily": {
+			const names = value.split(",").map((name) => name.trim().replace(/^(["'])(.*)\1$/, "$2"));
+			return names.some((name) => name === "" || /[(){}]/.test(name)) ? void 0 : names.length === 1 ? names[0] : names;
+		}
+		case "cubicBezier": {
+			const points = /^cubic-bezier\(([^)]*)\)$/.exec(value)?.[1].split(",").map((n) => Number(n.trim()));
+			return points?.length === 4 && points.every(Number.isFinite) ? points : void 0;
+		}
+		case "color": return hexColor(value);
+		default: return;
+	}
+}
+/** `#rgb`, `#rrggbb` (and with alpha) as a DTCG sRGB color. */
+function hexColor(value) {
+	const match = /^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.exec(value);
+	if (!match) return void 0;
+	let hex = match[1].toLowerCase();
+	if (hex.length <= 4) hex = hex.replace(/./g, (c) => c + c);
+	const channel = (i) => Number.parseInt(hex.slice(i, i + 2), 16) / 255;
+	const round = (n) => Math.round(n * 1e4) / 1e4;
+	const color = {
+		colorSpace: "srgb",
+		components: [
+			round(channel(0)),
+			round(channel(2)),
+			round(channel(4))
+		],
+		hex: `#${hex.slice(0, 6)}`
+	};
+	if (hex.length === 8) color.alpha = round(channel(6));
+	return color;
+}
+//#endregion
+//#region src/cli/main.ts
+/**
+* The `vicss` command line (PLAN §5.15), run in-process by tests through
+* `main(argv, io)`. Arguments are parsed here rather than by a dependency
+* (D20): commands take a few `--name value` options and flags each.
+*/
+const CONFIG_OPTION = "  --config <file>      The vicss config, relative to the current directory\n";
+const HELP = `Usage: vicss <command> [options]
+
+Commands:
+  init                 Write vicss.config.ts and the generated types
+  types                Write the generated types (vicss.d.ts) and vicss.lint.json
+  check                Check every styled file: errors, off-scale values, unused tokens
+  inspect <file>       Print the atoms and CSS of one file
+  tokens export        Write the resolved tokens as CSS, JSON or DTCG
+  critical <dir>       Inline the critical CSS of the prerendered pages in <dir>
+
+Options:
+  -h, --help           Show help for a command: vicss <command> --help
+  -v, --version        Print the version
+
+Run it in the project root, where vite.config.ts and vicss.config.ts are.
+`;
+const string = (parsed, name) => {
+	const value = parsed.options[name];
+	return typeof value === "string" ? value : void 0;
+};
+const COMMANDS = {
+	init: {
+		spec: {
+			preset: "string",
+			dtcg: "string",
+			force: "boolean"
+		},
+		help: `Usage: vicss init [--preset tailwind|none] [--dtcg <file>] [--force]
+
+Writes vicss.config.ts, then the generated types, and prints how to add the
+plugin to vite.config.ts.
+
+Options:
+  --preset <name>      tailwind (Tailwind v4's theme; the default) or none
+                       (a small starting design system; the default with --dtcg)
+  --dtcg <file>        Read tokens from a DTCG .tokens.json or .resolver.json file
+  --force              Replace an existing vicss.config.*
+`,
+		async run(io, parsed) {
+			const preset = string(parsed, "preset");
+			if (preset !== void 0 && preset !== "tailwind" && preset !== "none") return usage(io, `--preset takes tailwind or none, not ${preset}`, this.help);
+			return init(io, {
+				preset,
+				dtcg: string(parsed, "dtcg"),
+				force: parsed.options["force"] === true
+			});
+		}
+	},
+	types: {
+		spec: {
+			config: "string",
+			out: "string"
+		},
+		help: `Usage: vicss types [--out <file>] [--config <file>]
+
+Writes the generated types for the design system in vicss.config.ts, as the
+Vite plugin does whenever the config loads: src/vicss.d.ts, else
+app/vicss.d.ts, else vicss.d.ts when there is neither directory; and
+vicss.lint.json next to them, which the
+rules of @menapo/vicss/lint read. Run it in CI before type-checking and linting.
+
+Options:
+  --out <file>         Where to write the types, relative to the current directory
+${CONFIG_OPTION}`,
+		run: (io, parsed) => types(io, {
+			config: string(parsed, "config"),
+			out: string(parsed, "out")
+		})
+	},
+	check: {
+		spec: {
+			config: "string",
+			"max-arbitrary": "string",
+			json: "boolean"
+		},
+		help: `Usage: vicss check [--max-arbitrary <n>] [--json] [--config <file>]
+
+Compiles every file under include as the build does and reports every error
+with its file and line, invariant violations across files, the values outside
+the scales, the share of hashed atoms, and tokens nothing uses. Exits with 1 on
+errors. In GitHub Actions (GITHUB_ACTIONS set) it also prints annotations.
+
+Options:
+  --max-arbitrary <n>  Fail when more than n values are outside the scales
+  --json               Print the report as JSON
+${CONFIG_OPTION}`,
+		run(io, parsed) {
+			const max = string(parsed, "max-arbitrary");
+			const maxArbitrary = max === void 0 ? void 0 : Number(max);
+			if (maxArbitrary !== void 0 && !(Number.isInteger(maxArbitrary) && maxArbitrary >= 0)) return Promise.resolve(usage(io, `--max-arbitrary takes a whole number, not ${max}`, this.help));
+			return check(io, {
+				config: string(parsed, "config"),
+				maxArbitrary,
+				json: parsed.options["json"] === true
+			});
+		}
+	},
+	inspect: {
+		spec: { config: "string" },
+		help: `Usage: vicss inspect <file> [--config <file>]
+
+Prints the atoms a file compiles to (class, property, value, condition
+chain, cascade layer) and the CSS the build emits for them.
+
+Options:
+${CONFIG_OPTION}`,
+		run(io, parsed) {
+			const [file, ...rest] = parsed.positionals;
+			if (file === void 0 || rest.length > 0) return Promise.resolve(usage(io, "inspect takes one file", this.help));
+			return inspect(io, file, { config: string(parsed, "config") });
+		}
+	},
+	tokens: {
+		spec: {
+			config: "string",
+			format: "string",
+			out: "string"
+		},
+		help: `Usage: vicss tokens export [--format css|json|dtcg] [--out <file>] [--config <file>]
+
+Writes every token of the design system, resolved:
+  css                  The tokens layer vicss prints, with every mode (default)
+  json                 Each scale's tokens: custom property, value, values per mode
+  dtcg                 A DTCG 2025.10 .tokens.json file that dtcg() reads back,
+                       values per mode included; text styles are not exported
+
+Options:
+  --format <format>    css, json or dtcg
+  --out <file>         Write to a file rather than to stdout
+${CONFIG_OPTION}`,
+		run(io, parsed) {
+			const [action, ...rest] = parsed.positionals;
+			if (action !== "export" || rest.length > 0) return Promise.resolve(usage(io, "the tokens command is: vicss tokens export", this.help));
+			const format = string(parsed, "format") ?? "css";
+			if (format !== "css" && format !== "json" && format !== "dtcg") return Promise.resolve(usage(io, `--format takes css, json or dtcg, not ${format}`, this.help));
+			return exportTokens(io, {
+				config: string(parsed, "config"),
+				format,
+				out: string(parsed, "out")
+			});
+		}
+	},
+	critical: {
+		spec: {
+			budget: "string",
+			hashes: "string",
+			"no-hashes": "boolean",
+			"dry-run": "boolean",
+			json: "boolean"
+		},
+		help: `Usage: vicss critical <dir> [--budget <bytes>] [--hashes <file>] [--no-hashes] [--dry-run] [--json]
+
+Gives the prerendered pages under <dir> critical CSS, for pages a framework
+writes after vite build (Astro, SvelteKit, Vike, React Router prerendering);
+the plugin's critical option covers the HTML Vite itself emits. In each page,
+every stylesheet holding vicss's CSS becomes an inline <style> with what the
+page's markup uses, and loads from the end of <body>, where it no longer
+blocks the first paint. Pages are rewritten in place; a page done before is
+left alone. Each page's CSP hashes go into vicss-critical.json in <dir>.
+
+Options:
+  --budget <bytes>     Warn about pages whose inline CSS is over this many
+                       gzip bytes (default 14000: the first round trip)
+  --hashes <file>      Where the CSP hashes go, relative to <dir>
+  --no-hashes          Write no hashes file
+  --dry-run            Report what would change and write nothing
+  --json               Print the report as JSON
+`,
+		run(io, parsed) {
+			const [dir, ...rest] = parsed.positionals;
+			if (dir === void 0 || rest.length > 0) return Promise.resolve(usage(io, "critical takes one directory", this.help));
+			const raw = string(parsed, "budget");
+			const budget = raw === void 0 ? void 0 : Number(raw);
+			if (budget !== void 0 && !(Number.isFinite(budget) && budget > 0)) return Promise.resolve(usage(io, `--budget takes a number of bytes, not ${raw}`, this.help));
+			const file = string(parsed, "hashes");
+			if (file !== void 0 && parsed.options["no-hashes"] === true) return Promise.resolve(usage(io, "--hashes and --no-hashes exclude each other", this.help));
+			const problem = file === void 0 ? void 0 : hashesProblem(file);
+			if (problem !== void 0) return Promise.resolve(usage(io, `--hashes ${problem}, not ${file}`, this.help));
+			return criticalCommand(io, dir, {
+				...budget === void 0 ? {} : { budget },
+				...parsed.options["no-hashes"] === true ? { hashes: false } : file === void 0 ? {} : { hashes: file },
+				dryRun: parsed.options["dry-run"] === true,
+				json: parsed.options["json"] === true
+			});
+		}
+	}
+};
+/**
+* Runs the command line `argv` (without `node` and the script) and returns
+* the exit code. A failure no command reports itself is an INTERNAL error
+* with exit code 1, not a rejected promise the binary would print as a
+* stack trace.
+*/
+async function main(argv, io) {
+	try {
+		return await run(argv, io);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		try {
+			io.stderr(`error vicss(INTERNAL): ${message}\n`);
+		} catch {}
+		return 1;
+	}
+}
+async function run(argv, io) {
+	const [name, ...args] = argv;
+	if (name === void 0 || name === "-h" || name === "--help" || name === "help") {
+		const topic = name === "help" ? args[0] : void 0;
+		const command = topic === void 0 ? void 0 : COMMANDS[topic];
+		io.stdout(command?.help ?? HELP);
+		return 0;
+	}
+	if (name === "-v" || name === "--version") {
+		io.stdout(`${version()}\n`);
+		return 0;
+	}
+	const command = COMMANDS[name];
+	if (!command) return usage(io, `unknown command ${name}`, HELP);
+	const parsed = parse(args, command.spec);
+	if (typeof parsed === "string") return usage(io, parsed, command.help);
+	if (parsed.options["help"] === true) {
+		io.stdout(command.help);
+		return 0;
+	}
+	return command.run(io, parsed);
+}
+/** Exit code 2: the command line itself is wrong. */
+function usage(io, message, help) {
+	io.stderr(`vicss: ${message}\n\n${help}`);
+	return 2;
+}
+/** `--name value`, `--name=value`, flags, `-h`, and `--` before positionals that look like options. */
+function parse(args, spec) {
+	const positionals = [];
+	const options = {};
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--") {
+			positionals.push(...args.slice(i + 1));
+			break;
+		}
+		if (arg === "-h" || arg === "--help") {
+			options["help"] = true;
+			continue;
+		}
+		if (!arg.startsWith("--")) {
+			if (arg.startsWith("-") && arg !== "-") return `unknown option ${arg}`;
+			positionals.push(arg);
+			continue;
+		}
+		const eq = arg.indexOf("=");
+		const name = arg.slice(2, eq === -1 ? void 0 : eq);
+		const kind = spec[name];
+		if (kind === void 0) return `unknown option --${name}`;
+		if (kind === "boolean") {
+			if (eq !== -1) return `--${name} takes no value`;
+			options[name] = true;
+			continue;
+		}
+		const value = eq === -1 ? args[++i] : arg.slice(eq + 1);
+		if (value === void 0 || eq === -1 && value.startsWith("--")) return `--${name} needs a value`;
+		options[name] = value;
+	}
+	return {
+		positionals,
+		options
+	};
+}
+/** By the package's own name, which resolves from the source and from `dist/` alike. */
+function version() {
+	return createRequire(import.meta.url)("@menapo/vicss/package.json").version;
+}
+//#endregion
+//#region src/cli/bin.ts
+/**
+* The `vicss` binary (PLAN §5.15), built as `dist/cli.js`. Everything but
+* wiring the process lives in `main.ts`, which tests run in-process.
+*/
+for (const stream of [process.stdout, process.stderr]) stream.on("error", (error) => {
+	if (error.code !== "EPIPE") throw error;
+	process.exit(process.exitCode ?? 0);
+});
+process.exitCode = await main(process.argv.slice(2), {
+	cwd: process.cwd(),
+	env: process.env,
+	stdout: (text) => process.stdout.write(text),
+	stderr: (text) => process.stderr.write(text)
+});
+//#endregion
+export {};