banhaten 0.5.0 → 0.6.0

package/src/cli/index.js

@@ -1,1002 +1,1002 @@
-#!/usr/bin/env node
-
-import { createHash } from "node:crypto"
-import fs from "node:fs/promises"
-import path from "node:path"
-import process from "node:process"
-import { fileURLToPath } from "node:url"
-import { parseCommandLine } from "./command-line.js"
-import {
-  inspectBanhatenProject,
-  printBanhatenDoctor,
-} from "./doctor.js"
-import {
-  assertFileUnchanged,
-  deferUntilApplied,
-  formatUnifiedDiff,
-  readFileForUpdate,
-  runFileTransaction,
-  writeFile,
-} from "./file-transaction.js"
-import {
-  applyPackageDependencyPlan,
-  createPackageDependencyPlan,
-  mergeDependencyRequirements,
-} from "./package-plan.js"
-import { inspectPackageInstallState } from "./package-install-state.js"
-import {
-  createInstallPlan,
-  resolveInstallTarget,
-} from "./install-plan.js"
-import {
-  createInstallPlanReceipt,
-  normalizeReceiptComponents,
-  normalizeReceiptTarget,
-  validateReceiptDestinations,
-} from "./install-receipt.js"
-import {
-  ensureGlobalCssImports,
-  removeExistingTokenBlock,
-} from "./global-css.js"
-import {
-  printInstallHint,
-  printResult,
-  resolveInstallAction,
-} from "./reporting.js"
-import { assertSchema } from "./schema-validation.js"
-import {
-  listComponents,
-  searchComponents,
-  showComponentDocs,
-  viewComponent,
-} from "./registry-query.js"
-
-const packageRoot = path.resolve(
-  path.dirname(fileURLToPath(import.meta.url)),
-  "..",
-  ".."
-)
-const registryRoot = path.join(packageRoot, "registry")
-const registryIndexPath = path.join(registryRoot, "index.json")
-const packageJsonPath = path.join(packageRoot, "package.json")
-const schemaRoot = path.join(packageRoot, "schema")
-
-const CONFIG_FILE = "banhaten.config.json"
-const INSTALL_RECEIPT_FILE = ".banhaten/installed.json"
-const SETUP_DEV_DEPENDENCIES = {
-  tailwindcss: "^4.0.0",
-}
-const VITE_DEV_DEPENDENCIES = {
-  "@tailwindcss/vite": "^4.0.0",
-}
-let runtimeOptions = {
-  json: false,
-  silent: false,
-}
-
-const DEFAULT_CONFIG = {
-  $schema: ".banhaten/schema/config.schema.json",
-  tailwind: {
-    css: "app/globals.css",
-  },
-  aliases: {
-    ui: "@/components/ui",
-    utils: "@/lib/utils",
-    hooks: "@/hooks",
-  },
-}
-
-// Top-level keys from the shadcn-shaped config this CLI grew out of. They are
-// deliberately migrated away rather than rejected, so an existing project can
-// upgrade in place. Every *other* unknown key is a real error: without this
-// list, dropping unknown keys wholesale is indistinguishable from silently
-// destroying a setting the user meant to keep.
-const LEGACY_CONFIG_KEYS = Object.freeze(["style", "tsx", "rsc", "iconLibrary"])
-
-function stripLegacyConfigKeys(config) {
-  const next = { ...config }
-  for (const key of LEGACY_CONFIG_KEYS) delete next[key]
-  return next
-}
-
-function findLegacyConfigKeys(config) {
-  return LEGACY_CONFIG_KEYS.filter((key) => key in config)
-}
-
-const registry = await readJson(registryIndexPath)
-const packageManifest = await readJson(packageJsonPath)
-const registrySchema = await readJson(path.join(schemaRoot, "registry.schema.json"))
-const configSchema = await readJson(path.join(schemaRoot, "config.schema.json"))
-assertSchema(registry, registrySchema, "registry/index.json")
-
-main().catch((error) => {
-  console.error(`banhaten: ${error.message}`)
-  process.exitCode = 1
-})
-
-async function main() {
-  const { command, positionals, flags } = parseCommandLine(process.argv.slice(2))
-  runtimeOptions = {
-    json: Boolean(flags.json),
-    silent: Boolean(flags.silent),
-  }
-
-  if (command === "version" || flags.version) {
-    console.log(packageManifest.version)
-    return
-  }
-
-  if (!command || command === "help" || flags.help) {
-    printHelp()
-    return
-  }
-
-  if (command === "list") {
-    listComponents(registry, runtimeOptions)
-    return
-  }
-
-  if (command === "search") {
-    searchComponents(registry, positionals, runtimeOptions)
-    return
-  }
-
-  if (command === "docs") {
-    await showComponentDocs(registry, packageRoot, positionals, runtimeOptions)
-    return
-  }
-
-  if (command === "view") {
-    await viewComponent(
-      registry,
-      registryRoot,
-      positionals,
-      flags,
-      runtimeOptions
-    )
-    return
-  }
-
-  if (command === "doctor") {
-    const report = await inspectBanhatenProject({
-      cwd: path.resolve(flags.cwd || process.cwd()),
-      registryVersion: packageManifest.version,
-    })
-    printBanhatenDoctor(report, runtimeOptions)
-    if (report.summary.errors > 0) process.exitCode = 1
-    return
-  }
-
-  if (command === "init") {
-    await runFileTransaction(() => initProject(flags))
-    return
-  }
-
-  if (command === "add") {
-    await runFileTransaction(() => addComponents(positionals, flags))
-    return
-  }
-
-  if (command === "diff") {
-    await runFileTransaction(() => diffComponents(positionals, flags))
-    return
-  }
-
-  if (command === "update") {
-    await runFileTransaction(() => updateComponents(positionals, flags))
-    return
-  }
-
-  throw new Error(`unknown command "${command}"`)
-}
-
-function printHelp() {
-  console.log(`Banhaten design system
-
-Usage:
-  banhaten init [--cwd <path>] [--force] [--dry-run] [--json]
-  banhaten add <component...> [--cwd <path>] [--force] [--dry-run] [--json]
-  banhaten diff [component...] [--cwd <path>] [--json]
-  banhaten update [component...] [--cwd <path>] [--force] [--dry-run] [--json]
-  banhaten list [--json]
-  banhaten search <query> [--json]
-  banhaten docs <component> [--json]
-  banhaten view <component> [--file <registry-source>] [--json]
-  banhaten doctor [--cwd <path>] [--json]
-  banhaten version
-
-Examples:
-  npx banhaten init
-  npx banhaten add button
-  npx banhaten diff
-  npx banhaten update button
-  npx banhaten search input
-  npx banhaten docs button
-  npx banhaten view button
-  npx banhaten doctor
-
-Command flags:
-  --cwd <path>     Run project-aware commands against a project directory.
-  --dry-run        Preview init, add, or update writes.
-  --force          Replace locally modified generated files after review.
-  --json           Print machine-readable output where shown above.
-
-Global flags:
-  --help, -h       Print help.
-  --silent, -s     Suppress normal command output.
-  --yes, -y        Accepted for non-interactive scripts.
-  --version, -v    Print the installed CLI version.
-`)
-}
-
-async function initProject(flags) {
-  const cwd = path.resolve(flags.cwd || process.cwd())
-  const dryRun = Boolean(flags["dry-run"])
-  const force = Boolean(flags.force)
-  const config = await loadConfig(cwd)
-  const installPlan = await createInstallPlan(cwd, config)
-  const receipt = await readInstallReceipt(cwd)
-  validateReceiptDestinations(installPlan, receipt, registry)
-  const managedOptions = { dryRun, force, receipt }
-  const writes = []
-
-  writes.push(
-    ...(await writeConfig(cwd, config, { dryRun, force })),
-    ...(await writeProjectSchemaFiles(cwd, { dryRun, force })),
-    ...(await writeBaseFiles(installPlan, managedOptions)),
-    ...(await writeGlobalCss(installPlan, managedOptions)),
-    ...(await writeAliasConfig(installPlan, { dryRun, force }))
-  )
-
-  const packageResult = await updatePackageJson(
-    cwd,
-    getPackageChanges(installPlan, registry.base.dependencies || {}),
-    { dryRun }
-  )
-  writes.push(...packageResult.writes)
-  writes.push(...(await writeInstallReceipt(installPlan, [], { dryRun })))
-  const installResolution = await resolveInstallAction(
-    cwd,
-    packageResult.installRequired
-  )
-  for (const evidence of installResolution.evidence) {
-    await assertFileUnchanged(evidence.path, evidence.source)
-  }
-  const { install } = installResolution
-
-  deferUntilApplied(() => {
-    printResult(
-      "Initialized Banhaten design system",
-      writes,
-      dryRun,
-      runtimeOptions,
-      install
-    )
-    printInstallHint(install, dryRun, runtimeOptions)
-  })
-}
-
-async function addComponents(names, flags) {
-  if (names.length === 0) {
-    throw new Error("missing component name. Try `banhaten add button`.")
-  }
-
-  await writeComponents(names, flags, {
-    inferInstalled: false,
-    title: `Added ${names.join(", ")}`,
-  })
-}
-
-async function diffComponents(names, flags) {
-  await writeComponents(names, { ...flags, "dry-run": true, "show-diff": true }, {
-    inferInstalled: true,
-    title: names.length
-      ? `Checked ${names.join(", ")} for updates`
-      : "Checked installed components for updates",
-  })
-}
-
-async function updateComponents(names, flags) {
-  await writeComponents(names, flags, {
-    inferInstalled: true,
-    title: names.length
-      ? `Updated ${names.join(", ")}`
-      : "Updated installed components",
-  })
-}
-
-async function writeComponents(requestedNames, flags, options) {
-  const cwd = path.resolve(flags.cwd || process.cwd())
-  const dryRun = Boolean(flags["dry-run"])
-  const force = Boolean(flags.force)
-  const showDiff = Boolean(flags["show-diff"])
-  const config = await loadConfig(cwd)
-  const installPlan = await createInstallPlan(cwd, config)
-  const receipt = await readInstallReceipt(cwd)
-  validateReceiptDestinations(installPlan, receipt, registry)
-  const managedOptions = { dryRun, force, receipt, showDiff }
-  const selectedNames =
-    requestedNames.length > 0
-      ? requestedNames
-      : options.inferInstalled
-        ? await findInstalledComponents(installPlan)
-        : requestedNames
-
-  if (selectedNames.length === 0) {
-    throw new Error(
-      "no installed components found. Run `banhaten add button` first, or pass component names."
-    )
-  }
-
-  const names = resolveRegistryDependencies(selectedNames)
-
-  const writes = []
-  const deps = {}
-  const components = []
-
-  mergeDependencyRequirements(
-    deps,
-    registry.base.dependencies || {},
-    "registry base"
-  )
-
-  for (const name of names) {
-    const component = registry.components[name]
-    if (!component) {
-      throw new Error(`unknown component "${name}". Run \`banhaten list\`.`)
-    }
-
-    mergeDependencyRequirements(
-      deps,
-      component.dependencies || {},
-      `registry component "${name}"`
-    )
-    components.push({ component, name })
-  }
-
-  writes.push(
-    ...(await writeConfig(cwd, config, { dryRun, force })),
-    ...(await writeProjectSchemaFiles(cwd, { dryRun, force })),
-    ...(await writeBaseFiles(installPlan, managedOptions)),
-    ...(await writeGlobalCss(installPlan, managedOptions)),
-    ...(await writeAliasConfig(installPlan, { dryRun, force }))
-  )
-
-  for (const { component, name } of components) {
-    writes.push(
-      ...(await writeRegistryFiles(installPlan, component.files || [], {
-        ...managedOptions,
-        owner: name,
-      }))
-    )
-  }
-
-  const packageResult = await updatePackageJson(
-    cwd,
-    getPackageChanges(installPlan, deps),
-    { dryRun }
-  )
-  writes.push(...packageResult.writes)
-  writes.push(...(await writeInstallReceipt(installPlan, names, { dryRun })))
-  const installResolution = await resolveInstallAction(
-    cwd,
-    packageResult.installRequired
-  )
-  for (const evidence of installResolution.evidence) {
-    await assertFileUnchanged(evidence.path, evidence.source)
-  }
-  const { install } = installResolution
-
-  deferUntilApplied(() => {
-    printResult(options.title, writes, dryRun, runtimeOptions, install)
-    printInstallHint(install, dryRun, runtimeOptions)
-  })
-}
-
-async function readInstallReceipt(cwd) {
-  const receipt = await readJsonForUpdate(path.join(cwd, INSTALL_RECEIPT_FILE))
-  if (!receipt) return null
-  if (receipt.schemaVersion !== 1 || !receipt.components) {
-    throw new Error(
-      `${INSTALL_RECEIPT_FILE} is invalid. Re-run an explicit \`banhaten add <component> --force\` command to rebuild it.`
-    )
-  }
-  return receipt
-}
-
-async function findInstalledComponents(installPlan) {
-  const { cwd } = installPlan
-  const receiptPath = path.join(cwd, INSTALL_RECEIPT_FILE)
-  const receipt = await readInstallReceipt(cwd)
-  if (receipt) {
-    const installed = []
-    for (const [name, record] of Object.entries(receipt.components)) {
-      if (!registry.components[name] || !Array.isArray(record.files)) continue
-      if (
-        record.files.length > 0 &&
-        (await allPathsExist(
-          record.files.map((file) =>
-            path.join(cwd, normalizeReceiptTarget(file.target))
-          )
-        ))
-      ) {
-        installed.push(name)
-      }
-    }
-
-    return installed
-  }
-
-  const installed = []
-
-  for (const [name, component] of Object.entries(registry.components)) {
-    const files = component.files || []
-    if (files.length === 0) continue
-
-    const targetPaths = files.map((file) =>
-      path.join(cwd, resolveInstallTarget(installPlan, file.target))
-    )
-    if (await allPathsExist(targetPaths)) {
-      installed.push(name)
-    }
-  }
-
-  return installed
-}
-
-async function writeInstallReceipt(installPlan, names, options) {
-  const { cwd } = installPlan
-  const receiptPath = path.join(cwd, INSTALL_RECEIPT_FILE)
-  const current = (await readJsonForUpdate(receiptPath)) || {
-    schemaVersion: 1,
-    components: {},
-  }
-  const components = normalizeReceiptComponents(current.components || {})
-  const managedFiles = Object.fromEntries(
-    Object.entries(current.managedFiles || {}).map(([target, record]) => [
-      normalizeReceiptTarget(target),
-      record,
-    ])
-  )
-
-  await addManagedFileRecords(
-    managedFiles,
-    installPlan,
-    registry.base.files || [],
-    "base"
-  )
-
-  for (const name of names) {
-    const component = registry.components[name]
-    await addManagedFileRecords(
-      managedFiles,
-      installPlan,
-      component.files || [],
-      name
-    )
-    components[name] = {
-      files: await Promise.all(
-        (component.files || []).map(async (file) => {
-          const sourcePath = path.join(registryRoot, file.source)
-          const source = await fs.readFile(sourcePath)
-          const target = resolveInstallTarget(installPlan, file.target)
-          const content = isTextRegistryFile(file.source)
-            ? applyTemplate(source.toString("utf8"), installPlan, target)
-            : source
-
-          return {
-            target,
-            sha256: createHash("sha256").update(content).digest("hex"),
-          }
-        })
-      ),
-    }
-  }
-
-  const next = {
-    schemaVersion: 1,
-    registryVersion: packageManifest.version,
-    installPlan: createInstallPlanReceipt(installPlan),
-    components: sortObject(components),
-    managedFiles: sortObject(managedFiles),
-    tokenCss: await createTokenCssReceipt(installPlan),
-  }
-  const status = await writeFile(
-    receiptPath,
-    `${JSON.stringify(next, null, 2)}\n`,
-    { dryRun: options.dryRun, force: true }
-  )
-
-  return [`${status} ${INSTALL_RECEIPT_FILE}`]
-}
-
-async function addManagedFileRecords(records, installPlan, files, owner) {
-  for (const file of files) {
-    const source = await fs.readFile(path.join(registryRoot, file.source))
-    const target = resolveInstallTarget(installPlan, file.target)
-    const content = isTextRegistryFile(file.source)
-      ? applyTemplate(source.toString("utf8"), installPlan, target)
-      : source
-    records[target] = {
-      owner,
-      sha256: hashContent(content),
-    }
-  }
-}
-
-async function createTokenCssReceipt(installPlan) {
-  const tokenCss = await fs.readFile(
-    path.join(registryRoot, "styles", "globals.css"),
-    "utf8"
-  )
-  return {
-    target: installPlan.destinations.css,
-    sha256: hashNormalizedText(tokenCss),
-  }
-}
-
-async function allPathsExist(paths) {
-  const results = await Promise.all(paths.map((targetPath) => exists(targetPath)))
-  return results.every(Boolean)
-}
-
-function resolveRegistryDependencies(names) {
-  const resolved = []
-  const seen = new Set()
-  const visiting = new Set()
-
-  for (const name of names) {
-    visit(name)
-  }
-
-  return resolved
-
-  function visit(name) {
-    const component = registry.components[name]
-    if (!component) {
-      throw new Error(`unknown component "${name}". Run \`banhaten list\`.`)
-    }
-
-    if (seen.has(name)) return
-    if (visiting.has(name)) {
-      throw new Error(`circular registry dependency detected at "${name}".`)
-    }
-
-    visiting.add(name)
-    for (const dependency of component.registryDependencies || []) {
-      visit(dependency)
-    }
-    visiting.delete(name)
-
-    seen.add(name)
-    resolved.push(name)
-  }
-}
-
-async function loadConfig(cwd) {
-  const configPath = path.join(cwd, CONFIG_FILE)
-  const componentsPath = path.join(cwd, "components.json")
-  const config = structuredClone(DEFAULT_CONFIG)
-
-  const componentsConfig = await readJsonForUpdate(componentsPath)
-  let hasExplicitCssPath = false
-  if (componentsConfig) {
-    if (componentsConfig.tailwind?.css) {
-      config.tailwind.css = componentsConfig.tailwind.css
-      hasExplicitCssPath = true
-    }
-    config.aliases.utils = componentsConfig.aliases?.utils || config.aliases.utils
-    config.aliases.hooks = componentsConfig.aliases?.hooks || config.aliases.hooks
-    config.aliases.ui =
-      componentsConfig.aliases?.ui ||
-      appendAliasSegment(componentsConfig.aliases?.components, "ui") ||
-      config.aliases.ui
-  }
-
-  const localConfig = await readJsonForUpdate(configPath)
-  if (localConfig) {
-    // Validate what the user actually wrote, before it is merged onto the
-    // defaults. Validating the merged object instead would apply
-    // `additionalProperties: false` to something that structurally cannot carry
-    // an unknown top-level key, so a stray key would pass here and then be
-    // silently dropped by writeConfig. Known legacy keys are stripped first so
-    // they migrate instead of failing.
-    assertSchema(stripLegacyConfigKeys(localConfig), configSchema, CONFIG_FILE)
-
-    if (localConfig.tailwind?.css) hasExplicitCssPath = true
-    config.tailwind = { ...config.tailwind, ...(localConfig.tailwind || {}) }
-    config.aliases = { ...config.aliases, ...(localConfig.aliases || {}) }
-  }
-
-  if (!hasExplicitCssPath) {
-    config.tailwind.css = await detectCssPath(cwd, config.tailwind.css)
-  }
-
-  assertSchema(config, configSchema, CONFIG_FILE)
-
-  return config
-}
-
-async function detectCssPath(cwd, fallback) {
-  const candidates = [
-    "app/globals.css",
-    "src/app/globals.css",
-    "src/index.css",
-    "src/globals.css",
-    "styles/globals.css",
-  ]
-
-  for (const candidate of candidates) {
-    if (await exists(path.join(cwd, candidate))) return candidate
-  }
-
-  if (await exists(path.join(cwd, "src", "app"))) return "src/app/globals.css"
-
-  return fallback
-}
-
-async function writeConfig(cwd, config, options) {
-  const configPath = path.join(cwd, CONFIG_FILE)
-  if ((await exists(configPath)) && !options.force) {
-    const current = await fs.readFile(configPath, "utf8")
-    const currentConfig = JSON.parse(current)
-    // Spread the existing file first so any key this version does not manage
-    // survives the rewrite. Rebuilding from a fixed whitelist would delete it
-    // and still report the write as a plain "updated". Legacy keys are the one
-    // intentional exception, and the removal is reported rather than silent.
-    const legacyKeys = findLegacyConfigKeys(currentConfig)
-    const nextConfig = {
-      ...stripLegacyConfigKeys(currentConfig),
-      $schema: DEFAULT_CONFIG.$schema,
-      tailwind: config.tailwind,
-      aliases: config.aliases,
-    }
-
-    if (JSON.stringify(currentConfig) !== JSON.stringify(nextConfig)) {
-      const status = await writeFile(
-        configPath,
-        `${JSON.stringify(nextConfig, null, 2)}\n`,
-        { dryRun: options.dryRun }
-      )
-
-      const notes = [`${status} ${relative(cwd, configPath)}`]
-      if (legacyKeys.length > 0) {
-        notes.push(
-          `removed legacy config ${legacyKeys.length === 1 ? "key" : "keys"} ` +
-            `${legacyKeys.map((key) => JSON.stringify(key)).join(", ")} from ` +
-            `${relative(cwd, configPath)}`
-        )
-      }
-      return notes
-    }
-
-    return [`kept ${relative(cwd, configPath)}`]
-  }
-
-  const status = await writeFile(
-    configPath,
-    `${JSON.stringify(config, null, 2)}\n`,
-    options
-  )
-  return [`${status} ${relative(cwd, configPath)}`]
-}
-
-async function writeProjectSchemaFiles(cwd, options) {
-  const schemaFiles = [
-    "config.schema.json",
-    "registry.schema.json",
-    "tokens.schema.json",
-  ]
-  const writes = []
-
-  for (const schemaFile of schemaFiles) {
-    const sourcePath = path.join(schemaRoot, schemaFile)
-    const targetPath = path.join(cwd, ".banhaten", "schema", schemaFile)
-    const source = await fs.readFile(sourcePath, "utf8")
-    const status = await writeFile(targetPath, source, options)
-
-    writes.push(`${status} ${relative(cwd, targetPath)}`)
-  }
-
-  return writes
-}
-
-async function writeBaseFiles(installPlan, options) {
-  return writeRegistryFiles(installPlan, registry.base.files || [], {
-    ...options,
-    owner: "base",
-  })
-}
-
-async function writeRegistryFiles(installPlan, files, options) {
-  const { cwd } = installPlan
-  const writes = []
-
-  for (const file of files) {
-    const sourcePath = path.join(registryRoot, file.source)
-    const targetPath = path.join(
-      cwd,
-      resolveInstallTarget(installPlan, file.target)
-    )
-    const source = await fs.readFile(sourcePath)
-    const content = isTextRegistryFile(file.source)
-      ? applyTemplate(
-          source.toString("utf8"),
-          installPlan,
-          relative(cwd, targetPath)
-        )
-      : source
-    const target = relative(cwd, targetPath)
-
-    const current = await readFileForUpdate(targetPath)
-    assertManagedFileSafe(current, content, target, options)
-
-    const status = await writeFile(targetPath, content, options)
-    writes.push(`${status} ${target}`)
-    if (options.showDiff && status === "would update") {
-      writes.push(formatUnifiedDiff(
-        target,
-        isTextRegistryFile(file.source) ? current.toString("utf8") : current,
-        content
-      ))
-    }
-  }
-
-  return writes
-}
-
-async function writeGlobalCss(installPlan, options) {
-  const { cwd } = installPlan
-  const cssPath = path.join(cwd, installPlan.destinations.css)
-  const sourcePath = path.join(registryRoot, "styles", "globals.css")
-  const tokenCss = await fs.readFile(sourcePath, "utf8")
-  const current = await readTextForUpdate(cssPath)
-  const tokenBlock = current
-    ? removeExistingTokenBlock(current, relative(cwd, cssPath))
-    : { content: "", found: false }
-
-  const nextCss = current
-    ? `${tokenBlock.content.trimEnd()}\n\n${tokenCss}\n`
-    : `${tokenCss}\n`
-  const next = ensureGlobalCssImports(nextCss)
-
-  if (
-    current &&
-    tokenBlock.found &&
-    next !== current &&
-    !options.dryRun &&
-    !options.force
-  ) {
-    const expectedHash = options.receipt?.tokenCss?.sha256
-    const currentHash = hashNormalizedText(tokenBlock.block)
-    if (!expectedHash || currentHash !== expectedHash) {
-      throw new Error(
-        `${relative(cwd, cssPath)} contains local changes inside the generated Banhaten token block. ` +
-        "Run `banhaten diff` to inspect them, move intentional overrides outside the generated block, or re-run with `--force`."
-      )
-    }
-  }
-
-  const status = await writeFile(cssPath, next, options)
-  const writes = [`${status} ${relative(cwd, cssPath)}`]
-  if (options.showDiff && status === "would update" && current !== null) {
-    writes.push(formatUnifiedDiff(relative(cwd, cssPath), current, next))
-  }
-  return writes
-}
-
-async function writeAliasConfig(installPlan, options) {
-  const writes = []
-
-  for (const plannedConfig of [installPlan.typescript, installPlan.vite]) {
-    if (!plannedConfig) continue
-    const status = await writeFile(
-      plannedConfig.targetPath,
-      plannedConfig.nextSource,
-      {
-        dryRun: options.dryRun,
-        expectedCurrent: plannedConfig.currentSource,
-        force: true,
-      }
-    )
-    writes.push(
-      `${status} ${relative(installPlan.cwd, plannedConfig.targetPath)}`
-    )
-  }
-
-  return writes
-}
-
-function getPackageChanges(installPlan, dependencies) {
-  const devDependencies = { ...SETUP_DEV_DEPENDENCIES }
-  if (installPlan.vite) {
-    Object.assign(devDependencies, VITE_DEV_DEPENDENCIES)
-  }
-
-  return {
-    dependencies,
-    devDependencies,
-  }
-}
-
-async function updatePackageJson(cwd, changes, options) {
-  const packagePath = path.join(cwd, "package.json")
-  const currentSource = await readTextForUpdate(packagePath)
-  const packageExists = currentSource !== null
-  const packageJson = currentSource !== null ? JSON.parse(currentSource) : {
-    name: path.basename(cwd).toLowerCase(),
-    version: "0.0.0",
-    private: true,
-  }
-  const packagePlan = createPackageDependencyPlan(packageJson, changes)
-
-  if (packagePlan.operations.length === 0 && packageExists) {
-    await assertFileUnchanged(packagePath, currentSource)
-    const installState = await inspectPackageInstallState({
-      cwd,
-      packageJson,
-      requirements: packagePlan.requirements,
-    })
-    for (const evidence of installState.evidence) {
-      await assertFileUnchanged(evidence.path, evidence.source)
-    }
-    return {
-      installRequired: installState.required,
-      writes: [`kept ${relative(cwd, packagePath)}`],
-    }
-  }
-
-  applyPackageDependencyPlan(packageJson, packagePlan.operations)
-
-  const status = await writeFile(packagePath, `${JSON.stringify(packageJson, null, 2)}\n`, {
-    dryRun: options.dryRun,
-    expectedCurrent: currentSource,
-    force: true,
-  })
-
-  return {
-    installRequired: packagePlan.operations.length > 0,
-    writes: [`${status} ${relative(cwd, packagePath)}`],
-  }
-}
-
-function applyTemplate(source, installPlan, target) {
-  const replacements = {
-    "@/components/ui": resolveTemplateImport(
-      installPlan,
-      target,
-      "ui"
-    ),
-    "@/lib/utils": resolveTemplateImport(
-      installPlan,
-      target,
-      "utils"
-    ),
-    "@/hooks": resolveTemplateImport(
-      installPlan,
-      target,
-      "hooks"
-    ),
-  }
-
-  return source.replace(
-    /@\/components\/ui|@\/lib\/utils|@\/hooks/g,
-    (match) => replacements[match]
-  )
-}
-
-function resolveTemplateImport(installPlan, target, destinationName) {
-  const configuredAlias = installPlan.config.aliases[destinationName]
-  if (
-    configuredAlias === "@" ||
-    configuredAlias === "~" ||
-    configuredAlias.startsWith("@/") ||
-    configuredAlias.startsWith("~/")
-  ) {
-    return configuredAlias.replace(/\/$/, "")
-  }
-
-  const targetDirectory = path.posix.dirname(
-    normalizeReceiptTarget(target)
-  )
-  const destination = installPlan.destinations[destinationName]
-  const relativeImport = path.posix.relative(targetDirectory, destination)
-
-  if (!relativeImport) return "."
-  return relativeImport.startsWith(".")
-    ? relativeImport
-    : `./${relativeImport}`
-}
-
-function isTextRegistryFile(source) {
-  return !/\.(avif|eot|gif|ico|jpe?g|otf|png|ttf|webp|woff2?)$/i.test(source)
-}
-
-async function readJson(filePath) {
-  return JSON.parse(await fs.readFile(filePath, "utf8"))
-}
-
-async function readJsonForUpdate(filePath) {
-  const source = await readTextForUpdate(filePath)
-  return source === null ? null : JSON.parse(source)
-}
-
-async function readTextForUpdate(filePath) {
-  const source = await readFileForUpdate(filePath)
-  return source === null ? null : source.toString("utf8")
-}
-
-function assertManagedFileSafe(current, nextContent, target, options) {
-  if (options.dryRun || options.force || current === null) return
-
-  const next = Buffer.isBuffer(nextContent)
-    ? nextContent
-    : Buffer.from(nextContent, "utf8")
-  if (current.equals(next)) return
-
-  const expectedHash = findManagedFileHash(options.receipt, target)
-  const currentHash = hashContent(current)
-  if (expectedHash && currentHash === expectedHash) return
-
-  const owner = options.owner ? ` (${options.owner})` : ""
-  const reason = expectedHash
-    ? "has local changes since Banhaten installed it"
-    : "already exists without a Banhaten ownership receipt"
-  const diffCommand = ["banhaten", "diff", options.owner === "base" ? "" : options.owner]
-    .filter(Boolean)
-    .join(" ")
-  throw new Error(
-    `${target}${owner} ${reason}. Run \`${diffCommand}\` to inspect the registry version, ` +
-    "or re-run the command with `--force` to replace the file."
-  )
-}
-
-function findManagedFileHash(receipt, target) {
-  const normalizedTarget = normalizeReceiptTarget(target)
-  const direct = Object.entries(receipt?.managedFiles || {}).find(
-    ([recordedTarget]) =>
-      normalizeReceiptTarget(recordedTarget) === normalizedTarget
-  )?.[1]?.sha256
-  if (direct) return direct
-
-  for (const component of Object.values(receipt?.components || {})) {
-    const match = component.files?.find(
-      (file) => normalizeReceiptTarget(file.target) === normalizedTarget
-    )
-    if (match?.sha256) return match.sha256
-  }
-
-  return null
-}
-
-function hashContent(content) {
-  return createHash("sha256").update(content).digest("hex")
-}
-
-function hashNormalizedText(content) {
-  return hashContent(String(content).replace(/\r\n/g, "\n").trim())
-}
-
-async function exists(filePath) {
-  try {
-    await fs.access(filePath)
-    return true
-  } catch {
-    return false
-  }
-}
-
-function appendAliasSegment(alias, segment) {
-  if (!alias) return null
-  return `${alias.replace(/\/$/, "")}/${segment}`
-}
-
-function sortObject(value) {
-  return Object.fromEntries(
-    Object.entries(value).sort(([left], [right]) => left.localeCompare(right))
-  )
-}
-
-function relative(cwd, targetPath) {
-  return path.relative(cwd, targetPath).replaceAll("\\", "/")
-}
+#!/usr/bin/env node
+
+import { createHash } from "node:crypto"
+import fs from "node:fs/promises"
+import path from "node:path"
+import process from "node:process"
+import { fileURLToPath } from "node:url"
+import { parseCommandLine } from "./command-line.js"
+import {
+  inspectBanhatenProject,
+  printBanhatenDoctor,
+} from "./doctor.js"
+import {
+  assertFileUnchanged,
+  deferUntilApplied,
+  formatUnifiedDiff,
+  readFileForUpdate,
+  runFileTransaction,
+  writeFile,
+} from "./file-transaction.js"
+import {
+  applyPackageDependencyPlan,
+  createPackageDependencyPlan,
+  mergeDependencyRequirements,
+} from "./package-plan.js"
+import { inspectPackageInstallState } from "./package-install-state.js"
+import {
+  createInstallPlan,
+  resolveInstallTarget,
+} from "./install-plan.js"
+import {
+  createInstallPlanReceipt,
+  normalizeReceiptComponents,
+  normalizeReceiptTarget,
+  validateReceiptDestinations,
+} from "./install-receipt.js"
+import {
+  ensureGlobalCssImports,
+  removeExistingTokenBlock,
+} from "./global-css.js"
+import {
+  printInstallHint,
+  printResult,
+  resolveInstallAction,
+} from "./reporting.js"
+import { assertSchema } from "./schema-validation.js"
+import {
+  listComponents,
+  searchComponents,
+  showComponentDocs,
+  viewComponent,
+} from "./registry-query.js"
+
+const packageRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  ".."
+)
+const registryRoot = path.join(packageRoot, "registry")
+const registryIndexPath = path.join(registryRoot, "index.json")
+const packageJsonPath = path.join(packageRoot, "package.json")
+const schemaRoot = path.join(packageRoot, "schema")
+
+const CONFIG_FILE = "banhaten.config.json"
+const INSTALL_RECEIPT_FILE = ".banhaten/installed.json"
+const SETUP_DEV_DEPENDENCIES = {
+  tailwindcss: "^4.0.0",
+}
+const VITE_DEV_DEPENDENCIES = {
+  "@tailwindcss/vite": "^4.0.0",
+}
+let runtimeOptions = {
+  json: false,
+  silent: false,
+}
+
+const DEFAULT_CONFIG = {
+  $schema: ".banhaten/schema/config.schema.json",
+  tailwind: {
+    css: "app/globals.css",
+  },
+  aliases: {
+    ui: "@/components/ui",
+    utils: "@/lib/utils",
+    hooks: "@/hooks",
+  },
+}
+
+// Top-level keys from the shadcn-shaped config this CLI grew out of. They are
+// deliberately migrated away rather than rejected, so an existing project can
+// upgrade in place. Every *other* unknown key is a real error: without this
+// list, dropping unknown keys wholesale is indistinguishable from silently
+// destroying a setting the user meant to keep.
+const LEGACY_CONFIG_KEYS = Object.freeze(["style", "tsx", "rsc", "iconLibrary"])
+
+function stripLegacyConfigKeys(config) {
+  const next = { ...config }
+  for (const key of LEGACY_CONFIG_KEYS) delete next[key]
+  return next
+}
+
+function findLegacyConfigKeys(config) {
+  return LEGACY_CONFIG_KEYS.filter((key) => key in config)
+}
+
+const registry = await readJson(registryIndexPath)
+const packageManifest = await readJson(packageJsonPath)
+const registrySchema = await readJson(path.join(schemaRoot, "registry.schema.json"))
+const configSchema = await readJson(path.join(schemaRoot, "config.schema.json"))
+assertSchema(registry, registrySchema, "registry/index.json")
+
+main().catch((error) => {
+  console.error(`banhaten: ${error.message}`)
+  process.exitCode = 1
+})
+
+async function main() {
+  const { command, positionals, flags } = parseCommandLine(process.argv.slice(2))
+  runtimeOptions = {
+    json: Boolean(flags.json),
+    silent: Boolean(flags.silent),
+  }
+
+  if (command === "version" || flags.version) {
+    console.log(packageManifest.version)
+    return
+  }
+
+  if (!command || command === "help" || flags.help) {
+    printHelp()
+    return
+  }
+
+  if (command === "list") {
+    listComponents(registry, runtimeOptions)
+    return
+  }
+
+  if (command === "search") {
+    searchComponents(registry, positionals, runtimeOptions)
+    return
+  }
+
+  if (command === "docs") {
+    await showComponentDocs(registry, packageRoot, positionals, runtimeOptions)
+    return
+  }
+
+  if (command === "view") {
+    await viewComponent(
+      registry,
+      registryRoot,
+      positionals,
+      flags,
+      runtimeOptions
+    )
+    return
+  }
+
+  if (command === "doctor") {
+    const report = await inspectBanhatenProject({
+      cwd: path.resolve(flags.cwd || process.cwd()),
+      registryVersion: packageManifest.version,
+    })
+    printBanhatenDoctor(report, runtimeOptions)
+    if (report.summary.errors > 0) process.exitCode = 1
+    return
+  }
+
+  if (command === "init") {
+    await runFileTransaction(() => initProject(flags))
+    return
+  }
+
+  if (command === "add") {
+    await runFileTransaction(() => addComponents(positionals, flags))
+    return
+  }
+
+  if (command === "diff") {
+    await runFileTransaction(() => diffComponents(positionals, flags))
+    return
+  }
+
+  if (command === "update") {
+    await runFileTransaction(() => updateComponents(positionals, flags))
+    return
+  }
+
+  throw new Error(`unknown command "${command}"`)
+}
+
+function printHelp() {
+  console.log(`Banhaten design system
+
+Usage:
+  banhaten init [--cwd <path>] [--force] [--dry-run] [--json]
+  banhaten add <component...> [--cwd <path>] [--force] [--dry-run] [--json]
+  banhaten diff [component...] [--cwd <path>] [--json]
+  banhaten update [component...] [--cwd <path>] [--force] [--dry-run] [--json]
+  banhaten list [--json]
+  banhaten search <query> [--json]
+  banhaten docs <component> [--json]
+  banhaten view <component> [--file <registry-source>] [--json]
+  banhaten doctor [--cwd <path>] [--json]
+  banhaten version
+
+Examples:
+  npx banhaten init
+  npx banhaten add button
+  npx banhaten diff
+  npx banhaten update button
+  npx banhaten search input
+  npx banhaten docs button
+  npx banhaten view button
+  npx banhaten doctor
+
+Command flags:
+  --cwd <path>     Run project-aware commands against a project directory.
+  --dry-run        Preview init, add, or update writes.
+  --force          Replace locally modified generated files after review.
+  --json           Print machine-readable output where shown above.
+
+Global flags:
+  --help, -h       Print help.
+  --silent, -s     Suppress normal command output.
+  --yes, -y        Accepted for non-interactive scripts.
+  --version, -v    Print the installed CLI version.
+`)
+}
+
+async function initProject(flags) {
+  const cwd = path.resolve(flags.cwd || process.cwd())
+  const dryRun = Boolean(flags["dry-run"])
+  const force = Boolean(flags.force)
+  const config = await loadConfig(cwd)
+  const installPlan = await createInstallPlan(cwd, config)
+  const receipt = await readInstallReceipt(cwd)
+  validateReceiptDestinations(installPlan, receipt, registry)
+  const managedOptions = { dryRun, force, receipt }
+  const writes = []
+
+  writes.push(
+    ...(await writeConfig(cwd, config, { dryRun, force })),
+    ...(await writeProjectSchemaFiles(cwd, { dryRun, force })),
+    ...(await writeBaseFiles(installPlan, managedOptions)),
+    ...(await writeGlobalCss(installPlan, managedOptions)),
+    ...(await writeAliasConfig(installPlan, { dryRun, force }))
+  )
+
+  const packageResult = await updatePackageJson(
+    cwd,
+    getPackageChanges(installPlan, registry.base.dependencies || {}),
+    { dryRun }
+  )
+  writes.push(...packageResult.writes)
+  writes.push(...(await writeInstallReceipt(installPlan, [], { dryRun })))
+  const installResolution = await resolveInstallAction(
+    cwd,
+    packageResult.installRequired
+  )
+  for (const evidence of installResolution.evidence) {
+    await assertFileUnchanged(evidence.path, evidence.source)
+  }
+  const { install } = installResolution
+
+  deferUntilApplied(() => {
+    printResult(
+      "Initialized Banhaten design system",
+      writes,
+      dryRun,
+      runtimeOptions,
+      install
+    )
+    printInstallHint(install, dryRun, runtimeOptions)
+  })
+}
+
+async function addComponents(names, flags) {
+  if (names.length === 0) {
+    throw new Error("missing component name. Try `banhaten add button`.")
+  }
+
+  await writeComponents(names, flags, {
+    inferInstalled: false,
+    title: `Added ${names.join(", ")}`,
+  })
+}
+
+async function diffComponents(names, flags) {
+  await writeComponents(names, { ...flags, "dry-run": true, "show-diff": true }, {
+    inferInstalled: true,
+    title: names.length
+      ? `Checked ${names.join(", ")} for updates`
+      : "Checked installed components for updates",
+  })
+}
+
+async function updateComponents(names, flags) {
+  await writeComponents(names, flags, {
+    inferInstalled: true,
+    title: names.length
+      ? `Updated ${names.join(", ")}`
+      : "Updated installed components",
+  })
+}
+
+async function writeComponents(requestedNames, flags, options) {
+  const cwd = path.resolve(flags.cwd || process.cwd())
+  const dryRun = Boolean(flags["dry-run"])
+  const force = Boolean(flags.force)
+  const showDiff = Boolean(flags["show-diff"])
+  const config = await loadConfig(cwd)
+  const installPlan = await createInstallPlan(cwd, config)
+  const receipt = await readInstallReceipt(cwd)
+  validateReceiptDestinations(installPlan, receipt, registry)
+  const managedOptions = { dryRun, force, receipt, showDiff }
+  const selectedNames =
+    requestedNames.length > 0
+      ? requestedNames
+      : options.inferInstalled
+        ? await findInstalledComponents(installPlan)
+        : requestedNames
+
+  if (selectedNames.length === 0) {
+    throw new Error(
+      "no installed components found. Run `banhaten add button` first, or pass component names."
+    )
+  }
+
+  const names = resolveRegistryDependencies(selectedNames)
+
+  const writes = []
+  const deps = {}
+  const components = []
+
+  mergeDependencyRequirements(
+    deps,
+    registry.base.dependencies || {},
+    "registry base"
+  )
+
+  for (const name of names) {
+    const component = registry.components[name]
+    if (!component) {
+      throw new Error(`unknown component "${name}". Run \`banhaten list\`.`)
+    }
+
+    mergeDependencyRequirements(
+      deps,
+      component.dependencies || {},
+      `registry component "${name}"`
+    )
+    components.push({ component, name })
+  }
+
+  writes.push(
+    ...(await writeConfig(cwd, config, { dryRun, force })),
+    ...(await writeProjectSchemaFiles(cwd, { dryRun, force })),
+    ...(await writeBaseFiles(installPlan, managedOptions)),
+    ...(await writeGlobalCss(installPlan, managedOptions)),
+    ...(await writeAliasConfig(installPlan, { dryRun, force }))
+  )
+
+  for (const { component, name } of components) {
+    writes.push(
+      ...(await writeRegistryFiles(installPlan, component.files || [], {
+        ...managedOptions,
+        owner: name,
+      }))
+    )
+  }
+
+  const packageResult = await updatePackageJson(
+    cwd,
+    getPackageChanges(installPlan, deps),
+    { dryRun }
+  )
+  writes.push(...packageResult.writes)
+  writes.push(...(await writeInstallReceipt(installPlan, names, { dryRun })))
+  const installResolution = await resolveInstallAction(
+    cwd,
+    packageResult.installRequired
+  )
+  for (const evidence of installResolution.evidence) {
+    await assertFileUnchanged(evidence.path, evidence.source)
+  }
+  const { install } = installResolution
+
+  deferUntilApplied(() => {
+    printResult(options.title, writes, dryRun, runtimeOptions, install)
+    printInstallHint(install, dryRun, runtimeOptions)
+  })
+}
+
+async function readInstallReceipt(cwd) {
+  const receipt = await readJsonForUpdate(path.join(cwd, INSTALL_RECEIPT_FILE))
+  if (!receipt) return null
+  if (receipt.schemaVersion !== 1 || !receipt.components) {
+    throw new Error(
+      `${INSTALL_RECEIPT_FILE} is invalid. Re-run an explicit \`banhaten add <component> --force\` command to rebuild it.`
+    )
+  }
+  return receipt
+}
+
+async function findInstalledComponents(installPlan) {
+  const { cwd } = installPlan
+  const receiptPath = path.join(cwd, INSTALL_RECEIPT_FILE)
+  const receipt = await readInstallReceipt(cwd)
+  if (receipt) {
+    const installed = []
+    for (const [name, record] of Object.entries(receipt.components)) {
+      if (!registry.components[name] || !Array.isArray(record.files)) continue
+      if (
+        record.files.length > 0 &&
+        (await allPathsExist(
+          record.files.map((file) =>
+            path.join(cwd, normalizeReceiptTarget(file.target))
+          )
+        ))
+      ) {
+        installed.push(name)
+      }
+    }
+
+    return installed
+  }
+
+  const installed = []
+
+  for (const [name, component] of Object.entries(registry.components)) {
+    const files = component.files || []
+    if (files.length === 0) continue
+
+    const targetPaths = files.map((file) =>
+      path.join(cwd, resolveInstallTarget(installPlan, file.target))
+    )
+    if (await allPathsExist(targetPaths)) {
+      installed.push(name)
+    }
+  }
+
+  return installed
+}
+
+async function writeInstallReceipt(installPlan, names, options) {
+  const { cwd } = installPlan
+  const receiptPath = path.join(cwd, INSTALL_RECEIPT_FILE)
+  const current = (await readJsonForUpdate(receiptPath)) || {
+    schemaVersion: 1,
+    components: {},
+  }
+  const components = normalizeReceiptComponents(current.components || {})
+  const managedFiles = Object.fromEntries(
+    Object.entries(current.managedFiles || {}).map(([target, record]) => [
+      normalizeReceiptTarget(target),
+      record,
+    ])
+  )
+
+  await addManagedFileRecords(
+    managedFiles,
+    installPlan,
+    registry.base.files || [],
+    "base"
+  )
+
+  for (const name of names) {
+    const component = registry.components[name]
+    await addManagedFileRecords(
+      managedFiles,
+      installPlan,
+      component.files || [],
+      name
+    )
+    components[name] = {
+      files: await Promise.all(
+        (component.files || []).map(async (file) => {
+          const sourcePath = path.join(registryRoot, file.source)
+          const source = await fs.readFile(sourcePath)
+          const target = resolveInstallTarget(installPlan, file.target)
+          const content = isTextRegistryFile(file.source)
+            ? applyTemplate(source.toString("utf8"), installPlan, target)
+            : source
+
+          return {
+            target,
+            sha256: createHash("sha256").update(content).digest("hex"),
+          }
+        })
+      ),
+    }
+  }
+
+  const next = {
+    schemaVersion: 1,
+    registryVersion: packageManifest.version,
+    installPlan: createInstallPlanReceipt(installPlan),
+    components: sortObject(components),
+    managedFiles: sortObject(managedFiles),
+    tokenCss: await createTokenCssReceipt(installPlan),
+  }
+  const status = await writeFile(
+    receiptPath,
+    `${JSON.stringify(next, null, 2)}\n`,
+    { dryRun: options.dryRun, force: true }
+  )
+
+  return [`${status} ${INSTALL_RECEIPT_FILE}`]
+}
+
+async function addManagedFileRecords(records, installPlan, files, owner) {
+  for (const file of files) {
+    const source = await fs.readFile(path.join(registryRoot, file.source))
+    const target = resolveInstallTarget(installPlan, file.target)
+    const content = isTextRegistryFile(file.source)
+      ? applyTemplate(source.toString("utf8"), installPlan, target)
+      : source
+    records[target] = {
+      owner,
+      sha256: hashContent(content),
+    }
+  }
+}
+
+async function createTokenCssReceipt(installPlan) {
+  const tokenCss = await fs.readFile(
+    path.join(registryRoot, "styles", "globals.css"),
+    "utf8"
+  )
+  return {
+    target: installPlan.destinations.css,
+    sha256: hashNormalizedText(tokenCss),
+  }
+}
+
+async function allPathsExist(paths) {
+  const results = await Promise.all(paths.map((targetPath) => exists(targetPath)))
+  return results.every(Boolean)
+}
+
+function resolveRegistryDependencies(names) {
+  const resolved = []
+  const seen = new Set()
+  const visiting = new Set()
+
+  for (const name of names) {
+    visit(name)
+  }
+
+  return resolved
+
+  function visit(name) {
+    const component = registry.components[name]
+    if (!component) {
+      throw new Error(`unknown component "${name}". Run \`banhaten list\`.`)
+    }
+
+    if (seen.has(name)) return
+    if (visiting.has(name)) {
+      throw new Error(`circular registry dependency detected at "${name}".`)
+    }
+
+    visiting.add(name)
+    for (const dependency of component.registryDependencies || []) {
+      visit(dependency)
+    }
+    visiting.delete(name)
+
+    seen.add(name)
+    resolved.push(name)
+  }
+}
+
+async function loadConfig(cwd) {
+  const configPath = path.join(cwd, CONFIG_FILE)
+  const componentsPath = path.join(cwd, "components.json")
+  const config = structuredClone(DEFAULT_CONFIG)
+
+  const componentsConfig = await readJsonForUpdate(componentsPath)
+  let hasExplicitCssPath = false
+  if (componentsConfig) {
+    if (componentsConfig.tailwind?.css) {
+      config.tailwind.css = componentsConfig.tailwind.css
+      hasExplicitCssPath = true
+    }
+    config.aliases.utils = componentsConfig.aliases?.utils || config.aliases.utils
+    config.aliases.hooks = componentsConfig.aliases?.hooks || config.aliases.hooks
+    config.aliases.ui =
+      componentsConfig.aliases?.ui ||
+      appendAliasSegment(componentsConfig.aliases?.components, "ui") ||
+      config.aliases.ui
+  }
+
+  const localConfig = await readJsonForUpdate(configPath)
+  if (localConfig) {
+    // Validate what the user actually wrote, before it is merged onto the
+    // defaults. Validating the merged object instead would apply
+    // `additionalProperties: false` to something that structurally cannot carry
+    // an unknown top-level key, so a stray key would pass here and then be
+    // silently dropped by writeConfig. Known legacy keys are stripped first so
+    // they migrate instead of failing.
+    assertSchema(stripLegacyConfigKeys(localConfig), configSchema, CONFIG_FILE)
+
+    if (localConfig.tailwind?.css) hasExplicitCssPath = true
+    config.tailwind = { ...config.tailwind, ...(localConfig.tailwind || {}) }
+    config.aliases = { ...config.aliases, ...(localConfig.aliases || {}) }
+  }
+
+  if (!hasExplicitCssPath) {
+    config.tailwind.css = await detectCssPath(cwd, config.tailwind.css)
+  }
+
+  assertSchema(config, configSchema, CONFIG_FILE)
+
+  return config
+}
+
+async function detectCssPath(cwd, fallback) {
+  const candidates = [
+    "app/globals.css",
+    "src/app/globals.css",
+    "src/index.css",
+    "src/globals.css",
+    "styles/globals.css",
+  ]
+
+  for (const candidate of candidates) {
+    if (await exists(path.join(cwd, candidate))) return candidate
+  }
+
+  if (await exists(path.join(cwd, "src", "app"))) return "src/app/globals.css"
+
+  return fallback
+}
+
+async function writeConfig(cwd, config, options) {
+  const configPath = path.join(cwd, CONFIG_FILE)
+  if ((await exists(configPath)) && !options.force) {
+    const current = await fs.readFile(configPath, "utf8")
+    const currentConfig = JSON.parse(current)
+    // Spread the existing file first so any key this version does not manage
+    // survives the rewrite. Rebuilding from a fixed whitelist would delete it
+    // and still report the write as a plain "updated". Legacy keys are the one
+    // intentional exception, and the removal is reported rather than silent.
+    const legacyKeys = findLegacyConfigKeys(currentConfig)
+    const nextConfig = {
+      ...stripLegacyConfigKeys(currentConfig),
+      $schema: DEFAULT_CONFIG.$schema,
+      tailwind: config.tailwind,
+      aliases: config.aliases,
+    }
+
+    if (JSON.stringify(currentConfig) !== JSON.stringify(nextConfig)) {
+      const status = await writeFile(
+        configPath,
+        `${JSON.stringify(nextConfig, null, 2)}\n`,
+        { dryRun: options.dryRun }
+      )
+
+      const notes = [`${status} ${relative(cwd, configPath)}`]
+      if (legacyKeys.length > 0) {
+        notes.push(
+          `removed legacy config ${legacyKeys.length === 1 ? "key" : "keys"} ` +
+            `${legacyKeys.map((key) => JSON.stringify(key)).join(", ")} from ` +
+            `${relative(cwd, configPath)}`
+        )
+      }
+      return notes
+    }
+
+    return [`kept ${relative(cwd, configPath)}`]
+  }
+
+  const status = await writeFile(
+    configPath,
+    `${JSON.stringify(config, null, 2)}\n`,
+    options
+  )
+  return [`${status} ${relative(cwd, configPath)}`]
+}
+
+async function writeProjectSchemaFiles(cwd, options) {
+  const schemaFiles = [
+    "config.schema.json",
+    "registry.schema.json",
+    "tokens.schema.json",
+  ]
+  const writes = []
+
+  for (const schemaFile of schemaFiles) {
+    const sourcePath = path.join(schemaRoot, schemaFile)
+    const targetPath = path.join(cwd, ".banhaten", "schema", schemaFile)
+    const source = await fs.readFile(sourcePath, "utf8")
+    const status = await writeFile(targetPath, source, options)
+
+    writes.push(`${status} ${relative(cwd, targetPath)}`)
+  }
+
+  return writes
+}
+
+async function writeBaseFiles(installPlan, options) {
+  return writeRegistryFiles(installPlan, registry.base.files || [], {
+    ...options,
+    owner: "base",
+  })
+}
+
+async function writeRegistryFiles(installPlan, files, options) {
+  const { cwd } = installPlan
+  const writes = []
+
+  for (const file of files) {
+    const sourcePath = path.join(registryRoot, file.source)
+    const targetPath = path.join(
+      cwd,
+      resolveInstallTarget(installPlan, file.target)
+    )
+    const source = await fs.readFile(sourcePath)
+    const content = isTextRegistryFile(file.source)
+      ? applyTemplate(
+          source.toString("utf8"),
+          installPlan,
+          relative(cwd, targetPath)
+        )
+      : source
+    const target = relative(cwd, targetPath)
+
+    const current = await readFileForUpdate(targetPath)
+    assertManagedFileSafe(current, content, target, options)
+
+    const status = await writeFile(targetPath, content, options)
+    writes.push(`${status} ${target}`)
+    if (options.showDiff && status === "would update") {
+      writes.push(formatUnifiedDiff(
+        target,
+        isTextRegistryFile(file.source) ? current.toString("utf8") : current,
+        content
+      ))
+    }
+  }
+
+  return writes
+}
+
+async function writeGlobalCss(installPlan, options) {
+  const { cwd } = installPlan
+  const cssPath = path.join(cwd, installPlan.destinations.css)
+  const sourcePath = path.join(registryRoot, "styles", "globals.css")
+  const tokenCss = await fs.readFile(sourcePath, "utf8")
+  const current = await readTextForUpdate(cssPath)
+  const tokenBlock = current
+    ? removeExistingTokenBlock(current, relative(cwd, cssPath))
+    : { content: "", found: false }
+
+  const nextCss = current
+    ? `${tokenBlock.content.trimEnd()}\n\n${tokenCss}\n`
+    : `${tokenCss}\n`
+  const next = ensureGlobalCssImports(nextCss)
+
+  if (
+    current &&
+    tokenBlock.found &&
+    next !== current &&
+    !options.dryRun &&
+    !options.force
+  ) {
+    const expectedHash = options.receipt?.tokenCss?.sha256
+    const currentHash = hashNormalizedText(tokenBlock.block)
+    if (!expectedHash || currentHash !== expectedHash) {
+      throw new Error(
+        `${relative(cwd, cssPath)} contains local changes inside the generated Banhaten token block. ` +
+        "Run `banhaten diff` to inspect them, move intentional overrides outside the generated block, or re-run with `--force`."
+      )
+    }
+  }
+
+  const status = await writeFile(cssPath, next, options)
+  const writes = [`${status} ${relative(cwd, cssPath)}`]
+  if (options.showDiff && status === "would update" && current !== null) {
+    writes.push(formatUnifiedDiff(relative(cwd, cssPath), current, next))
+  }
+  return writes
+}
+
+async function writeAliasConfig(installPlan, options) {
+  const writes = []
+
+  for (const plannedConfig of [installPlan.typescript, installPlan.vite]) {
+    if (!plannedConfig) continue
+    const status = await writeFile(
+      plannedConfig.targetPath,
+      plannedConfig.nextSource,
+      {
+        dryRun: options.dryRun,
+        expectedCurrent: plannedConfig.currentSource,
+        force: true,
+      }
+    )
+    writes.push(
+      `${status} ${relative(installPlan.cwd, plannedConfig.targetPath)}`
+    )
+  }
+
+  return writes
+}
+
+function getPackageChanges(installPlan, dependencies) {
+  const devDependencies = { ...SETUP_DEV_DEPENDENCIES }
+  if (installPlan.vite) {
+    Object.assign(devDependencies, VITE_DEV_DEPENDENCIES)
+  }
+
+  return {
+    dependencies,
+    devDependencies,
+  }
+}
+
+async function updatePackageJson(cwd, changes, options) {
+  const packagePath = path.join(cwd, "package.json")
+  const currentSource = await readTextForUpdate(packagePath)
+  const packageExists = currentSource !== null
+  const packageJson = currentSource !== null ? JSON.parse(currentSource) : {
+    name: path.basename(cwd).toLowerCase(),
+    version: "0.0.0",
+    private: true,
+  }
+  const packagePlan = createPackageDependencyPlan(packageJson, changes)
+
+  if (packagePlan.operations.length === 0 && packageExists) {
+    await assertFileUnchanged(packagePath, currentSource)
+    const installState = await inspectPackageInstallState({
+      cwd,
+      packageJson,
+      requirements: packagePlan.requirements,
+    })
+    for (const evidence of installState.evidence) {
+      await assertFileUnchanged(evidence.path, evidence.source)
+    }
+    return {
+      installRequired: installState.required,
+      writes: [`kept ${relative(cwd, packagePath)}`],
+    }
+  }
+
+  applyPackageDependencyPlan(packageJson, packagePlan.operations)
+
+  const status = await writeFile(packagePath, `${JSON.stringify(packageJson, null, 2)}\n`, {
+    dryRun: options.dryRun,
+    expectedCurrent: currentSource,
+    force: true,
+  })
+
+  return {
+    installRequired: packagePlan.operations.length > 0,
+    writes: [`${status} ${relative(cwd, packagePath)}`],
+  }
+}
+
+function applyTemplate(source, installPlan, target) {
+  const replacements = {
+    "@/components/ui": resolveTemplateImport(
+      installPlan,
+      target,
+      "ui"
+    ),
+    "@/lib/utils": resolveTemplateImport(
+      installPlan,
+      target,
+      "utils"
+    ),
+    "@/hooks": resolveTemplateImport(
+      installPlan,
+      target,
+      "hooks"
+    ),
+  }
+
+  return source.replace(
+    /@\/components\/ui|@\/lib\/utils|@\/hooks/g,
+    (match) => replacements[match]
+  )
+}
+
+function resolveTemplateImport(installPlan, target, destinationName) {
+  const configuredAlias = installPlan.config.aliases[destinationName]
+  if (
+    configuredAlias === "@" ||
+    configuredAlias === "~" ||
+    configuredAlias.startsWith("@/") ||
+    configuredAlias.startsWith("~/")
+  ) {
+    return configuredAlias.replace(/\/$/, "")
+  }
+
+  const targetDirectory = path.posix.dirname(
+    normalizeReceiptTarget(target)
+  )
+  const destination = installPlan.destinations[destinationName]
+  const relativeImport = path.posix.relative(targetDirectory, destination)
+
+  if (!relativeImport) return "."
+  return relativeImport.startsWith(".")
+    ? relativeImport
+    : `./${relativeImport}`
+}
+
+function isTextRegistryFile(source) {
+  return !/\.(avif|eot|gif|ico|jpe?g|otf|png|ttf|webp|woff2?)$/i.test(source)
+}
+
+async function readJson(filePath) {
+  return JSON.parse(await fs.readFile(filePath, "utf8"))
+}
+
+async function readJsonForUpdate(filePath) {
+  const source = await readTextForUpdate(filePath)
+  return source === null ? null : JSON.parse(source)
+}
+
+async function readTextForUpdate(filePath) {
+  const source = await readFileForUpdate(filePath)
+  return source === null ? null : source.toString("utf8")
+}
+
+function assertManagedFileSafe(current, nextContent, target, options) {
+  if (options.dryRun || options.force || current === null) return
+
+  const next = Buffer.isBuffer(nextContent)
+    ? nextContent
+    : Buffer.from(nextContent, "utf8")
+  if (current.equals(next)) return
+
+  const expectedHash = findManagedFileHash(options.receipt, target)
+  const currentHash = hashContent(current)
+  if (expectedHash && currentHash === expectedHash) return
+
+  const owner = options.owner ? ` (${options.owner})` : ""
+  const reason = expectedHash
+    ? "has local changes since Banhaten installed it"
+    : "already exists without a Banhaten ownership receipt"
+  const diffCommand = ["banhaten", "diff", options.owner === "base" ? "" : options.owner]
+    .filter(Boolean)
+    .join(" ")
+  throw new Error(
+    `${target}${owner} ${reason}. Run \`${diffCommand}\` to inspect the registry version, ` +
+    "or re-run the command with `--force` to replace the file."
+  )
+}
+
+function findManagedFileHash(receipt, target) {
+  const normalizedTarget = normalizeReceiptTarget(target)
+  const direct = Object.entries(receipt?.managedFiles || {}).find(
+    ([recordedTarget]) =>
+      normalizeReceiptTarget(recordedTarget) === normalizedTarget
+  )?.[1]?.sha256
+  if (direct) return direct
+
+  for (const component of Object.values(receipt?.components || {})) {
+    const match = component.files?.find(
+      (file) => normalizeReceiptTarget(file.target) === normalizedTarget
+    )
+    if (match?.sha256) return match.sha256
+  }
+
+  return null
+}
+
+function hashContent(content) {
+  return createHash("sha256").update(content).digest("hex")
+}
+
+function hashNormalizedText(content) {
+  return hashContent(String(content).replace(/\r\n/g, "\n").trim())
+}
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function appendAliasSegment(alias, segment) {
+  if (!alias) return null
+  return `${alias.replace(/\/$/, "")}/${segment}`
+}
+
+function sortObject(value) {
+  return Object.fromEntries(
+    Object.entries(value).sort(([left], [right]) => left.localeCompare(right))
+  )
+}
+
+function relative(cwd, targetPath) {
+  return path.relative(cwd, targetPath).replaceAll("\\", "/")
+}