@yopem-ui/cli 0.0.2 → 0.1.1

package/src/init.ts

@@ -1,16 +1,27 @@
-import { readFile, realpath, writeFile, mkdir, unlink } from "node:fs/promises"
-import { dirname, join } from "node:path"
-import ts from "typescript-api"
-
-import type { InstallOptions, JsonObject, JsonValue } from "./install"
+import type {
+  FileChange,
+  InstallOptions,
+  JsonObject,
+  JsonValue,
+} from "@yopem-ui/cli/install"
 
 import {
+  applyInstall,
   existingFile,
-  installItem,
   isRecord,
   isString,
-  runBun,
-} from "./install"
+  planInstall,
+  writeFiles,
+} from "@yopem-ui/cli/install"
+import {
+  isPackageName,
+  packageRunner,
+  pendingDependencies,
+  workspaceRoot,
+} from "@yopem-ui/cli/project"
+import { readFile, realpath } from "node:fs/promises"
+import { join, relative, resolve } from "node:path"
+import ts from "typescript-api"
 
 type Framework =
   | "vite"
@@ -20,7 +31,10 @@ type Framework =
   | "next"
   | "astro"
 
-type PackageManager = "bun" | "npm" | "pnpm" | "yarn"
+interface SharedUI {
+  name: string
+  source: string
+}
 
 interface Edit {
   start: number
@@ -28,8 +42,28 @@ interface Edit {
   text: string
 }
 
+export interface InitResult {
+  framework: Framework
+  configured: number
+  warnings?: string[]
+  preview?: {
+    files: {
+      path: string
+      action: "write" | "skip" | "delete" | "conflict"
+      reason?: string
+    }[]
+    dependencies: {
+      cwd: string
+      dependencies: string[]
+      devDependencies: string[]
+    }[]
+    prerequisites: string[]
+  }
+}
+
 export interface InitOptions extends InstallOptions {
   framework?: Framework
+  ui?: string
 }
 
 function object(value: JsonValue | undefined): value is JsonObject {
@@ -266,6 +300,19 @@ function addAlias(
   ) {
     throw new Error(`Incompatible @ alias in ${path}`)
   }
+
+  const aliasValue = declaration?.initializer ?? current.initializer
+
+  if (
+    ts.isStringLiteral(aliasValue) &&
+    /^(?:\.\/)?src\/?$/.test(aliasValue.text)
+  ) {
+    edits.push({
+      start: current.initializer.getStart(source),
+      end: current.initializer.end,
+      text: "yopemSource",
+    })
+  }
 }
 
 function moduleConfig(source: ts.SourceFile, path: string) {
@@ -549,14 +596,18 @@ function babelPlugin(presets = false) {
   return `babel({ plugins: yopemBabelPlugins${presets ? ", presets: yopemBabelPresets" : ""} })`
 }
 
-function stylexSetup(babelPlugins: string[] = [], babelPresets: string[] = []) {
+function stylexSetup(
+  babelPlugins: string[] = [],
+  babelPresets: string[] = [],
+  shared?: SharedUI,
+) {
   return `import babel from "@rolldown/plugin-babel"
 import { createRequire as yopemCreateRequire } from "node:module"
 import { fileURLToPath as yopemFileURLToPath } from "node:url"
 
-const yopemSource = yopemFileURLToPath(new URL("./src", import.meta.url))
+const yopemSource = yopemFileURLToPath(new URL("./src", import.meta.url))${shared ? `\nconst yopemUISource = yopemFileURLToPath(new URL(${JSON.stringify(shared.source)}, import.meta.url))` : ""}
 const yopemBabelPlugins = [${babelPlugins.join(", ")}${babelPlugins.length ? ", " : ""}["@stylexjs/babel-plugin", {
-  aliases: { "@/*": [yopemSource + "/*"] },
+  aliases: { "@/*": [yopemSource + "/*"]${shared ? `, ${JSON.stringify(`${shared.name}/*`)}: [yopemUISource + "/*"]` : ""} },
   dev: process.env.NODE_ENV !== "production",
   runtimeInjection: false,
   treeshakeCompensation: true,
@@ -564,7 +615,7 @@ const yopemBabelPlugins = [${babelPlugins.join(", ")}${babelPlugins.length ? ",
 }]]${babelPresets.length ? `\nconst yopemBabelPresets = [${babelPresets.join(", ")}]` : ""}
 const yopemPostcssPlugin = yopemCreateRequire(import.meta.url)("@stylexjs/postcss-plugin")({
   cwd: yopemFileURLToPath(new URL(".", import.meta.url)),
-  include: ["src/**/*.{js,jsx,ts,tsx}", "app/**/*.{js,jsx,ts,tsx}"],
+  include: ["src/**/*.{js,jsx,ts,tsx}", "app/**/*.{js,jsx,ts,tsx}"${shared ? ', yopemUISource + "/**/*.{js,jsx,ts,tsx}"' : ""}],
   babelConfig: {
     babelrc: false,
     parserOpts: { plugins: ["typescript", "jsx"] },
@@ -697,10 +748,20 @@ function viteConfig(
   path: string,
   babelConfig: ReturnType<typeof migrateBabel>,
   postcssPlugins: string[],
+  shared?: SharedUI,
 ) {
   content = stripLegacyConfig(content, path)
 
   if (content.includes("stylex.vite(") || hasYopemStylexConfig(content)) {
+    if (
+      shared &&
+      (!content.includes(JSON.stringify(`${shared.name}/*`)) ||
+        !content.includes(JSON.stringify(shared.source)))
+    )
+      throw new Error(
+        `Existing StyleX configuration targets a different UI package in ${path}`,
+      )
+
     if (!content.includes('"@":') && !content.includes("'@':")) {
       throw new Error(`Existing StyleX configuration lacks @ alias in ${path}`)
     }
@@ -736,7 +797,7 @@ function viteConfig(
   edits.push({
     start: 0,
     end: 0,
-    text: stylexSetup(babelConfig.plugins, babelConfig.presets),
+    text: stylexSetup(babelConfig.plugins, babelConfig.presets, shared),
   })
 
   return applyEdits(content, edits)
@@ -747,6 +808,7 @@ function astroConfig(
   path: string,
   babelConfig: ReturnType<typeof migrateBabel>,
   postcssPlugins: string[],
+  shared?: SharedUI,
 ) {
   content = stripLegacyConfig(content, path)
   const source = parsed(path, content)
@@ -772,6 +834,15 @@ function astroConfig(
     hasYopemStylexConfig(content) && content.includes(`${reactName}()`)
 
   if (alreadyConfigured) {
+    if (
+      shared &&
+      (!content.includes(JSON.stringify(`${shared.name}/*`)) ||
+        !content.includes(JSON.stringify(shared.source)))
+    )
+      throw new Error(
+        `Existing StyleX configuration targets a different UI package in ${path}`,
+      )
+
     if (!content.includes('"@":') && !content.includes("'@':")) {
       throw new Error(`Existing StyleX configuration lacks @ alias in ${path}`)
     }
@@ -847,7 +918,7 @@ function astroConfig(
   edits.push({
     start: 0,
     end: 0,
-    text: `${reactImport ? "" : 'import react from "@astrojs/react"\n'}${stylexSetup(babelConfig.plugins, babelConfig.presets)}`,
+    text: `${reactImport ? "" : 'import react from "@astrojs/react"\n'}${stylexSetup(babelConfig.plugins, babelConfig.presets, shared)}`,
   })
 
   return applyEdits(content, edits)
@@ -924,10 +995,10 @@ function tsconfig(content: string, path: string) {
   return applyEdits(content, edits)
 }
 
-function reactEntry(content: string, path: string) {
+function reactEntry(content: string, path: string, prefix = "@") {
   if (content.includes("themeMarker") || content.includes("rootStyles.html")) {
     if (
-      !content.includes('"@/styles/styles.css"') ||
+      !content.includes(`"${prefix}/styles/styles.css"`) ||
       !content.includes("rootStyles.html") ||
       !content.includes('dataset.theme = "light"')
     ) {
@@ -947,7 +1018,7 @@ function reactEntry(content: string, path: string) {
     {
       start: 0,
       end: 0,
-      text: 'import "@/styles/styles.css"\nimport * as stylex from "@stylexjs/stylex"\nimport { lightTheme, rootStyles, themeMarker } from "@/styles/tokens.stylex"\n',
+      text: `import "${prefix}/styles/styles.css"\nimport * as stylex from "@stylexjs/stylex"\nimport { lightTheme, rootStyles, themeMarker } from "${prefix}/styles/tokens.stylex"\n`,
     },
     {
       start: last.end,
@@ -961,10 +1032,11 @@ function jsxLayout(
   content: string,
   path: string,
   framework: "next" | "tanstack-start" | "react-router",
+  prefix = "@",
 ) {
   if (content.includes("stylexProps(") || content.includes("rootStyles.html")) {
     if (
-      !content.includes('"@/styles/styles.css"') ||
+      !content.includes(`"${prefix}/styles/styles.css"`) ||
       !content.includes("rootStyles.html") ||
       !content.includes("rootStyles.body")
     ) {
@@ -1064,20 +1136,20 @@ function jsxLayout(
     })
   }
 
-  const css = 'import "@/styles/styles.css"\n'
+  const css = `import "${prefix}/styles/styles.css"\n`
   edits.push({
     start: 0,
     end: 0,
-    text: `${css}import { stylexProps } from "@/lib/stylex"\nimport { lightTheme, rootStyles, themeMarker } from "@/styles/tokens.stylex"\n`,
+    text: `${css}import { stylexProps } from "${prefix}/lib/stylex"\nimport { lightTheme, rootStyles, themeMarker } from "${prefix}/styles/tokens.stylex"\n`,
   })
 
   return applyEdits(content, edits)
 }
 
-function astroLayout(content: string, path: string) {
+function astroLayout(content: string, path: string, prefix = "@") {
   if (content.includes("yopemHtml.className")) {
     if (
-      !content.includes('"@/styles/styles.css"') ||
+      !content.includes(`"${prefix}/styles/styles.css"`) ||
       !content.includes("yopemBody.className")
     ) {
       throw new Error(`Incomplete Yopem layout in ${path}`)
@@ -1117,7 +1189,7 @@ function astroLayout(content: string, path: string) {
     {
       start: end,
       end,
-      text: `${content.includes('"@/styles/styles.css"') ? "" : '\nimport "@/styles/styles.css"'}\nimport * as stylex from "@stylexjs/stylex"\nimport { lightTheme, rootStyles, themeMarker } from "@/styles/tokens.stylex"\n\nconst yopemHtml = stylex.props(themeMarker, lightTheme, rootStyles.html)\nconst yopemBody = stylex.props(rootStyles.body)`,
+      text: `${content.includes(`"${prefix}/styles/styles.css"`) ? "" : `\nimport "${prefix}/styles/styles.css"`}\nimport * as stylex from "@stylexjs/stylex"\nimport { lightTheme, rootStyles, themeMarker } from "${prefix}/styles/tokens.stylex"\n\nconst yopemHtml = stylex.props(themeMarker, lightTheme, rootStyles.html)\nconst yopemBody = stylex.props(rootStyles.body)`,
     },
   ]
 
@@ -1170,7 +1242,7 @@ function astroLayout(content: string, path: string) {
   return applyEdits(content, edits)
 }
 
-function nextBabel(esm: boolean) {
+function nextBabel(esm: boolean, shared?: SharedUI) {
   const header = esm
     ? `import { createRequire } from "node:module"
 import { dirname } from "node:path"
@@ -1208,7 +1280,7 @@ function expandLocalSpreads({ types: t }) {
 }
 
 ${esm ? 'export const presets = ["next/babel"]\nexport const plugins = [' : 'module.exports = {\n  presets: ["next/babel"],\n  plugins: ['}expandLocalSpreads, ["@stylexjs/babel-plugin", {
-  aliases: { "@/*": [path.join(__dirname, "src/*")] },
+  aliases: { "@/*": [path.join(__dirname, "src/*")]${shared ? `, ${JSON.stringify(`${shared.name}/*`)}: [path.join(__dirname, ${JSON.stringify(`${shared.source}*`)})]` : ""} },
   dev: process.env.NODE_ENV !== "production",
   runtimeInjection: false,
   treeshakeCompensation: true,
@@ -1217,7 +1289,40 @@ ${esm ? 'export const presets = ["next/babel"]\nexport const plugins = [' : 'mod
 `
 }
 
-function nextPostcss() {
+function nextConfig(content: string, path: string, name: string) {
+  const source = parsed(path, content)
+  const config = moduleConfig(source, path)
+  const packages = property(config, "transpilePackages")
+  const edits: Edit[] = []
+
+  if (!packages) {
+    addProperty(
+      source,
+      config,
+      `transpilePackages: [${JSON.stringify(name)}]`,
+      edits,
+    )
+  } else {
+    if (!ts.isArrayLiteralExpression(packages.initializer))
+      throw new Error(`Unsupported transpilePackages in ${path}`)
+
+    if (
+      !packages.initializer.elements.some(
+        (entry) => ts.isStringLiteral(entry) && entry.text === name,
+      )
+    )
+      addArrayEntries(
+        source,
+        packages.initializer,
+        [JSON.stringify(name)],
+        edits,
+      )
+  }
+
+  return applyEdits(content, edits)
+}
+
+function nextPostcss(shared?: SharedUI) {
   return `// Next loads this PostCSS config synchronously through CommonJS.
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const babelConfig = require("./babel.config.js")
@@ -1225,7 +1330,7 @@ const babelConfig = require("./babel.config.js")
 module.exports = {
   plugins: {
     "@stylexjs/postcss-plugin": {
-      include: ["src/**/*.{js,jsx,ts,tsx}", "app/**/*.{js,jsx,ts,tsx}", "pages/**/*.{js,jsx,ts,tsx}"],
+      include: ["src/**/*.{js,jsx,ts,tsx}", "app/**/*.{js,jsx,ts,tsx}", "pages/**/*.{js,jsx,ts,tsx}"${shared ? `, require("node:path").join(__dirname, ${JSON.stringify(`${shared.source}**/*.{js,jsx,ts,tsx}`)})` : ""}],
       babelConfig: {
         babelrc: false,
         parserOpts: { plugins: ["typescript", "jsx"] },
@@ -1239,7 +1344,12 @@ module.exports = {
 `
 }
 
-function postcss(content: string, path: string, esm: boolean) {
+function postcss(
+  content: string,
+  path: string,
+  esm: boolean,
+  shared?: SharedUI,
+) {
   if (content.includes('"@stylexjs/postcss-plugin"')) return content
   const source = parsed(path, content)
   let config: ts.ObjectLiteralExpression | undefined
@@ -1269,7 +1379,7 @@ function postcss(content: string, path: string, esm: boolean) {
     source,
     plugins,
     `"@stylexjs/postcss-plugin": {
-      include: ["src/**/*.{js,jsx,ts,tsx}", "app/**/*.{js,jsx,ts,tsx}", "pages/**/*.{js,jsx,ts,tsx}"],
+      include: ["src/**/*.{js,jsx,ts,tsx}", "app/**/*.{js,jsx,ts,tsx}", "pages/**/*.{js,jsx,ts,tsx}"${shared ? `, ${esm ? "yopemRequire" : "require"}("node:path").resolve(${esm ? 'yopemRequire("node:url").fileURLToPath(new URL(".", import.meta.url))' : "__dirname"}, ${JSON.stringify(`${shared.source}**/*.{js,jsx,ts,tsx}`)})` : ""}],
       babelConfig: { babelrc: false, parserOpts: { plugins: ["typescript", "jsx"] }, plugins: yopemBabelConfig.plugins },
       useCSSLayers: true,
     }`,
@@ -1279,7 +1389,7 @@ function postcss(content: string, path: string, esm: boolean) {
     start: 0,
     end: 0,
     text: esm
-      ? 'import { createRequire } from "node:module"\nconst yopemBabelConfig = createRequire(import.meta.url)("./babel.config.js")\n'
+      ? 'import { createRequire } from "node:module"\nconst yopemRequire = createRequire(import.meta.url)\nconst yopemBabelConfig = yopemRequire("./babel.config.js")\n'
       : 'const yopemBabelConfig = require("./babel.config.js")\n',
   })
 
@@ -1295,7 +1405,7 @@ const lintRules = {
   "yopem-ui/valid-polymorphic-as": "error",
 }
 
-function lintConfig(content: string) {
+function lintConfig(content: string, shared?: SharedUI) {
   const config: JsonValue = JSON.parse(content)
 
   if (!object(config)) throw new Error("Invalid .oxlintrc.json")
@@ -1325,6 +1435,45 @@ function lintConfig(content: string) {
     throw new Error("Conflicting yopem-ui plugin in .oxlintrc.json")
   }
 
+  const configuredRules: JsonObject = { ...lintRules, ...rules }
+
+  if (shared) {
+    for (const name of [
+      "yopem-ui/enforce-styling-methods",
+      "yopem-ui/no-restyle",
+      "yopem-ui/valid-polymorphic-as",
+    ]) {
+      const setting = configuredRules[name] ?? "error"
+      const level = Array.isArray(setting) ? (setting[0] ?? "error") : setting
+
+      if (level === "off" || level === 0) continue
+
+      const options = Array.isArray(setting) ? (setting[1] ?? {}) : {}
+
+      if (!object(options)) throw new Error(`Invalid options for ${name}`)
+
+      const sources = options.componentSources ?? [
+        "@/components/ui/",
+        "@registry/components/ui/",
+        "@yopem-ui/ui",
+      ]
+
+      if (!Array.isArray(sources) || !sources.every(isString)) {
+        throw new Error(`Invalid componentSources for ${name}`)
+      }
+
+      configuredRules[name] = [
+        level,
+        {
+          ...options,
+          componentSources: [
+            ...new Set([...sources, `${shared.name}/components/ui/`]),
+          ],
+        },
+      ]
+    }
+  }
+
   const next = {
     ...config,
     jsPlugins: existing
@@ -1333,7 +1482,7 @@ function lintConfig(content: string) {
           ...plugins,
           { name: "yopem-ui", specifier: "@yopem-ui/oxlint-plugin" },
         ],
-    rules: { ...lintRules, ...rules },
+    rules: configuredRules,
     overrides: overrides.some(
       (entry) => JSON.stringify(entry) === JSON.stringify(componentOverride),
     )
@@ -1419,48 +1568,9 @@ function detectFramework(
   return detected[0]!
 }
 
-async function packageManager(
-  root: string,
-  declared: JsonValue | undefined,
-): Promise<PackageManager> {
-  const markers: [PackageManager, string][] = [
-    ["bun", "bun.lock"],
-    ["bun", "bun.lockb"],
-    ["npm", "package-lock.json"],
-    ["pnpm", "pnpm-lock.yaml"],
-    ["yarn", "yarn.lock"],
-  ]
-
-  const found = new Set<PackageManager>()
-
-  for (const [manager, path] of markers) {
-    if (await existingFile(root, path)) found.add(manager)
-  }
-
-  if (found.size > 1) throw new Error("Conflicting package manager lockfiles")
-
-  const named = isString(declared) ? declared.split("@")[0] : undefined
-
-  if (
-    named &&
-    named !== "bun" &&
-    named !== "npm" &&
-    named !== "pnpm" &&
-    named !== "yarn"
-  ) {
-    throw new Error(`Unsupported package manager: ${named}`)
-  }
-
-  const locked = [...found][0]
-
-  if (locked && named && locked !== named) {
-    throw new Error("Package manager and lockfile disagree")
-  }
-
-  return locked ?? named ?? "bun"
-}
-
-export async function initProject(options: InitOptions = {}) {
+export async function initProject(
+  options: InitOptions = {},
+): Promise<InitResult> {
   const root = await realpath(options.cwd ?? process.cwd())
 
   if (!(await existingFile(root, "package.json"))) {
@@ -1484,13 +1594,46 @@ export async function initProject(options: InitOptions = {}) {
   )
 
   const framework = detectFramework(dependencies, options.framework)
-  const manager = await packageManager(root, manifest.packageManager)
+  const uiRoot = options.ui ? await realpath(resolve(root, options.ui)) : root
+  let shared: SharedUI | undefined
+
+  if (options.ui) {
+    if (uiRoot === root)
+      throw new Error("Shared UI package must differ from app")
+
+    const uiManifest: JsonValue = JSON.parse(
+      await readFile(join(uiRoot, "package.json"), "utf8"),
+    )
+
+    if (!object(uiManifest) || !isPackageName(uiManifest.name))
+      throw new Error("Shared UI package requires a valid package name")
+
+    const owner = await workspaceRoot(root)
+
+    if ((await workspaceRoot(uiRoot)) !== owner)
+      throw new Error("App and UI package must belong to the same workspace")
+
+    shared = {
+      name: uiManifest.name,
+      source: `${relative(root, join(uiRoot, "src")).replaceAll("\\", "/")}/`,
+    }
+  }
+
+  const packageRun = await packageRunner(root, options.run)
+  const uiRun = await packageRunner(uiRoot, options.run)
   const edits = new Map<string, { before: string | null; after: string }>()
 
+  const plannedFiles: {
+    path: string
+    action: "write" | "skip" | "delete"
+    reason?: string
+  }[] = []
+
   async function plan(
     path: string,
     transform: (content: string) => string,
     fallback?: string,
+    reason?: string,
   ) {
     const exists = await existingFile(root, path)
 
@@ -1498,6 +1641,12 @@ export async function initProject(options: InitOptions = {}) {
     const before = exists ? await readFile(join(root, path), "utf8") : null
     const after = transform(before ?? fallback!)
 
+    plannedFiles.push({
+      path: resolve(root, path),
+      action: before === after ? "skip" : "write",
+      ...(reason && { reason }),
+    })
+
     if (before !== after) edits.set(path, { before, after })
   }
 
@@ -1550,7 +1699,54 @@ export async function initProject(options: InitOptions = {}) {
       : "tsconfig.json"
 
   await plan(tsPath, (content) => tsconfig(content, tsPath))
-  await plan(".oxlintrc.json", lintConfig, "{}")
+  await plan(".oxlintrc.json", (content) => lintConfig(content, shared), "{}")
+
+  if (shared) {
+    const prefix = relative(root, uiRoot).replaceAll("\\", "/")
+
+    await plan(
+      `${prefix}/package.json`,
+      (content) => {
+        const value: JsonValue = JSON.parse(content)
+
+        if (
+          !object(value) ||
+          (value.exports !== undefined && !object(value.exports))
+        )
+          throw new Error("Shared UI package requires object exports")
+        const exports = object(value.exports) ? { ...value.exports } : {}
+
+        const paths = {
+          "./components/ui/*": "./src/components/ui/*.tsx",
+          "./lib/*": "./src/lib/*.ts",
+          "./styles/tokens.stylex": "./src/styles/tokens.stylex.ts",
+          "./styles/styles.css": "./src/styles/styles.css",
+          "./theme/*": "./src/theme/*.tsx",
+        }
+
+        for (const [path, target] of Object.entries(paths)) {
+          if (exports[path] !== undefined && exports[path] !== target)
+            throw new Error(`Conflicting UI package export: ${path}`)
+          exports[path] = target
+        }
+
+        const sideEffects =
+          value.sideEffects === false
+            ? ["**/*.css"]
+            : Array.isArray(value.sideEffects) &&
+                !value.sideEffects.includes("**/*.css")
+              ? [...value.sideEffects, "**/*.css"]
+              : value.sideEffects
+
+        return JSON.stringify(value.exports) === JSON.stringify(exports) &&
+          JSON.stringify(value.sideEffects) === JSON.stringify(sideEffects)
+          ? content
+          : `${JSON.stringify({ ...value, exports, sideEffects }, null, 2)}\n`
+      },
+      undefined,
+      "Shared UI exports: ./components/ui/*, ./lib/*, ./styles/tokens.stylex, ./styles/styles.css, ./theme/*; CSS side effects",
+    )
+  }
 
   const devDependencies = [
     "oxlint@^1.79.0",
@@ -1561,7 +1757,9 @@ export async function initProject(options: InitOptions = {}) {
     "@stylexjs/postcss-plugin@^0.19.0",
   ]
 
-  const runtimeDependencies: string[] = []
+  const runtimeDependencies: string[] = shared
+    ? [`${shared.name}@workspace:*`, "@stylexjs/stylex@^0.19.0"]
+    : []
 
   if (framework === "astro") {
     const config = await chooseFile(root, [
@@ -1571,7 +1769,7 @@ export async function initProject(options: InitOptions = {}) {
     ])
 
     await plan(config, (content) =>
-      astroConfig(content, config, babelConfig, postcssPlugins),
+      astroConfig(content, config, babelConfig, postcssPlugins, shared),
     )
 
     const layout = await chooseFile(root, [
@@ -1579,12 +1777,27 @@ export async function initProject(options: InitOptions = {}) {
       "src/layouts/layout.astro",
     ])
 
-    await plan(layout, (content) => astroLayout(content, layout))
+    await plan(layout, (content) => astroLayout(content, layout, shared?.name))
 
     for (const name of ["@astrojs/react", "react", "react-dom"]) {
       if (!(name in dependencies)) runtimeDependencies.push(name)
     }
   } else if (framework === "next") {
+    if (shared) {
+      const config = await chooseFile(
+        root,
+        ["next.config.ts", "next.config.mjs", "next.config.js"],
+        "next.config.mjs",
+      )
+
+      const name = shared.name
+      await plan(
+        config,
+        (content) => nextConfig(content, config, name),
+        "export default {}\n",
+      )
+    }
+
     if (!object(manifest.scripts))
       throw new Error("Next.js scripts are missing")
     nextScripts(manifest.scripts)
@@ -1594,7 +1807,9 @@ export async function initProject(options: InitOptions = {}) {
       "app/layout.tsx",
     ])
 
-    await plan(layout, (content) => jsxLayout(content, layout, "next"))
+    await plan(layout, (content) =>
+      jsxLayout(content, layout, "next", shared?.name),
+    )
 
     const babel = await chooseFile(
       root,
@@ -1612,7 +1827,7 @@ export async function initProject(options: InitOptions = {}) {
       throw new Error(`Unsupported Babel configuration: ${babel}`)
     }
 
-    const babelContent = nextBabel(manifest.type === "module")
+    const babelContent = nextBabel(manifest.type === "module", shared)
     await plan(
       babel,
       (content) => {
@@ -1634,15 +1849,16 @@ export async function initProject(options: InitOptions = {}) {
     await plan(
       postcssPath,
       (content) =>
-        postcssPath === "postcss.config.cjs" && content === nextPostcss()
+        postcssPath === "postcss.config.cjs" && content === nextPostcss(shared)
           ? content
           : postcss(
               content,
               postcssPath,
               postcssPath.endsWith(".mjs") ||
                 (postcssPath.endsWith(".js") && manifest.type === "module"),
+              shared,
             ),
-      nextPostcss(),
+      nextPostcss(shared),
     )
     devDependencies.splice(
       0,
@@ -1663,7 +1879,7 @@ export async function initProject(options: InitOptions = {}) {
     ])
 
     await plan(config, (content) =>
-      viteConfig(content, config, babelConfig, postcssPlugins),
+      viteConfig(content, config, babelConfig, postcssPlugins, shared),
     )
 
     if (
@@ -1677,7 +1893,9 @@ export async function initProject(options: InitOptions = {}) {
           : ["app/root.tsx", "src/root.tsx"],
       )
 
-      await plan(layout, (content) => jsxLayout(content, layout, framework))
+      await plan(layout, (content) =>
+        jsxLayout(content, layout, framework, shared?.name),
+      )
     } else {
       const entry = await chooseFile(root, [
         "src/main.tsx",
@@ -1686,110 +1904,282 @@ export async function initProject(options: InitOptions = {}) {
         "src/index.jsx",
       ])
 
-      await plan(entry, (content) => reactEntry(content, entry))
+      await plan(entry, (content) => reactEntry(content, entry, shared?.name))
     }
   }
 
-  const packageRun =
-    options.run ??
-    (manager === "bun"
-      ? runBun
-      : async function runPackage(args: string[], cwd: string) {
-          const command =
-            manager === "npm" && args[0] === "add" ? "install" : args[0]!
-
-          const flags = args
-            .slice(1)
-            .map((argument) => (argument === "-d" ? "-D" : argument))
-
-          const child = Bun.spawn([manager, command, ...flags], {
-            cwd,
-            stdout: "inherit",
-            stderr: "inherit",
-          })
+  const basePlan = await planInstall("base", {
+    ...options,
+    cwd: uiRoot,
+    importPrefix: shared?.name,
+    dryRun: true,
+    run: uiRun,
+  })
 
-          if ((await child.exited) !== 0)
-            throw new Error(`${manager} ${command} failed`)
-        })
+  const conflict = basePlan.preview.files.find(
+    (file) => file.action === "conflict",
+  )
 
-  await installItem("base", { ...options, cwd: root, run: packageRun })
+  if (conflict) throw new Error(conflict.reason)
 
   if (
-    !(await readFile(join(root, "src/styles/styles.css"), "utf8")).includes(
-      "@stylex;",
-    )
+    !basePlan.changes.get("src/styles/styles.css")?.after?.includes("@stylex;")
   ) {
     throw new Error(
       "Add @stylex; to src/styles/styles.css before configuring StyleX",
     )
   }
 
-  const packages = await readFile(join(root, "package.json"), "utf8")
-  const installed: JsonValue = JSON.parse(packages)
+  const runtimeRequirements =
+    uiRoot === root
+      ? [...basePlan.requirements.dependencies, ...runtimeDependencies]
+      : runtimeDependencies
 
-  if (!object(installed))
-    throw new Error("Invalid package.json after installation")
+  const devRequirements =
+    uiRoot === root
+      ? [...basePlan.requirements.devDependencies, ...devDependencies]
+      : devDependencies
 
-  const available = Object.fromEntries(
-    [installed.dependencies, installed.devDependencies].flatMap((entry) =>
-      object(entry) ? Object.entries(entry) : [],
-    ),
+  const appPending = await pendingDependencies(
+    root,
+    runtimeRequirements,
+    devRequirements,
   )
 
-  const neededRuntime = runtimeDependencies.filter(
-    (name) => !(name in available),
+  const baseDependencyNames = new Set(
+    [
+      ...basePlan.requirements.dependencies,
+      ...basePlan.requirements.devDependencies,
+    ].map((argument) => {
+      const separator = argument.indexOf("@", 1)
+
+      return separator < 0 ? argument : argument.slice(0, separator)
+    }),
   )
 
-  if (neededRuntime.length) await packageRun(["add", ...neededRuntime], root)
+  function isBaseDependency(argument: string) {
+    const separator = argument.indexOf("@", 1)
 
-  const neededDev = devDependencies.filter(
-    (name) => !(name.split("@").slice(0, -1).join("@") in available),
-  )
+    return baseDependencyNames.has(
+      separator < 0 ? argument : argument.slice(0, separator),
+    )
+  }
 
-  if (neededDev.length) await packageRun(["add", "-d", ...neededDev], root)
+  const baseApplicationPlan =
+    uiRoot === root
+      ? {
+          ...basePlan,
+          preview: {
+            ...basePlan.preview,
+            dependencies: appPending.dependencies.filter(isBaseDependency),
+            devDependencies:
+              appPending.devDependencies.filter(isBaseDependency),
+          },
+        }
+      : basePlan
 
-  for (const [path, { before }] of edits) {
-    const exists = await existingFile(root, path)
-    const current = exists ? await readFile(join(root, path), "utf8") : null
+  if (options.dryRun) {
+    const baseDependencies = {
+      dependencies: basePlan.preview.dependencies,
+      devDependencies: basePlan.preview.devDependencies,
+    }
 
-    if (current !== before) throw new Error(`File changed during init: ${path}`)
-  }
+    for (const [path] of retired)
+      plannedFiles.push({ path: resolve(root, path), action: "delete" })
+
+    if (framework === "next") {
+      if (!object(manifest.scripts))
+        throw new Error("Next.js scripts are missing")
+      const originalScripts = manifest.scripts
+      const scripts = nextScripts(originalScripts)
+      plannedFiles.push({
+        path: join(root, "package.json"),
+        action:
+          JSON.stringify(scripts) === JSON.stringify(manifest.scripts)
+            ? "skip"
+            : "write",
+        reason: `Next.js scripts: ${
+          Object.entries(scripts)
+            .filter(([name, value]) => value !== originalScripts[name])
+            .map(
+              ([name, value]) =>
+                `${name}: ${JSON.stringify(originalScripts[name])} -> ${JSON.stringify(value)}`,
+            )
+            .join("; ") || "unchanged"
+        }`,
+      })
+    }
 
-  for (const [path, before] of retired) {
-    if ((await readFile(join(root, path), "utf8")) !== before)
-      throw new Error(`File changed during init: ${path}`)
-  }
+    const dependencyTargets =
+      uiRoot === root
+        ? [{ cwd: root, ...appPending }]
+        : [
+            { cwd: uiRoot, ...baseDependencies },
+            { cwd: root, ...appPending },
+          ]
+
+    for (const group of dependencyTargets) {
+      if (!group.dependencies.length && !group.devDependencies.length) continue
+      const path = join(group.cwd, "package.json")
+      const planned = plannedFiles.find((file) => file.path === path)
+
+      if (planned) {
+        planned.action = "write"
+        planned.reason = [
+          planned.reason,
+          "Pending package-manager dependency changes",
+        ]
+          .filter(Boolean)
+          .join("; ")
+      } else {
+        plannedFiles.push({
+          path,
+          action: "write",
+          reason: "Pending package-manager dependency changes",
+        })
+      }
+    }
 
-  for (const [path, { before, after }] of edits) {
-    await mkdir(dirname(join(root, path)), { recursive: true })
-    await writeFile(join(root, path), after, {
-      flag: before === null ? "wx" : "w",
-    })
+    for (const warning of basePlan.warnings) options.onWarning?.(warning)
+
+    return {
+      framework,
+      configured: 0,
+      ...(basePlan.warnings.length && { warnings: basePlan.warnings }),
+      preview: {
+        files: [
+          ...basePlan.preview.files.map((file) => ({
+            ...file,
+            path: join(uiRoot, file.path),
+          })),
+          ...plannedFiles,
+        ],
+        dependencies: dependencyTargets,
+        prerequisites: [
+          "Supported framework, safe project paths and configuration",
+          "Validated registry base with @stylex; stylesheet directive",
+        ],
+      },
+    }
   }
 
-  for (const path of retired.keys()) await unlink(join(root, path))
+  let baseInstalled = false
 
-  if (framework === "next") {
-    const latest: JsonValue = JSON.parse(
-      await readFile(join(root, "package.json"), "utf8"),
-    )
+  try {
+    const baseResult = await applyInstall(baseApplicationPlan, options)
+    baseInstalled = true
+
+    if (
+      !(await readFile(join(uiRoot, "src/styles/styles.css"), "utf8")).includes(
+        "@stylex;",
+      )
+    ) {
+      throw new Error(
+        "Add @stylex; to src/styles/styles.css before configuring StyleX",
+      )
+    }
+
+    if (!(await existingFile(root, "package.json")))
+      throw new Error("Missing package.json after installation")
+    const packages = await readFile(join(root, "package.json"), "utf8")
+    const installed: JsonValue = JSON.parse(packages)
 
-    if (!object(latest))
+    if (!object(installed))
       throw new Error("Invalid package.json after installation")
 
-    if (JSON.stringify(latest.scripts) !== JSON.stringify(manifest.scripts)) {
-      throw new Error("Next.js scripts changed during init")
+    const pending = await pendingDependencies(
+      root,
+      runtimeRequirements,
+      devRequirements,
+    )
+
+    if (uiRoot === root) {
+      pending.dependencies = pending.dependencies.filter(
+        (argument) => !isBaseDependency(argument),
+      )
+      pending.devDependencies = pending.devDependencies.filter(
+        (argument) => !isBaseDependency(argument),
+      )
     }
 
-    const scripts = nextScripts(latest.scripts)
+    if (pending.dependencies.length)
+      await packageRun(["add", ...pending.dependencies], root)
+
+    if (pending.devDependencies.length)
+      await packageRun(["add", "-d", ...pending.devDependencies], root)
+
+    if (shared) {
+      const path = `${relative(root, uiRoot).replaceAll("\\", "/")}/package.json`
+      const planned = edits.get(path)
+
+      if (planned) {
+        if (!(await existingFile(root, path)))
+          throw new Error("Missing UI package.json after installation")
+        const current = await readFile(join(uiRoot, "package.json"), "utf8")
+        const before: JsonValue = JSON.parse(planned.before!)
+        const after: JsonValue = JSON.parse(planned.after)
+        const value: JsonValue = JSON.parse(current)
+
+        if (
+          !object(before) ||
+          !object(after) ||
+          !object(value) ||
+          value.name !== before.name ||
+          JSON.stringify(value.exports) !== JSON.stringify(before.exports) ||
+          JSON.stringify(value.sideEffects) !==
+            JSON.stringify(before.sideEffects)
+        )
+          throw new Error("UI package exports changed during installation")
 
-    if (JSON.stringify(latest.scripts) !== JSON.stringify(scripts)) {
-      await writeFile(
-        join(root, "package.json"),
-        `${JSON.stringify({ ...latest, scripts }, null, 2)}\n`,
-      )
+        edits.set(path, {
+          before: current,
+          after: `${JSON.stringify({ ...value, exports: after.exports, sideEffects: after.sideEffects }, null, 2)}\n`,
+        })
+      }
     }
-  }
 
-  return { framework, configured: edits.size }
+    const changes = new Map<string, FileChange>(edits)
+
+    for (const [path, before] of retired) {
+      changes.set(path, { before, after: null })
+    }
+
+    if (framework === "next") {
+      if (!(await existingFile(root, "package.json")))
+        throw new Error("Missing package.json after installation")
+      const before = await readFile(join(root, "package.json"), "utf8")
+      const latest: JsonValue = JSON.parse(before)
+
+      if (!object(latest))
+        throw new Error("Invalid package.json after installation")
+
+      if (JSON.stringify(latest.scripts) !== JSON.stringify(manifest.scripts)) {
+        throw new Error("Next.js scripts changed during init")
+      }
+
+      const scripts = nextScripts(latest.scripts)
+
+      changes.set("package.json", {
+        before,
+        after:
+          JSON.stringify(latest.scripts) === JSON.stringify(scripts)
+            ? before
+            : `${JSON.stringify({ ...latest, scripts }, null, 2)}\n`,
+      })
+    }
+
+    await writeFiles(root, changes)
+
+    return {
+      framework,
+      configured: edits.size,
+      ...(baseResult.warnings && { warnings: baseResult.warnings }),
+    }
+  } catch (cause) {
+    if (!baseInstalled) throw cause
+    throw new Error(
+      `${cause instanceof Error ? cause.message : String(cause)}\nDependencies may have changed (package.json, lockfiles, node_modules); package-manager changes were not rolled back.\nPrior init base install may have changed source files and ui.json; that install was not rolled back.`,
+      { cause },
+    )
+  }
 }