@shadow-js/ui 1.0.1 → 1.0.3

package/dist/cli.mjs

@@ -1,9 +1,9 @@
 #!/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 { existsSync, mkdirSync, readFileSync, readlinkSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { parseArgs } from "node:util";
+import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 // src/cli/fs.ts
 /**
@@ -11,6 +11,59 @@ import { fileURLToPath } from "node:url";
 * directory or an in-memory tree, and so every path goes through one place.
 * @packageDocumentation
 */
+/** Symbolic links followed while resolving one path; the same bound the operating system uses. */
+const MAX_LINK_HOPS = 40;
+/** Folders `ancestors` climbs at most: far beyond any real project, so a path loop cannot spin. */
+const MAX_LEVELS = 64;
+/**
+* `start` and its parent folders up to the filesystem root, nearest first (at most 64).
+*
+* @param start An absolute folder.
+* @returns The folders, `start` first.
+* @example
+* ancestors("/a/b"); // ["/a/b", "/a", "/"]
+* @since 1.0.0
+*
+* @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
+*/
+function ancestors(start) {
+	const folders = [start];
+	for (let folder = dirname(start); folders.length < MAX_LEVELS; folder = dirname(folder)) {
+		if (folder === folders[folders.length - 1]) break;
+		folders.push(folder);
+	}
+	return folders;
+}
+/** Whether a failed file call means "nothing is there" (or a file stands where a directory should). */
+function isMissing(error) {
+	const code = error.code;
+	return code === "ENOENT" || code === "ENOTDIR";
+}
+/**
+* The real path of `path`, where the part that does not exist yet is kept as written. A symbolic
+* link whose target is missing is followed to that target: a write through it would create the
+* target, so the guard has to see where it is.
+*/
+function resolveReal(path, hops) {
+	try {
+		return realpathSync(path);
+	} catch (error) {
+		if (!isMissing(error)) throw error;
+	}
+	let link;
+	try {
+		link = readlinkSync(path);
+	} catch (error) {
+		if (!isMissing(error) && error.code !== "EINVAL") throw error;
+	}
+	if (link !== void 0) {
+		if (hops >= MAX_LINK_HOPS) throw Object.assign(/* @__PURE__ */ new Error(`Too many symbolic links: ${path}`), { code: "ELOOP" });
+		return resolveReal(resolve(resolveReal(dirname(path), hops + 1), link), hops + 1);
+	}
+	const parent = dirname(path);
+	if (parent === path) return path;
+	return join(resolveReal(parent, hops), basename(path));
+}
 /**
 * The real filesystem.
 *
@@ -26,7 +79,7 @@ function nodeFs() {
 		exists: (path) => existsSync(path),
 		read(path) {
 			try {
-				return readFileSync(path, "utf8");
+				return readFileSync(path, "utf8").replace(/^\uFEFF/, "");
 			} catch (error) {
 				if (error.code === "ENOENT") return void 0;
 				throw error;
@@ -40,15 +93,7 @@ function nodeFs() {
 			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);
+			return resolveReal(path, 0);
 		}
 	};
 }
@@ -210,25 +255,37 @@ function installCrashHandlers(argv) {
 	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) => ({
+/** The whole of `a` deleted and the whole of `b` inserted: always correct, never minimal. */
+function replacement(a, b) {
+	return [...a.map((line) => ({
 		kind: "delete",
 		line
 	})), ...b.map((line) => ({
 		kind: "insert",
 		line
 	}))];
+}
+/** The edit script turning `a` into `b`; one big replacement when the texts are too large or too different. */
+function edits(a, b) {
+	const n = a.length;
+	const m = b.length;
+	const max = n + m;
+	if (max > 2e4) return replacement(a, b);
 	const offset = max;
-	let frontier = new Int32Array(2 * max + 2);
+	const frontier = new Int32Array(2 * max + 2);
+	/** The frontier before each round, only the diagonals the next round can read: `[offset - d - 1, offset + d + 1]`. */
 	const trace = [];
+	let kept = 0;
 	let reached = -1;
 	for (let d = 0; d <= max && reached === -1; d += 1) {
-		trace.push(frontier.slice());
-		const next = frontier.slice();
+		const from = Math.max(0, offset - d - 1);
+		const cells = frontier.slice(from, Math.min(frontier.length, offset + d + 2));
+		kept += cells.length;
+		if (kept > 16e6) return replacement(a, b);
+		trace.push({
+			from,
+			cells
+		});
 		for (let k = -d; k <= d; k += 2) {
 			let x;
 			const below = frontier[offset + k - 1] ?? 0;
@@ -240,24 +297,24 @@ function edits(a, b) {
 				x += 1;
 				y += 1;
 			}
-			next[offset + k] = x;
+			frontier[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 previous = trace[d];
+		const at = (index) => previous === void 0 ? 0 : previous.cells[index - previous.from] ?? 0;
 		const k = x - y;
-		const below = previous[offset + k - 1] ?? 0;
-		const above = previous[offset + k + 1] ?? 0;
+		const below = at(offset + k - 1);
+		const above = at(offset + k + 1);
 		const previousK = k === -d || k !== d && below < above ? k + 1 : k - 1;
-		const previousX = previous[offset + previousK] ?? 0;
+		const previousX = at(offset + previousK);
 		const previousY = previousX - previousK;
 		while (x > previousX && y > previousY) {
 			x -= 1;
@@ -371,6 +428,186 @@ function unifiedDiff(before, after, labels, context = 3) {
 		...hunks
 	].join("\n");
 }
+// 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")
+		}
+	};
+}
 // src/cli/paths.ts
 /**
 * Path handling: reading `tsconfig` path aliases, mapping an import alias to a directory, and the
@@ -459,9 +696,59 @@ function parseJsonc(text) {
 function asRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
 }
+/** The `extends` links followed from one tsconfig: far beyond any real chain. */
+const MAX_EXTENDS = 16;
+/** The file an `extends` entry names, or `undefined`: a path, or a package looked up in `node_modules`. */
+function extendsFile(fs, folder, entry) {
+	const candidates = (base) => base.endsWith(".json") ? [base] : [`${base}.json`, join(base, "tsconfig.json")];
+	if (entry.startsWith(".") || isAbsolute(entry)) return candidates(resolve(folder, entry)).find((file) => fs.exists(file));
+	for (const parent of ancestors(folder)) {
+		const found = candidates(join(parent, "node_modules", entry)).find((file) => fs.exists(file));
+		if (found !== void 0) return found;
+	}
+}
+/**
+* The `paths` and `baseUrl` of one tsconfig with its `extends` merged in, as TypeScript does: later
+* bases override earlier ones, the config itself overrides its bases, and `paths` is replaced as a
+* whole. `seen` holds the chain so far, so a cycle or a very long chain ends.
+*/
+function readOptions(fs, file, label, seen) {
+	const text = fs.read(file);
+	if (text === void 0) return void 0;
+	let parsed;
+	try {
+		parsed = parseJsonc(text);
+	} catch (error) {
+		if (error instanceof SyntaxError) throw new SchemaError(`${label} is not valid JSON: ${error.message}`);
+		throw error;
+	}
+	const config = asRecord(parsed);
+	const options = asRecord(config?.["compilerOptions"]);
+	const folder = dirname(file);
+	let merged = {};
+	const bases = [config?.["extends"]].flat();
+	for (const entry of seen.length < MAX_EXTENDS ? bases : []) {
+		const base = typeof entry === "string" ? extendsFile(fs, folder, entry) : void 0;
+		if (base !== void 0 && !seen.includes(base)) merged = {
+			...merged,
+			...readOptions(fs, base, base, [...seen, base])
+		};
+	}
+	const paths = asRecord(options?.["paths"]);
+	const baseUrl = options?.["baseUrl"];
+	return {
+		...merged,
+		...paths !== void 0 && {
+			paths,
+			pathsDir: folder
+		},
+		...typeof baseUrl === "string" && { baseUrl: resolve(folder, baseUrl) }
+	};
+}
 /**
 * 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.
+* `tsconfig.app.json`), following their `extends` (relative files and packages in `node_modules`).
+* Targets are resolved against `baseUrl` or the directory of the config that declares `paths`.
 *
 * @param fs The project filesystem.
 * @param root The project root.
@@ -475,12 +762,10 @@ function asRecord(value) {
 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"]);
+		const file = join(root, name);
+		const { paths, pathsDir, baseUrl } = readOptions(fs, file, name, [file]) ?? {};
 		if (paths === void 0) continue;
-		const base = typeof options?.["baseUrl"] === "string" ? resolve(root, options["baseUrl"]) : root;
+		const base = baseUrl ?? pathsDir ?? root;
 		for (const [pattern, targets] of Object.entries(paths)) {
 			if (!Array.isArray(targets)) continue;
 			mappings.push({
@@ -507,19 +792,26 @@ function readPathMappings(fs, root) {
 * @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
 */
 function aliasToDirectory(alias, mappings) {
+	let best;
 	for (const { pattern, targets } of mappings) {
+		const target = targets[0];
+		if (target === void 0) continue;
 		const star = pattern.indexOf("*");
 		if (star === -1) {
-			if (pattern === alias && targets[0] !== void 0) return targets[0];
+			if (pattern === alias) return target;
 			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);
+		if (alias.startsWith(prefix) && alias.endsWith(suffix) && alias.length >= prefix.length + suffix.length && (best === void 0 || prefix.length > best.length)) {
+			const rest = alias.slice(prefix.length, alias.length - suffix.length);
+			best = {
+				length: prefix.length,
+				directory: target.replace("*", rest)
+			};
+		}
 	}
+	if (best !== void 0) return best.directory;
 	throw new PathError(`The alias "${alias}" is not covered by "paths" in tsconfig.json. Add, for example:\n  "compilerOptions": { "paths": { "@/*": ["./src/*"] } }`);
 }
 /**
@@ -569,12 +861,31 @@ function resolveInsideReal(fs, root, target) {
 // 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.
+* are used when their lockfile (or the `packageManager` field) says so, in the project or a parent folder.
 * @packageDocumentation
 */
+/** The package manager one folder says it uses (field first, then lockfiles), or `undefined`. */
+function managerOf(fs, folder) {
+	const manifest = fs.read(join(folder, "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(folder, "pnpm-lock.yaml"))) return "pnpm";
+	if (fs.exists(join(folder, "yarn.lock"))) return "yarn";
+	if (fs.exists(join(folder, "bun.lock")) || fs.exists(join(folder, "bun.lockb"))) return "bun";
+	if (fs.exists(join(folder, "package-lock.json"))) return "npm";
+}
 /**
-* Detects the project's package manager: the `packageManager` field of `package.json` first, then
-* lockfiles, otherwise npm.
+* Detects the project's package manager. In the project folder and then each parent folder (a
+* package inside a workspace is managed from the workspace root) it reads the `packageManager`
+* field of `package.json`, then the lockfiles; the nearest folder that says anything wins, and npm
+* is the default.
 *
 * @param fs The project filesystem.
 * @param root The project root.
@@ -586,19 +897,10 @@ function resolveInsideReal(fs, root, target) {
 * @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;
+	for (const folder of ancestors(root)) {
+		const manager = managerOf(fs, folder);
+		if (manager !== void 0) return manager;
 	}
-	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";
 }
 /**
@@ -633,186 +935,6 @@ function installCommand(manager, packages) {
 		};
 	}
 }
-// 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")
-		}
-	};
-}
 // src/cli/project.ts
 /**
 * The project the CLI works in: `components.json`, `package.json`, the stylesheet that imports
@@ -1243,6 +1365,7 @@ function dependentsOf(index, name, candidates) {
 *
 * @param specifier An import specifier such as `@/components/ui/button`.
 * @param aliases The aliases from `components.json`.
+* @param options Rewrites besides the aliases (relative imports between ui components).
 * @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"
@@ -1250,9 +1373,12 @@ function dependentsOf(index, name, candidates) {
 *
 * @internal Not exported from `@shadow-js/ui`: part of the shadow-ui command, whose public surface is the CLI.
 */
-function rewriteSpecifier(specifier, aliases) {
+function rewriteSpecifier(specifier, aliases, options = {}) {
 	if (specifier === "@/lib/utils") return aliases.utils;
-	if (specifier.startsWith("@/components/ui/")) return `${aliases.ui}/${specifier.slice(16)}`;
+	if (specifier.startsWith("@/components/ui/")) {
+		const rest = specifier.slice(16);
+		return options.relativeUi === true ? `./${rest}` : `${aliases.ui}/${rest}`;
+	}
 	if (specifier.startsWith("@/hooks/")) return `${aliases.hooks}/${specifier.slice(8)}`;
 	if (specifier.startsWith("@/lib/")) return `${aliases.lib}/${specifier.slice(6)}`;
 	return specifier;
@@ -1265,6 +1391,7 @@ const SPECIFIER = /(\bfrom\s*|\bimport\s*\(\s*|\bimport\s+)(["'])(@\/[^"'\n]+)\2
 *
 * @param source A registry file's text.
 * @param aliases The aliases from `components.json`.
+* @param options Rewrites besides the aliases (relative imports between ui components).
 * @returns The text with rewritten specifiers.
 * @example
 * rewriteImports('import { cn } from "@/lib/utils";', aliases);
@@ -1272,8 +1399,8 @@ const SPECIFIER = /(\bfrom\s*|\bimport\s*\(\s*|\bimport\s+)(["'])(@\/[^"'\n]+)\2
 *
 * @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}`);
+function rewriteImports(source, aliases, options = {}) {
+	return source.replace(SPECIFIER, (_match, lead, quote, specifier) => `${lead}${quote}${rewriteSpecifier(specifier, aliases, options)}${quote}`);
 }
 // src/cli/commands.ts
 /**
@@ -1334,12 +1461,26 @@ function targetFor(item, file, config, mappings, ctx, pathOverride) {
 	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));
 }
+/**
+* Whether ui components written with `--path` need relative imports between them: they do when that directory is not the one the
+* `ui` alias names (the alias would point at a directory that does not hold them), or when the alias names no directory at all.
+*/
+function importsBetweenUiAreRelative(ctx, config, mappings, pathOverride) {
+	if (pathOverride === void 0) return false;
+	try {
+		return resolve(aliasToDirectory(config.aliases.ui, mappings)) !== resolve(ctx.cwd, pathOverride);
+	} catch (error) {
+		if (error instanceof PathError) return true;
+		throw error;
+	}
+}
 /** 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 = [];
+	const relativeUi = importsBetweenUiAreRelative(ctx, config, mappings, pathOverride);
 	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 content = file.path.endsWith(".css") ? raw : rewriteImports(raw, config.aliases, { relativeUi: relativeUi && item.type === "ui" });
 		const target = targetFor(item, file, config, mappings, ctx, pathOverride);
 		const current = ctx.fs.read(target);
 		plans.push({
@@ -1536,6 +1677,11 @@ async function runInit(ctx, flags) {
 			recordFile(ctx, label, current === void 0 ? "create" : "update");
 			return "created";
 		};
+		const configPath = resolveInsideReal(ctx.fs, ctx.cwd, "components.json");
+		const themeFile = themePathFor(config.tailwind.css);
+		resolveInsideReal(ctx.fs, ctx.cwd, themeFile);
+		const cssPath = resolveInsideReal(ctx.fs, ctx.cwd, config.tailwind.css);
+		const utils = planInitUtils(ctx, config);
 		ctx.report?.set("dryRun", flags.dryRun);
 		ctx.report?.set("config", {
 			baseColor,
@@ -1544,14 +1690,12 @@ async function runInit(ctx, flags) {
 		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));
@@ -1564,7 +1708,6 @@ async function runInit(ctx, flags) {
 			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 {
@@ -1584,7 +1727,7 @@ async function runInit(ctx, flags) {
 				recordFile(ctx, config.tailwind.css, "skipped");
 			}
 		}
-		const added = await runAddForInit(ctx, config, flags);
+		const added = await runAddForInit(ctx, utils, flags);
 		if (added !== OK) return added;
 		const tooling = [];
 		if (!info.hasTailwind) tooling.push("tailwindcss");
@@ -1596,14 +1739,21 @@ async function runInit(ctx, flags) {
 		return failed(ctx, error);
 	}
 }
-/** `init` copies `utils` through the same pipeline as `add`. */
-async function runAddForInit(ctx, config, flags) {
+/** Plans `utils` through the same pipeline as `add`. */
+function planInitUtils(ctx, config) {
 	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)) {
+	return {
+		plan,
+		entries: planFiles(ctx, config, plan.items, void 0, mappings)
+	};
+}
+/** `init` copies `utils` through the same pipeline as `add`. */
+async function runAddForInit(ctx, { plan, entries }, flags) {
+	for (const entry of entries) {
 		const where = display(ctx.cwd, entry.target);
 		if (entry.status === "unchanged") {
 			ctx.out(`  unchanged  ${where}`);
@@ -1759,7 +1909,8 @@ function runDiff(ctx, names) {
 }
 /**
 * 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.
+* project imports one of them, and keeps (exit 1) a file that differs from the registry, because
+* the user edited it; `force` overrides both. It never removes npm packages.
 *
 * @param ctx The CLI context.
 * @param names Component names.
@@ -1786,6 +1937,7 @@ function runRemove(ctx, names, flags) {
 		ctx.report?.set("dryRun", flags.dryRun);
 		ctx.report?.set("removed", []);
 		let code = OK;
+		let kept = 0;
 		for (const name of removing) {
 			const blockers = dependentsOf(ctx.registry.index, name, installedNames).filter((other) => !removing.includes(other));
 			if (blockers.length > 0 && !flags.force) {
@@ -1799,18 +1951,30 @@ function runRemove(ctx, names, flags) {
 			}
 			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);
+			for (const entry of planFiles(ctx, config, [item], void 0, mappings)) {
+				if (entry.status === "create") continue;
+				const where = display(ctx.cwd, entry.target);
+				if (entry.status === "differs" && !flags.force) {
+					kept += 1;
+					ctx.out(`  kept       ${where} (differs from the registry; pass --force to remove it)`);
+					ctx.report?.push("kept", {
+						name,
+						path: where
+					});
+					continue;
+				}
 				ctx.out(`  ${flags.dryRun ? "would remove" : "remove"}  ${where}`);
-				if (!flags.dryRun) ctx.fs.remove(target);
+				if (!flags.dryRun) ctx.fs.remove(entry.target);
 				ctx.report?.push("removed", {
 					name,
 					path: where
 				});
 			}
 		}
+		if (kept > 0) {
+			problem(ctx, "SHADOW_UI_FILES_DIFFER", `${kept} file(s) differ from the registry and were kept; pass --force to remove them.`);
+			code = FAILED;
+		}
 		return code;
 	} catch (error) {
 		return failed(ctx, error);
@@ -2160,6 +2324,42 @@ async function dispatch(ctx, command, rest, values, common) {
 		}
 	}
 }
+// src/cli/prompt.ts
+/**
+* The yes/no question of the executable, kept apart from `bin.ts` (which runs on import) so a test
+* can drive it with in-memory streams.
+* @packageDocumentation
+*/
+/**
+* Asks a yes/no question and resolves `true` only for `y` or `yes` (any case). An empty answer is
+* no, and so is the end of input (Ctrl-D, a closed pipe): readline never settles `question()` when
+* its input ends, which left Node to exit with code 13 ("unsettled top-level await").
+*
+* @param question The question, without the `(y/N)` suffix.
+* @param input The stream the answer is read from.
+* @param output The stream the question is written to.
+* @returns Whether the user said yes.
+* @example
+* const yes = await askYesNo("Install packages?", process.stdin, process.stdout);
+* @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 askYesNo(question, input, output) {
+	const prompt = createInterface({
+		input,
+		output
+	});
+	try {
+		const answer = await new Promise((settle, fail) => {
+			prompt.once("close", () => settle(""));
+			prompt.question(`${question} (y/N) `).then(settle, fail);
+		});
+		return /^y(es)?$/i.test(answer.trim());
+	} finally {
+		prompt.close();
+	}
+}
 // src/cli/registry-source.ts
 /**
 * Where the CLI reads the registry from. The registry ships inside the package, so nothing is
@@ -2243,21 +2443,12 @@ function realContext(cwd) {
 		cwd: resolve(cwd ?? process.cwd()),
 		fs: nodeFs(),
 		registry: loadRegistrySource(),
-		version: "1.0.1",
+		version: "1.0.3",
 		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();
-			}
+			return askYesNo(question, process.stdin, process.stdout);
 		},
 		install: ({ cwd: directory, manager, packages, output }) => new Promise((done, reject) => {
 			const args = manager === "npm" ? ["install", ...packages] : ["add", ...packages];