marvelous-ui-library 1.0.0 → 1.0.2

package/README.md

@@ -7,9 +7,9 @@ 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.
+`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. Enter a Polar license key in the hidden prompt for Pro, or press Enter for Free. User setup then asks which agents to connect and registers Codex and Claude Code directly. For automation, set `MARVELOUS_LICENSE_KEY` for Pro and use `--scope user --clients codex,claude` to choose agents; `--clients none` installs only the shared Pack. Rerunning user setup removes a previously selected plugin when you deselect that agent. A noninteractive invocation without a key defaults to Free in the current project. `--edition free|pro` remains available for existing scripts. Other agents can use project setup or the manual instructions in the Pack's `docs/MCP.md`.
 
-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:
+The Pro Pack requires a Polar license key for the first download and for newer releases. A supplied invalid key causes an error. 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
@@ -17,4 +17,12 @@ 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.
 
+Every verified Pro ZIP is saved under `~/.marvelous-ui/archives`, including when the Pack is installed in a project. Keep a backup of this folder if you want to preserve your downloaded releases. To restore a saved release without contacting Polar or the download service:
+
+```bash
+npx marvelous-ui-library@latest restore --version 1.0.0
+```
+
+Run `restore` without `--version` in an interactive terminal to choose from the saved releases. Use `--scope project|user` to choose the target. Restoration compares managed component hashes and preserves customized files. A saved release remains usable after the key expires; fetching a release that was never saved still requires an active key.
+
 The Free Pack is MIT licensed. The Pro Pack is subject to the commercial license shipped in its `LICENSE.md`.

package/bin.mjs

@@ -3,19 +3,22 @@ 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";
+import { Writable } from "node:stream";
+import { locations, readState, latestRelease, downloadRelease, installPack, addComponents, detectFramework, listProArchives, readProArchive } from "./lib/installer.mjs";
+import { checkUserAgents, configureUserAgents, parseUserAgents, readUserAgents } from "./lib/agents.mjs";
 
 const HELP = `Marvelous UI
 
-  npx marvelous-ui-library@latest init [--scope project|user] [--edition free|pro]
+  npx marvelous-ui-library@latest init [--scope project|user]
   npx marvelous-ui-library@latest add <component...> [--scope project|user] [--out path]
   npx marvelous-ui-library@latest update [--scope project|user]
+  npx marvelous-ui-library@latest restore [--scope project|user] [--version 1.1.0]
 
-Options: --project path, --clients names. For Pro, set MARVELOUS_LICENSE_KEY or enter the Polar key when prompted.
+Options: --project path, --clients names. User setup supports codex,claude,none. At init, press Enter for Free or enter a Polar key for Pro. In automation, set MARVELOUS_LICENSE_KEY for Pro.
 `;
 
 function options(args) {
-  const values = new Set(["scope", "edition", "project", "out", "clients"]);
+  const values = new Set(["scope", "edition", "project", "out", "clients", "version"]);
   const parsed = { slugs: [] };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -36,12 +39,21 @@ async function ask(question, fallback = "") {
   finally { rl.close(); }
 }
 
+async function askSecret(question) {
+  if (!process.stdin.isTTY) return "";
+  const muted = new Writable({ write(_chunk, _encoding, done) { done(); } });
+  const rl = createInterface({ input: process.stdin, output: muted, terminal: true });
+  process.stdout.write(question);
+  try { return (await rl.question("")).trim(); }
+  finally { rl.close(); process.stdout.write("\n"); }
+}
+
 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: ");
+  const key = process.env.MARVELOUS_LICENSE_KEY?.trim() || await askSecret("Polar license key: ");
   if (!key) throw new Error("A Pro license key is required. Set MARVELOUS_LICENSE_KEY or run interactively.");
   return key;
 }
@@ -58,33 +70,110 @@ function chosenOut(project, supplied, componentState) {
 }
 
 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" });
+  if (place.scope !== "user") return;
+  const agents = readUserAgents(place);
+  if (agents.length) {
+    const names = configureUserAgents(place, agents);
+    console.log(`Updated agent plugins: ${names.join(", ")}.`);
+  }
+}
+
+function defaultUserAgents(place) {
+  const previous = readUserAgents(place);
+  if (existsSync(join(place.base, "agents.json"))) return previous.length ? previous.join(",") : "none";
+  for (const name of ["codex", "claude"]) {
+    try { execFileSync(name, ["--version"], { stdio: "ignore" }); return name; }
+    catch {}
+  }
+  return "none";
 }
 
 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");
+  let key = process.env.MARVELOUS_LICENSE_KEY?.trim() ?? "";
+  if (!opts.edition && !key && current?.edition !== "pro") key = await askSecret("Polar license key (optional, press Enter for Free): ");
+  const edition = opts.edition ?? (key || current?.edition === "pro" ? "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 (opts.edition === "free" && key) throw new Error("A Polar key was provided with --edition free. Remove the key or choose Pro.");
+  let selectedAgents = null;
+  if (scope === "user") {
+    const choice = opts.clients ?? (process.stdin.isTTY
+      ? await ask("Which agents should be connected? [codex,claude,none] (comma-separated) ", defaultUserAgents(place))
+      : existsSync(join(place.base, "agents.json")) ? defaultUserAgents(place) : "none");
+    selectedAgents = parseUserAgents(choice);
+  }
+  if (selectedAgents) checkUserAgents(selectedAgents);
+  const componentState = readState(place.components);
+  const hasComponents = !!(current && componentState?.slugs?.length && componentState.sourceScope === scope);
+  console.log(`Marvelous UI: ${edition} Pack, ${scope === "user" ? "user profile" : `${detectFramework(project)} project`}${key ? ", Polar key received" : ""}.`);
   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);
+    const bytes = await downloadRelease(edition, meta, edition === "pro" ? key || await licenseKey() : "");
+    installPack(bytes, 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 edition.");
+      },
+    });
+    if (hasComponents) report(addComponents({ place, project, slugs: componentState.slugs, out: componentState.out, useCurrentPack: true }));
     console.log(`Pack ${meta.version} installed in ${place.pack}`);
-  } else console.log(`Pack ${current.version} is installed. Run update to fetch a newer version.`);
+  } else {
+    if (edition === "pro" && key) await downloadRelease("pro", await latestRelease("pro"), key);
+    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" });
+    const names = configureUserAgents(place, selectedAgents);
+    console.log(names.length ? `Connected for all projects: ${names.join(", ")}.` : "No agent connected by choice.");
+  }
+  console.log(scope === "user" && !selectedAgents.length ? "Pack installed." : "Ready. Restart your agent to load Marvelous UI.");
+}
+
+async function restore(opts, project) {
+  const scope = opts.scope ?? existingScope(project) ?? "project";
+  const place = locations(scope, project);
+  const archives = listProArchives(place);
+  let version = opts.version;
+  if (!version) {
+    if (!process.stdin.isTTY) throw new Error("Specify --version to restore a saved Pro ZIP noninteractively.");
+    if (!archives.length) throw new Error("No saved Pro ZIP found. A new download requires an active key.");
+    console.log("Saved Pro ZIPs:");
+    archives.forEach((item, index) => console.log(`  ${index + 1}. ${item.version} (${item.sha256.slice(0, 12)})`));
+    const choice = Number(await ask("Choose a version [1]: ", "1"));
+    if (!Number.isSafeInteger(choice) || choice < 1 || choice > archives.length) throw new Error("Choose a listed Pro version.");
+    version = archives[choice - 1].version;
   }
-  console.log("Ready. Ask your coding agent to build a UI with Marvelous UI.");
+  const { bytes, meta } = readProArchive(place, version);
+  const current = readState(place.state);
+  const componentState = readState(place.components);
+  const hasComponents = !!(current && componentState?.slugs?.length && componentState.sourceScope === scope);
+  console.log(`Restoring Pro Pack ${meta.version} from the verified local ZIP.`);
+  installPack(bytes, "pro", 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 restored version.");
+    },
+  });
+  if (hasComponents) report(addComponents({ place, project, slugs: componentState.slugs, out: componentState.out, useCurrentPack: true }));
+  if (!current && scope === "project") {
+    const out = chosenOut(project, opts.out, componentState);
+    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 pluginRefresh(place);
+  console.log(`Pro Pack ${meta.version} restored without contacting the download service.`);
 }
 
 async function add(opts, project) {
@@ -142,11 +231,12 @@ async function run(args = process.argv.slice(2)) {
   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}`);
+  if (!["init", "add", "update", "restore"].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);
+  if (command === "restore") return restore(opts, project);
   return update(opts, project);
 }
 

package/lib/agents.mjs

@@ -0,0 +1,69 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const SUPPORTED = ["codex", "claude"];
+const LABELS = { codex: "Codex", claude: "Claude Code" };
+
+export function parseUserAgents(value) {
+  const names = [...new Set(value.toLowerCase().split(",").map((name) => name.trim()).filter(Boolean))];
+  if (names.length === 1 && names[0] === "none") return [];
+  const unsupported = names.filter((name) => !SUPPORTED.includes(name));
+  if (unsupported.length) throw new Error(`User setup supports Codex and Claude Code. Unsupported choice: ${unsupported.join(", ")}. Other agents can use project setup or the manual guide.`);
+  if (!names.length) throw new Error("Choose codex, claude, both, or none.");
+  return names;
+}
+
+export function readUserAgents(place) {
+  const file = join(place.base, "agents.json");
+  if (!existsSync(file)) return [];
+  const state = JSON.parse(readFileSync(file, "utf8"));
+  if (state.schema !== 1 || !Array.isArray(state.clients) || state.clients.some((name) => !SUPPORTED.includes(name))) {
+    throw new Error(`Unsupported Marvelous UI agent state: ${file}`);
+  }
+  return state.clients;
+}
+
+function runAgent(command, args, runner) {
+  try { runner(command, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }); }
+  catch (error) {
+    const detail = String(error.stderr ?? error.message ?? "").trim().split(/\r?\n/).at(-1);
+    throw new Error(`${LABELS[command]} setup failed${detail ? `: ${detail}` : "."} The Pack remains installed. Rerun init to retry agent setup.`);
+  }
+}
+
+export function checkUserAgents(clients, runner = execFileSync) {
+  for (const client of clients) runAgent(client, ["--version"], runner);
+}
+
+export function configureUserAgents(place, clients, runner = execFileSync) {
+  const prior = readUserAgents(place);
+  for (const client of clients) {
+    if (client === "codex") {
+      runAgent("codex", ["plugin", "marketplace", "add", place.pack], runner);
+      runAgent("codex", ["plugin", "add", "marvelous-ui@marvelous-ui"], runner);
+    } else {
+      if (prior.includes("claude")) {
+        runAgent("claude", ["plugin", "marketplace", "update", "marvelous-ui"], runner);
+        runAgent("claude", ["plugin", "update", "marvelous-ui@marvelous-ui"], runner);
+      } else {
+        runAgent("claude", ["plugin", "marketplace", "add", place.pack], runner);
+        runAgent("claude", ["plugin", "install", "marvelous-ui@marvelous-ui", "--scope", "user"], runner);
+      }
+    }
+  }
+  for (const client of prior.filter((name) => !clients.includes(name))) {
+    if (client === "codex") runAgent("codex", ["plugin", "remove", "marvelous-ui@marvelous-ui"], runner);
+    else runAgent("claude", ["plugin", "uninstall", "marvelous-ui@marvelous-ui", "--scope", "user"], runner);
+  }
+  saveUserAgents(place, clients);
+  return clients.map((name) => LABELS[name]);
+}
+
+function saveUserAgents(place, clients) {
+  const file = join(place.base, "agents.json");
+  mkdirSync(place.base, { recursive: true });
+  const temporary = `${file}.${process.pid}.tmp`;
+  writeFileSync(temporary, JSON.stringify({ schema: 1, clients }, null, 2) + "\n", { mode: 0o600 });
+  renameSync(temporary, file);
+}

package/lib/installer.mjs

@@ -1,4 +1,4 @@
-import { execFileSync } from "node:child_process";
+import { execFileSync, execSync } 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";
@@ -17,7 +17,7 @@ export function locations(scope, project = process.cwd(), home = homedir()) {
   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") };
+  return { scope, base, pack: join(base, "pack"), state: join(base, "install.json"), components: join(projectBase, "components.json"), archives: join(home, ".marvelous-ui", "archives") };
 }
 
 export function readState(file) {
@@ -114,6 +114,72 @@ function validPack(dir, edition, version) {
   if (edition === "free" && !existsSync(join(dir, "LICENSE"))) throw new Error("The Free license is missing from the Pack.");
 }
 
+function archiveName(meta) { return `pro-${meta.version}-${meta.sha256}.zip`; }
+
+function safeArchiveDirectory(directory) {
+  const parent = dirname(directory);
+  for (const path of [parent, directory]) {
+    try { if (lstatSync(path).isSymbolicLink()) throw new Error("The Pro archive directory cannot be a symbolic link."); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+}
+
+/** Keep a verified release outside the project before replacing its installed Pack. */
+export function saveProArchive(bytes, meta, place) {
+  validMeta(meta);
+  if (bytes.length !== meta.bytes || hash(bytes) !== meta.sha256) throw new Error("The Pro archive failed its size or SHA-256 check.");
+  const directory = place.archives ?? join(homedir(), ".marvelous-ui", "archives");
+  const target = join(directory, archiveName(meta));
+  let temporary;
+  try {
+    safeArchiveDirectory(directory);
+    mkdirSync(directory, { recursive: true });
+    const conflicting = readdirSync(directory).find((name) => {
+      const match = /^pro-(\d+\.\d+\.\d+)-([a-f0-9]{64})\.zip$/.exec(name);
+      return match && match[1] === meta.version && match[2] !== meta.sha256;
+    });
+    if (conflicting) throw new Error(`Pro Pack ${meta.version} is already saved with a different SHA-256. Pack versions must be immutable.`);
+    if (existsSync(target)) {
+      if (!lstatSync(target).isFile()) throw new Error("The Pro archive path is not a regular file.");
+      const prior = readFileSync(target);
+      if (prior.length !== meta.bytes || hash(prior) !== meta.sha256) throw new Error("An existing Pro archive is corrupt. Remove or move it, then retry.");
+      return target;
+    }
+    temporary = join(directory, `.${archiveName(meta)}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`);
+    writeFileSync(temporary, bytes, { flag: "wx", mode: 0o600 });
+    renameSync(temporary, target);
+    return target;
+  } catch (error) {
+    throw new Error(`The verified Pro ZIP could not be saved to ${target}: ${error.message}`);
+  } finally { if (temporary && existsSync(temporary)) rmSync(temporary, { force: true }); }
+}
+
+export function listProArchives(place) {
+  const directory = place.archives ?? join(homedir(), ".marvelous-ui", "archives");
+  safeArchiveDirectory(directory);
+  if (!existsSync(directory)) return [];
+  return readdirSync(directory).flatMap((name) => {
+    const match = /^pro-(\d+\.\d+\.\d+)-([a-f0-9]{64})\.zip$/.exec(name);
+    if (!match) return [];
+    const path = join(directory, name);
+    if (!lstatSync(path).isFile()) return [];
+    return [{ version: match[1], sha256: match[2], path }];
+  }).sort((a, b) => b.version.localeCompare(a.version, undefined, { numeric: true }) || a.sha256.localeCompare(b.sha256));
+}
+
+export function readProArchive(place, version) {
+  if (version && !VERSION.test(version)) throw new Error("Specify a valid Pack version, for example 1.1.0.");
+  const matches = listProArchives(place).filter((item) => !version || item.version === version);
+  if (!matches.length) throw new Error(`No saved Pro ZIP found${version ? ` for ${version}` : ""}. A new download requires an active key.`);
+  if (matches.length !== 1) throw new Error("Several Pro ZIPs match. Specify a unique version or move the duplicate archive.");
+  const item = matches[0];
+  const bytes = readFileSync(item.path);
+  const meta = { version: item.version, sha256: item.sha256, bytes: bytes.length };
+  validMeta(meta);
+  if (hash(bytes) !== meta.sha256) throw new Error(`The saved Pro ZIP for ${item.version} failed its SHA-256 check.`);
+  return { bytes, meta, path: item.path };
+}
+
 /** 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);
@@ -125,10 +191,17 @@ export function installPack(bytes, edition, meta, place, { installDependencies =
   try {
     extractPack(bytes, stage, `marvelous-ui-${edition}`);
     validPack(stage, edition, meta.version);
+    if (edition === "pro") saveProArchive(bytes, meta, place);
     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" });
+      const npmArgs = ["ci", "--omit=dev", "--ignore-scripts", "--no-audit", "--no-fund", "--silent"];
+      try {
+        if (process.env.npm_execpath?.endsWith(".js")) execFileSync(process.execPath, [process.env.npm_execpath, ...npmArgs], { cwd: stage, stdio: ["ignore", "pipe", "pipe"] });
+        else if (process.platform === "win32") execSync(`npm ${npmArgs.join(" ")}`, { cwd: stage, stdio: ["ignore", "pipe", "pipe"] });
+        else execFileSync("npm", npmArgs, { cwd: stage, stdio: ["ignore", "pipe", "pipe"] });
+      } catch (error) {
+        const detail = String(error.stderr ?? error.message ?? "").trim().split(/\r?\n/).at(-1);
+        throw new Error(`The Pack dependencies could not be installed${detail ? `: ${detail}` : "."}`);
+      }
     }
     beforeCommit?.(stage);
     if (existsSync(backup)) throw new Error("A previous installation is still being recovered.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "marvelous-ui-library",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Install and update the Marvelous UI component Pack for coding agents",
   "type": "module",
   "license": "MIT",