mlola-ui 1.0.0

package/src/doctor.js

@@ -0,0 +1,156 @@
+import fs from "node:fs";
+import path from "node:path";
+import { interpolateTarget, loadConfig, targetRoot } from "./config.js";
+import { createTransformContext, expectedFile } from "./installer.js";
+import { loadRegistry, readJson, sha256, sourcePath } from "./registry.js";
+
+const FORBIDDEN_DEPENDENCIES = [
+  "clsx",
+  "tailwind-merge",
+  "tailwindcss",
+  "@tailwindcss/postcss",
+  "lucide-react",
+];
+
+function finding(level, message) {
+  return { level, message };
+}
+
+function projectDependencies(cwd) {
+  const filename = path.join(cwd, "package.json");
+  if (!fs.existsSync(filename)) return {};
+  const manifest = readJson(filename);
+  return {
+    ...manifest.dependencies,
+    ...manifest.devDependencies,
+    ...manifest.peerDependencies,
+  };
+}
+
+function projectContains(cwd, pattern) {
+  const roots = ["app", "src", "pages"]
+    .map((directory) => path.join(cwd, directory))
+    .filter((directory) => fs.existsSync(directory));
+  let inspected = 0;
+  const queue = [...roots];
+  while (queue.length && inspected < 500) {
+    const current = queue.shift();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      const filename = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        queue.push(filename);
+      } else if (/\.(?:tsx?|jsx?|html)$/.test(entry.name)) {
+        inspected += 1;
+        if (pattern.test(fs.readFileSync(filename, "utf8"))) return true;
+      }
+    }
+  }
+  return false;
+}
+
+export function runDoctor(cwd) {
+  const findings = [];
+  let config;
+  let registry;
+  try {
+    config = loadConfig(cwd);
+    findings.push(finding("pass", "mlola.config.json is valid"));
+  } catch (error) {
+    findings.push(finding("error", error.message));
+    return findings;
+  }
+  try {
+    registry = loadRegistry();
+    const seen = new Set();
+    for (const item of registry.items) {
+      for (const file of item.files) {
+        if (seen.has(file.path)) continue;
+        seen.add(file.path);
+        const filename = sourcePath(file.path);
+        if (!fs.existsSync(filename) || sha256(fs.readFileSync(filename)) !== file.integrity) {
+          throw new Error(`Integrity mismatch for ${file.path}`);
+        }
+      }
+    }
+    findings.push(finding("pass", `bundled Registry v2 snapshot is valid (${registry.items.length} items)`));
+  } catch (error) {
+    findings.push(finding("error", error.message));
+    return findings;
+  }
+
+  const dependencies = projectDependencies(cwd);
+  const forbidden = FORBIDDEN_DEPENDENCIES.filter((name) => dependencies[name]);
+  if (forbidden.length) {
+    findings.push(finding("warn", `forbidden styling dependencies declared: ${forbidden.join(", ")}`));
+  } else {
+    findings.push(finding("pass", "no forbidden styling dependencies are declared"));
+  }
+
+  const requiredEngines = new Set();
+  for (const item of registry.items) {
+    for (const name of Object.keys(item.engineDependencies)) requiredEngines.add(name);
+  }
+  const missingEngines = [...requiredEngines].filter((name) => !dependencies[name]);
+  if (missingEngines.length) {
+    findings.push(
+      finding("warn", `engine packages used by the registry are not declared: ${missingEngines.join(", ")}`),
+    );
+  } else if (requiredEngines.size) {
+    findings.push(finding("pass", "registry engine packages are declared"));
+  }
+  if (!dependencies.react) findings.push(finding("warn", "React is not declared in package.json"));
+  if (!dependencies["react-dom"]) findings.push(finding("warn", "ReactDOM is not declared in package.json"));
+
+  const styleFile = path.join(cwd, targetRoot(config, "styles"), "mlola", "index.css");
+  if (!fs.existsSync(styleFile)) {
+    findings.push(finding("warn", `missing ${path.relative(cwd, styleFile)}; rerun init`));
+  } else {
+    const css = fs.readFileSync(styleFile, "utf8");
+    if (!css.includes(config.engine.engine ?? "@mlola-ui/engine") && !css.includes(config.engine.tokens)) {
+      findings.push(finding("warn", "Mlola stylesheet does not import the configured engine"));
+    } else {
+      findings.push(finding("pass", "Mlola engine stylesheet import is present"));
+    }
+  }
+
+  if (projectContains(cwd, /\bdata-theme\s*=/)) {
+    findings.push(finding("pass", "data-theme is present in application source"));
+  } else if (projectContains(cwd, /\bdata-skin\s*=/)) {
+    findings.push(finding("warn", "data-skin is legacy; set data-theme on the document root"));
+  } else {
+    findings.push(
+      finding("warn", `set data-theme="${config.theme}" on <html> or an application container`),
+    );
+  }
+
+  const context = createTransformContext(registry, config);
+  let installedItems = 0;
+  let modifiedFiles = 0;
+  for (const item of registry.items) {
+    const primary = item.files.find((file) =>
+      file.path.endsWith(`/${item.name}/${item.name}.tsx`),
+    );
+    if (!primary) continue;
+    const primaryDestination = path.join(cwd, interpolateTarget(primary.target, config));
+    if (!fs.existsSync(primaryDestination)) continue;
+    installedItems += 1;
+    for (const file of item.files) {
+      const destination = path.join(cwd, interpolateTarget(file.target, config));
+      if (!fs.existsSync(destination) || fs.readFileSync(destination, "utf8") !== expectedFile(file, context)) {
+        modifiedFiles += 1;
+      }
+    }
+  }
+  if (modifiedFiles) {
+    findings.push(
+      finding(
+        "warn",
+        `${modifiedFiles} installed registry file(s) differ from the deterministic snapshot`,
+      ),
+    );
+  } else {
+    findings.push(finding("pass", `${installedItems} installed item(s) match the registry snapshot`));
+  }
+  return findings;
+}

package/src/installer.js

@@ -0,0 +1,131 @@
+import fs from "node:fs";
+import path from "node:path";
+import { interpolateTarget } from "./config.js";
+import { sha256, sourcePath } from "./registry.js";
+
+const SOURCE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+const IMPORT_PATTERN =
+  /(?:import|export)\s+(?:type\s+)?(?:[\s\S]*?\s+from\s+)?["']([^"']+)["']|import\(\s*["']([^"']+)["']\s*\)/g;
+
+function importsFrom(content) {
+  return [...content.matchAll(IMPORT_PATTERN)].map((match) => match[1] ?? match[2]);
+}
+
+function sourceImportCandidates(fromSource, specifier) {
+  const unresolved = path.posix.normalize(path.posix.join(path.posix.dirname(fromSource), specifier));
+  return [
+    unresolved,
+    ...SOURCE_EXTENSIONS.map((extension) => `${unresolved}${extension}`),
+    ...SOURCE_EXTENSIONS.map((extension) => `${unresolved}/index${extension}`),
+  ];
+}
+
+function withoutSourceExtension(value) {
+  const extension = SOURCE_EXTENSIONS.find((candidate) => value.endsWith(candidate));
+  const clean = extension ? value.slice(0, -extension.length) : value;
+  return clean.endsWith("/index") ? clean.slice(0, -"/index".length) : clean;
+}
+
+export function createTransformContext(registry, config) {
+  const filesBySource = new Map();
+  for (const item of registry.items) {
+    for (const file of item.files) filesBySource.set(file.path, file);
+  }
+  return { filesBySource, config };
+}
+
+export function transformSource(content, sourceFile, context) {
+  const replacements = new Map();
+  for (const specifier of importsFrom(content)) {
+    if (specifier.startsWith(".")) {
+      const importedSource = sourceImportCandidates(sourceFile.path, specifier).find((candidate) =>
+        context.filesBySource.has(candidate),
+      );
+      if (importedSource) {
+        const importedFile = context.filesBySource.get(importedSource);
+        replacements.set(
+          specifier,
+          withoutSourceExtension(interpolateTarget(importedFile.target, context.config, "import")),
+        );
+      }
+      continue;
+    }
+
+    if (specifier.startsWith("@mlola-ui/")) {
+      const [, packageName, ...subpath] = specifier.split("/");
+      const configured = context.config.engine?.[packageName];
+      if (configured) {
+        replacements.set(specifier, [configured, ...subpath].join("/"));
+      }
+    }
+  }
+
+  if (!replacements.size) return content;
+  return content.replace(/(["'])([^"']+)\1/g, (match, quote, specifier) => {
+    const replacement = replacements.get(specifier);
+    return replacement ? `${quote}${replacement}${quote}` : match;
+  });
+}
+
+export function expectedFile(file, context) {
+  // Pro files arrive with their content, already checked against their integrity.
+  if (typeof file.content === "string") {
+    if (sha256(file.content) !== file.integrity) throw new Error(`Pro source failed integrity validation: ${file.path}`);
+    return transformSource(file.content, file, context);
+  }
+  const bundledSource = sourcePath(file.path);
+  if (!fs.existsSync(bundledSource)) {
+    throw new Error(`Bundled source is missing for ${file.path}. Reinstall mlola-ui.`);
+  }
+  const original = fs.readFileSync(bundledSource, "utf8");
+  if (sha256(original) !== file.integrity) {
+    throw new Error(`Bundled source failed integrity validation: ${file.path}`);
+  }
+  return transformSource(original, file, context);
+}
+
+export function installItems(cwd, registry, items, config, { overwrite = false } = {}) {
+  const context = createTransformContext(registry, config);
+  const written = [];
+  const unchanged = [];
+  const conflicts = [];
+  const seenDestinations = new Set();
+
+  for (const item of items) {
+    for (const file of item.files) {
+      const relativeDestination = interpolateTarget(file.target, config);
+      const destination = path.resolve(cwd, relativeDestination);
+      if (destination !== cwd && !destination.startsWith(`${path.resolve(cwd)}${path.sep}`)) {
+        throw new Error(`Refusing to write outside the project: ${relativeDestination}`);
+      }
+      if (seenDestinations.has(destination)) continue;
+      seenDestinations.add(destination);
+
+      const content = expectedFile(file, context);
+      if (fs.existsSync(destination)) {
+        if (fs.readFileSync(destination, "utf8") === content) {
+          unchanged.push(relativeDestination);
+          continue;
+        }
+        if (!overwrite) {
+          conflicts.push(relativeDestination);
+          continue;
+        }
+      }
+      fs.mkdirSync(path.dirname(destination), { recursive: true });
+      fs.writeFileSync(destination, content);
+      written.push(relativeDestination);
+    }
+  }
+  return { written, unchanged, conflicts };
+}
+
+export function collectEngineDependencies(items) {
+  const dependencies = new Map();
+  for (const item of items) {
+    for (const [name, range] of Object.entries(item.engineDependencies)) {
+      dependencies.set(name, range);
+    }
+  }
+  return dependencies;
+}

package/src/pro.js

@@ -0,0 +1,160 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { targetRoot } from "./config.js";
+import { sha256 } from "./registry.js";
+
+/**
+ * Mlola Pro in the CLI.
+ *
+ * Pro source is never bundled. `mlola-ui login <token>` stores a token made at
+ * /account (readable by the current user only); `add` sends it to the Pro
+ * endpoint, which returns the items and their Pro dependencies stamped with
+ * the licence. In CI, `MLOLA_PRO_TOKEN` takes the place of a login.
+ */
+
+export const DEFAULT_HOST = "https://ui.mlola.com";
+const TOKEN_PATTERN = /^mlp_[0-9a-z]{40}$/;
+
+export function hostFrom(env, explicit) {
+  return (explicit ?? env.MLOLA_STUDIO_URL ?? DEFAULT_HOST).replace(/\/$/, "");
+}
+
+export function credentialsPath(env) {
+  const base = env.MLOLA_CONFIG_DIR ?? path.join(env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config"), "mlola-ui");
+  return path.join(base, "credentials.json");
+}
+
+export function readCredentials(env) {
+  if (env.MLOLA_PRO_TOKEN) return { token: env.MLOLA_PRO_TOKEN.trim(), host: undefined, from: "MLOLA_PRO_TOKEN" };
+  const filename = credentialsPath(env);
+  if (!fs.existsSync(filename)) return null;
+  try {
+    const saved = JSON.parse(fs.readFileSync(filename, "utf8"));
+    return typeof saved.token === "string" ? { token: saved.token, host: saved.host, from: filename } : null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveCredentials(env, token, host) {
+  const filename = credentialsPath(env);
+  fs.mkdirSync(path.dirname(filename), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(filename, `${JSON.stringify({ token, host }, null, 2)}\n`, { mode: 0o600 });
+  fs.chmodSync(filename, 0o600);
+  return filename;
+}
+
+export function clearCredentials(env) {
+  const filename = credentialsPath(env);
+  if (!fs.existsSync(filename)) return false;
+  fs.rmSync(filename);
+  return true;
+}
+
+async function request(fetcher, url, token, init = {}) {
+  let response;
+  try {
+    response = await fetcher(url, { ...init, headers: { ...init.headers, authorization: `Bearer ${token}` } });
+  } catch (error) {
+    throw new Error(`Could not reach ${new URL(url).origin}: ${error.message}`);
+  }
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) throw new Error(payload.error ?? `The Pro service answered ${response.status}.`);
+  return payload;
+}
+
+/** Checks a token with the service before it is saved, so a typo fails at login rather than at add. */
+export async function verifyToken(host, token, fetcher) {
+  if (!TOKEN_PATTERN.test(token)) throw new Error("That is not a Mlola Pro token. Tokens start with mlp_; create one at /account.");
+  return request(fetcher, `${host}/api/pro/licence`, token);
+}
+
+/**
+ * Fetches Pro items, then checks every file and stylesheet against the
+ * integrity the service sent with it.
+ */
+export async function fetchProItems(host, token, names, fetcher) {
+  const payload = await request(fetcher, `${host}/api/pro/items`, token, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ names }),
+  });
+  if (!Array.isArray(payload.items)) throw new Error("The Pro service sent an unexpected response.");
+  for (const item of payload.items) {
+    for (const file of item.files ?? []) {
+      if (typeof file.content !== "string" || sha256(file.content) !== file.integrity) {
+        throw new Error(`Pro source failed integrity validation: ${file.path}`);
+      }
+    }
+  }
+  const styles = Array.isArray(payload.styles) ? payload.styles : [];
+  for (const style of styles) {
+    if (!/^[a-z][a-z0-9-]*$/.test(style.name) || sha256(style.css) !== style.integrity) {
+      throw new Error(`Pro stylesheet failed integrity validation: ${style.name}`);
+    }
+  }
+  const guide = payload.guide && typeof payload.guide.content === "string" ? payload.guide : null;
+  if (guide && sha256(guide.content) !== guide.integrity) throw new Error("The Pro agent guide failed integrity validation.");
+  return { items: payload.items, styles, guide };
+}
+
+export const GUIDE_FILENAME = "mlola-pro.agents.md";
+
+/** Pro's guide for coding agents lands at the project root, beside AGENTS.md. */
+export function writeProGuide(cwd, guide, { overwrite = false } = {}) {
+  if (!guide) return { status: "none" };
+  const filename = path.join(cwd, GUIDE_FILENAME);
+  if (fs.existsSync(filename)) {
+    const current = fs.readFileSync(filename, "utf8");
+    if (current === guide.content) return { status: "unchanged" };
+    if (!overwrite) return { status: "conflict" };
+  }
+  fs.writeFileSync(filename, guide.content);
+  return { status: "written" };
+}
+
+/**
+ * Pro stylesheets land in <styles>/mlola-pro/<name>.css, gathered by
+ * <styles>/mlola-pro.css, which the project imports once after the engine.
+ */
+export function writeProStyles(cwd, config, styles, { overwrite = false } = {}) {
+  const root = targetRoot(config, "styles");
+  const written = [];
+  const unchanged = [];
+  const conflicts = [];
+  for (const style of styles) {
+    const relative = path.join(root, "mlola-pro", `${style.name}.css`);
+    const filename = path.join(cwd, relative);
+    if (fs.existsSync(filename)) {
+      if (fs.readFileSync(filename, "utf8") === style.css) {
+        unchanged.push(relative);
+        continue;
+      }
+      if (!overwrite) {
+        conflicts.push(relative);
+        continue;
+      }
+    }
+    fs.mkdirSync(path.dirname(filename), { recursive: true });
+    fs.writeFileSync(filename, style.css);
+    written.push(relative);
+  }
+
+  const indexRelative = path.join(root, "mlola-pro.css");
+  const indexFile = path.join(cwd, indexRelative);
+  let index = fs.existsSync(indexFile) ? fs.readFileSync(indexFile, "utf8") : "/* Mlola Pro styles. Import this file once, after the engine stylesheet. */\n";
+  let changed = false;
+  for (const style of styles) {
+    const line = `@import "./mlola-pro/${style.name}.css";`;
+    if (!index.includes(line)) {
+      index += `${line}\n`;
+      changed = true;
+    }
+  }
+  if (changed) {
+    fs.mkdirSync(path.dirname(indexFile), { recursive: true });
+    fs.writeFileSync(indexFile, index);
+  }
+  return { written, unchanged, conflicts, index: styles.length ? indexRelative : null };
+}

package/src/registry.js

@@ -0,0 +1,91 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const CLI_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+export const BUNDLED_REGISTRY_ROOT = path.join(CLI_ROOT, "registry");
+
+export function sha256(content) {
+  return `sha256-${createHash("sha256").update(content).digest("base64")}`;
+}
+
+export function readJson(filename) {
+  return JSON.parse(fs.readFileSync(filename, "utf8"));
+}
+
+export function loadRegistry() {
+  const filename = path.join(BUNDLED_REGISTRY_ROOT, "index.json");
+  if (!fs.existsSync(filename)) {
+    throw new Error(
+      `Bundled registry is missing at ${filename}. Reinstall mlola-ui; this package is incomplete.`,
+    );
+  }
+  const registry = readJson(filename);
+  if (registry.schemaVersion !== 2 || !Array.isArray(registry.items)) {
+    throw new Error("Bundled registry is not a valid Registry v2 snapshot.");
+  }
+  return registry;
+}
+
+/** Names in the commercial catalog, so the CLI can say so instead of "unknown". */
+export function loadCatalogNames() {
+  const filename = path.join(BUNDLED_REGISTRY_ROOT, "catalog.json");
+  if (!fs.existsSync(filename)) return new Set();
+  const catalog = readJson(filename);
+  return new Set([
+    ...(catalog.components ?? []),
+    ...(catalog.blocks ?? []),
+    ...(catalog.pages ?? []),
+    ...(catalog.templates ?? []),
+  ]);
+}
+
+export function sourcePath(relativePath) {
+  const filename = path.resolve(BUNDLED_REGISTRY_ROOT, "source", relativePath);
+  const sourceRoot = path.resolve(BUNDLED_REGISTRY_ROOT, "source");
+  if (filename !== sourceRoot && !filename.startsWith(`${sourceRoot}${path.sep}`)) {
+    throw new Error(`Unsafe registry source path: ${relativePath}`);
+  }
+  return filename;
+}
+
+export function itemMap(registry) {
+  return new Map(registry.items.map((item) => [item.name, item]));
+}
+
+export function resolveItems(registry, requestedNames, catalogNames = loadCatalogNames()) {
+  const byName = itemMap(registry);
+  const ordered = [];
+  const visited = new Set();
+  const visiting = new Set();
+
+  function visit(name, chain = []) {
+    const item = byName.get(name);
+    if (!item) {
+      if (catalogNames.has(name)) {
+        throw new Error(
+          `"${name}" is part of Mlola Pro, not the free registry. ` +
+            `See https://ui.mlola.com/pricing to get Pro.`,
+        );
+      }
+      const suggestions = [...byName.keys()]
+        .filter((candidate) => candidate.includes(name) || name.includes(candidate))
+        .slice(0, 4);
+      const hint = suggestions.length ? ` Did you mean ${suggestions.join(", ")}?` : "";
+      throw new Error(`Registry item "${name}" does not exist.${hint}`);
+    }
+    if (visiting.has(name)) {
+      throw new Error(`Registry dependency cycle: ${[...chain, name].join(" -> ")}`);
+    }
+    if (visited.has(name)) return;
+    visiting.add(name);
+    for (const dependency of item.registryDependencies) visit(dependency, [...chain, name]);
+    visiting.delete(name);
+    visited.add(name);
+    ordered.push(item);
+  }
+
+  for (const name of requestedNames) visit(name);
+  return ordered;
+}

package/src/theme-pull.js

@@ -0,0 +1,91 @@
+import fs from "node:fs";
+import path from "node:path";
+import { DEFAULT_CONFIG, loadConfig, targetRoot } from "./config.js";
+
+/**
+ * `mlola-ui theme pull <id | url>`: copy a Studio theme into the project.
+ *
+ * Writes the spec to mlola.theme.json (the record, and what the engine build
+ * reads) and the rendered stylesheet to <styles>/mlola/theme.css, imported
+ * from index.css. The CSS is fetched pinned to the exact version the spec
+ * came from, so the two files always agree.
+ */
+
+export const DEFAULT_STUDIO_URL = "https://ui.mlola.com";
+const THEME_ID = /^th-[0-9a-z]{12}$/;
+
+/** Accepts `th-…`, `th-…@3`, or a hosted URL such as https://host/t/th-….css. */
+export function parseThemeReference(reference, host = DEFAULT_STUDIO_URL) {
+  if (!reference) throw new Error("Name the theme to pull: mlola-ui theme pull <theme-id | url>");
+  let base = host;
+  let token = reference;
+  if (/^https?:\/\//.test(reference)) {
+    const url = new URL(reference);
+    const match = /\/t\/([^/]+)$/.exec(url.pathname);
+    if (!match) throw new Error(`Not a hosted theme URL: ${reference}`);
+    base = url.origin;
+    token = match[1];
+  }
+  const match = /^(th-[0-9a-z]{12})(?:@([1-9]\d*))?(?:\.(?:css|json))?$/.exec(token);
+  if (!match || !THEME_ID.test(match[1])) throw new Error(`Not a theme id: ${token}`);
+  return { base: base.replace(/\/$/, ""), id: match[1], version: match[2] ? Number(match[2]) : undefined };
+}
+
+async function fetchText(url, fetcher) {
+  let response;
+  try {
+    response = await fetcher(url);
+  } catch (error) {
+    throw new Error(`Could not reach ${new URL(url).origin}: ${error.message}`);
+  }
+  if (response.status === 404) {
+    throw new Error("No shared theme at that id. Private themes cannot be pulled; set it to Link or Public in the Studio.");
+  }
+  if (!response.ok) throw new Error(`${url} answered ${response.status}.`);
+  return response.text();
+}
+
+function ensureImport(indexFile, line) {
+  const current = fs.existsSync(indexFile) ? fs.readFileSync(indexFile, "utf8") : "";
+  if (current.includes(line)) return false;
+  fs.mkdirSync(path.dirname(indexFile), { recursive: true });
+  fs.writeFileSync(indexFile, `${current}${current && !current.endsWith("\n") ? "\n" : ""}${line}\n`);
+  return true;
+}
+
+export async function pullTheme(cwd, reference, { host, overwrite = false, fetcher = fetch, output = console } = {}) {
+  const { base, id, version } = parseThemeReference(reference, host);
+  const pinned = (extension, at) => `${base}/t/${id}@${at}.${extension}`;
+
+  const record = JSON.parse(await fetchText(version ? pinned("json", version) : `${base}/t/${id}.json`, fetcher));
+  if (!record?.spec || typeof record.version !== "number") throw new Error("The server returned an unexpected theme record.");
+  const css = await fetchText(pinned("css", record.version), fetcher);
+
+  const themeFile = path.join(cwd, "mlola.theme.json");
+  if (fs.existsSync(themeFile) && !overwrite) {
+    const existing = JSON.parse(fs.readFileSync(themeFile, "utf8"));
+    if (existing?.studio?.id !== id) {
+      throw new Error("mlola.theme.json already holds another theme. Re-run with --overwrite to replace it.");
+    }
+  }
+  const spec = {
+    $schema: "https://unpkg.com/@mlola-ui/engine/generated/theme-spec.schema.json",
+    ...record.spec,
+    id: record.selector,
+    studio: { id, version: record.version, source: pinned("json", record.version) },
+  };
+  fs.writeFileSync(themeFile, `${JSON.stringify(spec, null, 2)}\n`);
+
+  const config = fs.existsSync(path.join(cwd, "mlola.config.json")) ? loadConfig(cwd) : DEFAULT_CONFIG;
+  const stylesDirectory = path.join(cwd, targetRoot(config, "styles"), "mlola");
+  fs.mkdirSync(stylesDirectory, { recursive: true });
+  fs.writeFileSync(path.join(stylesDirectory, "theme.css"), css);
+  const imported = ensureImport(path.join(stylesDirectory, "index.css"), '@import "./theme.css";');
+
+  const stylesRelative = path.relative(cwd, stylesDirectory);
+  output.log(`✓ Pulled ${record.name} (${id}@${record.version})`);
+  output.log(`✓ Wrote mlola.theme.json and ${path.join(stylesRelative, "theme.css")}`);
+  if (imported) output.log(`✓ Imported it from ${path.join(stylesRelative, "index.css")}`);
+  output.log(`Set data-theme="${record.selector}" on <html> or any container.`);
+  return { id, version: record.version, selector: record.selector };
+}