@gntik-ai/cli 0.0.0-stage → 0.5.0

package/dist/index.js

@@ -0,0 +1,1712 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+//#region package.json
+var version = "0.5.0";
+//#endregion
+//#region src/errors.ts
+/** Machine-readable error codes and the exit code each one maps to. */
+const EXIT_CODES = {
+	OK: 0,
+	ERROR: 1,
+	REGISTRY: 1,
+	INSTALL: 1,
+	CODEMODS: 1,
+	USAGE: 2,
+	NOT_FOUND: 3,
+	CONFLICT: 4
+};
+var CliError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+	get exitCode() {
+		return EXIT_CODES[this.code];
+	}
+};
+//#endregion
+//#region src/args.ts
+const COMMANDS = [
+	"init",
+	"add",
+	"eject",
+	"list",
+	"search",
+	"docs",
+	"upgrade"
+];
+const OPTIONS = {
+	json: { type: "boolean" },
+	cwd: { type: "string" },
+	registry: {
+		type: "string",
+		short: "r"
+	},
+	"dry-run": { type: "boolean" },
+	yes: {
+		type: "boolean",
+		short: "y"
+	},
+	overwrite: { type: "boolean" },
+	"no-install": { type: "boolean" },
+	"no-deps": { type: "boolean" },
+	kind: {
+		type: "string",
+		short: "k"
+	},
+	group: {
+		type: "string",
+		short: "g"
+	},
+	brand: { type: "string" },
+	limit: { type: "string" },
+	from: { type: "string" },
+	to: { type: "string" },
+	codemod: {
+		type: "string",
+		multiple: true
+	},
+	"skip-codemod": {
+		type: "string",
+		multiple: true
+	},
+	list: { type: "boolean" },
+	apply: { type: "boolean" },
+	help: {
+		type: "boolean",
+		short: "h"
+	},
+	version: {
+		type: "boolean",
+		short: "v"
+	}
+};
+/** Flags each command accepts on top of the global ones (--json --cwd --registry --help --yes). */
+const COMMAND_FLAGS = {
+	init: [
+		"dry-run",
+		"overwrite",
+		"no-install",
+		"brand"
+	],
+	add: [
+		"dry-run",
+		"overwrite",
+		"no-install"
+	],
+	eject: [
+		"dry-run",
+		"overwrite",
+		"no-install",
+		"no-deps"
+	],
+	list: ["kind", "group"],
+	search: ["kind", "limit"],
+	docs: [],
+	upgrade: [
+		"dry-run",
+		"from",
+		"to",
+		"codemod",
+		"skip-codemod",
+		"list",
+		"apply"
+	]
+};
+const GLOBAL_FLAGS = [
+	"json",
+	"cwd",
+	"registry",
+	"help",
+	"version",
+	"yes"
+];
+function parseCliArgs(argv) {
+	let parsed;
+	try {
+		parsed = parseArgs({
+			args: argv,
+			options: OPTIONS,
+			allowPositionals: true,
+			strict: true
+		});
+	} catch (e) {
+		throw new CliError("USAGE", e.message);
+	}
+	const { values, positionals } = parsed;
+	const [first, ...rest] = positionals;
+	let command;
+	if (first !== void 0) {
+		if (!COMMANDS.includes(first)) throw new CliError("USAGE", `Unknown command "${first}". Run gntik-ui --help.`);
+		command = first;
+		const allowed = /* @__PURE__ */ new Set([...GLOBAL_FLAGS, ...COMMAND_FLAGS[command]]);
+		for (const key of Object.keys(values)) if (!allowed.has(key)) throw new CliError("USAGE", `Option --${key} is not valid for "${command}".`);
+	}
+	let limit;
+	if (values.limit !== void 0) {
+		limit = Number(values.limit);
+		if (!Number.isInteger(limit) || limit < 1) throw new CliError("USAGE", "--limit must be a positive integer");
+	}
+	if (values.apply && values["dry-run"]) throw new CliError("USAGE", "--apply and --dry-run cannot be combined");
+	return {
+		command,
+		positionals: command ? rest : positionals,
+		flags: {
+			json: values.json ?? false,
+			cwd: values.cwd,
+			registry: values.registry,
+			dryRun: values["dry-run"] ?? false,
+			yes: values.yes ?? false,
+			overwrite: values.overwrite ?? false,
+			install: !values["no-install"],
+			deps: !values["no-deps"],
+			kind: values.kind,
+			group: values.group,
+			brand: values.brand,
+			limit,
+			from: values.from,
+			to: values.to,
+			codemods: (values.codemod ?? []).flatMap(splitList),
+			skipCodemods: (values["skip-codemod"] ?? []).flatMap(splitList),
+			list: values.list ?? false,
+			apply: values.apply ?? false,
+			help: values.help ?? false,
+			version: values.version ?? false
+		}
+	};
+}
+/** `--codemod a,b --codemod c` → ['a', 'b', 'c']. */
+function splitList(value) {
+	return value.split(",").map((v) => v.trim()).filter(Boolean);
+}
+//#endregion
+//#region src/project.ts
+const CONFIG_FILE = "gntik-ui.json";
+const VITE_CONFIGS = [
+	"ts",
+	"mts",
+	"js",
+	"mjs",
+	"cjs",
+	"cts"
+].map((e) => `vite.config.${e}`);
+const NEXT_CONFIGS = [
+	"ts",
+	"mjs",
+	"js",
+	"cjs"
+].map((e) => `next.config.${e}`);
+const CSS_CANDIDATES = [
+	"src/index.css",
+	"src/styles.css",
+	"src/globals.css",
+	"src/app.css",
+	"src/main.css",
+	"src/styles/globals.css",
+	"src/app/globals.css",
+	"app/globals.css",
+	"styles/globals.css",
+	"styles.css"
+];
+const LOCKFILES = [
+	["pnpm-lock.yaml", "pnpm"],
+	["bun.lock", "bun"],
+	["bun.lockb", "bun"],
+	["yarn.lock", "yarn"],
+	["package-lock.json", "npm"]
+];
+function readJson(file) {
+	if (!existsSync(file)) return null;
+	try {
+		return JSON.parse(readFileSync(file, "utf8"));
+	} catch {
+		throw new CliError("ERROR", `${file} is not valid JSON`);
+	}
+}
+function detectPackageManager(cwd, pkg) {
+	let dir = cwd;
+	for (;;) {
+		for (const [file, pm] of LOCKFILES) if (existsSync(path.join(dir, file))) return pm;
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	const declared = pkg?.packageManager?.split("@")[0];
+	if (declared === "pnpm" || declared === "yarn" || declared === "bun" || declared === "npm") return declared;
+	return "npm";
+}
+function detectProject(cwd) {
+	const has = (f) => existsSync(path.join(cwd, f));
+	const packageJson = readJson(path.join(cwd, "package.json"));
+	const deps = {
+		...packageJson?.dependencies,
+		...packageJson?.devDependencies
+	};
+	let framework = "generic";
+	if (NEXT_CONFIGS.some(has) || "next" in deps) framework = "next";
+	else if (VITE_CONFIGS.some(has) || "vite" in deps) framework = "vite";
+	const src = has("src");
+	const css = CSS_CANDIDATES.find(has) ?? null;
+	let cssDefault = "src/index.css";
+	let entry = [
+		"src/main.tsx",
+		"src/main.jsx",
+		"src/main.ts",
+		"src/main.js",
+		"src/index.tsx"
+	].find(has) ?? "src/main.tsx";
+	if (framework === "next") {
+		const appDir = has("src/app") || src && !has("app") ? "src/app" : "app";
+		cssDefault = `${appDir}/globals.css`;
+		entry = [
+			"tsx",
+			"jsx",
+			"js"
+		].map((e) => `${appDir}/layout.${e}`).find(has) ?? `${appDir}/layout.tsx`;
+	} else if (!src) cssDefault = "index.css";
+	return {
+		cwd,
+		framework,
+		packageManager: detectPackageManager(cwd, packageJson),
+		css,
+		cssDefault,
+		src,
+		entry,
+		packageJson
+	};
+}
+function defaultConfig(info, brand = "gntik") {
+	const root = info.src ? "src/" : "";
+	return {
+		version: 1,
+		framework: info.framework,
+		packageManager: info.packageManager,
+		css: info.css ?? info.cssDefault,
+		brand,
+		aliases: {
+			components: `${root}components`,
+			blocks: `${root}components/blocks`,
+			templates: `${root}components/templates`
+		}
+	};
+}
+function loadConfig(cwd) {
+	const cfg = readJson(path.join(cwd, CONFIG_FILE));
+	if (!cfg) return null;
+	if (!cfg.aliases?.components) throw new CliError("ERROR", `${CONFIG_FILE} is missing aliases.components`);
+	return cfg;
+}
+/** Maps a registry target into the project via the config aliases (project-relative, posix). */
+function mapTarget(target, kind, config) {
+	const { aliases } = config;
+	const join = (dir, rest) => path.posix.join(dir || ".", rest);
+	if (target.startsWith("components/")) return join(aliases.components, target.slice(11));
+	if (target.startsWith("blocks/")) return join(aliases.blocks, target.slice(7));
+	if (target.startsWith("templates/")) return join(aliases.templates, target.slice(10));
+	return join(kind === "block" ? aliases.blocks : kind === "template" ? aliases.templates : aliases.components, target);
+}
+function installedPackages(pkg) {
+	return /* @__PURE__ */ new Set([...Object.keys(pkg?.dependencies ?? {}), ...Object.keys(pkg?.devDependencies ?? {})]);
+}
+function installCommand(pm, packages, dev = false) {
+	return [
+		pm,
+		pm === "npm" ? "install" : "add",
+		...dev ? ["-D"] : [],
+		...packages
+	];
+}
+//#endregion
+//#region src/copy.ts
+const posix = path.posix;
+const CODE_EXT = /\.(tsx?|jsx?|mts|cts|mjs|cjs)$/;
+/** Packages a React project always has; never auto-installed. */
+const IMPLICIT = /* @__PURE__ */ new Set(["react", "react-dom"]);
+const stripExt = (p) => p.replace(CODE_EXT, "");
+/** Bare specifier → package name ('@scope/pkg/sub' → '@scope/pkg'). */
+function packageName(spec) {
+	if (spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("node:") || spec.startsWith("#")) return null;
+	const parts = spec.split("/");
+	return spec.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0] ?? null;
+}
+/** Every module specifier in a source file, with its position. */
+const SPEC_RE = /(\bfrom\s*|\bimport\s*\(\s*|\bimport\s+|\brequire\s*\(\s*)(['"])([^'"\n]+)\2/g;
+function rewriteSpecifiers(code, fn) {
+	return code.replace(SPEC_RE, (m, lead, q, spec) => {
+		const next = fn(spec);
+		return next === spec ? m : `${lead}${q}${next}${q}`;
+	});
+}
+function buildIndex(registry) {
+	const byKey = /* @__PURE__ */ new Map();
+	const pkgByDir = /* @__PURE__ */ new Map();
+	for (const item of registry.items) for (const f of [...item.files.map((x) => x.path), ...item.docs ? [item.docs] : []]) {
+		const key = stripExt(f);
+		if (!byKey.has(key)) byKey.set(key, {
+			item,
+			path: f,
+			viaDir: false
+		});
+		if (posix.basename(key) === "index") {
+			const dir = posix.dirname(key);
+			if (!byKey.has(dir)) byKey.set(dir, {
+				item,
+				path: f,
+				viaDir: true
+			});
+		}
+		const m = /^packages\/([^/]+)\//.exec(f);
+		if (m?.[1] && !pkgByDir.has(m[1])) pkgByDir.set(m[1], item.package);
+	}
+	return {
+		byKey,
+		pkgByDir
+	};
+}
+/** Target for an item's doc file: next to the item's file that shares its source folder. */
+function docsTarget(item, config) {
+	if (!item.docs) return null;
+	const dir = posix.dirname(item.docs);
+	const sibling = item.files.find((f) => posix.dirname(f.path) === dir) ?? item.files[0];
+	if (!sibling) return null;
+	return posix.join(posix.dirname(mapTarget(sibling.target, item.kind, config)), posix.basename(item.docs));
+}
+function relSpec(fromFile, toFile, keepExt, asDir) {
+	let to = asDir ? posix.dirname(toFile) : stripExt(toFile);
+	if (keepExt && !asDir) to += keepExt;
+	let rel = posix.relative(posix.dirname(fromFile), to);
+	if (!rel.startsWith(".")) rel = `./${rel}`;
+	return rel;
+}
+/**
+* Reads the items' files from the registry, maps them to project targets and rewrites imports:
+* relative imports between copied files are re-pointed at the new locations; relative imports
+* into kit code that is not copied become package imports (e.g. '../../components/Button' →
+* '@gntik-ai/ui'). Nothing is written here.
+*/
+async function planCopy(registry, items, config, cwd, opts = {}) {
+	const { byKey, pkgByDir } = buildIndex(registry);
+	const copyMap = /* @__PURE__ */ new Map();
+	const sources = [];
+	for (const item of items) {
+		for (const f of item.files) {
+			copyMap.set(f.path, mapTarget(f.target, item.kind, config));
+			sources.push({
+				item,
+				source: f.path
+			});
+		}
+		const dt = opts.includeDocs ? docsTarget(item, config) : null;
+		if (dt && item.docs) {
+			copyMap.set(item.docs, dt);
+			sources.push({
+				item,
+				source: item.docs
+			});
+		}
+	}
+	const rewrites = [];
+	const warnings = [];
+	const packages = /* @__PURE__ */ new Set();
+	const files = [];
+	for (const { item, source } of sources) {
+		const target = copyMap.get(source);
+		let content = await registry.read(source);
+		if (CODE_EXT.test(source)) content = rewriteSpecifiers(content, (spec) => {
+			const bare = packageName(spec);
+			if (bare) {
+				if (!IMPLICIT.has(bare)) packages.add(bare);
+				return spec;
+			}
+			if (!spec.startsWith(".")) return spec;
+			const extMatch = CODE_EXT.exec(spec);
+			const resolved = posix.normalize(posix.join(posix.dirname(source), stripExt(spec)));
+			const hit = byKey.get(resolved);
+			let next = spec;
+			const copiedTarget = hit ? copyMap.get(hit.path) : void 0;
+			if (hit && copiedTarget) next = relSpec(target, copiedTarget, extMatch?.[0] ?? null, hit.viaDir);
+			else if (hit) next = hit.item.package;
+			else {
+				const dir = /^packages\/([^/]+)\//.exec(resolved)?.[1];
+				if (dir) {
+					next = pkgByDir.get(dir) ?? `@gntik-ai/${dir}`;
+					if (source !== item.docs) warnings.push(`${target}: '${spec}' is kit-internal code outside the registry; mapped to '${next}' — check that it is exported there.`);
+				} else warnings.push(`${target}: could not resolve '${spec}'; left unchanged.`);
+			}
+			if (next !== spec) {
+				rewrites.push({
+					file: target,
+					from: spec,
+					to: next
+				});
+				const pkg = packageName(next);
+				if (pkg) packages.add(pkg);
+			}
+			return next;
+		});
+		const abs = path.join(cwd, target);
+		let status = "create";
+		if (existsSync(abs)) status = await readFile(abs, "utf8") === content ? "identical" : "conflict";
+		files.push({
+			id: item.id,
+			source,
+			target,
+			status,
+			content
+		});
+	}
+	return {
+		files,
+		rewrites,
+		warnings,
+		packages: [...packages].sort()
+	};
+}
+/** Writes the plan unless it has conflicts (then nothing is written) or this is a dry run. */
+async function applyCopy(plan, cwd, opts) {
+	if (opts.overwrite) {
+		for (const f of plan.files) if (f.status === "conflict") f.status = "overwrite";
+	}
+	const conflicts = plan.files.filter((f) => f.status === "conflict").map((f) => f.target);
+	const written = [];
+	if (conflicts.length || opts.dryRun) return {
+		conflicts,
+		written
+	};
+	for (const f of plan.files) {
+		if (f.status === "identical") continue;
+		const abs = path.join(cwd, f.target);
+		await mkdir(path.dirname(abs), { recursive: true });
+		await writeFile(abs, f.content);
+		written.push(f.target);
+	}
+	return {
+		conflicts,
+		written
+	};
+}
+const fileSummary = (f) => ({
+	id: f.id,
+	source: f.source,
+	target: f.target,
+	status: f.status
+});
+const REGISTRY_FILE = "kit-registry.json";
+const ITEM_KINDS = [
+	"component",
+	"layout",
+	"block",
+	"template"
+];
+/** Copy-in kinds: their source is copied into the project. Components and layouts install from npm. */
+const isCopyIn = (kind) => kind === "block" || kind === "template";
+var Registry = class {
+	data;
+	source;
+	byId = /* @__PURE__ */ new Map();
+	constructor(data, source) {
+		this.data = data;
+		this.source = source;
+		for (const item of data.items) this.byId.set(item.id, item);
+	}
+	get items() {
+		return this.data.items;
+	}
+	get(id) {
+		return this.byId.get(id);
+	}
+	/** Reads a repo-relative file from the registry source. */
+	async read(file) {
+		if (this.source.type === "local") try {
+			return await readFile(path.join(this.source.base, file), "utf8");
+		} catch {
+			throw new CliError("REGISTRY", `Cannot read ${file} from ${this.source.base}`);
+		}
+		return fetchText(new URL(file, this.source.base).href);
+	}
+	/**
+	* Requested ids plus their registryDependencies, recursively; dependencies come before
+	* the items that need them. Unknown ids throw NOT_FOUND.
+	*/
+	closure(ids) {
+		const out = [];
+		const seen = /* @__PURE__ */ new Set();
+		const visit = (id, from) => {
+			if (seen.has(id)) return;
+			seen.add(id);
+			const item = this.get(id);
+			if (!item) throw new CliError("NOT_FOUND", from ? `Unknown registry dependency "${id}" (needed by ${from})` : `Unknown item "${id}"`);
+			for (const dep of item.registryDependencies) visit(dep, id);
+			out.push(item);
+		};
+		for (const id of ids) visit(id);
+		return out;
+	}
+};
+async function fetchText(url) {
+	let res;
+	try {
+		res = await fetch(url);
+	} catch (e) {
+		throw new CliError("REGISTRY", `Cannot fetch ${url}: ${e.message}`);
+	}
+	if (!res.ok) throw new CliError("REGISTRY", `Cannot fetch ${url}: HTTP ${res.status}`);
+	return res.text();
+}
+const isUrl = (s) => /^https?:\/\//i.test(s);
+/** Resolves `--registry` (a checkout dir, a kit-registry.json path or a base URL) to a source. */
+async function resolveSource(spec, cwd) {
+	if (isUrl(spec)) {
+		if (spec.endsWith(".json")) {
+			const u = new URL(spec);
+			return {
+				source: {
+					type: "url",
+					base: new URL("./", u).href
+				},
+				file: u.href
+			};
+		}
+		const base = spec.endsWith("/") ? spec : `${spec}/`;
+		return {
+			source: {
+				type: "url",
+				base
+			},
+			file: new URL(REGISTRY_FILE, base).href
+		};
+	}
+	const abs = path.resolve(cwd, spec);
+	const st = await stat(abs).catch(() => null);
+	if (!st) throw new CliError("REGISTRY", `Registry path not found: ${abs}`);
+	if (st.isFile()) return {
+		source: {
+			type: "local",
+			base: path.dirname(abs)
+		},
+		file: abs
+	};
+	return {
+		source: {
+			type: "local",
+			base: abs
+		},
+		file: path.join(abs, REGISTRY_FILE)
+	};
+}
+function validateRegistry(data, where) {
+	const fail = (msg) => {
+		throw new CliError("REGISTRY", `Invalid registry ${where}: ${msg}`);
+	};
+	if (!data || typeof data !== "object") fail("not an object");
+	const d = data;
+	if (d.version !== 1) fail(`unsupported version ${String(d.version)}`);
+	if (!Array.isArray(d.items)) fail("\"items\" must be an array");
+	for (const [i, item] of d.items.entries()) {
+		if (!item || typeof item.id !== "string") fail(`items[${i}].id missing`);
+		if (!ITEM_KINDS.includes(item.kind)) fail(`items[${i}] (${item.id}) has unknown kind "${String(item.kind)}"`);
+		if (!Array.isArray(item.files)) fail(`items[${i}] (${item.id}) has no files array`);
+		item.dependencies ??= [];
+		item.registryDependencies ??= [];
+		item.group ??= "";
+		item.status ??= "stable";
+		item.description ??= "";
+	}
+	return d;
+}
+async function loadRegistry(spec, cwd) {
+	const { source, file } = await resolveSource(spec, cwd);
+	let text;
+	if (source.type === "local") text = await readFile(file, "utf8").catch(() => {
+		throw new CliError("REGISTRY", `No ${REGISTRY_FILE} at ${file}`);
+	});
+	else text = await fetchText(file);
+	let json;
+	try {
+		json = JSON.parse(text);
+	} catch {
+		throw new CliError("REGISTRY", `${file} is not valid JSON`);
+	}
+	return new Registry(validateRegistry(json, file), source);
+}
+/** Short, stable item summary used by list/search JSON. */
+function summary(item) {
+	return {
+		id: item.id,
+		kind: item.kind,
+		name: item.name,
+		package: item.package,
+		group: item.group,
+		status: item.status,
+		description: item.description
+	};
+}
+//#endregion
+//#region src/context.ts
+const defaultExec = (cmd, args, { cwd, quiet }) => {
+	const r = spawnSync(cmd, args, {
+		cwd,
+		stdio: quiet ? "pipe" : "inherit",
+		shell: process.platform === "win32"
+	});
+	if (r.error) return 127;
+	return r.status ?? 1;
+};
+const ok = (data, text) => ({
+	code: 0,
+	data,
+	text
+});
+function registrySpec(ctx, configured) {
+	return ctx.flags.registry ?? ctx.env.GNTIK_UI_REGISTRY ?? configured ?? "https://raw.githubusercontent.com/gntik-ai/gntik-ui/main/";
+}
+async function openRegistry(ctx, configured) {
+	return loadRegistry(registrySpec(ctx, configured), ctx.invocationCwd);
+}
+/**
+* Installs the packages the project does not declare yet. Runs only when installing is allowed
+* (no --dry-run, no --no-install); otherwise reports the commands.
+*/
+function runInstall(ctx, pm, pkg, wanted, wantedDev = []) {
+	const have = installedPackages(pkg);
+	const packages = [...new Set(wanted)].filter((p) => !have.has(p)).sort();
+	const dev = [...new Set(wantedDev)].filter((p) => !have.has(p) && !packages.includes(p)).sort();
+	const cmds = [];
+	if (packages.length) cmds.push(installCommand(pm, packages));
+	if (dev.length) cmds.push(installCommand(pm, dev, true));
+	const report = {
+		packages,
+		dev,
+		commands: cmds.map((c) => c.join(" ")),
+		ran: false,
+		exitCode: null
+	};
+	if (!cmds.length || ctx.flags.dryRun || !ctx.flags.install) return report;
+	report.ran = true;
+	for (const [cmd, ...args] of cmds) {
+		const code = ctx.exec(cmd, args, {
+			cwd: ctx.cwd,
+			quiet: ctx.flags.json
+		});
+		report.exitCode = code;
+		if (code !== 0) break;
+	}
+	return report;
+}
+function installLines(report, ctx) {
+	if (!report.commands.length) return ["Packages: already installed."];
+	const verb = report.ran ? "Ran" : ctx.flags.dryRun ? "Would run" : "Run";
+	const lines = report.commands.map((c) => `${verb}: ${c}`);
+	if (report.ran && report.exitCode !== 0) lines.push(`Install failed (exit ${report.exitCode}).`);
+	return lines;
+}
+/** Turns a failed install into a non-zero result that still carries the data. */
+function withInstallStatus(result, report) {
+	if (report.ran && report.exitCode !== 0) return {
+		...result,
+		code: 1,
+		error: new CliError("INSTALL", `Install command failed with exit code ${report.exitCode}`)
+	};
+	return result;
+}
+//#endregion
+//#region src/commands/add.ts
+function projectContext(ctx) {
+	const info = detectProject(ctx.cwd);
+	const loaded = loadConfig(ctx.cwd);
+	return {
+		info,
+		config: loaded ?? defaultConfig(info),
+		configured: loaded !== null
+	};
+}
+/** Public export names of a component: from its index file, else its name. */
+function exportNames(item, indexSource) {
+	const names = /* @__PURE__ */ new Set();
+	if (indexSource) for (const m of indexSource.matchAll(/export\s*\{([^}]*)\}/g)) for (const part of (m[1] ?? "").split(",")) {
+		const p = part.trim();
+		if (!p || p.startsWith("type ")) continue;
+		const name = (p.split(/\s+as\s+/)[1] ?? p).trim();
+		if (/^[A-Z]/.test(name)) names.add(name);
+	}
+	if (!names.size) names.add(item.name.replace(/[^A-Za-z0-9_$]/g, ""));
+	return [...names];
+}
+function importLine(names, from) {
+	return `import { ${names.join(", ")} } from '${from}';`;
+}
+async function packageImport(ctx, item, read) {
+	const index = item.files.find((f) => /\/index\.[jt]sx?$/.test(f.path));
+	return importLine(exportNames(item, index ? await read(index.path).catch(() => void 0) : void 0), item.package);
+}
+function copySection(plan, conflicts, ctx) {
+	const label = {
+		create: ctx.flags.dryRun ? "would create" : "created",
+		identical: "unchanged",
+		conflict: "CONFLICT",
+		overwrite: ctx.flags.dryRun ? "would overwrite" : "overwritten"
+	};
+	const lines = plan.files.map((f) => `  ${label[f.status].padEnd(15)} ${f.target}`);
+	if (plan.rewrites.length) lines.push("Rewritten imports:", ...plan.rewrites.map((r) => `  ${r.file}: '${r.from}' → '${r.to}'`));
+	if (plan.warnings.length) lines.push("Warnings:", ...plan.warnings.map((w) => `  ${w}`));
+	if (conflicts.length) lines.push(`${conflicts.length} file(s) already exist and differ — nothing was written. Re-run with --overwrite to replace them.`);
+	return lines;
+}
+async function add(ctx, positionals) {
+	if (!positionals.length) throw new CliError("USAGE", "Usage: gntik-ui add <id...>");
+	const project = projectContext(ctx);
+	const { config, info } = project;
+	const registry = await openRegistry(ctx, config.registry);
+	const closure = registry.closure(positionals);
+	const requested = new Set(positionals);
+	const toCopy = closure.filter((i) => isCopyIn(i.kind));
+	const packageItems = closure.filter((i) => !isCopyIn(i.kind) && (requested.has(i.id) || toCopy.length > 0));
+	const viaPackage = packageItems.filter((i) => requested.has(i.id));
+	const plan = await planCopy(registry, toCopy, config, ctx.cwd);
+	const { conflicts, written } = await applyCopy(plan, ctx.cwd, {
+		overwrite: ctx.flags.overwrite,
+		dryRun: ctx.flags.dryRun
+	});
+	const imports = [];
+	for (const item of viaPackage) imports.push(await packageImport(ctx, item, (p) => registry.read(p)));
+	const wanted = [
+		...packageItems.map((i) => i.package),
+		...toCopy.flatMap((i) => i.dependencies),
+		...plan.packages
+	];
+	const install = conflicts.length ? {
+		packages: [],
+		dev: [],
+		commands: [],
+		ran: false,
+		exitCode: null
+	} : runInstall(ctx, config.packageManager, info.packageJson, wanted);
+	const data = {
+		dryRun: ctx.flags.dryRun,
+		configured: project.configured,
+		items: closure.map((i) => ({
+			id: i.id,
+			kind: i.kind,
+			package: i.package,
+			mode: isCopyIn(i.kind) ? "copy" : "package",
+			requested: requested.has(i.id)
+		})),
+		files: plan.files.map(fileSummary),
+		written,
+		conflicts,
+		rewrites: plan.rewrites,
+		warnings: plan.warnings,
+		imports,
+		install
+	};
+	const text = [];
+	if (!project.configured) text.push(`No ${CONFIG_FILE} found — using defaults (run gntik-ui init).`);
+	if (plan.files.length) text.push("Files:", ...copySection(plan, conflicts, ctx));
+	if (imports.length) text.push("Import:", ...imports.map((l) => `  ${l}`));
+	text.push(...installLines(install, ctx));
+	if (conflicts.length) return {
+		code: 4,
+		data,
+		text,
+		error: new CliError("CONFLICT", `${conflicts.length} file(s) already exist: ${conflicts.join(", ")}`)
+	};
+	return withInstallStatus({
+		code: 0,
+		data,
+		text
+	}, install);
+}
+//#endregion
+//#region src/commands/eject.ts
+const SKIP_DIRS = /* @__PURE__ */ new Set([
+	"node_modules",
+	".git",
+	"dist",
+	"build",
+	".next",
+	"out",
+	"coverage",
+	".turbo",
+	".vercel"
+]);
+const CODE = /\.(tsx?|jsx?|mts|mjs)$/;
+async function walk(dir, out = []) {
+	const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+	for (const e of entries) if (e.isDirectory()) {
+		if (!SKIP_DIRS.has(e.name) && !e.name.startsWith(".")) await walk(path.join(dir, e.name), out);
+	} else if (CODE.test(e.name)) out.push(path.join(dir, e.name));
+	return out;
+}
+/** Finds `import { … } from '<package>'` lines that use the ejected component's names. */
+async function findUsages(cwd, pkg, names, localEntry, skip) {
+	const usages = [];
+	const re = new RegExp(String.raw`import\s*(?:type\s*)?\{([^}]*)\}\s*from\s*['"]${pkg.replace(/[/.]/g, "\\$&")}['"]`, "g");
+	for (const abs of await walk(cwd)) {
+		const rel = path.relative(cwd, abs).split(path.sep).join("/");
+		if (skip.has(rel)) continue;
+		const text = await readFile(abs, "utf8");
+		for (const m of text.matchAll(re)) {
+			const hit = (m[1] ?? "").split(",").map((s) => s.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0]?.trim() ?? "").filter((n) => names.includes(n));
+			if (!hit.length) continue;
+			let spec = path.posix.relative(path.posix.dirname(rel), localEntry);
+			if (!spec.startsWith(".")) spec = `./${spec}`;
+			const line = text.slice(0, m.index).split("\n").length;
+			usages.push({
+				file: rel,
+				line,
+				names: hit,
+				replacement: `import { ${hit.join(", ")} } from '${spec}';`
+			});
+		}
+	}
+	return usages;
+}
+async function eject(ctx, positionals) {
+	const [id] = positionals;
+	if (!id || positionals.length > 1) throw new CliError("USAGE", "Usage: gntik-ui eject <id>");
+	const project = projectContext(ctx);
+	const { config, info } = project;
+	const registry = await openRegistry(ctx, config.registry);
+	const item = registry.get(id);
+	if (!item) throw new CliError("NOT_FOUND", `Unknown item "${id}"`);
+	const items = ctx.flags.deps ? registry.closure([id]) : [item];
+	const plan = await planCopy(registry, items, config, ctx.cwd, { includeDocs: true });
+	const { conflicts, written } = await applyCopy(plan, ctx.cwd, {
+		overwrite: ctx.flags.overwrite,
+		dryRun: ctx.flags.dryRun
+	});
+	const indexFile = item.files.find((f) => /\/index\.[jt]sx?$/.test(f.path)) ?? item.files[0];
+	const localEntry = indexFile ? (() => {
+		const t = mapTarget(indexFile.target, item.kind, config);
+		return /\/index\.[jt]sx?$/.test(t) ? path.posix.dirname(t) : t.replace(/\.[jt]sx?$/, "");
+	})() : "";
+	const indexContent = plan.files.find((f) => f.source === indexFile?.path)?.content;
+	const names = exportNames(item, indexContent);
+	const usages = await findUsages(ctx.cwd, item.package, names, localEntry, new Set(plan.files.map((f) => f.target)));
+	const install = conflicts.length ? {
+		packages: [],
+		dev: [],
+		commands: [],
+		ran: false,
+		exitCode: null
+	} : runInstall(ctx, config.packageManager, info.packageJson, [...items.flatMap((i) => i.dependencies), ...plan.packages]);
+	const nextSteps = [
+		`Import ${names.join(", ")} from the local copy (${localEntry}) instead of '${item.package}'.`,
+		...usages.length ? [`Update the ${usages.length} import(s) listed under usages.`] : [],
+		"The copy no longer receives kit updates; diff against the registry when upgrading."
+	];
+	const data = {
+		dryRun: ctx.flags.dryRun,
+		configured: project.configured,
+		id,
+		items: items.map((i) => i.id),
+		files: plan.files.map(fileSummary),
+		written,
+		conflicts,
+		rewrites: plan.rewrites,
+		warnings: plan.warnings,
+		localImport: localEntry,
+		exports: names,
+		usages,
+		nextSteps,
+		install
+	};
+	const text = [];
+	if (!project.configured) text.push(`No ${CONFIG_FILE} found — using defaults (run gntik-ui init).`);
+	text.push(`Eject ${item.name} (${items.map((i) => i.id).join(", ")}):`, ...copySection(plan, conflicts, ctx));
+	if (conflicts.length) {
+		if (ctx.flags.deps) text.push("Tip: --no-deps ejects only this item and keeps its dependencies on the package.");
+		return {
+			code: 4,
+			data,
+			text,
+			error: new CliError("CONFLICT", `${conflicts.length} file(s) already exist: ${conflicts.join(", ")}`)
+		};
+	}
+	text.push("Next:", ...nextSteps.map((s) => `  - ${s}`));
+	for (const u of usages) text.push(`  ${u.file}:${u.line}  ${u.replacement}`);
+	text.push(...installLines(install, ctx));
+	return withInstallStatus({
+		code: 0,
+		data,
+		text
+	}, install);
+}
+//#endregion
+//#region src/commands/init.ts
+const BRANDS = [
+	"gntik",
+	"musematic",
+	"falcone"
+];
+const CSS_IMPORTS = [
+	"@import \"tailwindcss\";",
+	"@import \"@fontsource/geist\";",
+	"@import \"@fontsource/geist-mono\";",
+	"@import \"@gntik-ai/ui/styles.css\";"
+];
+const IMPORT_TARGETS = [
+	"tailwindcss",
+	"@fontsource/geist",
+	"@fontsource/geist-mono",
+	"@gntik-ai/ui/styles.css"
+];
+/**
+* Puts Tailwind, the Geist fonts and the kit styles at the top of the CSS entry, in that order,
+* keeping everything else. Existing copies of those imports are moved, not duplicated.
+*/
+function patchCss(text) {
+	const lines = text === null ? [] : text.split(/\r?\n/);
+	const isOurs = (l) => {
+		const m = /^\s*@import\s+(?:url\()?\s*["']([^"']+)["']/.exec(l);
+		return !!m && IMPORT_TARGETS.includes(m[1] ?? "");
+	};
+	const head = lines.slice(0, CSS_IMPORTS.length).map((l) => l.trim());
+	if (CSS_IMPORTS.every((l, i) => head[i] === l) && lines.slice(CSS_IMPORTS.length).every((l) => !isOurs(l))) return text ?? "";
+	const rest = lines.filter((l) => !isOurs(l));
+	while (rest.length && rest[0]?.trim() === "") rest.shift();
+	return [
+		...CSS_IMPORTS,
+		"",
+		...rest
+	].join("\n").replace(/\n*$/, "\n");
+}
+const presetName = (brand) => `${brand}Preset`;
+function themeSnippet(framework, entry, css, brand) {
+	const preset = presetName(brand);
+	const cssImport = (from) => {
+		let rel = path.posix.relative(path.posix.dirname(from), css);
+		if (!rel.startsWith(".")) rel = `./${rel}`;
+		return rel;
+	};
+	if (framework === "next") return [{
+		file: `${path.posix.dirname(entry)}/providers.tsx`,
+		code: `'use client';
+import type { ReactNode } from 'react';
+import { ThemeProvider, ${preset}, themeScript } from '@gntik-ai/ui';
+
+export function Providers({ children }: { children: ReactNode }) {
+  return (
+    <>
+      {/* Applies the stored theme before first paint (no flash). */}
+      <script dangerouslySetInnerHTML={{ __html: themeScript() }} />
+      <ThemeProvider brand={${preset}}>{children}</ThemeProvider>
+    </>
+  );
+}
+`
+	}, {
+		file: entry,
+		code: `import type { ReactNode } from 'react';
+import { Providers } from './providers';
+import '${cssImport(entry)}';
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    // The theme script sets the class before React hydrates.
+    <html lang="en" className="dark" suppressHydrationWarning>
+      <body className="bg-background text-foreground antialiased">
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+`
+	}];
+	const files = [{
+		file: entry,
+		code: `import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { ThemeProvider, ${preset} } from '@gntik-ai/ui';
+import App from './App';
+import '${cssImport(entry)}';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <ThemeProvider brand={${preset}}>
+      <App />
+    </ThemeProvider>
+  </StrictMode>,
+);
+`
+	}];
+	if (framework === "vite") files.push({
+		file: "vite.config.ts",
+		code: `import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+import { themeScript } from '@gntik-ai/ui';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss(),
+    // Inlines the theme script in <head> so the stored theme applies before first paint.
+    { name: 'gntik-theme', transformIndexHtml: () => [{ tag: 'script', children: themeScript(), injectTo: 'head-prepend' }] },
+  ],
+});
+`
+	});
+	else files.push({
+		file: "index.html",
+		code: `<!-- In <head>: inline the output of themeScript() from @gntik-ai/ui to avoid a theme flash. -->
+<script>/* themeScript() output */<\/script>
+`
+	});
+	return files;
+}
+async function readOrNull(file) {
+	return existsSync(file) ? readFile(file, "utf8") : null;
+}
+function change(file, before, after) {
+	return {
+		file,
+		action: before === null ? "create" : before === after ? "unchanged" : "patch",
+		content: after
+	};
+}
+async function init(ctx) {
+	const brand = ctx.flags.brand ?? "gntik";
+	if (!BRANDS.includes(brand)) throw new CliError("USAGE", `--brand must be one of ${BRANDS.join(", ")}`);
+	if (!existsSync(ctx.cwd)) throw new CliError("USAGE", `Directory not found: ${ctx.cwd}`);
+	const info = detectProject(ctx.cwd);
+	const existing = loadConfig(ctx.cwd);
+	const config = existing && !ctx.flags.overwrite ? existing : {
+		...defaultConfig(info, brand),
+		...existing?.registry ? { registry: existing.registry } : {}
+	};
+	const cssFile = config.css;
+	const cssPath = path.join(ctx.cwd, cssFile);
+	const cfgPath = path.join(ctx.cwd, CONFIG_FILE);
+	const cssBefore = await readOrNull(cssPath);
+	const cfgBefore = await readOrNull(cfgPath);
+	const cfgText = `${JSON.stringify(config, null, 2)}\n`;
+	const changes = [change(cssFile, cssBefore, patchCss(cssBefore)), change(CONFIG_FILE, cfgBefore, cfgBefore !== null && !ctx.flags.overwrite ? cfgBefore : cfgText)];
+	if (!ctx.flags.dryRun) for (const c of changes) {
+		if (c.action === "unchanged") continue;
+		const abs = path.join(ctx.cwd, c.file);
+		await mkdir(path.dirname(abs), { recursive: true });
+		await writeFile(abs, c.content);
+	}
+	const warnings = [];
+	if ((await readOrNull(path.join(ctx.cwd, ".npmrc")))?.split(/\r?\n/).some((line) => line.trim().startsWith(`@gntik-ai:registry`))) warnings.push("New @gntik-ai versions are on npmjs.org; remove the @gntik-ai:registry line from .npmrc.");
+	if (cssBefore && /@tailwind\s+(base|components|utilities)/.test(cssBefore)) warnings.push(`${cssFile} has Tailwind v3 directives (@tailwind …); the kit needs Tailwind v4 — remove them.`);
+	if (!info.packageJson) warnings.push("No package.json found in this directory.");
+	const have = installedPackages(info.packageJson);
+	const dev = [];
+	if (!have.has("tailwindcss")) {
+		dev.push("tailwindcss", info.framework === "next" ? "@tailwindcss/postcss" : "@tailwindcss/vite");
+		if (info.framework === "next" && !existsSync(path.join(ctx.cwd, "postcss.config.mjs"))) warnings.push("Add postcss.config.mjs: export default { plugins: { \"@tailwindcss/postcss\": {} } };");
+	}
+	const install = runInstall(ctx, config.packageManager, info.packageJson, [
+		"@gntik-ai/ui",
+		"@gntik-ai/tokens",
+		"@fontsource/geist",
+		"@fontsource/geist-mono"
+	], dev);
+	const snippet = themeSnippet(info.framework, info.entry, cssFile, config.brand);
+	const label = (a) => (ctx.flags.dryRun ? {
+		create: "would create",
+		patch: "would patch",
+		unchanged: "unchanged"
+	} : {
+		create: "created",
+		patch: "patched",
+		unchanged: "unchanged"
+	})[a];
+	const text = [
+		`Project: ${info.framework} · ${config.packageManager} · CSS ${cssFile}${info.css ? "" : " (new)"}`,
+		...changes.map((c) => `  ${label(c.action).padEnd(13)} ${c.file}`),
+		...warnings.map((w) => `Warning: ${w}`),
+		"",
+		"Wire the theme (dark by default; light and high_contrast via useTheme().setMode):",
+		...snippet.flatMap((s) => [
+			"",
+			`// ${s.file}`,
+			...s.code.trimEnd().split("\n")
+		]),
+		"",
+		...installLines(install, ctx)
+	];
+	return withInstallStatus({
+		code: 0,
+		data: {
+			dryRun: ctx.flags.dryRun,
+			project: {
+				framework: info.framework,
+				packageManager: config.packageManager,
+				css: cssFile,
+				cssExisted: info.css !== null,
+				entry: info.entry,
+				src: info.src
+			},
+			config,
+			changes: changes.map(({ file, action }) => ({
+				file,
+				action
+			})),
+			snippet,
+			warnings,
+			install
+		},
+		text
+	}, install);
+}
+//#endregion
+//#region src/commands/query.ts
+async function registryFor(ctx) {
+	let configured;
+	try {
+		configured = loadConfig(ctx.cwd)?.registry;
+	} catch {
+		configured = void 0;
+	}
+	return openRegistry(ctx, configured);
+}
+function checkKind(kind) {
+	if (kind && !ITEM_KINDS.includes(kind)) throw new CliError("USAGE", `--kind must be one of ${ITEM_KINDS.join(", ")}`);
+}
+/** Fixed-width table for humans. */
+function table(rows) {
+	const widths = rows[0]?.map((_, i) => Math.max(...rows.map((r) => (r[i] ?? "").length))) ?? [];
+	return rows.map((r) => r.map((c, i) => i === r.length - 1 ? c : c.padEnd(widths[i] ?? 0)).join("  ").trimEnd());
+}
+const truncate = (s, n) => s.length > n ? `${s.slice(0, n - 1)}…` : s;
+async function list(ctx) {
+	const { kind, group } = ctx.flags;
+	checkKind(kind);
+	const registry = await registryFor(ctx);
+	const items = registry.items.filter((i) => (!kind || i.kind === kind) && (!group || i.group.toLowerCase() === group.toLowerCase()));
+	const rows = [[
+		"ID",
+		"KIND",
+		"GROUP",
+		"STATUS",
+		"PACKAGE"
+	], ...items.map((i) => [
+		i.id,
+		i.kind,
+		i.group,
+		i.status,
+		i.package
+	])];
+	return ok({
+		registry: registry.source.base,
+		count: items.length,
+		items: items.map(summary)
+	}, items.length ? [
+		...table(rows),
+		"",
+		`${items.length} item(s)`
+	] : ["No items match."]);
+}
+/** Subsequence match: every query char appears in order. Returns a 0..1 closeness. */
+function subsequence(q, s) {
+	let i = 0;
+	let gaps = 0;
+	let last = -1;
+	for (let j = 0; j < s.length && i < q.length; j++) if (s[j] === q[i]) {
+		if (last >= 0) gaps += j - last - 1;
+		last = j;
+		i++;
+	}
+	return i === q.length ? 1 / (1 + gaps) : 0;
+}
+/** Scores one item against one query term; 0 means no match. */
+function termScore(term, item) {
+	const id = item.id.toLowerCase();
+	const name = item.name.toLowerCase();
+	const group = item.group.toLowerCase();
+	const desc = item.description.toLowerCase();
+	if (id === term || name === term) return 100;
+	if (id.startsWith(term) || name.startsWith(term)) return 80;
+	if (id.includes(term) || name.includes(term)) return 60;
+	if (group === term || group.includes(term)) return 40;
+	if (new RegExp(`\\b${term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`).test(desc)) return 30;
+	const fuzzy = Math.max(subsequence(term, id), subsequence(term, name));
+	if (fuzzy > 0 && term.length >= 2) return Math.round(10 + 20 * fuzzy);
+	if (desc.includes(term)) return 10;
+	return 0;
+}
+function searchItems(items, query) {
+	const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+	return items.map((item) => {
+		const scores = terms.map((t) => termScore(t, item));
+		return {
+			item,
+			score: scores.every((s) => s > 0) ? scores.reduce((a, b) => a + b, 0) : 0
+		};
+	}).filter((r) => r.score > 0).sort((a, b) => b.score - a.score || a.item.id.localeCompare(b.item.id));
+}
+async function search(ctx, positionals) {
+	const query = positionals.join(" ").trim();
+	if (!query) throw new CliError("USAGE", "Usage: gntik-ui search <query>");
+	checkKind(ctx.flags.kind);
+	let results = searchItems((await registryFor(ctx)).items.filter((i) => !ctx.flags.kind || i.kind === ctx.flags.kind), query);
+	if (ctx.flags.limit) results = results.slice(0, ctx.flags.limit);
+	const rows = [[
+		"ID",
+		"KIND",
+		"SCORE",
+		"DESCRIPTION"
+	], ...results.map((r) => [
+		r.item.id,
+		r.item.kind,
+		String(r.score),
+		truncate(r.item.description, 60)
+	])];
+	return ok({
+		query,
+		count: results.length,
+		items: results.map((r) => ({
+			...summary(r.item),
+			score: r.score
+		}))
+	}, results.length ? table(rows) : [`No items match "${query}".`]);
+}
+const STR = String.raw`(?:'((?:[^'\\]|\\.)*)'|"((?:[^"\\]|\\.)*)"|\x60((?:[^\x60\\]|\\.)*)\x60)`;
+const unescape = (s) => s.replace(/\\(.)/g, "$1");
+/** Reads primitive, pattern and the keyboard table from a *.doc.ts file without executing it. */
+function parseDocFile(text) {
+	const field = (name) => {
+		const m = new RegExp(`\\b${name}\\s*:\\s*${STR}`).exec(text);
+		return m ? unescape(m[1] ?? m[2] ?? m[3] ?? "") : null;
+	};
+	const keyboard = [];
+	const start = /\bkeyboard\s*:\s*\[/.exec(text);
+	if (start) {
+		let depth = 1;
+		let i = start.index + start[0].length;
+		for (; i < text.length && depth > 0; i++) {
+			const c = text[i];
+			if (c === "[") depth++;
+			else if (c === "]") depth--;
+			else if (c === "'" || c === "\"" || c === "`") {
+				for (i++; i < text.length && text[i] !== c; i++) if (text[i] === "\\") i++;
+			}
+		}
+		const body = text.slice(start.index + start[0].length, i - 1);
+		const row = new RegExp(String.raw`\[\s*${STR}\s*,\s*${STR}\s*,?\s*\]`, "g");
+		for (const m of body.matchAll(row)) keyboard.push({
+			key: unescape(m[1] ?? m[2] ?? m[3] ?? ""),
+			behaviour: unescape(m[4] ?? m[5] ?? m[6] ?? "")
+		});
+	}
+	return {
+		primitive: field("primitive"),
+		pattern: field("pattern"),
+		keyboard
+	};
+}
+async function docs(ctx, positionals) {
+	const [id] = positionals;
+	if (!id || positionals.length > 1) throw new CliError("USAGE", "Usage: gntik-ui docs <id>");
+	const registry = await registryFor(ctx);
+	const item = registry.get(id);
+	if (!item) throw new CliError("NOT_FOUND", `Unknown item "${id}". Try: gntik-ui search ${id}`);
+	let info = {
+		primitive: null,
+		pattern: null,
+		keyboard: []
+	};
+	if (item.docs) info = parseDocFile(await registry.read(item.docs));
+	const text = [
+		`${item.name} (${item.id}) — ${item.kind} · ${item.group} · ${item.status}`,
+		"",
+		item.description,
+		"",
+		`Package:      ${item.package}`,
+		...info.primitive ? [`Primitive:    ${info.primitive}`] : [],
+		...info.pattern ? [`ARIA pattern: ${info.pattern}`] : [],
+		`Dependencies: ${item.dependencies.join(", ") || "—"}`,
+		`Registry deps: ${item.registryDependencies.join(", ") || "—"}`,
+		"Files:",
+		...item.files.map((f) => `  ${f.path} → ${f.target}`)
+	];
+	if (info.keyboard.length) text.push("", "Keyboard:", ...table([["KEY", "BEHAVIOUR"], ...info.keyboard.map((k) => [k.key, k.behaviour])]).map((l) => `  ${l}`));
+	return ok({
+		item: {
+			...summary(item),
+			files: item.files,
+			dependencies: item.dependencies,
+			registryDependencies: item.registryDependencies,
+			docs: item.docs ?? null
+		},
+		primitive: info.primitive,
+		pattern: info.pattern,
+		keyboard: info.keyboard
+	}, text);
+}
+//#endregion
+//#region src/commands/upgrade.ts
+const CODEMODS_PACKAGE = "@gntik-ai/codemods";
+const VERSION_RE = /^v?\d+(\.\d+){0,2}(-[0-9A-Za-z.-]+)?$/;
+/**
+* Finds @gntik-ai/codemods in the project's node_modules (walking up from cwd, like Node — but not
+* NODE_PATH or global folders, so only a package the project installed counts).
+*/
+function findCodemods(cwd) {
+	let dir = path.resolve(cwd);
+	for (;;) {
+		const pkgDir = path.join(dir, "node_modules", ...CODEMODS_PACKAGE.split("/"));
+		if (existsSync(path.join(pkgDir, "package.json"))) try {
+			return createRequire(path.join(pkgDir, "package.json")).resolve(CODEMODS_PACKAGE);
+		} catch {
+			return null;
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+/** Imports @gntik-ai/codemods from the project; null when it is not installed. */
+async function loadCodemods(cwd) {
+	const resolved = findCodemods(cwd);
+	if (!resolved) return null;
+	const mod = await import(pathToFileURL(resolved).href);
+	if (!Array.isArray(mod.transforms) || typeof mod.selectTransforms !== "function" || typeof mod.runCodemods !== "function") throw new CliError("ERROR", `${resolved} does not look like ${CODEMODS_PACKAGE} (missing transforms/selectTransforms/runCodemods)`);
+	return {
+		module: mod,
+		path: resolved
+	};
+}
+/** Declared @gntik-ai/* versions in the project's package.json (ranges stripped; workspace:/file: specs skipped). */
+function declaredVersions(pkg) {
+	const out = {};
+	for (const [name, spec] of Object.entries({
+		...pkg?.devDependencies,
+		...pkg?.dependencies
+	})) {
+		if (!name.startsWith(`@gntik-ai/`) || name === "@gntik-ai/codemods") continue;
+		const m = /\d+(\.\d+){0,2}(-[0-9A-Za-z.-]+)?/.exec(spec);
+		if (m && !/^(workspace|file|link|git|github|https?):/.test(spec)) out[name] = m[0];
+	}
+	return Object.fromEntries(Object.entries(out).sort(([a], [b]) => a.localeCompare(b)));
+}
+const metaOut = (t) => ({
+	id: t.id,
+	package: t.package,
+	fromVersion: t.fromVersion,
+	toVersion: t.toVersion,
+	reportOnly: t.reportOnly,
+	description: t.description
+});
+async function upgrade(ctx, positionals) {
+	const { flags } = ctx;
+	for (const [name, v] of [["--from", flags.from], ["--to", flags.to]]) if (v !== void 0 && !(name === "--to" && v === "latest") && !VERSION_RE.test(v)) throw new CliError("USAGE", `${name} must be a version like 0.2.0, got "${v}"`);
+	const dryRun = !flags.apply;
+	const pkg = readJson(path.join(ctx.cwd, "package.json"));
+	const detected = declaredVersions(pkg);
+	const from = flags.from ?? (Object.keys(detected).length ? detected : null);
+	const to = flags.to ?? "latest";
+	const loaded = await loadCodemods(ctx.cwd);
+	if (!loaded) {
+		const install = installCommand(detectPackageManager(ctx.cwd, pkg), [CODEMODS_PACKAGE], true).join(" ");
+		return {
+			code: 1,
+			data: {
+				dryRun,
+				from,
+				to,
+				codemods: {
+					installed: false,
+					version: null,
+					install
+				}
+			},
+			text: [`${CODEMODS_PACKAGE} is not installed in this project. Install it, then run upgrade again:`, `  ${install}`],
+			error: new CliError("CODEMODS", `${CODEMODS_PACKAGE} not found from ${ctx.cwd}`)
+		};
+	}
+	const { module: mods } = loaded;
+	const codemods = {
+		installed: true,
+		version: mods.VERSION ?? null,
+		install: null
+	};
+	const known = new Set(mods.transforms.map((t) => t.id));
+	const unknown = [...flags.codemods, ...flags.skipCodemods].filter((id) => !known.has(id));
+	if (unknown.length) throw new CliError("NOT_FOUND", `Unknown codemod(s): ${unknown.join(", ")}. Run gntik-ui upgrade --list.`);
+	const selected = mods.selectTransforms({
+		from: from ?? void 0,
+		to,
+		only: flags.codemods.length ? flags.codemods : void 0,
+		skip: flags.skipCodemods,
+		force: flags.codemods.length > 0
+	});
+	const selectedIds = new Set(selected.map((t) => t.id));
+	const fromLabel = from === null ? "any version" : typeof from === "string" ? from : Object.entries(from).map(([n, v]) => `${n}@${v}`).join(", ");
+	const header = `${CODEMODS_PACKAGE} ${codemods.version ?? "?"} · from ${fromLabel} → ${to}`;
+	if (flags.list) {
+		const rows = [[
+			"ID",
+			"PACKAGE",
+			"VERSIONS",
+			"SELECTED",
+			"KIND"
+		], ...mods.transforms.map((t) => [
+			t.id,
+			t.package,
+			`${t.fromVersion} → ${t.toVersion}`,
+			selectedIds.has(t.id) ? "yes" : "no",
+			t.reportOnly ? "report" : "rewrite"
+		])];
+		return ok({
+			dryRun,
+			from,
+			to,
+			codemods,
+			transforms: mods.transforms.map((t) => ({
+				...metaOut(t),
+				selected: selectedIds.has(t.id)
+			}))
+		}, [
+			header,
+			"",
+			...table(rows),
+			"",
+			...mods.transforms.map((t) => `${t.id}: ${t.description}`)
+		]);
+	}
+	const base = {
+		dryRun,
+		from,
+		to,
+		codemods,
+		transforms: selected.map(metaOut)
+	};
+	if (!selected.length) return ok({
+		...base,
+		scanned: 0,
+		files: [],
+		changed: [],
+		reports: [],
+		errors: []
+	}, [header, "No codemods apply to this upgrade."]);
+	const result = await mods.runCodemods({
+		cwd: ctx.cwd,
+		transforms: selected.map((t) => t.id),
+		dry: dryRun,
+		files: positionals.length ? positionals : void 0
+	});
+	const files = [...result.files].sort((a, b) => a.file.localeCompare(b.file));
+	const changed = files.filter((f) => f.status === "modified").map((f) => f.file);
+	const reports = files.flatMap((f) => f.reports.map((r) => ({
+		file: f.file,
+		line: r.line,
+		transform: r.transform,
+		message: r.message
+	})));
+	const errors = files.filter((f) => f.status === "error").map((f) => ({
+		file: f.file,
+		message: f.error ?? "failed"
+	}));
+	const data = {
+		...base,
+		scanned: result.scanned,
+		files,
+		changed,
+		reports,
+		errors
+	};
+	const text = [
+		header,
+		`Codemods: ${selected.map((t) => t.id).join(", ")}`,
+		`Scanned ${result.scanned} file(s).`
+	];
+	const verb = dryRun ? "Would modify" : "Modified";
+	if (changed.length) text.push("", `${verb} ${changed.length} file(s):`, ...files.filter((f) => f.status === "modified").map((f) => `  ${f.file} (${f.transforms.join(", ")})`));
+	else text.push("No files to change.");
+	if (reports.length) text.push("", `Warnings (${reports.length}):`, ...reports.map((r) => `  ${r.file}${r.line ? `:${r.line}` : ""} [${r.transform}] ${r.message}`));
+	if (errors.length) text.push("", `Errors (${errors.length}):`, ...errors.map((e) => `  ${e.file}: ${e.message}`));
+	if (dryRun && changed.length) text.push("", "Dry run: nothing was written. Re-run with --apply to write the changes.");
+	if (errors.length) return {
+		code: 1,
+		data,
+		text,
+		error: new CliError("ERROR", `${errors.length} file(s) could not be transformed`)
+	};
+	return ok(data, text);
+}
+//#endregion
+//#region src/help.ts
+const GLOBAL = `Global options:
+  --json              Machine-readable output on stdout (stable shape, see README)
+  --cwd <dir>         Project directory (default: current directory)
+  -r, --registry <p>  Registry: checkout dir, kit-registry.json path or base URL
+                      (default: $GNTIK_UI_REGISTRY, gntik-ui.json "registry", then GitHub main)
+  -y, --yes           Accepted for scripts; the CLI never prompts
+  -h, --help          Help for a command
+  -v, --version       Print the version
+
+Exit codes: 0 ok · 1 error (registry, install, codemods) · 2 usage · 3 unknown item · 4 file conflicts`;
+const HELP = {
+	main: `gntik-ui — add the gntik-ui design system to a product.
+
+Usage: gntik-ui <command> [options]
+
+Commands:
+  init               Set up a project (CSS imports, gntik-ui.json, packages)
+  add <id...>        Add components/layouts (npm) or copy blocks/templates into the project
+  eject <id>         Copy a component's source into the project so the team owns it
+  list               List registry items (--kind, --group)
+  search <query>     Fuzzy search on id, name, description and group
+  docs <id>          Show an item's description, files, dependencies and keyboard contract
+  upgrade [paths...] Run the codemods for @gntik-ai/* breaking changes (dry run unless --apply)
+
+${GLOBAL}`,
+	init: `Usage: gntik-ui init [--brand gntik|musematic|falcone] [--dry-run] [--no-install] [--overwrite]
+
+Detects the framework (Vite, Next, generic), package manager and CSS entry, then:
+  - puts @import "tailwindcss", the Geist fonts and "@gntik-ai/ui/styles.css" at the top of the CSS entry
+  - writes gntik-ui.json (aliases for components, blocks, templates; brand preset); kept if present
+    unless --overwrite
+  - prints the ThemeProvider + themeScript wiring for the framework
+  - installs @gntik-ai/ui @gntik-ai/tokens and the fonts (skipped with --no-install or --dry-run)
+
+${GLOBAL}`,
+	add: `Usage: gntik-ui add <id...> [--dry-run] [--overwrite] [--no-install]
+
+Components and layouts install from their npm package; the import line is printed.
+Blocks and templates are copied into the configured directories with their registry
+dependencies; imports are rewritten (relative between copied files, package imports for kit
+code). Existing files that differ are reported as conflicts and nothing is written unless
+--overwrite is given.
+
+${GLOBAL}`,
+	eject: `Usage: gntik-ui eject <id> [--no-deps] [--dry-run] [--overwrite] [--no-install]
+
+Copies the item's source (and its registry dependencies, unless --no-deps) into the components
+directory, rewrites imports, and lists the imports in the project to switch to the local copy.
+
+${GLOBAL}`,
+	list: `Usage: gntik-ui list [--kind component|layout|block|template] [--group <group>]
+
+${GLOBAL}`,
+	search: `Usage: gntik-ui search <query> [--kind <kind>] [--limit <n>]
+
+All terms must match (id, name, group or description); results are ranked.
+
+${GLOBAL}`,
+	docs: `Usage: gntik-ui docs <id>
+
+Prints description, status, package, files, dependencies and the keyboard table from the
+item's *.doc.ts file.
+
+${GLOBAL}`,
+	upgrade: `Usage: gntik-ui upgrade [paths...] [--from <v>] [--to <v>] [--codemod <id>...] [--skip-codemod <id>...]
+                         [--list] [--apply]
+
+Migrates the project's code across @gntik-ai/* breaking changes with the transforms in
+@gntik-ai/codemods, loaded from the project (install it with: pnpm add -D @gntik-ai/codemods).
+
+  --from <v>           Version upgrading from (default: the @gntik-ai/* versions in package.json;
+                       every codemod when none are declared)
+  --to <v>             Version upgrading to (default: latest)
+  --codemod <id>       Run only these codemods, whatever the versions (repeatable or comma-separated)
+  --skip-codemod <id>  Leave these out (repeatable or comma-separated)
+  --list               List the codemods and which ones this upgrade selects; changes nothing
+  --apply              Write the changes. Without it the run is dry: it reports the files it would
+                       change and the warnings (report-only codemods never write)
+  paths...             Files or directories to process (default: the project, without node_modules,
+                       dist, build, .next, …)
+
+Exit code 1 when @gntik-ai/codemods is missing (the install command is printed) or a file fails
+to parse.
+
+${GLOBAL}`
+};
+//#endregion
+//#region src/cli.ts
+const VERSION = version;
+const HANDLERS = {
+	init: (ctx) => init(ctx),
+	add,
+	eject,
+	list: (ctx) => list(ctx),
+	search,
+	docs,
+	upgrade
+};
+/** Runs the CLI and returns the exit code. Never calls process.exit. */
+async function run(argv, opts = {}) {
+	const stdout = opts.stdout ?? ((s) => process.stdout.write(s));
+	const stderr = opts.stderr ?? ((s) => process.stderr.write(s));
+	const invocationCwd = opts.cwd ?? process.cwd();
+	const wantsJson = argv.includes("--json");
+	let command = null;
+	const fail = (err) => {
+		if (wantsJson) stdout(`${JSON.stringify({
+			ok: false,
+			command,
+			error: {
+				code: err.code,
+				message: err.message
+			}
+		}, null, 2)}\n`);
+		else stderr(`gntik-ui: ${err.message}\n`);
+		return err.exitCode;
+	};
+	try {
+		const args = parseCliArgs(argv);
+		command = args.command ?? null;
+		const { flags } = args;
+		if (flags.version) {
+			stdout(flags.json ? `${JSON.stringify({
+				ok: true,
+				command: "version",
+				version: VERSION
+			})}\n` : `${VERSION}\n`);
+			return 0;
+		}
+		if (flags.help || !args.command) {
+			if (!flags.help && args.positionals.length) throw new CliError("USAGE", `Unknown command "${args.positionals[0]}"`);
+			const help = HELP[args.command ?? "main"];
+			stdout(flags.json ? `${JSON.stringify({
+				ok: true,
+				command: command ?? "help",
+				help
+			})}\n` : `${help}\n`);
+			return flags.help ? 0 : 2;
+		}
+		const ctx = {
+			cwd: path.resolve(invocationCwd, flags.cwd ?? "."),
+			invocationCwd,
+			flags,
+			exec: opts.exec ?? defaultExec,
+			env: opts.env ?? process.env
+		};
+		const result = await HANDLERS[args.command](ctx, args.positionals);
+		if (flags.json) {
+			const out = {
+				ok: result.code === 0,
+				command,
+				...result.data
+			};
+			if (result.error) out.error = {
+				code: result.error.code,
+				message: result.error.message
+			};
+			stdout(`${JSON.stringify(out, null, 2)}\n`);
+		} else {
+			if (result.text.length) stdout(`${result.text.join("\n")}\n`);
+			if (result.error) stderr(`gntik-ui: ${result.error.message}\n`);
+		}
+		return result.code;
+	} catch (e) {
+		if (e instanceof CliError) return fail(e);
+		return fail(new CliError("ERROR", e.message ?? String(e)));
+	}
+}
+//#endregion
+//#region src/index.ts
+process.exitCode = await run(process.argv.slice(2));
+//#endregion
+export {};