create-cmp-cli 0.2.0

package/src/lib/project-doctor.mjs

@@ -0,0 +1,329 @@
+// Project-level diagnosis for `create-cmp doctor` — works on ANY Gradle/KMP
+// project with a gradle/libs.versions.toml, not only ones we scaffolded (this
+// is the ecosystem-funnel feature). Pure logic: the command layer gathers
+// filesystem/env inputs and passes them in, so every check unit-tests without
+// touching disk.
+
+import { parseVersions, parseProperties } from "./toml.mjs";
+import { lockstepViolation } from "./upgrade.mjs";
+import { nearestSet } from "./registry.mjs";
+
+export const GIB = 1024 ** 3;
+export const KONAN_WARN_BYTES = 10 * GIB;
+export const DISK_WARN_BYTES = 3 * GIB;
+
+/**
+ * @typedef {object} Finding
+ * @property {string} id
+ * @property {"ok"|"warn"|"fail"} level
+ * @property {string} title
+ * @property {string} detail
+ * @property {{auto:boolean, description:string}} [fix] auto = --fix can heal it
+ */
+
+/**
+ * Diagnose a project from pre-gathered inputs.
+ * @param {object} input
+ * @param {string|null} input.toml          gradle/libs.versions.toml content (null = absent)
+ * @param {string|null} input.gradleProperties gradle.properties content (null = absent)
+ * @param {string|null} input.localProperties  local.properties content (null = absent)
+ * @param {boolean|null} input.sdkDirExists  does local.properties sdk.dir point at a real dir (null = no sdk.dir line)
+ * @param {boolean} input.androidHomeSet     ANDROID_HOME/ANDROID_SDK_ROOT points at a real dir
+ * @param {boolean} input.hasIos             project has an iOS side (iosApp/ or iosMain sources)
+ * @param {object|null} input.registry       version-set registry (null = skip drift check)
+ * @param {number|null} input.konanBytes     ~/.konan size in bytes (null = unknown/absent)
+ * @param {number|null} input.freeDiskBytes  free disk space in bytes (null = unknown)
+ * @param {string[]|null} [input.inspectorHits] relative (posix) paths of Kotlin sources that
+ *        reference the live-inspector endpoint (`/inspect/` or `InspectorHttpServer`);
+ *        null = scan skipped (no composeApp sources), [] = project has no inspector code.
+ * @param {{catalog:string, theme:string}|null} [input.inspectorCatalog] the stamped
+ *        InspectorCatalog.kt content + concatenated theme sources (Tokens.kt/Theme.kt) for
+ *        the declared-token drift tripwire; null = skip.
+ * @returns {Finding[]}
+ */
+export function diagnoseProject(input) {
+  const findings = [];
+  const {
+    toml,
+    gradleProperties,
+    localProperties,
+    sdkDirExists,
+    androidHomeSet,
+    hasIos,
+    registry,
+    konanBytes,
+    freeDiskBytes,
+    inspectorHits = null,
+    inspectorCatalog = null,
+  } = input;
+
+  // --- version catalog ------------------------------------------------------
+  let versions = null;
+  if (toml === null) {
+    findings.push({
+      id: "version-catalog",
+      level: "warn",
+      title: "No gradle/libs.versions.toml",
+      detail:
+        "No version catalog found — version checks (kotlin↔ksp lockstep, drift vs proven-green sets) are skipped.",
+    });
+  } else {
+    versions = parseVersions(toml);
+    const values = Object.fromEntries([...versions].map(([k, v]) => [k, v.value]));
+
+    // kotlin ↔ ksp lockstep (the classic KMP build-killer).
+    if (values.kotlin && values.ksp) {
+      const violation = lockstepViolation(values);
+      if (violation) {
+        findings.push({
+          id: "kotlin-ksp-lockstep",
+          level: "fail",
+          title: "kotlin ↔ ksp lockstep VIOLATED",
+          detail: violation.replace(" Refusing to write a broken pairing.", ""),
+          fix: {
+            auto: false,
+            description: `Set ksp = "${values.kotlin}-<kspVersion>" in gradle/libs.versions.toml (or run \`create-cmp upgrade\` to move to a proven-green set).`,
+          },
+        });
+      } else {
+        findings.push({
+          id: "kotlin-ksp-lockstep",
+          level: "ok",
+          title: "kotlin ↔ ksp lockstep",
+          detail: `kotlin ${values.kotlin} / ksp ${values.ksp} agree.`,
+        });
+      }
+    }
+
+    // Known-bad combo: Room on Kotlin/Native (iOS) needs KSP2.
+    if (values.room && hasIos) {
+      const props = gradleProperties !== null ? parseProperties(gradleProperties) : new Map();
+      const ksp2 = props.get("ksp.useKSP2");
+      if (!ksp2 || ksp2.value !== "true") {
+        findings.push({
+          id: "ksp2-flag",
+          level: "fail",
+          title: "Room + iOS without ksp.useKSP2=true",
+          detail:
+            "Room's KSP processor on Kotlin/Native (iOS) requires KSP2. Without ksp.useKSP2=true the iOS " +
+            "build dies with `ClassNotFoundException: org.jetbrains.kotlin.cli.utilities.MainKt` (the KSP2/iOS catch-22).",
+          fix: { auto: true, description: "Add `ksp.useKSP2=true` to gradle.properties." },
+        });
+      } else {
+        findings.push({
+          id: "ksp2-flag",
+          level: "ok",
+          title: "ksp.useKSP2=true",
+          detail: "Room + iOS detected and KSP2 is enabled (the native catch-22 is defused).",
+        });
+      }
+    }
+
+    // Known-bad combo: Room < 2.7 has no Kotlin/Native support at all.
+    if (values.room && hasIos) {
+      const m = values.room.match(/^(\d+)\.(\d+)/);
+      if (m && (Number(m[1]) < 2 || (Number(m[1]) === 2 && Number(m[2]) < 7))) {
+        findings.push({
+          id: "room-native-support",
+          level: "fail",
+          title: `Room ${values.room} cannot target iOS`,
+          detail: "Room gained Kotlin Multiplatform (native) support in 2.7.0 — upgrade Room to use it from iOS code.",
+          fix: { auto: false, description: "Run `create-cmp upgrade` to move Room (and its lockstep partners) to a proven-green set." },
+        });
+      }
+    }
+
+    // Drift vs the nearest proven-green registry set.
+    if (registry) {
+      const near = nearestSet(registry, versions);
+      if (near) {
+        const drift = [];
+        for (const [k, v] of Object.entries(near.set.versions)) {
+          const cur = versions.get(k);
+          if (cur && cur.value !== v) drift.push(`${k} ${cur.value} → ${v}`);
+        }
+        if (drift.length === 0) {
+          findings.push({
+            id: "registry-drift",
+            level: "ok",
+            title: `Matches proven-green set ${near.set.id}`,
+            detail: "Every catalog version this set pins is at the proven-green value.",
+          });
+        } else {
+          findings.push({
+            id: "registry-drift",
+            level: "warn",
+            title: `Drift vs proven-green set ${near.set.id} (${drift.length} version${drift.length === 1 ? "" : "s"})`,
+            detail: drift.join(", "),
+            fix: { auto: false, description: `Run \`create-cmp upgrade --set ${near.set.id}\` to align (diff shown before anything is written).` },
+          });
+        }
+      }
+    }
+  }
+
+  // --- local.properties / SDK ------------------------------------------------
+  if (localProperties === null) {
+    findings.push({
+      id: "local-properties",
+      level: androidHomeSet ? "warn" : "fail",
+      title: "No local.properties",
+      detail: androidHomeSet
+        ? "local.properties is missing, but ANDROID_HOME/ANDROID_SDK_ROOT is set so Gradle can still resolve the SDK."
+        : "local.properties is missing and ANDROID_HOME/ANDROID_SDK_ROOT is not set — the Android build cannot locate an SDK.",
+      fix: {
+        auto: androidHomeSet,
+        description: androidHomeSet
+          ? "Write local.properties with sdk.dir from ANDROID_HOME."
+          : "Install the Android SDK (run `create-cmp doctor` toolchain bootstrap), then set ANDROID_HOME or write local.properties with sdk.dir=<sdk path>.",
+      },
+    });
+  } else if (sdkDirExists === null) {
+    findings.push({
+      id: "local-properties",
+      level: androidHomeSet ? "warn" : "fail",
+      title: "local.properties has no sdk.dir",
+      detail: "local.properties exists but declares no sdk.dir.",
+      fix: {
+        auto: androidHomeSet,
+        description: androidHomeSet
+          ? "Add sdk.dir from ANDROID_HOME to local.properties."
+          : "Add `sdk.dir=<android sdk path>` to local.properties or export ANDROID_HOME.",
+      },
+    });
+  } else if (sdkDirExists === false) {
+    findings.push({
+      id: "local-properties",
+      level: "fail",
+      title: "sdk.dir points at a missing directory",
+      detail: "local.properties sdk.dir does not exist on disk — Gradle will fail to resolve the Android SDK.",
+      fix: {
+        auto: androidHomeSet,
+        description: androidHomeSet
+          ? "Rewrite sdk.dir from ANDROID_HOME."
+          : "Fix sdk.dir in local.properties to point at a real Android SDK install.",
+      },
+    });
+  } else {
+    findings.push({
+      id: "local-properties",
+      level: "ok",
+      title: "local.properties sdk.dir",
+      detail: "sdk.dir exists and points at a real directory.",
+    });
+  }
+
+  // --- environment ------------------------------------------------------------
+  if (typeof konanBytes === "number") {
+    if (konanBytes > KONAN_WARN_BYTES) {
+      findings.push({
+        id: "konan-size",
+        level: "warn",
+        title: `~/.konan is ${formatBytes(konanBytes)}`,
+        detail:
+          "The Kotlin/Native toolchain cache has accumulated old compiler versions. Stale prebuilt toolchains are safe to remove.",
+        fix: { auto: false, description: "Run `create-cmp clean` to report and remove stale kotlin-native-prebuilt versions." },
+      });
+    } else {
+      findings.push({
+        id: "konan-size",
+        level: "ok",
+        title: `~/.konan is ${formatBytes(konanBytes)}`,
+        detail: "Within the expected footprint.",
+      });
+    }
+  }
+
+  if (typeof freeDiskBytes === "number") {
+    if (freeDiskBytes < DISK_WARN_BYTES) {
+      findings.push({
+        id: "disk-free",
+        level: "warn",
+        title: `Only ${formatBytes(freeDiskBytes)} free disk space`,
+        detail:
+          "KMP builds routinely fail mid-package with `No space left on device` below ~3 GB free. Free space before building.",
+        fix: { auto: false, description: "Run `create-cmp clean` (project build dirs + stale ~/.konan), and consider `rm -rf ~/.gradle/caches` manually." },
+      });
+    } else {
+      findings.push({
+        id: "disk-free",
+        level: "ok",
+        title: `${formatBytes(freeDiskBytes)} free disk space`,
+        detail: "Enough headroom for a KMP build (needs ≥3 GB).",
+      });
+    }
+  }
+
+  // --- live inspector placement (must never be reachable in release) ---------
+  // Static check by design: no network probe, no adb — the release guarantee is
+  // STRUCTURAL (inspector code lives only in the androidDebug source set), so we
+  // verify structure. inspectorHits are Kotlin sources referencing the inspector
+  // endpoint ("/inspect/" or InspectorHttpServer).
+  if (Array.isArray(inspectorHits) && inspectorHits.length > 0) {
+    const leaks = inspectorHits.filter((p) => !normalizePath(p).includes("/androidDebug/"));
+    if (leaks.length === 0) {
+      findings.push({
+        id: "inspector-placement",
+        level: "ok",
+        title: "Live inspector is debug-only",
+        detail:
+          "All inspector endpoint code lives in the androidDebug source set — structurally absent from release builds.",
+      });
+    } else {
+      findings.push({
+        id: "inspector-placement",
+        level: "warn",
+        title: "Inspector endpoint may be reachable in RELEASE builds",
+        detail:
+          `Inspector code referenced outside androidDebug: ${leaks.join(", ")}. ` +
+          "The live inspector server must never ship in release — keep the server, root registry " +
+          "and catalog in composeApp/src/androidDebug/kotlin only (the androidRelease twin must stay a no-op).",
+        fix: {
+          auto: false,
+          description:
+            "Move the offending code back to composeApp/src/androidDebug/kotlin (release keeps only the no-op startInspector() twin).",
+        },
+      });
+    }
+  }
+
+  // --- inspector catalog drift tripwire ---------------------------------------
+  // The design-system catalog is a hand-registry: a token ADDED to the theme but
+  // missing from InspectorCatalog.kt silently vanishes from /inspect/design-system.
+  if (inspectorCatalog && inspectorCatalog.catalog && inspectorCatalog.theme) {
+    const declared = [...inspectorCatalog.theme.matchAll(/^\s*val\s+([A-Z]\w*)\s*=/gm)].map((m) => m[1]);
+    const missing = declared.filter((name) => !inspectorCatalog.catalog.includes(`"${name}"`));
+    if (missing.length === 0) {
+      findings.push({
+        id: "inspector-catalog-drift",
+        level: "ok",
+        title: "Inspector catalog covers all declared tokens",
+        detail: `Every theme token (${declared.length}) appears in InspectorCatalog.kt.`,
+      });
+    } else {
+      findings.push({
+        id: "inspector-catalog-drift",
+        level: "warn",
+        title: `Inspector catalog is missing ${missing.length} declared token${missing.length === 1 ? "" : "s"}`,
+        detail:
+          `Declared in the theme but absent from InspectorCatalog.kt: ${missing.join(", ")}. ` +
+          "These tokens will not appear on /inspect/design-system, so drift on them goes uncaught.",
+        fix: { auto: false, description: "Add the missing entries to InspectorCatalog.kt (read from the real theme objects)." },
+      });
+    }
+  }
+
+  return findings;
+}
+
+function normalizePath(p) {
+  return String(p).split("\\").join("/");
+}
+
+/** Human-readable byte size (GB/MB). */
+export function formatBytes(bytes) {
+  if (bytes >= GIB) return `${(bytes / GIB).toFixed(1)} GB`;
+  const mib = 1024 ** 2;
+  if (bytes >= mib) return `${(bytes / mib).toFixed(0)} MB`;
+  return `${bytes} B`;
+}

package/src/lib/registry.mjs

@@ -0,0 +1,102 @@
+// Loader + helpers for the proven-green version-set registry
+// (src/versions/registry.json). Pure logic (nearest-set matching, validation)
+// is exported for unit testing.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REGISTRY_PATH = path.join(__dirname, "..", "versions", "registry.json");
+
+/**
+ * Load the registry JSON (or a custom one for tests).
+ * @param {string} [registryPath]
+ */
+export function loadRegistry(registryPath = REGISTRY_PATH) {
+  const registry = JSON.parse(fs.readFileSync(registryPath, "utf8"));
+  const errors = validateRegistry(registry);
+  if (errors.length) {
+    throw new Error(`Invalid version-set registry ${registryPath}:\n  - ${errors.join("\n  - ")}`);
+  }
+  return registry;
+}
+
+/**
+ * Structural validation of a registry object. Returns a list of problems
+ * (empty = valid). Also enforces the kotlin↔ksp lockstep INSIDE each set —
+ * a registry must never ship a broken pairing.
+ * @param {object} registry
+ * @returns {string[]}
+ */
+export function validateRegistry(registry) {
+  const errors = [];
+  if (!registry || typeof registry !== "object") return ["registry is not an object"];
+  if (!Array.isArray(registry.sets) || registry.sets.length === 0) {
+    return ["registry.sets must be a non-empty array"];
+  }
+  const seen = new Set();
+  registry.sets.forEach((set, i) => {
+    const where = `sets[${i}]${set && set.id ? ` (${set.id})` : ""}`;
+    if (!set || typeof set !== "object") {
+      errors.push(`${where}: not an object`);
+      return;
+    }
+    if (typeof set.id !== "string" || !set.id) errors.push(`${where}: missing string id`);
+    if (set.id && seen.has(set.id)) errors.push(`${where}: duplicate id`);
+    seen.add(set.id);
+    if (!set.versions || typeof set.versions !== "object" || Array.isArray(set.versions)) {
+      errors.push(`${where}: missing versions object`);
+      return;
+    }
+    for (const [k, v] of Object.entries(set.versions)) {
+      if (typeof v !== "string" || !v) errors.push(`${where}: versions.${k} must be a non-empty string`);
+    }
+    const { kotlin, ksp } = set.versions;
+    if (kotlin && ksp && !ksp.startsWith(`${kotlin}-`)) {
+      errors.push(`${where}: ksp "${ksp}" is not in lockstep with kotlin "${kotlin}" (must be "${kotlin}-<kspVersion>")`);
+    }
+    if (set.gradleProperties && typeof set.gradleProperties !== "object") {
+      errors.push(`${where}: gradleProperties must be an object`);
+    }
+    if (set.gradleWrapper && typeof set.gradleWrapper.distributionUrl !== "string") {
+      errors.push(`${where}: gradleWrapper.distributionUrl must be a string`);
+    }
+    if (set.notes && !Array.isArray(set.notes)) errors.push(`${where}: notes must be an array`);
+  });
+  return errors;
+}
+
+/** The default upgrade target: the newest (last) set. */
+export function latestSet(registry) {
+  return registry.sets[registry.sets.length - 1];
+}
+
+/** Look a set up by id; returns null when absent. */
+export function getSet(registry, id) {
+  return registry.sets.find((s) => s.id === id) || null;
+}
+
+/**
+ * The registry set that best matches a project's current [versions] values
+ * (most exact key+value matches; ties go to the NEWER set). Used by doctor to
+ * report drift against the closest known-green baseline.
+ * @param {object} registry
+ * @param {Map<string,{value:string}>|Record<string,string>} projectVersions
+ * @returns {{set:object, matches:number}|null}
+ */
+export function nearestSet(registry, projectVersions) {
+  const values =
+    projectVersions instanceof Map
+      ? Object.fromEntries([...projectVersions].map(([k, v]) => [k, v.value]))
+      : projectVersions;
+  let best = null;
+  for (const set of registry.sets) {
+    let matches = 0;
+    for (const [k, v] of Object.entries(set.versions)) {
+      if (values[k] === v) matches++;
+    }
+    if (!best || matches >= best.matches) best = { set, matches };
+  }
+  return best;
+}

package/src/lib/rename.mjs

@@ -0,0 +1,116 @@
+// Package-source directory rename: com/example/app → com/<org>/<app>.
+//
+// This is the classic scaffolder bug: a naive `mv com/example/app com/acme/app`
+// fails or corrupts when the new package SHARES a prefix with the old one
+// (e.g. com.example.app → com.example.demo keeps `com/example`), when the new
+// package is DEEPER or SHALLOWER, or when an intermediate dir already holds
+// other content. We handle it by:
+//   1. moving the leaf source tree to a unique temp location (atomic rename),
+//   2. removing now-empty old intermediate dirs,
+//   3. creating the new intermediate dirs,
+//   4. moving the temp tree into the final location.
+// Step (1)+(4) decouples source and destination so overlapping prefixes,
+// nesting changes, and re-runs (idempotency) all behave.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const OLD_PACKAGE_PATH = "com/example/app";
+
+/**
+ * Rename the package source dir under each root.
+ * @param {string} projectDir absolute path to the stamped project
+ * @param {string[]} packageSourceRoots e.g. ["composeApp/src/commonMain/kotlin", ...]
+ * @param {string} newPackagePath slash form, e.g. "com/acme/app"
+ * @param {object} [opts]
+ * @param {(msg:string)=>void} [opts.log]
+ * @returns {{moved: string[], skipped: string[]}}
+ */
+export function renamePackageDirs(projectDir, packageSourceRoots, newPackagePath, opts = {}) {
+  const log = opts.log || (() => {});
+  const moved = [];
+  const skipped = [];
+
+  const oldRel = OLD_PACKAGE_PATH;
+  const newRel = newPackagePath.split("/").filter(Boolean).join("/");
+
+  for (const root of packageSourceRoots) {
+    const rootAbs = path.join(projectDir, root);
+    const oldAbs = path.join(rootAbs, oldRel);
+    const newAbs = path.join(rootAbs, newRel);
+
+    if (!fs.existsSync(oldAbs) || !fs.statSync(oldAbs).isDirectory()) {
+      // Idempotent: if already renamed (or root absent) there's nothing to do.
+      skipped.push(root);
+      continue;
+    }
+
+    if (path.resolve(oldAbs) === path.resolve(newAbs)) {
+      // Same package — no rename needed.
+      skipped.push(root);
+      continue;
+    }
+
+    // 1. Move the leaf to a unique temp dir under the root.
+    const tmpAbs = path.join(rootAbs, `.__cmp_pkg_tmp_${process.pid}_${moved.length}`);
+    if (fs.existsSync(tmpAbs)) fs.rmSync(tmpAbs, { recursive: true, force: true });
+    fs.renameSync(oldAbs, tmpAbs);
+
+    // 2. Prune now-empty old intermediate dirs (com/example, com) up to root.
+    pruneEmptyDirsUp(rootAbs, path.dirname(oldAbs));
+
+    // 3. Ensure new parent exists.
+    fs.mkdirSync(path.dirname(newAbs), { recursive: true });
+
+    // 4. Move temp into place. If destination already exists (overlap edge),
+    //    merge contents rather than clobber.
+    if (fs.existsSync(newAbs)) {
+      mergeMove(tmpAbs, newAbs);
+      fs.rmSync(tmpAbs, { recursive: true, force: true });
+    } else {
+      fs.renameSync(tmpAbs, newAbs);
+    }
+
+    moved.push(root);
+    log(`  renamed ${root}/${oldRel} → ${root}/${newRel}`);
+  }
+
+  return { moved, skipped };
+}
+
+/**
+ * Remove empty directories walking up from `startDir` until `stopAtDir`
+ * (exclusive). Stops at the first non-empty directory.
+ */
+function pruneEmptyDirsUp(stopAtDir, startDir) {
+  let dir = startDir;
+  const stop = path.resolve(stopAtDir);
+  while (path.resolve(dir) !== stop && path.resolve(dir).startsWith(stop)) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir);
+    } catch {
+      break;
+    }
+    if (entries.length > 0) break;
+    fs.rmdirSync(dir);
+    dir = path.dirname(dir);
+  }
+}
+
+/**
+ * Recursively move src tree contents into an existing dest dir, merging.
+ */
+function mergeMove(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      mergeMove(s, d);
+    } else {
+      fs.mkdirSync(path.dirname(d), { recursive: true });
+      fs.renameSync(s, d);
+    }
+  }
+}

package/src/lib/schema.mjs

@@ -0,0 +1,123 @@
+// Tiny hand-rolled JSON-Schema (draft-07 subset) validator.
+// Supports exactly the keywords used by options.schema.json:
+//   type, required, properties, additionalProperties, enum, const,
+//   pattern, minLength, minItems, maxItems, items.
+// Returns { valid, errors: [{ path, message }] }.
+
+function typeOf(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value; // object | string | number | boolean
+}
+
+function matchesType(value, type) {
+  switch (type) {
+    case "object":
+      return value !== null && typeof value === "object" && !Array.isArray(value);
+    case "array":
+      return Array.isArray(value);
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number";
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    case "boolean":
+      return typeof value === "boolean";
+    case "null":
+      return value === null;
+    default:
+      return false;
+  }
+}
+
+function validateNode(value, schema, path, errors) {
+  if (!schema || typeof schema !== "object") return;
+
+  if (schema.type !== undefined) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!types.some((t) => matchesType(value, t))) {
+      errors.push({
+        path,
+        message: `expected type ${types.join(" | ")} but got ${typeOf(value)}`,
+      });
+      // Type mismatch — further keyword checks are unreliable; stop here.
+      return;
+    }
+  }
+
+  if (schema.const !== undefined && value !== schema.const) {
+    errors.push({ path, message: `must equal ${JSON.stringify(schema.const)}` });
+  }
+
+  if (schema.enum !== undefined && !schema.enum.includes(value)) {
+    errors.push({
+      path,
+      message: `must be one of ${schema.enum.map((v) => JSON.stringify(v)).join(", ")}`,
+    });
+  }
+
+  if (typeof value === "string") {
+    if (schema.minLength !== undefined && value.length < schema.minLength) {
+      errors.push({ path, message: `must be at least ${schema.minLength} characters` });
+    }
+    if (schema.pattern !== undefined) {
+      let re;
+      try {
+        re = new RegExp(schema.pattern);
+      } catch {
+        re = null;
+      }
+      if (re && !re.test(value)) {
+        errors.push({ path, message: `must match pattern ${schema.pattern}` });
+      }
+    }
+  }
+
+  if (Array.isArray(value)) {
+    if (schema.minItems !== undefined && value.length < schema.minItems) {
+      errors.push({ path, message: `must have at least ${schema.minItems} item(s)` });
+    }
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) {
+      errors.push({ path, message: `must have at most ${schema.maxItems} item(s)` });
+    }
+    if (schema.items) {
+      value.forEach((item, i) => {
+        validateNode(item, schema.items, `${path}[${i}]`, errors);
+      });
+    }
+  }
+
+  if (matchesType(value, "object")) {
+    if (Array.isArray(schema.required)) {
+      for (const key of schema.required) {
+        if (!(key in value)) {
+          errors.push({ path: path ? `${path}.${key}` : key, message: "is required" });
+        }
+      }
+    }
+    const props = schema.properties || {};
+    for (const [key, val] of Object.entries(value)) {
+      const childPath = path ? `${path}.${key}` : key;
+      if (props[key]) {
+        validateNode(val, props[key], childPath, errors);
+      } else if (schema.additionalProperties === false) {
+        errors.push({ path: childPath, message: "is not an allowed property" });
+      } else if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+        validateNode(val, schema.additionalProperties, childPath, errors);
+      }
+    }
+  }
+}
+
+export function validate(value, schema) {
+  const errors = [];
+  validateNode(value, schema, "", errors);
+  return { valid: errors.length === 0, errors };
+}
+
+export function formatErrors(errors) {
+  return errors
+    .map((e) => `  - ${e.path || "(root)"}: ${e.message}`)
+    .join("\n");
+}