marvelous-ui-library 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quentin Fankrache EI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# Marvelous UI Library CLI
+
+Install the Free Pack in a web project:
+
+```bash
+npx marvelous-ui-library@latest init
+npx marvelous-ui-library@latest add dialog tabs toast
+```
+
+`init` detects the project and supported agent configuration. In an interactive terminal it asks whether to install the Pack in this project or in your user profile, then asks for Free or Pro. For automation, use `--scope project|user --edition free|pro`. A noninteractive invocation defaults to Free in the current project.
+
+The Pro Pack requires a Polar license key. Enter it when prompted or pass it through the `MARVELOUS_LICENSE_KEY` environment variable. The key is not written to a project file. A project Pack remains at its installed version until you run:
+
+```bash
+npx marvelous-ui-library@latest update
+```
+
+`update` compares installed component hashes before replacing files. Locally customized files are reported and preserved. A Pack installed in your user profile does not change copies already installed in other projects. A current Pro license key, including a key from an active yearly Renewal, is required to fetch a newer Pro Pack. For a private Renewal link, contact hello@marvelous-ui.com.
+
+The Free Pack is MIT licensed. The Pro Pack is subject to the commercial license shipped in its `LICENSE.md`.

package/bin.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { locations, readState, latestRelease, downloadRelease, installPack, addComponents, detectFramework } from "./lib/installer.mjs";
+
+const HELP = `Marvelous UI
+
+  npx marvelous-ui-library@latest init [--scope project|user] [--edition free|pro]
+  npx marvelous-ui-library@latest add <component...> [--scope project|user] [--out path]
+  npx marvelous-ui-library@latest update [--scope project|user]
+
+Options: --project path, --clients names. For Pro, set MARVELOUS_LICENSE_KEY or enter the Polar key when prompted.
+`;
+
+function options(args) {
+  const values = new Set(["scope", "edition", "project", "out", "clients"]);
+  const parsed = { slugs: [] };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") parsed.help = true;
+    else if (arg.startsWith("--")) {
+      const name = arg.slice(2);
+      if (!values.has(name) || !args[i + 1] || args[i + 1].startsWith("--")) throw new Error(`Invalid option: ${arg}`);
+      parsed[name] = args[++i];
+    } else parsed.slugs.push(arg);
+  }
+  return parsed;
+}
+
+async function ask(question, fallback = "") {
+  if (!process.stdin.isTTY) return fallback;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try { return (await rl.question(question)).trim() || fallback; }
+  finally { rl.close(); }
+}
+
+function existingScope(project) {
+  return readState(locations("project", project).state) ? "project" : readState(locations("user", project).state) ? "user" : null;
+}
+
+async function licenseKey() {
+  const key = process.env.MARVELOUS_LICENSE_KEY?.trim() || await ask("Polar license key: ");
+  if (!key) throw new Error("A Pro license key is required. Set MARVELOUS_LICENSE_KEY or run interactively.");
+  return key;
+}
+
+function report(result) {
+  for (const kind of ["added", "updated", "unchanged", "conflicts"]) {
+    const paths = result[kind];
+    if (paths?.length) console.log(`${kind}: ${paths.length}${kind === "conflicts" ? ` (${paths.join(", ")})` : ""}`);
+  }
+}
+
+function chosenOut(project, supplied, componentState) {
+  return supplied ?? componentState?.out ?? (existsSync(join(project, "src")) ? "src/marvelous" : "marvelous");
+}
+
+function pluginRefresh(place) {
+  console.log("If your agent installed a copy of the plugin, register the updated Pack again:");
+  execFileSync(process.execPath, [join(place.pack, "scripts", "init-agent.mjs"), "--plugin"], { stdio: "inherit" });
+}
+
+async function init(opts, project) {
+  const scope = opts.scope ?? existingScope(project) ?? await ask("Install in this project or for this user? [project/user] ", "project");
+  const place = locations(scope, project);
+  const current = readState(place.state);
+  const edition = opts.edition ?? current?.edition ?? await ask("Free or Pro Pack? [free/pro] ", "free");
+  if (!["project", "user"].includes(scope) || !["free", "pro"].includes(edition)) throw new Error("Choose --scope project|user and --edition free|pro.");
+  console.log(`Marvelous UI: ${edition} Pack, ${scope} scope, ${detectFramework(project)} project`);
+  if (!current || current.edition !== edition) {
+    const meta = await latestRelease(edition);
+    const bytes = await downloadRelease(edition, meta, edition === "pro" ? await licenseKey() : "");
+    installPack(bytes, edition, meta, place);
+    console.log(`Pack ${meta.version} installed in ${place.pack}`);
+  } else console.log(`Pack ${current.version} is installed. Run update to fetch a newer version.`);
+  if (scope === "project") {
+    const out = chosenOut(project, opts.out, readState(place.components));
+    const args = [join(place.pack, "scripts", "init-agent.mjs"), project, "--out", out];
+    if (opts.clients) args.push("--clients", opts.clients);
+    execFileSync(process.execPath, args, { stdio: "inherit" });
+  } else {
+    console.log("Register the user Pack with your agent using these commands:");
+    execFileSync(process.execPath, [join(place.pack, "scripts", "init-agent.mjs"), "--plugin"], { stdio: "inherit" });
+  }
+  console.log("Ready. Ask your coding agent to build a UI with Marvelous UI.");
+}
+
+async function add(opts, project) {
+  const scope = opts.scope ?? existingScope(project);
+  if (!scope) throw new Error("Run marvelous-ui-library init first.");
+  const place = locations(scope, project);
+  const out = chosenOut(project, opts.out, readState(place.components));
+  const result = addComponents({ place, project, slugs: opts.slugs, out });
+  report(result);
+  console.log(result.usage);
+}
+
+async function update(opts, project) {
+  const scope = opts.scope ?? existingScope(project);
+  if (!scope) throw new Error("Run marvelous-ui-library init first.");
+  const place = locations(scope, project);
+  const current = readState(place.state);
+  const componentState = readState(place.components);
+  const hasComponents = componentState?.slugs?.length && componentState.sourceScope === scope;
+  const pinnedOlder = hasComponents && scope === "user" &&
+    (componentState.packVersion !== current.version || componentState.packSha256 !== current.sha256 || componentState.packEdition !== current.edition);
+  const meta = await latestRelease(current.edition);
+  if (meta.version === current.version) {
+    if (meta.sha256 !== current.sha256) throw new Error(`Pack ${meta.version} changed without a version bump. Contact hello@marvelous-ui.com.`);
+    if (pinnedOlder) {
+      console.log(`Updating this project's components from Pack ${componentState.packVersion} to ${current.version}:`);
+      const preview = addComponents({ place, project, slugs: componentState.slugs, out: componentState.out, dryRun: true, useCurrentPack: true });
+      report(preview);
+      if (preview.conflicts.length) console.log("Customized files will be preserved. Merge those files manually if you want the new version.");
+      report(addComponents({ place, project, slugs: componentState.slugs, out: componentState.out, useCurrentPack: true }));
+      pluginRefresh(place);
+      return;
+    }
+    return console.log(`Pack ${current.version} is already current.`);
+  }
+  console.log(`Pack ${current.version} -> ${meta.version}. Installed project files will be compared before replacement.`);
+  const bytes = await downloadRelease(current.edition, meta, current.edition === "pro" ? await licenseKey() : "");
+  installPack(bytes, current.edition, meta, place, {
+    beforeCommit: (stagedPack) => {
+      if (!hasComponents) return;
+      const preview = addComponents({ place: { ...place, pack: stagedPack }, project, slugs: componentState.slugs, out: componentState.out, dryRun: true, useCurrentPack: true });
+      console.log("Project component changes:");
+      report(preview);
+      if (preview.conflicts.length) console.log("Customized files will be preserved. Merge those files manually if you want the new version.");
+    },
+  });
+  console.log(`Pack ${meta.version} installed.`);
+  if (hasComponents) report(addComponents({ place, project, slugs: componentState.slugs, out: componentState.out, useCurrentPack: true }));
+  if (scope === "user") console.log("Other projects stay at their installed versions until you run update in those projects.");
+  pluginRefresh(place);
+}
+
+async function run(args = process.argv.slice(2)) {
+  const command = args[0];
+  if (command === "--help" || command === "-h") return console.log(HELP);
+  const opts = options(args.slice(1));
+  if (!command || opts.help || command === "help") return console.log(HELP);
+  if (!["init", "add", "update"].includes(command)) throw new Error(`Unknown command: ${command}\n${HELP}`);
+  const project = resolve(opts.project ?? process.cwd());
+  if (!existsSync(project)) throw new Error(`Project does not exist: ${project}`);
+  if (command === "init") return init(opts, project);
+  if (command === "add") return add(opts, project);
+  return update(opts, project);
+}
+
+run().catch((error) => { console.error(`Marvelous UI: ${error.message}`); process.exitCode = 1; });

package/lib/archive.mjs

@@ -0,0 +1,82 @@
+import { inflateRawSync } from "node:zlib";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const END = 0x06054b50;
+const CENTRAL = 0x02014b50;
+const LOCAL = 0x04034b50;
+const MAX_ARCHIVE = 100 * 1024 * 1024;
+const MAX_EXTRACTED = 250 * 1024 * 1024;
+
+function endRecord(zip) {
+  for (let at = zip.length - 22; at >= Math.max(0, zip.length - 65557); at--) {
+    if (zip.readUInt32LE(at) === END && at + 22 + zip.readUInt16LE(at + 20) === zip.length) return at;
+  }
+  throw new Error("The Pack archive has no ZIP directory.");
+}
+
+/** Extract a commercial Pack ZIP without trusting names, symlinks or compressed sizes. */
+export function extractPack(zip, destination, root) {
+  if (!Buffer.isBuffer(zip) || zip.length > MAX_ARCHIVE) throw new Error("Pack archive exceeds the size limit.");
+  const end = endRecord(zip);
+  const count = zip.readUInt16LE(end + 10);
+  const start = zip.readUInt32LE(end + 16);
+  const centralSize = zip.readUInt32LE(end + 12);
+  if (count === 0 || count === 0xffff || start + centralSize > end) throw new Error("Invalid ZIP directory.");
+  const entries = [];
+  const names = new Set();
+  let offset = start;
+  let total = 0;
+  for (let i = 0; i < count; i++) {
+    if (offset + 46 > end || zip.readUInt32LE(offset) !== CENTRAL) throw new Error("Invalid ZIP entry.");
+    const flags = zip.readUInt16LE(offset + 8);
+    const method = zip.readUInt16LE(offset + 10);
+    const compressed = zip.readUInt32LE(offset + 20);
+    const size = zip.readUInt32LE(offset + 24);
+    const nameLength = zip.readUInt16LE(offset + 28);
+    const extraLength = zip.readUInt16LE(offset + 30);
+    const commentLength = zip.readUInt16LE(offset + 32);
+    const local = zip.readUInt32LE(offset + 42);
+    const madeBy = zip.readUInt16LE(offset + 4) >> 8;
+    const mode = zip.readUInt32LE(offset + 38) >>> 16;
+    const nameEnd = offset + 46 + nameLength;
+    if (nameEnd > end || flags & 1 || ![0, 8].includes(method) || (madeBy === 3 && (mode & 0o170000) === 0o120000)) {
+      throw new Error("Unsupported or unsafe ZIP entry.");
+    }
+    const name = zip.subarray(offset + 46, nameEnd).toString("utf8");
+    const rel = name.startsWith(`${root}/`) ? name.slice(root.length + 1) : "";
+    const directory = rel.endsWith("/");
+    const parts = (directory ? rel.slice(0, -1) : rel).split("/");
+    if (!rel || rel.includes("\\") || parts.some((part) => !part || part === "." || part === ".." || part.includes(":"))) {
+      if (name === `${root}/`) { offset = nameEnd + extraLength + commentLength; continue; }
+      throw new Error(`Unsafe Pack path: ${name}`);
+    }
+    if (directory) {
+      if (size !== 0 || compressed !== 0) throw new Error(`Invalid ZIP directory: ${name}`);
+      offset = nameEnd + extraLength + commentLength;
+      continue;
+    }
+    const portableName = rel.toLowerCase();
+    if (names.has(portableName) || local + 30 > start || zip.readUInt32LE(local) !== LOCAL) throw new Error("Invalid or duplicate ZIP entry.");
+    names.add(portableName);
+    total += size;
+    if (total > MAX_EXTRACTED) throw new Error("Pack expands beyond the size limit.");
+    const dataStart = local + 30 + zip.readUInt16LE(local + 26) + zip.readUInt16LE(local + 28);
+    if (dataStart + compressed > start) throw new Error("ZIP entry exceeds its bounds.");
+    entries.push({ rel, method, compressed, size, dataStart });
+    offset = nameEnd + extraLength + commentLength;
+  }
+  if (offset !== start + centralSize) throw new Error("Invalid ZIP directory size.");
+  const files = entries.map(({ rel, method, compressed, size, dataStart }) => {
+    const data = zip.subarray(dataStart, dataStart + compressed);
+    const contents = method === 0 ? data : inflateRawSync(data, { maxOutputLength: size + 1 });
+    if (contents.length !== size) throw new Error(`Invalid ZIP entry size: ${rel}`);
+    return { rel, contents };
+  });
+  for (const { rel, contents } of files) {
+    const target = join(destination, ...rel.split("/"));
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, contents);
+  }
+  return files.map((file) => file.rel);
+}

package/lib/installer.mjs

@@ -0,0 +1,216 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { extractPack } from "./archive.mjs";
+import { copyManagedFiles, hash } from "./managed.mjs";
+
+export const ORIGIN = "https://marvelous-ui.com";
+const MAX_DOWNLOAD = 100 * 1024 * 1024;
+const REQUEST_TIMEOUT = 60000;
+const VERSION = /^\d+\.\d+\.\d+$/;
+const SHA256 = /^[a-f0-9]{64}$/;
+
+export function locations(scope, project = process.cwd(), home = homedir()) {
+  if (!["project", "user"].includes(scope)) throw new Error("Scope must be project or user.");
+  const projectBase = join(resolve(project), ".marvelous-ui");
+  try { if (lstatSync(projectBase).isSymbolicLink()) throw new Error("The project Pack directory cannot be a symbolic link."); }
+  catch (error) { if (error.code !== "ENOENT") throw error; }
+  const base = scope === "user" ? join(home, ".marvelous-ui") : projectBase;
+  return { scope, base, pack: join(base, "pack"), state: join(base, "install.json"), components: join(projectBase, "components.json") };
+}
+
+export function readState(file) {
+  if (!existsSync(file)) return null;
+  const state = JSON.parse(readFileSync(file, "utf8"));
+  if (state.schema !== 1) throw new Error(`Unsupported Marvelous UI state: ${file}`);
+  return state;
+}
+
+function saveState(file, state) {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ schema: 1, ...state }, null, 2) + "\n", { mode: 0o600 });
+  renameSync(tmp, file);
+}
+
+function validMeta(meta) {
+  if (!meta || !VERSION.test(meta.version) || !SHA256.test(meta.sha256) || !Number.isSafeInteger(meta.bytes) || meta.bytes < 1 || meta.bytes > MAX_DOWNLOAD) {
+    throw new Error("The release manifest is invalid.");
+  }
+  return { version: meta.version, sha256: meta.sha256, bytes: meta.bytes };
+}
+
+function protectedProjectPack(place) {
+  if (place.scope !== "project") return;
+  const file = join(place.base, ".gitignore");
+  try { if (lstatSync(file).isSymbolicLink()) throw new Error("The Pack ignore file cannot be a symbolic link."); }
+  catch (error) { if (error.code !== "ENOENT") throw error; }
+  let rules = existsSync(file) ? readFileSync(file, "utf8") : "";
+  if (!rules.split(/\r?\n/).includes("/pack/")) {
+    rules = `${rules.trimEnd()}${rules.trim() ? "\n" : ""}/pack/\n/.stage-*/\n/.backup-*/\n`;
+    writeFileSync(file, rules);
+  }
+  try {
+    const tracked = execFileSync("git", ["ls-files", "--cached", "--", ".marvelous-ui/pack"], {
+      cwd: dirname(place.base), encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+    });
+    if (tracked.trim()) throw new Error("The Pack is tracked by Git. Remove .marvelous-ui/pack from the Git index before continuing.");
+  } catch (error) { if (error.message?.startsWith("The Pack is tracked")) throw error; }
+}
+
+async function response(fetcher, url, init = {}) {
+  let res;
+  try { res = await fetcher(url, { ...init, signal: AbortSignal.timeout(REQUEST_TIMEOUT) }); }
+  catch { throw new Error("The Marvelous UI download service is unavailable. Try again later."); }
+  if (!res.ok) {
+    const code = await res.json().then((body) => body.error).catch(() => "");
+    if (res.status === 403 && code === "invalid_key") throw new Error("This license key is invalid or expired. For a private renewal link, contact hello@marvelous-ui.com.");
+    if (res.status === 404) throw new Error("This Pack version is unavailable. Contact hello@marvelous-ui.com.");
+    throw new Error(`The Marvelous UI download service failed (${res.status}${code ? `, ${code}` : ""}). Try again later.`);
+  }
+  return res;
+}
+
+export async function latestRelease(edition, { fetcher = fetch, origin = ORIGIN } = {}) {
+  if (!["free", "pro"].includes(edition)) throw new Error("Edition must be free or pro.");
+  const url = edition === "free" ? `${origin}/downloads/marvelous-ui-free.json` : `${origin}/api/pack`;
+  const res = await response(fetcher, url);
+  let metadata;
+  try { metadata = await res.json(); }
+  catch { throw new Error("The Marvelous UI release metadata is unavailable. Try again later."); }
+  return validMeta(metadata);
+}
+
+export async function downloadRelease(edition, meta, key, { fetcher = fetch, origin = ORIGIN } = {}) {
+  validMeta(meta);
+  if (edition === "pro" && !key) throw new Error("Set MARVELOUS_LICENSE_KEY or enter your Polar license key when prompted.");
+  const url = edition === "free" ? `${origin}/downloads/marvelous-ui-free.zip` : `${origin}/api/pack`;
+  const init = edition === "pro" ? { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ key, version: meta.version }) } : {};
+  const res = await response(fetcher, url, init);
+  if (!res.body) throw new Error("The Pack download was empty.");
+  const chunks = [];
+  let received = 0;
+  try {
+    for await (const chunk of res.body) {
+      received += chunk.length;
+      if (received > meta.bytes || received > MAX_DOWNLOAD) throw new Error("The Pack download exceeds its expected size.");
+      chunks.push(chunk);
+    }
+  } catch (error) {
+    if (error.message === "The Pack download exceeds its expected size.") throw error;
+    throw new Error("The Pack download was interrupted. Try again later.");
+  }
+  const bytes = Buffer.concat(chunks, received);
+  if (bytes.length !== meta.bytes || hash(bytes) !== meta.sha256) throw new Error("The downloaded Pack failed its size or SHA-256 check.");
+  return bytes;
+}
+
+function validPack(dir, edition, version) {
+  const registry = JSON.parse(readFileSync(join(dir, "registry.json"), "utf8"));
+  const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+  if (registry.version !== version || pkg.version !== version || !Array.isArray(registry.items) || !registry.items.length) throw new Error("The Pack version or registry is invalid.");
+  if (edition === "pro" && !existsSync(join(dir, "LICENSE.md"))) throw new Error("The Pro license is missing from the Pack.");
+  if (edition === "free" && !existsSync(join(dir, "LICENSE"))) throw new Error("The Free license is missing from the Pack.");
+}
+
+/** Install a verified ZIP atomically so a failed download or npm install keeps the prior Pack. */
+export function installPack(bytes, edition, meta, place, { installDependencies = true, beforeCommit } = {}) {
+  validMeta(meta);
+  if (bytes.length !== meta.bytes || hash(bytes) !== meta.sha256) throw new Error("The Pack failed its size or SHA-256 check.");
+  mkdirSync(place.base, { recursive: true });
+  protectedProjectPack(place);
+  const stage = mkdtempSync(join(place.base, ".stage-"));
+  const backup = join(place.base, `.backup-${process.pid}`);
+  try {
+    extractPack(bytes, stage, `marvelous-ui-${edition}`);
+    validPack(stage, edition, meta.version);
+    if (installDependencies) {
+      const npmArgs = ["ci", "--omit=dev", "--ignore-scripts", "--no-audit"];
+      if (process.env.npm_execpath?.endsWith(".js")) execFileSync(process.execPath, [process.env.npm_execpath, ...npmArgs], { cwd: stage, stdio: "inherit" });
+      else execFileSync("npm", npmArgs, { cwd: stage, stdio: "inherit", shell: process.platform === "win32" });
+    }
+    beforeCommit?.(stage);
+    if (existsSync(backup)) throw new Error("A previous installation is still being recovered.");
+    const prior = existsSync(place.pack);
+    const oldState = prior ? readState(place.state) : null;
+    if (prior) renameSync(place.pack, backup);
+    try { renameSync(stage, place.pack); }
+    catch (error) { if (prior) renameSync(backup, place.pack); throw error; }
+    const archive = oldState && place.scope === "user"
+      ? join(place.base, "versions", `${oldState.edition}-${oldState.version}-${oldState.sha256}`) : null;
+    let archived = false;
+    try {
+      if (archive && !existsSync(archive)) {
+        mkdirSync(dirname(archive), { recursive: true });
+        renameSync(backup, archive);
+        archived = true;
+      }
+      saveState(place.state, { edition, version: meta.version, sha256: meta.sha256, scope: place.scope ?? "project" });
+    }
+    catch (error) {
+      rmSync(place.pack, { recursive: true, force: true });
+      if (prior) renameSync(archived ? archive : backup, place.pack);
+      throw error;
+    }
+    if (prior && !archived) rmSync(backup, { recursive: true, force: true });
+  } finally { if (existsSync(stage)) rmSync(stage, { recursive: true, force: true }); }
+}
+
+function filesUnder(root, current = root) {
+  return readdirSync(current).flatMap((name) => {
+    const abs = join(current, name);
+    return statSync(abs).isDirectory() ? filesUnder(root, abs) : [relative(root, abs).split(sep).join("/")];
+  });
+}
+
+function targetFolder(project, out) {
+  const target = resolve(project, out);
+  const rel = relative(resolve(project), target);
+  if (!rel || rel.startsWith("..") || isAbsolute(rel)) throw new Error("The component output must be inside the project.");
+  let cursor = resolve(project);
+  for (const part of rel.split(sep)) {
+    cursor = join(cursor, part);
+    try { if (lstatSync(cursor).isSymbolicLink()) throw new Error("The component output cannot pass through a symbolic link."); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+  return target;
+}
+
+/** Stage the existing Pack CLI's dependency closure and merge only managed, unedited files. */
+export function addComponents({ place, project, slugs, out, dryRun = false, useCurrentPack = false }) {
+  if (!slugs.length || slugs.some((slug) => !/^[a-z0-9][a-z0-9-]*$/.test(slug))) throw new Error("Specify valid component slugs.");
+  const state = readState(place.state);
+  if (!state) throw new Error("Run marvelous-ui-library init first.");
+  const target = targetFolder(project, out);
+  const stage = mkdtempSync(join(tmpdir(), "mv-components-"));
+  try {
+    const prior = readState(place.components) ?? { slugs: [], out, files: {} };
+    if (prior.out !== out && prior.slugs.length) throw new Error(`Components are tracked in ${prior.out}; use --out ${prior.out}.`);
+    let selectedPack = place.pack;
+    let selectedState = state;
+    if (!useCurrentPack && place.scope === "user" && prior.slugs.length && prior.packVersion &&
+        (prior.packVersion !== state.version || prior.packSha256 !== state.sha256 || prior.packEdition !== state.edition)) {
+      if (!["free", "pro"].includes(prior.packEdition) || !VERSION.test(prior.packVersion) || !SHA256.test(prior.packSha256)) {
+        throw new Error("The project's pinned Pack state is invalid. Run update in this project.");
+      }
+      selectedPack = join(place.base, "versions", `${prior.packEdition}-${prior.packVersion}-${prior.packSha256}`);
+      if (!existsSync(selectedPack)) throw new Error("This project's pinned Pack version is unavailable. Run update in this project.");
+      selectedState = { version: prior.packVersion, sha256: prior.packSha256, edition: prior.packEdition };
+    }
+    const packCli = join(selectedPack, "scripts", "add.mjs");
+    const usage = execFileSync(process.execPath, [packCli, ...slugs, "--out", stage], { encoding: "utf8" });
+    const files = filesUnder(stage);
+    const result = copyManagedFiles(stage, target, files, prior.files, { dryRun });
+    if (!dryRun) saveState(place.components, { out, slugs: [...new Set([...prior.slugs, ...slugs])].sort(), files: result.hashes, sourceScope: state.scope, packVersion: selectedState.version, packSha256: selectedState.sha256, packEdition: selectedState.edition });
+    return { ...result, usage: usage.replaceAll(stage, target) };
+  } finally { rmSync(stage, { recursive: true, force: true }); }
+}
+
+export function detectFramework(project) {
+  const file = join(project, "package.json");
+  if (!existsSync(file)) return "HTML";
+  const pkg = JSON.parse(readFileSync(file, "utf8"));
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  return Object.entries({ next: "Next.js", nuxt: "Nuxt", "@angular/core": "Angular", "@sveltejs/kit": "SvelteKit", astro: "Astro", vue: "Vue", svelte: "Svelte", react: "React" }).find(([key]) => deps[key])?.[1] ?? "HTML";
+}

package/lib/managed.mjs

@@ -0,0 +1,54 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+
+export const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+
+function safeTarget(root, rel) {
+  if (typeof rel !== "string" || !rel || isAbsolute(rel) || rel.includes("\\") || rel.split("/").some((p) => !p || p === "." || p === ".." || p.includes(":"))) {
+    throw new Error(`Unsafe file path: ${rel}`);
+  }
+  const target = resolve(root, ...rel.split("/"));
+  if (!target.startsWith(resolve(root) + sep)) throw new Error(`File escapes the project: ${rel}`);
+  let cursor = resolve(root);
+  try { if (lstatSync(cursor).isSymbolicLink()) throw new Error(`Symbolic link in install path: ${rel}`); }
+  catch (error) { if (error.code !== "ENOENT") throw error; }
+  for (const part of rel.split("/")) {
+    cursor = join(cursor, part);
+    try { if (lstatSync(cursor).isSymbolicLink()) throw new Error(`Symbolic link in install path: ${rel}`); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+  return target;
+}
+
+/** Compare desired files with the hashes recorded when Marvelous last wrote them. */
+export function copyManagedFiles(source, target, files, previous = {}, { dryRun = false } = {}) {
+  const result = { added: [], updated: [], unchanged: [], conflicts: [], hashes: { ...previous } };
+  const writes = [];
+  for (const rel of [...new Set(files)].sort()) {
+    const from = safeTarget(source, rel);
+    const to = safeTarget(target, rel);
+    const bytes = readFileSync(from);
+    const next = hash(bytes);
+    if (!existsSync(to)) {
+      result.added.push(rel);
+      result.hashes[rel] = next;
+      writes.push([to, bytes]);
+      continue;
+    }
+    const current = hash(readFileSync(to));
+    if (current === next) {
+      result.unchanged.push(rel);
+      result.hashes[rel] = next;
+    } else if (previous[rel] === current) {
+      result.updated.push(rel);
+      result.hashes[rel] = next;
+      writes.push([to, bytes]);
+    } else result.conflicts.push(rel);
+  }
+  if (!dryRun) for (const [to, bytes] of writes) {
+    mkdirSync(dirname(to), { recursive: true });
+    writeFileSync(to, bytes);
+  }
+  return result;
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "marvelous-ui-library",
+  "version": "1.0.0",
+  "description": "Install and update the Marvelous UI component Pack for coding agents",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "marvelous-ui-library": "bin.mjs"
+  },
+  "files": [
+    "bin.mjs",
+    "lib/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/baz-fkr/marvelous-ui-library.git",
+    "directory": "cli"
+  }
+}