@usehyper/cli 0.1.0

package/src/registry/apply.ts

@@ -0,0 +1,268 @@
+/**
+ * Component applier.
+ *
+ * Takes a fetched `RegistryComponent`, the user's `HyperConfig`, and writes
+ * the files into their repo. Handles:
+ *
+ *   - recursive `registryDeps` resolution (depth-first, deduplicated)
+ *   - import rewriting per the user's alias
+ *   - sha256-based drift detection: refuse to overwrite locally-modified
+ *     files unless `--force` is set
+ *   - atomic-ish lockfile updates: in-memory mutation of the lock object,
+ *     a single write at the end
+ *   - peer-dependency reporting (returned to the caller)
+ */
+
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises"
+import { dirname, resolve } from "node:path"
+import type { HyperConfig, HyperLock, LockedComponent } from "../config/types.ts"
+import type { RegistryClient } from "./client.ts"
+import { mergeEnvFile } from "./env-writer.ts"
+import { resolveTarget, rewriteFile } from "./rewrite.ts"
+import type { RegistryComponent, RegistryFile } from "./types.ts"
+
+export interface ApplyOptions {
+  readonly cwd: string
+  readonly config: HyperConfig
+  readonly client: RegistryClient
+  readonly lock: HyperLock
+  readonly force: boolean
+  readonly dryRun: boolean
+  /** Pretend each component is at this version (snapshot/CI use case). */
+  readonly version?: string
+}
+
+export interface ApplyOutcome {
+  /** Files written or that would have been written (dry run). */
+  readonly written: readonly { path: string; component: string; reason: "new" | "updated" }[]
+  /** Files unchanged (already match the registry). */
+  readonly unchanged: readonly { path: string; component: string }[]
+  /** Files that conflict (local-modified, no --force). */
+  readonly conflicts: readonly { path: string; component: string }[]
+  /** Components touched, in install order (deps first). */
+  readonly components: readonly RegistryComponent[]
+  /** Updated lock — caller persists with `writeLock`. */
+  readonly lock: HyperLock
+  /** Peer deps surfaced after install. */
+  readonly peerDeps: Readonly<Record<string, string>>
+  readonly optionalPeerDeps: Readonly<Record<string, string>>
+  /** Warnings raised by `resolveTarget` (unknown placeholders). */
+  readonly warnings: readonly string[]
+  /** Env-var changes applied to `.env.local`. */
+  readonly envVars: {
+    readonly path: string
+    readonly added: readonly string[]
+    readonly preserved: readonly string[]
+  }
+}
+
+/**
+ * Resolve the full transitive dep set for a list of root components.
+ * Returns components in topological order (deps before dependents).
+ */
+export async function resolveDeps(
+  roots: readonly string[],
+  client: RegistryClient,
+): Promise<RegistryComponent[]> {
+  const visited = new Map<string, RegistryComponent>()
+  const order: RegistryComponent[] = []
+  const visiting = new Set<string>()
+
+  const visit = async (name: string): Promise<void> => {
+    if (visited.has(name)) return
+    if (visiting.has(name)) {
+      throw new Error(`registry cycle detected at ${name}`)
+    }
+    visiting.add(name)
+    const c = await client.getComponent(name)
+    for (const d of c.registryDeps) await visit(d)
+    visiting.delete(name)
+    visited.set(name, c)
+    order.push(c)
+  }
+
+  for (const r of roots) await visit(r)
+  return order
+}
+
+async function readIfExists(path: string): Promise<string | null> {
+  try {
+    return await readFile(path, "utf8")
+  } catch {
+    return null
+  }
+}
+
+async function sha256(s: string): Promise<string> {
+  const buf = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(s))
+  return Array.from(new Uint8Array(buf))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("")
+}
+
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await stat(p)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Apply (or simulate applying) a list of root components.
+ *
+ * The roots come from the user (`hyper add cors auth-jwt` → `["cors", "auth-jwt"]`).
+ * Their transitive deps are resolved automatically.
+ */
+export async function applyComponents(
+  roots: readonly string[],
+  opts: ApplyOptions,
+): Promise<ApplyOutcome> {
+  const components = await resolveDeps(roots, opts.client)
+  const subpathsByComponent = new Map(components.map((c) => [c.name, c.subpaths]))
+
+  const written: { path: string; component: string; reason: "new" | "updated" }[] = []
+  const unchanged: { path: string; component: string }[] = []
+  const conflicts: { path: string; component: string }[] = []
+  const peerDeps: Record<string, string> = {}
+  const optionalPeerDeps: Record<string, string> = {}
+  const warnings: string[] = []
+
+  const componentsByName: Record<string, LockedComponent> = { ...opts.lock.components }
+
+  for (const c of components) {
+    Object.assign(peerDeps, c.peerDeps)
+    Object.assign(optionalPeerDeps, c.optionalPeerDeps)
+
+    const lockedFiles: { path: string; sha256: string }[] = []
+
+    for (const f of c.files) {
+      const resolved = resolveTarget(f, c.name, opts.config.baseDir)
+      const relPath = resolved.relPath
+      if (resolved.warning) warnings.push(`${c.name}: ${resolved.warning}`)
+      const abs = resolve(opts.cwd, relPath)
+
+      const rewritten = resolved.rewriteImports
+        ? rewriteFile(f.contents, {
+            alias: opts.config.alias,
+            targetPath: relPath,
+            baseDir: opts.config.baseDir,
+            subpathsByComponent,
+          })
+        : f.contents
+      const newHash = await sha256(rewritten)
+
+      const existing = await readIfExists(abs)
+      if (existing !== null) {
+        const existingHash = await sha256(existing)
+        if (existingHash === newHash) {
+          unchanged.push({ path: relPath, component: c.name })
+          lockedFiles.push({ path: relPath, sha256: newHash })
+          continue
+        }
+        // The file exists and differs.
+        const lockedHash = opts.lock.components[c.name]?.files.find(
+          (lf) => lf.path === relPath,
+        )?.sha256
+        const isUpdate = lockedHash === existingHash
+        // - isUpdate: matches the lockfile → user hasn't touched it → safe to overwrite as an update.
+        // - else:    user-edited file → conflict unless --force.
+        if (!isUpdate && !opts.force) {
+          conflicts.push({ path: relPath, component: c.name })
+          continue
+        }
+        if (!opts.dryRun) {
+          await mkdir(dirname(abs), { recursive: true })
+          await writeFile(abs, rewritten)
+        }
+        written.push({ path: relPath, component: c.name, reason: "updated" })
+        lockedFiles.push({ path: relPath, sha256: newHash })
+        continue
+      }
+
+      // Net-new file.
+      if (!opts.dryRun) {
+        await mkdir(dirname(abs), { recursive: true })
+        await writeFile(abs, rewritten)
+      }
+      written.push({ path: relPath, component: c.name, reason: "new" })
+      lockedFiles.push({ path: relPath, sha256: newHash })
+    }
+
+    // Only update the lock entry if no conflicts blocked installs for this component.
+    const componentConflicts = conflicts.filter((x) => x.component === c.name)
+    if (componentConflicts.length === 0) {
+      const entry: LockedComponent = {
+        version: opts.version ?? c.version,
+        installedAt: new Date().toISOString(),
+        alias: opts.config.alias,
+        files: lockedFiles.sort((a, b) => a.path.localeCompare(b.path)),
+      }
+      componentsByName[c.name] = entry
+    }
+  }
+
+  const lock: HyperLock = {
+    schema: 1,
+    registryUrl: opts.config.registryUrl,
+    components: componentsByName,
+  }
+
+  // Collect env vars across the install. First component to declare a key
+  // wins; later components see it as "preserved" (idempotent re-runs).
+  // Components with conflicts are skipped so a half-applied install doesn't
+  // leak secrets.
+  const conflictedNames = new Set(conflicts.map((x) => x.component))
+  const envVarsToAdd: Record<string, string> = {}
+  for (const c of components) {
+    if (!c.envVars || conflictedNames.has(c.name)) continue
+    for (const [k, v] of Object.entries(c.envVars)) {
+      if (!(k in envVarsToAdd)) envVarsToAdd[k] = v
+    }
+  }
+  const envPath = ".env.local"
+  const envSummary = await applyEnvVars(opts.cwd, envPath, envVarsToAdd, opts.dryRun)
+
+  return {
+    written,
+    unchanged,
+    conflicts,
+    components,
+    lock,
+    peerDeps,
+    optionalPeerDeps,
+    warnings,
+    envVars: { path: envPath, ...envSummary },
+  }
+}
+
+async function applyEnvVars(
+  cwd: string,
+  relPath: string,
+  vars: Readonly<Record<string, string>>,
+  dryRun: boolean,
+): Promise<{ added: readonly string[]; preserved: readonly string[] }> {
+  if (Object.keys(vars).length === 0) return { added: [], preserved: [] }
+  const abs = resolve(cwd, relPath)
+  const existing = (await readIfExists(abs)) ?? ""
+  const merge = mergeEnvFile(existing, vars)
+  if (!dryRun && merge.added.length > 0) {
+    await mkdir(dirname(abs), { recursive: true })
+    await writeFile(abs, merge.merged)
+  }
+  return { added: merge.added, preserved: merge.preserved }
+}
+
+/** Read the actual on-disk version of a registry file (for `hyper diff`). */
+export async function readLocalFile(
+  cwd: string,
+  config: HyperConfig,
+  componentName: string,
+  manifestFile: RegistryFile,
+): Promise<string | null> {
+  const relPath = resolveTarget(manifestFile, componentName, config.baseDir).relPath
+  const abs = resolve(cwd, relPath)
+  if (!(await pathExists(abs))) return null
+  return await readFile(abs, "utf8")
+}

package/src/registry/client.ts

@@ -0,0 +1,127 @@
+/**
+ * Registry client.
+ *
+ * Resolution order:
+ *   1. fetch `<registryUrl>/r/<name>(@<version>)?.json`
+ *   2. on network failure or non-200, fall back to the bundled snapshot
+ *      (regenerated by the root `postinstall` and the CLI's `prepack` hook)
+ *   3. on no match, throw
+ *
+ * The bundled snapshot keeps `hyper add` working in air-gapped CI and during
+ * registry outages. It's meant as a safety net, not a primary path — production
+ * installs always hit the network when reachable.
+ *
+ * The snapshot is loaded lazily because it's gitignored: in a fresh clone
+ * before `postinstall` runs, the file may not exist. That's fine — we just
+ * skip the fallback in that case.
+ */
+
+import type { RegistryComponent, RegistryIndex } from "./types.ts"
+
+interface Snapshot {
+  readonly index: RegistryIndex
+  readonly components: Readonly<Record<string, RegistryComponent>>
+}
+
+let snapshotCache: Snapshot | null | undefined
+
+async function loadSnapshot(): Promise<Snapshot | null> {
+  if (snapshotCache !== undefined) return snapshotCache
+  try {
+    const mod = (await import("./snapshot.ts")) as {
+      SNAPSHOT_INDEX: RegistryIndex
+      SNAPSHOT_COMPONENTS: Readonly<Record<string, RegistryComponent>>
+    }
+    snapshotCache = { index: mod.SNAPSHOT_INDEX, components: mod.SNAPSHOT_COMPONENTS }
+  } catch {
+    snapshotCache = null
+  }
+  return snapshotCache
+}
+
+export interface RegistryClient {
+  readonly url: string
+  getIndex(): Promise<RegistryIndex>
+  getComponent(name: string, version?: string): Promise<RegistryComponent>
+  listComponents(): Promise<
+    readonly { name: string; version: string; title?: string; description: string }[]
+  >
+}
+
+export interface RegistryClientOptions {
+  readonly url?: string
+  /** Force snapshot-only mode (offline, deterministic CI). */
+  readonly offline?: boolean
+  /** Throw on snapshot fallback (used by tests + strict CI). */
+  readonly noFallback?: boolean
+  /** Override fetch for tests. */
+  readonly fetch?: typeof fetch
+}
+
+const DEFAULT_URL = "https://hyperjs.ai"
+
+export class RegistryError extends Error {
+  override readonly name = "RegistryError"
+  constructor(
+    message: string,
+    readonly status?: number,
+  ) {
+    super(message)
+  }
+}
+
+export function createRegistryClient(opts: RegistryClientOptions = {}): RegistryClient {
+  const url = (opts.url ?? DEFAULT_URL).replace(/\/+$/, "")
+  const offline = opts.offline === true
+  const noFallback = opts.noFallback === true
+  const fetchFn = opts.fetch ?? globalThis.fetch
+
+  const tryFetch = async <T>(path: string): Promise<T | null> => {
+    if (offline) return null
+    try {
+      const res = await fetchFn(`${url}${path}`, {
+        headers: { accept: "application/json" },
+      })
+      if (!res.ok) return null
+      return (await res.json()) as T
+    } catch {
+      return null
+    }
+  }
+
+  return {
+    url,
+    async getIndex() {
+      const remote = await tryFetch<RegistryIndex>("/r/index.json")
+      if (remote) return remote
+      if (noFallback) throw new RegistryError(`failed to fetch ${url}/r/index.json`)
+      const snap = await loadSnapshot()
+      if (!snap) throw new RegistryError("registry unreachable and no offline snapshot available")
+      return snap.index
+    },
+    async getComponent(name, version) {
+      const slug = version ? `${name}@${version}` : name
+      const remote = await tryFetch<RegistryComponent>(`/r/${slug}.json`)
+      if (remote) return remote
+      const snap = await loadSnapshot()
+      const cached = snap?.components[name]
+      if (!cached) throw new RegistryError(`component not found: ${name}`)
+      if (version && cached.version !== version) {
+        throw new RegistryError(
+          `version mismatch (snapshot has ${cached.version}, requested ${version})`,
+        )
+      }
+      if (noFallback) throw new RegistryError(`failed to fetch ${url}/r/${slug}.json`)
+      return cached
+    },
+    async listComponents() {
+      const idx = await this.getIndex()
+      return idx.components.map((c) => ({
+        name: c.name,
+        version: c.version,
+        description: c.description,
+        ...(c.title !== undefined && { title: c.title }),
+      }))
+    },
+  }
+}

package/src/registry/env-writer.ts

@@ -0,0 +1,135 @@
+/**
+ * `.env.local` merger for `hyper add`.
+ *
+ * When a component declares `envVars`, the CLI appends entries to the
+ * project's `.env.local`, leaving any existing keys untouched. Re-running
+ * `hyper add` is therefore idempotent: secrets are generated exactly once.
+ *
+ * Two kinds of `${...}` interpolation are resolved LOCALLY (so secrets
+ * never leave the user's machine):
+ *
+ *   ${random:hex:N}     -> N random bytes encoded as 2N hex chars
+ *   ${random:base64:N}  -> N random bytes encoded as base64
+ *
+ * Anything else (including unknown `${...}` forms) is written through
+ * verbatim. Users can fill those in by hand.
+ */
+
+import { randomBytes } from "node:crypto"
+
+export interface EnvMergeResult {
+  /** New file contents (unchanged + appended block). */
+  readonly merged: string
+  /** Keys we added in this run. */
+  readonly added: readonly string[]
+  /** Keys that were already present and left as-is. */
+  readonly preserved: readonly string[]
+}
+
+/**
+ * Merge a flat record of `KEY -> value-template` into an existing `.env`
+ * file body. Existing keys are preserved verbatim; new keys are appended
+ * with their `${random:...}` placeholders resolved.
+ *
+ * Pure function: no I/O, no clock, no env access. Callers handle the
+ * file read + write + dry-run gating.
+ */
+export function mergeEnvFile(
+  existing: string,
+  vars: Readonly<Record<string, string>>,
+): EnvMergeResult {
+  const known = parseEnvKeys(existing)
+  const added: string[] = []
+  const preserved: string[] = []
+  const newLines: string[] = []
+
+  // Stable order: alphabetical by key, so re-runs produce reproducible diffs.
+  const keys = Object.keys(vars).sort()
+  for (const key of keys) {
+    if (known.has(key)) {
+      preserved.push(key)
+      continue
+    }
+    const template = vars[key] ?? ""
+    const value = resolveInterpolations(template)
+    newLines.push(`${key}=${formatValue(value)}`)
+    added.push(key)
+  }
+
+  if (newLines.length === 0) {
+    return { merged: existing, added, preserved }
+  }
+
+  // Existing body keeps its content verbatim. We strip *all* trailing
+  // newlines, then separate with exactly one blank line before the new
+  // block. Pre-empty files just get the block itself.
+  const trimmed = existing.replace(/(?:\r?\n)+$/g, "")
+  const header = "# Added by `hyper add`"
+  const block = `${header}\n${newLines.join("\n")}\n`
+  const merged = trimmed === "" ? block : `${trimmed}\n\n${block}`
+  return { merged, added, preserved }
+}
+
+/**
+ * Parse just the keys defined in an `.env` file body. Tolerates blank lines,
+ * `# comments`, `export FOO=…` prefixes, and quoted values. We do NOT need
+ * to evaluate the values — only know which keys are taken.
+ */
+function parseEnvKeys(body: string): Set<string> {
+  const keys = new Set<string>()
+  for (const rawLine of body.split(/\r?\n/)) {
+    const line = stripComment(rawLine).trim()
+    if (line === "") continue
+    const m = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line)
+    if (m?.[1]) keys.add(m[1])
+  }
+  return keys
+}
+
+function stripComment(line: string): string {
+  // A `#` only starts a comment when not inside quotes. Cheap heuristic:
+  // scan once, flipping a quote state. Good enough for the limited set of
+  // shapes a `.env.local` ever contains.
+  let inSingle = false
+  let inDouble = false
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i]
+    if (ch === "\\") {
+      i++
+      continue
+    }
+    if (!inDouble && ch === "'") inSingle = !inSingle
+    else if (!inSingle && ch === '"') inDouble = !inDouble
+    else if (!inSingle && !inDouble && ch === "#") return line.slice(0, i)
+  }
+  return line
+}
+
+const RANDOM_HEX_RE = /^\$\{random:hex:(\d+)\}$/
+const RANDOM_B64_RE = /^\$\{random:base64:(\d+)\}$/
+
+function resolveInterpolations(template: string): string {
+  // Whole-string interpolation only. Mid-string `${...}` is rare in
+  // .env.local conventions and ambiguous to escape; keep the contract small.
+  const hex = RANDOM_HEX_RE.exec(template)
+  if (hex?.[1]) {
+    const n = Math.max(1, Math.min(1024, Number.parseInt(hex[1], 10)))
+    return randomBytes(n).toString("hex")
+  }
+  const b64 = RANDOM_B64_RE.exec(template)
+  if (b64?.[1]) {
+    const n = Math.max(1, Math.min(1024, Number.parseInt(b64[1], 10)))
+    return randomBytes(n).toString("base64")
+  }
+  return template
+}
+
+/**
+ * Quote values that need it. Bare values (no whitespace, no `#`, no `$`,
+ * etc.) stay unquoted to match the dominant `.env` convention.
+ */
+function formatValue(value: string): string {
+  if (value === "") return ""
+  if (/^[A-Za-z0-9_./:+\-=]+$/.test(value)) return value
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`
+}

package/src/registry/index.ts

@@ -0,0 +1,18 @@
+/** Public surface for the registry client + applier. */
+
+export {
+  applyComponents,
+  readLocalFile,
+  resolveDeps,
+} from "./apply.ts"
+export type { ApplyOptions, ApplyOutcome } from "./apply.ts"
+export { createRegistryClient, RegistryError } from "./client.ts"
+export type { RegistryClient, RegistryClientOptions } from "./client.ts"
+export { resolveTarget, rewriteFile } from "./rewrite.ts"
+export { SNAPSHOT_COMPONENTS, SNAPSHOT_INDEX } from "./snapshot.ts"
+export type {
+  RegistryComponent,
+  RegistryFile,
+  RegistryIndex,
+  RegistryIndexEntry,
+} from "./types.ts"