@shadow-js/ui 0.0.0-stage → 1.0.0

package/dist/cli.mjs

@@ -0,0 +1,2293 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+//#region src/cli/fs.ts
+/**
+* The filesystem the CLI works on, as an interface so commands are tested against a temp
+* directory or an in-memory tree, and so every path goes through one place.
+* @packageDocumentation
+*/
+/**
+* The real filesystem.
+*
+* @returns A {@link ProjectFs} over `node:fs`.
+* @example
+* const fs = nodeFs();
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function nodeFs() {
+	return {
+		exists: (path) => existsSync(path),
+		read(path) {
+			try {
+				return readFileSync(path, "utf8");
+			} catch (error) {
+				if (error.code === "ENOENT") return void 0;
+				throw error;
+			}
+		},
+		write(path, content) {
+			mkdirSync(dirname(path), { recursive: true });
+			writeFileSync(path, content);
+		},
+		remove(path) {
+			rmSync(path, { force: true });
+		},
+		realpath(path) {
+			const tail = [];
+			let current = path;
+			while (!existsSync(current)) {
+				const parent = dirname(current);
+				if (parent === current) return path;
+				tail.unshift(basename(current));
+				current = parent;
+			}
+			return join(realpathSync(current), ...tail);
+		}
+	};
+}
+/**
+* What a command records while it works, for the document: the facts, the warnings, and the first failure. Present in
+* the context of a `--json` run only.
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+var Report = class {
+	/** The facts, by key. */
+	data = {};
+	warnings = [];
+	/** The failure; a second one adds its message to the first. */
+	error;
+	/**
+	* Sets a fact.
+	* @param key The key of `data`.
+	* @param value The value.
+	*/
+	set(key, value) {
+		this.data[key] = value;
+	}
+	/**
+	* Adds a value to the list at a key of `data`.
+	* @param key The key of `data`; the list is made when it is missing.
+	* @param value The value.
+	*/
+	push(key, value) {
+		const list = this.data[key];
+		if (Array.isArray(list)) list.push(value);
+		else this.data[key] = [value];
+	}
+	/**
+	* Adds a warning.
+	* @param code The stable code.
+	* @param message The sentence.
+	*/
+	warn(code, message) {
+		this.warnings.push({
+			code,
+			message
+		});
+	}
+	/**
+	* Records the failure. The first code wins; a later message is added to the first.
+	* @param code The stable code.
+	* @param message The sentence.
+	*/
+	fail(code, message) {
+		this.error = this.error === void 0 ? {
+			code,
+			message
+		} : {
+			...this.error,
+			message: `${this.error.message} ${message}`
+		};
+	}
+};
+/**
+* A successful document.
+* @param command The command that ran.
+* @param data The facts of the command.
+* @param warnings The warnings; none by default.
+* @returns The document.
+* @example
+* jsonSuccess("shadow-ui list", { items: [] }).ok; // true
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function jsonSuccess(command, data, warnings = []) {
+	return {
+		schema: 1,
+		command,
+		ok: true,
+		data,
+		warnings
+	};
+}
+/**
+* A failed document.
+* @param command The command that ran.
+* @param error The code and the message.
+* @param data What is known despite the failure.
+* @param warnings The warnings raised before it.
+* @returns The document, with `ok: false`.
+* @example
+* jsonFailure("shadow-ui add", { code: "SHADOW_UI_NO_CONFIG", message: "no components.json" }).ok; // false
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function jsonFailure(command, error, data = {}, warnings = []) {
+	return {
+		schema: 1,
+		command,
+		ok: false,
+		data,
+		warnings,
+		error
+	};
+}
+/**
+* The document as text, without the final newline (the output adds one).
+* @param document The document.
+* @param compact True for one line.
+* @returns The JSON text.
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function jsonText(document, compact = false) {
+	return JSON.stringify(document, null, compact ? void 0 : 2);
+}
+/**
+* Whether the command line asks for JSON: `--json` anywhere before a `--`. Read before the line is parsed, so a refused
+* command line is answered in JSON too.
+* @param argv The arguments after `shadow-ui`.
+* @returns True for `--json`.
+* @example
+* wantsJson(["list", "--json"]); // true
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function wantsJson(argv) {
+	for (const arg of argv) {
+		if (arg === "--") return false;
+		if (arg === "--json") return true;
+	}
+	return false;
+}
+/**
+* Prints an uncaught exception or a rejected promise as a JSON failure, then exits 1. Installed by the executable when the
+* command line asks for JSON, so a crash is no exception to "stdout carries one document". A reader that went away
+* (`| head -n 1` closed the pipe) is not a crash: the process exits quietly.
+* @param argv The arguments after `shadow-ui`; the first word that is not an option names the command.
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function installCrashHandlers(argv) {
+	let crashed = false;
+	const crash = (error) => {
+		if (typeof error === "object" && error !== null && Reflect.get(error, "code") === "EPIPE") process.exit(0);
+		if (crashed) process.exit(1);
+		crashed = true;
+		const message = error instanceof Error ? error.message : String(error);
+		if (error instanceof Error && error.stack !== void 0) process.stderr.write(`${error.stack}\n`);
+		const word = argv.find((arg) => !arg.startsWith("-"));
+		const document = jsonFailure(word === void 0 ? "shadow-ui" : `shadow-ui ${word}`, {
+			code: "SHADOW_UI_UNEXPECTED",
+			message: `unexpected error: ${message}`
+		});
+		process.stdout.write(`${jsonText(document)}\n`, () => process.exit(1));
+	};
+	process.on("uncaughtException", crash);
+	process.on("unhandledRejection", crash);
+}
+/** The edit script turning `a` into `b`; one big replacement when the texts are too large. */
+function edits(a, b) {
+	const n = a.length;
+	const m = b.length;
+	const max = n + m;
+	if (max > 2e4) return [...a.map((line) => ({
+		kind: "delete",
+		line
+	})), ...b.map((line) => ({
+		kind: "insert",
+		line
+	}))];
+	const offset = max;
+	let frontier = new Int32Array(2 * max + 2);
+	const trace = [];
+	let reached = -1;
+	for (let d = 0; d <= max && reached === -1; d += 1) {
+		trace.push(frontier.slice());
+		const next = frontier.slice();
+		for (let k = -d; k <= d; k += 2) {
+			let x;
+			const below = frontier[offset + k - 1] ?? 0;
+			const above = frontier[offset + k + 1] ?? 0;
+			if (k === -d || k !== d && below < above) x = above;
+			else x = below + 1;
+			let y = x - k;
+			while (x < n && y < m && a[x] === b[y]) {
+				x += 1;
+				y += 1;
+			}
+			next[offset + k] = x;
+			if (x >= n && y >= m) {
+				reached = d;
+				break;
+			}
+		}
+		frontier = next;
+	}
+	const result = [];
+	let x = n;
+	let y = m;
+	for (let d = reached; d > 0; d -= 1) {
+		const previous = trace[d] ?? /* @__PURE__ */ new Int32Array(0);
+		const k = x - y;
+		const below = previous[offset + k - 1] ?? 0;
+		const above = previous[offset + k + 1] ?? 0;
+		const previousK = k === -d || k !== d && below < above ? k + 1 : k - 1;
+		const previousX = previous[offset + previousK] ?? 0;
+		const previousY = previousX - previousK;
+		while (x > previousX && y > previousY) {
+			x -= 1;
+			y -= 1;
+			result.push({
+				kind: "equal",
+				line: a[x] ?? ""
+			});
+		}
+		if (x === previousX) {
+			y -= 1;
+			result.push({
+				kind: "insert",
+				line: b[y] ?? ""
+			});
+		} else {
+			x -= 1;
+			result.push({
+				kind: "delete",
+				line: a[x] ?? ""
+			});
+		}
+	}
+	while (x > 0 && y > 0) {
+		x -= 1;
+		y -= 1;
+		result.push({
+			kind: "equal",
+			line: a[x] ?? ""
+		});
+	}
+	return result.reverse();
+}
+/** Text to lines, ignoring the line-ending style and a final newline. */
+function toLines(text) {
+	const lines = text.replace(/\r\n/g, "\n").split("\n");
+	if (lines[lines.length - 1] === "") lines.pop();
+	return lines;
+}
+/**
+* Whether two texts are the same apart from line endings (CRLF vs LF) and a trailing newline.
+*
+* @param a One text.
+* @param b Another text.
+* @returns `true` when they have the same lines.
+* @example
+* sameContent("a\r\nb\r\n", "a\nb"); // true
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function sameContent(a, b) {
+	const left = toLines(a);
+	const right = toLines(b);
+	return left.length === right.length && left.every((line, index) => line === right[index]);
+}
+/**
+* A unified diff (3 lines of context) from `before` to `after`.
+*
+* @param before The old text (what is on disk).
+* @param after The new text (what the registry has).
+* @param labels Names for the `---` and `+++` header lines.
+* @returns The diff, or `""` when the texts have the same lines.
+* @example
+* unifiedDiff("a\n", "b\n", { before: "local", after: "registry" });
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function unifiedDiff(before, after, labels, context = 3) {
+	const script = edits(toLines(before), toLines(after));
+	if (script.every((operation) => operation.kind === "equal")) return "";
+	const hunks = [];
+	let index = 0;
+	let oldLine = 1;
+	let newLine = 1;
+	const lineNumbers = [];
+	for (const operation of script) {
+		lineNumbers.push({
+			old: oldLine,
+			new: newLine
+		});
+		if (operation.kind !== "insert") oldLine += 1;
+		if (operation.kind !== "delete") newLine += 1;
+	}
+	while (index < script.length) {
+		while (index < script.length && script[index]?.kind === "equal") index += 1;
+		if (index >= script.length) break;
+		const start = Math.max(0, index - context);
+		let end = index;
+		let lastChange = index;
+		while (end < script.length) {
+			if (script[end]?.kind !== "equal") lastChange = end;
+			else if (end - lastChange > context * 2) break;
+			end += 1;
+		}
+		const stop = Math.min(script.length, lastChange + context + 1);
+		const slice = script.slice(start, stop);
+		const oldCount = slice.filter((operation) => operation.kind !== "insert").length;
+		const newCount = slice.filter((operation) => operation.kind !== "delete").length;
+		const first = lineNumbers[start] ?? {
+			old: 1,
+			new: 1
+		};
+		hunks.push(`@@ -${oldCount === 0 ? first.old - 1 : first.old},${oldCount} +${newCount === 0 ? first.new - 1 : first.new},${newCount} @@`, ...slice.map((operation) => `${operation.kind === "equal" ? " " : operation.kind === "insert" ? "+" : "-"}${operation.line}`));
+		index = stop;
+	}
+	return [
+		`--- ${labels.before}`,
+		`+++ ${labels.after}`,
+		...hunks
+	].join("\n");
+}
+//#endregion
+//#region src/cli/paths.ts
+/**
+* Path handling: reading `tsconfig` path aliases, mapping an import alias to a directory, and the
+* guard that keeps every write inside the project. Pure except for the `ProjectFs` it is handed.
+* @packageDocumentation
+*/
+/**
+* Thrown when a path would leave the project or an alias cannot be mapped to a directory.
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+var PathError = class extends Error {
+	/** The stable code `--json` prints. */
+	code = "SHADOW_UI_UNSAFE_PATH";
+	constructor(message) {
+		super(message);
+		this.name = "PathError";
+	}
+};
+/**
+* Drops the commas that stand right before a closing `}` or `]`. String literals are copied as they
+* are, so a comma inside a string never changes.
+*/
+function dropTrailingCommas(text) {
+	let out = "";
+	let index = 0;
+	while (index < text.length) {
+		const char = text[index] ?? "";
+		if (char === "\"") {
+			let end = index + 1;
+			while (end < text.length && text[end] !== "\"") end += text[end] === "\\" ? 2 : 1;
+			out += text.slice(index, end + 1);
+			index = end + 1;
+			continue;
+		}
+		if (char === ",") {
+			const closing = /\s*[}\]]/y;
+			closing.lastIndex = index + 1;
+			if (closing.test(text)) {
+				index += 1;
+				continue;
+			}
+		}
+		out += char;
+		index += 1;
+	}
+	return out;
+}
+/**
+* Parses JSON with comments and trailing commas, as tsconfig files are written. Line and block
+* comments are removed, and trailing commas are dropped; the contents of strings are left as they
+* are.
+*
+* @param text JSON with comments.
+* @returns The parsed value.
+* @throws SyntaxError when the cleaned text is not JSON.
+* @example
+* parseJsonc('{ // comment\n "a": 1, }'); // { a: 1 }
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function parseJsonc(text) {
+	let out = "";
+	let index = 0;
+	while (index < text.length) {
+		const char = text[index] ?? "";
+		const next = text[index + 1] ?? "";
+		if (char === "\"") {
+			let end = index + 1;
+			while (end < text.length && text[end] !== "\"") end += text[end] === "\\" ? 2 : 1;
+			out += text.slice(index, end + 1);
+			index = end + 1;
+		} else if (char === "/" && next === "/") while (index < text.length && text[index] !== "\n") index += 1;
+		else if (char === "/" && next === "*") {
+			const end = text.indexOf("*/", index + 2);
+			index = end === -1 ? text.length : end + 2;
+		} else {
+			out += char;
+			index += 1;
+		}
+	}
+	return JSON.parse(dropTrailingCommas(out));
+}
+function asRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+/**
+* Reads the `compilerOptions.paths` of the project's tsconfig files (`tsconfig.json`,
+* `tsconfig.app.json`). Targets are resolved against `baseUrl` or the config's directory.
+*
+* @param fs The project filesystem.
+* @param root The project root.
+* @returns The mappings, first file first.
+* @example
+* readPathMappings(fs, "/app"); // [{ pattern: "@/*", targets: ["/app/src/*"] }]
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function readPathMappings(fs, root) {
+	const mappings = [];
+	for (const name of ["tsconfig.json", "tsconfig.app.json"]) {
+		const text = fs.read(join(root, name));
+		if (text === void 0) continue;
+		const options = asRecord(asRecord(parseJsonc(text))?.["compilerOptions"]);
+		const paths = asRecord(options?.["paths"]);
+		if (paths === void 0) continue;
+		const base = typeof options?.["baseUrl"] === "string" ? resolve(root, options["baseUrl"]) : root;
+		for (const [pattern, targets] of Object.entries(paths)) {
+			if (!Array.isArray(targets)) continue;
+			mappings.push({
+				pattern,
+				targets: targets.filter((target) => typeof target === "string").map((target) => resolve(base, target))
+			});
+		}
+	}
+	return mappings;
+}
+/**
+* Maps an import alias directory (`@/components/ui`) to an absolute directory using the tsconfig
+* mappings.
+*
+* @param alias The alias from `components.json`.
+* @param mappings From {@link readPathMappings}.
+* @returns The absolute directory path.
+* @throws PathError when no mapping covers the alias.
+* @example
+* aliasToDirectory("@/components/ui", [{ pattern: "@/*", targets: ["/app/src/*"] }]);
+* // "/app/src/components/ui"
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function aliasToDirectory(alias, mappings) {
+	for (const { pattern, targets } of mappings) {
+		const star = pattern.indexOf("*");
+		if (star === -1) {
+			if (pattern === alias && targets[0] !== void 0) return targets[0];
+			continue;
+		}
+		const prefix = pattern.slice(0, star);
+		const suffix = pattern.slice(star + 1);
+		if (!alias.startsWith(prefix) || !alias.endsWith(suffix) || alias.length < prefix.length + suffix.length) continue;
+		const rest = alias.slice(prefix.length, alias.length - suffix.length);
+		const target = targets[0];
+		if (target !== void 0) return target.replace("*", rest);
+	}
+	throw new PathError(`The alias "${alias}" is not covered by "paths" in tsconfig.json. Add, for example:\n  "compilerOptions": { "paths": { "@/*": ["./src/*"] } }`);
+}
+/**
+* Resolves `target` against `root` and throws unless the result is inside `root`. This is the
+* single guard every write and delete goes through.
+*
+* @param root The project root (absolute).
+* @param target A path, absolute or relative to `root`.
+* @returns The normalized absolute path.
+* @throws PathError when the path escapes the project.
+* @example
+* resolveInside("/app", "src/a.ts"); // "/app/src/a.ts"
+* resolveInside("/app", "../x"); // throws
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function resolveInside(root, target) {
+	const absolute = resolve(root, target);
+	const rel = relative(resolve(root), absolute);
+	if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new PathError(`Refusing to write outside the project: ${target}`);
+	return absolute;
+}
+/**
+* Like {@link resolveInside} but also follows symbolic links of the nearest existing ancestor, so
+* a symlinked directory cannot be used to write outside the project.
+*
+* @param fs The project filesystem.
+* @param root The project root.
+* @param target A path, absolute or relative to `root`.
+* @returns The normalized absolute path.
+* @throws PathError when the path, or its real location, is outside the project.
+* @example
+* resolveInsideReal(fs, "/app", "src/components/ui/button.tsx");
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function resolveInsideReal(fs, root, target) {
+	const absolute = resolveInside(root, target);
+	const real = fs.realpath(absolute);
+	const realRoot = fs.realpath(resolve(root));
+	const rel = relative(realRoot, real);
+	if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new PathError(`Refusing to write outside the project (symbolic link): ${target}`);
+	return absolute;
+}
+//#endregion
+//#region src/cli/pm.ts
+/**
+* Package manager detection and the install command line. npm is the default; pnpm, yarn and bun
+* are used when their lockfile (or the `packageManager` field) says so.
+* @packageDocumentation
+*/
+/**
+* Detects the project's package manager: the `packageManager` field of `package.json` first, then
+* lockfiles, otherwise npm.
+*
+* @param fs The project filesystem.
+* @param root The project root.
+* @returns The package manager name.
+* @example
+* detectPackageManager(fs, "/app"); // "pnpm" when /app/pnpm-lock.yaml exists
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function detectPackageManager(fs, root) {
+	const manifest = fs.read(join(root, "package.json"));
+	if (manifest !== void 0) try {
+		const field = JSON.parse(manifest).packageManager;
+		if (typeof field === "string") {
+			const name = field.split("@")[0];
+			if (name === "npm" || name === "pnpm" || name === "yarn" || name === "bun") return name;
+		}
+	} catch (error) {
+		if (!(error instanceof SyntaxError)) throw error;
+	}
+	if (fs.exists(join(root, "pnpm-lock.yaml"))) return "pnpm";
+	if (fs.exists(join(root, "yarn.lock"))) return "yarn";
+	if (fs.exists(join(root, "bun.lock")) || fs.exists(join(root, "bun.lockb"))) return "bun";
+	return "npm";
+}
+/**
+* The command and arguments that install `packages` as dependencies.
+*
+* @param manager The package manager.
+* @param packages Package specifiers (`clsx@2.1.1`).
+* @returns The executable and its arguments.
+* @example
+* installCommand("npm", ["clsx@2.1.1"]); // { command: "npm", args: ["install", "clsx@2.1.1"] }
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function installCommand(manager, packages) {
+	switch (manager) {
+		case "npm": return {
+			command: "npm",
+			args: ["install", ...packages]
+		};
+		case "pnpm": return {
+			command: "pnpm",
+			args: ["add", ...packages]
+		};
+		case "yarn": return {
+			command: "yarn",
+			args: ["add", ...packages]
+		};
+		case "bun": return {
+			command: "bun",
+			args: ["add", ...packages]
+		};
+	}
+}
+//#endregion
+//#region src/cli/schema.ts
+/**
+* The base colors, in documentation order.
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+const BASE_COLORS = [
+	"neutral",
+	"zinc",
+	"slate",
+	"stone",
+	"gray"
+];
+/**
+* The default aliases (shadcn's).
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+const DEFAULT_ALIASES = {
+	components: "@/components",
+	ui: "@/components/ui",
+	lib: "@/lib",
+	utils: "@/lib/utils",
+	hooks: "@/hooks"
+};
+/** Registry item names are kebab-case; nothing else may reach a file path. */
+const NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** A file name inside `registry/<name>/`. */
+const FILE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+* Whether `name` is a valid registry item name.
+*
+* @param name Any string.
+* @returns `true` for kebab-case names such as `dropdown-menu`.
+* @example
+* isValidItemName("../etc/passwd"); // false
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function isValidItemName(name) {
+	return NAME_PATTERN.test(name);
+}
+/**
+* Thrown for malformed registry or configuration data.
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+var SchemaError = class extends Error {
+	/** The stable code `--json` prints. */
+	code = "SHADOW_UI_INVALID_FILE";
+	constructor(message) {
+		super(message);
+		this.name = "SchemaError";
+	}
+};
+function record(value, where) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new SchemaError(`${where} must be an object`);
+	return value;
+}
+function text(value, where) {
+	if (typeof value !== "string" || value === "") throw new SchemaError(`${where} must be a string`);
+	return value;
+}
+function strings(value, where) {
+	if (!Array.isArray(value)) throw new SchemaError(`${where} must be an array`);
+	return value.map((entry, index) => text(entry, `${where}[${index}]`));
+}
+function itemType(value, where) {
+	if (value === "ui" || value === "lib" || value === "hook") return value;
+	throw new SchemaError(`${where} must be "ui", "lib" or "hook"`);
+}
+function parseItem(value, index) {
+	const where = `items[${index}]`;
+	const item = record(value, where);
+	const name = text(item["name"], `${where}.name`);
+	if (!isValidItemName(name)) throw new SchemaError(`${where}.name "${name}" is not a valid name`);
+	const files = item["files"];
+	if (!Array.isArray(files) || files.length === 0) throw new SchemaError(`${where}.files must be a non-empty array`);
+	const dependencies = record(item["dependencies"], `${where}.dependencies`);
+	const tailwind = record(item["tailwind"], `${where}.tailwind`);
+	return {
+		name,
+		type: itemType(item["type"], `${where}.type`),
+		title: text(item["title"], `${where}.title`),
+		description: text(item["description"], `${where}.description`),
+		files: files.map((file, fileIndex) => {
+			const entry = record(file, `${where}.files[${fileIndex}]`);
+			const path = text(entry["path"], `${where}.files[${fileIndex}].path`);
+			const segments = path.split("/");
+			const [root, folder, base] = segments;
+			if (segments.length !== 3 || root !== "registry" || folder !== name || base === void 0 || !FILE_PATTERN.test(base)) throw new SchemaError(`${where}.files[${fileIndex}].path "${path}" must be registry/${name}/<file>`);
+			return {
+				path,
+				type: itemType(entry["type"], `${where}.files[${fileIndex}].type`)
+			};
+		}),
+		registryDependencies: strings(item["registryDependencies"], `${where}.registryDependencies`),
+		dependencies: Object.fromEntries(Object.entries(dependencies).map(([pkg, version]) => [pkg, text(version, `${where}.dependencies.${pkg}`)])),
+		exports: strings(item["exports"], `${where}.exports`),
+		primitives: strings(item["primitives"], `${where}.primitives`),
+		tailwind: {
+			tokens: strings(tailwind["tokens"], `${where}.tailwind.tokens`),
+			animations: tailwind["animations"] === true
+		}
+	};
+}
+/**
+* Validates parsed `registry.json` data.
+*
+* @param value The parsed JSON.
+* @returns The typed index.
+* @throws SchemaError naming the first malformed field.
+* @example
+* const index = parseRegistryIndex(JSON.parse(readFileSync("registry.json", "utf8")));
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function parseRegistryIndex(value) {
+	const root = record(value, "registry");
+	const items = root["items"];
+	if (!Array.isArray(items)) throw new SchemaError("registry.items must be an array");
+	const parsed = items.map(parseItem);
+	const seen = /* @__PURE__ */ new Set();
+	for (const item of parsed) {
+		if (seen.has(item.name)) throw new SchemaError(`registry has two items named "${item.name}"`);
+		seen.add(item.name);
+	}
+	return {
+		name: text(root["name"], "registry.name"),
+		version: text(root["version"], "registry.version"),
+		frameworkDependencies: strings(root["frameworkDependencies"], "registry.frameworkDependencies"),
+		items: parsed
+	};
+}
+/**
+* Validates parsed `components.json` data.
+*
+* @param value The parsed JSON.
+* @returns The typed configuration, with defaults for missing aliases.
+* @throws SchemaError naming the first malformed field.
+* @example
+* const config = parseComponentsConfig(JSON.parse(readFileSync("components.json", "utf8")));
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function parseComponentsConfig(value) {
+	const root = record(value, "components.json");
+	const tailwind = record(root["tailwind"], "components.json tailwind");
+	const baseColor = tailwind["baseColor"] ?? "neutral";
+	if (!BASE_COLORS.includes(baseColor)) throw new SchemaError(`components.json tailwind.baseColor must be one of ${BASE_COLORS.join(", ")}`);
+	const given = root["aliases"] === void 0 ? {} : record(root["aliases"], "components.json aliases");
+	const alias = (key) => {
+		const entry = given[key];
+		if (entry === void 0) return DEFAULT_ALIASES[key];
+		const aliasText = text(entry, `components.json aliases.${key}`);
+		if (aliasText.includes("..") || /\s/.test(aliasText)) throw new SchemaError(`components.json aliases.${key} "${aliasText}" is not a valid alias`);
+		return aliasText;
+	};
+	const framework = root["framework"];
+	return {
+		framework: framework === "vite" || framework === "dusk" ? framework : "unknown",
+		tailwind: {
+			css: text(tailwind["css"], "components.json tailwind.css"),
+			baseColor
+		},
+		aliases: {
+			components: alias("components"),
+			ui: alias("ui"),
+			lib: alias("lib"),
+			utils: alias("utils"),
+			hooks: alias("hooks")
+		}
+	};
+}
+//#endregion
+//#region src/cli/project.ts
+/**
+* The project the CLI works in: `components.json`, `package.json`, the stylesheet that imports
+* Tailwind, and the theme stylesheet `init` generates. Reads through {@link ProjectFs}.
+* @packageDocumentation
+*/
+/**
+* The file name of the generated theme stylesheet.
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+const THEME_FILE = "shadow-ui.css";
+/**
+* Reads the project's `package.json`.
+*
+* @param fs The project filesystem.
+* @param root The project root.
+* @returns The manifest, or `undefined` when there is no `package.json`.
+* @throws SchemaError when the file is not valid JSON.
+* @example
+* readManifest(fs, "/app")?.packages.has("vite");
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function readManifest(fs, root) {
+	const text = fs.read(join(root, "package.json"));
+	if (text === void 0) return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		if (error instanceof SyntaxError) throw new SchemaError(`package.json is not valid JSON: ${error.message}`);
+		throw error;
+	}
+	const packages = /* @__PURE__ */ new Set();
+	if (typeof parsed === "object" && parsed !== null) for (const field of [
+		"dependencies",
+		"devDependencies",
+		"peerDependencies",
+		"optionalDependencies"
+	]) {
+		const group = parsed[field];
+		if (typeof group === "object" && group !== null) for (const name of Object.keys(group)) packages.add(name);
+	}
+	return { packages };
+}
+/**
+* Reads and validates `components.json`.
+*
+* @param fs The project filesystem.
+* @param root The project root.
+* @returns The configuration, or `undefined` when the file does not exist.
+* @throws SchemaError when the file is malformed.
+* @example
+* const config = readConfig(fs, "/app");
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function readConfig(fs, root) {
+	const text = fs.read(join(root, "components.json"));
+	if (text === void 0) return void 0;
+	try {
+		return parseComponentsConfig(JSON.parse(text));
+	} catch (error) {
+		if (error instanceof SyntaxError) throw new SchemaError(`components.json is not valid JSON: ${error.message}`);
+		throw error;
+	}
+}
+/**
+* The text of `components.json` for a configuration.
+*
+* @param config The configuration.
+* @returns Pretty-printed JSON ending in a newline.
+* @example
+* fs.write("components.json", serializeConfig(config));
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function serializeConfig(config) {
+	return `${JSON.stringify({
+		framework: config.framework,
+		tailwind: {
+			css: config.tailwind.css,
+			baseColor: config.tailwind.baseColor
+		},
+		aliases: config.aliases
+	}, null, 2)}\n`;
+}
+const CSS_CANDIDATES = [
+	"src/index.css",
+	"src/styles.css",
+	"src/app.css",
+	"src/global.css",
+	"src/globals.css",
+	"src/styles/globals.css",
+	"src/styles/global.css",
+	"src/styles/index.css",
+	"app/app.css",
+	"app/globals.css"
+];
+const TAILWIND_IMPORT = /@import\s+["']tailwindcss["']|@import\s+["']tailwindcss\//;
+/**
+* Detects the framework, whether Tailwind is installed, and the stylesheet to extend.
+*
+* @param fs The project filesystem.
+* @param root The project root.
+* @param manifest The project's manifest.
+* @returns What was found.
+* @example
+* detectProject(fs, "/app", manifest).framework; // "vite"
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function detectProject(fs, root, manifest) {
+	const framework = manifest.packages.has("@shadow-js/dusk") ? "dusk" : manifest.packages.has("vite") || manifest.packages.has("@shadow-js/vite") ? "vite" : "unknown";
+	let existing;
+	for (const candidate of CSS_CANDIDATES) {
+		const text = fs.read(join(root, candidate));
+		if (text === void 0) continue;
+		if (TAILWIND_IMPORT.test(text)) {
+			existing = candidate;
+			break;
+		}
+		existing ??= candidate;
+	}
+	return {
+		framework,
+		hasTailwind: manifest.packages.has("tailwindcss"),
+		hasTailwindVite: manifest.packages.has("@tailwindcss/vite"),
+		css: {
+			path: existing ?? (framework === "dusk" ? "src/app.css" : "src/index.css"),
+			exists: existing !== void 0
+		}
+	};
+}
+/** Vite config files, in the order Vite looks for them. */
+const VITE_CONFIGS = [
+	"vite.config.ts",
+	"vite.config.mts",
+	"vite.config.js",
+	"vite.config.mjs",
+	"vite.config.cts",
+	"vite.config.cjs"
+];
+/** An `@` alias in a Vite config: `"@": ...`, `find: "@"`, or a plugin that reads tsconfig `paths`. */
+const VITE_ALIAS = /["']@["']\s*:|\bfind\s*:\s*["']@["']|tsconfig-?paths|tsconfigPaths/i;
+/** The Tailwind Vite plugin in a Vite config. */
+const VITE_TAILWIND = /@tailwindcss\/vite|\btailwindcss\s*\(/;
+/**
+* What the project's Vite config already has, so `init` prints only the steps that are missing.
+* The check reads the config as text (it is TypeScript that may import anything): a config that
+* builds its alias or plugin list in a way this does not recognize is reported as missing, which
+* costs a redundant hint, never a wrong edit.
+*
+* @param fs The project filesystem.
+* @param root The project root.
+* @returns `undefined` when no Vite config file exists.
+* @example
+* readViteSetup(fs, "/app")?.alias; // true when `"@"` is aliased
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function readViteSetup(fs, root) {
+	for (const file of VITE_CONFIGS) {
+		const text = fs.read(join(root, file));
+		if (text === void 0) continue;
+		return {
+			file,
+			alias: VITE_ALIAS.test(text),
+			tailwind: VITE_TAILWIND.test(text)
+		};
+	}
+}
+/**
+* The default `components.json` for a project.
+*
+* @param info From {@link detectProject}.
+* @param baseColor The chosen base color.
+* @param css Override for the stylesheet path.
+* @returns A complete configuration.
+* @example
+* defaultConfig(info, "zinc");
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function defaultConfig(info, baseColor, css) {
+	return {
+		framework: info.framework,
+		tailwind: {
+			css: css ?? info.css.path,
+			baseColor
+		},
+		aliases: DEFAULT_ALIASES
+	};
+}
+/**
+* The theme stylesheet `init` writes into the project: the base color variables, the Tailwind v4
+* token mapping and base layer, and the animation utilities, in one file.
+*
+* @param source The registry source.
+* @param baseColor The base color.
+* @returns CSS text.
+* @example
+* fs.write("src/shadow-ui.css", buildThemeCss(registry, "neutral"));
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function buildThemeCss(source, baseColor) {
+	return [
+		"/* Generated by `shadow-ui init`. Edit freely: this file is yours. */",
+		source.readStyle(`themes/${baseColor}.css`).trimEnd(),
+		source.readStyle("theme-core.css").trim(),
+		source.readStyle("animations.css").trim(),
+		""
+	].join("\n\n");
+}
+/**
+* The `@import` line that pulls the theme stylesheet into the entry stylesheet (the theme file is
+* written next to it).
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+const THEME_IMPORT_LINE = `@import "./${THEME_FILE}";`;
+/**
+* Inserts the theme import after the Tailwind import of a stylesheet.
+*
+* @param css The entry stylesheet's text.
+* @returns The new text, or `undefined` when the import is already there or no Tailwind import exists.
+* @example
+* insertThemeImport('@import "tailwindcss";\n'); // '@import "tailwindcss";\n@import "./shadow-ui.css";\n'
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function insertThemeImport(css) {
+	if (css.includes("shadow-ui.css")) return void 0;
+	const lines = css.split("\n");
+	const at = lines.findIndex((entry) => TAILWIND_IMPORT.test(entry));
+	if (at === -1) return void 0;
+	lines.splice(at + 1, 0, THEME_IMPORT_LINE);
+	return lines.join("\n");
+}
+/**
+* Project-relative path for display (forward slashes).
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function display(root, absolute) {
+	return relative(root, absolute).replaceAll("\\", "/");
+}
+/**
+* The theme file next to a stylesheet.
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function themePathFor(cssPath) {
+	return join(dirname(cssPath), THEME_FILE);
+}
+//#endregion
+//#region src/cli/resolve.ts
+/**
+* Registry resolution: from the names a user typed to the ordered list of items to copy and the
+* npm packages they need. Pure: no filesystem, no network.
+* @packageDocumentation
+*/
+/**
+* Thrown for an unknown or invalid item name, a `registryDependencies` entry that is not in the
+* registry, a dependency cycle, or conflicting versions of one npm package.
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+var ResolveError = class extends Error {
+	/** The stable code `--json` prints: `SHADOW_UI_UNKNOWN_COMPONENT`, `SHADOW_UI_INVALID_NAME` or `SHADOW_UI_REGISTRY_CONFLICT`. */
+	code;
+	constructor(message, code = "SHADOW_UI_UNKNOWN_COMPONENT") {
+		super(message);
+		this.name = "ResolveError";
+		this.code = code;
+	}
+};
+/** Levenshtein distance, for "did you mean" hints. Names are short, so the plain table is fine. */
+function distance(a, b) {
+	const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+	for (let i = 1; i <= a.length; i += 1) {
+		let diagonal = row[0] ?? 0;
+		row[0] = i;
+		for (let j = 1; j <= b.length; j += 1) {
+			const above = row[j] ?? 0;
+			row[j] = Math.min(above + 1, (row[j - 1] ?? 0) + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+			diagonal = above;
+		}
+	}
+	return row[b.length] ?? 0;
+}
+function suggestion(index, name) {
+	let best;
+	let bestDistance = 3;
+	for (const item of index.items) {
+		const d = distance(name, item.name);
+		if (d < bestDistance) {
+			best = item.name;
+			bestDistance = d;
+		}
+	}
+	return best === void 0 ? "" : ` Did you mean "${best}"?`;
+}
+/**
+* Finds an item by name.
+*
+* @param index The registry.
+* @param name The item name.
+* @returns The item, or `undefined` when there is none.
+* @example
+* findItem(index, "button")?.files;
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function findItem(index, name) {
+	return index.items.find((item) => item.name === name);
+}
+/**
+* Resolves requested names to a copy plan: transitive `registryDependencies`, dependencies first,
+* each item once. The order is deterministic: depth-first, in the order of the request and of each
+* item's `registryDependencies`. Traversal is iterative, so a deep dependency chain cannot overflow
+* the stack.
+*
+* @param index The registry.
+* @param names Requested item names.
+* @returns The plan.
+* @throws ResolveError for an invalid or unknown name, a dependency missing from the registry, a
+*   cycle, or two versions of one npm package.
+* @example
+* resolveItems(index, ["dialog"]).items.map((item) => item.name); // ["utils", "icons", "dialog"]
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function resolveItems(index, names) {
+	const requested = [...new Set(names)];
+	const ordered = [];
+	const done = /* @__PURE__ */ new Set();
+	const visiting = /* @__PURE__ */ new Set();
+	for (const root of requested) {
+		if (!isValidItemName(root)) throw new ResolveError(`"${root}" is not a valid component name.`, "SHADOW_UI_INVALID_NAME");
+		if (done.has(root)) continue;
+		const first = findItem(index, root);
+		if (first === void 0) throw new ResolveError(`Unknown component "${root}".${suggestion(index, root)}`);
+		const stack = [{
+			item: first,
+			next: 0
+		}];
+		visiting.add(root);
+		while (stack.length > 0) {
+			const frame = stack[stack.length - 1];
+			if (frame === void 0) break;
+			const dependency = frame.item.registryDependencies[frame.next];
+			if (dependency === void 0) {
+				stack.pop();
+				visiting.delete(frame.item.name);
+				if (!done.has(frame.item.name)) {
+					done.add(frame.item.name);
+					ordered.push(frame.item);
+				}
+				continue;
+			}
+			frame.next += 1;
+			if (done.has(dependency)) continue;
+			if (visiting.has(dependency)) throw new ResolveError(`Circular registry dependency: ${[...stack.map((entry) => entry.item.name), dependency].join(" -> ")}`, "SHADOW_UI_REGISTRY_CONFLICT");
+			const item = findItem(index, dependency);
+			if (item === void 0) throw new ResolveError(`"${frame.item.name}" depends on "${dependency}", which is not in the registry.`, "SHADOW_UI_REGISTRY_CONFLICT");
+			visiting.add(dependency);
+			stack.push({
+				item,
+				next: 0
+			});
+		}
+	}
+	const dependencies = {};
+	for (const item of ordered) for (const [name, version] of Object.entries(item.dependencies)) {
+		const known = dependencies[name];
+		if (known !== void 0 && known !== version) throw new ResolveError(`"${name}" is required at both ${known} and ${version}.`, "SHADOW_UI_REGISTRY_CONFLICT");
+		dependencies[name] = version;
+	}
+	return {
+		requested,
+		items: ordered,
+		dependencies: Object.fromEntries(Object.entries(dependencies).sort(([a], [b]) => a.localeCompare(b))),
+		usesPrimitives: ordered.some((item) => item.primitives.length > 0),
+		usesAnimations: ordered.some((item) => item.tailwind.animations)
+	};
+}
+/**
+* The items that import `name`, directly or not, among `candidates` (used by `remove` to refuse
+* deleting something another installed item needs).
+*
+* @param index The registry.
+* @param name The item to be removed.
+* @param candidates Names of installed items to check.
+* @returns The candidates that depend on `name`, sorted.
+* @example
+* dependentsOf(index, "utils", ["button", "dialog"]); // ["button", "dialog"]
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function dependentsOf(index, name, candidates) {
+	const found = [];
+	for (const candidate of candidates) {
+		if (candidate === name || !isValidItemName(candidate)) continue;
+		if (findItem(index, candidate) === void 0) continue;
+		if (resolveItems(index, [candidate]).items.some((entry) => entry.name === name)) found.push(candidate);
+	}
+	return found.sort();
+}
+//#endregion
+//#region src/cli/rewrite.ts
+/**
+* Maps one import specifier from the registry layout to the project's aliases.
+*
+* @param specifier An import specifier such as `@/components/ui/button`.
+* @param aliases The aliases from `components.json`.
+* @returns The rewritten specifier, or the input unchanged when it is not a registry alias.
+* @example
+* rewriteSpecifier("@/lib/utils", { ...aliases, utils: "~/helpers/cn" }); // "~/helpers/cn"
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function rewriteSpecifier(specifier, aliases) {
+	if (specifier === "@/lib/utils") return aliases.utils;
+	if (specifier.startsWith("@/components/ui/")) return `${aliases.ui}/${specifier.slice(16)}`;
+	if (specifier.startsWith("@/hooks/")) return `${aliases.hooks}/${specifier.slice(8)}`;
+	if (specifier.startsWith("@/lib/")) return `${aliases.lib}/${specifier.slice(6)}`;
+	return specifier;
+}
+/** `from "x"`, `import "x"`, `import("x")` and `export ... from "x"` specifiers. */
+const SPECIFIER = /(\bfrom\s*|\bimport\s*\(\s*|\bimport\s+)(["'])(@\/[^"'\n]+)\2/g;
+/**
+* Rewrites every registry-alias import in `source` to the project's aliases. Only module
+* specifiers are touched (static imports, re-exports, dynamic imports); other strings are not.
+*
+* @param source A registry file's text.
+* @param aliases The aliases from `components.json`.
+* @returns The text with rewritten specifiers.
+* @example
+* rewriteImports('import { cn } from "@/lib/utils";', aliases);
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function rewriteImports(source, aliases) {
+	return source.replace(SPECIFIER, (_match, lead, quote, specifier) => `${lead}${quote}${rewriteSpecifier(specifier, aliases)}${quote}`);
+}
+//#endregion
+//#region src/cli/commands.ts
+/**
+* The CLI commands. Each takes a {@link CliContext} (filesystem, registry, output, prompt and
+* installer are parameters), so tests run them against a temp directory with a recording
+* installer. Every command returns the process exit code.
+* @packageDocumentation
+*/
+/** Exit codes. */
+const OK = 0;
+const FAILED = 1;
+/** Prints an error and records it for `--json`. @returns The failing exit code. */
+function problem(ctx, code, message) {
+	ctx.err(`error: ${message}`);
+	ctx.report?.fail(code, message);
+	return FAILED;
+}
+/** Prints a warning and records it for `--json`. */
+function caution(ctx, code, message) {
+	ctx.err(`warning: ${message}`);
+	ctx.report?.warn(code, message);
+}
+/** Records one file of the document's `files`. */
+function recordFile(ctx, path, action, diff) {
+	ctx.report?.push("files", diff === void 0 ? {
+		path,
+		action
+	} : {
+		path,
+		action,
+		diff
+	});
+}
+function failed(ctx, error) {
+	if (error instanceof SchemaError || error instanceof ResolveError || error instanceof PathError) return problem(ctx, error.code, error.message);
+	throw error;
+}
+function requireProject(ctx) {
+	const manifest = readManifest(ctx.fs, ctx.cwd);
+	if (manifest === void 0) problem(ctx, "SHADOW_UI_NO_PROJECT", "no package.json here. Run this command in the root of your project.");
+	return manifest;
+}
+function requireConfig(ctx) {
+	const config = readConfig(ctx.fs, ctx.cwd);
+	if (config === void 0) problem(ctx, "SHADOW_UI_NO_CONFIG", "components.json not found. Run `shadow-ui init` first.");
+	return config;
+}
+/** The directory (absolute) an item's files go to. */
+function directoryFor(item, config, mappings, ctx, pathOverride) {
+	if (item.type === "ui" && pathOverride !== void 0) return resolve(ctx.cwd, pathOverride);
+	if (item.type === "ui") return aliasToDirectory(config.aliases.ui, mappings);
+	if (item.type === "hook") return aliasToDirectory(config.aliases.hooks, mappings);
+	return aliasToDirectory(config.aliases.lib, mappings);
+}
+/** The absolute target of one registry file, checked to be inside the project. */
+function targetFor(item, file, config, mappings, ctx, pathOverride) {
+	const base = file.path.slice(file.path.lastIndexOf("/") + 1);
+	if (item.type === "lib" && item.name === "utils") return resolveInsideReal(ctx.fs, ctx.cwd, `${aliasToDirectory(config.aliases.utils, mappings)}${extname(base)}`);
+	return resolveInsideReal(ctx.fs, ctx.cwd, join(directoryFor(item, config, mappings, ctx, pathOverride), base));
+}
+/** Builds the per-file plan for the items, reading what is on disk. */
+function planFiles(ctx, config, items, pathOverride, mappings = readPathMappings(ctx.fs, ctx.cwd)) {
+	const plans = [];
+	for (const item of items) for (const file of item.files) {
+		const raw = ctx.registry.readFile(file.path);
+		const content = file.path.endsWith(".css") ? raw : rewriteImports(raw, config.aliases);
+		const target = targetFor(item, file, config, mappings, ctx, pathOverride);
+		const current = ctx.fs.read(target);
+		plans.push({
+			item,
+			file,
+			target,
+			content,
+			current,
+			status: current === void 0 ? "create" : sameContent(current, content) ? "unchanged" : "differs"
+		});
+	}
+	return plans;
+}
+function diffOf(plan, ctx) {
+	return unifiedDiff(plan.current ?? "", plan.content, {
+		before: `a/${display(ctx.cwd, plan.target)} (yours)`,
+		after: `b/${display(ctx.cwd, plan.target)} (registry)`
+	});
+}
+/** Missing packages the plan needs, as install specifiers. */
+function missingPackages(ctx, needed, framework) {
+	const installed = readManifest(ctx.fs, ctx.cwd)?.packages ?? /* @__PURE__ */ new Set();
+	const missing = [];
+	for (const name of framework) if (!installed.has(name)) missing.push(name);
+	for (const [name, version] of Object.entries(needed)) if (!installed.has(name)) missing.push(`${name}@${version}`);
+	return missing;
+}
+async function installMissing(ctx, packages, flags) {
+	if (packages.length === 0) return OK;
+	const manager = detectPackageManager(ctx.fs, ctx.cwd);
+	const { command, args } = installCommand(manager, packages);
+	const line = [command, ...args].join(" ");
+	const record = (status) => ctx.report?.push("installs", {
+		status,
+		manager,
+		packages,
+		command: line
+	});
+	if (flags.dryRun) {
+		ctx.out(`would run: ${line}`);
+		record("dry-run");
+		return OK;
+	}
+	if (flags.skipInstall) {
+		ctx.out(`Install the packages yourself: ${line}`);
+		record("skipped");
+		return OK;
+	}
+	if (!(flags.yes || await ctx.confirm(`Install ${packages.join(", ")} with ${manager}?`))) {
+		ctx.out(`Skipped. Install the packages yourself: ${line}`);
+		record("skipped");
+		return OK;
+	}
+	ctx.out(`running: ${line}`);
+	try {
+		await ctx.install({
+			cwd: ctx.cwd,
+			manager,
+			packages,
+			output: ctx.report === void 0 ? "inherit" : "stderr"
+		});
+	} catch (error) {
+		record("failed");
+		return problem(ctx, "SHADOW_UI_INSTALL_FAILED", `${line} failed: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	record("installed");
+	return OK;
+}
+/**
+* Copies components into the project, with everything they import.
+*
+* Resolves `registryDependencies` transitively, rewrites imports to the configured aliases, writes
+* new files, leaves identical files alone, and shows a diff for files that differ. A differing file
+* is replaced with `overwrite` or when the user confirms; otherwise it is kept and the exit code is 1.
+* Installs the npm packages the files import that the project lacks. Every target is checked to be
+* inside the project.
+*
+* @param ctx The CLI context.
+* @param names Component names (ignored with `flags.all`).
+* @param flags The flags.
+* @returns The exit code: 0 on success, 1 on any error or when a differing file was kept.
+* @example
+* await runAdd(ctx, ["button", "dialog"], { overwrite: false, dryRun: false, yes: true, skipInstall: false, all: false, path: undefined });
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+async function runAdd(ctx, names, flags) {
+	try {
+		if (requireProject(ctx) === void 0) return FAILED;
+		const config = requireConfig(ctx);
+		if (config === void 0) return FAILED;
+		const requested = flags.all ? ctx.registry.index.items.map((item) => item.name) : names;
+		if (requested.length === 0) return problem(ctx, "SHADOW_UI_NO_COMPONENTS", "name at least one component, e.g. `shadow-ui add button`, or pass --all.");
+		const plan = resolveItems(ctx.registry.index, requested);
+		const extra = plan.items.map((item) => item.name).filter((name) => !plan.requested.includes(name));
+		ctx.report?.set("dryRun", flags.dryRun);
+		ctx.report?.set("requested", plan.requested);
+		ctx.report?.set("dependencies", extra);
+		ctx.report?.set("files", []);
+		ctx.out(`Adding ${plan.requested.join(", ")}${extra.length > 0 ? ` (and ${extra.join(", ")} they depend on)` : ""}`);
+		const files = planFiles(ctx, config, plan.items, flags.path);
+		let kept = 0;
+		for (const entry of files) {
+			const where = display(ctx.cwd, entry.target);
+			if (entry.status === "unchanged") {
+				ctx.out(`  unchanged  ${where}`);
+				recordFile(ctx, where, "unchanged");
+				continue;
+			}
+			if (entry.status === "create") {
+				ctx.out(`  ${flags.dryRun ? "would create" : "create"}  ${where}`);
+				if (!flags.dryRun) ctx.fs.write(entry.target, entry.content);
+				recordFile(ctx, where, "create");
+				continue;
+			}
+			ctx.out(`  differs    ${where}`);
+			const diff = diffOf(entry, ctx);
+			for (const line of diff.split("\n")) ctx.out(`    ${line}`);
+			if (flags.dryRun) {
+				recordFile(ctx, where, "differs", diff);
+				continue;
+			}
+			if (flags.overwrite || !flags.yes && await ctx.confirm(`Overwrite ${where}?`)) {
+				ctx.fs.write(entry.target, entry.content);
+				ctx.out(`  overwrote  ${where}`);
+				recordFile(ctx, where, "overwrite");
+			} else {
+				kept += 1;
+				ctx.out(`  kept       ${where} (pass --overwrite to replace it)`);
+				recordFile(ctx, where, "kept", diff);
+			}
+		}
+		if (plan.usesAnimations) {
+			const css = ctx.fs.read(join(ctx.cwd, config.tailwind.css));
+			if (!ctx.fs.exists(join(ctx.cwd, themePathFor(config.tailwind.css))) && !(css ?? "").includes("animate-in")) caution(ctx, "SHADOW_UI_NO_ANIMATIONS", `these components animate; run \`shadow-ui init\` to add ${THEME_FILE} (animation utilities).`);
+		}
+		const installFailed = await installMissing(ctx, missingPackages(ctx, plan.dependencies, plan.usesPrimitives ? ctx.registry.index.frameworkDependencies : []), flags);
+		if (kept > 0) {
+			const message = `${kept} file(s) differ from the registry and were kept.`;
+			ctx.err(message);
+			ctx.report?.fail("SHADOW_UI_FILES_DIFFER", message);
+		}
+		return installFailed === OK && kept === 0 ? OK : FAILED;
+	} catch (error) {
+		return failed(ctx, error);
+	}
+}
+/**
+* Sets a project up: writes `components.json`, `lib/utils`, and the theme stylesheet, wires the
+* stylesheet in, installs the helper packages, and prints what remains to configure by hand.
+* An existing file is kept unless `overwrite` is set. The one exception is `components.json`: a
+* changed base color or stylesheet (from the flags) rewrites it, keeping the aliases.
+*
+* @param ctx The CLI context.
+* @param flags The flags.
+* @returns The exit code.
+* @example
+* await runInit(ctx, { overwrite: false, dryRun: false, yes: true, skipInstall: false, baseColor: "zinc", css: undefined });
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+async function runInit(ctx, flags) {
+	try {
+		const manifest = requireProject(ctx);
+		if (manifest === void 0) return FAILED;
+		const info = detectProject(ctx.fs, ctx.cwd, manifest);
+		if (info.framework === "unknown") caution(ctx, "SHADOW_UI_UNKNOWN_FRAMEWORK", "neither Vite nor @shadow-js/dusk found in package.json; continuing with Vite defaults.");
+		const existing = readConfig(ctx.fs, ctx.cwd);
+		const baseColor = flags.baseColor ?? existing?.tailwind.baseColor ?? "neutral";
+		const config = existing === void 0 || flags.overwrite ? defaultConfig(info, baseColor, flags.css) : {
+			...existing,
+			tailwind: {
+				css: flags.css ?? existing.tailwind.css,
+				baseColor
+			}
+		};
+		const write = (path, content, label) => {
+			const absolute = resolveInsideReal(ctx.fs, ctx.cwd, path);
+			const current = ctx.fs.read(absolute);
+			if (current !== void 0 && !flags.overwrite) {
+				if (!sameContent(current, content)) {
+					ctx.out(`  kept       ${label} (exists; pass --overwrite to replace it)`);
+					recordFile(ctx, label, "kept");
+				} else {
+					ctx.out(`  unchanged  ${label}`);
+					recordFile(ctx, label, "unchanged");
+				}
+				return "kept";
+			}
+			ctx.out(`  ${flags.dryRun ? "would write" : "write"}   ${label}`);
+			if (!flags.dryRun) ctx.fs.write(absolute, content);
+			recordFile(ctx, label, current === void 0 ? "create" : "update");
+			return "created";
+		};
+		ctx.report?.set("dryRun", flags.dryRun);
+		ctx.report?.set("config", {
+			baseColor,
+			css: config.tailwind.css
+		});
+		ctx.report?.set("files", []);
+		ctx.out("Setting up @shadow-js/ui");
+		const configText = serializeConfig(config);
+		const configPath = resolveInsideReal(ctx.fs, ctx.cwd, "components.json");
+		const configNow = ctx.fs.read(configPath);
+		if (existing !== void 0 && !flags.overwrite && configNow !== void 0 && (config.tailwind.baseColor !== existing.tailwind.baseColor || config.tailwind.css !== existing.tailwind.css) && !sameContent(configNow, configText)) {
+			ctx.out(`  ${flags.dryRun ? "would update" : "updated"}   components.json (base color ${config.tailwind.baseColor}, stylesheet ${config.tailwind.css})`);
+			if (!flags.dryRun) ctx.fs.write(configPath, configText);
+			recordFile(ctx, "components.json", "update");
+		} else write("components.json", configText, "components.json");
+		const themeFile = themePathFor(config.tailwind.css);
+		const themeLabel = themeFile.replaceAll("\\", "/");
+		const themeText = buildThemeCss(ctx.registry, config.tailwind.baseColor);
+		const themeCurrent = ctx.fs.read(resolveInsideReal(ctx.fs, ctx.cwd, themeFile));
+		const recolor = existing !== void 0 && !flags.overwrite && existing.tailwind.baseColor !== config.tailwind.baseColor && themeCurrent !== void 0;
+		if (recolor && sameContent(themeCurrent, buildThemeCss(ctx.registry, existing.tailwind.baseColor))) {
+			ctx.out(`  ${flags.dryRun ? "would write" : "write"}   ${themeLabel} (${config.tailwind.baseColor})`);
+			if (!flags.dryRun) ctx.fs.write(resolveInsideReal(ctx.fs, ctx.cwd, themeFile), themeText);
+			recordFile(ctx, themeLabel, "update");
+		} else if (recolor) {
+			ctx.out(`  kept       ${themeLabel} (edited; pass --overwrite to regenerate it for ${config.tailwind.baseColor})`);
+			recordFile(ctx, themeLabel, "kept");
+		} else write(themeFile, themeText, themeLabel);
+		const cssPath = resolveInsideReal(ctx.fs, ctx.cwd, config.tailwind.css);
+		const css = ctx.fs.read(cssPath);
+		if (css === void 0) write(config.tailwind.css, `@import "tailwindcss";\n${THEME_IMPORT_LINE}\n`, config.tailwind.css);
+		else {
+			const next = insertThemeImport(css);
+			if (next === void 0) {
+				ctx.out(`  unchanged  ${config.tailwind.css} (${css.includes("shadow-ui.css") ? "already imports the theme" : "no `@import \"tailwindcss\"` line; add the import yourself"})`);
+				recordFile(ctx, config.tailwind.css, "unchanged");
+			} else if (flags.dryRun) {
+				ctx.out(`  would add  ${THEME_IMPORT_LINE} to ${config.tailwind.css}`);
+				recordFile(ctx, config.tailwind.css, "update");
+			} else if (flags.yes || await ctx.confirm(`Add @import "./shadow-ui.css"; to ${config.tailwind.css}?`)) {
+				ctx.fs.write(cssPath, next);
+				ctx.out(`  edited     ${config.tailwind.css} (added ${THEME_IMPORT_LINE})`);
+				recordFile(ctx, config.tailwind.css, "update");
+			} else {
+				ctx.out(`  skipped    add this line after the Tailwind import of ${config.tailwind.css}: ${THEME_IMPORT_LINE}`);
+				recordFile(ctx, config.tailwind.css, "skipped");
+			}
+		}
+		const added = await runAddForInit(ctx, config, flags);
+		if (added !== OK) return added;
+		const tooling = [];
+		if (!info.hasTailwind) tooling.push("tailwindcss");
+		if (!info.hasTailwindVite) tooling.push("@tailwindcss/vite");
+		const installed = await installMissing(ctx, tooling, flags);
+		printNextSteps(ctx, config, info.framework);
+		return installed;
+	} catch (error) {
+		return failed(ctx, error);
+	}
+}
+/** `init` copies `utils` through the same pipeline as `add`. */
+async function runAddForInit(ctx, config, flags) {
+	const plan = resolveItems(ctx.registry.index, ["utils"]);
+	const mappings = [...readPathMappings(ctx.fs, ctx.cwd), {
+		pattern: "@/*",
+		targets: [join(ctx.cwd, "src", "*")]
+	}];
+	for (const entry of planFiles(ctx, config, plan.items, void 0, mappings)) {
+		const where = display(ctx.cwd, entry.target);
+		if (entry.status === "unchanged") {
+			ctx.out(`  unchanged  ${where}`);
+			recordFile(ctx, where, "unchanged");
+		} else if (entry.status === "differs" && !flags.overwrite) {
+			ctx.out(`  kept       ${where} (exists; pass --overwrite to replace it)`);
+			recordFile(ctx, where, "kept");
+		} else {
+			ctx.out(`  ${flags.dryRun ? "would write" : "write"}   ${where}`);
+			if (!flags.dryRun) ctx.fs.write(entry.target, entry.content);
+			recordFile(ctx, where, entry.status === "create" ? "create" : "update");
+		}
+	}
+	return installMissing(ctx, missingPackages(ctx, plan.dependencies, []), flags);
+}
+function printNextSteps(ctx, config, framework) {
+	const mappings = readPathMappings(ctx.fs, ctx.cwd);
+	const vite = readViteSetup(ctx.fs, ctx.cwd);
+	ctx.out("");
+	ctx.out("Next steps");
+	let step = 1;
+	const say = (text) => {
+		ctx.out(`  ${step++}. ${text}`);
+		ctx.report?.push("nextSteps", text);
+	};
+	try {
+		aliasToDirectory(config.aliases.ui, mappings);
+	} catch (error) {
+		if (!(error instanceof PathError)) throw error;
+		say("Add the import alias to tsconfig.json: \"compilerOptions\": { \"paths\": { \"@/*\": [\"./src/*\"] } }");
+	}
+	if (framework !== "unknown" || vite !== void 0) {
+		const file = vite?.file ?? "vite.config.ts";
+		const tailwind = vite?.tailwind === true;
+		if (vite?.alias !== true) say(`Make Vite resolve "@": in ${file} add \`resolve: { alias: { "@": fileURLToPath(new URL("./src", import.meta.url)) } }\` (\`fileURLToPath\` is from "node:url").`);
+		if (!tailwind) say(`Add \`tailwindcss()\` from @tailwindcss/vite to \`plugins\` in ${file}.`);
+	} else say("Make Vite resolve \"@\": in vite.config.ts add `resolve: { alias: { \"@\": fileURLToPath(new URL(\"./src\", import.meta.url)) } }` and `tailwindcss()` from @tailwindcss/vite to `plugins`.");
+	say(`Import ${config.tailwind.css} once in your entry file (it already imports ${THEME_FILE}).`);
+	say("Prevent a flash of the wrong theme: put the text of themeScript() from \"@shadow-js/ui\" in a <script> in <head> (README, \"Dark mode\"), and wrap the app in <ThemeProvider>.");
+	say("Add components: shadow-ui add button dialog");
+}
+/**
+* Lists the registry's components and whether each is already in the project. In a `--json` run
+* (`ctx.report` is set) the rows are recorded as `items`, with `initialized` saying whether `components.json` exists.
+*
+* @param ctx The CLI context.
+* @returns The exit code.
+* @example
+* runList(ctx);
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function runList(ctx) {
+	try {
+		const config = readConfig(ctx.fs, ctx.cwd);
+		const mappings = config === void 0 ? [] : readPathMappings(ctx.fs, ctx.cwd);
+		const rows = ctx.registry.index.items.map((item) => {
+			let installed = false;
+			if (config !== void 0) {
+				const main = item.files[0];
+				if (main !== void 0) try {
+					installed = ctx.fs.exists(targetFor(item, main, config, mappings, ctx, void 0));
+				} catch (error) {
+					if (!(error instanceof PathError)) throw error;
+				}
+			}
+			return {
+				name: item.name,
+				type: item.type,
+				description: item.description,
+				installed
+			};
+		});
+		ctx.report?.set("initialized", config !== void 0);
+		ctx.report?.set("items", rows);
+		const width = Math.max(...rows.map((row) => row.name.length));
+		for (const row of rows) ctx.out(`${row.installed ? "*" : " "} ${row.name.padEnd(width)}  ${row.description}`);
+		ctx.out("");
+		ctx.out(`${rows.length} items${config === void 0 ? "" : "; * = already in your project"}`);
+		return OK;
+	} catch (error) {
+		return failed(ctx, error);
+	}
+}
+/**
+* Compares the project's copy of components with the registry's and prints a unified diff of each
+* that differs. With no names, checks every component that is in the project.
+*
+* @param ctx The CLI context.
+* @param names Component names, or empty for all installed ones.
+* @returns 0 when every checked file matches, 1 when a checked file differs or a named component is
+*   not in the project.
+* @example
+* await runDiff(ctx, ["button"]);
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function runDiff(ctx, names) {
+	try {
+		if (requireProject(ctx) === void 0) return FAILED;
+		const config = requireConfig(ctx);
+		if (config === void 0) return FAILED;
+		for (const name of names) {
+			if (!isValidItemName(name)) throw new ResolveError(`"${name}" is not a valid component name.`);
+			if (findItem(ctx.registry.index, name) === void 0) throw new ResolveError(`Unknown component "${name}".`);
+		}
+		const items = (names.length === 0 ? ctx.registry.index.items : names.map((name) => findItem(ctx.registry.index, name))).filter((item) => item !== void 0);
+		let differing = 0;
+		let checked = 0;
+		ctx.report?.set("components", []);
+		const record = (name, path, status, diff) => ctx.report?.push("components", diff === void 0 ? {
+			name,
+			path,
+			status
+		} : {
+			name,
+			path,
+			status,
+			diff
+		});
+		for (const entry of planFiles(ctx, config, items, void 0)) {
+			const where = display(ctx.cwd, entry.target);
+			if (entry.status === "create") {
+				if (names.length > 0) {
+					ctx.out(`${entry.item.name}: not in your project (${where})`);
+					record(entry.item.name, where, "missing");
+					differing += 1;
+				}
+				continue;
+			}
+			checked += 1;
+			if (entry.status === "unchanged") {
+				if (names.length > 0) ctx.out(`${entry.item.name}: up to date (${where})`);
+				record(entry.item.name, where, "up-to-date");
+				continue;
+			}
+			differing += 1;
+			ctx.out(`${entry.item.name}: differs (${where})`);
+			const diff = diffOf(entry, ctx);
+			ctx.out(diff);
+			record(entry.item.name, where, "differs", diff);
+		}
+		if (names.length === 0) ctx.out(`${checked} file(s) checked, ${differing} differ from the registry.`);
+		ctx.report?.set("checked", checked);
+		ctx.report?.set("differing", differing);
+		if (differing > 0) ctx.report?.fail("SHADOW_UI_DIFFERS", `${differing} file(s) differ from the registry or are missing from the project.`);
+		return differing === 0 ? OK : FAILED;
+	} catch (error) {
+		return failed(ctx, error);
+	}
+}
+/**
+* Deletes components' files from the project. Refuses when another component that is in the
+* project imports one of them (unless `force`), and never removes npm packages.
+*
+* @param ctx The CLI context.
+* @param names Component names.
+* @param flags The flags.
+* @returns The exit code.
+* @example
+* await runRemove(ctx, ["badge"], { dryRun: false, force: false });
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function runRemove(ctx, names, flags) {
+	try {
+		if (requireProject(ctx) === void 0) return FAILED;
+		const config = requireConfig(ctx);
+		if (config === void 0) return FAILED;
+		if (names.length === 0) return problem(ctx, "SHADOW_UI_NO_COMPONENTS", "name at least one component to remove.");
+		const mappings = readPathMappings(ctx.fs, ctx.cwd);
+		const installedNames = ctx.registry.index.items.filter((item) => {
+			const main = item.files[0];
+			return main !== void 0 && ctx.fs.exists(targetFor(item, main, config, mappings, ctx, void 0));
+		}).map((item) => item.name);
+		const removing = resolveItems(ctx.registry.index, names).requested;
+		ctx.report?.set("dryRun", flags.dryRun);
+		ctx.report?.set("removed", []);
+		let code = OK;
+		for (const name of removing) {
+			const blockers = dependentsOf(ctx.registry.index, name, installedNames).filter((other) => !removing.includes(other));
+			if (blockers.length > 0 && !flags.force) {
+				problem(ctx, "SHADOW_UI_IN_USE", `${name} is used by ${blockers.join(", ")}; remove those first or pass --force.`);
+				ctx.report?.push("blocked", {
+					name,
+					usedBy: blockers
+				});
+				code = FAILED;
+				continue;
+			}
+			const item = findItem(ctx.registry.index, name);
+			if (item === void 0) continue;
+			for (const file of item.files) {
+				const target = targetFor(item, file, config, mappings, ctx, void 0);
+				if (!ctx.fs.exists(target)) continue;
+				const where = display(ctx.cwd, target);
+				ctx.out(`  ${flags.dryRun ? "would remove" : "remove"}  ${where}`);
+				if (!flags.dryRun) ctx.fs.remove(target);
+				ctx.report?.push("removed", {
+					name,
+					path: where
+				});
+			}
+		}
+		return code;
+	} catch (error) {
+		return failed(ctx, error);
+	}
+}
+//#endregion
+//#region src/cli/completion.ts
+/**
+* Shell completion scripts for the `shadow-ui` command. Each script is static text built from the
+* commands and flags it is given. It never calls back into the CLI, so it cannot complete
+* component names.
+* @packageDocumentation
+*/
+/**
+* The shells `shadow-ui completion` writes a script for.
+* @example
+* const shells: readonly string[] = SHELLS; // ["bash", "zsh", "fish"]
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+const SHELLS = [
+	"bash",
+	"zsh",
+	"fish"
+];
+/**
+* The shells as a phrase for messages: `bash, zsh or fish`.
+* @example
+* const phrase: string = SHELL_CHOICES; // "bash, zsh or fish"
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+const SHELL_CHOICES = `${SHELLS.slice(0, -1).join(", ")} or ${SHELLS[SHELLS.length - 1]}`;
+/**
+* Tells whether a word names one of the shells {@link SHELLS} lists.
+* @param value The word from the command line, if any.
+* @returns `true` when `value` is `bash`, `zsh` or `fish`.
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function isShell(value) {
+	return value !== void 0 && SHELLS.includes(value);
+}
+/**
+* Builds the completion script for one shell. The script has no trailing newline.
+* @param shell The shell the script is for.
+* @param spec The commands and long flags the script offers.
+* @returns The script text, ready to save or to `source`.
+* @example
+* const script = completionScript("bash", { commands: ["init", "add"], flags: ["yes"] });
+* // script begins with "# bash completion for shadow-ui" and its last line is
+* // "complete -o default -F _shadow_ui shadow-ui"
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function completionScript(shell, spec) {
+	const commands = spec.commands.join(" ");
+	switch (shell) {
+		case "bash": return bashScript(commands, spec.flags.map((flag) => `--${flag}`));
+		case "zsh": return zshScript(commands, spec.flags.map((flag) => `--${flag}`));
+		case "fish": return fishScript(commands, spec.flags);
+	}
+}
+function bashScript(commands, flags) {
+	return [
+		"# bash completion for shadow-ui. Save it in your bash-completion directory as shadow-ui,",
+		"# or run: source <(shadow-ui completion bash)",
+		"_shadow_ui() {",
+		"  local cur",
+		"  cur=\"${COMP_WORDS[COMP_CWORD]}\"",
+		"  if [ \"$COMP_CWORD\" -eq 1 ]; then",
+		`    COMPREPLY=( $(compgen -W "${commands}" -- "$cur") )`,
+		"  elif [[ \"$cur\" == -* ]]; then",
+		`    COMPREPLY=( $(compgen -W "${flags.join(" ")}" -- "$cur") )`,
+		"  fi",
+		"  return 0",
+		"}",
+		"complete -o default -F _shadow_ui shadow-ui"
+	].join("\n");
+}
+function zshScript(commands, flags) {
+	return [
+		"#compdef shadow-ui",
+		"",
+		"_shadow_ui() {",
+		"  local -a commands flags",
+		`  commands=(${commands})`,
+		`  flags=(${flags.join(" ")})`,
+		"  if (( CURRENT == 2 )); then",
+		"    compadd -- $commands",
+		"  elif [[ $PREFIX == -* ]]; then",
+		"    compadd -- $flags",
+		"  else",
+		"    _files",
+		"  fi",
+		"}",
+		"",
+		"if [[ $funcstack[1] == _shadow_ui ]]; then",
+		"  _shadow_ui \"$@\"",
+		"else",
+		"  compdef _shadow_ui shadow-ui",
+		"fi"
+	].join("\n");
+}
+function fishScript(commands, flags) {
+	return [
+		"# fish completion for shadow-ui. Save it as ~/.config/fish/completions/shadow-ui.fish,",
+		"# or run: shadow-ui completion fish | source",
+		`complete -c shadow-ui -f -n __fish_use_subcommand -a "${commands}"`,
+		`complete -c shadow-ui -f -n "__fish_seen_subcommand_from completion" -a "${SHELLS.join(" ")}"`,
+		...flags.map((flag) => `complete -c shadow-ui -l ${flag}`)
+	].join("\n");
+}
+//#endregion
+//#region src/cli/main.ts
+/**
+* Argument parsing and dispatch for the `shadow-ui` command. `main` takes its context as a
+* parameter, so it is tested without spawning a process.
+* @packageDocumentation
+*/
+/** Subcommand names the shell completion offers, aliases included. */
+const COMMANDS = [
+	"init",
+	"add",
+	"list",
+	"ls",
+	"diff",
+	"remove",
+	"rm",
+	"completion",
+	"help"
+];
+const HELP = `shadow-ui: add shadcn-style components to a ShadowJS project
+
+Usage
+  shadow-ui init [options]            set up components.json, lib/utils and the theme
+  shadow-ui add <name...> [options]   copy components (and what they import) into the project
+  shadow-ui list                      list the registry; * marks components in your project
+  shadow-ui diff [name...]            compare your copy with the registry (exit 1 if it differs)
+  shadow-ui remove <name...>          delete components from the project
+  shadow-ui completion <shell>        print a bash, zsh or fish completion script
+
+Options
+  -y, --yes            answer yes to confirmations (never overwrites by itself)
+  -o, --overwrite      replace files that differ from the registry
+      --dry-run        print what would happen, change nothing
+  -a, --all            add: every component
+      --path <dir>     add: write ui components to <dir> instead of the configured alias
+      --skip-install   do not install npm packages; print the command instead
+      --base-color <c> init: ${BASE_COLORS.join(" | ")} (default neutral)
+      --css <file>     init: the stylesheet that imports Tailwind
+      --force          remove: even if another component uses it
+      --cwd <dir>      run in <dir>
+  -h, --help           show this help
+  -v, --version        show the version of @shadow-js/ui
+      --json           print one JSON document on stdout instead of words (every command; nothing is asked)
+`;
+const OPTIONS = {
+	yes: {
+		type: "boolean",
+		short: "y"
+	},
+	overwrite: {
+		type: "boolean",
+		short: "o"
+	},
+	"dry-run": { type: "boolean" },
+	all: {
+		type: "boolean",
+		short: "a"
+	},
+	path: { type: "string" },
+	"skip-install": { type: "boolean" },
+	"base-color": { type: "string" },
+	css: { type: "string" },
+	force: { type: "boolean" },
+	json: { type: "boolean" },
+	cwd: { type: "string" },
+	help: {
+		type: "boolean",
+		short: "h"
+	},
+	version: {
+		type: "boolean",
+		short: "v"
+	}
+};
+/** The command a document names: `shadow-ui add` (an alias is named by its command). */
+const CANONICAL = {
+	ls: "list",
+	rm: "remove"
+};
+/**
+* Runs the CLI. With `--json` (anywhere before a `--`) every outcome is one JSON document on stdout, in the contract of
+* `json.ts`: the command's facts in `data`, its warnings in `warnings`, its failure in `error`. The human lines that
+* `data` already holds are left out, the warnings and errors still go to stderr, nothing is asked, and an installer's
+* output goes to stderr. The exit codes are the same with and without `--json`.
+*
+* @param argv The arguments after the executable (`["add", "button"]`).
+* @param context Builds the context for a working directory (`--cwd` overrides the default).
+* @returns The process exit code.
+* @example
+* process.exitCode = await main(process.argv.slice(2), (cwd) => realContext(cwd));
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+async function main(argv, context) {
+	const json = wantsJson(argv);
+	let parsed;
+	const base = context(void 0);
+	/** Prints a document: the one thing a `--json` run writes on stdout. */
+	const emit = (document) => base.out(jsonText(document));
+	try {
+		parsed = parseArgs({
+			args: [...argv],
+			options: OPTIONS,
+			allowPositionals: true,
+			strict: true
+		});
+	} catch (error) {
+		if (error instanceof TypeError) {
+			if (json) {
+				const message = error.message.split(". ")[0] ?? error.message;
+				emit(jsonFailure("shadow-ui", {
+					code: /^Unknown option/.test(message) ? "SHADOW_UI_UNKNOWN_OPTION" : "SHADOW_UI_INVALID_OPTION",
+					message
+				}));
+				return 1;
+			}
+			base.err(`error: ${error.message}`);
+			base.err("Run `shadow-ui --help` for usage.");
+			return 1;
+		}
+		throw error;
+	}
+	const { values, positionals } = parsed;
+	const [command, ...rest] = positionals;
+	if (values.help === true || command === "help" || command === void 0 && values.version !== true) {
+		const missing = command === void 0 && values.help !== true;
+		if (json) emit(missing ? jsonFailure("shadow-ui", {
+			code: "SHADOW_UI_MISSING_COMMAND",
+			message: "no command given. Run `shadow-ui --help` for usage."
+		}) : jsonSuccess("shadow-ui", { usage: HELP }));
+		else base.out(HELP);
+		return missing ? 1 : 0;
+	}
+	if (values.version === true) {
+		const version = base.version ?? base.registry.index.version;
+		if (json) emit(jsonSuccess("shadow-ui", { version }));
+		else base.out(version);
+		return 0;
+	}
+	const real = values.cwd === void 0 ? base : context(values.cwd);
+	const report = json ? new Report() : void 0;
+	const ctx = report === void 0 ? real : {
+		...real,
+		out: () => void 0,
+		confirm: async () => false,
+		report
+	};
+	const scope = `shadow-ui ${CANONICAL[command ?? ""] ?? command ?? ""}`.trimEnd();
+	const common = {
+		overwrite: values.overwrite === true,
+		dryRun: values["dry-run"] === true,
+		yes: values.yes === true,
+		skipInstall: values["skip-install"] === true
+	};
+	let code;
+	try {
+		code = await dispatch(ctx, command, rest, values, common);
+	} catch (error) {
+		if (report === void 0) throw error;
+		const message = error instanceof Error ? error.message : String(error);
+		if (error instanceof Error && error.stack !== void 0) ctx.err(error.stack);
+		report.fail("SHADOW_UI_UNEXPECTED", `unexpected error: ${message}`);
+		code = 1;
+	}
+	if (report !== void 0) {
+		const unknown = command === void 0 || !COMMANDS.includes(command);
+		const document = code === 0 ? jsonSuccess(scope, report.data, report.warnings) : jsonFailure(unknown ? "shadow-ui" : scope, report.error ?? {
+			code: "SHADOW_UI_FAILED",
+			message: "the command failed."
+		}, report.data, report.warnings);
+		real.out(jsonText(document));
+	}
+	return code;
+}
+/** Runs the named command. */
+async function dispatch(ctx, command, rest, values, common) {
+	switch (command) {
+		case "init": {
+			const color = values["base-color"];
+			if (color !== void 0 && !BASE_COLORS.includes(color)) {
+				const message = `--base-color must be one of ${BASE_COLORS.join(", ")}`;
+				ctx.err(`error: ${message}`);
+				ctx.report?.fail("SHADOW_UI_INVALID_BASE_COLOR", message);
+				return 1;
+			}
+			return runInit(ctx, {
+				...common,
+				baseColor: color,
+				css: values.css
+			});
+		}
+		case "add": return runAdd(ctx, rest, {
+			...common,
+			all: values.all === true,
+			path: values.path
+		});
+		case "list":
+		case "ls": return runList(ctx);
+		case "diff": return runDiff(ctx, rest);
+		case "remove":
+		case "rm": return runRemove(ctx, rest, {
+			dryRun: common.dryRun,
+			force: values.force === true
+		});
+		case "completion": {
+			const shell = rest[0];
+			if (!isShell(shell)) {
+				const message = shell === void 0 ? `completion needs a shell: ${SHELL_CHOICES}` : `unknown shell "${shell}": use ${SHELL_CHOICES}`;
+				ctx.err(`error: ${message}`);
+				ctx.report?.fail("SHADOW_UI_INVALID_SHELL", message);
+				return 1;
+			}
+			const script = completionScript(shell, {
+				commands: COMMANDS,
+				flags: Object.keys(OPTIONS)
+			});
+			if (ctx.report !== void 0) {
+				ctx.report.set("shell", shell);
+				ctx.report.set("script", script);
+				return 0;
+			}
+			for (const line of script.split("\n")) ctx.out(line);
+			return 0;
+		}
+		default: {
+			const message = `unknown command "${command ?? ""}"`;
+			ctx.err(`error: ${message}`);
+			ctx.err("Run `shadow-ui --help` for usage.");
+			ctx.report?.fail("SHADOW_UI_UNKNOWN_COMMAND", message);
+			return 1;
+		}
+	}
+}
+//#endregion
+//#region src/cli/registry-source.ts
+/**
+* Where the CLI reads the registry from. The registry ships inside the package, so nothing is
+* downloaded: `registry.json` plus the files under `registry/` and `styles/`.
+* @packageDocumentation
+*/
+/**
+* Builds a source from an index and two reader functions (tests use in-memory ones).
+*
+* @param index The parsed index.
+* @param read Reads a package-relative file.
+* @returns The source. Only files named in the index, and the known stylesheets, can be read.
+* @example
+* const source = createRegistrySource(index, (path) => files[path]);
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function createRegistrySource(index, read) {
+	const listed = new Set(index.items.flatMap((item) => item.files.map((file) => file.path)));
+	const styles = /* @__PURE__ */ new Set([
+		"theme-core.css",
+		"animations.css",
+		...BASE_COLORS.map((base) => `themes/${base}.css`)
+	]);
+	const fetch = (path) => {
+		const text = read(path);
+		if (text === void 0) throw new Error(`The registry file "${path}" is missing from the package.`);
+		return text;
+	};
+	return {
+		index,
+		readFile(path) {
+			if (!listed.has(path)) throw new Error(`"${path}" is not a registry file.`);
+			return fetch(path);
+		},
+		readStyle(name) {
+			if (!styles.has(name)) throw new Error(`"${name}" is not a registry stylesheet.`);
+			return fetch(`styles/${name}`);
+		}
+	};
+}
+/** The package root: the nearest ancestor of this file with the `@shadow-js/ui` package.json. */
+function packageRoot() {
+	let directory = dirname(fileURLToPath(import.meta.url));
+	for (;;) {
+		const manifest = join(directory, "package.json");
+		if (existsSync(manifest)) {
+			if (JSON.parse(readFileSync(manifest, "utf8")).name === "@shadow-js/ui") return directory;
+		}
+		const parent = dirname(directory);
+		if (parent === directory) throw new Error("Cannot locate the @shadow-js/ui package.");
+		directory = parent;
+	}
+}
+/**
+* Opens the registry that ships with this package.
+*
+* @param root Package root override (for tests).
+* @returns The source.
+* @throws SchemaError when `registry.json` is malformed, or an Error when it or a registry file cannot be read.
+* @example
+* const registry = loadRegistrySource();
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function loadRegistrySource(root = packageRoot()) {
+	return createRegistrySource(parseRegistryIndex(JSON.parse(readFileSync(join(root, "registry.json"), "utf8"))), (path) => {
+		const file = join(root, path);
+		return existsSync(file) ? readFileSync(file, "utf8") : void 0;
+	});
+}
+//#endregion
+//#region src/cli/bin.ts
+/**
+* The `shadow-ui` executable: wires the real filesystem, terminal and package manager into
+* {@link main}. Kept tiny; everything testable lives in the other modules.
+*/
+function realContext(cwd) {
+	return {
+		cwd: resolve(cwd ?? process.cwd()),
+		fs: nodeFs(),
+		registry: loadRegistrySource(),
+		version: "1.0.0",
+		out: (line) => process.stdout.write(`${line}\n`),
+		err: (line) => process.stderr.write(`${line}\n`),
+		async confirm(question) {
+			if (!process.stdin.isTTY) return false;
+			const prompt = createInterface({
+				input: process.stdin,
+				output: process.stdout
+			});
+			try {
+				const answer = await prompt.question(`${question} (y/N) `);
+				return /^y(es)?$/i.test(answer.trim());
+			} finally {
+				prompt.close();
+			}
+		},
+		install: ({ cwd: directory, manager, packages, output }) => new Promise((done, reject) => {
+			const args = manager === "npm" ? ["install", ...packages] : ["add", ...packages];
+			const child = spawn(manager, args, {
+				cwd: directory,
+				stdio: output === "stderr" ? [
+					"inherit",
+					2,
+					2
+				] : "inherit",
+				shell: process.platform === "win32"
+			});
+			child.on("error", reject);
+			child.on("close", (code) => code === 0 ? done() : reject(/* @__PURE__ */ new Error(`${manager} exited with code ${code}`)));
+		})
+	};
+}
+const argv = process.argv.slice(2);
+if (wantsJson(argv)) installCrashHandlers(argv);
+process.exitCode = await main(argv, realContext);
+//#endregion
+export {};