@multicomma/arkcn 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# arkcn
+
+shadcn/ui-style React components ported to [Ark UI](https://ark-ui.com), plus data-heavy primitives:
+data grid, data table engine, kanban, gantt, scheduler, node graph, query builder, rich text editor
+(tiptap), tree select, cascader, transfer list, virtual list, hotkeys, and more. Tailwind v4.
+
+Every part is exported on its own, carries a `data-slot`, and is styled through Ark's data attributes.
+Triggers are polymorphic via `asChild`.
+
+## Install components
+
+```bash
+npx @multicomma/arkcn init            # arkcn.json, src/lib/utils.ts, base styles, "@/" alias check, base deps
+npx @multicomma/arkcn add button card dialog data-grid
+npx @multicomma/arkcn list            # everything in the registry (--type all, `list data-grid --docs`)
+npx @multicomma/arkcn diff            # which installed files you changed locally
+```
+
+`init` writes `arkcn.json` (alias, `srcDir`, component/lib/hooks dirs, stylesheet), merges the
+toolkit's tokens, custom variants, utilities, and keyframes into your stylesheet after
+`@import "tailwindcss"` (between `/* arkcn:base */` markers, so re-running refreshes them),
+makes sure the `@/*` path alias exists, and installs the base packages (Ark UI, lucide, clsx,
+tailwind-merge, cva, tw-animate-css, the typography plugin). Tailwind v4 is required.
+
+`add` copies the component **and everything it imports** (other components, `lib`, `hooks`) into
+your project with imports rewritten to your alias, appends any component-specific CSS block, and
+installs the packages those files need (tiptap for the editor, pragmatic drag and drop for kanban,
+and so on). Files you have edited are kept unless you pass `--overwrite`; `diff --verbose` shows
+what changed. `--no-install` skips the package manager, `--all` adds every component.
+
+The components then belong to you: edit them freely, exactly as with shadcn/ui.
+
+### Registry
+
+The CLI reads a registry generated from this repo (`npm run build:registry` → `registry/`), bundled
+in the npm package so a CLI version always installs a matching component set and works offline.
+The same folder is committed here, so you can also read it from a URL, for example to pick up
+components newer than your installed CLI:
+
+```bash
+npx @multicomma/arkcn add kanban --registry https://raw.githubusercontent.com/itsdanreed/arkcn/main/registry
+# or export ARKCN_REGISTRY=...
+```
+
+Each item is `registry/items/<name>.json`: files with content, `registryDependencies`,
+`dependencies` (with versions), an optional `css` fragment, and `docs`. `registry/index.json` is the
+manifest and `registry/base.css` the init payload.
+
+## MCP server
+
+The package also ships an MCP server so agents (Claude Code, Cursor, and others) can browse the
+registry, read documentation and source, and copy components into a project:
+
+```json
+{ "mcpServers": { "@multicomma/arkcn": { "command": "npx", "args": ["-y", "@multicomma/arkcn", "mcp"] } } }
+```
+
+Tools: `list_components`, `search_components`, `get_component` (source, deps, css, docs),
+`get_docs`, `plan_install` (dry run against a project), `add_components` (writes files and CSS,
+returns the packages to install). Pass `--registry <url>` to read a hosted registry.
+
+## Consume from node_modules instead
+
+The demo app imports the package source directly: import `@multicomma/arkcn/styles.css`,
+alias `@/components/ui`, `@/lib`, and `@/hooks` to `node_modules/@multicomma/arkcn/src/...`,
+and add `@source "../node_modules/@multicomma/arkcn/src"` because Tailwind does not scan
+`node_modules`. Heavy dependencies (tiptap, pragmatic drag and drop, recharts, embla, date-fns,
+react-day-picker, input-otp, react-resizable-panels, sonner, next-themes) are optional peers.
+
+The demo application lives in the `arkcn-demo` repository.
+
+## Develop
+
+```bash
+npm install
+npm run check   # registry build + typecheck + lint (oxlint with Tailwind rules, quotes, Ark part coverage, Prettier) + CLI e2e test
+npm publish     # prepublishOnly runs the same check
+```

package/bin/arkcn.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util"
+import { add, diff, init, list } from "../cli/commands.mjs"
+import { createRegistry } from "../cli/registry.mjs"
+import { c, fail, log } from "../cli/ui.mjs"
+
+const help = `${c.bold("@multicomma/arkcn")} - copy Ark UI components into your project
+
+${c.bold("Usage")}
+  npx @multicomma/arkcn init [--yes] [--alias @] [--css src/index.css] [--dir src] [--no-install]
+  npx @multicomma/arkcn add <name...> [--all] [--overwrite] [--yes] [--no-install]
+  npx @multicomma/arkcn list [name...] [--type ui|lib|hook|all] [--docs]
+  npx @multicomma/arkcn diff [name...] [--verbose]
+  npx @multicomma/arkcn mcp
+
+${c.bold("Commands")}
+  init   Write arkcn.json, lib/utils, the base styles, check the "@/" alias, install base deps
+  add    Copy components (and everything they import) into your project, merge their styles, install deps
+  list   Show the registry, or one item with --docs
+  diff   Show which installed files were changed locally since they were added
+  mcp    Start the Model Context Protocol server (stdio) for agents
+
+${c.bold("Options")}
+  --registry <url|dir>  Read the registry from a URL or directory instead of the bundled copy
+                        (also ARKCN_REGISTRY), e.g. the GitHub raw URL of registry/
+  --cwd <dir>           Project directory (default: current)
+`
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  allowNegative: true,
+  options: {
+    help: { type: "boolean", short: "h" },
+    yes: { type: "boolean", short: "y" },
+    all: { type: "boolean" },
+    overwrite: { type: "boolean" },
+    install: { type: "boolean", default: true },
+    verbose: { type: "boolean", short: "v" },
+    docs: { type: "boolean" },
+    alias: { type: "string" },
+    css: { type: "string" },
+    dir: { type: "string" },
+    type: { type: "string" },
+    cwd: { type: "string" },
+    registry: { type: "string" },
+  },
+})
+
+const [command, ...names] = positionals
+const cwd = values.cwd ?? process.cwd()
+const registry = createRegistry(values.registry ?? process.env.ARKCN_REGISTRY)
+
+try {
+  switch (command) {
+    case "init":
+      await init(cwd, registry, values)
+      break
+    case "add":
+      await add(cwd, registry, names, values)
+      break
+    case "list":
+      await list(cwd, registry, names, values)
+      break
+    case "diff":
+      await diff(cwd, registry, names, values)
+      break
+    case "mcp": {
+      const { startServer } = await import("../mcp/server.mjs")
+      await startServer({ registryBase: values.registry ?? process.env.ARKCN_REGISTRY })
+      break
+    }
+    default:
+      log(help)
+      if (command && !values.help) fail(`Unknown command: ${command}`)
+  }
+} catch (error) {
+  fail(error instanceof Error ? error.message : String(error))
+}

package/cli/commands.mjs

@@ -0,0 +1,251 @@
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+import {
+  CONFIG_FILE,
+  defaultConfig,
+  detectBundlerAlias,
+  detectPackageManager,
+  ensureTsconfigAlias,
+  installDependencies,
+  installedVersion,
+  mergeBaseCss,
+  mergeComponentCss,
+  readConfig,
+  readPackageJson,
+  readProjectFile,
+  rewriteImports,
+  targetPath,
+  writeConfig,
+  writeProjectFile,
+} from "./project.mjs"
+import { c, confirm, fail, log, ok, table, warn } from "./ui.mjs"
+
+/** Write an item's files. Returns what was written and what was kept. */
+export function writeItem(cwd, config, item, { overwrite }) {
+  const written = []
+  const kept = []
+  for (const file of item.files) {
+    const rel = targetPath(config, file.path)
+    const content = rewriteImports(file.content, config)
+    const current = readProjectFile(cwd, rel)
+    if (current === content) continue
+    if (current !== null && !overwrite) {
+      kept.push(rel)
+      continue
+    }
+    writeProjectFile(cwd, rel, content)
+    written.push(rel)
+  }
+  return { written, kept }
+}
+
+/** Files that exist locally and differ from the registry version. */
+export function findConflicts(cwd, config, items) {
+  const conflicts = []
+  for (const item of items)
+    for (const file of item.files) {
+      const rel = targetPath(config, file.path)
+      const current = readProjectFile(cwd, rel)
+      if (current !== null && current !== rewriteImports(file.content, config)) conflicts.push(rel)
+    }
+  return conflicts
+}
+
+/** Packages an item set needs that the project does not have yet. */
+export function missingDependencies(cwd, items) {
+  const deps = new Map()
+  for (const item of items)
+    for (const [dep, version] of Object.entries(item.dependencies))
+      if (!installedVersion(cwd, dep)) deps.set(dep, version)
+  return [...deps].map(([dep, version]) => `${dep}@${version}`)
+}
+
+/** `init`: config file, utils, base styles, alias check, base dependencies. */
+export async function init(cwd, registry, flags) {
+  if (!readPackageJson(cwd)) fail(`No package.json in ${cwd}. Run this inside your app.`)
+  const existing = readConfig(cwd)
+  if (existing && !flags.yes) {
+    const again = await confirm(`${CONFIG_FILE} already exists. Re-run init and refresh the base styles?`, {
+      fallback: false,
+    })
+    if (!again) return
+  }
+  const config = {
+    ...defaultConfig,
+    ...existing,
+    ...(flags.alias ? { alias: flags.alias } : {}),
+    ...(flags.css ? { css: flags.css } : {}),
+    ...(flags.dir
+      ? {
+          srcDir: flags.dir,
+          componentsDir: `${flags.dir}/components/ui`,
+          libDir: `${flags.dir}/lib`,
+          hooksDir: `${flags.dir}/hooks`,
+        }
+      : {}),
+  }
+  writeConfig(cwd, config)
+  ok(`Wrote ${CONFIG_FILE}`)
+
+  const tailwind = installedVersion(cwd, "tailwindcss")
+  if (!tailwind) warn("tailwindcss is not in package.json; it will be installed (v4 is required).")
+  else if (!/(\^|~)?4\./.test(tailwind)) warn(`tailwindcss ${tailwind} found; the toolkit needs v4.`)
+
+  const alias = ensureTsconfigAlias(cwd, config.alias, config.srcDir)
+  if (alias === "added") ok(`Added "${config.alias}/*" -> "./${config.srcDir}/*" to tsconfig paths`)
+  else if (alias === "ok") ok(`tsconfig already maps "${config.alias}/*"`)
+  else warn(`Add "paths": { "${config.alias}/*": ["./${config.srcDir}/*"] } to your tsconfig compilerOptions.`)
+  const bundler = detectBundlerAlias(cwd, config.alias)
+  if (bundler.framework === "vite" && !bundler.ok)
+    warn(
+      `Add the alias to ${bundler.file}: resolve.alias { "${config.alias}": path.resolve(__dirname, "./${config.srcDir}") }`
+    )
+
+  const { items } = await registry.closure(["utils"])
+  for (const item of items) writeItem(cwd, config, item, { overwrite: false })
+  ok(`Wrote ${targetPath(config, "lib/utils.ts")}`)
+
+  const result = mergeBaseCss(cwd, config, await registry.baseCss())
+  const verb = {
+    created: "Created",
+    updated: "Updated base styles in",
+    appended: "Appended base styles to",
+    unchanged: "Base styles already current in",
+  }
+  ok(`${verb[result]} ${config.css}`)
+
+  const index = await registry.index()
+  const deps = Object.entries(index.baseDependencies)
+    .filter(([dep]) => !installedVersion(cwd, dep))
+    .map(([dep, version]) => `${dep}@${version}`)
+  await install(cwd, deps, flags)
+  log(`\nNext: ${c.cyan("npx @multicomma/arkcn add button card dialog")}`)
+}
+
+async function install(cwd, deps, flags) {
+  if (deps.length === 0) return ok("No new dependencies")
+  if (flags.install === false) return log(`${c.dim("Skipped install. Needed:")} ${deps.join(" ")}`)
+  log(`${c.dim(`Installing with ${detectPackageManager(cwd)}:`)} ${deps.join(" ")}`)
+  const res = installDependencies(cwd, deps)
+  if (!res.ok) fail("Install failed. Install the packages above and re-run.")
+}
+
+/** `add`: closure of components, files, CSS fragments, dependencies. */
+export async function add(cwd, registry, names, flags) {
+  const config = readConfig(cwd)
+  if (!config) fail(`No ${CONFIG_FILE}. Run ${c.cyan("npx @multicomma/arkcn init")} first.`)
+  const index = await registry.index()
+  const wanted = flags.all ? index.items.filter((i) => i.type === "ui").map((i) => i.name) : names
+  if (wanted.length === 0) fail("Nothing to add. Pass component names or --all.")
+  const { items, missing } = await registry.closure(wanted)
+  if (missing.length) fail(`Unknown: ${missing.join(", ")}. See ${c.cyan("npx @multicomma/arkcn list")}.`)
+
+  let overwrite = !!flags.overwrite
+  const conflicts = findConflicts(cwd, config, items)
+  if (conflicts.length && !overwrite) {
+    warn(`These files exist and differ from the registry:\n  ${conflicts.join("\n  ")}`)
+    overwrite = await confirm("Overwrite them?", { yes: flags.yes, fallback: false })
+    if (!overwrite) log(c.dim("Keeping your versions; only new files will be written."))
+  }
+
+  let cssChanges = 0
+  for (const item of items) {
+    const { written, kept } = writeItem(cwd, config, item, { overwrite })
+    for (const rel of written) ok(`${item.name} -> ${rel}`)
+    for (const rel of kept) log(`${c.dim("kept")} ${rel}`)
+    if (item.css) {
+      const r = mergeComponentCss(cwd, config, item.name, item.css)
+      if (r !== "unchanged") {
+        cssChanges++
+        ok(`${item.name} styles ${r === "updated" ? "updated in" : "appended to"} ${config.css}`)
+      }
+    }
+  }
+  await install(cwd, missingDependencies(cwd, items), flags)
+  const uiCount = items.filter((i) => i.type === "ui").length
+  log(
+    `\n${c.bold(`${uiCount} component(s), ${items.length - uiCount} helper(s)${cssChanges ? `, ${cssChanges} style block(s)` : ""}`)}`
+  )
+}
+
+/** `list`: everything in the registry, or one item in detail. */
+export async function list(cwd, registry, names, flags) {
+  const index = await registry.index()
+  const config = readConfig(cwd)
+  if (names.length) {
+    for (const name of names) {
+      const item = await registry.item(name)
+      if (!item) return fail(`Unknown component: ${name}`)
+      log(`${c.bold(item.name)} ${c.dim(`(${item.type})`)}\n${item.description}\n`)
+      log(`${c.dim("files:")} ${item.files.map((f) => f.path).join(", ")}`)
+      log(`${c.dim("needs:")} ${item.registryDependencies.join(", ") || "-"}`)
+      log(`${c.dim("packages:")} ${Object.keys(item.dependencies).join(", ") || "-"}`)
+      if (item.css) log(`${c.dim("styles:")} yes`)
+      if (flags.docs && item.docs) log(`\n${item.docs}`)
+    }
+    return
+  }
+  const type = flags.type ?? "ui"
+  const rows = index.items
+    .filter((i) => type === "all" || i.type === type)
+    .map((i) => {
+      const installed = config && i.files.every((f) => existsSync(join(cwd, targetPath(config, f))))
+      return [i.name, i.type, installed ? c.green("installed") : "", i.description.slice(0, 70)]
+    })
+  table(rows, ["name", "type", "", "description"])
+  log(c.dim(`\n${rows.length} item(s) from ${registry.source}. \`list <name> --docs\` prints the documentation.`))
+}
+
+/** `diff`: compare installed files with the registry. */
+export async function diff(cwd, registry, names, flags) {
+  const config = readConfig(cwd)
+  if (!config) fail(`No ${CONFIG_FILE}. Run init first.`)
+  const index = await registry.index()
+  const targets = names.length ? names : index.items.map((i) => i.name)
+  let changed = 0
+  for (const name of targets) {
+    const item = await registry.item(name)
+    if (!item) return fail(`Unknown component: ${name}`)
+    for (const file of item.files) {
+      const rel = targetPath(config, file.path)
+      const current = readProjectFile(cwd, rel)
+      if (current === null) {
+        if (names.length) log(`${c.dim("missing")} ${rel}`)
+        continue
+      }
+      const expected = rewriteImports(file.content, config)
+      if (current === expected) {
+        if (names.length) log(`${c.green("same")}    ${rel}`)
+        continue
+      }
+      changed++
+      log(`${c.yellow("changed")} ${rel}`)
+      if (flags.verbose) log(lineDiff(current, expected))
+    }
+  }
+  if (!changed) ok("Installed files match the registry")
+  else log(c.dim(`\n${changed} file(s) differ. \`add <name> --overwrite\` replaces them with the registry version.`))
+}
+
+/** Minimal LCS line diff (files are small). */
+export function lineDiff(current, expected) {
+  const a = current.split("\n")
+  const b = expected.split("\n")
+  const dp = Array.from({ length: a.length + 1 }, () => new Uint16Array(b.length + 1))
+  for (let i = a.length - 1; i >= 0; i--)
+    for (let j = b.length - 1; j >= 0; j--)
+      dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1])
+  let i = 0
+  let j = 0
+  const out = []
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      i++
+      j++
+    } else if (dp[i + 1][j] >= dp[i][j + 1]) out.push(c.red(`- ${a[i++]}`))
+    else out.push(c.green(`+ ${b[j++]}`))
+  }
+  while (i < a.length) out.push(c.red(`- ${a[i++]}`))
+  while (j < b.length) out.push(c.green(`+ ${b[j++]}`))
+  return out.join("\n")
+}

package/cli/project.mjs

@@ -0,0 +1,168 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { dirname, join, relative } from "node:path"
+import { spawnSync } from "node:child_process"
+
+export const CONFIG_FILE = "arkcn.json"
+
+export const defaultConfig = {
+  alias: "@",
+  /** What the alias points at; component dirs live under it. */
+  srcDir: "src",
+  componentsDir: "src/components/ui",
+  libDir: "src/lib",
+  hooksDir: "src/hooks",
+  css: "src/index.css",
+}
+
+export function readConfig(cwd) {
+  const file = join(cwd, CONFIG_FILE)
+  if (!existsSync(file)) return null
+  return { ...defaultConfig, ...JSON.parse(readFileSync(file, "utf8")) }
+}
+
+export function writeConfig(cwd, config) {
+  writeFileSync(join(cwd, CONFIG_FILE), JSON.stringify(config, null, 2) + "\n")
+}
+
+export function detectPackageManager(cwd) {
+  if (existsSync(join(cwd, "pnpm-lock.yaml"))) return "pnpm"
+  if (existsSync(join(cwd, "yarn.lock"))) return "yarn"
+  if (existsSync(join(cwd, "bun.lock")) || existsSync(join(cwd, "bun.lockb"))) return "bun"
+  return "npm"
+}
+
+export function readPackageJson(cwd) {
+  const file = join(cwd, "package.json")
+  if (!existsSync(file)) return null
+  return JSON.parse(readFileSync(file, "utf8"))
+}
+
+export function installedVersion(cwd, dep) {
+  const pkg = readPackageJson(cwd)
+  return pkg?.dependencies?.[dep] ?? pkg?.devDependencies?.[dep] ?? null
+}
+
+/** Target path inside the project for a registry file path like "components/ui/button.tsx". */
+export function targetPath(config, registryPath) {
+  if (registryPath.startsWith("components/ui/"))
+    return join(config.componentsDir, registryPath.slice("components/ui/".length))
+  if (registryPath.startsWith("lib/")) return join(config.libDir, registryPath.slice("lib/".length))
+  if (registryPath.startsWith("hooks/")) return join(config.hooksDir, registryPath.slice("hooks/".length))
+  return registryPath
+}
+
+/** Rewrite "@/components/ui/x", "@/lib/x", "@/hooks/x" imports to the project's alias and dirs. */
+export function rewriteImports(content, config) {
+  const alias = config.alias.replace(/\/$/, "")
+  const dirs = { "components/ui": config.componentsDir, lib: config.libDir, hooks: config.hooksDir }
+  const rootPrefix = new RegExp(`^${config.srcDir.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/`)
+  return content.replace(/from "@\/(components\/ui|lib|hooks)\/([^"]+)"/g, (_, kind, rest) => {
+    const dir = dirs[kind].replace(rootPrefix, "")
+    return `from "${alias}/${dir}/${rest}"`
+  })
+}
+
+export function writeProjectFile(cwd, rel, content) {
+  const file = join(cwd, rel)
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, content)
+  return relative(cwd, file)
+}
+
+export function readProjectFile(cwd, rel) {
+  const file = join(cwd, rel)
+  return existsSync(file) ? readFileSync(file, "utf8") : null
+}
+
+const BASE_START = "/* arkcn:base */"
+const BASE_END = "/* arkcn:base:end */"
+const fragmentStart = (name) => `/* arkcn:component ${name} */`
+const fragmentEnd = (name) => `/* arkcn:component ${name}:end */`
+
+function replaceBlock(css, start, end, block) {
+  const i = css.indexOf(start)
+  const j = css.indexOf(end)
+  if (i >= 0 && j > i) {
+    const current = css.slice(i, j + end.length + 1)
+    if (current === block) return { css, result: "unchanged" }
+    return { css: css.slice(0, i) + block + css.slice(j + end.length).replace(/^\n/, ""), result: "updated" }
+  }
+  return { css: css.trimEnd() + "\n\n" + block, result: "appended" }
+}
+
+/** Insert or replace the base block; creates the stylesheet (with the tailwind import) when missing. */
+export function mergeBaseCss(cwd, config, baseCss) {
+  const block = `${BASE_START}\n${baseCss.trim()}\n${BASE_END}\n`
+  let css = readProjectFile(cwd, config.css)
+  if (css === null) {
+    writeProjectFile(cwd, config.css, `@import "tailwindcss";\n\n${block}`)
+    return "created"
+  }
+  if (!/@import\s+"tailwindcss"/.test(css)) css = `@import "tailwindcss";\n` + css
+  const merged = replaceBlock(css, BASE_START, BASE_END, block)
+  if (merged.result !== "unchanged") writeProjectFile(cwd, config.css, merged.css)
+  return merged.result
+}
+
+export function mergeComponentCss(cwd, config, name, fragment) {
+  const css = readProjectFile(cwd, config.css) ?? `@import "tailwindcss";\n`
+  const block = `${fragmentStart(name)}\n${fragment.trim()}\n${fragmentEnd(name)}\n`
+  const merged = replaceBlock(css, fragmentStart(name), fragmentEnd(name), block)
+  if (merged.result !== "unchanged") writeProjectFile(cwd, config.css, merged.css)
+  return merged.result
+}
+
+export function installDependencies(cwd, deps) {
+  if (deps.length === 0) return { ok: true, skipped: true }
+  const pm = detectPackageManager(cwd)
+  const args = pm === "npm" ? ["install", ...deps] : ["add", ...deps]
+  const result = spawnSync(pm, args, { cwd, stdio: "inherit" })
+  return { ok: result.status === 0, pm, args }
+}
+
+/** Ensure tsconfig paths has "<alias>/*": ["./<srcDir>/*"]. Returns "ok" | "added" | "manual". */
+export function ensureTsconfigAlias(cwd, alias, srcDir = "src") {
+  for (const name of ["tsconfig.app.json", "tsconfig.json"]) {
+    const file = join(cwd, name)
+    if (!existsSync(file)) continue
+    const raw = readFileSync(file, "utf8")
+    let json
+    try {
+      json = JSON.parse(
+        raw
+          .replace(/\/\*[\s\S]*?\*\//g, "")
+          .replace(/^\s*\/\/.*$/gm, "")
+          .replace(/,(\s*[}\]])/g, "$1")
+      )
+    } catch {
+      return "manual"
+    }
+    const paths = json.compilerOptions?.paths ?? {}
+    if (paths[`${alias}/*`]) return "ok"
+    if (raw.includes("//") || raw.includes("/*")) return "manual"
+    json.compilerOptions = { ...json.compilerOptions, paths: { ...paths, [`${alias}/*`]: [`./${srcDir}/*`] } }
+    writeFileSync(file, JSON.stringify(json, null, 2) + "\n")
+    return "added"
+  }
+  return "manual"
+}
+
+export function detectBundlerAlias(cwd, alias) {
+  const candidates = [
+    "vite.config.ts",
+    "vite.config.js",
+    "vite.config.mts",
+    "next.config.ts",
+    "next.config.js",
+    "next.config.mjs",
+  ]
+  for (const name of candidates) {
+    const file = join(cwd, name)
+    if (!existsSync(file)) continue
+    const raw = readFileSync(file, "utf8")
+    if (name.startsWith("next")) return { file: name, ok: true, framework: "next" }
+    const ok = raw.includes(`"${alias}"`) || raw.includes(`'${alias}'`) || raw.includes("tsconfigPaths")
+    return { file: name, ok, framework: "vite" }
+  }
+  return { file: null, ok: false, framework: "unknown" }
+}

package/cli/registry.mjs

@@ -0,0 +1,50 @@
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+/** The registry shipped inside this package (generated by scripts/build-registry.mjs). */
+export const bundledDir = new URL("../registry/", import.meta.url).pathname
+
+/**
+ * A registry source: the bundled directory by default, or a base URL (`--registry`,
+ * `ARKCN_REGISTRY`) such as https://raw.githubusercontent.com/itsdanreed/arkcn/main/registry
+ */
+export function createRegistry(base) {
+  const remote = base && /^https?:\/\//.test(base)
+  const read = async (rel) => {
+    if (!remote) return readFileSync(join(base ?? bundledDir, rel), "utf8")
+    const url = `${base.replace(/\/$/, "")}/${rel}`
+    const res = await fetch(url)
+    if (!res.ok) throw new Error(`Registry request failed: ${res.status} ${url}`)
+    return res.text()
+  }
+  const cache = new Map()
+  const cached = (rel, parse) => {
+    if (!cache.has(rel)) cache.set(rel, read(rel).then(parse))
+    return cache.get(rel)
+  }
+  return {
+    source: remote ? base : "bundled",
+    index: () => cached("index.json", JSON.parse),
+    item: (name) => cached(`items/${name}.json`, JSON.parse).catch(() => null),
+    baseCss: () => cached("base.css", (s) => s),
+    /** Every item needed to install `names`, dependencies first, each once. */
+    async closure(names) {
+      const ordered = []
+      const seen = new Set()
+      const missing = []
+      const visit = async (name, chain) => {
+        if (seen.has(name)) return
+        const item = await this.item(name)
+        if (!item) {
+          missing.push(chain.length ? `${name} (needed by ${chain[chain.length - 1]})` : name)
+          return
+        }
+        seen.add(name)
+        for (const dep of item.registryDependencies) await visit(dep, [...chain, name])
+        ordered.push(item)
+      }
+      for (const name of names) await visit(name, [])
+      return { items: ordered, missing }
+    },
+  }
+}

package/cli/ui.mjs

@@ -0,0 +1,46 @@
+import { createInterface } from "node:readline/promises"
+import { stdin, stdout } from "node:process"
+
+const tty = stdout.isTTY && !process.env.NO_COLOR
+const ESC = "["
+const paint = (code) => (s) => (tty ? `${ESC}${code}m${s}${ESC}0m` : String(s))
+export const c = {
+  bold: paint("1"),
+  dim: paint("2"),
+  green: paint("32"),
+  yellow: paint("33"),
+  red: paint("31"),
+  cyan: paint("36"),
+}
+
+export const log = (...args) => console.log(...args)
+export const ok = (msg) => log(`${c.green("+")} ${msg}`)
+export const warn = (msg) => log(`${c.yellow("!")} ${msg}`)
+export const fail = (msg) => {
+  console.error(`${c.red("x")} ${msg}`)
+  process.exit(1)
+}
+
+export async function confirm(question, { yes = false, fallback = true } = {}) {
+  if (yes) return fallback
+  if (!stdin.isTTY) return fallback
+  const rl = createInterface({ input: stdin, output: stdout })
+  try {
+    const answer = (await rl.question(`${question} ${fallback ? "[Y/n]" : "[y/N]"} `)).trim().toLowerCase()
+    if (!answer) return fallback
+    return answer === "y" || answer === "yes"
+  } finally {
+    rl.close()
+  }
+}
+
+export function table(rows, headers) {
+  const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => String(r[i] ?? "").length)))
+  const line = (cells) =>
+    cells
+      .map((cell, i) => String(cell ?? "").padEnd(widths[i]))
+      .join("  ")
+      .trimEnd()
+  log(c.bold(line(headers)))
+  for (const r of rows) log(line(r))
+}