npm - uipkge-ng - Versions diffs - 0.1.0 - Mend

uipkge-ng 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,22 @@
+MIT License
+Copyright (c) 2026 Uday Adaka
+uipkge (https://uipkge.dev) - uipkge-ng, the uipkge CLI for Angular
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,371 @@
+# uipkge-ng
+**Add [uipkge](https://uipkge.dev) components to your Angular app — as source you own.**
+uipkge-ng is the Angular CLI for the uipkge registry, in the spirit of shadcn/ui: it copies each component's source into your project, installs what it needs and wires up Tailwind. There's no runtime package to depend on and no version to upgrade — the code is yours to read and change.
+```bash
+npx uipkge-ng init
+npx uipkge-ng add button dialog date-picker
+```
+```ts
+import { UiButtonComponent } from '@/ui/button';
+```
+```html
+<button ui-button variant="outline">Save</button>
+```
+- **One command to set up** — Tailwind CSS v4, the `cn()` helper, design tokens (light and dark) and tsconfig paths.
+- **Dependencies resolved** — adding `date-picker` brings `calendar`, `popover` and their npm packages; `@angular/*` packages are pinned to your Angular version.
+- **Safe in real projects** — it never overwrites your files without asking, works in multi-project workspaces and monorepos, and follows your folder layout.
+- **Your own registries too** — install from private registries with auth, or publish your own with `uipkge-ng build`.
+- **AI-ready** — `uipkge-ng mcp` lets assistants browse components and their source.
+## Contents
+- [Requirements](#requirements)
+- [Getting started](#getting-started)
+- [Commands](#commands)
+- [Existing projects](#existing-projects)
+- [Workspaces and monorepos](#workspaces-and-monorepos)
+- [components.json](#componentsjson)
+- [Custom folders](#custom-folders)
+- [Registries](#registries)
+- [Publishing your own registry](#publishing-your-own-registry)
+- [AI assistants (MCP)](#ai-assistants-mcp)
+- [CI and scripting](#ci-and-scripting)
+- [Troubleshooting](#troubleshooting)
+## Requirements
+- Node.js **20.12** or newer
+- An Angular CLI application with standalone components (Analog/Vite supported; Nx workspaces not yet)
+- npm, pnpm, yarn or bun — detected from your lockfile
+## Getting started
+Run it without installing:
+```bash
+npx uipkge-ng init          # or: pnpm dlx uipkge-ng init / bunx uipkge-ng init
+```
+or add it to the project and use it from there:
+```bash
+npm i -D uipkge-ng
+npx uipkge-ng add button
+```
+`init` shows what it did:
+```text
+✔ uipkge is ready.
+  ✔ Tailwind CSS v4 set up
+  ✔ tsconfig paths `@/*` and `@/ui/*` added (tsconfig.json)
+  ✔ cn() helper written (src/lib/utils.ts)
+  ✔ design tokens written (src/uipkge.css)
+  ✔ src/styles.css imports ./uipkge.css
+  ✔ components.json written
+```
+Then add components — by name, or run `uipkge-ng add` on its own to pick from a searchable list:
+```bash
+npx uipkge-ng add card dialog
+npx uipkge-ng list            # everything available, ✔ on what you have
+```
+Dark mode follows a `dark` class on `<html>`.
+`@uipkge/ng` and `uipkge` are aliases of the same CLI — `npx @uipkge/ng add button` and `npx uipkge add button` work too.
+## Commands
+| Command | |
+| --- | --- |
+| [`init`](#init) | set up the project |
+| [`add [items...]`](#add) | add components and their dependencies |
+| [`list [@registry] [query]`](#list) | browse components (alias `ls`) |
+| [`view <items...>`](#view) | show a component's details and source |
+| [`diff [item]`](#diff) | compare your copies with the registry |
+| [`info`](#info) | project, config and registry details |
+| [`build [registry.json]`](#publishing-your-own-registry) | build your own registry |
+| [`mcp`](#ai-assistants-mcp) | MCP server for AI assistants |
+Items can be names (`button`), named-registry items (`@acme/card`), item URLs (`https://…/card.json`) or local item files (`./card.json`).
+### init
+Sets the project up once:
+- installs **Tailwind CSS v4** if it's missing (`tailwindcss`, `@tailwindcss/postcss`, `postcss`) and creates or extends your PostCSS config
+- adds the `@/*` and `@/ui/*` paths to your tsconfig — comments, formatting and existing paths are kept
+- writes the `cn()` helper to `src/lib/utils.ts`
+- writes the design tokens to `src/uipkge.css` and imports them from your global stylesheet (found in `angular.json`). With a Sass/Less stylesheet, `src/uipkge.css` is added to the app's `styles` in `angular.json` instead
+- writes `components.json`
+Nothing on the network can fail halfway: everything is fetched before the project is touched. Re-running is safe; `--overwrite` rewrites the foundation files.
+### add
+```bash
+uipkge-ng add button dialog
+uipkge-ng add --all
+uipkge-ng add @acme/card
+```
+Adds the components and everything they depend on — other components first, then npm packages. Components you already have are left as they are.
+| Flag | |
+| --- | --- |
+| `--dry-run` | list every file that would be created, overwritten or kept, the npm packages and extras — nothing is written |
+| `--view[=<path>]` | print the files that would be written (optionally only those matching `<path>`) |
+| `--diff[=<path>]` | show how they'd differ from your files |
+| `-p, --path <dir>` | put the requested components in `<dir>` (their dependencies stay in the usual folder) |
+| `-o, --overwrite` | replace existing files |
+| `-a, --all` | add every component |
+| `-y, --yes` | don't ask for confirmation |
+Unknown names stop the command before anything changes. Items can also carry install-time extras, which `add` applies:
+- `cssVars` / `css` → a marked block in `src/uipkge.css`, replaced (not duplicated) on reinstall; colour variables are registered with Tailwind, so `bg-<name>` works
+- `envVars` → appended to `.env`; existing keys are never touched
+- `docs` → printed after install
+### list
+```bash
+uipkge-ng list                 # grouped by category
+uipkge-ng list date            # search names and descriptions
+uipkge-ng list --category form
+uipkge-ng list --installed
+uipkge-ng list @acme           # a named registry
+```
+Works outside a project too. `--json` for scripts.
+### view
+```bash
+uipkge-ng view date-picker
+```
+Everything an install would bring — description, dependencies, notes and the full source of every file — without installing. `--json` prints the raw item.
+### diff
+```bash
+uipkge-ng diff                 # which installed components differ from the registry
+uipkge-ng diff button          # the unified diff for one
+```
+Checks what you installed from the default registry and from every named one. Takes any item form: `button`, `@acme/card`, a URL or a local file. Line-ending differences are ignored. To take the registry version, `uipkge-ng add button --overwrite`.
+### info
+Prints the CLI and Node versions, the project (app, Angular, package manager, Tailwind, PostCSS), `components.json`, the folders your aliases resolve to, whether the registry is reachable and what's installed. Paste it into bug reports; `--json` for machines.
+## Existing projects
+uipkge-ng is built to be run on apps that already have code in them:
+- **Your files are never overwritten silently.** If a file `add` would write already exists with different content — say your own `button.component.ts` — it stops before writing anything. Interactively it asks; otherwise re-run with `--overwrite`, or install elsewhere with `--path src/app/uipkge`.
+- **Your styles stay yours.** Tokens live in their own file (`src/uipkge.css`); your stylesheet only gains one import line.
+- **Your tsconfig stays yours.** Existing paths are kept. If `@/*` already points somewhere else, uipkge's path is added as a fallback and the helper goes where your mapping resolves.
+- **Your `utils.ts` stays yours.** If `src/lib/utils.ts` exists, `init` keeps it and warns if it doesn't export `cn()`.
+- **Try first.** `add --dry-run` shows exactly what would change, `add --diff` shows how.
+## Workspaces and monorepos
+**Angular multi-project workspaces** (`ng new --create-application=false`, apps under `projects/`): run uipkge-ng inside the app's folder, or pass it with `-c`:
+```bash
+npx uipkge-ng init -c projects/admin
+npx uipkge-ng add button -c projects/admin
+```
+Each app gets its own `components.json`, tokens and paths — written to its `tsconfig.app.json` and `tsconfig.spec.json`, keeping the paths it inherits. Packages are installed once, for the workspace. At the workspace root, uipkge-ng asks you to choose rather than guess.
+**npm, pnpm, yarn and bun workspaces**: run it in the app (`apps/web`). The package manager comes from the workspace's lockfile.
+**Nx** isn't supported yet.
+## components.json
+`init` writes it; you can edit it by hand.
+```json
+{
+  "framework": "angular",
+  "registryUrl": "https://uipkge.dev/r/angular",
+  "styles": "src/styles.css",
+  "tokens": "src/uipkge.css",
+  "aliases": {
+    "ui": "@/ui",
+    "lib": "@/lib",
+    "blocks": "@/app/components/blocks"
+  },
+  "registries": {}
+}
+```
+| Field | |
+| --- | --- |
+| `registryUrl` | the default registry (the `UIPKGE_REGISTRY_URL` environment variable overrides it) |
+| `styles` | your global stylesheet, which imports the tokens |
+| `tokens` | the file uipkge owns for design tokens and item CSS |
+| `aliases` | where components, helpers and blocks go — see [Custom folders](#custom-folders) |
+| `registries` | named and private registries — see [Registries](#registries) |
+## Custom folders
+By default components go to `src/app/components/ui`, helpers to `src/lib` and blocks to `src/app/components/blocks`. For your own layout, point `aliases` at import aliases your tsconfig `paths` map:
+```json
+{ "aliases": { "ui": "@shared/ui", "lib": "@core/lib", "blocks": "@shared/blocks" } }
+```
+```jsonc
+// tsconfig.json
+"paths": { "@shared/*": ["./src/app/shared/*"], "@core/*": ["./src/app/core/*"] }
+```
+Every command then uses those folders, and the `@/ui/…` and `@/lib/…` imports inside component sources are rewritten to your aliases. An alias that `paths` doesn't map is an error, so files never land somewhere unexpected. `uipkge-ng info` shows where each alias resolves.
+## Registries
+Components come from `https://uipkge.dev/r/angular` unless you configure otherwise. Any shadcn-style registry works — a public one, your company's private one, or one you [build yourself](#publishing-your-own-registry).
+### Changing the default registry
+Set `registryUrl` in `components.json`, or `UIPKGE_REGISTRY_URL` in the environment (it wins, which is handy for mirrors and CI):
+```json
+{ "registryUrl": "https://registry.acme.dev/r" }
+```
+Bare names (`uipkge-ng add card`) then come from that registry. It doesn't need to ship the foundation: if it has no `utils` or `tailwind` item, `init` takes uipkge's and says so.
+### Named and private registries
+To use several registries side by side, add them under `registries`; their items are then `@name/item`:
+```json
+{
+  "registries": {
+    "@acme": "https://acme.dev/r/{name}.json",
+    "@internal": {
+      "url": "https://registry.internal.dev/{name}.json",
+      "headers": { "Authorization": "Bearer ${INTERNAL_TOKEN}" },
+      "params": { "v": "2" }
+    }
+  }
+}
+```
+```bash
+uipkge-ng add @acme/card
+uipkge-ng list @internal
+uipkge-ng view @internal/data-table
+```
+- `{name}` becomes the item name; `list` reads the index at `{name}` = `registry`.
+- `${VAR}` in headers comes from the environment, then `.env.local`, then `.env`. A missing variable is an error before any request is made.
+- Headers are only ever sent to that registry's own URLs.
+- `list @name`, `info` and `diff` show which of its items you have. Items added from a URL or a file can be checked with `uipkge-ng diff <url-or-file>`.
+## Publishing your own registry
+Describe your items in a `registry.json`, pointing at your source files:
+```json
+{
+  "name": "acme",
+  "homepage": "https://acme.dev",
+  "items": [
+    {
+      "name": "stat-card",
+      "type": "registry:ui",
+      "description": "A labelled number.",
+      "registryDependencies": ["badge"],
+      "dependencies": [],
+      "files": [
+        {
+          "path": "src/stat-card/stat-card.ts",
+          "type": "registry:ui",
+          "target": "~/src/app/components/ui/stat-card/stat-card.ts"
+        }
+      ]
+    }
+  ]
+}
+```
+```bash
+npx uipkge-ng build                       # → public/r/stat-card.json, public/r/registry.json
+npx uipkge-ng build path/to/registry.json --output dist/r
+```
+`build` inlines each file's content into `<item>.json` and writes a `registry.json` index. It checks everything first — names, duplicates, missing files, paths or targets outside the project, dependency formats — reports every problem at once and writes nothing until they all pass.
+In `registryDependencies`, a bare name (`badge`) is a uipkge component — `build` writes it as its full uipkge URL, so it resolves the same in every project, whatever that project's default registry is. For your own items use `@acme/name` or a full URL; a bare name that matches one of your items is reported as an error. Import `cn` from `@/lib/utils` and other components from `@/ui/…` in your sources — installs rewrite those to each project's aliases. Serve the output folder anywhere static and add it to `registries`.
+## AI assistants (MCP)
+`uipkge-ng mcp` runs a read-only [Model Context Protocol](https://modelcontextprotocol.io) server on stdio, so assistants can find components and read their real source instead of guessing APIs:
+| Tool | |
+| --- | --- |
+| `list_components` | search by query, category or named registry |
+| `view_components` | details, dependencies, notes and full source |
+| `get_add_command` | the `npx uipkge-ng add …` command, checked against the registry |
+| `list_registries` | the default and named registries this project can use |
+It never writes files — installing stays a command you run. It reads the `components.json` of the directory it starts in, named registries included.
+```json
+// .mcp.json — Claude Code, Cursor and others use the same shape
+{ "mcpServers": { "uipkge": { "command": "npx", "args": ["-y", "uipkge-ng", "mcp"] } } }
+```
+## CI and scripting
+- Confirmations are skipped automatically when there's no TTY or `CI` is set; `-y` skips them anywhere.
+- Without a TTY, `add` with no names is an error — pass names or `--all`.
+- A file conflict fails with exit code 1 and nothing written; pass `--overwrite` if replacing is intended.
+- `-s, --silent` prints only errors (package-manager output appears only if it fails).
+- `list`, `view` and `info` take `--json`.
+- An option a command doesn't use is an error, not ignored — `init --dry-run` fails rather than initializing.
+- `NO_COLOR` turns colours off.
+| Option | |
+| --- | --- |
+| `-c, --cwd <dir>` | run in another directory |
+| `-y, --yes` | don't ask for confirmation |
+| `-s, --silent` | only print errors |
+| `--debug` | stack traces on errors |
+| `-h, --help` / `-v, --version` | |
+## Troubleshooting
+| Message | Fix |
+| --- | --- |
+| `No components.json found` | run `uipkge-ng init` first |
+| `This workspace has 2 apps: …` | run inside the app's folder, or pass `-c projects/<app>` |
+| `N files already exist with different content` | keep yours and use `--path`, or replace with `--overwrite` |
+| `The "ui" alias "…" is not mapped in tsconfig.json "paths"` | add the mapping, or reset `aliases` to the defaults |
+| `Registry "@acme" needs the environment variable ACME_TOKEN` | set it in your shell, `.env.local` or `.env` |
+| `Nx workspaces are not supported yet` | use a standalone Angular CLI app for now |
+Still stuck? Include the output of `npx uipkge-ng info` when you [open an issue](https://github.com/uday-a/uipkge-cli/issues).
+## Credits
+Created by **Uday Adaka** as part of **[uipkge](https://uipkge.dev)**. It uses the [shadcn/ui](https://ui.shadcn.com) registry format, so any registry in that format can serve Angular items to it.
+## License
+[MIT](./LICENSE) © 2026 Uday Adaka — uipkge. You can use, change and redistribute it freely; keep the copyright and license notice in copies of the CLI.

package/dist/args.js ADDED Viewed

@@ -0,0 +1,7 @@
+/**
+ * `--view` / `--diff` take an optional value (`--view` or `--view=src/x.ts`),
+ * which node's parseArgs can't express; a bare flag becomes `--flag=` (all files).
+ */
+export function normalizeOptionalValues(argv) {
+    return argv.map(arg => (arg === '--view' || arg === '--diff' ? `${arg}=` : arg));
+}

package/dist/commands/add.js ADDED Viewed

@@ -0,0 +1,216 @@
+import { existsSync, readFileSync } from 'node:fs';
+import * as path from 'node:path';
+import { registryFor, requireConfig } from '../config.js';
+import { UipkgeError } from '../errors.js';
+import { applyCss, applyEnv, envKeys, hasCss } from '../extras.js';
+import { conflictingFiles, isItemInstalled, targetedFiles, writeItemFiles } from '../files.js';
+import { adaptItem, resolveLayout } from '../layout.js';
+import { color, log, plural } from '../output.js';
+import { installPackages, missingPackages, pinAngular } from '../packages.js';
+import { declaredDependencies, loadProject, resolveTarget } from '../project.js';
+import { confirm, isInteractive, pickComponents } from '../prompts.js';
+import { planInstall } from '../resolve.js';
+import { colorPatch, compareItem } from './diff.js';
+import { firstSentence, isListable } from './list.js';
+export const DEFAULT_UI_DIR = 'src/app/components/ui';
+/**
+ * `--path shared/ui` moves an item's files from the UI folder to `shared/ui`,
+ * keeping the per-component subfolder. Files outside the UI folder (e.g.
+ * `src/lib/…`) stay put. Only requested items move: their dependencies stay in
+ * the UI folder, where the `@/ui/*` imports expect them.
+ */
+export function relocate(item, dir, uiDir = DEFAULT_UI_DIR) {
+    const base = dir.replace(/\\/g, '/').replace(/^\.?\/+/, '').replace(/\/+$/, '');
+    const from = `~/${uiDir}/`;
+    return {
+        ...item,
+        files: item.files.map(f => (f.target?.startsWith(from) ? { ...f, target: `~/${base}/${f.target.slice(from.length)}` } : f)),
+    };
+}
+export async function runAdd(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 preview = options.dryRun || options.view !== undefined || options.diff !== undefined;
+    const layout = resolveLayout(root, config.aliases);
+    let names = [...new Set(options.names)];
+    if (options.all || !names.length) {
+        const listable = (await registry.index()).items.filter(isListable);
+        if (options.all)
+            names = listable.map(i => i.name);
+        else if (!isInteractive()) {
+            throw new UipkgeError('No components given.', 'Pass names (`uipkge-ng add button dialog`) or --all. See `uipkge-ng list`.');
+        }
+        else {
+            names = await pickComponents(listable.map(i => ({
+                value: i.name,
+                label: i.name,
+                hint: isItemInstalled(root, adaptItem(i, layout)) ? 'installed' : firstSentence(i.description ?? '').slice(0, 60),
+            })));
+        }
+    }
+    log.step('Resolving components');
+    const plan = await planInstall(registry, names, item => isItemInstalled(root, item), options.overwrite || preview, (item, requested) => {
+        const adapted = adaptItem(item, layout);
+        return requested && options.path ? relocate(adapted, options.path, layout.dirs.ui) : adapted;
+    });
+    const declared = declaredDependencies(project.packageJson);
+    const packages = missingPackages(pinAngular(plan.dependencies, project.angularCore), declared);
+    const devPackages = missingPackages(pinAngular(plan.devDependencies, project.angularCore), declared);
+    // Previews cover what you asked for, plus dependencies that would actually be new.
+    const previewPlan = { ...plan, install: plan.install.filter(i => plan.requested.includes(i.name) || !isItemInstalled(root, i)) };
+    if (options.view !== undefined)
+        return printView(previewPlan, options.view);
+    if (options.diff !== undefined)
+        return printDiff(root, previewPlan, options.diff);
+    if (options.dryRun)
+        return printDryRun(root, config.tokens, plan, packages, devPackages, options.overwrite);
+    if (!plan.install.length) {
+        log.info(`Already installed: ${plan.skipped.join(', ')}. ${color.dim('Use --overwrite to reinstall.')}`);
+        return;
+    }
+    // Existing files that differ: never write the rest of an item around them.
+    let overwrite = options.overwrite;
+    const conflicts = overwrite ? [] : plan.install.flatMap(item => conflictingFiles(root, item).map(file => `${file} (${item.name})`));
+    if (conflicts.length) {
+        const list = conflicts.map(c => `  • ${c}`).join('\n');
+        if (options.yes || !isInteractive()) {
+            throw new UipkgeError(`${plural(conflicts.length, 'file')} already exist${conflicts.length === 1 ? 's' : ''} with different content:\n${list}`, 'Nothing was changed. Re-run with --overwrite to replace them, or --path <dir> to add the component somewhere else.');
+        }
+        log.warn(`These files already exist with different content:\n${list}`);
+        if (!(await confirm(`Overwrite ${conflicts.length === 1 ? 'it' : 'them'}?`, false))) {
+            log.info('Nothing was changed.');
+            return;
+        }
+        overwrite = true;
+    }
+    if (!options.yes && isInteractive()) {
+        log.info(`${color.bold('Will add')} ${plan.install.map(i => i.name).join(', ')}`);
+        if (packages.length || devPackages.length)
+            log.info(`${color.bold('npm')}      ${[...packages, ...devPackages].join(', ')}`);
+        if (!(await confirm('Continue?'))) {
+            log.info('Nothing was changed.');
+            return;
+        }
+    }
+    if (packages.length || devPackages.length) {
+        log.step(`Installing ${[...packages, ...devPackages].join(', ')}`);
+        await installPackages(project.packageManager, project.packageRoot, packages);
+        await installPackages(project.packageManager, project.packageRoot, devPackages, true);
+    }
+    const kept = [];
+    const docs = [];
+    const tokensFile = path.join(root, config.tokens);
+    for (const item of plan.install) {
+        const result = await writeItemFiles(root, item, overwrite);
+        kept.push(...result.kept);
+        const extras = [];
+        if (await applyCss(tokensFile, item))
+            extras.push(`css → ${config.tokens}`);
+        const envAdded = await applyEnv(path.join(root, '.env'), item);
+        if (envAdded.length)
+            extras.push(`.env: ${envAdded.join(', ')}`);
+        if (item.tailwind)
+            log.warn(`${item.name} ships a Tailwind v3 config; Tailwind v4 reads config from CSS, so it was not applied.`);
+        if (item.docs)
+            docs.push([item.name, item.docs]);
+        log.success(`${item.name} ${color.dim(`(${[plural(result.written.length, 'file'), ...extras].join(', ')})`)}`);
+    }
+    log.blank();
+    log.info(`${color.green('✔')} Added ${plural(plan.install.length, 'component')}.`);
+    if (plan.skipped.length)
+        log.info(color.dim(`  Already installed, left as is: ${plan.skipped.join(', ')}`));
+    if (kept.length)
+        log.info(color.dim(`  Existing files kept (use --overwrite to replace): ${kept.join(', ')}`));
+    for (const [name, text] of docs) {
+        log.blank();
+        log.info(`${color.bold(`Notes from ${name}:`)}\n${text.trim()}`);
+    }
+}
+function fileStates(root, item, overwrite) {
+    return targetedFiles(item).map(f => {
+        const abs = resolveTarget(root, f.target);
+        const differs = conflictingFiles(root, { ...item, files: [f] }).length > 0;
+        return { file: path.relative(root, abs), state: !existsSync(abs) ? 'new' : overwrite ? 'overwrite' : differs ? 'conflict' : 'keep' };
+    });
+}
+function printDryRun(root, tokens, plan, packages, devPackages, overwrite) {
+    const toWrite = plan.install.filter(item => overwrite || !isItemInstalled(root, item));
+    const already = plan.install.filter(item => !overwrite && isItemInstalled(root, item)).map(i => i.name);
+    log.info(color.bold('Dry run — nothing will be written.'));
+    if (!toWrite.length) {
+        log.info(`All of it is already installed: ${[...already, ...plan.skipped].join(', ')}.`);
+        return;
+    }
+    const label = {
+        new: color.green('new      '),
+        overwrite: color.yellow('overwrite'),
+        keep: color.dim('keep     '),
+        conflict: color.red('conflict '),
+    };
+    for (const item of toWrite) {
+        log.blank();
+        log.info(color.bold(item.name));
+        for (const { file, state } of fileStates(root, item, overwrite))
+            log.info(`  ${label[state]} ${file}`);
+        if (hasCss(item))
+            log.info(`  ${color.cyan('css      ')} block in ${tokens}`);
+        if (item.envVars) {
+            const envFile = path.join(root, '.env');
+            const existing = existsSync(envFile) ? envKeys(readFileSync(envFile, 'utf8')) : new Set();
+            const add = Object.keys(item.envVars).filter(k => !existing.has(k));
+            if (add.length)
+                log.info(`  ${color.cyan('env      ')} .env: ${add.join(', ')}`);
+        }
+        if (item.docs)
+            log.info(`  ${color.cyan('notes    ')} shown after install`);
+    }
+    if (already.length)
+        log.info(color.dim(`\nAlready installed (skipped): ${already.join(', ')}`));
+    if (packages.length)
+        log.info(`\n${color.bold('npm install')} ${packages.join(' ')}`);
+    if (devPackages.length)
+        log.info(`${color.bold('npm install -D')} ${devPackages.join(' ')}`);
+    const conflicts = overwrite ? 0 : toWrite.reduce((n, item) => n + conflictingFiles(root, item).length, 0);
+    if (conflicts)
+        log.warn(`${plural(conflicts, 'file')} differ${conflicts === 1 ? 's' : ''} from yours; add will stop unless you pass --overwrite.`);
+    log.info(color.dim('\nRun again without --dry-run to apply.'));
+}
+function matches(file, filter) {
+    return !filter || file.replace(/\\/g, '/').includes(filter.replace(/\\/g, '/').replace(/^\.?\//, ''));
+}
+function printView(plan, filter) {
+    let shown = 0;
+    for (const item of plan.install) {
+        for (const f of targetedFiles(item)) {
+            const file = f.target.replace(/^~\//, '');
+            if (!matches(file, filter))
+                continue;
+            shown++;
+            process.stdout.write(`${color.bold(`── ${file}`)} ${color.dim(`(${item.name})`)}\n${f.content ?? ''}\n`);
+        }
+    }
+    if (!shown)
+        log.info(filter ? `No file matches "${filter}".` : 'No files.');
+}
+async function printDiff(root, plan, filter) {
+    let changed = 0;
+    let fresh = 0;
+    for (const item of plan.install) {
+        for (const status of await compareItem(root, item)) {
+            if (!matches(status.file, filter))
+                continue;
+            if (status.status === 'changed') {
+                changed++;
+                process.stdout.write(`${colorPatch(status.patch)}\n`);
+            }
+            else if (status.status === 'missing') {
+                fresh++;
+                log.info(`${color.green('new file')} ${status.file} ${color.dim(`(${item.name})`)}`);
+            }
+        }
+    }
+    if (!changed && !fresh)
+        log.success(filter ? `No differences in files matching "${filter}".` : 'No differences — your files match the registry.');
+}