@dowel-ui/cli 0.1.1

package/dist/index.js

@@ -0,0 +1,1056 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import * as prompts from "@clack/prompts";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import pc from "picocolors";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+//#region src/branding.ts
+/**
+* Branding, mirrored from the repository root config.
+*
+* Duplicated deliberately: the published CLI cannot import from the monorepo
+* root, and `pnpm rebrand` rewrites both copies in the same pass.
+*/
+const branding = {
+	libraryName: "Dowel",
+	cliName: "dowel",
+	/**
+	* The npm package name, which is NOT the command name. npm rejected the
+	* unscoped `dowel` as too similar to `del` and `bower` — a rule that runs
+	* only at publish time, so a 404 from the registry proves a name is unused,
+	* never that it can be claimed. This is what follows `npx`; `cliName` is the
+	* binary the package installs.
+	*/
+	cliPackage: "@dowel-ui/cli",
+	registryUrl: "https://dowel-eight.vercel.app/r"
+};
+//#endregion
+//#region ../registry/dist/schema-ByqIpT47.js
+/**
+* Content hash used to detect local edits to an installed file.
+*
+* Line endings are normalised before hashing so a Windows checkout does not
+* read as "every file modified", which would make `update` useless there.
+*/
+function hashContent(content) {
+	const normalised = content.replace(/\r\n/g, "\n");
+	return `sha256:${createHash("sha256").update(normalised, "utf8").digest("hex")}`;
+}
+const registryFileTypeSchema = z.enum([
+	"registry:ui",
+	"registry:lib",
+	"registry:hook",
+	"registry:block",
+	"registry:style"
+]);
+const registryItemTypeSchema = z.enum([
+	"registry:ui",
+	"registry:lib",
+	"registry:hook",
+	"registry:theme",
+	"registry:block"
+]);
+const registryFileSchema = z.object({
+	/**
+	* Logical path within the registry, e.g. `ui/button.tsx`, `lib/utils.ts`.
+	*
+	* The leading segment selects which of the consumer's aliases the file is
+	* written under. The registry deliberately does not know the destination —
+	* that depends on a project layout it has never seen.
+	*/
+	path: z.string().min(1),
+	type: registryFileTypeSchema,
+	content: z.string(),
+	/**
+	* `sha256:<hex>` of `content` as published.
+	*
+	* Recorded at install time so `update` can tell an untouched file from one
+	* the user has edited. This cannot be added later: an install that did not
+	* record a hash leaves no way to know what it originally wrote.
+	*/
+	hash: z.string().regex(/^sha256:[0-9a-f]{64}$/)
+});
+const registryItemSchema = z.object({
+	$schema: z.string().optional(),
+	registryVersion: z.literal(1),
+	name: z.string().regex(/^[a-z][a-z0-9-]*$/),
+	type: registryItemTypeSchema,
+	title: z.string().min(1),
+	description: z.string().min(10),
+	category: z.string().min(1),
+	status: z.enum([
+		"stable",
+		"beta",
+		"experimental"
+	]),
+	/** npm packages to install alongside the files. */
+	dependencies: z.array(z.string()),
+	/** Other registry items to install first. */
+	registryDependencies: z.array(z.string()),
+	files: z.array(registryFileSchema).min(1),
+	a11y: z.string().optional()
+});
+const registryIndexEntrySchema = registryItemSchema.pick({
+	name: true,
+	type: true,
+	title: true,
+	description: true,
+	category: true,
+	status: true,
+	dependencies: true,
+	registryDependencies: true
+}).extend({ fileCount: z.number().int().positive() });
+const registryIndexSchema = z.object({
+	$schema: z.string().optional(),
+	registryVersion: z.literal(1),
+	/** Version of the package the registry was generated from. */
+	generatedFrom: z.string().min(1),
+	items: z.array(registryIndexEntrySchema)
+});
+//#endregion
+//#region src/lib/errors.ts
+/**
+* An error whose message is written for the person running the command.
+*
+* Anything thrown as a CliError is printed as a clean message with no stack
+* trace; everything else is treated as a bug and printed in full, because a
+* stack trace is exactly what is useful then and exactly what is noise when the
+* problem is "you have not run init yet".
+*/
+var CliError = class extends Error {
+	hint;
+	constructor(message, hint) {
+		super(message);
+		this.name = "CliError";
+		this.hint = hint;
+	}
+};
+//#endregion
+//#region src/lib/config.ts
+const CONFIG_FILE = "components.json";
+/**
+* How the CLI turns an import alias into a directory.
+*
+* Stored as a prefix/base pair taken from the project's tsconfig paths, rather
+* than as absolute directories, so the config stays readable and survives the
+* project being moved or checked out somewhere else.
+*/
+const resolveSchema = z.object({
+	/** Alias prefix, e.g. "@/" for `"@/*": ["./src/*"]`. */
+	prefix: z.string().min(1),
+	/** Directory the prefix maps to, relative to the project root, e.g. "src". */
+	base: z.string()
+});
+const aliasesSchema = z.object({
+	components: z.string().min(1),
+	ui: z.string().min(1),
+	lib: z.string().min(1),
+	hooks: z.string().min(1),
+	utils: z.string().min(1),
+	/**
+	* Where blocks are installed.
+	*
+	* Optional so a components.json written before blocks existed still parses;
+	* `blocksAlias()` derives a sensible default from `components` when it is
+	* absent. Silently failing to install a block would be worse than either.
+	*/
+	blocks: z.string().min(1).optional()
+});
+const installedItemSchema = z.object({
+	/** Registry version the item was installed from. */
+	from: z.string(),
+	/** Project-relative file path to the hash of the content we wrote. */
+	files: z.record(z.string(), z.string()),
+	/**
+	* Registry entries this one imports.
+	*
+	* Recorded so `remove` can refuse to delete something another installed
+	* component still needs, without having to reach the registry to find out.
+	* Optional, because installs made before this existed have no record of it.
+	*/
+	dependsOn: z.array(z.string()).optional()
+});
+const configSchema = z.object({
+	$schema: z.string().optional(),
+	version: z.literal(1),
+	typescript: z.boolean(),
+	registry: z.string().min(1),
+	tailwind: z.object({ 
+	/** Project-relative path to the stylesheet that imports Tailwind. */
+css: z.string().min(1) }),
+	aliases: aliasesSchema,
+	resolve: resolveSchema,
+	/**
+	* What has been installed, and the hash of what was written.
+	*
+	* This is what lets `update` tell an untouched file from one the user has
+	* edited. It has to be recorded at install time — an install that skipped it
+	* leaves no way to ever know what it originally wrote.
+	*/
+	installed: z.record(z.string(), installedItemSchema).default({})
+});
+/** The blocks alias, or a default derived from where components live. */
+function blocksAlias(config) {
+	return config.aliases.blocks ?? `${config.aliases.components}/blocks`;
+}
+function configPath(cwd) {
+	return join(cwd, CONFIG_FILE);
+}
+function configExists(cwd) {
+	return existsSync(configPath(cwd));
+}
+function readConfig(cwd) {
+	const path = configPath(cwd);
+	if (!existsSync(path)) throw new CliError(`No ${CONFIG_FILE} found in ${cwd}.`, "Run `init` first to set the project up.");
+	let raw;
+	try {
+		raw = JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		throw new CliError(`${CONFIG_FILE} is not valid JSON.`);
+	}
+	const parsed = configSchema.safeParse(raw);
+	if (!parsed.success) {
+		const issues = parsed.error.issues.map((issue) => `  ${issue.path.join(".") || "(root)"}: ${issue.message}`).join("\n");
+		throw new CliError(`${CONFIG_FILE} is not valid:\n${issues}`);
+	}
+	return parsed.data;
+}
+function writeConfig(cwd, config) {
+	writeFileSync(configPath(cwd), `${JSON.stringify(config, null, 2)}\n`);
+}
+//#endregion
+//#region src/lib/logger.ts
+/**
+* All CLI output goes through here.
+*
+* A single place to route messages means the format stays consistent, and
+* anything that needs to change later — quiet mode, JSON output, writing to
+* stderr — changes in one file rather than in every command.
+*/
+const logger = {
+	info(message) {
+		console.log(message);
+	},
+	success(message) {
+		console.log(`${pc.green("✓")} ${message}`);
+	},
+	warn(message) {
+		console.warn(`${pc.yellow("!")} ${message}`);
+	},
+	error(message) {
+		console.error(`${pc.red("✕")} ${message}`);
+	},
+	step(message) {
+		console.log(`${pc.dim("·")} ${message}`);
+	},
+	blank() {
+		console.log("");
+	}
+};
+//#endregion
+//#region src/lib/package-manager.ts
+const INSTALL_COMMAND = {
+	pnpm: ["add"],
+	yarn: ["add"],
+	bun: ["add"],
+	npm: ["install"]
+};
+/** Packages already present are skipped, so re-running `add` installs nothing. */
+function missingDependencies(installed, required) {
+	return required.filter((dependency) => !(dependency in installed));
+}
+function installDependencies(manager, cwd, dependencies) {
+	if (dependencies.length === 0) return;
+	const args = [...INSTALL_COMMAND[manager], ...dependencies];
+	const result = spawnSync(manager, args, {
+		cwd,
+		stdio: "inherit"
+	});
+	if (result.error) throw new CliError(`Could not run ${manager}: ${result.error.message}`, `Install these manually: ${dependencies.join(" ")}`);
+	if (result.status !== 0) throw new CliError(`${manager} ${args.join(" ")} failed.`, "Fix the install and run the command again — no files were rolled back.");
+}
+//#endregion
+//#region src/lib/paths.ts
+/**
+* Maps a registry file path to a destination in the project.
+*
+* The registry publishes logical paths — `ui/button.tsx`, `lib/utils.ts` —
+* because it has never seen the project it is being installed into. The leading
+* segment selects which alias the file belongs under, and the alias is resolved
+* through the project's own tsconfig prefix.
+*/
+function resolveDestination(config, registryPath) {
+	const [group, ...rest] = registryPath.split("/");
+	const relative = rest.join("/");
+	if (!group || relative === "") throw new CliError(`Registry path "${registryPath}" is not in a recognised group.`);
+	const alias = group === "ui" ? config.aliases.ui : group === "lib" ? config.aliases.lib : group === "hooks" ? config.aliases.hooks : group === "blocks" ? blocksAlias(config) : void 0;
+	if (!alias) throw new CliError(`Registry path "${registryPath}" uses unknown group "${group}".`, "This usually means the CLI is older than the registry it is reading.");
+	return join(aliasToDirectory(config, alias), relative);
+}
+/** Turns an import alias such as `@/components/ui` into `src/components/ui`. */
+function aliasToDirectory(config, alias) {
+	const { prefix, base } = config.resolve;
+	if (!alias.startsWith(prefix)) throw new CliError(`Alias "${alias}" does not start with the configured prefix "${prefix}".`, `Check the "aliases" and "resolve" entries in components.json.`);
+	const withoutPrefix = alias.slice(prefix.length);
+	return base ? join(base, withoutPrefix) : withoutPrefix;
+}
+/**
+* Rewrites the library's own import aliases to the ones the project uses.
+*
+* The published source is written against `@/components/*` and `@/lib/*`. A
+* project that puts its components somewhere else, or uses `~/` instead of
+* `@/`, gets files that import from where they actually live. Getting this
+* wrong is the single most common way a source-first install produces code that
+* does not compile.
+*/
+function rewriteImports(content, config) {
+	const { aliases } = config;
+	return content.replace(/(["'])@\/lib\/utils\1/g, (_match, quote) => `${quote}${aliases.utils}${quote}`).replace(/(["'])@\/lib\/([^"']+)\1/g, (_match, quote, rest) => `${quote}${aliases.lib}/${rest}${quote}`).replace(/(["'])@\/components\/([^"']+)\1/g, (_match, quote, rest) => `${quote}${aliases.ui}/${rest}${quote}`).replace(/(["'])@\/hooks\/([^"']+)\1/g, (_match, quote, rest) => `${quote}${aliases.hooks}/${rest}${quote}`).replace(/(["'])@\/blocks\/([^"']+)\1/g, (_match, quote, rest) => `${quote}${blocksAlias(config)}/${rest}${quote}`);
+}
+//#endregion
+//#region src/lib/project.ts
+const LOCKFILES = [
+	["pnpm-lock.yaml", "pnpm"],
+	["bun.lock", "bun"],
+	["bun.lockb", "bun"],
+	["yarn.lock", "yarn"],
+	["package-lock.json", "npm"]
+];
+function detectPackageManager(root) {
+	for (const [lockfile, manager] of LOCKFILES) if (existsSync(join(root, lockfile))) return manager;
+	return "npm";
+}
+function readPackageJson(root) {
+	const path = join(root, "package.json");
+	if (!existsSync(path)) throw new CliError(`No package.json found in ${root}.`, "Run this from the root of your project.");
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		throw new CliError("package.json is not valid JSON.");
+	}
+}
+function versionOf(packageJson, name) {
+	return packageJson.dependencies?.[name] ?? packageJson.devDependencies?.[name];
+}
+/** Leading integer of a range such as `^4.3.3`, `~4.0.0`, `4.x`. */
+function majorVersion(range) {
+	if (!range) return void 0;
+	const match = /(\d+)/.exec(range);
+	return match?.[1] === void 0 ? void 0 : Number(match[1]);
+}
+function detectFramework(packageJson) {
+	if (versionOf(packageJson, "next")) return "next";
+	if (versionOf(packageJson, "@remix-run/react") ?? versionOf(packageJson, "react-router")) return "remix";
+	if (versionOf(packageJson, "vite")) return "vite";
+	return "unknown";
+}
+/** Directories worth searching for the stylesheet, in the order projects use them. */
+const CSS_SEARCH_DIRS = [
+	"app",
+	"src/app",
+	"src/styles",
+	"styles",
+	"src",
+	"."
+];
+/**
+* Finds the stylesheet that pulls Tailwind in.
+*
+* Located by content rather than by name: `globals.css`, `index.css`,
+* `app.css` and `main.css` are all common, and guessing at the filename would
+* mean appending tokens to a stylesheet that is never loaded.
+*/
+function findCssEntry(root) {
+	for (const dir of CSS_SEARCH_DIRS) {
+		const absolute = join(root, dir);
+		if (!existsSync(absolute) || !statSync(absolute).isDirectory()) continue;
+		for (const entry of readdirSync(absolute)) {
+			if (!entry.endsWith(".css")) continue;
+			const path = join(absolute, entry);
+			const content = readFileSync(path, "utf8");
+			if (/@import\s+["']tailwindcss["']/.test(content) || /@tailwind\s+/.test(content)) return dir === "." ? entry : `${dir}/${entry}`;
+		}
+	}
+}
+/**
+* Reads the first wildcard alias out of tsconfig paths.
+*
+* `"@/*": ["./src/*"]` becomes `{ prefix: "@/", base: "src" }`. Only the
+* wildcard form is understood, which covers how essentially every React project
+* is set up; anything else falls through to a prompt rather than a wrong guess.
+*/
+function detectResolve(root) {
+	for (const file of ["tsconfig.json", "jsconfig.json"]) {
+		const path = join(root, file);
+		if (!existsSync(path)) continue;
+		let parsed;
+		try {
+			const raw = readFileSync(path, "utf8").replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/.*$/gm, "$1").replace(/,(\s*[}\]])/g, "$1");
+			parsed = JSON.parse(raw);
+		} catch {
+			continue;
+		}
+		const paths = parsed.compilerOptions?.paths;
+		if (!paths) continue;
+		for (const [alias, targets] of Object.entries(paths)) {
+			const target = targets[0];
+			if (!alias.endsWith("/*") || target === void 0 || !target.endsWith("/*")) continue;
+			return {
+				prefix: alias.slice(0, -1),
+				base: target.slice(0, -2).replace(/^\.\//, "").replace(/\/$/, "")
+			};
+		}
+	}
+}
+function inspectProject(root) {
+	const packageJson = readPackageJson(root);
+	return {
+		root,
+		packageManager: detectPackageManager(root),
+		packageJson,
+		isTypeScript: existsSync(join(root, "tsconfig.json")),
+		reactVersion: versionOf(packageJson, "react"),
+		tailwindVersion: versionOf(packageJson, "tailwindcss"),
+		framework: detectFramework(packageJson),
+		cssEntry: findCssEntry(root),
+		resolve: detectResolve(root)
+	};
+}
+/**
+* Refuses to proceed on a project this version cannot support correctly.
+*
+* Every check here fails loudly on purpose. Writing v4 token syntax into a v3
+* project, or TypeScript source into a JavaScript one, produces a project that
+* does not build — and the person debugging it has no reason to suspect the
+* install rather than their own code.
+*/
+function assertSupported(project) {
+	if (!project.reactVersion) throw new CliError("This does not look like a React project — react is not in package.json.", "Run this from the root of a React application.");
+	if (!project.isTypeScript) throw new CliError("JavaScript projects are not supported yet.", "The published components are TypeScript. Add a tsconfig.json, or wait for JS output in a future release.");
+	const tailwindMajor = majorVersion(project.tailwindVersion);
+	if (tailwindMajor === void 0) throw new CliError("Tailwind CSS is not installed.", "Install tailwindcss v4 and its plugin for your bundler, then run init again.");
+	if (tailwindMajor < 4) throw new CliError(`Tailwind CSS v${String(tailwindMajor)} is not supported — v4 or later is required.`, "The design tokens are defined with @theme, which v3 cannot parse. Upgrade to Tailwind v4 first.");
+}
+//#endregion
+//#region src/lib/registry-client.ts
+/**
+* Reads the registry over HTTP, or from a directory on disk.
+*
+* The local path form is not a testing shortcut bolted on afterwards — it is
+* how private forks and enterprise mirrors are meant to work, and it is what
+* lets the end-to-end tests run against a registry built in the same commit
+* rather than against whatever happens to be deployed.
+*/
+function isHttp(baseUrl) {
+	return baseUrl.startsWith("http://") || baseUrl.startsWith("https://");
+}
+function localPath(baseUrl, file) {
+	const root = baseUrl.startsWith("file:") ? fileURLToPath(baseUrl) : baseUrl;
+	return join(root, file);
+}
+async function readJson(baseUrl, file, what) {
+	if (!isHttp(baseUrl)) {
+		const path = localPath(baseUrl, file);
+		if (!existsSync(path)) throw new CliError(`${what} not found at ${path}.`);
+		try {
+			return JSON.parse(readFileSync(path, "utf8"));
+		} catch {
+			throw new CliError(`${what} at ${path} is not valid JSON.`);
+		}
+	}
+	const url = `${baseUrl.replace(/\/$/, "")}/${file}`;
+	let response;
+	try {
+		response = await fetch(url);
+	} catch (cause) {
+		throw new CliError(`Could not reach the registry at ${url}.`, cause instanceof Error ? cause.message : void 0);
+	}
+	if (response.status === 404) throw new CliError(`${what} not found in the registry.`);
+	if (!response.ok) throw new CliError(`Registry returned ${String(response.status)} for ${url}.`);
+	try {
+		return await response.json();
+	} catch {
+		throw new CliError(`${what} at ${url} is not valid JSON.`);
+	}
+}
+async function fetchIndex(baseUrl) {
+	const raw = await readJson(baseUrl, "index.json", "Registry index");
+	const parsed = registryIndexSchema.safeParse(raw);
+	if (!parsed.success) throw new CliError("The registry index does not match the format this CLI understands.", "Update the CLI, or point --registry at a compatible registry.");
+	return parsed.data;
+}
+async function fetchItem(baseUrl, name) {
+	const raw = await readJson(baseUrl, `${name}.json`, `Component "${name}"`);
+	const parsed = registryItemSchema.safeParse(raw);
+	if (!parsed.success) throw new CliError(`Registry entry "${name}" does not match the format this CLI understands.`, "Update the CLI, or point --registry at a compatible registry.");
+	return parsed.data;
+}
+/**
+* Resolves items and everything they depend on, dependencies first.
+*
+* Depth-first post-order, so a component is always ordered after the things it
+* imports. A breadth-first walk reversed looks equivalent and is not: if two
+* requested items depend on each other's subtrees it produces the wrong order.
+* The visiting set makes a dependency cycle terminate rather than recurse
+* forever.
+*/
+async function resolveItems(baseUrl, names) {
+	const cache = /* @__PURE__ */ new Map();
+	const ordered = [];
+	const placed = /* @__PURE__ */ new Set();
+	const visiting = /* @__PURE__ */ new Set();
+	async function load(name) {
+		const cached = cache.get(name);
+		if (cached) return cached;
+		const item = await fetchItem(baseUrl, name);
+		cache.set(name, item);
+		return item;
+	}
+	async function visit(name) {
+		if (placed.has(name) || visiting.has(name)) return;
+		visiting.add(name);
+		const item = await load(name);
+		for (const dependency of item.registryDependencies) await visit(dependency);
+		visiting.delete(name);
+		placed.add(name);
+		ordered.push(item);
+	}
+	for (const name of names) await visit(name);
+	return ordered;
+}
+//#endregion
+//#region src/commands/add.ts
+/**
+* Classifies an existing file against what we previously wrote there.
+*
+* Three outcomes, and the distinction matters. A file whose content still
+* matches what we installed is ours to replace silently, which is what makes
+* re-running `add` a no-op. A file that differs from what we installed has been
+* edited by the user — the entire point of a source-first library — and must
+* never be overwritten without them saying so.
+*/
+function classifyFile(absolutePath, incomingHash, recordedHash) {
+	if (!existsSync(absolutePath)) return "write";
+	const currentHash = hashContent(readFileSync(absolutePath, "utf8"));
+	if (currentHash === incomingHash) return "unchanged";
+	if (recordedHash !== void 0 && currentHash === recordedHash) return "write";
+	return "modified";
+}
+function planFiles(cwd, config, items) {
+	const planned = [];
+	for (const item of items) {
+		const recorded = config.installed[item.name]?.files ?? {};
+		for (const file of item.files) {
+			if (file.type === "registry:style") continue;
+			const destination = resolveDestination(config, file.path);
+			const content = rewriteImports(file.content, config);
+			const hash = hashContent(content);
+			planned.push({
+				destination,
+				content,
+				hash,
+				action: classifyFile(join(cwd, destination), hash, recorded[destination])
+			});
+		}
+	}
+	return planned;
+}
+async function add(names, options) {
+	if (names.length === 0) throw new CliError("Name at least one component to add.", "For example: `add button dialog`.");
+	const { cwd, yes, overwrite } = options;
+	const config = readConfig(cwd);
+	const registry = options.registry ?? config.registry;
+	const project = inspectProject(cwd);
+	const items = await resolveItems(registry, names);
+	const requested = new Set(names);
+	const pulledIn = items.filter((item) => !requested.has(item.name));
+	const planned = planFiles(cwd, config, items);
+	const toWrite = planned.filter((file) => file.action === "write");
+	const modified = planned.filter((file) => file.action === "modified");
+	const unchanged = planned.filter((file) => file.action === "unchanged");
+	if (modified.length > 0 && !overwrite) {
+		logger.warn("These files have local changes and were left alone:");
+		for (const file of modified) logger.info(`  ${file.destination}`);
+		logger.blank();
+		logger.info(pc.dim("Re-run with --overwrite to replace them."));
+		if (toWrite.length === 0) {
+			logger.blank();
+			logger.info("Nothing else to do.");
+			return;
+		}
+	}
+	const writable = overwrite ? [...toWrite, ...modified] : toWrite;
+	if (writable.length === 0) {
+		logger.success(unchanged.length > 0 ? "Already up to date." : "Nothing to write.");
+		return;
+	}
+	const dependencies = [...new Set(items.flatMap((item) => item.dependencies))];
+	const missing = missingDependencies({
+		...project.packageJson.dependencies,
+		...project.packageJson.devDependencies
+	}, dependencies);
+	if (!yes) {
+		logger.info(pc.dim("Will write:"));
+		for (const file of writable) logger.info(`  ${file.destination}`);
+		if (pulledIn.length > 0) logger.info(pc.dim(`Pulled in as dependencies: ${pulledIn.map((i) => i.name).join(", ")}`));
+		if (missing.length > 0) logger.info(pc.dim(`Will install: ${missing.join(", ")}`));
+		logger.blank();
+		const proceed = await prompts.confirm({
+			message: "Continue?",
+			initialValue: true
+		});
+		if (prompts.isCancel(proceed) || !proceed) throw new CliError("Cancelled — nothing was changed.");
+	}
+	for (const file of writable) {
+		const absolute = join(cwd, file.destination);
+		mkdirSync(dirname(absolute), { recursive: true });
+		writeFileSync(absolute, file.content);
+	}
+	const writtenPaths = new Set(writable.map((file) => file.destination));
+	for (const item of items) {
+		const files = { ...config.installed[item.name]?.files };
+		for (const file of planFiles(cwd, config, [item])) if (writtenPaths.has(file.destination) || file.action === "unchanged") files[file.destination] = file.hash;
+		if (Object.keys(files).length > 0) config.installed[item.name] = {
+			from: item.registryVersion.toString(),
+			files,
+			dependsOn: item.registryDependencies
+		};
+	}
+	writeConfig(cwd, config);
+	if (missing.length > 0 && !options.skipInstall) installDependencies(project.packageManager, cwd, missing);
+	logger.blank();
+	logger.success(`Added ${items.map((item) => item.name).join(", ")}`);
+	if (missing.length > 0) logger.success(options.skipInstall ? `Install these yourself: ${missing.join(" ")}` : `Installed ${missing.join(", ")}`);
+	logger.blank();
+	logger.info(pc.dim("Files:"));
+	for (const file of writable) logger.info(`  ${file.destination}`);
+	if (unchanged.length > 0) logger.info(pc.dim(`  (${String(unchanged.length)} already up to date)`));
+}
+/**
+* Appends the design tokens to the project stylesheet.
+*
+* Appended rather than written as a new file, and inserted after the Tailwind
+* import rather than at the top, because `@theme` has to be processed by
+* Tailwind. The existing stylesheet is never rewritten — whatever the project
+* already had stays exactly where it was.
+*
+* Two separate idempotence checks, because they catch different things. The
+* marker survives the user editing their tokens, which they are meant to do —
+* a content check alone would re-insert the whole block over their changes. The
+* content check covers a token block that carries no marker.
+*/
+function insertTokens(stylesheet, tokens) {
+	if (stylesheet.includes("/* Design tokens. Safe to edit — this is your copy. */")) return stylesheet;
+	if (stylesheet.includes(tokens.trim())) return stylesheet;
+	const importMatch = /^[^\n]*@import\s+["']tailwindcss["'][^\n]*$/m.exec(stylesheet);
+	if (!importMatch) return `${stylesheet.trimEnd()}\n\n${tokens.trim()}\n`;
+	const insertAt = importMatch.index + importMatch[0].length;
+	return `${stylesheet.slice(0, insertAt)}\n\n${tokens.trim()}\n${stylesheet.slice(insertAt)}`;
+}
+async function init(options) {
+	const { cwd, registry, yes } = options;
+	if (configExists(cwd) && !yes) {
+		const overwrite = await prompts.confirm({
+			message: "components.json already exists. Overwrite it?",
+			initialValue: false
+		});
+		if (prompts.isCancel(overwrite) || !overwrite) throw new CliError("Cancelled — nothing was changed.");
+	}
+	const project = inspectProject(cwd);
+	assertSupported(project);
+	logger.step(`Detected ${pc.bold(project.framework)} · ${pc.bold(project.packageManager)}`);
+	let resolve = project.resolve;
+	if (!resolve) {
+		if (yes) throw new CliError("Could not read a path alias from tsconfig.json.", "Add something like `\"paths\": { \"@/*\": [\"./src/*\"] }` and run init again.");
+		const prefix = await prompts.text({
+			message: "What import alias do you use?",
+			placeholder: "@/",
+			initialValue: "@/"
+		});
+		const base = await prompts.text({
+			message: "Which directory does it point at?",
+			placeholder: "src",
+			initialValue: "src"
+		});
+		if (prompts.isCancel(prefix) || prompts.isCancel(base)) throw new CliError("Cancelled — nothing was changed.");
+		resolve = {
+			prefix,
+			base
+		};
+	}
+	let cssEntry = project.cssEntry;
+	if (!cssEntry) {
+		if (yes) throw new CliError("Could not find a stylesheet that imports Tailwind.", "Create one containing `@import \"tailwindcss\";` and run init again.");
+		const answer = await prompts.text({
+			message: "Where is the stylesheet that imports Tailwind?",
+			placeholder: "src/index.css"
+		});
+		if (prompts.isCancel(answer) || !answer) throw new CliError("Cancelled — nothing was changed.");
+		cssEntry = answer;
+	}
+	const config = {
+		$schema: `${branding.registryUrl}/schema/components.json`,
+		version: 1,
+		typescript: true,
+		registry,
+		tailwind: { css: cssEntry },
+		aliases: {
+			components: `${resolve.prefix}components`,
+			ui: `${resolve.prefix}components/ui`,
+			lib: `${resolve.prefix}lib`,
+			hooks: `${resolve.prefix}hooks`,
+			utils: `${resolve.prefix}lib/utils`,
+			blocks: `${resolve.prefix}components/blocks`
+		},
+		resolve,
+		installed: {}
+	};
+	const utils = await fetchItem(registry, "utils");
+	const theme = await fetchItem(registry, "theme");
+	const written = [];
+	const installedFiles = {};
+	for (const file of utils.files) {
+		const destination = resolveDestination(config, file.path);
+		const absolute = join(cwd, destination);
+		if (existsSync(absolute)) {
+			logger.step(`${pc.dim("skipped")} ${destination} ${pc.dim("(already exists)")}`);
+			continue;
+		}
+		mkdirSync(dirname(absolute), { recursive: true });
+		const content = rewriteImports(file.content, config);
+		writeFileSync(absolute, content);
+		installedFiles[destination] = file.hash;
+		written.push(destination);
+	}
+	config.installed.utils = {
+		from: utils.registryVersion.toString(),
+		files: installedFiles
+	};
+	const stylesheetPath = join(cwd, cssEntry);
+	if (!existsSync(stylesheetPath)) throw new CliError(`Stylesheet not found at ${cssEntry}.`);
+	const tokens = theme.files[0]?.content ?? "";
+	const stylesheet = readFileSync(stylesheetPath, "utf8");
+	const updated = insertTokens(stylesheet, tokens);
+	if (updated === stylesheet) logger.step(`${pc.dim("skipped")} ${cssEntry} ${pc.dim("(tokens already present)")}`);
+	else {
+		writeFileSync(stylesheetPath, updated);
+		written.push(cssEntry);
+	}
+	config.installed.theme = {
+		from: theme.registryVersion.toString(),
+		files: { [cssEntry]: theme.files[0]?.hash ?? "" }
+	};
+	writeConfig(cwd, config);
+	written.unshift("components.json");
+	const required = [...utils.dependencies];
+	const missing = missingDependencies({
+		...project.packageJson.dependencies,
+		...project.packageJson.devDependencies
+	}, required);
+	if (missing.length > 0 && !options.skipInstall) {
+		logger.step(`Installing ${missing.join(", ")}`);
+		installDependencies(project.packageManager, cwd, missing);
+	}
+	logger.blank();
+	logger.success("Project initialised.");
+	logger.blank();
+	logger.info(pc.dim("Files:"));
+	for (const file of written) logger.info(`  ${file}`);
+	if (missing.length > 0) {
+		logger.blank();
+		logger.info(pc.dim(options.skipInstall ? "Install manually:" : "Dependencies:"));
+		logger.info(`  ${missing.join(" ")}`);
+	}
+	logger.blank();
+	logger.info(`Next: ${pc.bold(`npx ${branding.cliPackage} add button`)}`);
+}
+//#endregion
+//#region src/commands/list.ts
+async function list(options) {
+	const config = configExists(options.cwd) ? readConfig(options.cwd) : void 0;
+	const registry = options.registry ?? config?.registry ?? branding.registryUrl;
+	const index = await fetchIndex(registry);
+	const installed = new Set(Object.keys(config?.installed ?? {}));
+	const items = index.items.filter((item) => item.type === "registry:ui").filter((item) => !options.category || item.category === options.category);
+	if (options.json) {
+		logger.info(JSON.stringify(items.map((item) => ({
+			...item,
+			installed: installed.has(item.name)
+		})), null, 2));
+		return;
+	}
+	if (items.length === 0) {
+		logger.warn(options.category ? `No components in category "${options.category}".` : "The registry has no components.");
+		return;
+	}
+	const byCategory = /* @__PURE__ */ new Map();
+	for (const item of items) byCategory.set(item.category, [...byCategory.get(item.category) ?? [], item]);
+	const width = Math.max(...items.map((item) => item.name.length));
+	for (const [category, categoryItems] of [...byCategory].sort()) {
+		logger.blank();
+		logger.info(pc.bold(category));
+		for (const item of categoryItems) {
+			const mark = installed.has(item.name) ? pc.green("✓") : " ";
+			logger.info(`  ${mark} ${item.name.padEnd(width)}  ${pc.dim(item.description)}`);
+		}
+	}
+	logger.blank();
+	logger.info(pc.dim(`${String(items.length)} components · ${String(installed.size)} installed · ${registry}`));
+}
+//#endregion
+//#region src/commands/remove.ts
+/**
+* Classifies a file before deleting it.
+*
+* Deleting is the one irreversible thing this CLI does, so it distinguishes a
+* file still exactly as installed — safe to remove — from one that has been
+* edited, which is the user's work and not ours to throw away.
+*/
+function classifyRemoval(absolutePath, recordedHash) {
+	if (!existsSync(absolutePath)) return "missing";
+	if (recordedHash === void 0) return "modified";
+	return hashContent(readFileSync(absolutePath, "utf8")) === recordedHash ? "unchanged" : "modified";
+}
+/**
+* Components that other installed entries still import.
+*
+* Removing a component something else depends on would break the project, so
+* those are reported and skipped rather than deleted with a warning after the
+* fact.
+*/
+function findDependents(installed, registryDependencies, removing) {
+	const blockers = /* @__PURE__ */ new Map();
+	for (const name of removing) {
+		const dependents = Object.keys(installed).filter((candidate) => !removing.has(candidate) && (registryDependencies.get(candidate) ?? []).includes(name));
+		if (dependents.length > 0) blockers.set(name, dependents);
+	}
+	return blockers;
+}
+async function remove(names, options) {
+	if (names.length === 0) throw new CliError("Name at least one component to remove.");
+	const { cwd } = options;
+	const config = readConfig(cwd);
+	const unknown = names.filter((name) => !(name in config.installed));
+	if (unknown.length > 0) throw new CliError(`Not installed: ${unknown.join(", ")}.`, "Run `list` to see what is installed.");
+	const registryDependencies = /* @__PURE__ */ new Map();
+	for (const [name, entry] of Object.entries(config.installed)) registryDependencies.set(name, entry.dependsOn ?? []);
+	const removing = new Set(names);
+	const blockers = findDependents(config.installed, registryDependencies, removing);
+	if (blockers.size > 0) {
+		logger.error("These are still needed by something else:");
+		for (const [name, dependents] of blockers) logger.info(`  ${name} — required by ${dependents.join(", ")}`);
+		throw new CliError("Nothing was removed.", "Remove the dependents first, or keep these.");
+	}
+	const planned = [];
+	for (const name of names) for (const [path, hash] of Object.entries(config.installed[name]?.files ?? {})) planned.push({
+		component: name,
+		path,
+		state: classifyRemoval(join(cwd, path), hash)
+	});
+	const modified = planned.filter((file) => file.state === "modified");
+	const deletable = planned.filter((file) => file.state === "unchanged" || options.force && file.state === "modified");
+	if (modified.length > 0 && !options.force) {
+		logger.warn("These have local changes and will be kept:");
+		for (const file of modified) logger.info(`  ${file.path}`);
+		logger.blank();
+		logger.info(pc.dim("Re-run with --force to delete them as well."));
+	}
+	if (deletable.length === 0) {
+		logger.blank();
+		logger.info("Nothing to delete.");
+		return;
+	}
+	if (!options.yes) {
+		logger.info(pc.dim("Will delete:"));
+		for (const file of deletable) logger.info(`  ${file.path}`);
+		logger.blank();
+		const proceed = await prompts.confirm({
+			message: `Delete ${String(deletable.length)} file(s)?`,
+			initialValue: false
+		});
+		if (prompts.isCancel(proceed) || !proceed) throw new CliError("Cancelled — nothing was deleted.");
+	}
+	for (const file of deletable) rmSync(join(cwd, file.path), { force: true });
+	const deleted = new Set(deletable.map((file) => file.path));
+	for (const name of names) {
+		const entry = config.installed[name];
+		if (!entry) continue;
+		const remaining = Object.fromEntries(Object.entries(entry.files).filter(([path]) => !deleted.has(path)));
+		if (Object.keys(remaining).length === 0) delete config.installed[name];
+		else entry.files = remaining;
+	}
+	writeConfig(cwd, config);
+	logger.blank();
+	logger.success(`Removed ${String(deletable.length)} file(s).`);
+	if (modified.length > 0 && !options.force) logger.warn(`${String(modified.length)} locally modified file(s) were kept.`);
+	logger.blank();
+	logger.info(pc.dim("npm packages are left installed — other code may still use them."));
+}
+//#endregion
+//#region src/commands/update.ts
+/**
+* Compares three versions of a file: what the registry has now, what we
+* installed, and what is on disk.
+*
+* The three-way comparison is why the install hash had to be recorded from the
+* very first release. Without it there is no way to distinguish "the user
+* edited this" from "upstream changed this", and the only safe behaviour left
+* is to never update anything.
+*/
+function compareFile(absolutePath, incomingHash, recordedHash) {
+	if (!existsSync(absolutePath)) return "missing";
+	const currentHash = hashContent(readFileSync(absolutePath, "utf8"));
+	if (currentHash === incomingHash) return "current";
+	if (recordedHash === void 0) return "conflict";
+	if (currentHash === recordedHash) return "outdated";
+	return incomingHash === recordedHash ? "modified" : "conflict";
+}
+const STATE_LABEL = {
+	current: "up to date",
+	outdated: "update available",
+	modified: "locally modified",
+	conflict: "modified, and changed upstream",
+	missing: "missing"
+};
+async function update(names, options) {
+	const { cwd } = options;
+	const config = readConfig(cwd);
+	const registry = options.registry ?? config.registry;
+	const targets = names.length > 0 ? names : Object.keys(config.installed);
+	if (targets.length === 0) throw new CliError("Nothing is installed yet.", "Add a component first.");
+	const unknown = targets.filter((name) => !(name in config.installed));
+	if (unknown.length > 0) throw new CliError(`Not installed: ${unknown.join(", ")}.`, "Run `list` to see what is installed.");
+	const reports = [];
+	for (const name of targets) {
+		const item = await fetchItem(registry, name);
+		const recorded = config.installed[name]?.files ?? {};
+		for (const file of item.files) {
+			if (file.type === "registry:style") continue;
+			const destination = resolveDestination(config, file.path);
+			const content = rewriteImports(file.content, config);
+			const hash = hashContent(content);
+			reports.push({
+				component: name,
+				destination,
+				hash,
+				content,
+				state: compareFile(join(cwd, destination), hash, recorded[destination])
+			});
+		}
+	}
+	const actionable = reports.filter((report) => report.state === "outdated" || report.state === "missing");
+	const conflicts = reports.filter((report) => report.state === "conflict" || report.state === "modified");
+	logger.blank();
+	for (const report of reports) {
+		const colour = report.state === "current" ? pc.dim : report.state === "outdated" || report.state === "missing" ? pc.yellow : pc.red;
+		logger.info(`  ${colour(STATE_LABEL[report.state].padEnd(30))} ${report.destination}`);
+	}
+	logger.blank();
+	if (actionable.length === 0 && conflicts.length === 0) {
+		logger.success("Everything is up to date.");
+		return;
+	}
+	const writable = options.overwrite ? [...actionable, ...conflicts] : actionable;
+	if (writable.length === 0) {
+		logger.warn("Only locally modified files differ; none were touched.");
+		logger.info(pc.dim("Re-run with --overwrite to replace them and lose those edits."));
+		return;
+	}
+	if (!options.yes) {
+		const proceed = await prompts.confirm({
+			message: options.overwrite ? `Overwrite ${String(writable.length)} file(s), discarding any local changes?` : `Update ${String(writable.length)} file(s)?`,
+			initialValue: !options.overwrite
+		});
+		if (prompts.isCancel(proceed) || !proceed) throw new CliError("Cancelled — nothing was changed.");
+	}
+	for (const report of writable) {
+		writeFileSync(join(cwd, report.destination), report.content);
+		const entry = config.installed[report.component];
+		if (entry) entry.files[report.destination] = report.hash;
+	}
+	writeConfig(cwd, config);
+	logger.blank();
+	logger.success(`Updated ${String(writable.length)} file(s).`);
+	if (!options.overwrite && conflicts.length > 0) logger.warn(`${String(conflicts.length)} locally modified file(s) were left alone.`);
+}
+//#endregion
+//#region src/index.ts
+const program = new Command();
+program.name(branding.cliName).description(`Add ${branding.libraryName} components to your project as source you own.`).version("0.1.0").option("-c, --cwd <path>", "project root", process.cwd()).option("-r, --registry <url>", "registry base URL, or a directory on disk");
+function globals() {
+	return program.opts();
+}
+program.command("init").description("set the project up: config, utilities and design tokens").option("-y, --yes", "accept every default and never prompt", false).option("--skip-install", "write files but do not install dependencies", false).action(async (options) => {
+	const { cwd, registry } = globals();
+	await init({
+		cwd,
+		registry: registry ?? branding.registryUrl,
+		yes: options.yes,
+		skipInstall: options.skipInstall
+	});
+});
+program.command("add").description("add one or more components, with everything they depend on").argument("[components...]", "component names").option("-y, --yes", "do not ask for confirmation", false).option("-o, --overwrite", "replace files that have local changes", false).option("--skip-install", "write files but do not install dependencies", false).action(async (components, options) => {
+	const { cwd, registry } = globals();
+	await add(components, {
+		cwd,
+		registry,
+		yes: options.yes,
+		overwrite: options.overwrite,
+		skipInstall: options.skipInstall
+	});
+});
+program.command("list").alias("ls").description("list everything in the registry, marking what is installed").option("--category <name>", "show one category only").option("--json", "machine-readable output", false).action(async (options) => {
+	const { cwd, registry } = globals();
+	await list({
+		cwd,
+		registry,
+		category: options.category,
+		json: options.json
+	});
+});
+program.command("remove").alias("rm").description("delete installed components, keeping anything you have edited").argument("[components...]", "component names").option("-y, --yes", "do not ask for confirmation", false).option("-f, --force", "delete files that have local changes too", false).action(async (components, options) => {
+	const { cwd } = globals();
+	await remove(components, {
+		cwd,
+		yes: options.yes,
+		force: options.force
+	});
+});
+program.command("update").description("compare installed components against the registry").argument("[components...]", "component names; defaults to everything installed").option("-y, --yes", "do not ask for confirmation", false).option("-o, --overwrite", "replace files that have local changes", false).action(async (components, options) => {
+	const { cwd, registry } = globals();
+	await update(components, {
+		cwd,
+		registry,
+		yes: options.yes,
+		overwrite: options.overwrite
+	});
+});
+/**
+* A CliError is a message for the person running the command; anything else is
+* a bug, and its stack trace is the useful part.
+*/
+async function main() {
+	try {
+		await program.parseAsync(process.argv);
+	} catch (error) {
+		logger.blank();
+		if (error instanceof CliError) {
+			logger.error(error.message);
+			if (error.hint) logger.info(pc.dim(`  ${error.hint}`));
+		} else {
+			logger.error("Something went wrong.");
+			logger.info(String(error instanceof Error ? error.stack ?? error.message : error));
+		}
+		logger.blank();
+		process.exitCode = 1;
+	}
+}
+main();
+//#endregion
+export { add, init, list, remove, update };
+
+//# sourceMappingURL=index.js.map