@yopem-ui/cli 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yopem-ui/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "CLI for installing Yopem UI source components and StyleX setup",
   "keywords": [
     "cli",

package/src/cli.ts

@@ -8,7 +8,7 @@ import { installItem, isRecord, isString } from "@yopem-ui/cli/install"
 import { resolve } from "node:path"
 
 const usage =
-  "Usage: yopem-ui [--help | --version] | init [--framework vite|tanstack-router|tanstack-start|react-router|next|astro] [--ui <path>] [--cwd <path>] [--registry <URL>] | <add|update> <name> [--force] [--dry-run] [--cwd <path>] [--registry <URL>]"
+  "Usage: yopem-ui [--help | --version] | init [--framework vite|tanstack-router|tanstack-start|react-router|next|astro] [--ui <path>] [--dry-run] [--cwd <path>] [--registry <URL>] | <add|update> <name> [--force] [--dry-run] [--cwd <path>] [--registry <URL>]"
 
 function isFramework(
   value: string | undefined,
@@ -78,9 +78,12 @@ export async function runCli(args: string[], options: InitOptions = {}) {
   const cwd = resolve(options.cwd ?? process.cwd(), flags.get("--cwd") ?? ".")
   const registryUrl = flags.get("--registry") ?? options.registryUrl
 
+  function onWarning(warning: string) {
+    console.warn(`Warning: ${warning}`)
+    options.onWarning?.(warning)
+  }
+
   if (command === "init") {
-    if (flags.has("--dry-run") || options.dryRun)
-      throw new Error("--dry-run is not supported for init")
     const framework = flags.get("--framework")
 
     if (
@@ -94,13 +97,44 @@ export async function runCli(args: string[], options: InitOptions = {}) {
       ...options,
       cwd,
       registryUrl,
+      dryRun: flags.has("--dry-run") || options.dryRun,
+      onWarning,
       ui: flags.get("--ui") ?? options.ui,
       framework: isFramework(framework) ? framework : options.framework,
     })
 
-    console.info(
-      `Configured ${result.framework} (${result.configured} file(s))`,
-    )
+    if (result.preview) {
+      for (const file of result.preview.files) {
+        const label =
+          file.action === "write"
+            ? "Write"
+            : file.action === "delete"
+              ? "Delete"
+              : "Skip"
+
+        console.info(
+          `${label} ${file.path}${file.reason ? ` (${file.reason})` : ""}`,
+        )
+      }
+
+      for (const group of result.preview.dependencies) {
+        console.info(
+          `Runtime dependencies (${group.cwd}): ${group.dependencies.join(", ") || "none"}`,
+        )
+        console.info(
+          `Dev dependencies (${group.cwd}): ${group.devDependencies.join(", ") || "none"}`,
+        )
+      }
+
+      console.info(`Prerequisites: ${result.preview.prerequisites.join("; ")}`)
+      console.info(
+        `Dry run: ${result.framework}. No files written or package-manager commands run.`,
+      )
+    } else {
+      console.info(
+        `Configured ${result.framework} (${result.configured} file(s))`,
+      )
+    }
 
     return result
   }
@@ -119,6 +153,7 @@ export async function runCli(args: string[], options: InitOptions = {}) {
     cwd,
     registryUrl,
     mode: command,
+    onWarning,
     force: flags.has("--force"),
     dryRun: flags.has("--dry-run") || options.dryRun,
   })

package/src/init.ts

@@ -6,15 +6,17 @@ import type {
 } from "@yopem-ui/cli/install"
 
 import {
+  applyInstall,
   existingFile,
-  installItem,
   isRecord,
   isString,
+  planInstall,
   writeFiles,
 } from "@yopem-ui/cli/install"
 import {
   isPackageName,
   packageRunner,
+  pendingDependencies,
   workspaceRoot,
 } from "@yopem-ui/cli/project"
 import { readFile, realpath } from "node:fs/promises"
@@ -40,6 +42,25 @@ 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
@@ -1498,10 +1519,11 @@ function nextScripts(value: JsonValue | undefined) {
 }
 
 async function chooseFile(root: string, names: string[], fallback?: string) {
-  const matches: string[] = []
+  const existing = await Promise.all(
+    names.map((name) => existingFile(root, name)),
+  )
 
-  for (const name of names)
-    if (await existingFile(root, name)) matches.push(name)
+  const matches = names.filter((_, index) => existing[index])
 
   if (matches.length > 1)
     throw new Error(`Ambiguous configuration: ${matches.join(", ")}`)
@@ -1547,8 +1569,9 @@ function detectFramework(
   return detected[0]!
 }
 
-export async function initProject(options: InitOptions = {}) {
-  if (options.dryRun) throw new Error("--dry-run is not supported for init")
+export async function initProject(
+  options: InitOptions = {},
+): Promise<InitResult> {
   const root = await realpath(options.cwd ?? process.cwd())
 
   if (!(await existingFile(root, "package.json"))) {
@@ -1597,14 +1620,24 @@ export async function initProject(options: InitOptions = {}) {
     }
   }
 
-  const packageRun = await packageRunner(root, options.run)
-  const uiRun = await packageRunner(uiRoot, options.run)
+  const [packageRun, uiRun] = await Promise.all([
+    packageRunner(root, options.run),
+    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)
 
@@ -1612,6 +1645,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 })
   }
 
@@ -1669,43 +1708,48 @@ export async function initProject(options: InitOptions = {}) {
   if (shared) {
     const prefix = relative(root, uiRoot).replaceAll("\\", "/")
 
-    await plan(`${prefix}/package.json`, (content) => {
-      const value: JsonValue = JSON.parse(content)
+    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",
-      }
+        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
-      }
+        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`
-    })
+        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 = [
@@ -1868,15 +1912,165 @@ export async function initProject(options: InitOptions = {}) {
     }
   }
 
+  const basePlan = await planInstall("base", {
+    ...options,
+    cwd: uiRoot,
+    importPrefix: shared?.name,
+    dryRun: true,
+    run: uiRun,
+  })
+
+  const conflict = basePlan.preview.files.find(
+    (file) => file.action === "conflict",
+  )
+
+  if (conflict) throw new Error(conflict.reason)
+
+  if (
+    !basePlan.changes.get("src/styles/styles.css")?.after?.includes("@stylex;")
+  ) {
+    throw new Error(
+      "Add @stylex; to src/styles/styles.css before configuring StyleX",
+    )
+  }
+
+  const runtimeRequirements =
+    uiRoot === root
+      ? [...basePlan.requirements.dependencies, ...runtimeDependencies]
+      : runtimeDependencies
+
+  const devRequirements =
+    uiRoot === root
+      ? [...basePlan.requirements.devDependencies, ...devDependencies]
+      : devDependencies
+
+  const appPending = await pendingDependencies(
+    root,
+    runtimeRequirements,
+    devRequirements,
+  )
+
+  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)
+    }),
+  )
+
+  function isBaseDependency(argument: string) {
+    const separator = argument.indexOf("@", 1)
+
+    return baseDependencyNames.has(
+      separator < 0 ? argument : argument.slice(0, separator),
+    )
+  }
+
+  const baseApplicationPlan =
+    uiRoot === root
+      ? {
+          ...basePlan,
+          preview: {
+            ...basePlan.preview,
+            dependencies: appPending.dependencies.filter(isBaseDependency),
+            devDependencies:
+              appPending.devDependencies.filter(isBaseDependency),
+          },
+        }
+      : basePlan
+
+  if (options.dryRun) {
+    const baseDependencies = {
+      dependencies: basePlan.preview.dependencies,
+      devDependencies: basePlan.preview.devDependencies,
+    }
+
+    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"
+        }`,
+      })
+    }
+
+    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 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",
+        ],
+      },
+    }
+  }
+
   let baseInstalled = false
 
   try {
-    await installItem("base", {
-      ...options,
-      cwd: uiRoot,
-      importPrefix: shared?.name,
-      run: uiRun,
-    })
+    const baseResult = await applyInstall(baseApplicationPlan, options)
     baseInstalled = true
 
     if (
@@ -1897,36 +2091,26 @@ export async function initProject(options: InitOptions = {}) {
     if (!object(installed))
       throw new Error("Invalid package.json after installation")
 
-    const available = Object.fromEntries(
-      [installed.dependencies, installed.devDependencies].flatMap((entry) =>
-        object(entry) ? Object.entries(entry) : [],
-      ),
+    const pending = await pendingDependencies(
+      root,
+      runtimeRequirements,
+      devRequirements,
     )
 
-    const neededRuntime = runtimeDependencies.filter((name) => {
-      if (shared && name === `${shared.name}@workspace:*`) {
-        const version = available[shared.name]
-
-        return (
-          !isString(version) ||
-          (version !== "*" && !version.startsWith("workspace:"))
-        )
-      }
-
-      const packageName = name.includes("@", 1)
-        ? name.slice(0, name.lastIndexOf("@"))
-        : name
-
-      return !(packageName in available)
-    })
-
-    if (neededRuntime.length) await packageRun(["add", ...neededRuntime], root)
+    if (uiRoot === root) {
+      pending.dependencies = pending.dependencies.filter(
+        (argument) => !isBaseDependency(argument),
+      )
+      pending.devDependencies = pending.devDependencies.filter(
+        (argument) => !isBaseDependency(argument),
+      )
+    }
 
-    const neededDev = devDependencies.filter(
-      (name) => !(name.split("@").slice(0, -1).join("@") in available),
-    )
+    if (pending.dependencies.length)
+      await packageRun(["add", ...pending.dependencies], root)
 
-    if (neededDev.length) await packageRun(["add", "-d", ...neededDev], root)
+    if (pending.devDependencies.length)
+      await packageRun(["add", "-d", ...pending.devDependencies], root)
 
     if (shared) {
       const path = `${relative(root, uiRoot).replaceAll("\\", "/")}/package.json`
@@ -1990,7 +2174,11 @@ export async function initProject(options: InitOptions = {}) {
 
     await writeFiles(root, changes)
 
-    return { framework, configured: edits.size }
+    return {
+      framework,
+      configured: edits.size,
+      ...(baseResult.warnings && { warnings: baseResult.warnings }),
+    }
   } catch (cause) {
     if (!baseInstalled) throw cause
     throw new Error(

package/src/install.ts

@@ -1,4 +1,8 @@
-import { isPackageName, packageRunner } from "@yopem-ui/cli/project"
+import {
+  isPackageName,
+  packageRunner,
+  pendingDependencies,
+} from "@yopem-ui/cli/project"
 import { createHash } from "node:crypto"
 import {
   chmod,
@@ -55,12 +59,19 @@ interface RegistryItem {
   files: RegistryFile[]
   name: string
   registryDependencies: string[]
+  registryVersion: string
+}
+
+interface Provenance {
+  registryUrl: string
+  items: Record<string, string>
 }
 
 interface Manifest {
   version: 1
   files: Record<string, string>
   importPrefix?: string
+  provenance?: Record<string, Provenance>
 }
 
 export interface InstallPreview {
@@ -74,6 +85,13 @@ export interface InstallPreview {
   devDependencies: string[]
 }
 
+export interface InstallResult {
+  installed: number
+  skipped: number
+  preview?: InstallPreview
+  warnings?: string[]
+}
+
 export interface InstallOptions {
   cwd?: string
   dryRun?: boolean
@@ -84,6 +102,7 @@ export interface InstallOptions {
   requestTimeoutMs?: number
   fetcher?: (url: string, init?: RequestInit) => Promise<Response>
   run?: (args: string[], cwd: string) => Promise<void>
+  onWarning?: (warning: string) => void
 }
 
 function registryBaseUrl(value: string) {
@@ -132,13 +151,22 @@ async function registryItemJson(
     let response: Response
 
     try {
-      response = await fetcher(url, { signal: controller.signal })
+      response = await fetcher(url, {
+        signal: controller.signal,
+        redirect: "error",
+      })
     } catch {
       throw new Error(
         `Registry network error: ${url}. Check your connection and --registry URL.`,
       )
     }
 
+    if (response.status >= 300 && response.status < 400) {
+      throw new Error(
+        `Registry redirect rejected: ${url} (HTTP ${response.status}). Redirects are not allowed; check --registry URL.`,
+      )
+    }
+
     if (!response.ok) {
       throw new Error(
         `Registry request failed: ${url} (HTTP ${response.status}). Check --registry URL and item name.`,
@@ -226,6 +254,7 @@ function parseItem(value: JsonValue, name: string): RegistryItem {
     !isString(value.title) ||
     !isString(value.description) ||
     !isString(value.registryVersion) ||
+    !value.registryVersion.trim() ||
     !isStringArray(value.categories) ||
     !isStringArray(value.dependencies) ||
     !isStringArray(value.devDependencies) ||
@@ -291,6 +320,7 @@ function parseItem(value: JsonValue, name: string): RegistryItem {
     dependencies: value.dependencies,
     devDependencies: value.devDependencies,
     registryDependencies: value.registryDependencies,
+    registryVersion: value.registryVersion,
   }
 }
 
@@ -353,9 +383,44 @@ function readManifest(content: string | null): Manifest {
     files[path] = integrity
   }
 
+  const provenance: Record<string, Provenance> = {}
+
+  if (value.provenance !== undefined) {
+    if (!isRecord(value.provenance)) throw new Error("Invalid ui.json")
+
+    for (const [path, origin] of Object.entries(value.provenance)) {
+      if (
+        !files[path] ||
+        !isRecord(origin) ||
+        !isString(origin.registryUrl) ||
+        !isRecord(origin.items) ||
+        Object.keys(origin.items).length === 0
+      )
+        throw new Error("Invalid ui.json")
+
+      try {
+        if (registryBaseUrl(origin.registryUrl) !== origin.registryUrl)
+          throw new Error("Invalid ui.json")
+      } catch {
+        throw new Error("Invalid ui.json provenance registry URL")
+      }
+
+      const items: Record<string, string> = {}
+
+      for (const [name, version] of Object.entries(origin.items)) {
+        if (!namePattern.test(name) || !isString(version) || !version.trim())
+          throw new Error("Invalid ui.json")
+        items[name] = version
+      }
+
+      provenance[path] = { registryUrl: origin.registryUrl, items }
+    }
+  }
+
   return {
     version: 1,
     files,
+    ...(value.provenance !== undefined && { provenance }),
     ...(value.importPrefix !== undefined && {
       importPrefix: value.importPrefix,
     }),
@@ -425,26 +490,34 @@ export async function writeFiles(
   }
 
   try {
-    for (const [path, change] of changes) {
-      const exists = await existingFile(root, path)
-      const before = exists ? await readFile(join(root, path)) : null
-
-      if ((before?.toString("utf8") ?? null) !== change.before) {
-        throw new Error(`File changed before commit: ${path}`)
-      }
-
-      const mode = exists ? (await lstat(join(root, path))).mode & 0o7777 : null
-      const after = change.after === null ? null : Buffer.from(change.after)
-      staged.push({
-        path,
-        before,
-        after,
-        mode,
-        afterMode: mode,
-        changed: change.before !== change.after,
-        directory: null,
-      })
-    }
+    staged.push(
+      ...(await Promise.all(
+        [...changes].map(async ([path, change]): Promise<StagedFile> => {
+          const exists = await existingFile(root, path)
+          const before = exists ? await readFile(join(root, path)) : null
+
+          if ((before?.toString("utf8") ?? null) !== change.before) {
+            throw new Error(`File changed before commit: ${path}`)
+          }
+
+          const mode = exists
+            ? (await lstat(join(root, path))).mode & 0o7777
+            : null
+
+          const after = change.after === null ? null : Buffer.from(change.after)
+
+          return {
+            path,
+            before,
+            after,
+            mode,
+            afterMode: mode,
+            changed: change.before !== change.after,
+            directory: null,
+          }
+        }),
+      )),
+    )
 
     for (const file of staged) {
       if (!file.changed) continue
@@ -470,7 +543,9 @@ export async function writeFiles(
 
     await prepare?.()
 
-    for (const file of staged) await verify(file, file.before, file.mode)
+    await Promise.all(
+      staged.map((file) => verify(file, file.before, file.mode)),
+    )
 
     for (const file of staged) {
       if (!file.changed) continue
@@ -549,7 +624,7 @@ export async function runBun(args: string[], cwd: string) {
   }
 }
 
-export async function installItem(name: string, options: InstallOptions = {}) {
+export async function planInstall(name: string, options: InstallOptions = {}) {
   if (!namePattern.test(name)) throw new Error(`Invalid item name: ${name}`)
   const registryUrl = registryBaseUrl(options.registryUrl ?? defaultRegistryUrl)
   const requestTimeoutMs = options.requestTimeoutMs ?? 30_000
@@ -572,6 +647,7 @@ export async function installItem(name: string, options: InstallOptions = {}) {
     : null
 
   const manifest = readManifest(manifestText)
+  const originalManifest = JSON.stringify(manifest)
   const importPrefix = options.importPrefix ?? manifest.importPrefix ?? "@"
 
   if (
@@ -619,6 +695,7 @@ export async function installItem(name: string, options: InstallOptions = {}) {
 
   await visit(name)
   const files = new Map<string, RegistryFile>()
+  const owners = new Map<string, Record<string, string>>()
   const dependencies = new Set<string>()
   const devDependencies = new Set<string>()
 
@@ -639,6 +716,9 @@ export async function installItem(name: string, options: InstallOptions = {}) {
       }
 
       files.set(path, transformed)
+      const ownership = owners.get(path) ?? {}
+      ownership[item.name] = item.registryVersion
+      owners.set(path, ownership)
     }
   }
 
@@ -646,14 +726,48 @@ export async function installItem(name: string, options: InstallOptions = {}) {
   const previewFiles: InstallPreview["files"] = []
   let installed = 0
   let skipped = 0
+  const warnings: string[] = []
+
+  function track(path: string, integrity: string, applied: boolean) {
+    manifest.files[path] = integrity
+    const previous = manifest.provenance?.[path]
+
+    if (!applied && previous && previous.registryUrl !== registryUrl) return
+
+    const ownership =
+      applied || !previous ? { ...owners.get(path)! } : { ...previous.items }
+
+    if (!applied && previous) {
+      for (const [name, version] of Object.entries(owners.get(path)!)) {
+        if (!Object.hasOwn(ownership, name)) ownership[name] = version
+      }
+    }
+
+    manifest.provenance ??= {}
+    manifest.provenance[path] = { registryUrl, items: ownership }
+  }
 
-  for (const [path, file] of files) {
-    const exists = await existingFile(root, path)
+  const currentFiles = await Promise.all(
+    [...files].map(async ([path, file]) => {
+      const exists = await existingFile(root, path)
+      const before = exists ? await readFile(join(root, path), "utf8") : null
+
+      return { path, file, before }
+    }),
+  )
 
-    const before = exists ? await readFile(join(root, path), "utf8") : null
+  for (const { path, file, before } of currentFiles) {
     const current = before === null ? null : hash(before)
     changes.set(path, { before, after: before })
     const previous = manifest.files[path]
+    const origin = manifest.provenance?.[path]
+
+    if (origin && origin.registryUrl !== registryUrl) {
+      warnings.push(
+        `Updating tracked file from a different registry: ${path}. Previous: ${origin.registryUrl}; requested: ${registryUrl}. Review source before applying.`,
+      )
+    }
+
     const decision: InstallPreview["files"][number] = { path, action: "skip" }
     previewFiles.push(decision)
 
@@ -670,7 +784,7 @@ export async function installItem(name: string, options: InstallOptions = {}) {
     }
 
     if (current === file.integrity) {
-      manifest.files[path] = file.integrity
+      track(path, file.integrity, false)
       decision.reason = `Identical file: ${path}`
       skipped++
     } else if (
@@ -691,29 +805,61 @@ export async function installItem(name: string, options: InstallOptions = {}) {
 
       if (current && options.force) decision.forced = true
       changes.set(path, { before, after: file.content })
-      manifest.files[path] = file.integrity
+      track(path, file.integrity, true)
       installed++
     }
   }
 
-  const manifestAfter = `${JSON.stringify(manifest, null, 2)}\n`
+  const manifestAfter =
+    manifestText !== null && JSON.stringify(manifest) === originalManifest
+      ? manifestText
+      : `${JSON.stringify(manifest, null, 2)}\n`
+
   changes.set("ui.json", { before: manifestText, after: manifestAfter })
   previewFiles.push({
     path: "ui.json",
     action: manifestText === manifestAfter ? "skip" : "write",
   })
 
-  for (const dependency of dependencies) devDependencies.delete(dependency)
+  const pending = await pendingDependencies(root, dependencies, devDependencies)
+
+  return {
+    root,
+    run,
+    changes,
+    installed,
+    skipped,
+    warnings,
+    requirements: {
+      dependencies: [...dependencies],
+      devDependencies: [...devDependencies],
+    },
+    preview: { files: previewFiles, ...pending },
+  }
+}
+
+export async function installItem(
+  name: string,
+  options: InstallOptions = {},
+): Promise<InstallResult> {
+  return await applyInstall(await planInstall(name, options), options)
+}
+
+export async function applyInstall(
+  plan: Awaited<ReturnType<typeof planInstall>>,
+  options: InstallOptions = {},
+): Promise<InstallResult> {
+  const { root, run, changes, installed, skipped, warnings, preview } = plan
+  const warningResult = warnings.length ? { warnings } : {}
+
+  for (const warning of warnings) options.onWarning?.(warning)
 
   if (options.dryRun) {
     return {
       installed: 0,
       skipped,
-      preview: {
-        files: previewFiles,
-        dependencies: [...dependencies],
-        devDependencies: [...devDependencies],
-      },
+      preview,
+      ...warningResult,
     }
   }
 
@@ -721,14 +867,14 @@ export async function installItem(name: string, options: InstallOptions = {}) {
 
   try {
     await writeFiles(root, changes, async () => {
-      if (dependencies.size) {
+      if (preview.dependencies.length) {
         dependenciesStarted = true
-        await run(["add", ...dependencies], root)
+        await run(["add", ...preview.dependencies], root)
       }
 
-      if (devDependencies.size) {
+      if (preview.devDependencies.length) {
         dependenciesStarted = true
-        await run(["add", "-d", ...devDependencies], root)
+        await run(["add", "-d", ...preview.devDependencies], root)
       }
     })
   } catch (cause) {
@@ -739,5 +885,5 @@ export async function installItem(name: string, options: InstallOptions = {}) {
     )
   }
 
-  return { installed, skipped }
+  return { installed, skipped, ...warningResult }
 }

package/src/project.ts

@@ -21,7 +21,7 @@ export function isPackageName(value: unknown): value is string {
   )
 }
 
-async function readPackage(root: string): Promise<JsonObject> {
+export async function readPackage(root: string): Promise<JsonObject> {
   if (!(await existingFile(root, "package.json"))) return {}
 
   const value: JsonValue = JSON.parse(
@@ -166,8 +166,12 @@ async function packageManager(root: string) {
     ["yarn", "yarn.lock"],
   ]
 
-  for (const [manager, path] of locks) {
-    if (await existingFile(root, path)) found.add(manager)
+  const existingLocks = await Promise.all(
+    locks.map(([, path]) => existingFile(root, path)),
+  )
+
+  for (const [index, [manager]] of locks.entries()) {
+    if (existingLocks[index]) found.add(manager)
   }
 
   if (found.size > 1) {
@@ -184,8 +188,12 @@ export async function packageRunner(
   run?: InstallOptions["run"],
 ): Promise<NonNullable<InstallOptions["run"]>> {
   const target = await realpath(root)
-  const owner = await workspaceRoot(target)
-  const local = await packageManager(target)
+
+  const [owner, local] = await Promise.all([
+    workspaceRoot(target),
+    packageManager(target),
+  ])
+
   const workspace = owner === target ? local : await packageManager(owner)
 
   if (local && workspace && local !== workspace) {
@@ -221,3 +229,174 @@ export async function packageRunner(
     }
   }
 }
+
+interface PendingDependencies {
+  dependencies: string[]
+  devDependencies: string[]
+}
+
+interface Requirement {
+  name: string
+  spec: string
+  argument: string
+}
+
+function requirement(argument: string): Requirement {
+  const separator = argument.indexOf("@", 1)
+  const name = separator < 0 ? argument : argument.slice(0, separator)
+  const spec = separator < 0 ? "" : argument.slice(separator + 1)
+
+  if (!isPackageName(name) || (separator >= 0 && !spec)) {
+    throw new Error(`Invalid package dependency: ${argument}`)
+  }
+
+  return { name, spec, argument }
+}
+
+function bounds(spec: string) {
+  const match = spec
+    .trim()
+    .match(/^(\^|~)?(\d+)(?:\.(\d+|[xX*]))?(?:\.(\d+|[xX*]))?$/)
+
+  if (!match) return null
+  const major = Number(match[2])
+  const hasMinor = match[3] !== undefined && /^\d+$/.test(match[3])
+  const hasPatch = match[4] !== undefined && /^\d+$/.test(match[4])
+
+  if (!hasMinor && hasPatch) return null
+  const minor = hasMinor ? Number(match[3]) : 0
+  const patch = hasPatch ? Number(match[4]) : 0
+  const minimum = `${major}.${minor}.${patch}`
+
+  if (!Bun.semver.satisfies(minimum, spec)) return null
+
+  const maximum =
+    match[1] === "^"
+      ? major > 0 || !hasMinor
+        ? `${major + 1}.0.0`
+        : minor > 0 || !hasPatch
+          ? `0.${minor + 1}.0`
+          : `0.0.${patch + 1}`
+      : !hasMinor
+        ? `${major + 1}.0.0`
+        : match[1] === "~" || !hasPatch
+          ? `${major}.${minor + 1}.0`
+          : null
+
+  return { minimum, maximum }
+}
+
+function compatible(existing: string, requested: string) {
+  if (!requested || requested === "*" || existing === requested) return true
+
+  if (requested === "workspace:*") {
+    return existing === "*" || existing.startsWith("workspace:")
+  }
+
+  const current = bounds(existing)
+  const wanted = bounds(requested)
+
+  if (!current) {
+    return (
+      /^v?\d+\.\d+\.\d+(?:-[\da-zA-Z.-]+)?(?:\+[\da-zA-Z.-]+)?$/.test(
+        existing,
+      ) && Bun.semver.satisfies(existing, requested)
+    )
+  }
+
+  if (!current.maximum) return Bun.semver.satisfies(current.minimum, requested)
+
+  if (!wanted?.maximum) return false
+
+  return (
+    Bun.semver.satisfies(current.minimum, requested) &&
+    Bun.semver.order(current.maximum, wanted.maximum) <= 0
+  )
+}
+
+function section(manifest: JsonObject, name: string) {
+  const value = manifest[name]
+
+  if (value === undefined) return {}
+
+  if (!isRecord(value)) throw new Error(`Invalid package.json ${name}`)
+
+  for (const [name, spec] of Object.entries(value)) {
+    if (!isPackageName(name) || !isString(spec) || !spec.trim()) {
+      throw new Error(`Invalid package.json dependency: ${name}`)
+    }
+  }
+
+  return value
+}
+
+export async function pendingDependencies(
+  root: string,
+  runtime: Iterable<string>,
+  dev: Iterable<string>,
+) {
+  const manifest = await readPackage(root)
+  const dependencies = section(manifest, "dependencies")
+  const devDependencies = section(manifest, "devDependencies")
+
+  const groups = new Map<
+    string,
+    { runtime: boolean; requirements: Requirement[] }
+  >()
+
+  for (const [arguments_, isRuntime] of [
+    [runtime, true],
+    [dev, false],
+  ] as const) {
+    for (const argument of arguments_) {
+      const entry = requirement(argument)
+
+      const group = groups.get(entry.name) ?? {
+        runtime: false,
+        requirements: [],
+      }
+
+      group.runtime ||= isRuntime
+      group.requirements.push(entry)
+      groups.set(entry.name, group)
+    }
+  }
+
+  const pending: PendingDependencies = {
+    dependencies: [],
+    devDependencies: [],
+  }
+
+  for (const [name, group] of groups) {
+    const installed = dependencies[name] ?? devDependencies[name]
+
+    const satisfied =
+      isString(installed) &&
+      group.requirements.every((entry) => compatible(installed, entry.spec))
+
+    if (satisfied && (!group.runtime || dependencies[name] !== undefined))
+      continue
+
+    const chosen = group.requirements.find((candidate) =>
+      group.requirements.every((entry) =>
+        compatible(candidate.spec || "*", entry.spec),
+      ),
+    )
+
+    if (!chosen && !satisfied) {
+      throw new Error(
+        `Conflicting package requirements: ${group.requirements.map((entry) => entry.argument).join(", ")}`,
+      )
+    }
+
+    const argument = satisfied ? `${name}@${installed}` : chosen!.argument
+
+    const target = group.runtime
+      ? pending.dependencies
+      : pending.devDependencies
+
+    target.push(argument)
+  }
+
+  return pending
+}