get-ui-cli 0.0.0-stage → 2.0.0

package/dist/core/transform.js

@@ -0,0 +1,148 @@
+// Source transforms: import rewriting for shadcn-style registry code and
+// Import rewriting and icon-placeholder transforms. Pure — no Node APIs.
+export const DEFAULT_ALIASES = {
+    components: '@/components',
+    ui: '@/components/ui',
+    utils: '@/lib/utils',
+    lib: '@/lib',
+    hooks: '@/hooks',
+};
+const SPECIFIER_RE = /(\bfrom\s*|\bimport\s*\(\s*|\bimport\s+|\brequire\s*\(\s*|\bjest\.mock\s*\(\s*)(['"])([^'"\n]+)\2/g;
+function stripExt(spec) {
+    return spec.replace(/\.(tsx?|jsx?|mjs|cjs)$/, '');
+}
+/**
+ * Map one module specifier from registry-internal form to the user's aliases.
+ * `fileMap` maps specifiers of files that are being installed (derived from their
+ * registry `path`/`target`) to where they will actually live.
+ */
+export function mapSpecifier(spec, aliases, fileMap = {}) {
+    const bare = stripExt(spec);
+    if (fileMap[spec])
+        return fileMap[spec];
+    if (fileMap[bare])
+        return fileMap[bare];
+    if (spec === 'cn' || spec === '@/lib/utils' || spec === '@/utils/cn')
+        return aliases.utils;
+    let m;
+    if ((m = bare.match(/^@\/registry\/(?:.+\/)?lib\/utils$/)))
+        return aliases.utils;
+    if ((m = bare.match(/^@\/registry\/(?:[^/]+\/)*?ui\/(.+)$/)))
+        return `${aliases.ui}/${m[1]}`;
+    if ((m = bare.match(/^@\/registry\/(?:[^/]+\/)*?hooks\/(.+)$/)))
+        return `${aliases.hooks}/${m[1]}`;
+    if ((m = bare.match(/^@\/registry\/(?:[^/]+\/)*?lib\/(.+)$/)))
+        return `${aliases.lib}/${m[1]}`;
+    if ((m = bare.match(/^@\/registry\/(?:[^/]+\/)*?(?:components|blocks|examples?)\/(.+)$/)))
+        return `${aliases.components}/${m[1]}`;
+    // e.g. `@/registry/magicui/marquee` — library-flat registries ship registry:ui files.
+    if ((m = bare.match(/^@\/registry\/[^/]+\/(.+)$/)))
+        return `${aliases.ui}/${m[1]}`;
+    if ((m = spec.match(/^@\/components\/ui\/(.+)$/)))
+        return `${aliases.ui}/${m[1]}`;
+    if ((m = spec.match(/^@\/components\/(.+)$/)))
+        return `${aliases.components}/${m[1]}`;
+    if ((m = spec.match(/^@\/hooks\/(.+)$/)))
+        return `${aliases.hooks}/${m[1]}`;
+    if ((m = spec.match(/^@\/lib\/(.+)$/)))
+        return `${aliases.lib}/${m[1]}`;
+    return spec;
+}
+/** Rewrite all import/export/require specifiers in `code`. */
+export function rewriteImports(code, aliases, fileMap = {}) {
+    return code.replace(SPECIFIER_RE, (_all, lead, quote, spec) => {
+        return `${lead}${quote}${mapSpecifier(spec, aliases, fileMap)}${quote}`;
+    });
+}
+/** List module specifiers imported by `code`. */
+export function listImports(code) {
+    const out = new Set();
+    for (const m of code.matchAll(SPECIFIER_RE))
+        out.add(m[3]);
+    return [...out];
+}
+// ---------------------------------------------------------------------------
+// shadcn "IconPlaceholder" (base-* styles / ReUI) -> concrete lucide-react icons
+// ---------------------------------------------------------------------------
+const ICON_LIB_ATTRS = ['lucide', 'tabler', 'hugeicons', 'phosphor', 'remixicon'];
+/** Find the end index (exclusive) of a JSX opening tag starting at `start` (`<`). */
+function jsxTagEnd(code, start) {
+    let depth = 0;
+    let quote = null;
+    for (let i = start + 1; i < code.length; i++) {
+        const ch = code[i];
+        if (quote) {
+            if (ch === '\\')
+                i++;
+            else if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === '`')
+            quote = ch;
+        else if (ch === '{')
+            depth++;
+        else if (ch === '}')
+            depth--;
+        else if (depth === 0 && ch === '/' && code[i + 1] === '>')
+            return { end: i + 2, selfClosing: true };
+        else if (depth === 0 && ch === '>')
+            return { end: i + 1, selfClosing: false };
+    }
+    return null;
+}
+/**
+ * Replace `<IconPlaceholder lucide="CheckIcon" tabler="…" … />` with `<CheckIcon … />`
+ * and swap the placeholder import for a lucide-react import.
+ */
+export function transformIconPlaceholders(code) {
+    if (!code.includes('IconPlaceholder'))
+        return code;
+    const icons = new Set();
+    let out = '';
+    let i = 0;
+    const re = /<IconPlaceholder\b/g;
+    let m;
+    while ((m = re.exec(code))) {
+        const tag = jsxTagEnd(code, m.index);
+        if (!tag)
+            break;
+        let attrs = code.slice(m.index + '<IconPlaceholder'.length, tag.selfClosing ? tag.end - 2 : tag.end - 1);
+        const lucide = attrs.match(/\blucide=(?:"([^"]+)"|\{\s*["']([^"']+)["']\s*\})/);
+        const name = lucide?.[1] ?? lucide?.[2] ?? 'CircleIcon';
+        icons.add(name);
+        for (const a of ICON_LIB_ATTRS)
+            attrs = attrs.replace(new RegExp(`\\s*\\b${a}=(?:"[^"]*"|\\{[^}]*\\})`, 'g'), '');
+        out += code.slice(i, m.index) + `<${name}${attrs}${tag.selfClosing ? '/>' : '>'}`;
+        i = tag.end;
+        re.lastIndex = tag.end;
+    }
+    out += code.slice(i);
+    out = out.replace(/<\/IconPlaceholder>/g, () => `</${[...icons][0] ?? 'CircleIcon'}>`);
+    // Names already imported from lucide-react.
+    const existing = new Set();
+    for (const im of out.matchAll(/import\s*\{([^}]*)\}\s*from\s*["']lucide-react["']/g))
+        for (const n of im[1].split(','))
+            existing.add(n.trim().split(/\s+as\s+/).pop().trim());
+    const needed = [...icons].filter((n) => !existing.has(n)).sort();
+    const lucideImport = needed.length ? `import { ${needed.join(', ')} } from "lucide-react"` : '';
+    const importRe = /import\s*\{\s*IconPlaceholder\s*\}\s*from\s*["'][^"']+["'];?/;
+    if (importRe.test(out))
+        out = out.replace(importRe, lucideImport);
+    else if (lucideImport)
+        out = `${lucideImport}\n${out}`;
+    return out;
+}
+/**
+ * React 19's types dropped the global `JSX` namespace, so `JSX.Element` in older
+ * components fails to type-check. Import the namespace from react where it's used.
+ */
+export function importJsxNamespace(code) {
+    if (!/(?<![\w.$])JSX\./.test(code))
+        return code;
+    if (/\bimport\b[^;]*?\bJSX\b[^;]*?\bfrom\s*['"]react['"]/.test(code))
+        return code;
+    const line = 'import type { JSX } from "react";\n';
+    const directive = code.match(/^\s*(['"])use (?:client|server)\1;?[^\n]*\n/);
+    return directive ? code.slice(0, directive[0].length) + line + code.slice(directive[0].length) : line + code;
+}

package/dist/core/versions.d.ts

@@ -0,0 +1,3 @@
+export declare const KNOWN_MAJORS: Record<string, string>;
+/** `motion` → `motion@12`; a dependency that already names a version is left alone. */
+export declare function withKnownMajor(dep: string): string;

package/dist/core/versions.js

@@ -0,0 +1,44 @@
+// Major versions the indexed components were written for. When a project doesn't
+// have one of these packages yet, get-ui installs this major instead of whatever
+// is newest (motion 14 and lucide-react 1.x, for example, break components written
+// for motion 12 and lucide 0.x). Keep in step with the exact pins the website's
+// live previews use (web/src/lib/preview/build.ts, PINS), so what you preview is
+// what you install. Pure.
+import { packageName } from './resolve.js';
+export const KNOWN_MAJORS = {
+    motion: '12',
+    'framer-motion': '12',
+    'lucide-react': '0',
+    'date-fns': '4',
+    '@base-ui/react': '1',
+    '@tanstack/react-table': '9',
+    '@tanstack/react-virtual': '3',
+    sonner: '2',
+    'radix-ui': '1',
+    '@radix-ui/react-slot': '1',
+    '@radix-ui/react-use-controllable-state': '1',
+    'class-variance-authority': '0',
+    clsx: '2',
+    'tailwind-merge': '3',
+    recharts: '3',
+    '@tabler/icons-react': '3',
+    'react-day-picker': '9',
+    'react-use-measure': '2',
+    'next-themes': '0',
+    '@dnd-kit/core': '6',
+    '@dnd-kit/sortable': '10',
+    '@dnd-kit/utilities': '3',
+    'input-otp': '1',
+    'embla-carousel-react': '8',
+    'embla-carousel-autoplay': '8',
+    vaul: '1',
+    cobe: '0',
+    gsap: '3',
+};
+/** `motion` → `motion@12`; a dependency that already names a version is left alone. */
+export function withKnownMajor(dep) {
+    if (packageName(dep) !== dep)
+        return dep;
+    const major = KNOWN_MAJORS[dep];
+    return major ? `${dep}@${major}` : dep;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+import { autocomplete, cancel, confirm, intro, isCancel, log, note, outro, select, spinner } from '@clack/prompts';
+import { Command } from 'commander';
+import fs from 'node:fs';
+import path from 'node:path';
+import pc from 'picocolors';
+import { findExact, searchItems, searchItemsScored } from './core/search.js';
+import { resolveItem } from './core/resolve.js';
+import { LIBRARIES } from './registry-types.js';
+import { detectProject } from './node/project.js';
+import { loadRegistry } from './node/registry.js';
+import { UTILS_SOURCE, installCommand, planInstall, runCommand, writePlan } from './node/install.js';
+const VERSION = '2.0.0';
+// Where `Preview:` links point; override for self-hosted or preview deployments.
+const PREVIEW_BASE = `${(process.env.GET_UI_SITE ?? 'https://get-ui.dev').replace(/\/+$/, '')}/c/`;
+const interactive = () => !!process.stdin.isTTY && !!process.stdout.isTTY && !process.env.CI;
+/**
+ * Auth for paid registries (Aceternity Pro, ReUI Pro…): GET_UI_TOKEN_<LIBRARY> (e.g.
+ * GET_UI_TOKEN_REUI, GET_UI_TOKEN_ACETERNITY) or REUI_LICENSE_KEY / ACETERNITY_API_KEY.
+ */
+function tokenEnvNames(libraryId) {
+    const id = libraryId.toUpperCase().replace(/[^A-Z0-9]+/g, '_');
+    return [`GET_UI_TOKEN_${id}`, ...(id === 'REUI' ? ['REUI_LICENSE_KEY'] : []), ...(id === 'ACETERNITY' ? ['ACETERNITY_API_KEY'] : [])];
+}
+function makeAuthHeaders(registry) {
+    return (url) => {
+        for (const lib of Object.values(registry.libraries)) {
+            if (!lib.itemBase || new URL(url).host !== new URL(lib.itemBase).host)
+                continue;
+            const token = tokenEnvNames(lib.id).map((n) => process.env[n]).find(Boolean);
+            if (token)
+                return { Authorization: `Bearer ${token}` };
+        }
+        return undefined;
+    };
+}
+function explainFailure(item, msg) {
+    if (/\b(401|403)\b|Authentication required|Unauthorized/i.test(msg))
+        return `${item.id} is a paid/pro component. Set ${tokenEnvNames(item.library)[0]} to your ${item.library} licence key / API token to install it.`;
+    return `${item.id}: ${msg}`;
+}
+function label(item) {
+    const lib = item.library;
+    return `${item.title}  ${pc.dim(`[${lib} · ${item.category}]`)}${item.pro ? ` ${pc.yellow('Pro')}` : ''}`;
+}
+function bail(msg) {
+    cancel(msg);
+    process.exit(1);
+}
+function truncate(s, n) {
+    return s.length > n ? s.slice(0, n - 1) + '…' : s;
+}
+function table(rows, header) {
+    const all = [header, ...rows];
+    const widths = header.map((_, i) => Math.max(...all.map((r) => r[i].length)));
+    const fmt = (r) => r.map((c, i) => c.padEnd(widths[i])).join('  ').trimEnd();
+    return [pc.bold(fmt(header)), pc.dim(widths.map((w) => '─'.repeat(w)).join('  ')), ...rows.map(fmt)].join('\n');
+}
+async function getRegistry(quiet = false) {
+    const s = quiet ? null : spinner();
+    s?.start('Loading component index…');
+    try {
+        const { registry, source } = await loadRegistry();
+        const pro = registry.items.filter((i) => i.pro).length;
+        const free = registry.items.length - pro;
+        s?.stop(`Loaded ${pc.bold(free.toLocaleString('en-US'))} components${pro ? ` (+${pro.toLocaleString('en-US')} Pro)` : ''} ${pc.dim(`(${source})`)}`);
+        return registry;
+    }
+    catch (e) {
+        s?.stop(pc.red('Failed to load the component index.'));
+        throw e;
+    }
+}
+/** Turn a user query into a registry item (exact match, or interactive pick). */
+async function pickItem(registry, query, opts) {
+    const items = registry.items;
+    if (query) {
+        const exact = findExact(items, query, opts.library);
+        if (exact)
+            return exact;
+    }
+    const results = query ? searchItemsScored(items, query, { library: opts.library, limit: 15 }) : [];
+    // Paid items need a licence key; rank free ones first (stable sort keeps relevance order).
+    results.sort((a, b) => Number(!!a.item.pro) - Number(!!b.item.pro));
+    if (query && !results.length)
+        bail(`No components match "${query}". Try ${pc.cyan('get-ui search <text>')}.`);
+    if (!interactive() || opts.yes) {
+        if (!query)
+            bail('No component given. Pass an id, e.g. `get-ui add magicui/marquee`.');
+        const top = results[0].item;
+        log.info(`"${query}" → ${pc.cyan(top.id)} ${pc.dim(`(best match of ${results.length})`)}`);
+        return top;
+    }
+    const toOption = (i) => ({ value: i.id, label: label(i), hint: i.id });
+    const choice = await autocomplete({
+        message: query ? `Pick a component matching "${query}"` : 'Search for a component',
+        initialUserInput: query ?? '',
+        maxItems: 15,
+        options: function () {
+            const q = (this.userInput ?? '').trim();
+            const list = q ? searchItems(items, q, { library: opts.library, limit: 15 }) : items.filter((i) => !opts.library || i.library === opts.library).slice(0, 15);
+            return list.map(toOption);
+        },
+    });
+    if (isCancel(choice))
+        bail('Cancelled.');
+    const item = items.find((i) => i.id === choice);
+    if (!item)
+        bail('Nothing selected.');
+    return item;
+}
+function printPlan(plan, results, pm) {
+    const lines = [];
+    for (const { item, result } of results) {
+        lines.push(`${pc.bold(pc.cyan(item.id))}${result.tree.length > 1 ? pc.dim(`  + ${result.tree.slice(1).join(', ')}`) : ''}`);
+    }
+    lines.push('');
+    lines.push(pc.bold('Files'));
+    for (const f of plan.files) {
+        const tag = f.kind === 'css' ? pc.magenta('merge ') : f.status === 'new' ? pc.green('create') : f.status === 'identical' ? pc.dim('same  ') : pc.yellow('exists');
+        lines.push(`  ${tag} ${f.rel}${f.note ? pc.dim(`  (${truncate(f.note, 90)})`) : ''}`);
+    }
+    if (!plan.files.length)
+        lines.push(pc.dim('  (none)'));
+    if (plan.dependencies.length || plan.devDependencies.length) {
+        lines.push('');
+        lines.push(pc.bold(`Packages (${pm})`));
+        if (plan.dependencies.length)
+            lines.push(`  ${plan.dependencies.join(' ')}`);
+        if (plan.devDependencies.length)
+            lines.push(`  ${pc.dim('dev:')} ${plan.devDependencies.join(' ')}`);
+    }
+    note(lines.join('\n'), 'Install plan');
+    for (const w of plan.warnings)
+        log.warn(w);
+}
+async function addCommand(queries, opts) {
+    console.log();
+    intro(pc.bgCyan(pc.black(' get-ui ')));
+    const cwd = path.resolve(opts.cwd);
+    if (!fs.existsSync(cwd))
+        bail(`Directory not found: ${cwd}`);
+    if (!fs.existsSync(path.join(cwd, 'package.json')))
+        log.warn(`No package.json in ${cwd} — files will still be written, but packages can't be installed.`);
+    const registry = await getRegistry();
+    const picked = [];
+    for (const q of queries.length ? queries : [undefined]) {
+        const item = await pickItem(registry, q, opts);
+        if (!picked.some((p) => p.id === item.id))
+            picked.push(item);
+    }
+    const s = spinner();
+    s.start(`Resolving ${picked.map((p) => p.id).join(', ')}…`);
+    const cache = new Map();
+    const settled = await Promise.allSettled(picked.map((item) => resolveItem(registry, item, { cache, headers: makeAuthHeaders(registry) })));
+    const results = [];
+    const failures = [];
+    settled.forEach((r, i) => {
+        if (r.status === 'rejected')
+            return failures.push(explainFailure(picked[i], r.reason?.message ?? String(r.reason)));
+        // A dependency that didn't download would leave a half-installed component; install none of it.
+        const missing = r.value.warnings.filter((w) => /^Could not fetch|requires authentication|^Unknown registry namespace/.test(w));
+        if (missing.length)
+            return failures.push(`${picked[i].id}: ${missing.join('; ')}. Nothing was installed for it — try again in a moment.`);
+        results.push({ item: picked[i], result: r.value });
+    });
+    if (!results.length) {
+        s.stop(pc.red('Resolution failed.'));
+        bail(failures.join('\n'));
+    }
+    const total = results.reduce((n, r) => n + r.result.files.length, 0);
+    s.stop(`Resolved ${total} file${total === 1 ? '' : 's'} from ${results.reduce((n, r) => n + r.result.tree.length, 0)} registry item(s).`);
+    for (const f of failures)
+        log.error(`Skipped — ${f}`);
+    const project = detectProject(cwd);
+    const plan = planInstall(results.map((r) => r.result), project);
+    log.info(pc.dim(`Project: ${project.hasSrc ? 'src/, ' : ''}alias ${project.aliasPrefix ?? '(relative imports)'}, Tailwind ${project.tailwind.version ?? '?'}${project.tailwind.css ? `, css ${path.relative(cwd, project.tailwind.css)}` : ''}, ${project.packageManager}`));
+    printPlan(plan, results, project.packageManager);
+    const cmds = [
+        plan.dependencies.length ? installCommand(project.packageManager, plan.dependencies) : null,
+        plan.devDependencies.length ? installCommand(project.packageManager, plan.devDependencies, true) : null,
+    ].filter((c) => !!c);
+    if (opts.dryRun) {
+        if (cmds.length)
+            log.info(`Would run: ${cmds.map((c) => pc.cyan(c.join(' '))).join(' && ')}`);
+        outro(pc.yellow('Dry run — nothing was written.'));
+        return;
+    }
+    if (!opts.yes && interactive()) {
+        const ok = await confirm({ message: 'Write these files?' });
+        if (isCancel(ok) || !ok)
+            bail('Cancelled.');
+    }
+    const written = await writePlan(plan, async (file) => {
+        if (opts.overwrite)
+            return 'overwrite';
+        if (opts.yes || !interactive())
+            return 'skip';
+        const answer = await select({
+            message: `${file.rel} already exists and differs. What should I do?`,
+            options: [
+                { value: 'skip', label: 'Keep mine (skip)' },
+                { value: 'overwrite', label: 'Overwrite' },
+            ],
+        });
+        if (isCancel(answer))
+            bail('Cancelled.');
+        return answer;
+    });
+    for (const f of written.written)
+        log.success(`${f.kind === 'css' ? 'Updated' : 'Wrote'} ${pc.cyan(f.rel)}`);
+    for (const f of written.skipped)
+        log.warn(`Skipped ${f.rel} (exists — use --overwrite to replace)`);
+    if (written.unchanged.length)
+        log.info(pc.dim(`${written.unchanged.length} file(s) already up to date.`));
+    let packagesFailed = false;
+    if (cmds.length) {
+        if (!opts.install || !project.hasPackageJson) {
+            log.info(`Install packages with: ${cmds.map((c) => pc.cyan(c.join(' '))).join(' && ')}`);
+        }
+        else {
+            for (const cmd of cmds) {
+                const sp = spinner();
+                sp.start(`Running ${cmd.join(' ')}`);
+                try {
+                    await runCommand(cmd, cwd);
+                    sp.stop(`Installed ${cmd.slice(2).filter((a) => !a.startsWith('-')).join(', ')}`);
+                }
+                catch (e) {
+                    packagesFailed = true;
+                    sp.stop(pc.red('Package install failed.'));
+                    log.error(e.message);
+                    log.info(`Run it yourself: ${pc.cyan(cmd.join(' '))}`);
+                }
+            }
+        }
+    }
+    for (const { item } of results)
+        log.message(`${pc.dim('Preview:')} ${pc.underline(PREVIEW_BASE + item.id)}`);
+    const ready = results.map((r) => r.item.title).join(', ');
+    if (failures.length || packagesFailed) {
+        process.exitCode = 1;
+        outro(pc.yellow(packagesFailed ? `Files written for ${ready}, but packages didn't install (see above).` : `${ready} ready to use; ${failures.length} not installed (see above).`));
+        return;
+    }
+    outro(pc.green(`Done! ${ready} ready to use.`));
+}
+const program = new Command();
+program.name('get-ui').description('Install components from shadcn/ui, Magic UI, Aceternity, ReUI, Kokonut UI, Cult UI, Motion Primitives, Unlumen UI and Amicro.').version(VERSION);
+program
+    .command('add [queries...]', { isDefault: true })
+    .description('Add one or more components (id like magicui/marquee, a name, or free text)')
+    .option('-y, --yes', 'skip prompts; pick the best match; keep existing files')
+    .option('-o, --overwrite', 'overwrite existing files')
+    .option('--dry-run', 'show what would be written / installed without changing anything')
+    .option('--cwd <dir>', 'project directory', process.cwd())
+    .option('-l, --library <id>', `restrict matches to a library (${Object.keys(LIBRARIES).join(', ')})`)
+    .option('--no-install', 'do not run the package manager; print the command instead')
+    .action(async (queries, opts) => {
+    await addCommand(queries ?? [], opts);
+});
+program
+    .command('search <query...>')
+    .description('Search the component index')
+    .option('-l, --library <id>', 'filter by library')
+    .option('-c, --category <name>', 'filter by category')
+    .option('-n, --limit <n>', 'number of results', '20')
+    .action(async (query, opts) => {
+    const registry = await getRegistry(true);
+    const results = searchItems(registry.items, query.join(' '), { library: opts.library, category: opts.category, limit: Number(opts.limit) || 20 });
+    if (!results.length) {
+        console.log(pc.yellow(`No components match "${query.join(' ')}".`));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(table(results.map((i) => [i.id, truncate(i.title, 48), i.library, i.category]), ['ID', 'TITLE', 'LIBRARY', 'CATEGORY']));
+    console.log(pc.dim(`\nInstall with: npx get-ui-cli add ${results[0].id}`));
+});
+program
+    .command('list')
+    .description('Show counts per library / category, or list items')
+    .option('-l, --library <id>', 'filter by library')
+    .option('-c, --category <name>', 'filter by category (lists items)')
+    .action(async (opts) => {
+    const registry = await getRegistry(true);
+    let items = registry.items;
+    if (opts.library)
+        items = items.filter((i) => i.library === opts.library);
+    if (opts.category)
+        items = items.filter((i) => i.category.toLowerCase() === opts.category.toLowerCase());
+    if (!items.length) {
+        console.log(pc.yellow('No components match those filters.'));
+        process.exitCode = 1;
+        return;
+    }
+    if (opts.category) {
+        console.log(table(items.map((i) => [i.id, truncate(i.title, 56), i.library]), ['ID', 'TITLE', 'LIBRARY']));
+        console.log(pc.dim(`\n${items.length} components`));
+        return;
+    }
+    const key = opts.library ? (i) => i.category : (i) => i.library;
+    const counts = new Map();
+    for (const i of items)
+        counts.set(key(i), (counts.get(key(i)) ?? 0) + 1);
+    const rows = [...counts.entries()].sort((a, b) => b[1] - a[1]).map(([k, n]) => [k, String(n), opts.library ? '' : registry.libraries[k]?.name ?? '']);
+    console.log(table(rows, [opts.library ? 'CATEGORY' : 'LIBRARY', 'COUNT', opts.library ? '' : 'NAME']));
+    console.log(pc.dim(`\n${items.length} components. Use --library / --category to drill down.`));
+});
+program
+    .command('view <id>')
+    .description('Show metadata, files and dependencies for a component (no writes)')
+    .option('--cwd <dir>', 'project directory (used to show target paths)', process.cwd())
+    .action(async (id, opts) => {
+    const registry = await getRegistry(true);
+    const item = findExact(registry.items, id) ?? searchItems(registry.items, id, { limit: 1 })[0];
+    if (!item) {
+        console.log(pc.red(`No component "${id}".`));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`${pc.bold(item.title)} ${pc.dim(item.id)}`);
+    if (item.description)
+        console.log(item.description);
+    console.log(pc.dim(`${registry.libraries[item.library]?.name ?? item.library} · ${item.category} · ${item.kind} · ${item.format}${item.author ? ` · by ${item.author}` : ''}`));
+    console.log(`Docs:    ${item.docs}`);
+    console.log(`Source:  ${item.source}`);
+    console.log(`Preview: ${PREVIEW_BASE}${item.id}\n`);
+    let result;
+    try {
+        result = await resolveItem(registry, item, { headers: makeAuthHeaders(registry) });
+    }
+    catch (e) {
+        console.log(pc.red(explainFailure(item, e.message)));
+        process.exitCode = 1;
+        return;
+    }
+    const project = detectProject(opts.cwd);
+    const plan = planInstall([result], project);
+    if (result.tree.length > 1)
+        console.log(`${pc.bold('Pulls in:')} ${result.tree.slice(1).join(', ')}`);
+    console.log(pc.bold('Files:'));
+    for (const f of plan.files)
+        console.log(`  ${f.kind === 'css' ? pc.magenta('merge') : '     '} ${f.rel}${f.note ? pc.dim(`  (${truncate(f.note, 80)})`) : ''}`);
+    const deps = result.dependencies;
+    console.log(`${pc.bold('Dependencies:')} ${deps.length ? deps.join(' ') : pc.dim('none')}`);
+    if (result.devDependencies.length)
+        console.log(`${pc.bold('Dev dependencies:')} ${result.devDependencies.join(' ')}`);
+    for (const w of result.warnings)
+        console.log(pc.yellow(`! ${w}`));
+    console.log(pc.dim(`\nInstall with: npx get-ui-cli add ${item.id}`));
+});
+program
+    .command('init')
+    .description('Create lib/utils.ts (cn helper) and install clsx + tailwind-merge')
+    .option('--cwd <dir>', 'project directory', process.cwd())
+    .option('--no-install', 'do not run the package manager')
+    .action(async (opts) => {
+    intro(pc.bgCyan(pc.black(' get-ui init ')));
+    const project = detectProject(opts.cwd);
+    if (fs.existsSync(project.utilsFile))
+        log.info(`${path.relative(project.cwd, project.utilsFile)} already exists.`);
+    else {
+        fs.mkdirSync(path.dirname(project.utilsFile), { recursive: true });
+        fs.writeFileSync(project.utilsFile, UTILS_SOURCE);
+        log.success(`Created ${pc.cyan(path.relative(project.cwd, project.utilsFile))}`);
+    }
+    const missing = ['clsx', 'tailwind-merge'].filter((d) => !project.installed.has(d));
+    if (missing.length) {
+        const cmd = installCommand(project.packageManager, missing);
+        if (!opts.install || !project.hasPackageJson)
+            log.info(`Install packages with: ${pc.cyan(cmd.join(' '))}`);
+        else {
+            const s = spinner();
+            s.start(`Running ${cmd.join(' ')}`);
+            try {
+                await runCommand(cmd, project.cwd);
+                s.stop(`Installed ${missing.join(', ')}`);
+            }
+            catch (e) {
+                s.stop(pc.red('Install failed'));
+                log.error(e.message);
+            }
+        }
+    }
+    outro(pc.green(`Ready. Try ${pc.cyan('npx get-ui-cli add magicui/marquee')}`));
+});
+program.parseAsync().catch((e) => {
+    console.error(pc.red(e instanceof Error ? e.message : String(e)));
+    process.exit(1);
+});

package/dist/node/install.d.ts

@@ -0,0 +1,43 @@
+import { type ResolveResult, type ResolvedFile } from '../core/resolve.js';
+import type { PackageManager, ProjectConfig } from './project.js';
+export declare const UTILS_SOURCE = "import { clsx, type ClassValue } from \"clsx\"\nimport { twMerge } from \"tailwind-merge\"\n\nexport function cn(...inputs: ClassValue[]) {\n  return twMerge(clsx(inputs))\n}\n";
+export type FileStatus = 'new' | 'identical' | 'modified';
+export interface PlannedFile {
+    abs: string;
+    /** Path relative to the project root, for display. */
+    rel: string;
+    content: string;
+    status: FileStatus;
+    /** Registry item the file came from (or `get-ui` for generated files). */
+    item: string;
+    /** CSS merges are applied without prompting (they never remove anything). */
+    kind: 'file' | 'css';
+    note?: string;
+}
+export interface InstallPlan {
+    files: PlannedFile[];
+    dependencies: string[];
+    devDependencies: string[];
+    warnings: string[];
+}
+export declare function destinationFor(file: ResolvedFile, project: ProjectConfig): string;
+/**
+ * An existing file at the destination that this file can't replace or reuse:
+ * - the same primitive in the other flavour (Radix vs Base UI `button.tsx`);
+ * - a different component with the same name (two libraries' `carousel.tsx`);
+ * - a version missing something the incoming one offers (a `size` prop, a badge
+ *   `success` variant) that the components being installed are likely to use.
+ * A user's styling edits keep the API, so their file is reused as before.
+ */
+export declare function clashes(existing: string, incoming: string): boolean;
+/** Compute everything that would be written / installed, without touching disk. */
+export declare function planInstall(results: ResolveResult[], project: ProjectConfig): InstallPlan;
+export type ConflictDecision = 'overwrite' | 'skip';
+export interface WriteResult {
+    written: PlannedFile[];
+    skipped: PlannedFile[];
+    unchanged: PlannedFile[];
+}
+export declare function writePlan(plan: InstallPlan, onConflict: (file: PlannedFile) => Promise<ConflictDecision>): Promise<WriteResult>;
+export declare function installCommand(pm: PackageManager, deps: string[], dev?: boolean): string[];
+export declare function runCommand(cmd: string[], cwd: string): Promise<void>;