banhaten 0.4.0 → 0.5.0

package/src/cli/install-plan.js

@@ -1,592 +1,592 @@
-import fs from "node:fs/promises"
-import path from "node:path"
-
-import {
-  parseJsonc,
-  readViteAliasKeys,
-  readViteAliasSourceRoot,
-  updateJsoncAliasSource,
-  updateViteConfigSource,
-} from "./config-editors.js"
-
-const TYPESCRIPT_CONFIG_CANDIDATES = [
-  "tsconfig.app.json",
-  "tsconfig.json",
-  "jsconfig.json",
-]
-const VITE_CONFIG_CANDIDATES = [
-  "vite.config.ts",
-  "vite.config.mts",
-  "vite.config.js",
-  "vite.config.mjs",
-]
-
-export async function createInstallPlan(cwd, config) {
-  const projectRoot = path.resolve(cwd)
-  const [typescriptPath, vitePath, hasSrcDirectory] = await Promise.all([
-    findFirstExisting(projectRoot, TYPESCRIPT_CONFIG_CANDIDATES),
-    findFirstExisting(projectRoot, VITE_CONFIG_CANDIDATES),
-    exists(path.join(projectRoot, "src")),
-  ])
-  const [typescriptSource, viteSource] = await Promise.all([
-    typescriptPath ? fs.readFile(typescriptPath, "utf8") : null,
-    vitePath ? fs.readFile(vitePath, "utf8") : null,
-  ])
-  const typescriptConfig = typescriptSource
-    ? parseTypescriptConfig(typescriptSource, typescriptPath, projectRoot)
-    : null
-  const aliasRootNames = collectAliasRootNames(config.aliases)
-  assertTypescriptConfigIsSelfContained(
-    typescriptConfig,
-    typescriptPath,
-    projectRoot,
-    aliasRootNames
-  )
-  const fallbackRoot = hasSrcDirectory
-    ? path.join(projectRoot, "src")
-    : projectRoot
-  const aliasRoots = {}
-
-  for (const aliasRoot of aliasRootNames) {
-    const typescriptRoot = typescriptConfig
-      ? readTypescriptAliasRoot(
-          typescriptConfig,
-          aliasRoot,
-          typescriptPath,
-          projectRoot
-        )
-      : null
-    let viteRoot = null
-
-    if (viteSource) {
-      try {
-        const configuredAlias = readViteAliasSourceRoot(viteSource, { aliasRoot })
-        if (configuredAlias !== null) {
-          viteRoot = resolveStaticAliasRoot(
-            path.dirname(vitePath),
-            configuredAlias
-          )
-          assertInsideProject(
-            projectRoot,
-            viteRoot,
-            `${relative(projectRoot, vitePath)} alias ${JSON.stringify(aliasRoot)}`
-          )
-        }
-      } catch (error) {
-        throw new Error(`${relative(projectRoot, vitePath)}: ${error.message}`)
-      }
-    }
-
-    if (typescriptRoot && viteRoot && !samePath(typescriptRoot, viteRoot)) {
-      throw new Error(
-        `alias conflict for ${JSON.stringify(aliasRoot)}: ` +
-          `${relative(projectRoot, typescriptPath)} resolves to ${formatProjectPath(projectRoot, typescriptRoot)}, ` +
-          `but ${relative(projectRoot, vitePath)} resolves to ${formatProjectPath(projectRoot, viteRoot)}. ` +
-          "Align the aliases before running Banhaten."
-      )
-    }
-
-    const absoluteRoot = typescriptRoot ?? viteRoot ?? fallbackRoot
-    assertInsideProject(
-      projectRoot,
-      absoluteRoot,
-      `alias ${JSON.stringify(aliasRoot)}`
-    )
-    aliasRoots[aliasRoot] = Object.freeze({
-      absolute: absoluteRoot,
-      relative: projectRelative(projectRoot, absoluteRoot),
-      typescriptDeclared: Boolean(typescriptRoot),
-      viteDeclared: Boolean(viteRoot),
-    })
-  }
-
-  assertNoOverlappingAliases({
-    aliases: config.aliases,
-    projectRoot,
-    typescriptConfig,
-    typescriptPath,
-    viteSource,
-    vitePath,
-  })
-
-  const typescript = typescriptSource
-    ? planTypescriptConfig({
-        aliasRoots,
-        currentSource: typescriptSource,
-        parsedConfig: typescriptConfig,
-        projectRoot,
-        targetPath: typescriptPath,
-      })
-    : null
-  const vite = viteSource
-    ? planViteConfig({
-        aliasRoots,
-        currentSource: viteSource,
-        projectRoot,
-        targetPath: vitePath,
-      })
-    : null
-  const destinations = Object.freeze({
-    css: resolveProjectDestination(
-      projectRoot,
-      config.tailwind.css,
-      "tailwind.css"
-    ),
-    hooks: resolveConfiguredAlias(
-      projectRoot,
-      config.aliases.hooks,
-      aliasRoots,
-      "aliases.hooks"
-    ),
-    ui: resolveConfiguredAlias(
-      projectRoot,
-      config.aliases.ui,
-      aliasRoots,
-      "aliases.ui"
-    ),
-    utils: stripExtension(
-      resolveConfiguredAlias(
-        projectRoot,
-        config.aliases.utils,
-        aliasRoots,
-        "aliases.utils"
-      )
-    ),
-  })
-
-  return Object.freeze({
-    aliasRoots: Object.freeze(aliasRoots),
-    config,
-    cwd: projectRoot,
-    destinations,
-    typescript,
-    vite,
-  })
-}
-
-export function resolveInstallTarget(plan, target) {
-  const replacements = {
-    "{{hooks}}": plan.destinations.hooks,
-    "{{ui}}": plan.destinations.ui,
-    "{{utils}}": plan.destinations.utils,
-  }
-  let resolved = target
-
-  for (const [placeholder, destination] of Object.entries(replacements)) {
-    resolved = resolved.replaceAll(placeholder, destination)
-  }
-
-  if (/\{\{[^}]+\}\}/.test(resolved)) {
-    throw new Error(`registry target contains an unknown placeholder: ${target}`)
-  }
-
-  return resolveProjectDestination(plan.cwd, resolved, `registry target ${target}`)
-}
-
-function planTypescriptConfig({
-  aliasRoots,
-  currentSource,
-  parsedConfig,
-  projectRoot,
-  targetPath,
-}) {
-  let nextSource = currentSource
-  const baseDirectory = getTypescriptBaseDirectory(
-    parsedConfig,
-    targetPath,
-    projectRoot
-  )
-
-  for (const [aliasRoot, rootPlan] of Object.entries(aliasRoots)) {
-    if (rootPlan.typescriptDeclared) continue
-
-    const targetPattern = `${relativeSpecifier(
-      baseDirectory,
-      rootPlan.absolute
-    )}/*`
-    nextSource = updateJsoncAliasSource(nextSource, {
-      aliasPattern: `${aliasRoot}/*`,
-      targetPattern,
-    })
-  }
-
-  try {
-    const verifiedConfig = parseJsonc(nextSource)
-    for (const [aliasRoot, rootPlan] of Object.entries(aliasRoots)) {
-      const verifiedRoot = readTypescriptAliasRoot(
-        verifiedConfig,
-        aliasRoot,
-        targetPath,
-        projectRoot
-      )
-      if (!verifiedRoot || !samePath(verifiedRoot, rootPlan.absolute)) {
-        throw new Error(
-          `failed to produce canonical TypeScript alias ${JSON.stringify(aliasRoot)}`
-        )
-      }
-    }
-  } catch (error) {
-    throw new Error(`${relative(projectRoot, targetPath)}: ${error.message}`)
-  }
-
-  return Object.freeze({
-    currentSource,
-    nextSource,
-    targetPath,
-  })
-}
-
-function planViteConfig({ aliasRoots, currentSource, projectRoot, targetPath }) {
-  let nextSource = currentSource
-
-  try {
-    if (Object.keys(aliasRoots).length === 0) {
-      nextSource = updateViteConfigSource(nextSource, {
-        aliasRoot: null,
-        sourceRoot: null,
-      })
-    }
-
-    for (const [aliasRoot, rootPlan] of Object.entries(aliasRoots)) {
-      nextSource = updateViteConfigSource(nextSource, {
-        aliasRoot,
-        sourceRoot: relativeSpecifier(
-          path.dirname(targetPath),
-          rootPlan.absolute
-        ),
-      })
-    }
-
-    for (const [aliasRoot, rootPlan] of Object.entries(aliasRoots)) {
-      const verifiedAlias = readViteAliasSourceRoot(nextSource, { aliasRoot })
-      const verifiedRoot = verifiedAlias
-        ? resolveStaticAliasRoot(path.dirname(targetPath), verifiedAlias)
-        : null
-      if (!verifiedRoot || !samePath(verifiedRoot, rootPlan.absolute)) {
-        throw new Error(
-          `failed to produce canonical Vite alias ${JSON.stringify(aliasRoot)}`
-        )
-      }
-    }
-  } catch (error) {
-    throw new Error(`${relative(projectRoot, targetPath)}: ${error.message}`)
-  }
-
-  return Object.freeze({
-    currentSource,
-    nextSource,
-    targetPath,
-  })
-}
-
-function parseTypescriptConfig(source, targetPath, projectRoot) {
-  try {
-    return parseJsonc(source)
-  } catch (error) {
-    throw new Error(`${relative(projectRoot, targetPath)}: ${error.message}`)
-  }
-}
-
-function readTypescriptAliasRoot(
-  config,
-  aliasRoot,
-  targetPath,
-  projectRoot
-) {
-  const compilerOptions = config.compilerOptions ?? {}
-  if (!isPlainObject(compilerOptions)) {
-    throw new Error(
-      `${relative(projectRoot, targetPath)}: TypeScript compilerOptions must be an object`
-    )
-  }
-
-  const paths = compilerOptions.paths ?? {}
-  if (!isPlainObject(paths)) {
-    throw new Error(
-      `${relative(projectRoot, targetPath)}: TypeScript compilerOptions.paths must be an object`
-    )
-  }
-
-  const aliasPattern = `${aliasRoot}/*`
-  if (!(aliasPattern in paths)) return null
-
-  const targets = paths[aliasPattern]
-  if (!Array.isArray(targets) || targets.length !== 1) {
-    throw new Error(
-      `${relative(projectRoot, targetPath)}: TypeScript path ${aliasPattern} must contain exactly one static target`
-    )
-  }
-
-  const [target] = targets
-  if (
-    typeof target !== "string" ||
-    !target.endsWith("*") ||
-    target.indexOf("*") !== target.length - 1 ||
-    (target.length > 1 && !/[\\/]/.test(target.at(-2)))
-  ) {
-    throw new Error(
-      `${relative(projectRoot, targetPath)}: TypeScript path ${aliasPattern} must contain one terminal *`
-    )
-  }
-
-  const targetPrefix = target.slice(0, -1).replace(/[\\/]$/, "") || "."
-  const absoluteRoot = path.resolve(
-    getTypescriptBaseDirectory(config, targetPath, projectRoot),
-    targetPrefix
-  )
-  assertInsideProject(
-    projectRoot,
-    absoluteRoot,
-    `${relative(projectRoot, targetPath)} path ${aliasPattern}`
-  )
-  return absoluteRoot
-}
-
-function getTypescriptBaseDirectory(config, targetPath, projectRoot) {
-  const baseUrl = config.compilerOptions?.baseUrl
-  if (baseUrl !== undefined && typeof baseUrl !== "string") {
-    throw new Error(
-      `${relative(projectRoot, targetPath)}: TypeScript compilerOptions.baseUrl must be a string`
-    )
-  }
-
-  return path.resolve(path.dirname(targetPath), baseUrl ?? ".")
-}
-
-function collectAliasRootNames(aliases = {}) {
-  const roots = new Set()
-
-  for (const alias of Object.values(aliases)) {
-    if (typeof alias !== "string") continue
-    if (alias === "@" || alias.startsWith("@/")) roots.add("@")
-    if (alias === "~" || alias.startsWith("~/")) roots.add("~")
-  }
-
-  return [...roots].sort()
-}
-
-function assertTypescriptConfigIsSelfContained(
-  config,
-  targetPath,
-  projectRoot,
-  aliasRootNames
-) {
-  if (config?.extends === undefined || aliasRootNames.length === 0) return
-
-  const compilerOptions = config.compilerOptions
-  const hasLocalBaseUrl = isPlainObject(compilerOptions) &&
-    Object.hasOwn(compilerOptions, "baseUrl")
-  const hasLocalPaths = isPlainObject(compilerOptions) &&
-    Object.hasOwn(compilerOptions, "paths")
-
-  if (!hasLocalBaseUrl || !hasLocalPaths) {
-    throw new Error(
-      `${relative(projectRoot, targetPath)} extends another TypeScript config, so its effective aliases cannot be validated safely. ` +
-        "Declare compilerOptions.baseUrl and compilerOptions.paths locally before running Banhaten."
-    )
-  }
-}
-
-function resolveConfiguredAlias(
-  projectRoot,
-  alias,
-  aliasRoots,
-  label
-) {
-  let absoluteTarget
-
-  if (path.isAbsolute(alias)) {
-    absoluteTarget = alias
-  } else if (alias.startsWith("./") || alias.startsWith("../")) {
-    absoluteTarget = path.resolve(projectRoot, alias)
-  } else {
-    const rootPlan = Object.entries(aliasRoots).find(
-      ([aliasRoot]) => alias === aliasRoot || alias.startsWith(`${aliasRoot}/`)
-    )
-
-    if (rootPlan) {
-      const [aliasRoot, plan] = rootPlan
-      const suffix = alias === aliasRoot ? "" : alias.slice(aliasRoot.length + 1)
-      absoluteTarget = path.resolve(plan.absolute, suffix)
-    } else {
-      absoluteTarget = path.resolve(projectRoot, alias)
-    }
-  }
-
-  assertInsideProject(projectRoot, absoluteTarget, label)
-  return projectRelative(projectRoot, absoluteTarget)
-}
-
-function resolveProjectDestination(projectRoot, destination, label) {
-  const absoluteTarget = path.isAbsolute(destination)
-    ? path.normalize(destination)
-    : path.resolve(projectRoot, destination)
-  assertInsideProject(projectRoot, absoluteTarget, label)
-  return projectRelative(projectRoot, absoluteTarget)
-}
-
-function resolveStaticAliasRoot(configDirectory, configuredAlias) {
-  if (configuredAlias.kind === "literal") {
-    if (!path.isAbsolute(configuredAlias.value)) {
-      throw new Error(
-        "unsupported Vite config: a string alias must be absolute; use fileURLToPath(new URL(..., import.meta.url)) for a config-relative path."
-      )
-    }
-    return path.normalize(configuredAlias.value)
-  }
-
-  return path.resolve(configDirectory, configuredAlias.value)
-}
-
-function assertNoOverlappingAliases({
-  aliases,
-  projectRoot,
-  typescriptConfig,
-  typescriptPath,
-  viteSource,
-  vitePath,
-}) {
-  const typescriptPaths = typescriptConfig?.compilerOptions?.paths ?? {}
-  const configuredAliases = Object.values(aliases).filter(
-    (alias) =>
-      typeof alias === "string" &&
-      (alias === "@" ||
-        alias === "~" ||
-        alias.startsWith("@/") ||
-        alias.startsWith("~/"))
-  )
-
-  for (const aliasPattern of Object.keys(typescriptPaths)) {
-    if (
-      configuredAliases.some((alias) =>
-        isOverlappingTypescriptAlias(aliasPattern, alias)
-      )
-    ) {
-      const aliasRoot = aliasPattern[0]
-      throw new Error(
-        `${relative(projectRoot, typescriptPath)}: alias ${JSON.stringify(aliasPattern)} overlaps a configured Banhaten destination. ` +
-          `Use the root ${JSON.stringify(aliasRoot)} alias so TypeScript, Vite, and generated files share one destination plan.`
-      )
-    }
-  }
-
-  if (!viteSource) return
-
-  try {
-    for (const aliasKey of readViteAliasKeys(viteSource)) {
-      if (
-        configuredAliases.some((alias) =>
-          isOverlappingViteAlias(aliasKey, alias)
-        )
-      ) {
-        const aliasRoot = aliasKey[0]
-        throw new Error(
-          `alias ${JSON.stringify(aliasKey)} overlaps a configured Banhaten destination. ` +
-            `Use the root ${JSON.stringify(aliasRoot)} alias so TypeScript, Vite, and generated files share one destination plan.`
-        )
-      }
-    }
-  } catch (error) {
-    throw new Error(`${relative(projectRoot, vitePath)}: ${error.message}`)
-  }
-}
-
-function isOverlappingTypescriptAlias(aliasPattern, configuredAlias) {
-  const aliasRoot = configuredAlias[0]
-  if (aliasPattern === `${aliasRoot}/*` || aliasPattern === aliasRoot) {
-    return false
-  }
-  if (aliasPattern[0] !== aliasRoot) return false
-
-  const wildcardIndex = aliasPattern.indexOf("*")
-  const staticPrefix = (wildcardIndex === -1
-    ? aliasPattern
-    : aliasPattern.slice(0, wildcardIndex)
-  ).replace(/\/$/, "")
-
-  if (staticPrefix === aliasRoot) return true
-  return (
-    configuredAlias === staticPrefix ||
-    configuredAlias.startsWith(`${staticPrefix}/`) ||
-    staticPrefix.startsWith(`${configuredAlias}/`) ||
-    (wildcardIndex !== -1 && configuredAlias.startsWith(staticPrefix))
-  )
-}
-
-function isOverlappingViteAlias(aliasKey, configuredAlias) {
-  const aliasRoot = configuredAlias[0]
-  if (aliasKey === aliasRoot || aliasKey[0] !== aliasRoot) return false
-
-  return (
-    configuredAlias === aliasKey ||
-    configuredAlias.startsWith(`${aliasKey}/`) ||
-    aliasKey.startsWith(`${configuredAlias}/`)
-  )
-}
-
-function assertInsideProject(projectRoot, targetPath, label) {
-  const target = path.resolve(targetPath)
-  const targetRelative = path.relative(projectRoot, target)
-  if (
-    targetRelative === ".." ||
-    targetRelative.startsWith(`..${path.sep}`) ||
-    path.isAbsolute(targetRelative)
-  ) {
-    throw new Error(
-      `${label} resolves outside the project: ${target}`
-    )
-  }
-}
-
-async function findFirstExisting(projectRoot, candidates) {
-  for (const candidate of candidates) {
-    const targetPath = path.join(projectRoot, candidate)
-    if (await exists(targetPath)) return targetPath
-  }
-  return null
-}
-
-function relativeSpecifier(fromDirectory, targetPath) {
-  const targetRelative = path
-    .relative(fromDirectory, targetPath)
-    .replaceAll("\\", "/")
-  if (!targetRelative) return "."
-  return targetRelative.startsWith(".")
-    ? targetRelative
-    : `./${targetRelative}`
-}
-
-function projectRelative(projectRoot, targetPath) {
-  const targetRelative = path.relative(projectRoot, targetPath)
-  return (targetRelative || ".").replaceAll("\\", "/")
-}
-
-function formatProjectPath(projectRoot, targetPath) {
-  const targetRelative = projectRelative(projectRoot, targetPath)
-  return targetRelative === "." ? "." : `./${targetRelative}`
-}
-
-function relative(projectRoot, targetPath) {
-  return path.relative(projectRoot, targetPath).replaceAll("\\", "/")
-}
-
-function stripExtension(filePath) {
-  return filePath.replace(/\.(t|j)sx?$/, "")
-}
-
-function samePath(left, right) {
-  return path.resolve(left) === path.resolve(right)
-}
-
-function isPlainObject(value) {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value)
-}
-
-async function exists(targetPath) {
-  try {
-    await fs.access(targetPath)
-    return true
-  } catch {
-    return false
-  }
-}
+import fs from "node:fs/promises"
+import path from "node:path"
+
+import {
+  parseJsonc,
+  readViteAliasKeys,
+  readViteAliasSourceRoot,
+  updateJsoncAliasSource,
+  updateViteConfigSource,
+} from "./config-editors.js"
+
+const TYPESCRIPT_CONFIG_CANDIDATES = [
+  "tsconfig.app.json",
+  "tsconfig.json",
+  "jsconfig.json",
+]
+const VITE_CONFIG_CANDIDATES = [
+  "vite.config.ts",
+  "vite.config.mts",
+  "vite.config.js",
+  "vite.config.mjs",
+]
+
+export async function createInstallPlan(cwd, config) {
+  const projectRoot = path.resolve(cwd)
+  const [typescriptPath, vitePath, hasSrcDirectory] = await Promise.all([
+    findFirstExisting(projectRoot, TYPESCRIPT_CONFIG_CANDIDATES),
+    findFirstExisting(projectRoot, VITE_CONFIG_CANDIDATES),
+    exists(path.join(projectRoot, "src")),
+  ])
+  const [typescriptSource, viteSource] = await Promise.all([
+    typescriptPath ? fs.readFile(typescriptPath, "utf8") : null,
+    vitePath ? fs.readFile(vitePath, "utf8") : null,
+  ])
+  const typescriptConfig = typescriptSource
+    ? parseTypescriptConfig(typescriptSource, typescriptPath, projectRoot)
+    : null
+  const aliasRootNames = collectAliasRootNames(config.aliases)
+  assertTypescriptConfigIsSelfContained(
+    typescriptConfig,
+    typescriptPath,
+    projectRoot,
+    aliasRootNames
+  )
+  const fallbackRoot = hasSrcDirectory
+    ? path.join(projectRoot, "src")
+    : projectRoot
+  const aliasRoots = {}
+
+  for (const aliasRoot of aliasRootNames) {
+    const typescriptRoot = typescriptConfig
+      ? readTypescriptAliasRoot(
+          typescriptConfig,
+          aliasRoot,
+          typescriptPath,
+          projectRoot
+        )
+      : null
+    let viteRoot = null
+
+    if (viteSource) {
+      try {
+        const configuredAlias = readViteAliasSourceRoot(viteSource, { aliasRoot })
+        if (configuredAlias !== null) {
+          viteRoot = resolveStaticAliasRoot(
+            path.dirname(vitePath),
+            configuredAlias
+          )
+          assertInsideProject(
+            projectRoot,
+            viteRoot,
+            `${relative(projectRoot, vitePath)} alias ${JSON.stringify(aliasRoot)}`
+          )
+        }
+      } catch (error) {
+        throw new Error(`${relative(projectRoot, vitePath)}: ${error.message}`)
+      }
+    }
+
+    if (typescriptRoot && viteRoot && !samePath(typescriptRoot, viteRoot)) {
+      throw new Error(
+        `alias conflict for ${JSON.stringify(aliasRoot)}: ` +
+          `${relative(projectRoot, typescriptPath)} resolves to ${formatProjectPath(projectRoot, typescriptRoot)}, ` +
+          `but ${relative(projectRoot, vitePath)} resolves to ${formatProjectPath(projectRoot, viteRoot)}. ` +
+          "Align the aliases before running Banhaten."
+      )
+    }
+
+    const absoluteRoot = typescriptRoot ?? viteRoot ?? fallbackRoot
+    assertInsideProject(
+      projectRoot,
+      absoluteRoot,
+      `alias ${JSON.stringify(aliasRoot)}`
+    )
+    aliasRoots[aliasRoot] = Object.freeze({
+      absolute: absoluteRoot,
+      relative: projectRelative(projectRoot, absoluteRoot),
+      typescriptDeclared: Boolean(typescriptRoot),
+      viteDeclared: Boolean(viteRoot),
+    })
+  }
+
+  assertNoOverlappingAliases({
+    aliases: config.aliases,
+    projectRoot,
+    typescriptConfig,
+    typescriptPath,
+    viteSource,
+    vitePath,
+  })
+
+  const typescript = typescriptSource
+    ? planTypescriptConfig({
+        aliasRoots,
+        currentSource: typescriptSource,
+        parsedConfig: typescriptConfig,
+        projectRoot,
+        targetPath: typescriptPath,
+      })
+    : null
+  const vite = viteSource
+    ? planViteConfig({
+        aliasRoots,
+        currentSource: viteSource,
+        projectRoot,
+        targetPath: vitePath,
+      })
+    : null
+  const destinations = Object.freeze({
+    css: resolveProjectDestination(
+      projectRoot,
+      config.tailwind.css,
+      "tailwind.css"
+    ),
+    hooks: resolveConfiguredAlias(
+      projectRoot,
+      config.aliases.hooks,
+      aliasRoots,
+      "aliases.hooks"
+    ),
+    ui: resolveConfiguredAlias(
+      projectRoot,
+      config.aliases.ui,
+      aliasRoots,
+      "aliases.ui"
+    ),
+    utils: stripExtension(
+      resolveConfiguredAlias(
+        projectRoot,
+        config.aliases.utils,
+        aliasRoots,
+        "aliases.utils"
+      )
+    ),
+  })
+
+  return Object.freeze({
+    aliasRoots: Object.freeze(aliasRoots),
+    config,
+    cwd: projectRoot,
+    destinations,
+    typescript,
+    vite,
+  })
+}
+
+export function resolveInstallTarget(plan, target) {
+  const replacements = {
+    "{{hooks}}": plan.destinations.hooks,
+    "{{ui}}": plan.destinations.ui,
+    "{{utils}}": plan.destinations.utils,
+  }
+  let resolved = target
+
+  for (const [placeholder, destination] of Object.entries(replacements)) {
+    resolved = resolved.replaceAll(placeholder, destination)
+  }
+
+  if (/\{\{[^}]+\}\}/.test(resolved)) {
+    throw new Error(`registry target contains an unknown placeholder: ${target}`)
+  }
+
+  return resolveProjectDestination(plan.cwd, resolved, `registry target ${target}`)
+}
+
+function planTypescriptConfig({
+  aliasRoots,
+  currentSource,
+  parsedConfig,
+  projectRoot,
+  targetPath,
+}) {
+  let nextSource = currentSource
+  const baseDirectory = getTypescriptBaseDirectory(
+    parsedConfig,
+    targetPath,
+    projectRoot
+  )
+
+  for (const [aliasRoot, rootPlan] of Object.entries(aliasRoots)) {
+    if (rootPlan.typescriptDeclared) continue
+
+    const targetPattern = `${relativeSpecifier(
+      baseDirectory,
+      rootPlan.absolute
+    )}/*`
+    nextSource = updateJsoncAliasSource(nextSource, {
+      aliasPattern: `${aliasRoot}/*`,
+      targetPattern,
+    })
+  }
+
+  try {
+    const verifiedConfig = parseJsonc(nextSource)
+    for (const [aliasRoot, rootPlan] of Object.entries(aliasRoots)) {
+      const verifiedRoot = readTypescriptAliasRoot(
+        verifiedConfig,
+        aliasRoot,
+        targetPath,
+        projectRoot
+      )
+      if (!verifiedRoot || !samePath(verifiedRoot, rootPlan.absolute)) {
+        throw new Error(
+          `failed to produce canonical TypeScript alias ${JSON.stringify(aliasRoot)}`
+        )
+      }
+    }
+  } catch (error) {
+    throw new Error(`${relative(projectRoot, targetPath)}: ${error.message}`)
+  }
+
+  return Object.freeze({
+    currentSource,
+    nextSource,
+    targetPath,
+  })
+}
+
+function planViteConfig({ aliasRoots, currentSource, projectRoot, targetPath }) {
+  let nextSource = currentSource
+
+  try {
+    if (Object.keys(aliasRoots).length === 0) {
+      nextSource = updateViteConfigSource(nextSource, {
+        aliasRoot: null,
+        sourceRoot: null,
+      })
+    }
+
+    for (const [aliasRoot, rootPlan] of Object.entries(aliasRoots)) {
+      nextSource = updateViteConfigSource(nextSource, {
+        aliasRoot,
+        sourceRoot: relativeSpecifier(
+          path.dirname(targetPath),
+          rootPlan.absolute
+        ),
+      })
+    }
+
+    for (const [aliasRoot, rootPlan] of Object.entries(aliasRoots)) {
+      const verifiedAlias = readViteAliasSourceRoot(nextSource, { aliasRoot })
+      const verifiedRoot = verifiedAlias
+        ? resolveStaticAliasRoot(path.dirname(targetPath), verifiedAlias)
+        : null
+      if (!verifiedRoot || !samePath(verifiedRoot, rootPlan.absolute)) {
+        throw new Error(
+          `failed to produce canonical Vite alias ${JSON.stringify(aliasRoot)}`
+        )
+      }
+    }
+  } catch (error) {
+    throw new Error(`${relative(projectRoot, targetPath)}: ${error.message}`)
+  }
+
+  return Object.freeze({
+    currentSource,
+    nextSource,
+    targetPath,
+  })
+}
+
+function parseTypescriptConfig(source, targetPath, projectRoot) {
+  try {
+    return parseJsonc(source)
+  } catch (error) {
+    throw new Error(`${relative(projectRoot, targetPath)}: ${error.message}`)
+  }
+}
+
+function readTypescriptAliasRoot(
+  config,
+  aliasRoot,
+  targetPath,
+  projectRoot
+) {
+  const compilerOptions = config.compilerOptions ?? {}
+  if (!isPlainObject(compilerOptions)) {
+    throw new Error(
+      `${relative(projectRoot, targetPath)}: TypeScript compilerOptions must be an object`
+    )
+  }
+
+  const paths = compilerOptions.paths ?? {}
+  if (!isPlainObject(paths)) {
+    throw new Error(
+      `${relative(projectRoot, targetPath)}: TypeScript compilerOptions.paths must be an object`
+    )
+  }
+
+  const aliasPattern = `${aliasRoot}/*`
+  if (!(aliasPattern in paths)) return null
+
+  const targets = paths[aliasPattern]
+  if (!Array.isArray(targets) || targets.length !== 1) {
+    throw new Error(
+      `${relative(projectRoot, targetPath)}: TypeScript path ${aliasPattern} must contain exactly one static target`
+    )
+  }
+
+  const [target] = targets
+  if (
+    typeof target !== "string" ||
+    !target.endsWith("*") ||
+    target.indexOf("*") !== target.length - 1 ||
+    (target.length > 1 && !/[\\/]/.test(target.at(-2)))
+  ) {
+    throw new Error(
+      `${relative(projectRoot, targetPath)}: TypeScript path ${aliasPattern} must contain one terminal *`
+    )
+  }
+
+  const targetPrefix = target.slice(0, -1).replace(/[\\/]$/, "") || "."
+  const absoluteRoot = path.resolve(
+    getTypescriptBaseDirectory(config, targetPath, projectRoot),
+    targetPrefix
+  )
+  assertInsideProject(
+    projectRoot,
+    absoluteRoot,
+    `${relative(projectRoot, targetPath)} path ${aliasPattern}`
+  )
+  return absoluteRoot
+}
+
+function getTypescriptBaseDirectory(config, targetPath, projectRoot) {
+  const baseUrl = config.compilerOptions?.baseUrl
+  if (baseUrl !== undefined && typeof baseUrl !== "string") {
+    throw new Error(
+      `${relative(projectRoot, targetPath)}: TypeScript compilerOptions.baseUrl must be a string`
+    )
+  }
+
+  return path.resolve(path.dirname(targetPath), baseUrl ?? ".")
+}
+
+function collectAliasRootNames(aliases = {}) {
+  const roots = new Set()
+
+  for (const alias of Object.values(aliases)) {
+    if (typeof alias !== "string") continue
+    if (alias === "@" || alias.startsWith("@/")) roots.add("@")
+    if (alias === "~" || alias.startsWith("~/")) roots.add("~")
+  }
+
+  return [...roots].sort()
+}
+
+function assertTypescriptConfigIsSelfContained(
+  config,
+  targetPath,
+  projectRoot,
+  aliasRootNames
+) {
+  if (config?.extends === undefined || aliasRootNames.length === 0) return
+
+  const compilerOptions = config.compilerOptions
+  const hasLocalBaseUrl = isPlainObject(compilerOptions) &&
+    Object.hasOwn(compilerOptions, "baseUrl")
+  const hasLocalPaths = isPlainObject(compilerOptions) &&
+    Object.hasOwn(compilerOptions, "paths")
+
+  if (!hasLocalBaseUrl || !hasLocalPaths) {
+    throw new Error(
+      `${relative(projectRoot, targetPath)} extends another TypeScript config, so its effective aliases cannot be validated safely. ` +
+        "Declare compilerOptions.baseUrl and compilerOptions.paths locally before running Banhaten."
+    )
+  }
+}
+
+function resolveConfiguredAlias(
+  projectRoot,
+  alias,
+  aliasRoots,
+  label
+) {
+  let absoluteTarget
+
+  if (path.isAbsolute(alias)) {
+    absoluteTarget = alias
+  } else if (alias.startsWith("./") || alias.startsWith("../")) {
+    absoluteTarget = path.resolve(projectRoot, alias)
+  } else {
+    const rootPlan = Object.entries(aliasRoots).find(
+      ([aliasRoot]) => alias === aliasRoot || alias.startsWith(`${aliasRoot}/`)
+    )
+
+    if (rootPlan) {
+      const [aliasRoot, plan] = rootPlan
+      const suffix = alias === aliasRoot ? "" : alias.slice(aliasRoot.length + 1)
+      absoluteTarget = path.resolve(plan.absolute, suffix)
+    } else {
+      absoluteTarget = path.resolve(projectRoot, alias)
+    }
+  }
+
+  assertInsideProject(projectRoot, absoluteTarget, label)
+  return projectRelative(projectRoot, absoluteTarget)
+}
+
+function resolveProjectDestination(projectRoot, destination, label) {
+  const absoluteTarget = path.isAbsolute(destination)
+    ? path.normalize(destination)
+    : path.resolve(projectRoot, destination)
+  assertInsideProject(projectRoot, absoluteTarget, label)
+  return projectRelative(projectRoot, absoluteTarget)
+}
+
+function resolveStaticAliasRoot(configDirectory, configuredAlias) {
+  if (configuredAlias.kind === "literal") {
+    if (!path.isAbsolute(configuredAlias.value)) {
+      throw new Error(
+        "unsupported Vite config: a string alias must be absolute; use fileURLToPath(new URL(..., import.meta.url)) for a config-relative path."
+      )
+    }
+    return path.normalize(configuredAlias.value)
+  }
+
+  return path.resolve(configDirectory, configuredAlias.value)
+}
+
+function assertNoOverlappingAliases({
+  aliases,
+  projectRoot,
+  typescriptConfig,
+  typescriptPath,
+  viteSource,
+  vitePath,
+}) {
+  const typescriptPaths = typescriptConfig?.compilerOptions?.paths ?? {}
+  const configuredAliases = Object.values(aliases).filter(
+    (alias) =>
+      typeof alias === "string" &&
+      (alias === "@" ||
+        alias === "~" ||
+        alias.startsWith("@/") ||
+        alias.startsWith("~/"))
+  )
+
+  for (const aliasPattern of Object.keys(typescriptPaths)) {
+    if (
+      configuredAliases.some((alias) =>
+        isOverlappingTypescriptAlias(aliasPattern, alias)
+      )
+    ) {
+      const aliasRoot = aliasPattern[0]
+      throw new Error(
+        `${relative(projectRoot, typescriptPath)}: alias ${JSON.stringify(aliasPattern)} overlaps a configured Banhaten destination. ` +
+          `Use the root ${JSON.stringify(aliasRoot)} alias so TypeScript, Vite, and generated files share one destination plan.`
+      )
+    }
+  }
+
+  if (!viteSource) return
+
+  try {
+    for (const aliasKey of readViteAliasKeys(viteSource)) {
+      if (
+        configuredAliases.some((alias) =>
+          isOverlappingViteAlias(aliasKey, alias)
+        )
+      ) {
+        const aliasRoot = aliasKey[0]
+        throw new Error(
+          `alias ${JSON.stringify(aliasKey)} overlaps a configured Banhaten destination. ` +
+            `Use the root ${JSON.stringify(aliasRoot)} alias so TypeScript, Vite, and generated files share one destination plan.`
+        )
+      }
+    }
+  } catch (error) {
+    throw new Error(`${relative(projectRoot, vitePath)}: ${error.message}`)
+  }
+}
+
+function isOverlappingTypescriptAlias(aliasPattern, configuredAlias) {
+  const aliasRoot = configuredAlias[0]
+  if (aliasPattern === `${aliasRoot}/*` || aliasPattern === aliasRoot) {
+    return false
+  }
+  if (aliasPattern[0] !== aliasRoot) return false
+
+  const wildcardIndex = aliasPattern.indexOf("*")
+  const staticPrefix = (wildcardIndex === -1
+    ? aliasPattern
+    : aliasPattern.slice(0, wildcardIndex)
+  ).replace(/\/$/, "")
+
+  if (staticPrefix === aliasRoot) return true
+  return (
+    configuredAlias === staticPrefix ||
+    configuredAlias.startsWith(`${staticPrefix}/`) ||
+    staticPrefix.startsWith(`${configuredAlias}/`) ||
+    (wildcardIndex !== -1 && configuredAlias.startsWith(staticPrefix))
+  )
+}
+
+function isOverlappingViteAlias(aliasKey, configuredAlias) {
+  const aliasRoot = configuredAlias[0]
+  if (aliasKey === aliasRoot || aliasKey[0] !== aliasRoot) return false
+
+  return (
+    configuredAlias === aliasKey ||
+    configuredAlias.startsWith(`${aliasKey}/`) ||
+    aliasKey.startsWith(`${configuredAlias}/`)
+  )
+}
+
+function assertInsideProject(projectRoot, targetPath, label) {
+  const target = path.resolve(targetPath)
+  const targetRelative = path.relative(projectRoot, target)
+  if (
+    targetRelative === ".." ||
+    targetRelative.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(targetRelative)
+  ) {
+    throw new Error(
+      `${label} resolves outside the project: ${target}`
+    )
+  }
+}
+
+async function findFirstExisting(projectRoot, candidates) {
+  for (const candidate of candidates) {
+    const targetPath = path.join(projectRoot, candidate)
+    if (await exists(targetPath)) return targetPath
+  }
+  return null
+}
+
+function relativeSpecifier(fromDirectory, targetPath) {
+  const targetRelative = path
+    .relative(fromDirectory, targetPath)
+    .replaceAll("\\", "/")
+  if (!targetRelative) return "."
+  return targetRelative.startsWith(".")
+    ? targetRelative
+    : `./${targetRelative}`
+}
+
+function projectRelative(projectRoot, targetPath) {
+  const targetRelative = path.relative(projectRoot, targetPath)
+  return (targetRelative || ".").replaceAll("\\", "/")
+}
+
+function formatProjectPath(projectRoot, targetPath) {
+  const targetRelative = projectRelative(projectRoot, targetPath)
+  return targetRelative === "." ? "." : `./${targetRelative}`
+}
+
+function relative(projectRoot, targetPath) {
+  return path.relative(projectRoot, targetPath).replaceAll("\\", "/")
+}
+
+function stripExtension(filePath) {
+  return filePath.replace(/\.(t|j)sx?$/, "")
+}
+
+function samePath(left, right) {
+  return path.resolve(left) === path.resolve(right)
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value)
+}
+
+async function exists(targetPath) {
+  try {
+    await fs.access(targetPath)
+    return true
+  } catch {
+    return false
+  }
+}