shadcn-nsh 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# shadcn-nsh
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[中文](./README.zh.md)
+
+CLI for adding styled NSH components (copy-into-app) from the shadcn-nsh registry.
+
+```sh
+bunx shadcn-nsh@latest init -c apps/web
+bunx shadcn-nsh@latest add button
+```
+
+Default registry: `https://raw.githubusercontent.com/aningdev/shadcn-nsh/main/public/r/{name}.json`.
+
+## Commands
+
+| Command             | What it does                                                         |
+| ------------------- | -------------------------------------------------------------------- |
+| `init`              | Writes `nsh-ui.json`, installs `theme`, points each `nsh.json` at it |
+| `add [components…]` | Copies items and their `registryDependencies` into the app           |
+| `list`              | The registry's items, `✓` on the ones the app has                    |
+| `view <items…>`     | The files `add` would write: target paths and contents               |
+| `diff [items…]`     | The app's files against the registry's; exit code 1 when they differ |
+| `build`             | Builds `registry.json` into `public/r` (maintaining this registry)   |
+| `serve`             | Serves `public/r` over HTTP for local testing                        |
+
+Every command takes `-c, --cwd <dir>` (default: the current directory). `init`, `add`, `list`,
+`view` and `diff` also take `--registry <url>`, a template with `{name}` in it; without it, `add`,
+`list`, `view` and `diff` use the one in `nsh-ui.json`, and `init` uses the public registry.
+`init` also takes `--overwrite` and `-y` (accepted; nothing prompts today).
+
+## add
+
+```sh
+shadcn-nsh add button -c apps/web
+shadcn-nsh add --all
+shadcn-nsh add button --dry-run
+shadcn-nsh add button --overwrite
+```
+
+- A file the app does not have is written; one identical to the registry's is skipped.
+- A file the app changed is kept and reported: `kept components/ui/button.tsx, differs (run diff)`.
+  `--overwrite` (`-o`) replaces it and prints the change: `overwrite components/ui/button.tsx (+2 -1)`.
+- `theme.json` is merged by key: the app keeps its colors and gains the tokens it lacks. A
+  recolored theme is kept as it is (`kept theme.json (the app's colors stay)`).
+- `--all` (`-a`) adds every `registry:ui` item the catalog lists, dependencies included.
+- `--dry-run` prints the same lines as `would write …` / `would overwrite …` and writes nothing —
+  not even `nsh-ui.json` or the theme `init` would install first.
+
+## list, view, diff
+
+```sh
+shadcn-nsh list
+shadcn-nsh list --json
+shadcn-nsh view button
+shadcn-nsh diff
+shadcn-nsh diff button
+```
+
+`list` reads the catalog (`index.json`) and marks an item when any of its files is in the app.
+
+`view` prints what `add` would write — dependencies first, at their target paths, with imports
+rewritten for this app — and writes nothing.
+
+`diff` compares the same rewritten content with the app's files. Without an item it lists the
+installed items that differ; with one it prints the changed lines. It exits 1 when anything
+differs, so it can gate an update:
+
+```sh
+shadcn-nsh diff || echo "run shadcn-nsh add <item> --overwrite"
+```
+
+Lines are the registry's version against the app's: `-` is a line of the app's file that
+overwriting would drop, `+` one it would add. `theme.json` compares keys, not values — a
+recolored theme is the app's own, and only `add --overwrite` replaces it.
+
+## nsh-ui.json
+
+`init` writes it where components install:
+
+```json
+{
+  "registry": "https://raw.githubusercontent.com/aningdev/shadcn-nsh/main/public/r/{name}.json",
+  "aliases": {
+    "components": "./components",
+    "ui": "./components/ui",
+    "lib": "./lib",
+    "theme": "./lib/theme"
+  }
+}
+```
+
+In a monorepo (`apps/*` + `packages/ui`) it lives in `packages/ui` and `add -c apps/web`
+installs there.
+
+## Develop in this monorepo
+
+```sh
+bun run shadcn-nsh -- --help
+bun run cli:build
+bun run registry:build   # public/r, then e2e against it
+bun run shadcn-nsh -- add button -c apps/web --registry "file://$PWD/public/r/{name}.json"
+```
+
+`bun test packages/cli` runs the command tests against a temporary app and a `file://` registry
+built from `public/r`.

package/README.zh.md

@@ -0,0 +1,100 @@
+# shadcn-nsh
+
+[English](./README.md)
+
+从 shadcn-nsh registry 向应用复制 styled NSH 组件的 CLI。
+
+```sh
+bunx shadcn-nsh@latest init -c apps/web
+bunx shadcn-nsh@latest add button
+```
+
+默认 registry：`https://raw.githubusercontent.com/aningdev/shadcn-nsh/main/public/r/{name}.json`。
+
+## 命令
+
+| 命令                | 作用                                                       |
+| ------------------- | ---------------------------------------------------------- |
+| `init`              | 写 `nsh-ui.json`、装 `theme`、把每个 `nsh.json` 指向它     |
+| `add [components…]` | 复制条目及其 `registryDependencies`                        |
+| `list`              | registry 的全部条目，应用已有的标 `✓`                      |
+| `view <items…>`     | `add` 会写的文件：目标路径与内容                           |
+| `diff [items…]`     | 对比应用内文件与 registry 的；有差异时退出码 1             |
+| `build`             | 把 `registry.json` 构建到 `public/r`（维护本 registry 用） |
+| `serve`             | 用 HTTP 提供 `public/r`，本地测试用                        |
+
+每个命令都接受 `-c, --cwd <dir>`（默认：当前目录）。`init`、`add`、`list`、`view`、`diff`
+另接受 `--registry <url>`（含 `{name}` 的模板）；省略时 `add`、`list`、`view`、`diff` 用
+`nsh-ui.json` 里的，`init` 用公共 registry。`init` 还接受 `--overwrite` 与 `-y`（接受，当前不弹确认）。
+
+## add
+
+```sh
+shadcn-nsh add button -c apps/web
+shadcn-nsh add --all
+shadcn-nsh add button --dry-run
+shadcn-nsh add button --overwrite
+```
+
+- 应用没有的文件写入；与 registry 相同的跳过。
+- 应用改过的文件保留并报告 `kept components/ui/button.tsx, differs (run diff)`。
+  `--overwrite`（`-o`）替换它并打印改动量：`overwrite components/ui/button.tsx (+2 -1)`。
+- `theme.json` 按 key 合并：应用保留自己的颜色，补上缺的 token；改过颜色的主题原样保留
+  （`kept theme.json (the app's colors stay)`）。
+- `--all`（`-a`）加全部 `registry:ui` 条目（含依赖）。
+- `--dry-run` 用 `would write …` / `would overwrite …` 打印同样的行，一个字节都不写——
+  包括 `init` 会先写的 `nsh-ui.json` 与主题。
+
+## list、view、diff
+
+```sh
+shadcn-nsh list
+shadcn-nsh list --json
+shadcn-nsh view button
+shadcn-nsh diff
+shadcn-nsh diff button
+```
+
+`list` 读目录（`index.json`），条目任一文件在应用里就标为已装。
+
+`view` 打印 `add` 会写的内容：依赖在前、目标路径、import 已按本应用改写；不写文件。
+
+`diff` 用同一份改写后的内容与应用里的文件比较。不带条目时列出有差异的已装条目，带条目时
+打印改动的行。有差异时退出码 1，可以用来卡更新：
+
+```sh
+shadcn-nsh diff || echo "run shadcn-nsh add <item> --overwrite"
+```
+
+行以 registry 版本对照应用版本：`-` 是覆盖会删掉的应用中的行，`+` 是它会加的行。
+`theme.json` 按 key 比较、不按值——改过颜色的主题是应用自己的，只有 `add --overwrite`
+会整体替换。
+
+## nsh-ui.json
+
+`init` 把它写在组件安装的地方：
+
+```json
+{
+  "registry": "https://raw.githubusercontent.com/aningdev/shadcn-nsh/main/public/r/{name}.json",
+  "aliases": {
+    "components": "./components",
+    "ui": "./components/ui",
+    "lib": "./lib",
+    "theme": "./lib/theme"
+  }
+}
+```
+
+monorepo（`apps/*` + `packages/ui`）里它位于 `packages/ui`，`add -c apps/web` 装到那里。
+
+## 本仓开发
+
+```sh
+bun run shadcn-nsh -- --help
+bun run cli:build
+bun run registry:build   # 生成 public/r，再用它做端到端
+bun run shadcn-nsh -- add button -c apps/web --registry "file://$PWD/public/r/{name}.json"
+```
+
+`bun test packages/cli` 用临时应用和由 `public/r` 生成的 `file://` registry 跑命令测试。

package/dist/index.js

@@ -0,0 +1,1000 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command as Command8 } from "commander";
+
+// package.json
+var package_default = {
+  name: "shadcn-nsh",
+  version: "0.2.0",
+  description: "Add styled NSH components (copy-into-app) from the shadcn-nsh registry",
+  keywords: [
+    "cli",
+    "components",
+    "nsh",
+    "registry",
+    "shadcn"
+  ],
+  homepage: "https://github.com/aningdev/shadcn-nsh#readme",
+  bugs: {
+    url: "https://github.com/aningdev/shadcn-nsh/issues"
+  },
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/aningdev/shadcn-nsh.git",
+    directory: "packages/cli"
+  },
+  bin: {
+    "shadcn-nsh": "./dist/index.js"
+  },
+  files: [
+    "dist"
+  ],
+  type: "module",
+  publishConfig: {
+    access: "public"
+  },
+  scripts: {
+    build: "tsup",
+    typecheck: "tsc --noEmit",
+    prepublishOnly: "bun run build"
+  },
+  dependencies: {
+    commander: "^15.0.0"
+  },
+  devDependencies: {
+    tsup: "^8.5.0"
+  },
+  engines: {
+    node: ">=20"
+  }
+};
+
+// src/commands/add.ts
+import path10 from "path";
+import { Command as Command2 } from "commander";
+
+// src/types.ts
+var DEFAULT_REGISTRY = "https://raw.githubusercontent.com/aningdev/shadcn-nsh/main/public/r/{name}.json";
+var DEFAULT_CONFIG = () => ({
+  registry: DEFAULT_REGISTRY,
+  aliases: {
+    components: "./components",
+    ui: "./components/ui",
+    lib: "./lib",
+    theme: "./lib/theme"
+  }
+});
+
+// src/utils/app.ts
+import path3 from "path";
+
+// src/utils/config.ts
+import fs from "fs/promises";
+import path from "path";
+var CONFIG_FILE = "nsh-ui.json";
+async function readConfig(cwd) {
+  const file = path.join(cwd, CONFIG_FILE);
+  try {
+    const raw = await fs.readFile(file, "utf8");
+    return { ...DEFAULT_CONFIG(), ...JSON.parse(raw) };
+  } catch {
+    return null;
+  }
+}
+async function writeConfig(cwd, config) {
+  const file = path.join(cwd, CONFIG_FILE);
+  await fs.writeFile(file, `${JSON.stringify(config, null, 2)}
+`, "utf8");
+}
+async function findNshJson(cwd) {
+  const file = path.join(cwd, "nsh.json");
+  try {
+    await fs.access(file);
+    return file;
+  } catch {
+    return null;
+  }
+}
+async function readJson(file) {
+  return JSON.parse(await fs.readFile(file, "utf8"));
+}
+async function writeJson(file, data) {
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, `${JSON.stringify(data, null, 2)}
+`, "utf8");
+}
+
+// src/utils/workspace.ts
+import fs2 from "fs/promises";
+import path2 from "path";
+async function exists(file) {
+  try {
+    await fs2.access(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function isConsumerUiPackage(uiDir) {
+  if (await exists(path2.join(uiDir, CONFIG_FILE))) return true;
+  try {
+    const pkg = JSON.parse(await fs2.readFile(path2.join(uiDir, "package.json"), "utf8"));
+    return pkg.name === "@workspace/ui";
+  } catch {
+    return false;
+  }
+}
+async function findMonorepoRoot(start) {
+  let dir = path2.resolve(start);
+  for (; ; ) {
+    const uiDir = path2.join(dir, "packages", "ui");
+    if (await isConsumerUiPackage(uiDir)) {
+      return dir;
+    }
+    const parent = path2.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+async function listApps(root) {
+  const appsDir = path2.join(root, "apps");
+  if (!await exists(appsDir)) return [];
+  const entries = await fs2.readdir(appsDir, { withFileTypes: true });
+  const apps = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const appDir = path2.join(appsDir, entry.name);
+    if (await findNshJson(appDir)) apps.push(appDir);
+  }
+  return apps;
+}
+async function resolveWorkspace(cwd) {
+  const resolved = path2.resolve(cwd);
+  const monoRoot = await findMonorepoRoot(resolved);
+  if (monoRoot) {
+    const uiRoot = path2.join(monoRoot, "packages", "ui");
+    return {
+      kind: "monorepo",
+      uiRoot,
+      apps: await listApps(monoRoot),
+      root: monoRoot
+    };
+  }
+  if (path2.basename(resolved) === "ui" && path2.basename(path2.dirname(resolved)) === "packages" && await isConsumerUiPackage(resolved)) {
+    const root = path2.dirname(path2.dirname(resolved));
+    return {
+      kind: "monorepo",
+      uiRoot: resolved,
+      apps: await listApps(root),
+      root
+    };
+  }
+  return {
+    kind: "app",
+    uiRoot: resolved,
+    apps: await findNshJson(resolved) ? [resolved] : [],
+    root: resolved
+  };
+}
+function themePathForApp(appDir, uiRoot) {
+  const abs = path2.join(uiRoot, "theme.json");
+  let rel = path2.relative(appDir, abs);
+  if (!rel.startsWith(".")) rel = `./${rel}`;
+  return rel.replace(/\\/g, "/");
+}
+
+// src/utils/app.ts
+async function readApp(cwd, registry) {
+  const ws = await resolveWorkspace(path3.resolve(cwd));
+  const stored = await readConfig(ws.uiRoot);
+  const config = stored ?? DEFAULT_CONFIG();
+  if (registry) config.registry = registry;
+  return { ws, config, hasConfig: stored != null };
+}
+
+// src/utils/install.ts
+import fs4 from "fs/promises";
+import path7 from "path";
+
+// src/utils/diff.ts
+function diffLines(before, after) {
+  const a = before.split("\n");
+  const b = after.split("\n");
+  const n = a.length;
+  const m = b.length;
+  const length = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+  for (let i2 = n - 1; i2 >= 0; i2 -= 1) {
+    for (let j2 = m - 1; j2 >= 0; j2 -= 1) {
+      length[i2][j2] = a[i2] === b[j2] ? length[i2 + 1][j2 + 1] + 1 : Math.max(length[i2 + 1][j2], length[i2][j2 + 1]);
+    }
+  }
+  const out = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      out.push({ kind: "same", text: a[i] });
+      i += 1;
+      j += 1;
+    } else if (length[i + 1][j] >= length[i][j + 1]) {
+      out.push({ kind: "del", text: a[i] });
+      i += 1;
+    } else {
+      out.push({ kind: "add", text: b[j] });
+      j += 1;
+    }
+  }
+  while (i < n) out.push({ kind: "del", text: a[i++] });
+  while (j < m) out.push({ kind: "add", text: b[j++] });
+  return out;
+}
+function countChanges(lines) {
+  let added = 0;
+  let removed = 0;
+  for (const line of lines) {
+    if (line.kind === "add") added += 1;
+    else if (line.kind === "del") removed += 1;
+  }
+  return { added, removed };
+}
+function changeSummary(added, removed) {
+  return `(+${added} -${removed})`;
+}
+function formatDiff(lines) {
+  return lines.map(
+    (line) => line.kind === "add" ? `+ ${line.text}` : line.kind === "del" ? `- ${line.text}` : `  ${line.text}`
+  ).join("\n");
+}
+
+// src/utils/plan.ts
+import fs3 from "fs";
+import fsPromises from "fs/promises";
+import path6 from "path";
+
+// src/utils/paths.ts
+import path4 from "path";
+function resolveAlias(cwd, alias) {
+  return path4.resolve(cwd, alias);
+}
+function relativeImport(fromFile, toModuleFile) {
+  let rel = path4.relative(path4.dirname(fromFile), toModuleFile);
+  if (!rel.startsWith(".")) rel = `./${rel}`;
+  return rel.replace(/\\/g, "/").replace(/\.(tsx?|jsx?)$/, "");
+}
+function defaultTarget(file, aliases) {
+  if (file.target) return file.target;
+  const base = path4.basename(file.path);
+  if (file.type === "registry:ui") return path4.posix.join(aliases.ui.replace(/^\.\//, ""), base);
+  if (file.type === "registry:lib") return path4.posix.join(aliases.lib.replace(/^\.\//, ""), base);
+  return base;
+}
+
+// src/utils/theme-merge.ts
+var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function mergeTheme(existing, incoming) {
+  const missing = [];
+  const merge = (base, extra, prefix) => {
+    const out = { ...base };
+    for (const [key, value] of Object.entries(extra)) {
+      const at = prefix ? `${prefix}.${key}` : key;
+      if (!(key in out)) {
+        out[key] = value;
+        missing.push(at);
+      } else if (isObject(out[key]) && isObject(value)) {
+        out[key] = merge(out[key], value, at);
+      }
+    }
+    return out;
+  };
+  const theme = merge(existing, incoming, "");
+  return { theme, added: missing.length, missing };
+}
+
+// src/utils/transform.ts
+import path5 from "path";
+function transformContent(content, absoluteTargetFile, config, cwd) {
+  const themeModule = resolveAlias(cwd, config.aliases.theme);
+  const themeImport = relativeImport(absoluteTargetFile, themeModule);
+  const libDir = resolveAlias(cwd, config.aliases.lib);
+  const rewritten = content.replaceAll(`from "@shadcn-nsh/theme"`, `from "${themeImport}"`).replaceAll(`from '@shadcn-nsh/theme'`, `from '${themeImport}'`);
+  return rewritten.replace(
+    /from (["'])\.\/lib\/([\w-]+)\1/g,
+    (_match, quote, name) => `from ${quote}${relativeImport(absoluteTargetFile, path5.join(libDir, name))}${quote}`
+  );
+}
+
+// src/utils/plan.ts
+function isThemeFile(file) {
+  return path6.basename(file.absolute) === "theme.json";
+}
+function hasChange(file) {
+  if (file.status === "merge") return true;
+  return file.status === "differs" && !isThemeFile(file);
+}
+async function readOrNull(file) {
+  try {
+    return await fsPromises.readFile(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+function themeMerge(existing, incoming) {
+  try {
+    return mergeTheme(
+      JSON.parse(existing),
+      JSON.parse(incoming)
+    );
+  } catch {
+    return null;
+  }
+}
+async function planItems(uiRoot, config, items) {
+  const planned = [];
+  for (const item of items) {
+    for (const file of item.files) {
+      if (file.content == null) {
+        throw new Error(`Item ${item.name} file ${file.path} has no content (run registry:build)`);
+      }
+      const target = defaultTarget(file, config.aliases);
+      const absolute = path6.isAbsolute(target) ? target : path6.resolve(uiRoot, target);
+      const content = transformContent(file.content, absolute, config, uiRoot);
+      const existing = await readOrNull(absolute);
+      const relative = path6.relative(uiRoot, absolute) || path6.basename(absolute);
+      const entry = {
+        item: item.name,
+        file,
+        path: relative,
+        absolute,
+        content,
+        existing,
+        status: "create",
+        added: 0,
+        removed: 0
+      };
+      if (existing != null) {
+        if (existing === content) {
+          entry.status = "same";
+        } else if (path6.basename(absolute) === "theme.json") {
+          const merged2 = themeMerge(existing, content);
+          if (merged2 && merged2.added > 0) {
+            entry.status = "merge";
+            entry.missing = merged2.missing;
+          } else {
+            entry.status = "differs";
+          }
+        } else {
+          entry.status = "differs";
+        }
+      }
+      if (existing != null && entry.status !== "same") {
+        const changes = countChanges(diffLines(existing, content));
+        entry.added = changes.added;
+        entry.removed = changes.removed;
+      }
+      planned.push(entry);
+    }
+  }
+  return planned;
+}
+function isInstalled(uiRoot, config, item) {
+  return (item.files ?? []).some((file) => {
+    const target = defaultTarget(file, config.aliases);
+    return fs3.existsSync(path6.isAbsolute(target) ? target : path6.resolve(uiRoot, target));
+  });
+}
+
+// src/utils/install.ts
+async function installItems(uiRoot, config, items, opts = {}) {
+  const planned = await planItems(uiRoot, config, items);
+  const written = [];
+  for (const file of planned) {
+    const shown = file.path;
+    if (file.status === "same") {
+      console.log(`skip ${shown} (identical)`);
+      continue;
+    }
+    if (file.status === "create") {
+      if (opts.dryRun) console.log(`would write ${shown}`);
+      else {
+        await write(file, file.content);
+        written.push(shown);
+        console.log(`write ${shown}`);
+      }
+      continue;
+    }
+    if (file.status === "merge" && !opts.overwrite) {
+      const count = file.missing?.length ?? 0;
+      if (opts.dryRun) {
+        console.log(`would merge ${shown} (${count} keys missing)`);
+      } else {
+        await write(file, await merged(file) ?? file.content);
+        written.push(shown);
+        console.log(`merge ${shown} (added ${count} keys)`);
+      }
+      continue;
+    }
+    const summary2 = changeSummary(file.added, file.removed);
+    if (!opts.overwrite) {
+      console.log(
+        isThemeFile(file) ? `kept ${shown} (the app's colors stay)` : `kept ${shown}, differs (run diff)`
+      );
+    } else if (opts.dryRun) {
+      console.log(`would overwrite ${shown} ${summary2}`);
+    } else {
+      await write(file, file.content);
+      written.push(shown);
+      console.log(`overwrite ${shown} ${summary2}`);
+    }
+  }
+  return { planned, written };
+}
+async function write(file, content) {
+  await fs4.mkdir(path7.dirname(file.absolute), { recursive: true });
+  await fs4.writeFile(file.absolute, content, "utf8");
+}
+async function merged(file) {
+  if (file.existing == null) return null;
+  try {
+    const { theme } = mergeTheme(
+      JSON.parse(file.existing),
+      JSON.parse(file.content)
+    );
+    return `${JSON.stringify(theme, null, 2)}
+`;
+  } catch {
+    return null;
+  }
+}
+
+// src/utils/registry.ts
+import fs5 from "fs/promises";
+import path8 from "path";
+function itemUrl(config, name, registryOverride) {
+  const template = registryOverride ?? config.registry;
+  if (!template.includes("{name}")) {
+    throw new Error(`Registry URL must contain {name}: ${template}`);
+  }
+  return template.replaceAll("{name}", name);
+}
+function indexUrl(config, registryOverride) {
+  const template = registryOverride ?? config.registry;
+  if (!template.includes("{name}")) {
+    throw new Error(`Registry URL must contain {name}: ${template}`);
+  }
+  return template.replaceAll("{name}", "index");
+}
+async function fetchItem(config, name, registryOverride) {
+  const url = itemUrl(config, name, registryOverride);
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`Failed to fetch ${url}: ${res.status} ${res.statusText}`);
+  }
+  return await res.json();
+}
+async function fetchIndex(config, registryOverride) {
+  const url = indexUrl(config, registryOverride);
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(
+      `Failed to fetch ${url}: ${res.status} ${res.statusText}. A registry needs an index.json (bun run registry:build writes one).`
+    );
+  }
+  return await res.json();
+}
+async function resolveTree(config, names, registryOverride) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  async function walk(name) {
+    if (seen.has(name)) return;
+    seen.add(name);
+    const item = await fetchItem(config, name, registryOverride);
+    for (const dep of item.registryDependencies ?? []) {
+      await walk(dep);
+    }
+    out.push(item);
+  }
+  for (const name of names) {
+    await walk(name);
+  }
+  return out;
+}
+var IMPORT_RE = /(?:import|export)\s[^;]*?from\s+["']([^"']+)["']|import\s+["']([^"']+)["']/g;
+var THEME_PACKAGE = "@shadcn-nsh/theme";
+var RESOLVE_SUFFIXES = ["", ".ts", ".tsx", ".json", "/index.ts", "/index.tsx"];
+async function checkRegistryDependencies(registry, baseDir) {
+  const owner = /* @__PURE__ */ new Map();
+  for (const item of registry.items) {
+    for (const file of item.files) owner.set(path8.resolve(baseDir, file.path), item.name);
+  }
+  const hasTheme = registry.items.some((item) => item.name === "theme");
+  const problems = [];
+  for (const item of registry.items) {
+    const used = /* @__PURE__ */ new Set();
+    for (const file of item.files) {
+      const abs = path8.resolve(baseDir, file.path);
+      if (!/\.(ts|tsx)$/.test(abs)) continue;
+      const source = await fs5.readFile(abs, "utf8");
+      for (const match of source.matchAll(IMPORT_RE)) {
+        const spec = match[1] ?? match[2];
+        if (spec === THEME_PACKAGE && hasTheme) used.add("theme");
+        else if (spec.startsWith(".")) {
+          const target = RESOLVE_SUFFIXES.map(
+            (x) => path8.resolve(path8.dirname(abs), spec) + x
+          ).find((candidate) => owner.has(candidate));
+          if (target) used.add(owner.get(target));
+          else problems.push(`${item.name}: imports "${spec}", which no registry item ships`);
+        }
+      }
+    }
+    used.delete(item.name);
+    const declared = new Set(item.registryDependencies ?? []);
+    for (const dep of used) {
+      if (!declared.has(dep))
+        problems.push(`${item.name}: imports "${dep}" but does not declare it`);
+    }
+    for (const dep of declared) {
+      if (!used.has(dep)) problems.push(`${item.name}: declares "${dep}" but never imports it`);
+    }
+  }
+  return problems;
+}
+
+// src/commands/init.ts
+import fs6 from "fs/promises";
+import path9 from "path";
+import { Command } from "commander";
+async function runInit(opts) {
+  const cwd = path9.resolve(opts.cwd);
+  const ws = await resolveWorkspace(cwd);
+  if (ws.kind === "app") {
+    const nshJsonPath = await findNshJson(cwd);
+    if (!nshJsonPath) {
+      throw new Error(
+        `No nsh.json in ${cwd}. Create an NSH app first (nsh init), then run shadcn-nsh init.`
+      );
+    }
+  } else if (ws.apps.length === 0) {
+    throw new Error(
+      `Monorepo at ${ws.root} has packages/ui but no apps/*/nsh.json. Add an NSH app under apps/.`
+    );
+  }
+  const config = DEFAULT_CONFIG();
+  if (opts.registry) config.registry = opts.registry;
+  await writeConfig(ws.uiRoot, config);
+  console.log(`write ${path9.relative(cwd, path9.join(ws.uiRoot, "nsh-ui.json")) || "nsh-ui.json"}`);
+  const items = await resolveTree(config, ["theme"], opts.registry);
+  await installItems(ws.uiRoot, config, items, { overwrite: opts.overwrite });
+  for (const appDir of ws.apps) {
+    const nshJsonPath = await findNshJson(appDir);
+    if (!nshJsonPath) continue;
+    const nsh = await readJson(nshJsonPath);
+    nsh.theme = ws.kind === "monorepo" ? themePathForApp(appDir, ws.uiRoot) : "./theme.json";
+    await writeJson(nshJsonPath, nsh);
+    console.log(
+      `update ${path9.relative(cwd, nshJsonPath) || "nsh.json"} theme \u2192 ${String(nsh.theme)}`
+    );
+  }
+  if (ws.kind === "app") {
+    const tsconfig = path9.join(cwd, "tsconfig.json");
+    try {
+      await fs6.access(tsconfig);
+    } catch {
+      await writeJson(tsconfig, {
+        extends: "./.nsh/tsconfig.json",
+        include: ["**/*.ts", "**/*.tsx"]
+      });
+      console.log("write tsconfig.json");
+    }
+  }
+  return config;
+}
+var init = new Command().name("init").description("Initialize shadcn-nsh (writes nsh-ui.json + theme; monorepo \u2192 packages/ui)").option("-c, --cwd <cwd>", "app or monorepo directory", process.cwd()).option("-y, --yes", "skip confirmation", false).option("--overwrite", "overwrite existing files", false).option("--registry <url>", "registry URL template containing {name}").action(async (opts) => {
+  await runInit(opts);
+  console.log("\nDone. Next: shadcn-nsh add button");
+});
+
+// src/commands/add.ts
+async function runAdd(components, opts) {
+  const cwd = path10.resolve(opts.cwd);
+  const dryRun = opts.dryRun === true;
+  if (components.length === 0 && !opts.all) {
+    throw new Error("Name at least one component, or pass --all.");
+  }
+  const { ws, config: stored, hasConfig } = await readApp(cwd, opts.registry);
+  let config = stored;
+  if (!hasConfig) {
+    if (dryRun) {
+      console.log("No nsh-ui.json \u2014 a dry run uses the default aliases (run init first).");
+      config = DEFAULT_CONFIG();
+      if (opts.registry) config.registry = opts.registry;
+    } else {
+      console.log("No nsh-ui.json \u2014 running init first\u2026");
+      config = await runInit({ cwd, overwrite: opts.overwrite, registry: opts.registry });
+    }
+  }
+  if (opts.registry) {
+    config.registry = opts.registry;
+    if (hasConfig && !dryRun) await writeConfig(ws.uiRoot, config);
+  }
+  const names = [...components];
+  if (opts.all) {
+    const index = await fetchIndex(config, opts.registry);
+    for (const item of index.items) {
+      if (item.type === "registry:ui" && !names.includes(item.name)) names.push(item.name);
+    }
+  }
+  if (names.length === 0) {
+    throw new Error("The registry lists no registry:ui item to add.");
+  }
+  const items = await resolveTree(config, names, opts.registry);
+  await installItems(ws.uiRoot, config, items, { overwrite: opts.overwrite, dryRun });
+  if (dryRun) {
+    const count = `${names.length} item${names.length === 1 ? "" : "s"}`;
+    console.log(`
+Dry run: nothing written. ${count} checked.`);
+    return 0;
+  }
+  console.log(
+    opts.all ? `
+Added: all ${names.length} registry:ui items` : `
+Added: ${names.join(", ")}`
+  );
+  if (ws.kind === "monorepo") {
+    console.log(`(installed under ${path10.relative(ws.root, ws.uiRoot) || "packages/ui"})`);
+  }
+  return 0;
+}
+var add = new Command2().name("add").description("Add registry components (monorepo: installs into packages/ui)").argument("[components...]", "component names (e.g. button)").option("-c, --cwd <cwd>", "app or monorepo directory", process.cwd()).option("-o, --overwrite", "replace files the app has changed", false).option("-a, --all", "every registry:ui item the registry lists", false).option("--dry-run", "print what would be written; write nothing", false).option("--registry <url>", "registry URL template containing {name}").action(
+  async (components, opts) => {
+    process.exitCode = await runAdd(components, opts);
+  }
+);
+
+// src/commands/build.ts
+import fs7 from "fs/promises";
+import path11 from "path";
+import { Command as Command3 } from "commander";
+
+// src/utils/registry-schema.ts
+var RegistryShapeError = class extends Error {
+  name = "RegistryShapeError";
+};
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function stringAt(value, where) {
+  if (typeof value !== "string") throw new RegistryShapeError(`${where}: expected a string`);
+  return value;
+}
+function optionalString(value, where) {
+  return value === void 0 ? void 0 : stringAt(value, where);
+}
+function optionalStrings(value, where) {
+  if (value === void 0) return void 0;
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+    throw new RegistryShapeError(`${where}: expected a list of strings`);
+  }
+  return value;
+}
+function fileAt(value, where) {
+  if (!isRecord(value)) throw new RegistryShapeError(`${where}: not an object`);
+  const file = {
+    path: stringAt(value.path, `${where}.path`),
+    type: stringAt(value.type, `${where}.type`)
+  };
+  const target = optionalString(value.target, `${where}.target`);
+  if (target !== void 0) file.target = target;
+  const content = optionalString(value.content, `${where}.content`);
+  if (content !== void 0) file.content = content;
+  return inSourceOrder(value, file);
+}
+function inSourceOrder(source, checked) {
+  const ordered = {};
+  for (const key of Object.keys(source)) {
+    if (key in checked) ordered[key] = checked[key];
+  }
+  return Object.assign(ordered, checked);
+}
+function parseRegistryItem(value, where) {
+  if (!isRecord(value)) throw new RegistryShapeError(`${where}: not an object`);
+  const type = stringAt(value.type, `${where}: type`);
+  if (!type.startsWith("registry:")) {
+    throw new RegistryShapeError(`${where}: type "${type}" is not a registry: type`);
+  }
+  if (!Array.isArray(value.files) || value.files.length === 0) {
+    throw new RegistryShapeError(`${where}: no files`);
+  }
+  const item = {
+    name: stringAt(value.name, `${where}: name`),
+    type,
+    files: value.files.map((file, at) => fileAt(file, `${where}: files[${at}]`))
+  };
+  const title = optionalString(value.title, `${where}: title`);
+  if (title !== void 0) item.title = title;
+  const description = optionalString(value.description, `${where}: description`);
+  if (description !== void 0) item.description = description;
+  const registryDependencies = optionalStrings(
+    value.registryDependencies,
+    `${where}: registryDependencies`
+  );
+  if (registryDependencies !== void 0) item.registryDependencies = registryDependencies;
+  const dependencies = optionalStrings(value.dependencies, `${where}: dependencies`);
+  if (dependencies !== void 0) item.dependencies = dependencies;
+  return inSourceOrder(value, item);
+}
+function parseRegistry(value, where) {
+  if (!isRecord(value)) throw new RegistryShapeError(`${where}: not a JSON object`);
+  if (!Array.isArray(value.items)) throw new RegistryShapeError(`${where}: no items list`);
+  return {
+    name: stringAt(value.name, `${where}: name`),
+    homepage: stringAt(value.homepage, `${where}: homepage`),
+    items: value.items.map((item, at) => parseRegistryItem(item, `${where}: items[${at}]`))
+  };
+}
+
+// src/commands/build.ts
+async function holdsItem(file, name) {
+  let value;
+  try {
+    value = JSON.parse(await fs7.readFile(file, "utf8"));
+  } catch (error) {
+    if (error instanceof SyntaxError) return false;
+    throw error;
+  }
+  try {
+    return parseRegistryItem(value, file).name === name;
+  } catch (error) {
+    if (error instanceof RegistryShapeError) return false;
+    throw error;
+  }
+}
+async function runBuild(registryFile, opts) {
+  const cwd = path11.resolve(opts.cwd);
+  const registryPath = path11.resolve(cwd, registryFile);
+  const outputDir = path11.resolve(cwd, opts.output);
+  const registry = parseRegistry(JSON.parse(await fs7.readFile(registryPath, "utf8")), registryPath);
+  const problems = await checkRegistryDependencies(registry, path11.dirname(registryPath));
+  if (problems.length > 0) {
+    for (const problem of problems) console.error(`registry: ${problem}`);
+    return 1;
+  }
+  await fs7.mkdir(outputDir, { recursive: true });
+  const catalog = [];
+  for (const item of registry.items) {
+    const built = {
+      ...item,
+      files: await Promise.all(
+        item.files.map(async (file) => {
+          const abs = path11.resolve(path11.dirname(registryPath), file.path);
+          const content = await fs7.readFile(abs, "utf8");
+          return {
+            ...file,
+            content
+          };
+        })
+      )
+    };
+    const outFile = path11.join(outputDir, `${item.name}.json`);
+    await fs7.writeFile(outFile, `${JSON.stringify(built, null, 2)}
+`, "utf8");
+    catalog.push({
+      name: item.name,
+      type: item.type,
+      title: item.title,
+      description: item.description,
+      // The targets `list` checks and `add` writes, without the contents.
+      files: item.files.map((file) => ({
+        path: file.path,
+        type: file.type,
+        target: file.target
+      }))
+    });
+    console.log(`built ${path11.relative(cwd, outFile)}`);
+  }
+  const indexPath = path11.join(outputDir, "index.json");
+  await fs7.writeFile(
+    indexPath,
+    `${JSON.stringify({ name: registry.name, homepage: registry.homepage, items: catalog }, null, 2)}
+`,
+    "utf8"
+  );
+  console.log(`built ${path11.relative(cwd, indexPath)}`);
+  const written = /* @__PURE__ */ new Set([...registry.items.map((item) => `${item.name}.json`), "index.json"]);
+  for (const entry of await fs7.readdir(outputDir, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith(".json") || written.has(entry.name)) continue;
+    const stale = path11.join(outputDir, entry.name);
+    const name = entry.name.slice(0, -".json".length);
+    if (!await holdsItem(stale, name)) continue;
+    await fs7.rm(stale);
+    console.log(`removed ${path11.relative(cwd, stale)} (not in ${path11.basename(registryPath)})`);
+  }
+  return 0;
+}
+var build = new Command3().name("build").description("Build registry items into public/r/*.json").argument("[registry]", "path to registry.json", "./registry.json").option("-o, --output <path>", "output directory", "./public/r").option("-c, --cwd <cwd>", "working directory", process.cwd()).action(async (registryFile, opts) => {
+  process.exitCode = await runBuild(registryFile, opts);
+});
+
+// src/commands/diff.ts
+import { Command as Command4 } from "commander";
+async function runDiff(names, opts) {
+  const { ws, config, hasConfig } = await readApp(opts.cwd, opts.registry);
+  if (!hasConfig) {
+    console.log("No nsh-ui.json \u2014 run init first.");
+    return 1;
+  }
+  const index = await fetchIndex(config, opts.registry);
+  const targets = names.length ? names : index.items.filter((item) => isInstalled(ws.uiRoot, config, item)).map((item) => item.name);
+  if (targets.length === 0) {
+    console.log("Nothing installed.");
+    return 0;
+  }
+  const items = await resolveTree(config, targets, opts.registry);
+  const changed = (await planItems(ws.uiRoot, config, items)).filter(hasChange);
+  if (changed.length === 0) {
+    console.log("No differences.");
+    return 0;
+  }
+  if (names.length === 0) {
+    for (const name of targets) {
+      const files = changed.filter((file) => file.item === name);
+      if (files.length === 0) continue;
+      const lines = files.map((file) => `  ${file.path}`);
+      console.log(`${name} ${summary(files)}`);
+      console.log(lines.join("\n"));
+    }
+    console.log(`
+Run shadcn-nsh diff <item> to see the changes.`);
+    return 1;
+  }
+  for (const file of changed) {
+    console.log(`${file.path} ${summary([file])}`);
+    console.log(formatDiff(diffLines(file.existing ?? "", file.content)));
+    console.log();
+  }
+  return 1;
+}
+var summary = (files) => changeSummary(
+  files.reduce((total, file) => total + file.added, 0),
+  files.reduce((total, file) => total + file.removed, 0)
+);
+var diff = new Command4().name("diff").description("Compare the app's installed files with the registry's; exit 1 when they differ").argument("[items...]", "item names (default: every installed item)").option("-c, --cwd <cwd>", "app or monorepo directory", process.cwd()).option("--registry <url>", "registry URL template containing {name}").action(async (items, opts) => {
+  process.exitCode = await runDiff(items, opts);
+});
+
+// src/commands/list.ts
+import { Command as Command5 } from "commander";
+async function runList(opts) {
+  const { ws, config } = await readApp(opts.cwd, opts.registry);
+  const index = await fetchIndex(config, opts.registry);
+  const rows = index.items.map((item) => ({
+    name: item.name,
+    type: item.type,
+    title: item.title,
+    description: item.description,
+    installed: isInstalled(ws.uiRoot, config, item)
+  }));
+  if (opts.json) {
+    console.log(
+      JSON.stringify({ name: index.name, homepage: index.homepage, items: rows }, null, 2)
+    );
+    return 0;
+  }
+  const nameWidth = Math.max(...rows.map((row) => row.name.length));
+  const typeWidth = Math.max(...rows.map((row) => row.type.length));
+  for (const row of rows) {
+    const mark = row.installed ? "\u2713" : " ";
+    const line = `${mark} ${row.name.padEnd(nameWidth)}  ${row.type.padEnd(typeWidth)}  ${row.description ?? ""}`;
+    console.log(line.trimEnd());
+  }
+  const installed = rows.filter((row) => row.installed).length;
+  console.log(`
+${rows.length} items, ${installed} installed`);
+  return 0;
+}
+var list = new Command5().name("list").description("List the registry's items, marking the ones the app has").option("-c, --cwd <cwd>", "app or monorepo directory", process.cwd()).option("--registry <url>", "registry URL template containing {name}").option("--json", "print the catalog as JSON", false).action(async (opts) => {
+  process.exitCode = await runList(opts);
+});
+
+// src/commands/serve.ts
+import fs8 from "fs/promises";
+import http from "http";
+import path12 from "path";
+import { Command as Command6 } from "commander";
+function fileUnder(root, pathname) {
+  const file = path12.join(root, pathname);
+  const relative = path12.relative(root, file);
+  if (relative === "" || relative === ".." || relative.startsWith(`..${path12.sep}`) || path12.isAbsolute(relative)) {
+    return null;
+  }
+  return file;
+}
+async function startRegistryServer(opts) {
+  const root = path12.resolve(opts.dir);
+  const port = opts.port ?? 0;
+  const server = http.createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url ?? "/", "http://127.0.0.1");
+      let pathname = url.pathname;
+      if (pathname === "/") pathname = "/index.json";
+      if (pathname.startsWith("/r/")) pathname = pathname.slice(2);
+      if (!pathname.startsWith("/")) pathname = `/${pathname}`;
+      const filePath = fileUnder(root, pathname);
+      if (filePath === null) {
+        res.writeHead(403, { "content-type": "text/plain; charset=utf-8" });
+        res.end("Forbidden");
+        return;
+      }
+      try {
+        const body = await fs8.readFile(filePath);
+        res.writeHead(200, {
+          "content-type": "application/json; charset=utf-8",
+          "access-control-allow-origin": "*"
+        });
+        res.end(body);
+      } catch {
+        res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+        res.end(`Not found: ${pathname}`);
+      }
+    } catch (error) {
+      res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+      res.end(error instanceof Error ? error.message : String(error));
+    }
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, "127.0.0.1", () => resolve());
+  });
+  const address = server.address();
+  const bound = typeof address === "object" && address != null ? address.port : port;
+  return {
+    url: `http://127.0.0.1:${bound}`,
+    port: bound,
+    close: () => new Promise((resolve, reject) => {
+      server.close((error) => error ? reject(error) : resolve());
+      server.closeAllConnections?.();
+    })
+  };
+}
+var serve = new Command6().name("serve").description("Serve public/r over HTTP for local CLI testing").option("-p, --port <port>", "port (0 picks a free one)", "4173").option("-d, --dir <path>", "registry directory", "./public/r").option("-c, --cwd <cwd>", "working directory", process.cwd()).action(async (opts) => {
+  const root = path12.resolve(opts.cwd, opts.dir);
+  const server = await startRegistryServer({ dir: root, port: Number(opts.port) });
+  console.log(`Serving ${root}`);
+  console.log(`  ${server.url}/index.json`);
+  console.log(`  ${server.url}/button.json`);
+  console.log(`CLI: --registry ${server.url}/{name}.json`);
+});
+
+// src/commands/view.ts
+import { Command as Command7 } from "commander";
+async function runView(names, opts) {
+  const { ws, config } = await readApp(opts.cwd, opts.registry);
+  const items = await resolveTree(config, names, opts.registry);
+  const planned = await planItems(ws.uiRoot, config, items);
+  let first = true;
+  for (const item of items) {
+    if (!first) console.log();
+    first = false;
+    console.log(`${item.name} (${item.type})`);
+    const deps = item.registryDependencies ?? [];
+    if (deps.length > 0) console.log(`  depends on: ${deps.join(", ")}`);
+    for (const file of planned.filter((entry) => entry.item === item.name)) {
+      console.log(`file ${file.path}`);
+      console.log(file.content.replace(/\n$/, ""));
+    }
+  }
+  return 0;
+}
+var view = new Command7().name("view").description("Print the files an item would write, its dependencies resolved").argument("<items...>", "item names (e.g. button)").option("-c, --cwd <cwd>", "app or monorepo directory", process.cwd()).option("--registry <url>", "registry URL template containing {name}").action(async (items, opts) => {
+  process.exitCode = await runView(items, opts);
+});
+
+// src/index.ts
+var program = new Command8().name("shadcn-nsh").description("Add styled NSH components (copy-into-app) from the shadcn-nsh registry").version(package_default.version);
+program.addCommand(build);
+program.addCommand(init);
+program.addCommand(add);
+program.addCommand(list);
+program.addCommand(view);
+program.addCommand(diff);
+program.addCommand(serve);
+program.parse();

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "shadcn-nsh",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Add styled NSH components (copy-into-app) from the shadcn-nsh registry",
+  "keywords": [
+    "cli",
+    "components",
+    "nsh",
+    "registry",
+    "shadcn"
+  ],
+  "homepage": "https://github.com/aningdev/shadcn-nsh#readme",
+  "bugs": {
+    "url": "https://github.com/aningdev/shadcn-nsh/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aningdev/shadcn-nsh.git",
+    "directory": "packages/cli"
+  },
+  "bin": {
+    "shadcn-nsh": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "commander": "^15.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}