@yopem-ui/cli 0.0.2 → 0.1.1

package/src/install.ts

@@ -1,8 +1,25 @@
+import {
+  isPackageName,
+  packageRunner,
+  pendingDependencies,
+} from "@yopem-ui/cli/project"
 import { createHash } from "node:crypto"
-import { lstat, mkdir, readFile, realpath, writeFile } from "node:fs/promises"
-import { dirname, join } from "node:path"
-
-const registryUrl = "http://localhost:3100/r"
+import {
+  chmod,
+  link,
+  lstat,
+  mkdir,
+  mkdtemp,
+  readFile,
+  realpath,
+  rename,
+  rm,
+  unlink,
+  writeFile,
+} from "node:fs/promises"
+import { dirname, join, relative } from "node:path"
+
+const defaultRegistryUrl = "https://ui.yopem.com/r"
 
 const namePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
 
@@ -42,19 +59,139 @@ 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 {
+  files: {
+    path: string
+    action: "write" | "skip" | "conflict"
+    reason?: string
+    forced?: true
+  }[]
+  dependencies: string[]
+  devDependencies: string[]
+}
+
+export interface InstallResult {
+  installed: number
+  skipped: number
+  preview?: InstallPreview
+  warnings?: string[]
 }
 
 export interface InstallOptions {
   cwd?: string
+  dryRun?: boolean
   force?: boolean
+  importPrefix?: string
   mode?: "add" | "update"
-  fetcher?: (url: string) => Promise<Response>
+  registryUrl?: string
+  requestTimeoutMs?: number
+  fetcher?: (url: string, init?: RequestInit) => Promise<Response>
   run?: (args: string[], cwd: string) => Promise<void>
+  onWarning?: (warning: string) => void
+}
+
+function registryBaseUrl(value: string) {
+  const url = URL.parse(value)
+
+  const local =
+    url &&
+    (url.hostname === "localhost" ||
+      url.hostname === "[::1]" ||
+      /^127(?:\.\d+){3}$/.test(url.hostname))
+
+  if (
+    !url ||
+    url.username ||
+    url.password ||
+    url.href.includes("?") ||
+    url.href.includes("#") ||
+    (url.protocol !== "https:" && !(url.protocol === "http:" && local))
+  ) {
+    throw new Error(
+      "Invalid registry URL. Use HTTPS (or local HTTP on localhost or a loopback address), without credentials, query or fragment.",
+    )
+  }
+
+  return url.href.replace(/\/+$/, "")
+}
+
+async function registryItemJson(
+  url: string,
+  fetcher: NonNullable<InstallOptions["fetcher"]>,
+  timeoutMs: number,
+) {
+  const controller = new AbortController()
+  const deadline = Promise.withResolvers<never>()
+
+  const timer = setTimeout(() => {
+    deadline.reject(
+      new Error(
+        `Registry request timed out after ${timeoutMs}ms: ${url}. Check your connection and --registry URL.`,
+      ),
+    )
+    controller.abort()
+  }, timeoutMs)
+
+  async function read() {
+    let response: Response
+
+    try {
+      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.`,
+      )
+    }
+
+    try {
+      const value: JsonValue = await response.json()
+
+      return value
+    } catch (cause) {
+      throw new Error(
+        cause instanceof SyntaxError
+          ? `Registry returned malformed JSON: ${url}. Check --registry URL and registry contents.`
+          : `Registry network error reading response: ${url}. Check your connection and --registry URL.`,
+      )
+    }
+  }
+
+  try {
+    return await Promise.race([read(), deadline.promise])
+  } finally {
+    clearTimeout(timer)
+    controller.abort()
+  }
 }
 
 export function isRecord(value: JsonValue | undefined): value is JsonObject {
@@ -103,6 +240,10 @@ function hash(content: string) {
   return `sha256-${createHash("sha256").update(content).digest("base64")}`
 }
 
+function validImportPrefix(value: unknown): value is string {
+  return value === "@" || isPackageName(value)
+}
+
 function parseItem(value: JsonValue, name: string): RegistryItem {
   if (
     !isRecord(value) ||
@@ -113,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) ||
@@ -178,6 +320,7 @@ function parseItem(value: JsonValue, name: string): RegistryItem {
     dependencies: value.dependencies,
     devDependencies: value.devDependencies,
     registryDependencies: value.registryDependencies,
+    registryVersion: value.registryVersion,
   }
 }
 
@@ -211,17 +354,18 @@ export async function existingFile(root: string, relative: string) {
   return true
 }
 
-async function readManifest(root: string): Promise<Manifest> {
-  if (!(await existingFile(root, ".yopem-ui.json"))) {
-    return { version: 1, files: {} }
-  }
+function readManifest(content: string | null): Manifest {
+  if (content === null) return { version: 1, files: {} }
 
-  const value: JsonValue = JSON.parse(
-    await readFile(join(root, ".yopem-ui.json"), "utf8"),
-  )
+  const value: JsonValue = JSON.parse(content)
 
-  if (!isRecord(value) || value.version !== 1 || !isRecord(value.files)) {
-    throw new Error("Invalid .yopem-ui.json")
+  if (
+    !isRecord(value) ||
+    value.version !== 1 ||
+    !isRecord(value.files) ||
+    (value.importPrefix !== undefined && !validImportPrefix(value.importPrefix))
+  ) {
+    throw new Error("Invalid ui.json")
   }
 
   const files: Record<string, string> = {}
@@ -233,13 +377,229 @@ async function readManifest(root: string): Promise<Manifest> {
       !isString(integrity) ||
       !hashPattern.test(integrity)
     ) {
-      throw new Error("Invalid .yopem-ui.json")
+      throw new Error("Invalid ui.json")
     }
 
     files[path] = integrity
   }
 
-  return { version: 1, files }
+  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,
+    }),
+  }
+}
+
+export interface FileChange {
+  before: string | null
+  after: string | null
+}
+
+interface StagedFile {
+  path: string
+  before: Buffer | null
+  after: Buffer | null
+  mode: number | null
+  afterMode: number | null
+  changed: boolean
+  directory: string | null
+}
+
+export async function writeFiles(
+  root: string,
+  changes: ReadonlyMap<string, FileChange>,
+  prepare?: () => Promise<void>,
+) {
+  const staged: StagedFile[] = []
+  const committed: StagedFile[] = []
+  const recovery = new Set<StagedFile>()
+
+  async function verify(
+    file: StagedFile,
+    expected: Buffer | null,
+    mode: number | null,
+  ) {
+    const exists = await existingFile(root, file.path)
+    const path = join(root, file.path)
+    const current = exists ? await readFile(path) : null
+
+    if (
+      (current === null
+        ? expected !== null
+        : expected === null || !current.equals(expected)) ||
+      (exists && ((await lstat(path)).mode & 0o7777) !== mode)
+    ) {
+      throw new Error(`File changed before commit: ${file.path}`)
+    }
+  }
+
+  async function cleanup() {
+    const failures: string[] = []
+
+    for (const file of staged) {
+      if (!file.directory || recovery.has(file)) continue
+
+      try {
+        await existingFile(root, relative(root, join(file.directory, "before")))
+        await rm(file.directory, { recursive: true, force: true })
+      } catch (cause) {
+        failures.push(
+          `Temporary cleanup failed: ${file.directory}: ${String(cause)}`,
+        )
+      }
+    }
+
+    return failures
+  }
+
+  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,
+      })
+    }
+
+    for (const file of staged) {
+      if (!file.changed) continue
+      const parent = dirname(join(root, file.path))
+      await mkdir(parent, { recursive: true })
+      await verify(file, file.before, file.mode)
+      file.directory = await mkdtemp(join(parent, ".yopem-ui-"))
+
+      if (file.after !== null) {
+        const path = join(file.directory, "after")
+        await writeFile(path, file.after, { flag: "wx" })
+
+        if (file.mode !== null) await chmod(path, file.mode)
+        file.afterMode = (await lstat(path)).mode & 0o7777
+      }
+
+      if (file.before !== null) {
+        const path = join(file.directory, "before")
+        await writeFile(path, file.before, { flag: "wx" })
+        await chmod(path, file.mode!)
+      }
+    }
+
+    await prepare?.()
+
+    for (const file of staged) await verify(file, file.before, file.mode)
+
+    for (const file of staged) {
+      if (!file.changed) continue
+      await verify(file, file.before, file.mode)
+      const path = join(root, file.path)
+
+      try {
+        if (file.after === null) await unlink(path)
+        else if (file.before === null)
+          await link(join(file.directory!, "after"), path)
+        else await rename(join(file.directory!, "after"), path)
+      } catch (cause) {
+        throw new Error(`Failed to commit ${file.path}: ${String(cause)}`, {
+          cause,
+        })
+      }
+
+      committed.push(file)
+    }
+  } catch (cause) {
+    const failures: string[] = []
+
+    for (const file of committed.toReversed()) {
+      try {
+        await verify(
+          file,
+          file.after,
+          file.after === null ? null : file.afterMode,
+        )
+
+        if (file.before === null) await unlink(join(root, file.path))
+        else if (file.after === null)
+          await link(join(file.directory!, "before"), join(root, file.path))
+        else
+          await rename(join(file.directory!, "before"), join(root, file.path))
+      } catch (rollbackCause) {
+        const backup =
+          file.before === null
+            ? ""
+            : `; original backup: ${join(file.directory!, "before")}`
+
+        if (file.before !== null) recovery.add(file)
+        failures.push(`${file.path}: ${String(rollbackCause)}${backup}`)
+      }
+    }
+
+    const rollback = committed.length
+      ? failures.length
+        ? `\nRollback incomplete: ${failures.join("\n")}`
+        : "\nCommitted files restored."
+      : ""
+
+    const cleanupFailures = await cleanup()
+    throw new Error(
+      `${cause instanceof Error ? cause.message : String(cause)}${rollback}${cleanupFailures.length ? `\n${cleanupFailures.join("\n")}` : ""}`,
+      { cause },
+    )
+  }
+
+  const failures = await cleanup()
+
+  if (failures.length) {
+    throw new Error(`Files committed. ${failures.join("\n")}`)
+  }
 }
 
 export async function runBun(args: string[], cwd: string) {
@@ -254,10 +614,48 @@ 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
+
+  if (
+    !Number.isInteger(requestTimeoutMs) ||
+    requestTimeoutMs <= 0 ||
+    requestTimeoutMs > 2_147_483_647
+  ) {
+    throw new Error(
+      "Registry request timeout must be an integer from 1 to 2147483647ms",
+    )
+  }
+
   const root = await realpath(options.cwd ?? process.cwd())
-  const manifest = await readManifest(root)
+  const run = await packageRunner(root, options.run)
+
+  const manifestText = (await existingFile(root, "ui.json"))
+    ? await readFile(join(root, "ui.json"), "utf8")
+    : null
+
+  const manifest = readManifest(manifestText)
+  const originalManifest = JSON.stringify(manifest)
+  const importPrefix = options.importPrefix ?? manifest.importPrefix ?? "@"
+
+  if (
+    !validImportPrefix(importPrefix) ||
+    (options.importPrefix !== undefined &&
+      !validImportPrefix(options.importPrefix))
+  ) {
+    throw new Error(`Invalid import prefix: ${importPrefix}`)
+  }
+
+  if (
+    importPrefix !== (manifest.importPrefix ?? "@") &&
+    Object.keys(manifest.files).length > 0
+  ) {
+    throw new Error("Cannot change import prefix with tracked files")
+  }
+
+  if (options.importPrefix !== undefined) manifest.importPrefix = importPrefix
   const items = new Map<string, RegistryItem>()
   const visiting = new Set<string>()
   const fetcher = options.fetcher ?? fetch
@@ -270,13 +668,15 @@ export async function installItem(name: string, options: InstallOptions = {}) {
     }
 
     visiting.add(itemName)
-    const response = await fetcher(`${registryUrl}/${itemName}.json`)
 
-    if (!response.ok)
-      throw new Error(
-        `Registry request failed: ${itemName} (${response.status})`,
-      )
-    const item = parseItem(await response.json(), itemName)
+    const item = parseItem(
+      await registryItemJson(
+        `${registryUrl}/${itemName}.json`,
+        fetcher,
+        requestTimeoutMs,
+      ),
+      itemName,
+    )
 
     for (const dependency of item.registryDependencies) await visit(dependency)
     items.set(itemName, item)
@@ -285,6 +685,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>()
 
@@ -296,39 +697,79 @@ export async function installItem(name: string, options: InstallOptions = {}) {
 
     for (const file of item.files) {
       const path = targetPath(file.target)
+      const content = file.content.replace(/(["'`])@\//g, `$1${importPrefix}/`)
+      const transformed = { ...file, content, integrity: hash(content) }
       const previous = files.get(path)
 
-      if (previous && previous.integrity !== file.integrity) {
+      if (previous && previous.integrity !== transformed.integrity) {
         throw new Error(`Conflicting registry files: ${path}`)
       }
 
-      files.set(path, file)
+      files.set(path, transformed)
+      const ownership = owners.get(path) ?? {}
+      ownership[item.name] = item.registryVersion
+      owners.set(path, ownership)
     }
   }
 
-  const writes: [string, RegistryFile][] = []
+  const changes = new Map<string, FileChange>()
+  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 current = exists
-      ? hash(await readFile(join(root, path), "utf8"))
-      : null
-
+    const before = exists ? await readFile(join(root, path), "utf8") : null
+    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)
 
     if (current && previous && current !== previous && !options.force) {
+      decision.reason = `Modified file: ${path} (use --force to overwrite)`
+
       if (options.mode === "update") {
-        throw new Error(`Modified file: ${path} (use --force to overwrite)`)
-      }
+        decision.action = "conflict"
+
+        if (!options.dryRun) throw new Error(decision.reason)
+      } else skipped++
 
-      skipped++
       continue
     }
 
     if (current === file.integrity) {
-      manifest.files[path] = file.integrity
+      track(path, file.integrity, false)
+      decision.reason = `Identical file: ${path}`
       skipped++
     } else if (
       current &&
@@ -336,45 +777,97 @@ export async function installItem(name: string, options: InstallOptions = {}) {
       previous === current &&
       options.mode !== "update"
     ) {
+      decision.reason = `Tracked file: ${path} (use update to replace)`
       skipped++
     } else if (current && !options.force && previous !== current) {
-      throw new Error(`Existing file: ${path} (use --force to overwrite)`)
+      decision.action = "conflict"
+      decision.reason = `Existing file: ${path} (use --force to overwrite)`
+
+      if (!options.dryRun) throw new Error(decision.reason)
     } else {
-      writes.push([path, file])
+      decision.action = "write"
+
+      if (current && options.force) decision.forced = true
+      changes.set(path, { before, after: file.content })
+      track(path, file.integrity, true)
+      installed++
     }
   }
 
-  const run = options.run ?? runBun
+  const manifestAfter =
+    manifestText !== null && JSON.stringify(manifest) === originalManifest
+      ? manifestText
+      : `${JSON.stringify(manifest, null, 2)}\n`
 
-  if (dependencies.size) await run(["add", ...dependencies], root)
+  changes.set("ui.json", { before: manifestText, after: manifestAfter })
+  previewFiles.push({
+    path: "ui.json",
+    action: manifestText === manifestAfter ? "skip" : "write",
+  })
+
+  const pending = await pendingDependencies(root, dependencies, devDependencies)
+
+  return {
+    root,
+    run,
+    changes,
+    installed,
+    skipped,
+    warnings,
+    requirements: {
+      dependencies: [...dependencies],
+      devDependencies: [...devDependencies],
+    },
+    preview: { files: previewFiles, ...pending },
+  }
+}
 
-  for (const dependency of dependencies) devDependencies.delete(dependency)
+export async function installItem(
+  name: string,
+  options: InstallOptions = {},
+): Promise<InstallResult> {
+  return await applyInstall(await planInstall(name, options), options)
+}
 
-  if (devDependencies.size) await run(["add", "-d", ...devDependencies], root)
+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,
+      ...warningResult,
+    }
+  }
 
-  for (const [path, file] of writes) {
-    if (await existingFile(root, path)) {
-      const current = hash(await readFile(join(root, path), "utf8"))
-      const previous = manifest.files[path]
+  let dependenciesStarted = false
 
-      if (
-        current !== previous &&
-        current !== file.integrity &&
-        !options.force
-      ) {
-        throw new Error(`Modified file: ${path} (use --force to overwrite)`)
+  try {
+    await writeFiles(root, changes, async () => {
+      if (preview.dependencies.length) {
+        dependenciesStarted = true
+        await run(["add", ...preview.dependencies], root)
       }
-    }
 
-    await mkdir(dirname(join(root, path)), { recursive: true })
-    await writeFile(join(root, path), file.content, { flag: "w" })
-    manifest.files[path] = file.integrity
+      if (preview.devDependencies.length) {
+        dependenciesStarted = true
+        await run(["add", "-d", ...preview.devDependencies], root)
+      }
+    })
+  } catch (cause) {
+    if (!dependenciesStarted) 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.`,
+      { cause },
+    )
   }
 
-  await writeFile(
-    join(root, ".yopem-ui.json"),
-    `${JSON.stringify(manifest, null, 2)}\n`,
-  )
-
-  return { installed: writes.length, skipped }
+  return { installed, skipped, ...warningResult }
 }