uipkge-ng 0.1.0

package/dist/commands/mcp.js

@@ -0,0 +1,149 @@
+import * as path from 'node:path';
+import { createInterface } from 'node:readline';
+import { readConfig, registryFor } from '../config.js';
+import { findAppRoot } from '../project.js';
+import { refKind } from '../registry.js';
+import { firstSentence, isListable } from './list.js';
+import { describeItem } from './view.js';
+/**
+ * A minimal Model Context Protocol server over stdio (newline-delimited JSON-RPC 2.0).
+ * Read-only: it browses the registry and hands back `uipkge-ng add` commands; it never writes files.
+ */
+const PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+const stringList = (description) => ({ type: 'array', items: { type: 'string' }, minItems: 1, description });
+export const TOOLS = [
+    {
+        name: 'list_components',
+        description: 'List uipkge Angular components, optionally filtered by a search query or category.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Matches name, title or description' },
+                category: { type: 'string' },
+                registry: { type: 'string', description: 'A named registry from components.json, e.g. @acme' },
+            },
+        },
+        async run(args, ctx) {
+            const ns = typeof args.registry === 'string' && args.registry ? args.registry : undefined;
+            const query = String(args.query ?? '').toLowerCase();
+            const category = String(args.category ?? '').toLowerCase();
+            const items = (await ctx.registry.index(ns)).items.filter(isListable).filter(i => (!category || (i.categories ?? []).some(c => c.toLowerCase() === category)) &&
+                (!query || [i.name, i.title, i.description].some(v => v?.toLowerCase().includes(query))));
+            if (!items.length)
+                return 'No components match.';
+            return items
+                .map(i => `${ns ? `${ns}/` : ''}${i.name}${i.categories?.length ? ` [${i.categories[0]}]` : ''} — ${firstSentence(i.description ?? '')}`)
+                .join('\n');
+        },
+    },
+    {
+        name: 'view_components',
+        description: 'Show components in full: description, dependencies, usage notes and the source of every file.',
+        inputSchema: { type: 'object', properties: { names: stringList('Names such as "button" or "@acme/card"') }, required: ['names'] },
+        async run(args, ctx) {
+            const items = await Promise.all(names(args).map(n => ctx.registry.item(n)));
+            return items.map(describeItem).join('\n\n---\n\n');
+        },
+    },
+    {
+        name: 'get_add_command',
+        description: 'Return the shell command that adds components (and their dependencies) to the project.',
+        inputSchema: { type: 'object', properties: { names: stringList('Component names') }, required: ['names'] },
+        async run(args, ctx) {
+            const list = names(args);
+            // Check bare names exist so the command isn't a guess.
+            const bare = list.filter(n => refKind(n) === 'name');
+            if (bare.length) {
+                const known = new Set((await ctx.registry.index()).items.map(i => i.name));
+                const unknown = bare.filter(n => !known.has(n));
+                if (unknown.length)
+                    throw new Error(`Unknown component: ${unknown.join(', ')}`);
+            }
+            return `npx uipkge-ng add ${list.join(' ')}`;
+        },
+    },
+    {
+        name: 'list_registries',
+        description: 'List the registries this project can install from.',
+        inputSchema: { type: 'object', properties: {} },
+        async run(_args, ctx) {
+            return [`default: ${ctx.registry.baseUrl}`, ...ctx.namespaces.map(n => `${n} (use ${n}/<name>)`)].join('\n');
+        },
+    },
+];
+function names(args) {
+    const list = Array.isArray(args.names) ? args.names.filter((n) => typeof n === 'string' && n.length > 0) : [];
+    if (!list.length)
+        throw new Error('"names" must be a non-empty list of strings');
+    return list;
+}
+/** Answers one JSON-RPC message; `undefined` for notifications (no reply). Exposed for tests. */
+export async function handleMessage(message, ctx, version) {
+    const reply = (result) => ({ jsonrpc: '2.0', id: message.id, result });
+    const fail = (code, msg) => ({ jsonrpc: '2.0', id: message.id ?? null, error: { code, message: msg } });
+    if (message?.jsonrpc !== '2.0' || typeof message.method !== 'string')
+        return fail(-32600, 'Invalid request');
+    const isNotification = message.id === undefined;
+    switch (message.method) {
+        case 'initialize': {
+            const asked = String(message.params?.protocolVersion ?? '');
+            return reply({
+                protocolVersion: PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0],
+                capabilities: { tools: {} },
+                serverInfo: { name: 'uipkge-ng', version },
+                instructions: 'Browse uipkge Angular components. To install, run the command from get_add_command in the project.',
+            });
+        }
+        case 'ping':
+            return reply({});
+        case 'tools/list':
+            return reply({ tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) });
+        case 'tools/call': {
+            const tool = TOOLS.find(t => t.name === message.params?.name);
+            if (!tool)
+                return fail(-32602, `Unknown tool: ${String(message.params?.name)}`);
+            try {
+                const text = await tool.run(message.params?.arguments ?? {}, ctx);
+                return reply({ content: [{ type: 'text', text }] });
+            }
+            catch (error) {
+                // Tool failures are results the model can read, not protocol errors.
+                return reply({ content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }], isError: true });
+            }
+        }
+        default:
+            return isNotification ? undefined : fail(-32601, `Method not found: ${message.method}`);
+    }
+}
+export async function runMcp(options) {
+    const cwd = path.resolve(options.cwd);
+    const root = findAppRoot(cwd);
+    const config = root ? await readConfig(root).catch(() => null) : null;
+    const ctx = { registry: registryFor(root, config, cwd), namespaces: Object.keys(config?.registries ?? {}) };
+    // stdout carries protocol messages only; anything else goes to stderr.
+    const lines = createInterface({ input: process.stdin });
+    const pending = new Set();
+    lines.on('line', line => {
+        if (!line.trim())
+            return;
+        const task = (async () => {
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                return send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+            }
+            const response = await handleMessage(message, ctx, options.version);
+            if (response)
+                send(response);
+        })();
+        pending.add(task);
+        void task.finally(() => pending.delete(task));
+    });
+    await new Promise(resolve => lines.on('close', resolve));
+    await Promise.all(pending);
+}
+function send(message) {
+    process.stdout.write(`${JSON.stringify(message)}\n`);
+}

package/dist/commands/view.js

@@ -0,0 +1,48 @@
+import * as path from 'node:path';
+import { readConfig, registryFor } from '../config.js';
+import { UipkgeError } from '../errors.js';
+import { color } from '../output.js';
+import { findAppRoot } from '../project.js';
+import { itemNameFromRef, refKind } from '../registry.js';
+import { assertKnownNames } from '../resolve.js';
+/** Everything an install would touch, without installing: metadata, dependencies, file contents. */
+export function describeItem(item) {
+    const lines = [color.bold(item.title ? `${item.title} (${item.name})` : item.name)];
+    if (item.description)
+        lines.push(item.description);
+    const meta = [
+        ['type', item.type],
+        ['categories', item.categories?.join(', ')],
+        ['npm', item.dependencies?.join(', ')],
+        ['npm (dev)', item.devDependencies?.join(', ')],
+        ['requires', item.registryDependencies?.map(r => (refKind(r) === 'url' ? itemNameFromRef(r) : r)).join(', ')],
+        ['env', item.envVars ? Object.keys(item.envVars).join(', ') : undefined],
+    ];
+    for (const [label, value] of meta)
+        if (value)
+            lines.push(`${color.dim(label.padEnd(11))}${value}`);
+    if (item.docs)
+        lines.push('', color.bold('Notes'), item.docs.trim());
+    for (const f of item.files) {
+        const file = (f.target ?? f.path ?? '(no target)').replace(/^~\//, '');
+        lines.push('', color.bold(`── ${file}`), f.content ?? color.dim('(no content in this document)'));
+    }
+    return lines.join('\n');
+}
+export async function runView(options) {
+    if (!options.items.length)
+        throw new UipkgeError('Nothing to view.', 'Pass one or more names, e.g. `uipkge-ng view button`.');
+    const cwd = path.resolve(options.cwd);
+    const root = findAppRoot(cwd);
+    const config = root ? await readConfig(root) : null;
+    const registry = registryFor(root, config, cwd);
+    const bare = options.items.filter(i => refKind(i) === 'name');
+    if (bare.length)
+        assertKnownNames(bare, new Set((await registry.index()).items.map(i => i.name)));
+    const items = await Promise.all(options.items.map(ref => registry.item(ref)));
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify(items.length === 1 ? items[0] : items, null, 2)}\n`);
+        return;
+    }
+    process.stdout.write(`${items.map(describeItem).join(`\n\n${'─'.repeat(40)}\n\n`)}\n`);
+}

package/dist/config.js

@@ -0,0 +1,56 @@
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import * as path from 'node:path';
+import { projectEnv } from './env.js';
+import { UipkgeError } from './errors.js';
+import { createRegistry, resolveRegistryUrl } from './registry.js';
+export const CONFIG_FILE = 'components.json';
+export const DEFAULT_ALIASES = { ui: '@/ui', lib: '@/lib', blocks: '@/app/components/blocks' };
+export function defaultConfig(registryUrl) {
+    return {
+        framework: 'angular',
+        registryUrl,
+        styles: 'src/styles.css',
+        tokens: 'src/uipkge.css',
+        aliases: { ...DEFAULT_ALIASES },
+    };
+}
+export async function readConfig(root) {
+    const file = path.join(root, CONFIG_FILE);
+    if (!existsSync(file))
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch (error) {
+        throw new UipkgeError(`${CONFIG_FILE} is not valid JSON: ${error instanceof Error ? error.message : error}`);
+    }
+    // Tolerate hand-edited or older files: fill in what's missing.
+    const base = defaultConfig(raw.registryUrl ?? '');
+    const config = { ...base, ...raw, aliases: { ...DEFAULT_ALIASES, ...raw.aliases }, framework: 'angular' };
+    for (const key of Object.keys(config.registries ?? {})) {
+        if (!/^@[a-z0-9][\w-]*$/i.test(key)) {
+            throw new UipkgeError(`Registry names in ${CONFIG_FILE} must look like "@acme" (got "${key}").`);
+        }
+    }
+    return config;
+}
+export async function requireConfig(root) {
+    const config = await readConfig(root);
+    if (!config) {
+        throw new UipkgeError(`No ${CONFIG_FILE} found in ${root}.`, 'Run `uipkge-ng init` first.');
+    }
+    return config;
+}
+export async function writeConfig(root, config) {
+    await writeFile(path.join(root, CONFIG_FILE), JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+/** The registry client for a project: default URL, named registries, `.env`-backed tokens. */
+export function registryFor(root, config, cwd = process.cwd()) {
+    return createRegistry(resolveRegistryUrl(config?.registryUrl), {
+        cwd,
+        registries: config?.registries,
+        env: projectEnv(root),
+    });
+}

package/dist/env.js

@@ -0,0 +1,33 @@
+import { existsSync, readFileSync } from 'node:fs';
+import * as path from 'node:path';
+/** `KEY=value` lines (quotes stripped, `export` allowed, comments ignored). */
+export function parseDotenv(text) {
+    const out = {};
+    for (const line of text.split(/\r?\n/)) {
+        const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);
+        if (!match)
+            continue;
+        let value = match[2];
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        else {
+            value = value.replace(/\s+#.*$/, '');
+        }
+        out[match[1]] = value;
+    }
+    return out;
+}
+/**
+ * Variables for registry `${VAR}` expansion: `.env`, then `.env.local`, then the
+ * real environment (which always wins). Values are never written back.
+ */
+export function projectEnv(root) {
+    const merged = {};
+    for (const file of ['.env', '.env.local']) {
+        const abs = root ? path.join(root, file) : '';
+        if (abs && existsSync(abs))
+            Object.assign(merged, parseDotenv(readFileSync(abs, 'utf8')));
+    }
+    return { ...merged, ...process.env };
+}

package/dist/errors.js

@@ -0,0 +1,9 @@
+/** An expected failure: printed as a message (plus optional hint), exit code 1, no stack. */
+export class UipkgeError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.hint = hint;
+        this.name = 'UipkgeError';
+    }
+}

package/dist/extras.js

@@ -0,0 +1,111 @@
+// Install-time additions a registry item can carry besides files:
+// cssVars, css, envVars, docs (shadcn registry-item schema).
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+export function hasCss(item) {
+    const vars = item.cssVars;
+    const anyVars = Boolean(vars && (Object.keys(vars.theme ?? {}).length || Object.keys(vars.light ?? {}).length || Object.keys(vars.dark ?? {}).length));
+    return anyVars || Boolean(item.css && Object.keys(item.css).length);
+}
+const decl = (name, value) => `  --${name.replace(/^--/, '')}: ${value};`;
+/** CSS text for an item's cssVars + css rules (no markers). */
+export function itemCss(item) {
+    const vars = item.cssVars ?? {};
+    const out = [];
+    const light = Object.entries(vars.light ?? {});
+    const dark = Object.entries(vars.dark ?? {});
+    if (light.length)
+        out.push(':root {', ...light.map(([k, v]) => decl(k, v)), '}');
+    if (dark.length)
+        out.push('.dark {', ...dark.map(([k, v]) => decl(k, v)), '}');
+    // Tailwind v4 only turns a variable into utilities (`bg-brand`) when it is
+    // registered as `--color-*` in @theme; do that for every light/dark colour var.
+    const colorNames = [...new Set([...light, ...dark].map(([k]) => k.replace(/^--/, '')))];
+    const theme = [
+        ...Object.entries(vars.theme ?? {}).map(([k, v]) => decl(k, v)),
+        ...colorNames.filter(n => !(vars.theme ?? {})[n]).map(n => `  --color-${n}: var(--${n});`),
+    ];
+    if (theme.length)
+        out.push('@theme inline {', ...theme, '}');
+    if (item.css && Object.keys(item.css).length)
+        out.push(serializeCss(item.css, 0));
+    return out.join('\n');
+}
+/** `{ "@layer base": { "h1": { "font-weight": "600" } } }` → nested CSS text. */
+export function serializeCss(rules, depth) {
+    const pad = '  '.repeat(depth);
+    const lines = [];
+    for (const [key, value] of Object.entries(rules)) {
+        if (typeof value === 'string') {
+            lines.push(`${pad}${key}: ${value};`);
+        }
+        else if (Object.keys(value).length === 0) {
+            lines.push(`${pad}${key};`); // e.g. `@import "x"` expressed as an empty rule
+        }
+        else {
+            lines.push(`${pad}${key} {`, serializeCss(value, depth + 1), `${pad}}`);
+        }
+    }
+    return lines.join('\n');
+}
+const START = (name) => `/* uipkge:${name} — added by \`uipkge-ng add ${name}\`; edits here are replaced on reinstall */`;
+const END = (name) => `/* /uipkge:${name} */`;
+/**
+ * Puts the item's CSS at the end of `stylesheet` inside markers, replacing a
+ * previous block for the same item so reinstalling never duplicates it.
+ * Returns the new text, or null when unchanged.
+ */
+export function upsertCssBlock(stylesheet, name, css) {
+    const block = `${START(name)}\n${css}\n${END(name)}`;
+    const start = stylesheet.indexOf(START(name));
+    const endMarker = END(name);
+    if (start !== -1) {
+        const end = stylesheet.indexOf(endMarker, start);
+        if (end !== -1) {
+            const next = stylesheet.slice(0, start) + block + stylesheet.slice(end + endMarker.length);
+            return next === stylesheet ? null : next;
+        }
+    }
+    const sep = stylesheet === '' || stylesheet.endsWith('\n\n') ? '' : stylesheet.endsWith('\n') ? '\n' : '\n\n';
+    return `${stylesheet}${sep}${block}\n`;
+}
+/** Keys already set in a dotenv file (`KEY=…`, `export KEY=…`). */
+export function envKeys(text) {
+    const keys = new Set();
+    for (const line of text.split(/\r?\n/)) {
+        const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+        if (match)
+            keys.add(match[1]);
+    }
+    return keys;
+}
+/** Appends variables the file doesn't define yet; never overwrites a value. */
+export function appendEnv(text, vars) {
+    const existing = envKeys(text);
+    const added = Object.keys(vars).filter(k => !existing.has(k));
+    if (!added.length)
+        return { text, added };
+    const quote = (v) => (/[\s#"'=]/.test(v) ? JSON.stringify(v) : v);
+    const lines = added.map(k => `${k}=${quote(vars[k])}`);
+    const sep = text === '' || text.endsWith('\n') ? '' : '\n';
+    return { text: `${text}${sep}${lines.join('\n')}\n`, added };
+}
+export async function applyCss(tokensFile, item) {
+    if (!hasCss(item))
+        return false;
+    const current = existsSync(tokensFile) ? await readFile(tokensFile, 'utf8') : '';
+    const next = upsertCssBlock(current, item.name, itemCss(item));
+    if (next === null)
+        return false;
+    await writeFile(tokensFile, next, 'utf8');
+    return true;
+}
+export async function applyEnv(envFile, item) {
+    if (!item.envVars || !Object.keys(item.envVars).length)
+        return [];
+    const current = existsSync(envFile) ? await readFile(envFile, 'utf8') : '';
+    const { text, added } = appendEnv(current, item.envVars);
+    if (added.length)
+        await writeFile(envFile, text, 'utf8');
+    return added;
+}

package/dist/files.js

@@ -0,0 +1,49 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import * as path from 'node:path';
+import { UipkgeError } from './errors.js';
+import { resolveTarget } from './project.js';
+/** Files of an item that have a destination. */
+export function targetedFiles(item) {
+    return item.files.filter((f) => typeof f.target === 'string' && f.target !== '');
+}
+/** Installed = every one of the item's target files exists. Works on index items (no content needed). */
+export function isItemInstalled(root, item) {
+    const files = targetedFiles(item);
+    return files.length > 0 && files.every(f => existsSync(resolveTarget(root, f.target)));
+}
+export const normalizeEol = (text) => text.replace(/\r\n?/g, '\n');
+/**
+ * Files that already exist with different content (line endings aside). Writing
+ * the rest of the item around them would mix your file with the registry's, so
+ * `add` stops on these unless told to overwrite.
+ */
+export function conflictingFiles(root, item) {
+    return targetedFiles(item).flatMap(f => {
+        const abs = resolveTarget(root, f.target);
+        if (!existsSync(abs) || typeof f.content !== 'string')
+            return [];
+        return normalizeEol(readFileSync(abs, 'utf8')) === normalizeEol(f.content) ? [] : [path.relative(root, abs)];
+    });
+}
+export async function writeItemFiles(root, item, overwrite) {
+    const result = { written: [], kept: [] };
+    const files = targetedFiles(item);
+    if (!files.length)
+        throw new UipkgeError(`Registry item \`${item.name}\` has no files to install.`);
+    for (const file of files) {
+        if (typeof file.content !== 'string') {
+            throw new UipkgeError(`Registry item \`${item.name}\` is missing the content of ${file.target}.`);
+        }
+        const abs = resolveTarget(root, file.target);
+        const rel = path.relative(root, abs);
+        if (existsSync(abs) && !overwrite) {
+            result.kept.push(rel);
+            continue;
+        }
+        await mkdir(path.dirname(abs), { recursive: true });
+        await writeFile(abs, file.content, 'utf8');
+        result.written.push(rel);
+    }
+    return result;
+}

package/dist/index.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import * as path from 'node:path';
+import { parseArgs } from 'node:util';
+import { normalizeOptionalValues } from './args.js';
+import { runAdd } from './commands/add.js';
+import { runBuild } from './commands/build.js';
+import { runDiff } from './commands/diff.js';
+import { runInfo } from './commands/info.js';
+import { runInit } from './commands/init.js';
+import { runList } from './commands/list.js';
+import { runMcp } from './commands/mcp.js';
+import { runView } from './commands/view.js';
+import { UipkgeError } from './errors.js';
+import { color, log, setSilent } from './output.js';
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+const COMMAND_HELP = [
+    ['init', 'set up Tailwind, the cn() helper, tokens and components.json'],
+    ['add [items...]', 'add components (and what they depend on)'],
+    ['list [@ns] [query]', 'list available components (alias: ls)'],
+    ['view <items...>', "show a component's details and files"],
+    ['diff [item]', 'compare installed components with the registry'],
+    ['info', 'show project, config and registry details'],
+    ['build [file]', 'build your own registry (registry.json → public/r)'],
+    ['mcp', 'run an MCP server so AI assistants can browse components'],
+];
+/** Called as `uipkge` (the alias package), help says so. */
+const CLI_NAMES = new Set(['uipkge-ng', 'uipkge']);
+const invokedAs = path.basename(process.argv[1] ?? '').replace(/\.[cm]?js$/, '');
+const NAME = CLI_NAMES.has(invokedAs) ? invokedAs : 'uipkge-ng';
+const HELP = `${NAME} ${VERSION} — add uipkge Angular components to your project
+
+Usage
+${COMMAND_HELP.map(([cmd, desc]) => `  ${`${NAME} ${cmd}`.padEnd(NAME.length + 21)}${desc}`).join('\n')}
+
+Items are names (button), @registry/name, item URLs (https://…/x.json) or local files (./x.json).
+
+Options
+  -c, --cwd <dir>       run in another directory
+  -y, --yes             don't ask for confirmation
+  -o, --overwrite       replace existing files (init, add)
+  -a, --all             add every component (add)
+  -p, --path <dir>      put the requested components in <dir> (add)
+      --dry-run         show what add would change, without changing it
+      --view[=<path>]   print the files add would write (optionally only matching <path>)
+      --diff[=<path>]   diff the files add would write against yours
+  -s, --silent          only print errors
+      --category <c>    only one category (list)
+  -i, --installed       only installed components (list)
+      --json            machine-readable output (list, view, info)
+      --output <dir>    where build writes the registry (default public/r)
+      --debug           show stack traces on errors
+  -h, --help            show this help
+  -v, --version         show the version
+
+Registry: https://uipkge.dev/r/angular (override with components.json "registryUrl" or UIPKGE_REGISTRY_URL)
+`;
+const COMMANDS = new Set(['init', 'add', 'list', 'ls', 'view', 'diff', 'info', 'build', 'mcp']);
+const OPTION_COMMANDS = {
+    overwrite: ['init', 'add'],
+    all: ['add'],
+    path: ['add'],
+    'dry-run': ['add'],
+    view: ['add'],
+    diff: ['add'],
+    category: ['list', 'ls'],
+    installed: ['list', 'ls'],
+    json: ['list', 'ls', 'view', 'info'],
+    output: ['build'],
+};
+async function main(argv) {
+    const { values, positionals } = parseArgs({
+        args: normalizeOptionalValues(argv),
+        allowPositionals: true,
+        options: {
+            cwd: { type: 'string', short: 'c' },
+            yes: { type: 'boolean', short: 'y', default: false },
+            overwrite: { type: 'boolean', short: 'o', default: false },
+            all: { type: 'boolean', short: 'a', default: false },
+            path: { type: 'string', short: 'p' },
+            'dry-run': { type: 'boolean', default: false },
+            view: { type: 'string' },
+            diff: { type: 'string' },
+            silent: { type: 'boolean', short: 's', default: false },
+            category: { type: 'string' },
+            installed: { type: 'boolean', short: 'i', default: false },
+            json: { type: 'boolean', default: false },
+            output: { type: 'string' },
+            debug: { type: 'boolean', default: false },
+            help: { type: 'boolean', short: 'h', default: false },
+            version: { type: 'boolean', short: 'v', default: false },
+        },
+    });
+    if (values.version)
+        return void process.stdout.write(`${VERSION}\n`);
+    const [command, ...rest] = positionals;
+    if (values.help || !command)
+        return void process.stdout.write(HELP);
+    if (!COMMANDS.has(command)) {
+        throw new UipkgeError(`Unknown command \`${command}\`.`, 'Run `uipkge-ng --help` to see the commands.');
+    }
+    // An option a command ignores would silently do the wrong thing (`init --dry-run` really initializing).
+    for (const [option, commands] of Object.entries(OPTION_COMMANDS)) {
+        const value = values[option];
+        if (value !== undefined && value !== false && !commands.includes(command)) {
+            throw new UipkgeError(`--${option} doesn't apply to \`${command}\`.`, `It works with: ${commands.filter(c => c !== 'ls').join(', ')}.`);
+        }
+    }
+    setSilent(values.silent);
+    const cwd = values.cwd ?? process.cwd();
+    switch (command) {
+        case 'init':
+            return runInit({ cwd, yes: values.yes, overwrite: values.overwrite });
+        case 'add':
+            return runAdd({
+                cwd,
+                names: rest,
+                all: values.all,
+                yes: values.yes,
+                overwrite: values.overwrite,
+                path: values.path,
+                dryRun: values['dry-run'],
+                view: values.view,
+                diff: values.diff,
+            });
+        case 'list':
+        case 'ls':
+            // `list @acme [query]` lists a named registry.
+            return rest[0]?.startsWith('@')
+                ? runList({ cwd, namespace: rest[0], query: rest[1], category: values.category, installedOnly: values.installed, json: values.json })
+                : runList({ cwd, query: rest[0], category: values.category, installedOnly: values.installed, json: values.json });
+        case 'view':
+            return runView({ cwd, items: rest, json: values.json });
+        case 'diff':
+            return runDiff({ cwd, name: rest[0] });
+        case 'info':
+            return runInfo({ cwd, json: values.json, version: VERSION });
+        case 'build':
+            return runBuild({ cwd, registry: rest[0] ?? 'registry.json', output: values.output ?? 'public/r' });
+        case 'mcp':
+            return runMcp({ cwd, version: VERSION });
+    }
+}
+main(process.argv.slice(2)).catch((error) => {
+    if (error instanceof UipkgeError) {
+        log.error(error.message);
+        if (error.hint)
+            process.stderr.write(`  ${color.dim(error.hint)}\n`);
+    }
+    else if (error instanceof Error && error.code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION') {
+        log.error(error.message);
+        process.stderr.write(`  ${color.dim('Run `uipkge-ng --help` to see the options.')}\n`);
+    }
+    else {
+        log.error(error instanceof Error ? error.message : String(error));
+        if (process.argv.includes('--debug') && error instanceof Error)
+            process.stderr.write(`${error.stack}\n`);
+        else
+            process.stderr.write(`  ${color.dim('Re-run with --debug for details.')}\n`);
+    }
+    process.exitCode = 1;
+});