uipkge-ng 0.1.0

package/dist/commands/build.js

@@ -0,0 +1,121 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import * as path from 'node:path';
+import { UipkgeError } from '../errors.js';
+import { color, log, plural } from '../output.js';
+import { DEFAULT_REGISTRY_URL, refKind } from '../registry.js';
+const ITEM_SCHEMA = 'https://uipkge.dev/schema/registry-item.json';
+const NAME = /^[a-z0-9][a-z0-9-]*$/;
+/** Everything wrong with a registry source, as `where: problem` lines. Files are checked against `root`. */
+export function validateRegistry(source, root) {
+    const problems = [];
+    if (!source || typeof source !== 'object' || !Array.isArray(source.items)) {
+        return ['registry: needs an "items" array'];
+    }
+    const { name, items } = source;
+    if (typeof name !== 'string' || !name)
+        problems.push('registry: needs a "name"');
+    const own = new Set(items.map(i => i?.name));
+    const seen = new Set();
+    items.forEach((item, i) => {
+        const where = typeof item?.name === 'string' && item.name ? `items.${item.name}` : `items[${i}]`;
+        if (typeof item?.name !== 'string' || !NAME.test(item.name)) {
+            problems.push(`${where}: "name" must be lowercase letters, digits and dashes`);
+        }
+        else if (seen.has(item.name)) {
+            problems.push(`${where}: duplicate name`);
+        }
+        else if (item.name === 'registry') {
+            // registry.json is the index; an item called "registry" would overwrite it.
+            problems.push(`${where}: "registry" is reserved for the index`);
+        }
+        if (typeof item?.name === 'string')
+            seen.add(item.name);
+        if (!Array.isArray(item?.files)) {
+            problems.push(`${where}: needs a "files" array`);
+        }
+        else {
+            item.files.forEach((file, j) => {
+                const at = `${where}.files[${j}]`;
+                if (typeof file?.path !== 'string' || !file.path)
+                    return void problems.push(`${at}: needs a "path"`);
+                const abs = path.resolve(root, file.path);
+                if (path.relative(root, abs).startsWith('..') || path.isAbsolute(file.path)) {
+                    problems.push(`${at}: path "${file.path}" is outside ${root}`);
+                }
+                else if (file.content === undefined && !existsSync(abs)) {
+                    problems.push(`${at}: file "${file.path}" not found`);
+                }
+                if (file.target !== undefined) {
+                    const target = String(file.target).replace(/^~\//, '');
+                    if (path.isAbsolute(target) || path.normalize(target).startsWith('..')) {
+                        problems.push(`${at}: target "${file.target}" must stay inside the project`);
+                    }
+                }
+            });
+        }
+        for (const key of ['dependencies', 'devDependencies']) {
+            const list = item?.[key];
+            if (list !== undefined && (!Array.isArray(list) || list.some(d => typeof d !== 'string' || !d.trim()))) {
+                problems.push(`${where}: "${key}" must be a list of package names`);
+            }
+        }
+        const deps = item?.registryDependencies;
+        if (deps !== undefined) {
+            if (!Array.isArray(deps))
+                problems.push(`${where}: "registryDependencies" must be a list`);
+            else
+                for (const dep of deps) {
+                    // Local files resolve against the installer's machine, not the registry — never valid in a published item.
+                    if (typeof dep !== 'string' || refKind(dep) === 'file') {
+                        problems.push(`${where}: registry dependency "${dep}" must be a name, @registry/name or an item URL`);
+                    }
+                    else if (refKind(dep) === 'name' && own.has(dep)) {
+                        // Bare names mean uipkge components; an item of this registry needs a form that says so.
+                        problems.push(`${where}: "${dep}" is an item of this registry — depend on it as @<registry>/${dep} or by URL`);
+                    }
+                }
+        }
+    });
+    return problems;
+}
+export async function runBuild(options) {
+    const root = path.resolve(options.cwd);
+    const sourceFile = path.resolve(root, options.registry);
+    if (!existsSync(sourceFile)) {
+        throw new UipkgeError(`No registry file at ${sourceFile}.`, 'Pass its path: `uipkge-ng build path/to/registry.json`.');
+    }
+    let source;
+    try {
+        source = JSON.parse(await readFile(sourceFile, 'utf8'));
+    }
+    catch (error) {
+        throw new UipkgeError(`${options.registry} is not valid JSON: ${error.message}`);
+    }
+    const problems = validateRegistry(source, root);
+    if (problems.length) {
+        throw new UipkgeError(`${options.registry} has ${plural(problems.length, 'problem')}:\n${problems.map(p => `  • ${p}`).join('\n')}`, 'Nothing was written.');
+    }
+    // Read everything before writing anything, so a failure leaves the output untouched.
+    const built = await Promise.all(source.items.map(async (item) => ({
+        $schema: ITEM_SCHEMA,
+        ...item,
+        // Bare names are uipkge components: pin them to uipkge so they resolve the same in every project.
+        ...(item.registryDependencies && {
+            registryDependencies: item.registryDependencies.map(d => (refKind(d) === 'name' ? `${DEFAULT_REGISTRY_URL}/${d}.json` : d)),
+        }),
+        files: await Promise.all(item.files.map(async (f) => ({ ...f, content: f.content ?? (await readFile(path.resolve(root, f.path), 'utf8')) }))),
+    })));
+    const outDir = path.resolve(root, options.output);
+    await mkdir(outDir, { recursive: true });
+    for (const item of built)
+        await writeFile(path.join(outDir, `${item.name}.json`), `${JSON.stringify(item, null, 2)}\n`, 'utf8');
+    // The index lists files without their content, like the uipkge registry does.
+    const index = { ...source, items: source.items.map(item => ({ ...item, files: item.files.map(({ content: _c, ...f }) => f) })) };
+    await writeFile(path.join(outDir, 'registry.json'), `${JSON.stringify(index, null, 2)}\n`, 'utf8');
+    const rel = path.relative(root, outDir) || '.';
+    log.success(`Built ${plural(built.length, 'item')} into ${rel}/`);
+    for (const item of built)
+        log.info(`  ${color.green('✔')} ${item.name}.json ${color.dim(`(${plural(item.files.length, 'file')})`)}`);
+    log.info(color.dim(`Serve ${rel}/ and use "https://<host>/<path>/{name}.json" under "registries" in components.json.`));
+}

package/dist/commands/diff.js

@@ -0,0 +1,140 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import * as path from 'node:path';
+import { createTwoFilesPatch } from 'diff';
+import { registryFor, requireConfig } from '../config.js';
+import { isItemInstalled, targetedFiles, normalizeEol } from '../files.js';
+import { adaptItem, resolveLayout } from '../layout.js';
+import { color, log, plural } from '../output.js';
+import { loadProject, resolveTarget } from '../project.js';
+import { refKind } from '../registry.js';
+import { assertKnownNames } from '../resolve.js';
+/** CRLF/LF differences are checkout noise, not changes. */
+export { normalizeEol };
+/** Compares each of the item's files on disk with the registry's copy. */
+export async function compareItem(root, item) {
+    const out = [];
+    for (const f of targetedFiles(item)) {
+        const abs = resolveTarget(root, f.target);
+        const file = path.relative(root, abs);
+        if (!existsSync(abs)) {
+            out.push({ file, status: 'missing' });
+            continue;
+        }
+        const local = normalizeEol(await readFile(abs, 'utf8'));
+        const remote = normalizeEol(f.content ?? '');
+        out.push(local === remote
+            ? { file, status: 'same' }
+            : { file, status: 'changed', patch: createTwoFilesPatch(`a/${file}`, `b/${file}`, local, remote, 'local', 'registry') });
+    }
+    return out;
+}
+/** Colours a unified diff for the terminal (no-op without colour support). */
+export function colorPatch(patch) {
+    return patch
+        .split('\n')
+        .filter(line => !line.startsWith('====')) // jsdiff's "Index:" banner separator
+        .map(line => {
+        if (line.startsWith('+++') || line.startsWith('---'))
+            return color.bold(line);
+        if (line.startsWith('@@'))
+            return color.cyan(line);
+        if (line.startsWith('+'))
+            return color.green(line);
+        if (line.startsWith('-'))
+            return color.red(line);
+        return line;
+    })
+        .join('\n');
+}
+export async function runDiff(options) {
+    const project = await loadProject(options.cwd);
+    const { root } = project;
+    const config = await requireConfig(root);
+    const registry = registryFor(root, config, path.resolve(options.cwd));
+    const layout = resolveLayout(root, config.aliases);
+    if (options.name) {
+        if (refKind(options.name) === 'name')
+            assertKnownNames([options.name], new Set((await registry.index()).items.map(i => i.name)));
+        await diffOne(root, adaptItem(await registry.item(options.name), layout), options.name);
+        return;
+    }
+    await diffAll(root, registry, Object.keys(config.registries ?? {}), layout);
+}
+async function diffOne(root, item, ref) {
+    const files = await compareItem(root, item);
+    if (files.every(f => f.status === 'missing')) {
+        log.info(`\`${ref}\` is not installed. Add it with \`uipkge-ng add ${ref}\`.`);
+        return;
+    }
+    const changed = files.filter(f => f.status === 'changed');
+    const missing = files.filter(f => f.status === 'missing');
+    for (const f of changed)
+        if (f.status === 'changed')
+            process.stdout.write(`${colorPatch(f.patch)}\n`);
+    for (const f of missing)
+        log.warn(`${f.file} is missing locally (the registry has it).`);
+    if (!changed.length && !missing.length) {
+        log.success(`${item.name} is up to date with the registry.`);
+        return;
+    }
+    log.blank();
+    log.info(`${item.name}: ${plural(changed.length, 'file')} differ${changed.length === 1 ? 's' : ''}` +
+        (missing.length ? `, ${missing.length} missing` : '') +
+        color.dim(` — \`uipkge-ng add ${ref} --overwrite\` takes the registry version.`));
+}
+// Skip the tokens/bundle items: `tailwind`'s declared target is the user's own
+// stylesheet (init writes the tokens elsewhere), so comparing it is meaningless.
+const NOT_DIFFABLE = new Set(['tailwind', 'init']);
+/**
+ * Installed items from the default registry and every named one, as refs
+ * (`button`, `@acme/card`). A named registry that can't be read is reported
+ * and skipped rather than failing the whole check.
+ */
+export async function installedRefs(root, registry, namespaces, layout) {
+    const sources = [undefined, ...namespaces];
+    const refs = await Promise.all(sources.map(async (ns) => {
+        let items;
+        try {
+            items = (await registry.index(ns)).items;
+        }
+        catch (error) {
+            if (!ns)
+                throw error;
+            log.warn(`Skipped ${ns}: ${error instanceof Error ? error.message : String(error)}`);
+            return [];
+        }
+        return items
+            .filter(i => !NOT_DIFFABLE.has(i.name) && isItemInstalled(root, adaptItem(i, layout)))
+            .map(i => (ns ? `${ns}/${i.name}` : i.name));
+    }));
+    return refs.flat();
+}
+async function diffAll(root, registry, namespaces, layout) {
+    const installed = await installedRefs(root, registry, namespaces, layout);
+    if (!installed.length) {
+        log.info('No uipkge components are installed yet. Add one with `uipkge-ng add <name>`.');
+        return;
+    }
+    log.step(`Checking ${plural(installed.length, 'component')} against ${[registry.baseUrl, ...namespaces].join(', ')}`);
+    const outdated = [];
+    const queue = [...installed];
+    // A handful in parallel: fast, without hammering the registry.
+    await Promise.all(Array.from({ length: Math.min(8, queue.length) }, async () => {
+        for (let next = queue.shift(); next; next = queue.shift()) {
+            const files = await compareItem(root, adaptItem(await registry.item(next), layout));
+            if (files.some(f => f.status !== 'same'))
+                outdated.push(next);
+        }
+    }));
+    if (!outdated.length) {
+        log.success(`All ${plural(installed.length, 'component')} match the registry.`);
+        return;
+    }
+    outdated.sort();
+    log.info(`${plural(outdated.length, 'component')} ${outdated.length === 1 ? 'differs' : 'differ'} from the registry:`);
+    for (const name of outdated)
+        log.info(`  ${color.yellow('•')} ${name}`);
+    log.blank();
+    log.info(color.dim('See the changes with `uipkge-ng diff <name>`.'));
+}

package/dist/commands/info.js

@@ -0,0 +1,122 @@
+import { existsSync } from 'node:fs';
+import * as path from 'node:path';
+import { readConfig, registryFor } from '../config.js';
+import { isItemInstalled } from '../files.js';
+import { adaptItem, resolveLayout } from '../layout.js';
+import { color } from '../output.js';
+import { declaredDependencies, detectPackageManager, findApp, readPackageJson } from '../project.js';
+import { FOUNDATION_ITEMS, resolveRegistryUrl } from '../registry.js';
+import { POSTCSS_FILES } from '../setup.js';
+/** A snapshot for bug reports: never throws on a broken project, it reports what it finds. */
+export async function collectInfo(cwd, version) {
+    const location = findApp(path.resolve(cwd));
+    const root = location?.root ?? null;
+    const packageRoot = location?.packageRoot ?? null;
+    const pkg = packageRoot ? await readPackageJson(packageRoot).catch(() => null) : null;
+    const deps = pkg ? declaredDependencies(pkg) : {};
+    const config = root ? await readConfig(root).catch(() => null) : null;
+    const url = resolveRegistryUrl(config?.registryUrl);
+    const info = {
+        cli: version,
+        node: process.version,
+        platform: `${process.platform}-${process.arch}`,
+        project: {
+            root,
+            packageRoot,
+            app: location?.app?.name ?? null,
+            apps: location?.ambiguous?.map(a => a.name) ?? null,
+            angular: deps['@angular/core'] ?? null,
+            analog: Boolean(deps['@analogjs/platform'] || deps['@analogjs/vite-plugin-angular']),
+            nx: Boolean(deps['nx'] || (packageRoot && existsSync(path.join(packageRoot, 'nx.json')))),
+            packageManager: packageRoot && pkg ? detectPackageManager(packageRoot, pkg) : null,
+            tailwind: deps['tailwindcss'] ?? null,
+            postcssConfig: packageRoot ? (POSTCSS_FILES.find(f => existsSync(path.join(packageRoot, f))) ?? null) : null,
+        },
+        config,
+        layout: null,
+        registry: { url, reachable: false, items: null },
+        installed: [],
+    };
+    let layout;
+    if (root && config) {
+        try {
+            layout = resolveLayout(root, config.aliases);
+            info.layout = layout.dirs;
+        }
+        catch (error) {
+            info.layout = { error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    try {
+        const index = await registryFor(root, config, cwd).index();
+        info.registry.reachable = true;
+        info.registry.items = index.items.length;
+        if (root && config) {
+            info.installed = index.items
+                .filter(i => !FOUNDATION_ITEMS.has(i.name) && isItemInstalled(root, layout ? adaptItem(i, layout) : i))
+                .map(i => i.name)
+                .sort();
+        }
+    }
+    catch (error) {
+        info.registry.error = error instanceof Error ? error.message : String(error);
+    }
+    // Named registries: best effort, an unreachable one just adds nothing.
+    if (root && config?.registries) {
+        const registry = registryFor(root, config, cwd);
+        for (const ns of Object.keys(config.registries)) {
+            try {
+                const items = (await registry.index(ns)).items;
+                info.installed.push(...items.filter(i => isItemInstalled(root, layout ? adaptItem(i, layout) : i)).map(i => `${ns}/${i.name}`));
+            }
+            catch {
+                // reported by `uipkge-ng list <ns>`
+            }
+        }
+    }
+    return info;
+}
+export async function runInfo(options) {
+    const info = await collectInfo(options.cwd, options.version);
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify(info, null, 2)}\n`);
+        return;
+    }
+    const yes = (v) => (v ? color.green(String(v)) : color.dim('no'));
+    const row = (label, value) => `  ${color.dim(label.padEnd(16))}${value}`;
+    const out = [
+        color.bold('uipkge'),
+        row('cli', info.cli),
+        row('node', `${info.node} (${info.platform})`),
+        '',
+        color.bold('Project'),
+        row('root', info.project.root ?? color.dim('no package.json found')),
+        ...(info.project.packageRoot && info.project.packageRoot !== info.project.root ? [row('workspace', info.project.packageRoot)] : []),
+        ...(info.project.app ? [row('app', info.project.app)] : []),
+        ...(info.project.apps ? [row('apps', color.yellow(`${info.project.apps.join(', ')} — run inside one`))] : []),
+        row('angular', info.project.angular ?? color.yellow('not an Angular project')),
+        row('package manager', info.project.packageManager ?? '—'),
+        row('tailwind', yes(info.project.tailwind)),
+        row('postcss config', yes(info.project.postcssConfig)),
+        row('analog / nx', `${info.project.analog ? 'analog' : 'no'} / ${info.project.nx ? color.yellow('nx (not supported yet)') : 'no'}`),
+        '',
+        color.bold('components.json'),
+        info.config ? JSON.stringify(info.config, null, 2).split('\n').map(l => `  ${l}`).join('\n') : row('status', color.yellow('not initialized — run `uipkge-ng init`')),
+        ...(info.layout
+            ? [
+                '',
+                color.bold('Folders'),
+                ...('error' in info.layout
+                    ? [row('aliases', color.red(info.layout.error))]
+                    : [row('ui', info.layout.ui), row('lib', info.layout.lib), row('blocks', info.layout.blocks)]),
+            ]
+            : []),
+        '',
+        color.bold('Registry'),
+        row('url', info.registry.url),
+        row('reachable', info.registry.reachable ? color.green(`yes (${info.registry.items} items)`) : color.red(`no — ${info.registry.error}`)),
+        row('installed', info.config ? (info.installed.length ? `${info.installed.length}: ${info.installed.join(', ')}` : 'none yet') : '—'),
+        row('named', Object.keys(info.config?.registries ?? {}).join(', ') || color.dim('none')),
+    ];
+    process.stdout.write(`${out.join('\n')}\n`);
+}

package/dist/commands/init.js

@@ -0,0 +1,154 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import * as path from 'node:path';
+import { defaultConfig, readConfig, registryFor, writeConfig } from '../config.js';
+import { UipkgeError } from '../errors.js';
+import { writeItemFiles } from '../files.js';
+import { adaptItem, resolveLayout } from '../layout.js';
+import { color, log } from '../output.js';
+import { installPackages, missingPackages } from '../packages.js';
+import { declaredDependencies, loadProject } from '../project.js';
+import { confirm, isInteractive } from '../prompts.js';
+import { createRegistry, DEFAULT_REGISTRY_URL, NotFoundError, resolveRegistryUrl } from '../registry.js';
+import { addGlobalStyle, appTsconfigEdit, planTailwind, readPostcssConfig, relativeImport, withTailwindPlugin, tsconfigsToEdit, withTokensImport, writeIfChanged, } from '../setup.js';
+export async function runInit(options) {
+    const project = await loadProject(options.cwd);
+    const { root, packageRoot } = project;
+    const existing = await readConfig(root);
+    if (existing && !options.overwrite) {
+        log.info(`uipkge is already set up in ${root} (components.json exists).`);
+        log.info(color.dim('Run `uipkge-ng init --overwrite` to redo it, or `uipkge-ng add <name>` to add components.'));
+        return;
+    }
+    if (!options.yes && isInteractive() && !(await confirm(`Set up uipkge in ${root}?`))) {
+        log.info('Nothing was changed.');
+        return;
+    }
+    // Keep a registry chosen in an existing components.json when re-running.
+    const config = existing ?? { ...defaultConfig(resolveRegistryUrl()), ...stylesFor(project.app) };
+    const registry = registryFor(root, config);
+    // Everything that can fail on the network happens before the project is touched.
+    log.step(`Fetching foundation from ${registry.baseUrl}`);
+    // A registry that ships only its own components can still be the default: the foundation then comes from uipkge.
+    const foundation = async (name) => {
+        try {
+            return await registry.item(name);
+        }
+        catch (error) {
+            if (!(error instanceof NotFoundError) || registry.baseUrl === DEFAULT_REGISTRY_URL)
+                throw error;
+            log.info(color.dim(`  ${registry.baseUrl} has no \`${name}\`; using uipkge's (${DEFAULT_REGISTRY_URL}).`));
+            return createRegistry(DEFAULT_REGISTRY_URL).item(name);
+        }
+    };
+    const [utils, tokens] = await Promise.all([foundation('utils'), foundation('tailwind')]);
+    const tokensCss = tokens.files.find(f => f.target?.endsWith('.css') || f.path?.endsWith('.css'))?.content;
+    if (!tokensCss)
+        throw new UipkgeError('The registry `tailwind` item has no CSS file.');
+    const done = [];
+    const declared = declaredDependencies(project.packageJson);
+    // 1. npm packages: Tailwind (dev) + what utils/tokens import.
+    // PostCSS config is read from the workspace root, where the Angular CLI runs.
+    const tailwind = planTailwind({ ...project, postcss: await readPostcssConfig(packageRoot) });
+    const devPackages = tailwind.kind === 'skip' ? [] : missingPackages(tailwind.devPackages, declared);
+    const packages = missingPackages([...(utils.dependencies ?? []), ...(tokens.dependencies ?? [])], declared);
+    if (packages.length || devPackages.length) {
+        log.step(`Installing ${[...packages, ...devPackages].join(', ')}`);
+        await installPackages(project.packageManager, packageRoot, packages);
+        await installPackages(project.packageManager, packageRoot, devPackages, true);
+    }
+    // 2. Tailwind wiring.
+    if (tailwind.kind === 'postcss') {
+        const file = path.join(packageRoot, tailwind.config.file);
+        if (tailwind.config.action === 'create')
+            await writeFile(file, withTailwindPlugin(''), 'utf8');
+        if (tailwind.config.action === 'merge')
+            await writeFile(file, withTailwindPlugin(await readFile(file, 'utf8')), 'utf8');
+        if (tailwind.config.action === 'manual') {
+            log.warn(`Add "@tailwindcss/postcss" to the plugins in ${tailwind.config.file} so Tailwind runs.`);
+        }
+        done.push('Tailwind CSS v4 set up');
+    }
+    else if (tailwind.kind === 'vite') {
+        log.warn("Analog/Vite: add Tailwind to vite.config.ts — `import tailwindcss from '@tailwindcss/vite'` and `plugins: [tailwindcss()]`.");
+        done.push('Tailwind CSS v4 installed (add the Vite plugin)');
+    }
+    // 3. tsconfig aliases the component sources import.
+    const tsconfigs = tsconfigsToEdit(root);
+    if (!tsconfigs.length)
+        throw new UipkgeError(`No tsconfig.json in ${root}.`);
+    const edited = [];
+    for (const file of tsconfigs) {
+        const abs = path.join(root, file);
+        if (await writeIfChanged(abs, appTsconfigEdit(root, file, await readFile(abs, 'utf8'))))
+            edited.push(file);
+    }
+    if (edited.length)
+        done.push(`tsconfig paths \`@/*\` and \`@/ui/*\` added (${edited.join(', ')})`);
+    // 4. cn() helper, wherever the `lib` alias points.
+    const layout = resolveLayout(root, config.aliases);
+    const utilsResult = await writeItemFiles(root, adaptItem(utils, layout), options.overwrite);
+    if (utilsResult.written.length)
+        done.push(`cn() helper written (${utilsResult.written.join(', ')})`);
+    // A kept file of the user's own is fine as long as it still gives components their cn().
+    for (const file of utilsResult.kept) {
+        if (!/export\s+(?:function|const|let)\s+cn\b|export\s*\{[^}]*\bcn\b[^}]*\}/.test(await readFile(path.join(root, file), 'utf8'))) {
+            log.warn(`${file} already exists and doesn't export cn(); components import it from there. Add it (\`uipkge-ng view utils\`) or re-run with --overwrite.`);
+        }
+    }
+    // 5. Design tokens in a file uipkge owns; the user's stylesheet only gains an import.
+    const tokensFile = path.join(root, config.tokens);
+    if (!existsSync(tokensFile) || options.overwrite) {
+        await mkdir(path.dirname(tokensFile), { recursive: true });
+        await writeFile(tokensFile, tokensCss, 'utf8');
+        done.push(`design tokens written (${config.tokens})`);
+    }
+    await linkTokens(project, config.styles, config.tokens, done);
+    await writeConfig(root, config);
+    done.push('components.json written');
+    log.blank();
+    log.success(color.bold('uipkge is ready.'));
+    for (const line of done)
+        log.info(`  ${color.green('✔')} ${line}`);
+    log.blank();
+    log.info(`Add a component:  ${color.cyan('uipkge-ng add button')}`);
+    log.info(`Browse them all:  ${color.cyan('uipkge-ng list')}`);
+}
+const TOKENS_FILE = 'uipkge.css';
+/** Global stylesheet and tokens file for a new components.json, from the app's angular.json styles. */
+function stylesFor(app) {
+    // Skip a tokens file an earlier init registered, or it would import itself.
+    const candidates = app?.styles.filter(f => path.posix.basename(f) !== TOKENS_FILE) ?? [];
+    const styles = candidates.find(f => f.endsWith('.css')) ?? candidates[0];
+    if (!styles || styles.startsWith('..'))
+        return undefined;
+    return { styles, tokens: path.posix.join(path.posix.dirname(styles), TOKENS_FILE) };
+}
+async function linkTokens(project, styles, tokens, done) {
+    const { root } = project;
+    const stylesFile = path.join(root, styles);
+    const importPath = relativeImport(styles, tokens);
+    if (path.resolve(root, styles) === path.resolve(root, tokens)) {
+        throw new UipkgeError(`"styles" and "tokens" in components.json are the same file (${styles}).`, 'Point "styles" at your global stylesheet.');
+    }
+    // Sass/Less: a CSS import there doesn't carry Tailwind v4's syntax reliably, so the tokens become their own global stylesheet.
+    if (!styles.endsWith('.css') && project.app) {
+        const entry = path.relative(project.packageRoot, path.join(root, tokens)).replace(/\\/g, '/');
+        if (await addGlobalStyle(project.packageRoot, project.app.name, entry))
+            done.push(`angular.json styles include ${entry}`);
+        return;
+    }
+    if (!existsSync(stylesFile)) {
+        const preprocessed = ['.scss', '.sass', '.less'].map(ext => styles.replace(/\.css$/, ext)).find(f => existsSync(path.join(root, f)));
+        if (preprocessed) {
+            log.warn(`Your global stylesheet is ${preprocessed}. Add \`@import '${importPath}';\` to a CSS file listed in angular.json "styles".`);
+            return;
+        }
+        await mkdir(path.dirname(stylesFile), { recursive: true });
+        await writeFile(stylesFile, '', 'utf8');
+        log.warn(`Created ${styles}; make sure it is listed under "styles" in angular.json.`);
+    }
+    if (await writeIfChanged(stylesFile, withTokensImport(await readFile(stylesFile, 'utf8'), importPath))) {
+        done.push(`${styles} imports ${importPath}`);
+    }
+}

package/dist/commands/list.js

@@ -0,0 +1,103 @@
+import * as path from 'node:path';
+import { readConfig, registryFor } from '../config.js';
+import { UipkgeError } from '../errors.js';
+import { isItemInstalled } from '../files.js';
+import { adaptItem, resolveLayout } from '../layout.js';
+import { color, plural } from '../output.js';
+import { findAppRoot } from '../project.js';
+import { FOUNDATION_ITEMS } from '../registry.js';
+import { existsSync } from 'node:fs';
+/** Foundation items are init's job; the style item is not something you add. */
+export function isListable(item) {
+    return !FOUNDATION_ITEMS.has(item.name) && item.type !== 'registry:style';
+}
+export function firstSentence(text) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    const end = flat.search(/[.!?](\s|$)/);
+    return end === -1 ? flat : flat.slice(0, end);
+}
+const OTHER = 'other';
+/** Filters, then groups by first category (alphabetical, `other` last), rows sorted by name. */
+export function groupRows(items, filter) {
+    const query = filter.query?.trim().toLowerCase();
+    const category = filter.category?.trim().toLowerCase();
+    const rows = items.filter(isListable).flatMap((item) => {
+        if (category && !(item.categories ?? []).some(c => c.toLowerCase() === category))
+            return [];
+        if (query && ![item.name, item.title, item.description].some(v => v?.toLowerCase().includes(query)))
+            return [];
+        const installed = filter.installed(item);
+        if (filter.installedOnly && !installed)
+            return [];
+        return [
+            {
+                name: item.name,
+                title: item.title ?? item.name,
+                description: firstSentence(item.description ?? ''),
+                category: (item.categories?.[0] ?? OTHER).toLowerCase(),
+                installed,
+            },
+        ];
+    });
+    const byCategory = new Map();
+    for (const row of rows)
+        byCategory.set(row.category, [...(byCategory.get(row.category) ?? []), row]);
+    return [...byCategory]
+        .sort(([a], [b]) => (a === OTHER ? 1 : b === OTHER ? -1 : a.localeCompare(b)))
+        .map(([cat, list]) => ({ category: cat, rows: list.sort((x, y) => x.name.localeCompare(y.name)) }));
+}
+export const ellipsize = (text, width) => width < 2 ? '' : text.length <= width ? text : `${text.slice(0, width - 1).trimEnd()}…`;
+export async function runList(options) {
+    const cwd = path.resolve(options.cwd);
+    if (!existsSync(cwd))
+        throw new UipkgeError(`The directory ${cwd} does not exist.`);
+    // Works anywhere (browse before init); installed marks need an initialized project.
+    const root = findAppRoot(cwd);
+    const config = root ? await readConfig(root) : null;
+    const registry = registryFor(root, config, cwd);
+    const index = await registry.index(options.namespace);
+    // A broken alias setup shouldn't stop browsing; installed marks fall back to the default folders.
+    let layout;
+    if (config && root) {
+        try {
+            layout = resolveLayout(root, config.aliases);
+        }
+        catch {
+            layout = undefined;
+        }
+    }
+    const groups = groupRows(options.namespace ? index.items.map(i => ({ ...i, name: `${options.namespace}/${i.name}` })) : index.items, {
+        query: options.query,
+        category: options.category,
+        installedOnly: options.installedOnly,
+        installed: item => Boolean(config && root && isItemInstalled(root, layout ? adaptItem(item, layout) : item)),
+    });
+    const rows = groups.flatMap(g => g.rows);
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify(rows, null, 2)}\n`);
+        return;
+    }
+    if (!rows.length) {
+        const what = options.installedOnly ? 'No installed components' : 'No components';
+        process.stdout.write(`${what}${options.query ? ` match "${options.query}"` : ''}.\n`);
+        return;
+    }
+    const width = Math.min(Math.max(process.stdout.columns || 100, 60), 120);
+    const nameWidth = Math.min(Math.max(...rows.map(r => r.name.length)) + 2, 30);
+    const out = [];
+    for (const group of groups) {
+        out.push('', `${color.bold(group.category)} ${color.dim(`(${group.rows.length})`)}`);
+        for (const row of group.rows) {
+            const mark = row.installed ? color.green('✔') : ' ';
+            out.push(`  ${mark} ${row.name.padEnd(nameWidth)}${color.dim(ellipsize(row.description, width - nameWidth - 4))}`);
+        }
+    }
+    const installedCount = rows.filter(r => r.installed).length;
+    out.push('', color.dim(plural(rows.length, 'component') +
+        (config ? ` · ${installedCount} installed` : '') +
+        (options.query ? ` matching "${options.query}"` : '')));
+    if (!config)
+        out.push(color.dim('Run `uipkge-ng init` in your project to see which ones are installed.'));
+    out.push(color.dim('Add one with `uipkge-ng add <name>`.'), '');
+    process.stdout.write(out.join('\n'));
+}