Wix Headless Replatform

scripts/lib/component-registry.mjs

import { execFile } from "node:child_process";
import path from "node:path";
import { promisify } from "node:util";
import { access, copyFile, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
import { createHash } from "node:crypto";
import { fileURLToPath } from "node:url";
import { resolveCapabilityBinding, validateComponentCapabilities } from "./component-capabilities.mjs";

const execFileAsync = promisify(execFile);

export const REGISTRY_RUNTIME_CLASSES = new Set(["astro-native", "react-static", "react-island"]);

export async function loadApprovedRegistry(registryRoot = new URL("../../registry/", import.meta.url)) {
  const root = registryRoot instanceof URL ? registryRoot : path.resolve(registryRoot);
  const rootPath = root instanceof URL ? fileURLPath(root) : root;
  const read = async (relativePath) => JSON.parse(await readFile(root instanceof URL ? new URL(relativePath, root) : path.join(root, relativePath), "utf8"));
  const registry = await read("registry.json");
  const approvalsDir = root instanceof URL ? new URL("approvals/", root) : path.join(root, "approvals");
  const approvals = new Map();
  for (const file of await jsonFilesRecursive(approvalsDir)) {
    const approval = JSON.parse(await readFile(root instanceof URL ? new URL(`approvals/${file}`, root) : path.join(approvalsDir, file), "utf8"));
    if (approval.decision === "approved" && approval.revoked !== true) {
      approvals.set(`${approval.registryItemName}@${approval.registryItemRevision}`, approval);
    }
  }
  const items = [];
  const rejected = [];
  for (const item of registry.items || []) {
    if (!item.revision || !item.sourceHash) {
      rejected.push({ item: item.name, reason: "registry-entry-is-not-immutable" });
      continue;
    }
    const approval = approvals.get(`${item.name}@${item.revision}`);
    if (!approval) {
      rejected.push({ item: item.name, reason: "missing-human-approval" });
      continue;
    }
    if (!REGISTRY_RUNTIME_CLASSES.has(approval.runtimeClass)) {
      rejected.push({ item: item.name, reason: "invalid-runtime-class" });
      continue;
    }
    if (!approval.reviewer?.human || !approval.reviewer?.id) {
      rejected.push({ item: item.name, reason: "approval-is-not-attributed-to-a-human" });
      continue;
    }
    if (!approval.licenseRef || !approval.sourceHash) {
      rejected.push({ item: item.name, reason: "approval-evidence-incomplete" });
      continue;
    }
    if (approval.sourceHash !== item.sourceHash) {
      rejected.push({ item: item.name, reason: "approval-source-hash-mismatch" });
      continue;
    }
    if (!item.capabilitiesRef || !item.capabilitiesHash || !item.contractRef || !item.contractHash) {
      rejected.push({ item: item.name, reason: "runtime-contract-metadata-missing" });
      continue;
    }
    if (approval.capabilitiesRef !== item.capabilitiesRef || approval.capabilitiesHash !== item.capabilitiesHash
      || approval.contractRef !== item.contractRef || approval.contractHash !== item.contractHash) {
      rejected.push({ item: item.name, reason: "approval-runtime-contract-mismatch" });
      continue;
    }
    try {
      const capabilityBytes = await readFile(safeJoin(rootPath, item.capabilitiesRef, "capability manifest"));
      const capabilityHash = createHash("sha256").update(capabilityBytes).digest("hex");
      if (capabilityHash !== item.capabilitiesHash) {
        rejected.push({ item: item.name, reason: "capability-manifest-hash-mismatch" });
        continue;
      }
      const capabilities = JSON.parse(capabilityBytes);
      const validation = validateComponentCapabilities(capabilities, {
        name: item.name,
        revision: item.revision,
        contract: approval.contractKind,
      });
      if (!validation.ok) {
        rejected.push({ item: item.name, reason: "capability-manifest-invalid", details: validation.errors });
        continue;
      }
      const contractBytes = await readFile(safeJoin(rootPath, item.contractRef, "agent contract"));
      const contractHash = createHash("sha256").update(contractBytes).digest("hex");
      if (contractHash !== item.contractHash) {
        rejected.push({ item: item.name, reason: "agent-contract-hash-mismatch" });
        continue;
      }
      if (!contractBytes.toString("utf8").trim()) {
        rejected.push({ item: item.name, reason: "agent-contract-empty" });
        continue;
      }
      items.push({ ...item, approval, capabilities });
    } catch (error) {
      rejected.push({ item: item.name, reason: "capability-manifest-unreadable", details: [error.message] });
    }
  }
  return { registry: { ...registry, items }, rejected };
}

export function selectRegistryItem(contract, approvedRegistry) {
  const hardRequirements = new Set(contract.hardRequirements || []);
  const rejected = [...(approvedRegistry.rejected || [])];
  const candidates = [];
  for (const item of approvedRegistry.registry?.items || []) {
    const approval = item.approval;
    const reasons = [];
    if (approval.contractKind !== contract.kind) reasons.push("contract-kind-mismatch");
    if (contract.requiresClientRuntime && approval.runtimeClass === "react-static") reasons.push("interaction-requires-runtime-state");
    for (const requirement of hardRequirements) if (approval.qualityGates?.[requirement] !== true) reasons.push(`quality-gate:${requirement}`);
    const capability = resolveCapabilityBinding(item.capabilities, contract.capabilityRequirements || {});
    reasons.push(...capability.reasons);
    if (reasons.length) rejected.push({ item: `${item.name}@${item.revision}`, reason: reasons.join(",") });
    else candidates.push({ item, binding: capability.binding });
  }
  candidates.sort((a, b) => {
    const aDeps = Object.keys(a.item.dependencies || {}).length + (a.item.registryDependencies || []).length;
    const bDeps = Object.keys(b.item.dependencies || {}).length + (b.item.registryDependencies || []).length;
    return aDeps - bDeps || a.item.name.localeCompare(b.item.name);
  });
  if (!candidates.length) return { strategy: "bounded-custom", selected: null, rejected };
  const winner = candidates[0];
  return {
    strategy: "curated-registry",
    selected: {
      name: winner.item.name,
      type: winner.item.type,
      files: winner.item.files,
      runtimeClass: winner.item.approval.runtimeClass,
      sourceHash: winner.item.approval.sourceHash,
      approvalRef: winner.item.approval.approvalRef,
      revision: winner.item.revision,
      dependencies: winner.item.dependencies || {},
      capabilitiesRef: winner.item.capabilitiesRef,
      capabilitiesHash: winner.item.capabilitiesHash,
      contractRef: winner.item.contractRef,
      contractHash: winner.item.contractHash,
      binding: winner.binding,
    },
    rejected: [...rejected, ...candidates.slice(1).map(({ item }) => ({ item: `${item.name}@${item.revision}`, reason: "higher-adaptation-or-dependency-cost" }))],
  };
}

// Installs the project's dependencies with the package manager its lockfile names (npm when none),
// so the lockfile and node_modules match the package.json a registry install just rewrote.
export async function installProjectDependencies({ outputDir }) {
  const root = path.resolve(outputDir);
  const exists = async (name) => { try { await access(path.join(root, name)); return true; } catch { return false; } };
  const runner = await exists("pnpm-lock.yaml") ? ["pnpm", "install"]
    : await exists("yarn.lock") ? ["yarn", "install"]
      : ["npm", "install", "--no-audit", "--no-fund"];
  const [command, ...args] = runner;
  const options = { cwd: root, maxBuffer: 16 * 1024 * 1024 };
  try {
    await execFileAsync(command, args, options);
    return { packageManager: command };
  } catch (error) {
    // Same fallback create-wix-project.mjs uses: a Corepack-only Node setup has no bare yarn/pnpm.
    if (error?.code !== "ENOENT" || command === "npm") throw error;
    await execFileAsync("corepack", [command, ...args], options);
    return { packageManager: `corepack ${command}` };
  }
}

export async function installRegistrySelection({ selection, ...options }) {
  const { installations } = await installRegistrySelections({ selections: [selection], ...options });
  return installations[0];
}

// Installs every curated selection of a page in one pass: each distinct item's files are copied
// once, their exact dependencies are merged into package.json once, and the package manager runs
// once. Installing per unit made a page with N approved buttons run N serial full installs.
// Returns one installation record per selection, in order.
export async function installRegistrySelections({ selections = [], outputDir, registryRoot = new URL("../../registry/", import.meta.url), installDependencies = installProjectDependencies }) {
  const root = registryRoot instanceof URL ? fileURLPath(registryRoot) : path.resolve(registryRoot);
  const destinationRoot = path.resolve(outputDir);
  const items = new Map();
  const dependencies = {};
  const dependencyOwner = {};
  for (const selection of selections) {
    if (!selection || selection.strategy !== "curated-registry" || !selection.selected) continue;
    const selected = selection.selected;
    const key = `${selected.name}@${selected.revision}`;
    if (items.has(key)) continue;
    const installed = [];
    for (const file of selected.files || []) {
      if (!file.path || !file.target || !file.sha256) throw new Error(`Registry file metadata is incomplete for ${selected.name}`);
      const source = safeJoin(root, file.path, "registry source");
      const destination = safeJoin(destinationRoot, file.target, "registry target");
      const sourceBytes = await readFile(source);
      const actualHash = createHash("sha256").update(sourceBytes).digest("hex");
      if (actualHash !== file.sha256) throw new Error(`Registry source hash mismatch for ${file.path}: expected ${file.sha256}, got ${actualHash}`);
      await mkdir(path.dirname(destination), { recursive: true });
      await copyFile(source, destination);
      installed.push({ source: file.path, target: file.target, sha256: actualHash });
    }
    const itemDependencies = selected.dependencies || {};
    if (Array.isArray(itemDependencies)) throw new Error(`Registry dependencies must be exact name/version pairs for ${selected.name}`);
    for (const [name, version] of Object.entries(itemDependencies)) {
      if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(String(version))) throw new Error(`Registry dependency ${name} must use an exact version, got ${version}`);
      if (dependencies[name] !== undefined && dependencies[name] !== String(version)) {
        throw new Error(`Registry dependency ${name} is pinned to ${dependencies[name]} by ${dependencyOwner[name]} and ${version} by ${key}; approved items must agree`);
      }
      dependencies[name] = String(version);
      dependencyOwner[name] = key;
    }
    items.set(key, { selected, installed, dependencies: itemDependencies });
  }
  let dependencyInstall = { ok: true, skipped: "no-dependencies" };
  if (Object.keys(dependencies).length) {
    const packagePath = path.join(destinationRoot, "package.json");
    const packageJson = JSON.parse(await readFile(packagePath, "utf8"));
    packageJson.dependencies = { ...(packageJson.dependencies || {}), ...dependencies };
    packageJson.dependencies = Object.fromEntries(Object.entries(packageJson.dependencies).sort(([a], [b]) => a.localeCompare(b)));
    await writeFile(packagePath, `${JSON.stringify(packageJson, null, 2)}\n`);
    // Rewriting package.json alone leaves the generated component importing packages that are not
    // installed and a lockfile that has drifted; install before returning so the next build works.
    try {
      dependencyInstall = { ok: true, ...(await installDependencies({ outputDir: destinationRoot, dependencies })) };
    } catch (error) {
      throw new Error(`Installing registry dependencies for ${[...items.values()].map((item) => item.selected.name).join(", ")} failed: ${error.message}`);
    }
  }
  const astroConfiguration = [...items.values()].some((item) => item.selected.runtimeClass?.startsWith("react-"))
    ? await ensureAstroReactIntegration(destinationRoot)
    : { changed: false, reason: "not-required" };
  const installations = selections.map((selection) => {
    const item = selection?.strategy === "curated-registry" && selection.selected ? items.get(`${selection.selected.name}@${selection.selected.revision}`) : null;
    if (!item) return { strategy: "bounded-custom", installed: [] };
    const { selected } = item;
    return {
      strategy: "curated-registry",
      item: selected.name,
      revision: selected.revision,
      sourceHash: selected.sourceHash,
      capabilitiesRef: selected.capabilitiesRef,
      capabilitiesHash: selected.capabilitiesHash,
      contractRef: selected.contractRef,
      contractHash: selected.contractHash,
      binding: selection.selected.binding,
      approvalRef: selected.approvalRef,
      installed: item.installed,
      dependencies: item.dependencies,
      dependencyInstall,
      astroConfiguration,
    };
  });
  return { installations, dependencyInstall, astroConfiguration };
}

async function ensureAstroReactIntegration(destinationRoot) {
  const configPath = path.join(destinationRoot, "astro.config.mjs");
  let source;
  try { source = await readFile(configPath, "utf8"); }
  catch (error) {
    if (error?.code === "ENOENT") throw new Error("React registry installation requires an existing astro.config.mjs");
    throw error;
  }
  const reactImport = source.match(/import\s+([A-Za-z_$][\w$]*)\s+from\s+["']@astrojs\/react["']/);
  const reactIdentifier = reactImport?.[1] || "react";
  const hasImport = Boolean(reactImport);
  const hasIntegration = new RegExp(`integrations\\s*:\\s*\\[[^\\]]*\\b${reactIdentifier}\\s*\\(`, "s").test(source);
  if (hasImport && hasIntegration) return { changed: false, config: "astro.config.mjs" };
  if (!/defineConfig\s*\(\s*\{/.test(source)) {
    throw new Error("Cannot safely add the React integration: astro.config.mjs must export defineConfig({...})");
  }
  let next = source;
  if (!hasImport) next = `import react from "@astrojs/react";\n${next}`;
  if (!hasIntegration) {
    if (/integrations\s*:\s*\[/.test(next)) {
      next = next.replace(/integrations\s*:\s*\[/, (match) => `${match}${reactIdentifier}(), `);
    } else {
      next = next.replace(/defineConfig\s*\(\s*\{/, (match) => `${match}\n  integrations: [${reactIdentifier}()],`);
    }
  }
  await writeFile(configPath, next);
  return {
    changed: true,
    config: "astro.config.mjs",
    sha256: createHash("sha256").update(next).digest("hex"),
  };
}

async function jsonFilesRecursive(dir, prefix = "") {
  try {
    const entries = await readdir(dir instanceof URL ? dir : path.resolve(dir), { withFileTypes: true });
    const files = [];
    for (const entry of entries) {
      const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
      if (entry.isFile() && entry.name.endsWith(".json")) files.push(relative);
      if (entry.isDirectory()) {
        const child = dir instanceof URL ? new URL(`${entry.name}/`, dir) : path.join(dir, entry.name);
        files.push(...await jsonFilesRecursive(child, relative));
      }
    }
    return files.sort();
  } catch (error) {
    if (error?.code === "ENOENT") return [];
    throw error;
  }
}

function safeJoin(root, relativePath, label) {
  if (path.isAbsolute(relativePath) || relativePath.split(/[\\/]+/).includes("..")) throw new Error(`${label} must be a safe relative path: ${relativePath}`);
  const normalizedRoot = path.resolve(root);
  const target = path.resolve(normalizedRoot, relativePath);
  if (target !== normalizedRoot && !target.startsWith(`${normalizedRoot}${path.sep}`)) throw new Error(`${label} escapes its root: ${relativePath}`);
  return target;
}

function fileURLPath(value) {
  if (value.protocol !== "file:") throw new Error(`Registry URL must use file: ${value}`);
  return fileURLToPath(value);
}