banhaten 0.1.2 → 0.2.0

package/src/cli/index.js

@@ -1,9 +1,54 @@
 #!/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,
+  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)),
@@ -12,29 +57,24 @@ const packageRoot = path.resolve(
 )
 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 FONT_IMPORTS = [
-  '@import "@fontsource/inter/400.css";',
-  '@import "@fontsource/inter/500.css";',
-  '@import "@fontsource/inter/600.css";',
-  '@import "@fontsource/inter/700.css";',
-]
-const TAILWIND_IMPORT = '@import "tailwindcss";'
+const INSTALL_RECEIPT_FILE = ".banhaten/installed.json"
 const SETUP_DEV_DEPENDENCIES = {
   tailwindcss: "^4.0.0",
 }
 const VITE_DEV_DEPENDENCIES = {
   "@tailwindcss/vite": "^4.0.0",
 }
-const CSS_START = "/* Banhaten design system tokens:"
-const CSS_END = "/* End Banhaten design system tokens. */"
-const syncExistsCache = new Map()
+let runtimeOptions = {
+  json: false,
+  silent: false,
+}
 
 const DEFAULT_CONFIG = {
-  $schema: "https://banhaten.dev/schema.json",
-  style: "default",
-  tsx: true,
+  $schema: ".banhaten/schema/config.schema.json",
   tailwind: {
     css: "app/globals.css",
   },
@@ -45,7 +85,28 @@ const DEFAULT_CONFIG = {
   },
 }
 
+// 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}`)
@@ -53,132 +114,165 @@ main().catch((error) => {
 })
 
 async function main() {
-  const { command, positionals, flags } = parseArgs(process.argv.slice(2))
+  const { command, positionals, flags } = parseCommandLine(process.argv.slice(2))
+  runtimeOptions = {
+    json: Boolean(flags.json),
+    silent: Boolean(flags.silent),
+  }
 
-  if (!command || command === "help" || flags.help || flags.h) {
+  if (command === "version" || flags.version) {
+    console.log(packageManifest.version)
+    return
+  }
+
+  if (!command || command === "help" || flags.help) {
     printHelp()
     return
   }
 
   if (command === "list") {
-    listComponents()
+    listComponents(registry, runtimeOptions)
     return
   }
 
-  if (command === "init") {
-    await initProject(flags)
+  if (command === "search") {
+    searchComponents(registry, positionals, runtimeOptions)
     return
   }
 
-  if (command === "add") {
-    await addComponents(positionals, flags)
+  if (command === "docs") {
+    await showComponentDocs(registry, packageRoot, positionals, runtimeOptions)
     return
   }
 
-  if (command === "diff") {
-    await diffComponents(positionals, flags)
+  if (command === "view") {
+    await viewComponent(
+      registry,
+      registryRoot,
+      positionals,
+      flags,
+      runtimeOptions
+    )
     return
   }
 
-  if (command === "update") {
-    await updateComponents(positionals, flags)
+  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
   }
 
-  throw new Error(`unknown command "${command}"`)
-}
-
-function parseArgs(argv) {
-  const flags = {}
-  const positionals = []
-
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index]
-
-    if (arg === "-h") {
-      flags.h = true
-      continue
-    }
-
-    if (!arg.startsWith("--")) {
-      positionals.push(arg)
-      continue
-    }
-
-    const [rawKey, inlineValue] = arg.slice(2).split("=")
-    const key = rawKey.trim()
+  if (command === "init") {
+    await runFileTransaction(() => initProject(flags))
+    return
+  }
 
-    if (inlineValue !== undefined) {
-      flags[key] = inlineValue
-      continue
-    }
+  if (command === "add") {
+    await runFileTransaction(() => addComponents(positionals, flags))
+    return
+  }
 
-    const next = argv[index + 1]
-    if ((key === "cwd" || key === "out") && next && !next.startsWith("-")) {
-      flags[key] = next
-      index += 1
-      continue
-    }
+  if (command === "diff") {
+    await runFileTransaction(() => diffComponents(positionals, flags))
+    return
+  }
 
-    flags[key] = true
+  if (command === "update") {
+    await runFileTransaction(() => updateComponents(positionals, flags))
+    return
   }
 
-  const [command, ...rest] = positionals
-  return { command, positionals: rest, flags }
+  throw new Error(`unknown command "${command}"`)
 }
 
 function printHelp() {
   console.log(`Banhaten design system
 
 Usage:
-  banhaten init [--cwd <path>] [--force] [--dry-run]
-  banhaten add <component...> [--cwd <path>] [--force] [--dry-run]
-  banhaten diff [component...] [--cwd <path>] [--force]
-  banhaten update [component...] [--cwd <path>] [--force] [--dry-run]
-  banhaten list
+  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.
 `)
 }
 
-function listComponents() {
-  const names = Object.keys(registry.components)
-
-  console.log("Available Banhaten design system components:")
-  for (const name of names) {
-    const component = registry.components[name]
-    console.log(`- ${name}: ${component.description}`)
-  }
-}
-
 async function initProject(flags) {
-  const cwd = path.resolve(String(flags.cwd || process.cwd()))
+  const cwd = path.resolve(flags.cwd || process.cwd())
   const dryRun = Boolean(flags["dry-run"])
   const force = Boolean(flags.force)
-  await warmPathHints(cwd)
   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 writeBaseFiles(cwd, config, { dryRun, force })),
-    ...(await writeGlobalCss(cwd, config, { dryRun, force })),
-    ...(await writeAliasConfig(cwd, config, { dryRun, force }))
+    ...(await writeProjectSchemaFiles(cwd, { dryRun, force })),
+    ...(await writeBaseFiles(installPlan, managedOptions)),
+    ...(await writeGlobalCss(installPlan, managedOptions)),
+    ...(await writeAliasConfig(installPlan, { dryRun, force }))
   )
 
-  const dependencyWrites = await updatePackageJson(
+  const packageResult = await updatePackageJson(
     cwd,
-    await getPackageChanges(cwd, registry.base.dependencies || {}),
+    getPackageChanges(installPlan, registry.base.dependencies || {}),
     { dryRun }
   )
-  writes.push(...dependencyWrites)
-
-  printResult("Initialized Banhaten design system", writes, dryRun)
-  printInstallHint(writes, 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) {
@@ -193,7 +287,7 @@ async function addComponents(names, flags) {
 }
 
 async function diffComponents(names, flags) {
-  await writeComponents(names, { ...flags, "dry-run": true }, {
+  await writeComponents(names, { ...flags, "dry-run": true, "show-diff": true }, {
     inferInstalled: true,
     title: names.length
       ? `Checked ${names.join(", ")} for updates`
@@ -211,16 +305,20 @@ async function updateComponents(names, flags) {
 }
 
 async function writeComponents(requestedNames, flags, options) {
-  const cwd = path.resolve(String(flags.cwd || process.cwd()))
+  const cwd = path.resolve(flags.cwd || process.cwd())
   const dryRun = Boolean(flags["dry-run"])
   const force = Boolean(flags.force)
-  await warmPathHints(cwd)
+  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(cwd, config)
+        ? await findInstalledComponents(installPlan)
         : requestedNames
 
   if (selectedNames.length === 0) {
@@ -232,12 +330,13 @@ async function writeComponents(requestedNames, flags, options) {
   const names = resolveRegistryDependencies(selectedNames)
 
   const writes = []
-  const deps = { ...(registry.base.dependencies || {}) }
+  const deps = {}
+  const components = []
 
-  writes.push(
-    ...(await writeConfig(cwd, config, { dryRun, force })),
-    ...(await writeBaseFiles(cwd, config, { dryRun, force })),
-    ...(await writeAliasConfig(cwd, config, { dryRun, force }))
+  mergeDependencyRequirements(
+    deps,
+    registry.base.dependencies || {},
+    "registry base"
   )
 
   for (const name of names) {
@@ -246,41 +345,200 @@ async function writeComponents(requestedNames, flags, options) {
       throw new Error(`unknown component "${name}". Run \`banhaten list\`.`)
     }
 
-    Object.assign(deps, component.dependencies || {})
+    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(cwd, config, component.files || [], {
-        dryRun,
-        force,
+      ...(await writeRegistryFiles(installPlan, component.files || [], {
+        ...managedOptions,
+        owner: name,
       }))
     )
   }
 
-  writes.push(...(await updatePackageJson(
+  const packageResult = await updatePackageJson(
     cwd,
-    await getPackageChanges(cwd, deps),
+    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
 
-  printResult(options.title, writes, dryRun)
-  printInstallHint(writes, dryRun)
+  deferUntilApplied(() => {
+    printResult(options.title, writes, dryRun, runtimeOptions, install)
+    printInstallHint(install, dryRun, runtimeOptions)
+  })
 }
 
-async function findInstalledComponents(cwd, config) {
+async function readInstallReceipt(cwd) {
+  const receipt = await readJsonIfExists(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)) {
-    for (const file of component.files || []) {
-      const targetPath = path.join(cwd, resolveTarget(cwd, config, file.target))
-      if (await exists(targetPath)) {
-        installed.push(name)
-        break
-      }
+    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 readJsonIfExists(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()
@@ -336,8 +594,14 @@ async function loadConfig(cwd) {
 
   const localConfig = await readJsonIfExists(configPath)
   if (localConfig) {
-    config.style = localConfig.style || config.style
-    config.tsx = localConfig.tsx ?? config.tsx
+    // 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 || {}) }
@@ -347,6 +611,8 @@ async function loadConfig(cwd) {
     config.tailwind.css = await detectCssPath(cwd, config.tailwind.css)
   }
 
+  assertSchema(config, configSchema, CONFIG_FILE)
+
   return config
 }
 
@@ -371,6 +637,38 @@ async function detectCssPath(cwd, 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)}`]
   }
 
@@ -382,30 +680,72 @@ async function writeConfig(cwd, config, options) {
   return [`${status} ${relative(cwd, configPath)}`]
 }
 
-async function writeBaseFiles(cwd, config, options) {
-  return writeRegistryFiles(cwd, config, registry.base.files || [], options)
+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(cwd, config, files, options) {
+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, resolveTarget(cwd, config, file.target))
+    const targetPath = path.join(
+      cwd,
+      resolveInstallTarget(installPlan, file.target)
+    )
     const source = await fs.readFile(sourcePath)
     const content = isTextRegistryFile(file.source)
-      ? applyTemplate(source.toString("utf8"), config)
+      ? applyTemplate(
+          source.toString("utf8"),
+          installPlan,
+          relative(cwd, targetPath)
+        )
       : source
+    const target = relative(cwd, targetPath)
+
+    await assertManagedFileSafe(targetPath, content, target, options)
 
     const status = await writeFile(targetPath, content, options)
-    writes.push(`${status} ${relative(cwd, targetPath)}`)
+    writes.push(`${status} ${target}`)
+    if (options.showDiff && status === "would update") {
+      const current = await fs.readFile(
+        targetPath,
+        isTextRegistryFile(file.source) ? "utf8" : undefined
+      )
+      writes.push(formatUnifiedDiff(target, current, content))
+    }
   }
 
   return writes
 }
 
-async function writeGlobalCss(cwd, config, options) {
-  const cssPath = path.join(cwd, config.tailwind.css)
+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 readTextIfExists(cssPath)
@@ -413,1313 +753,244 @@ async function writeGlobalCss(cwd, config, options) {
     ? removeExistingTokenBlock(current, relative(cwd, cssPath))
     : { content: "", found: false }
 
-  if (tokenBlock.found && !options.force) {
-    return [`kept ${relative(cwd, cssPath)}`]
-  }
-
   const nextCss = current
     ? `${tokenBlock.content.trimEnd()}\n\n${tokenCss}\n`
     : `${tokenCss}\n`
   const next = ensureGlobalCssImports(nextCss)
 
-  const status = await writeFile(cssPath, next, { ...options, force: true })
-  return [`${status} ${relative(cwd, cssPath)}`]
-}
-
-async function writeAliasConfig(cwd, config, options) {
-  if (!usesRootAlias(config, "@")) return []
+  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 writes = []
-  writes.push(...(await writeTypescriptAliasConfig(cwd, "@", options)))
-  writes.push(...(await writeViteAliasConfig(cwd, "@", options)))
+  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
 }
 
-function usesRootAlias(config, aliasRoot) {
-  return Object.values(config.aliases || {}).some((alias) =>
-    alias === aliasRoot || alias?.startsWith(`${aliasRoot}/`)
-  )
-}
-
-async function writeTypescriptAliasConfig(cwd, aliasRoot, options) {
-  const tsconfigPath = await findTypescriptConfigPath(cwd)
-  if (!tsconfigPath) return []
-
-  const config = await readJsonc(tsconfigPath)
-  const compilerOptions = config.compilerOptions || {}
-  const paths = compilerOptions.paths || {}
-  const sourceRoot = shouldUseSrcDirectory(cwd) ? "./src" : "."
-  const aliasPattern = `${aliasRoot}/*`
-  const targetPattern = `${sourceRoot}/*`
-
-  if (Array.isArray(paths[aliasPattern]) && paths[aliasPattern].includes(targetPattern)) {
-    return [`kept ${relative(cwd, tsconfigPath)}`]
-  }
+async function writeAliasConfig(installPlan, options) {
+  const writes = []
 
-  config.compilerOptions = {
-    ...compilerOptions,
-    paths: {
-      ...paths,
-      [aliasPattern]: [targetPattern],
-    },
+  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)}`
+    )
   }
 
-  const status = await writeFile(tsconfigPath, `${JSON.stringify(config, null, 2)}\n`, {
-    dryRun: options.dryRun,
-    force: true,
-  })
-  return [`${status} ${relative(cwd, tsconfigPath)}`]
+  return writes
 }
 
-async function findTypescriptConfigPath(cwd) {
-  const candidates = [
-    "tsconfig.app.json",
-    "tsconfig.json",
-    "jsconfig.json",
-  ]
-
-  for (const candidate of candidates) {
-    const target = path.join(cwd, candidate)
-    if (await exists(target)) return target
+function getPackageChanges(installPlan, dependencies) {
+  const devDependencies = { ...SETUP_DEV_DEPENDENCIES }
+  if (installPlan.vite) {
+    Object.assign(devDependencies, VITE_DEV_DEPENDENCIES)
   }
 
-  return null
+  return {
+    dependencies,
+    devDependencies,
+  }
 }
 
-async function writeViteAliasConfig(cwd, aliasRoot, options) {
-  const viteConfigPath = await findViteConfigPath(cwd)
-  if (!viteConfigPath) return []
-
-  const current = await fs.readFile(viteConfigPath, "utf8")
-  const sourceRoot = shouldUseSrcDirectory(cwd) ? "./src" : "."
-  let next
-
-  try {
-    next = updateViteConfigSource(current, { aliasRoot, sourceRoot })
-  } catch (error) {
-    throw new Error(`${relative(cwd, viteConfigPath)}: ${error.message}`)
+async function updatePackageJson(cwd, changes, options) {
+  const packagePath = path.join(cwd, "package.json")
+  const currentSource = await readTextIfExists(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 (next === current) {
-    return [`kept ${relative(cwd, viteConfigPath)}`]
+  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)}`],
+    }
   }
 
-  const status = await writeFile(viteConfigPath, next, {
+  applyPackageDependencyPlan(packageJson, packagePlan.operations)
+
+  const status = await writeFile(packagePath, `${JSON.stringify(packageJson, null, 2)}\n`, {
     dryRun: options.dryRun,
+    expectedCurrent: currentSource,
     force: true,
   })
-  return [`${status} ${relative(cwd, viteConfigPath)}`]
-}
-
-async function findViteConfigPath(cwd) {
-  const candidates = [
-    "vite.config.ts",
-    "vite.config.mts",
-    "vite.config.js",
-    "vite.config.mjs",
-  ]
 
-  for (const candidate of candidates) {
-    const target = path.join(cwd, candidate)
-    if (await exists(target)) return target
+  return {
+    installRequired: packagePlan.operations.length > 0,
+    writes: [`${status} ${relative(cwd, packagePath)}`],
   }
-
-  return null
 }
 
-function ensureNodeUrlImport(source) {
-  const imports = parseImportDeclarations(source)
-  const nodeUrlImports = imports.filter((entry) => entry.moduleSpecifier === "node:url")
-  const importedLocals = new Set(nodeUrlImports.flatMap((entry) => entry.namedLocals))
-  const missing = ["fileURLToPath", "URL"].filter((name) => !importedLocals.has(name))
-
-  if (missing.length === 0) return source
-
-  return prependImportLines(
-    source,
-    [`import { ${missing.join(", ")} } from "node:url"`]
+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 ensureTailwindViteImport(source, localName) {
-  const imports = parseImportDeclarations(source)
-  const tailwindImport = imports.find(
-    (entry) => entry.moduleSpecifier === "@tailwindcss/vite"
-  )
-
-  if (!tailwindImport) {
-    return prependImportLines(
-      source,
-      [`import ${localName} from "@tailwindcss/vite"`]
-    )
+function resolveTemplateImport(installPlan, target, destinationName) {
+  const configuredAlias = installPlan.config.aliases[destinationName]
+  if (
+    configuredAlias === "@" ||
+    configuredAlias === "~" ||
+    configuredAlias.startsWith("@/") ||
+    configuredAlias.startsWith("~/")
+  ) {
+    return configuredAlias.replace(/\/$/, "")
   }
 
-  if (!tailwindImport.defaultLocal) {
-    throw new Error(
-      "unsupported Vite config: @tailwindcss/vite must be imported with a default binding."
-    )
-  }
+  const targetDirectory = path.posix.dirname(
+    normalizeReceiptTarget(target)
+  )
+  const destination = installPlan.destinations[destinationName]
+  const relativeImport = path.posix.relative(targetDirectory, destination)
 
-  return source
+  if (!relativeImport) return "."
+  return relativeImport.startsWith(".")
+    ? relativeImport
+    : `./${relativeImport}`
 }
 
-function updateViteConfigSource(source, { aliasRoot, sourceRoot }) {
-  const tailwindLocalName = getTailwindViteLocalName(source)
-  let next = addViteResolveAlias(source, aliasRoot, sourceRoot)
-  next = addVitePluginCall(next, `${tailwindLocalName}()`, tailwindLocalName)
-  next = ensureTailwindViteImport(next, tailwindLocalName)
-  next = ensureNodeUrlImport(next)
-  return next
+function isTextRegistryFile(source) {
+  return !/\.(avif|eot|gif|ico|jpe?g|otf|png|ttf|webp|woff2?)$/i.test(source)
 }
 
-function getTailwindViteLocalName(source) {
-  const tailwindImport = parseImportDeclarations(source).find(
-    (entry) => entry.moduleSpecifier === "@tailwindcss/vite"
-  )
-
-  if (!tailwindImport) return "tailwindcss"
-  if (tailwindImport.defaultLocal) return tailwindImport.defaultLocal
-
-  throw new Error(
-    "unsupported Vite config: @tailwindcss/vite must be imported with a default binding."
-  )
+async function readJson(filePath) {
+  return JSON.parse(await fs.readFile(filePath, "utf8"))
 }
 
-function addViteResolveAlias(source, aliasRoot, sourceRoot) {
-  const configObject = findViteConfigObject(source)
-  const resolveProperty = findObjectProperty(source, configObject, "resolve")
-  const aliasEntry = `${JSON.stringify(aliasRoot)}: fileURLToPath(new URL(${JSON.stringify(
-    sourceRoot
-  )}, import.meta.url))`
-
-  if (!resolveProperty) {
-    return insertObjectProperty(
-      source,
-      configObject,
-      [
-        "resolve: {",
-        "  alias: {",
-        `    ${aliasEntry},`,
-        "  },",
-        "},",
-      ].join("\n")
-    )
-  }
-
-  const resolveObject = expectObjectLiteralValue(
-    source,
-    resolveProperty,
-    "unsupported Vite config: resolve must be an object literal."
-  )
-  const aliasProperty = findObjectProperty(source, resolveObject, "alias")
-
-  if (!aliasProperty) {
-    return insertObjectProperty(
-      source,
-      resolveObject,
-      [
-        "alias: {",
-        `  ${aliasEntry},`,
-        "},",
-      ].join("\n")
-    )
+async function readJsonIfExists(filePath) {
+  try {
+    return await readJson(filePath)
+  } catch (error) {
+    if (error.code === "ENOENT") return null
+    throw error
   }
+}
 
-  const aliasObject = expectObjectLiteralValue(
-    source,
-    aliasProperty,
-    "unsupported Vite config: resolve.alias must be an object literal."
-  )
-
-  if (findObjectProperty(source, aliasObject, aliasRoot)) {
-    return source
+async function readTextIfExists(filePath) {
+  try {
+    return await fs.readFile(filePath, "utf8")
+  } catch (error) {
+    if (error.code === "ENOENT") return null
+    throw error
   }
-
-  return insertObjectProperty(source, aliasObject, `${aliasEntry},`)
 }
 
-function addVitePluginCall(source, pluginCall, pluginLocalName) {
-  const configObject = findViteConfigObject(source)
-  const pluginsProperty = findObjectProperty(source, configObject, "plugins")
-
-  if (!pluginsProperty) {
-    return insertObjectProperty(source, configObject, `plugins: [${pluginCall}],`)
-  }
+async function assertManagedFileSafe(targetPath, nextContent, target, options) {
+  if (options.dryRun || options.force || !(await exists(targetPath))) return
 
-  const pluginsArray = expectArrayLiteralValue(
-    source,
-    pluginsProperty,
-    "unsupported Vite config: plugins must be an array literal."
-  )
+  const current = await fs.readFile(targetPath)
+  const next = Buffer.isBuffer(nextContent)
+    ? nextContent
+    : Buffer.from(nextContent, "utf8")
+  if (current.equals(next)) return
 
-  if (arrayHasCallExpression(source, pluginsArray, pluginLocalName)) {
-    return source
-  }
+  const expectedHash = findManagedFileHash(options.receipt, target)
+  const currentHash = hashContent(current)
+  if (expectedHash && currentHash === expectedHash) return
 
-  return appendArrayElement(source, pluginsArray, pluginCall)
+  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 findViteConfigObject(source) {
-  const expressionStart = findExportDefaultExpressionStart(source)
+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
 
-  if (expressionStart === -1) {
-    throw new Error(
-      "unsupported Vite config: expected `export default defineConfig({ ... })` or `export default { ... }`."
+  for (const component of Object.values(receipt?.components || {})) {
+    const match = component.files?.find(
+      (file) => normalizeReceiptTarget(file.target) === normalizedTarget
     )
+    if (match?.sha256) return match.sha256
   }
 
-  if (source[expressionStart] === "{") {
-    return createBracketRange(source, expressionStart, "{")
-  }
+  return null
+}
 
-  const callee = readIdentifierAt(source, expressionStart)
-  if (callee?.name !== "defineConfig") {
-    throw new Error(
-      "unsupported Vite config: default export must be `defineConfig({ ... })` or an object literal."
-    )
-  }
+function hashContent(content) {
+  return createHash("sha256").update(content).digest("hex")
+}
 
-  let index = skipWhitespaceAndComments(source, callee.end)
-  if (source[index] !== "(") {
-    throw new Error("unsupported Vite config: malformed defineConfig call.")
-  }
+function hashNormalizedText(content) {
+  return hashContent(String(content).replace(/\r\n/g, "\n").trim())
+}
 
-  index = skipWhitespaceAndComments(source, index + 1)
-  if (source[index] !== "{") {
-    throw new Error(
-      "unsupported Vite config: defineConfig must receive a config object literal."
-    )
+async function exists(filePath) {
+  try {
+    await fs.access(filePath)
+    return true
+  } catch {
+    return false
   }
-
-  return createBracketRange(source, index, "{")
-}
-
-function findExportDefaultExpressionStart(source) {
-  let index = 0
-
-  while (index < source.length) {
-    const next = skipIgnoredSyntax(source, index)
-    if (next !== index) {
-      index = next
-      continue
-    }
-
-    if (!matchIdentifier(source, index, "export")) {
-      index += 1
-      continue
-    }
-
-    const defaultStart = skipWhitespaceAndComments(source, index + "export".length)
-    if (!matchIdentifier(source, defaultStart, "default")) {
-      index += "export".length
-      continue
-    }
-
-    return skipWhitespaceAndComments(source, defaultStart + "default".length)
-  }
-
-  return -1
-}
-
-function createBracketRange(source, start, open) {
-  const close = open === "{" ? "}" : open === "[" ? "]" : ")"
-  const end = findMatchingBracket(source, start, open, close)
-  return { start, end: end + 1 }
-}
-
-function expectObjectLiteralValue(source, property, message) {
-  const valueStart = skipWhitespaceAndComments(source, property.valueStart)
-  if (source[valueStart] !== "{") throw new Error(message)
-  return createBracketRange(source, valueStart, "{")
-}
-
-function expectArrayLiteralValue(source, property, message) {
-  const valueStart = skipWhitespaceAndComments(source, property.valueStart)
-  if (source[valueStart] !== "[") throw new Error(message)
-  return createBracketRange(source, valueStart, "[")
-}
-
-function findObjectProperty(source, objectRange, propertyName) {
-  const bodyEnd = objectRange.end - 1
-  let index = objectRange.start + 1
-
-  while (index < bodyEnd) {
-    index = skipWhitespaceCommentsAndCommas(source, index, bodyEnd)
-    if (index >= bodyEnd) return null
-
-    const propertyStart = index
-    const name = readPropertyName(source, index)
-    const propertyEnd = findTopLevelCommaOrEnd(source, propertyStart, bodyEnd)
-
-    if (!name) {
-      index = propertyEnd + 1
-      continue
-    }
-
-    index = skipWhitespaceAndComments(source, name.end)
-    if (source[index] !== ":") {
-      if (name.name === propertyName) {
-        throw new Error(
-          `unsupported Vite config: ${propertyName} must be a normal object property.`
-        )
-      }
-      index = propertyEnd + 1
-      continue
-    }
-
-    if (name.name === propertyName) {
-      return {
-        name: name.name,
-        start: propertyStart,
-        end: propertyEnd,
-        valueStart: skipWhitespaceAndComments(source, index + 1),
-        valueEnd: propertyEnd,
-      }
-    }
-
-    index = propertyEnd + 1
-  }
-
-  return null
-}
-
-function readPropertyName(source, index) {
-  if (source[index] === "\"" || source[index] === "'") {
-    const literal = readStringLiteral(source, index)
-    return literal ? { name: literal.value, end: literal.end } : null
-  }
-
-  return readIdentifierAt(source, index)
-}
-
-function insertObjectProperty(source, objectRange, propertyText) {
-  const insertAt = objectRange.start + 1
-  const bodyEnd = objectRange.end - 1
-  const body = source.slice(insertAt, bodyEnd)
-  const hasContent = body.trim().length > 0
-  const propertyIndent = detectObjectChildIndent(source, objectRange)
-  const closeIndent = getLineIndent(source, bodyEnd)
-  const indentedProperty = indentMultiline(propertyText, propertyIndent)
-
-  if (!hasContent) {
-    return `${source.slice(0, insertAt)}\n${indentedProperty}\n${closeIndent}${source.slice(insertAt)}`
-  }
-
-  const needsTrailingNewline = source[insertAt] !== "\n" && source[insertAt] !== "\r"
-  const insertion = `\n${indentedProperty}${needsTrailingNewline ? "\n" : ""}`
-  return `${source.slice(0, insertAt)}${insertion}${source.slice(insertAt)}`
-}
-
-function detectObjectChildIndent(source, objectRange) {
-  const bodyEnd = objectRange.end - 1
-  let index = objectRange.start + 1
-
-  while (index < bodyEnd) {
-    if (source[index] === "\n") {
-      const next = skipHorizontalWhitespace(source, index + 1)
-      if (next < bodyEnd && source[next] !== "\n" && source[next] !== "\r") {
-        return source.slice(index + 1, next)
-      }
-    }
-    index += 1
-  }
-
-  return `${getLineIndent(source, objectRange.start)}  `
-}
-
-function appendArrayElement(source, arrayRange, elementText) {
-  const bodyStart = arrayRange.start + 1
-  const bodyEnd = arrayRange.end - 1
-  const body = source.slice(bodyStart, bodyEnd)
-
-  if (body.trim().length === 0) {
-    return `${source.slice(0, bodyStart)}${elementText}${source.slice(bodyStart)}`
-  }
-
-  const contentEnd = trimEndIndex(source, bodyStart, bodyEnd)
-  const hasNewline = bodyIncludesNewline(source, bodyStart, bodyEnd)
-  const hasTrailingComma = previousCodeChar(source, contentEnd) === ","
-
-  if (!hasNewline) {
-    const separator = hasTrailingComma ? " " : ", "
-    return `${source.slice(0, contentEnd)}${separator}${elementText}${source.slice(contentEnd)}`
-  }
-
-  const closeIndent = getLineIndent(source, bodyEnd)
-  const elementIndent = `${closeIndent}  `
-  const separator = hasTrailingComma ? "\n" : ",\n"
-  return `${source.slice(0, contentEnd)}${separator}${elementIndent}${elementText},${source.slice(contentEnd)}`
-}
-
-function arrayHasCallExpression(source, arrayRange, localName) {
-  const bodyEnd = arrayRange.end - 1
-  let index = arrayRange.start + 1
-
-  while (index < bodyEnd) {
-    index = skipWhitespaceCommentsAndCommas(source, index, bodyEnd)
-    if (index >= bodyEnd) return false
-
-    const elementEnd = findTopLevelCommaOrEnd(source, index, bodyEnd)
-    if (startsWithCallExpression(source, index, elementEnd, localName)) {
-      return true
-    }
-    index = elementEnd + 1
-  }
-
-  return false
-}
-
-function startsWithCallExpression(source, start, end, localName) {
-  const index = skipWhitespaceAndComments(source, start)
-  if (!matchIdentifier(source, index, localName)) return false
-
-  const callStart = skipWhitespaceAndComments(source, index + localName.length)
-  if (source[callStart] !== "(") return false
-
-  const callEnd = createBracketRange(source, callStart, "(").end
-  const next = skipWhitespaceAndComments(source, callEnd)
-  return next <= end
-}
-
-function parseImportDeclarations(source) {
-  const declarations = []
-  let index = 0
-
-  while (index < source.length) {
-    const next = skipIgnoredSyntax(source, index)
-    if (next !== index) {
-      index = next
-      continue
-    }
-
-    if (!matchIdentifier(source, index, "import")) {
-      index += 1
-      continue
-    }
-
-    const clauseStart = skipWhitespaceAndComments(source, index + "import".length)
-    if (source[clauseStart] === ".") {
-      index = clauseStart + 1
-      continue
-    }
-    if (source[clauseStart] === "(") {
-      index = clauseStart + 1
-      continue
-    }
-
-    const end = findImportDeclarationEnd(source, index)
-    const declaration = source.slice(index, end)
-    const moduleSpecifier = getImportModuleSpecifier(declaration)
-
-    if (moduleSpecifier) {
-      declarations.push({
-        start: index,
-        end,
-        moduleSpecifier,
-        defaultLocal: getDefaultImportLocal(declaration),
-        namedLocals: getNamedImportLocals(declaration),
-      })
-    }
-
-    index = end
-  }
-
-  return declarations
-}
-
-function findImportDeclarationEnd(source, start) {
-  const stack = []
-  let sawModuleSpecifier = false
-  let index = start
-
-  while (index < source.length) {
-    const skipped = skipComment(source, index)
-    if (skipped !== index) {
-      index = skipped
-      continue
-    }
-
-    if (source[index] === "\"" || source[index] === "'") {
-      const literal = readStringLiteral(source, index)
-      if (!literal) return source.length
-      sawModuleSpecifier = true
-      index = literal.end
-      continue
-    }
-
-    if (isOpeningBracket(source[index])) {
-      stack.push(expectedClosingBracket(source[index]))
-      index += 1
-      continue
-    }
-
-    if (isClosingBracket(source[index])) {
-      if (stack.at(-1) === source[index]) stack.pop()
-      index += 1
-      continue
-    }
-
-    if (stack.length === 0 && source[index] === ";") return index + 1
-    if (
-      stack.length === 0 &&
-      sawModuleSpecifier &&
-      (source[index] === "\n" || source[index] === "\r")
-    ) {
-      return index + 1
-    }
-
-    index += 1
-  }
-
-  return source.length
-}
-
-function getImportModuleSpecifier(declaration) {
-  let moduleSpecifier = null
-  let index = 0
-
-  while (index < declaration.length) {
-    const skipped = skipComment(declaration, index)
-    if (skipped !== index) {
-      index = skipped
-      continue
-    }
-
-    if (declaration[index] === "\"" || declaration[index] === "'") {
-      const literal = readStringLiteral(declaration, index)
-      if (!literal) break
-      moduleSpecifier = literal.value
-      index = literal.end
-      continue
-    }
-
-    index += 1
-  }
-
-  return moduleSpecifier
-}
-
-function getDefaultImportLocal(declaration) {
-  let index = skipWhitespaceAndComments(declaration, "import".length)
-
-  if (matchIdentifier(declaration, index, "type")) {
-    index = skipWhitespaceAndComments(declaration, index + "type".length)
-  }
-
-  if (declaration[index] === "\"" || declaration[index] === "{" || declaration[index] === "*") {
-    return null
-  }
-
-  const local = readIdentifierAt(declaration, index)
-  return local?.name ?? null
-}
-
-function getNamedImportLocals(declaration) {
-  const open = declaration.indexOf("{")
-  if (open === -1) return []
-
-  const close = findMatchingBracket(declaration, open, "{", "}")
-  const namedImportBody = declaration.slice(open + 1, close)
-  const locals = []
-
-  for (const specifier of splitTopLevelList(namedImportBody)) {
-    const trimmed = specifier.trim()
-    if (!trimmed) continue
-
-    const withoutType = trimmed.startsWith("type ")
-      ? trimmed.slice("type ".length).trim()
-      : trimmed
-    const asIndex = withoutType.toLowerCase().lastIndexOf(" as ")
-    const localName = asIndex === -1
-      ? withoutType
-      : withoutType.slice(asIndex + " as ".length).trim()
-    const local = readIdentifierAt(localName, 0)
-
-    if (local) locals.push(local.name)
-  }
-
-  return locals
-}
-
-function splitTopLevelList(source) {
-  const items = []
-  let start = 0
-  let index = 0
-
-  while (index < source.length) {
-    const skipped = skipIgnoredSyntax(source, index)
-    if (skipped !== index) {
-      index = skipped
-      continue
-    }
-
-    if (source[index] === ",") {
-      items.push(source.slice(start, index))
-      start = index + 1
-    }
-    index += 1
-  }
-
-  items.push(source.slice(start))
-  return items
-}
-
-function prependImportLines(source, lines) {
-  if (lines.length === 0) return source
-
-  let insertAt = 0
-  if (source.startsWith("#!")) {
-    const lineEnd = source.indexOf("\n")
-    insertAt = lineEnd === -1 ? source.length : lineEnd + 1
-  }
-
-  const prefix = `${lines.join("\n")}\n`
-  return `${source.slice(0, insertAt)}${prefix}${source.slice(insertAt)}`
-}
-
-function findTopLevelCommaOrEnd(source, start, end) {
-  const stack = []
-  let index = start
-
-  while (index < end) {
-    const next = skipIgnoredSyntax(source, index)
-    if (next !== index) {
-      index = next
-      continue
-    }
-
-    if (isOpeningBracket(source[index])) {
-      stack.push(expectedClosingBracket(source[index]))
-      index += 1
-      continue
-    }
-
-    if (isClosingBracket(source[index])) {
-      if (stack.at(-1) === source[index]) stack.pop()
-      index += 1
-      continue
-    }
-
-    if (stack.length === 0 && source[index] === ",") return index
-    index += 1
-  }
-
-  return end
-}
-
-function findMatchingBracket(source, start, open, close) {
-  if (source[start] !== open) {
-    throw new Error("unsupported Vite config: malformed JavaScript object.")
-  }
-
-  const stack = []
-  let index = start
-
-  while (index < source.length) {
-    const next = skipIgnoredSyntax(source, index)
-    if (next !== index) {
-      index = next
-      continue
-    }
-
-    if (isOpeningBracket(source[index])) {
-      stack.push(expectedClosingBracket(source[index]))
-      index += 1
-      continue
-    }
-
-    if (isClosingBracket(source[index])) {
-      const expected = stack.pop()
-      if (expected !== source[index]) {
-        throw new Error("unsupported Vite config: malformed JavaScript brackets.")
-      }
-      if (stack.length === 0) return index
-      index += 1
-      continue
-    }
-
-    index += 1
-  }
-
-  throw new Error(`unsupported Vite config: missing closing ${close}.`)
-}
-
-function skipIgnoredSyntax(source, index) {
-  const commentEnd = skipComment(source, index)
-  if (commentEnd !== index) return commentEnd
-
-  if (source[index] === "\"" || source[index] === "'" || source[index] === "`") {
-    return skipQuotedText(source, index)
-  }
-
-  return index
-}
-
-function skipComment(source, index) {
-  if (source[index] !== "/") return index
-
-  if (source[index + 1] === "/") {
-    const lineEnd = source.indexOf("\n", index + 2)
-    return lineEnd === -1 ? source.length : lineEnd + 1
-  }
-
-  if (source[index + 1] === "*") {
-    const blockEnd = source.indexOf("*/", index + 2)
-    return blockEnd === -1 ? source.length : blockEnd + 2
-  }
-
-  return index
-}
-
-function skipQuotedText(source, index) {
-  const quote = source[index]
-  index += 1
-
-  while (index < source.length) {
-    if (source[index] === "\\") {
-      index += 2
-      continue
-    }
-
-    if (source[index] === quote) return index + 1
-    index += 1
-  }
-
-  return source.length
-}
-
-function readStringLiteral(source, index) {
-  const quote = source[index]
-  if (quote !== "\"" && quote !== "'") return null
-
-  let value = ""
-  index += 1
-
-  while (index < source.length) {
-    if (source[index] === "\\") {
-      value += source[index + 1] ?? ""
-      index += 2
-      continue
-    }
-
-    if (source[index] === quote) {
-      return { value, end: index + 1 }
-    }
-
-    value += source[index]
-    index += 1
-  }
-
-  return null
-}
-
-function readIdentifierAt(source, index) {
-  if (!isIdentifierStart(source[index])) return null
-
-  let end = index + 1
-  while (end < source.length && isIdentifierPart(source[end])) {
-    end += 1
-  }
-
-  return { name: source.slice(index, end), end }
-}
-
-function matchIdentifier(source, index, name) {
-  if (source.slice(index, index + name.length) !== name) return false
-
-  const before = source[index - 1]
-  const after = source[index + name.length]
-  return !isIdentifierPart(before) && !isIdentifierPart(after)
-}
-
-function isIdentifierStart(char) {
-  return Boolean(char && /[A-Za-z_$]/.test(char))
-}
-
-function isIdentifierPart(char) {
-  return Boolean(char && /[A-Za-z0-9_$]/.test(char))
-}
-
-function isOpeningBracket(char) {
-  return char === "{" || char === "[" || char === "("
-}
-
-function isClosingBracket(char) {
-  return char === "}" || char === "]" || char === ")"
-}
-
-function expectedClosingBracket(char) {
-  if (char === "{") return "}"
-  if (char === "[") return "]"
-  return ")"
-}
-
-function skipWhitespaceAndComments(source, index) {
-  while (index < source.length) {
-    const next = skipComment(source, index)
-    if (next !== index) {
-      index = next
-      continue
-    }
-
-    if (!isWhitespace(source[index])) return index
-    index += 1
-  }
-
-  return index
-}
-
-function skipWhitespaceCommentsAndCommas(source, index, end) {
-  while (index < end) {
-    const next = skipWhitespaceAndComments(source, index)
-    if (next !== index) {
-      index = next
-      continue
-    }
-
-    if (source[index] !== ",") return index
-    index += 1
-  }
-
-  return index
-}
-
-function skipHorizontalWhitespace(source, index) {
-  while (source[index] === " " || source[index] === "\t") {
-    index += 1
-  }
-  return index
-}
-
-function isWhitespace(char) {
-  return char === " " || char === "\t" || char === "\n" || char === "\r"
-}
-
-function indentMultiline(text, indent) {
-  return text
-    .split("\n")
-    .map((line) => `${indent}${line}`)
-    .join("\n")
-}
-
-function getLineIndent(source, index) {
-  let lineStart = index
-  while (lineStart > 0 && source[lineStart - 1] !== "\n") {
-    lineStart -= 1
-  }
-
-  return source.slice(lineStart, skipHorizontalWhitespace(source, lineStart))
-}
-
-function trimEndIndex(source, start, end) {
-  while (end > start && isWhitespace(source[end - 1])) {
-    end -= 1
-  }
-  return end
-}
-
-function previousCodeChar(source, index) {
-  index -= 1
-  while (index >= 0 && isWhitespace(source[index])) {
-    index -= 1
-  }
-  return source[index]
-}
-
-function bodyIncludesNewline(source, start, end) {
-  for (let index = start; index < end; index += 1) {
-    if (source[index] === "\n" || source[index] === "\r") return true
-  }
-  return false
-}
-
-async function getPackageChanges(cwd, dependencies) {
-  const devDependencies = { ...SETUP_DEV_DEPENDENCIES }
-  if (await findViteConfigPath(cwd)) {
-    Object.assign(devDependencies, VITE_DEV_DEPENDENCIES)
-  }
-
-  return {
-    dependencies,
-    devDependencies,
-  }
-}
-
-async function updatePackageJson(cwd, changes, options) {
-  const packagePath = path.join(cwd, "package.json")
-  const dependencies = changes.dependencies || {}
-  const devDependencies = changes.devDependencies || {}
-  const packageJson = (await readJsonIfExists(packagePath)) || {
-    name: path.basename(cwd).toLowerCase(),
-    version: "0.0.0",
-    private: true,
-  }
-  const added = [
-    ...addPackageSection(packageJson, "dependencies", dependencies),
-    ...addPackageSection(packageJson, "devDependencies", devDependencies),
-  ]
-
-  if (added.length === 0 && (await exists(packagePath))) {
-    return [`kept ${relative(cwd, packagePath)}`]
-  }
-
-  const status = await writeFile(packagePath, `${JSON.stringify(packageJson, null, 2)}\n`, {
-    dryRun: options.dryRun,
-    force: true,
-  })
-
-  return [
-    `${status} ${relative(cwd, packagePath)}`,
-  ]
-}
-
-function addPackageSection(packageJson, section, dependencies) {
-  const added = []
-  const existing = packageJson[section] || {}
-
-  for (const [name, version] of Object.entries(dependencies)) {
-    if (hasPackageDependency(packageJson, name)) continue
-
-    existing[name] = version
-    added.push(name)
-  }
-
-  if (added.length > 0 || packageJson[section]) {
-    packageJson[section] = sortObject(existing)
-  }
-
-  return added
-}
-
-function hasPackageDependency(packageJson, name) {
-  return Boolean(
-    packageJson.dependencies?.[name] ||
-    packageJson.devDependencies?.[name] ||
-    packageJson.peerDependencies?.[name] ||
-    packageJson.optionalDependencies?.[name]
-  )
-}
-
-function applyTemplate(source, config) {
-  return source
-    .replaceAll("@/lib/utils", config.aliases.utils)
-    .replaceAll("@/hooks", config.aliases.hooks)
-}
-
-function isTextRegistryFile(source) {
-  return !/\.(avif|eot|gif|ico|jpe?g|otf|png|ttf|webp|woff2?)$/i.test(source)
-}
-
-function resolveTarget(cwd, config, target) {
-  const replacements = {
-    "{{ui}}": aliasToPath(cwd, config.aliases.ui),
-    "{{utils}}": stripExtension(aliasToPath(cwd, config.aliases.utils)),
-    "{{hooks}}": aliasToPath(cwd, config.aliases.hooks),
-  }
-
-  let resolved = target
-  for (const [placeholder, value] of Object.entries(replacements)) {
-    resolved = resolved.replaceAll(placeholder, value)
-  }
-
-  return resolved
-}
-
-function aliasToPath(cwd, alias) {
-  if (!alias) return ""
-  if (path.isAbsolute(alias)) return alias
-  if (alias.startsWith("./")) return alias.slice(2)
-  if (alias.startsWith("../")) return alias
-
-  if (alias.startsWith("@/") || alias.startsWith("~/")) {
-    const rest = alias.slice(2)
-    return path.join(shouldUseSrcDirectory(cwd) ? "src" : "", rest)
-  }
-
-  return alias
-}
-
-function shouldUseSrcDirectory(cwd) {
-  return pathExistsSyncHint(cwd, "src/app") || pathExistsSyncHint(cwd, "src")
-}
-
-function pathExistsSyncHint(cwd, segment) {
-  return Boolean(syncExistsCache.get(path.join(cwd, segment)))
-}
-
-async function warmPathHints(cwd) {
-  for (const segment of ["src", "src/app"]) {
-    const target = path.join(cwd, segment)
-    syncExistsCache.set(target, await exists(target))
-  }
-}
-
-async function writeFile(targetPath, content, options) {
-  const alreadyExists = await exists(targetPath)
-  const isBinary = Buffer.isBuffer(content)
-
-  if (options.dryRun) {
-    if (!alreadyExists) return "would write"
-
-    const current = await fs.readFile(targetPath)
-    const isEqual = isBinary
-      ? current.equals(content)
-      : current.toString("utf8") === content
-    if (isEqual) return "would keep"
-
-    return "would update"
-  }
-
-  if (alreadyExists && !options.force) {
-    const current = await fs.readFile(targetPath)
-    const isEqual = isBinary
-      ? current.equals(content)
-      : current.toString("utf8") === content
-    if (isEqual) return "kept"
-  }
-
-  await fs.mkdir(path.dirname(targetPath), { recursive: true })
-  await fs.writeFile(targetPath, content, isBinary ? undefined : "utf8")
-  return alreadyExists ? "updated" : "wrote"
-}
-
-async function readJson(filePath) {
-  return JSON.parse(await fs.readFile(filePath, "utf8"))
-}
-
-async function readJsonc(filePath) {
-  const content = await fs.readFile(filePath, "utf8")
-  return JSON.parse(stripJsonComments(content))
-}
-
-function stripJsonComments(content) {
-  let output = ""
-  let inString = false
-  let escaped = false
-
-  for (let index = 0; index < content.length; index += 1) {
-    const char = content[index]
-    const next = content[index + 1]
-
-    if (inString) {
-      output += char
-
-      if (escaped) {
-        escaped = false
-      } else if (char === "\\") {
-        escaped = true
-      } else if (char === "\"") {
-        inString = false
-      }
-
-      continue
-    }
-
-    if (char === "\"") {
-      inString = true
-      output += char
-      continue
-    }
-
-    if (char === "/" && next === "/") {
-      output += "  "
-      index += 2
-
-      while (index < content.length && content[index] !== "\n" && content[index] !== "\r") {
-        output += " "
-        index += 1
-      }
-
-      if (index < content.length) {
-        output += content[index]
-        if (content[index] === "\r" && content[index + 1] === "\n") {
-          index += 1
-          output += content[index]
-        }
-      }
-
-      continue
-    }
-
-    if (char === "/" && next === "*") {
-      output += "  "
-      index += 2
-
-      while (index < content.length) {
-        if (content[index] === "*" && content[index + 1] === "/") {
-          output += "  "
-          index += 1
-          break
-        }
-
-        output += content[index] === "\n" || content[index] === "\r" ? content[index] : " "
-        index += 1
-      }
-
-      continue
-    }
-
-    output += char
-  }
-
-  return output
-}
-
-async function readJsonIfExists(filePath) {
-  try {
-    return await readJson(filePath)
-  } catch (error) {
-    if (error.code === "ENOENT") return null
-    throw error
-  }
-}
-
-async function readTextIfExists(filePath) {
-  try {
-    return await fs.readFile(filePath, "utf8")
-  } catch (error) {
-    if (error.code === "ENOENT") return null
-    throw error
-  }
-}
-
-async function exists(filePath) {
-  try {
-    await fs.access(filePath)
-    return true
-  } catch {
-    return false
-  }
-}
-
-function removeExistingTokenBlock(content, fileLabel = "CSS file") {
-  const lines = splitLinesPreservingEndings(content)
-  const kept = []
-  let found = false
-  let inTokenBlock = false
-
-  for (const line of lines) {
-    const trimmed = line.trimStart()
-
-    if (trimmed.startsWith(CSS_START)) {
-      if (found || inTokenBlock) {
-        throw new Error(`${fileLabel}: multiple Banhaten token blocks found.`)
-      }
-      found = true
-      inTokenBlock = true
-      continue
-    }
-
-    if (trimmed.startsWith(CSS_END)) {
-      if (!inTokenBlock) {
-        throw new Error(`${fileLabel}: Banhaten token end marker has no start marker.`)
-      }
-      inTokenBlock = false
-      continue
-    }
-
-    if (!inTokenBlock) {
-      kept.push(line)
-    }
-  }
-
-  if (inTokenBlock) {
-    throw new Error(`${fileLabel}: Banhaten token block is missing its end marker.`)
-  }
-
-  return { content: kept.join(""), found }
-}
-
-function ensureGlobalCssImports(content) {
-  const cleaned = splitLinesPreservingEndings(content)
-    .filter((line) => {
-      const importSpecifier = readCssImportSpecifier(line)
-      return (
-        importSpecifier !== "tailwindcss" &&
-        !isManagedInterFontImport(importSpecifier)
-      )
-    })
-    .join("")
-    .trimStart()
-  return `${TAILWIND_IMPORT}\n${FONT_IMPORTS.join("\n")}\n${cleaned}`
-}
-
-function splitLinesPreservingEndings(content) {
-  const lines = []
-  let lineStart = 0
-  let index = 0
-
-  while (index < content.length) {
-    if (content[index] === "\r" && content[index + 1] === "\n") {
-      lines.push(content.slice(lineStart, index + 2))
-      index += 2
-      lineStart = index
-      continue
-    }
-
-    if (content[index] === "\n") {
-      lines.push(content.slice(lineStart, index + 1))
-      index += 1
-      lineStart = index
-      continue
-    }
-
-    index += 1
-  }
-
-  if (lineStart < content.length) {
-    lines.push(content.slice(lineStart))
-  }
-
-  return lines
-}
-
-function readCssImportSpecifier(line) {
-  const trimmed = line.trim()
-  const importPrefix = "@import"
-  if (!trimmed.startsWith(importPrefix)) return null
-
-  let index = importPrefix.length
-  while (trimmed[index] === " " || trimmed[index] === "\t") {
-    index += 1
-  }
-
-  const quote = trimmed[index]
-  if (quote !== "\"" && quote !== "'") return null
-
-  const start = index + 1
-  index = start
-  while (index < trimmed.length && trimmed[index] !== quote) {
-    index += 1
-  }
-
-  if (index >= trimmed.length) return null
-  const specifier = trimmed.slice(start, index)
-  index += 1
-
-  while (trimmed[index] === " " || trimmed[index] === "\t") {
-    index += 1
-  }
-
-  if (trimmed[index] === ";") index += 1
-
-  while (trimmed[index] === " " || trimmed[index] === "\t") {
-    index += 1
-  }
-
-  return index === trimmed.length ? specifier : null
-}
-
-function isManagedInterFontImport(specifier) {
-  if (!specifier) return false
-  if (specifier === "@fontsource/inter") return true
-  if (specifier === "@fontsource-variable/inter") return true
-
-  for (const weight of ["400", "500", "600", "700"]) {
-    if (specifier === `@fontsource/inter/${weight}.css`) return true
-  }
-
-  return false
 }
 
 function appendAliasSegment(alias, segment) {
@@ -1727,10 +998,6 @@ function appendAliasSegment(alias, segment) {
   return `${alias.replace(/\/$/, "")}/${segment}`
 }
 
-function stripExtension(filePath) {
-  return filePath.replace(/\.(t|j)sx?$/, "")
-}
-
 function sortObject(value) {
   return Object.fromEntries(
     Object.entries(value).sort(([left], [right]) => left.localeCompare(right))
@@ -1740,22 +1007,3 @@ function sortObject(value) {
 function relative(cwd, targetPath) {
   return path.relative(cwd, targetPath).replaceAll("\\", "/")
 }
-
-function printResult(title, writes, dryRun) {
-  console.log(`${dryRun ? "Dry run: " : ""}${title}`)
-  for (const write of writes) {
-    console.log(`- ${write}`)
-  }
-}
-
-function printInstallHint(writes, dryRun) {
-  if (dryRun) return
-
-  const packageJsonChanged = writes.some((write) =>
-    /^(wrote|updated) package\.json$/.test(write)
-  )
-
-  if (packageJsonChanged) {
-    console.log("\nNext: run npm install to install the added dependencies.")
-  }
-}