nxds-cli 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { Command, CommanderError, Option } from "commander";
-import path11 from "path";
+import { Argument, Command, CommanderError, Option } from "commander";
+import path13 from "path";
 
 // ../catalog/scripts/catalog-schema.ts
 import path from "path";
@@ -49,6 +49,11 @@ var setupStepSchema = z.enum([
   "wrap-root-with-provider"
 ]);
 var npmPackagesSchema = z.record(npmNameSchema, rangeSchema);
+var reactMajorSchema = z.union([z.literal(18), z.literal(19)]);
+var react18Schema = z.object({
+  files: z.array(catalogFileSchema),
+  packages: z.object({ npm: npmPackagesSchema })
+});
 function variantWith(packages) {
   return z.object({
     /** Other items this one needs, installed first. */
@@ -57,12 +62,35 @@ function variantWith(packages) {
     files: z.array(catalogFileSchema),
     /** Files in `files` the nxds CSS entry imports. */
     css: z.array(relativePathSchema),
-    steps: z.array(setupStepSchema)
+    steps: z.array(setupStepSchema),
+    react18: react18Schema.optional()
   }).refine(
     ({ css, files }) => css.every((entry) => files.some((file) => file.path === entry)),
     { path: ["css"], message: "must name files in `files`" }
+  ).refine(
+    ({ files, react18 }) => (react18?.files ?? []).every(
+      (file) => files.some((own) => own.path === file.path)
+    ),
+    {
+      path: ["react18", "files"],
+      message: "must replace files in `files`"
+    }
   );
 }
+function variantForReact(variant, react) {
+  if (react === 19 || !variant.react18) return variant;
+  const replaced = new Map(
+    variant.react18.files.map((file) => [file.path, file])
+  );
+  return {
+    ...variant,
+    files: variant.files.map((file) => replaced.get(file.path) ?? file),
+    packages: {
+      ...variant.packages,
+      npm: { ...variant.packages.npm, ...variant.react18.packages.npm }
+    }
+  };
+}
 var variantSchema = variantWith(z.object({ npm: npmPackagesSchema }));
 var setupVariantSchema = variantWith(
   z.object({
@@ -97,6 +125,8 @@ var catalogSchema = z.object({
   version: versionSchema,
   /** The frameworks the CLI installs. The docs copy also carries variants for others; a release catalog drops them. Names this version doesn't know are dropped too. */
   frameworks: z.array(z.string()).transform((frameworks) => frameworks.filter(isFramework)),
+  /** The React majors this release has files for. Releases from before React 18 support leave it out, and have React 19 files only. */
+  reactMajors: z.array(reactMajorSchema).nonempty().default([19]),
   items: z.array(catalogItemSchema)
 });
 function lines(issues, prefix) {
@@ -214,7 +244,7 @@ async function fetchRelease(registry, version) {
   if (isNewerSchema(value)) {
     const release = version === "latest" ? "The latest nxds release" : `nxds ${version}`;
     throw new CliError(
-      `${release} needs a newer nxds-cli than ${"0.2.0"}. Run \`${CLI_COMMAND}\` to get the newest one.`
+      `${release} needs a newer nxds-cli than ${"0.4.0"}. Run \`${CLI_COMMAND}\` to get the newest one.`
     );
   }
   const invalid = (problems) => new CliError(
@@ -229,11 +259,18 @@ Check \`--registry\`, or run the command again later.`
   }
   return parsed.data;
 }
-async function loadRelease(registry, version) {
+async function loadRelease(registry, version, react) {
   const catalog = await fetchRelease(registry, version);
-  if (catalog) return catalog;
+  if (!catalog) {
+    throw new CliError(
+      version === "latest" ? `${registry} has no nxds release.` : `${registry} has no nxds ${version}, the release this app is on. Run \`${CLI_COMMAND} update\` to move to the latest release.`
+    );
+  }
+  if (catalog.reactMajors.includes(react)) return catalog;
+  const latest = version === "latest" ? null : await fetchRelease(registry, "latest");
+  const fix = latest?.reactMajors.includes(react) ? `Upgrade the app to React 19, or run \`${CLI_COMMAND} update\` to move to nxds ${latest.version}, which has React ${react} files.` : "Upgrade the app to React 19.";
   throw new CliError(
-    version === "latest" ? `${registry} has no nxds release.` : `${registry} has no nxds ${version}, the release this app is on. Run \`${CLI_COMMAND} update\` to move to the latest release.`
+    `nxds ${catalog.version} has no React ${react} files. ${fix}`
   );
 }
 function findItem(catalog, name) {
@@ -248,12 +285,15 @@ function variantOf(item, framework) {
   if (variant) return variant;
   throw new CliError(`${item.title} is not available for ${framework} yet.`);
 }
-function setupVariant(catalog, framework) {
+function variantFor(item, target) {
+  return variantForReact(variantOf(item, target.framework), target.react);
+}
+function setupVariant(catalog, target) {
   const setup = catalog.items.find((item) => item.name === SETUP);
   if (setup?.kind !== "setup") {
     throw new Error(`nxds ${catalog.version} has no "${SETUP}" setup item.`);
   }
-  return variantOf(setup, framework);
+  return variantFor(setup, target);
 }
 function resolveItems(catalog, framework, names) {
   const ordered = [];
@@ -268,10 +308,10 @@ function resolveItems(catalog, framework, names) {
   names.forEach(visit);
   return ordered;
 }
-function releaseFiles(catalog, framework) {
+function releaseFiles(catalog, target) {
   return new Map(
-    catalog.items.flatMap(
-      (item) => (item.variants[framework]?.files ?? []).map(
+    catalog.items.filter((item) => item.variants[target.framework]).flatMap(
+      (item) => variantFor(item, target).files.map(
         (file) => [file.path, file.content]
       )
     )
@@ -285,6 +325,10 @@ function splitInstalled(catalog, installed) {
   };
 }
 
+// src/commands/browse.ts
+import { existsSync as existsSync5 } from "fs";
+import path6 from "path";
+
 // src/config.ts
 import { existsSync as existsSync2, writeFileSync } from "fs";
 import path3 from "path";
@@ -293,6 +337,8 @@ var CONFIG_FILE = "nxds.json";
 var configSchema = z2.looseObject({
   /** The CLI installs React only. */
   framework: z2.literal("react"),
+  /** The React major the installed files are for. */
+  react: reactMajorSchema,
   /** The nxds release every installed file comes from. */
   version: versionSchema,
   /** The nxds folder, relative to the project root. */
@@ -333,7 +379,7 @@ function writeConfig(root, config) {
 // src/project.ts
 import { existsSync as existsSync4 } from "fs";
 import path5 from "path";
-import { major, minVersion as minVersion2, validRange as validRange3 } from "semver";
+import { major, minVersion as minVersion2, parse, validRange as validRange3 } from "semver";
 
 // src/packages.ts
 import { spawnSync } from "child_process";
@@ -448,6 +494,27 @@ function readProject(root) {
 function findFile(project, candidates) {
   return firstExisting(project.root, candidates);
 }
+function reactMajor(project) {
+  const declared = project.dependencies.react;
+  if (declared === void 0) {
+    throw new CliError(
+      "This app has no react dependency. nxds needs React 18.3 or 19."
+    );
+  }
+  const installed = installedVersion(project, "react");
+  const range = validRange3(declared) === null ? null : minVersion2(declared);
+  const version = installed === null ? range : parse(installed);
+  if (version === null) {
+    throw new CliError(
+      `This app declares react ${declared}, which names no version, and none is installed. Install your dependencies, then run the command again.`
+    );
+  }
+  if (version.major >= 19) return 19;
+  if (version.major === 18 && version.minor >= 3) return 18;
+  throw new CliError(
+    `nxds needs React 18.3 or 19, and this app uses react ${version.version}. Upgrade React, then run the command again.`
+  );
+}
 function majorVersion(project, name) {
   const declared = project.dependencies[name];
   if (declared === void 0) return null;
@@ -457,8 +524,8 @@ function majorVersion(project, name) {
 }
 
 // src/commands/browse.ts
-function appRelease(cwd, registry) {
-  return loadRelease(registry, readConfig(cwd)?.version ?? "latest");
+function appRelease(registry, config, react) {
+  return loadRelease(registry, config?.version ?? "latest", react);
 }
 function summary(item) {
   return {
@@ -478,7 +545,12 @@ function summaryLines(items) {
   );
 }
 async function list(cwd, registry, kind) {
-  const items = (await appRelease(cwd, registry)).items.filter(
+  const catalog = await appRelease(
+    registry,
+    readConfig(cwd),
+    projectReact(cwd)
+  );
+  const items = catalog.items.filter(
     (item) => item.name !== SETUP && (kind === void 0 || item.kind === kind)
   );
   return { data: items.map(summary), lines: summaryLines(items), ok: true };
@@ -491,7 +563,12 @@ async function search(cwd, registry, query) {
     if (item.description.toLowerCase().includes(needle)) return 2;
     return void 0;
   };
-  const items = (await appRelease(cwd, registry)).items.filter((item) => item.name !== SETUP).flatMap((item) => {
+  const catalog = await appRelease(
+    registry,
+    readConfig(cwd),
+    projectReact(cwd)
+  );
+  const items = catalog.items.filter((item) => item.name !== SETUP).flatMap((item) => {
     const score = rank(item);
     return score === void 0 ? [] : [{ item, score }];
   }).sort((a, b) => a.score - b.score).map(({ item }) => item);
@@ -501,19 +578,28 @@ async function search(cwd, registry, query) {
     ok: true
   };
 }
-function projectFramework(cwd, catalog) {
-  const configured = readConfig(cwd)?.framework;
-  if (configured) return configured;
+function projectFramework(config, catalog) {
+  if (config) return config.framework;
   const [only, ...others] = catalog.frameworks;
   if (only && others.length === 0) return only;
   throw new CliError(
     `This release has several frameworks. Run \`${CLI_COMMAND} init\` first, so nxds knows which one your app uses.`
   );
 }
+function projectReact(cwd) {
+  if (!existsSync5(path6.join(cwd, "package.json"))) return 19;
+  const project = readProject(cwd);
+  return "react" in project.dependencies ? reactMajor(project) : 19;
+}
 async function view(cwd, registry, name) {
-  const catalog = await appRelease(cwd, registry);
+  const config = readConfig(cwd);
+  const react = projectReact(cwd);
+  const catalog = await appRelease(registry, config, react);
   const item = findItem(catalog, name);
-  const variant = variantOf(item, projectFramework(cwd, catalog));
+  const variant = variantFor(item, {
+    framework: projectFramework(config, catalog),
+    react
+  });
   const packages = Object.entries(variant.packages.npm).map(
     ([pkg, range]) => `${pkg}@${range}`
   );
@@ -573,13 +659,13 @@ function info(cwd) {
 
 // src/commands/check.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync7, readFileSync as readFileSync4 } from "fs";
-import path8 from "path";
-import { satisfies as satisfies2 } from "semver";
+import { existsSync as existsSync8, readFileSync as readFileSync4 } from "fs";
+import path9 from "path";
+import { major as major2, satisfies as satisfies2 } from "semver";
 
 // src/files.ts
-import { existsSync as existsSync5, mkdirSync, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
-import path6 from "path";
+import { existsSync as existsSync6, mkdirSync, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import path7 from "path";
 import { merge } from "node-diff3";
 function baseOf(previous, file) {
   if (!previous) return void 0;
@@ -604,13 +690,13 @@ function hasConflictMarkers(content) {
 }
 function conflictedFiles(root, config, files) {
   return [...files].filter((file) => {
-    const target = path6.join(root, config.dir, file);
-    return existsSync5(target) && hasConflictMarkers(readFileSync2(target, "utf8"));
+    const target = path7.join(root, config.dir, file);
+    return existsSync6(target) && hasConflictMarkers(readFileSync2(target, "utf8"));
   });
 }
 function fileState(root, config, file, previous) {
-  const target = path6.join(root, config.dir, file.path);
-  if (!existsSync5(target)) return "missing";
+  const target = path7.join(root, config.dir, file.path);
+  if (!existsSync6(target)) return "missing";
   const onDisk = readFileSync2(target, "utf8");
   if (hasConflictMarkers(onDisk)) return "conflicted";
   if (sameContent(onDisk, file.content)) return "current";
@@ -634,8 +720,8 @@ function writeFiles(root, config, files, previous, { overwrite, dryRun, version
   };
   const write = (file, content) => {
     if (dryRun) return;
-    const target = path6.join(root, config.dir, file);
-    mkdirSync(path6.dirname(target), { recursive: true });
+    const target = path7.join(root, config.dir, file);
+    mkdirSync(path7.dirname(target), { recursive: true });
     writeFileSync2(target, content);
   };
   for (const file of files) {
@@ -658,7 +744,7 @@ function writeFiles(root, config, files, previous, { overwrite, dryRun, version
       result.skipped.push(file.path);
       continue;
     }
-    const target = path6.join(root, config.dir, file.path);
+    const target = path7.join(root, config.dir, file.path);
     const ours = readFileSync2(target, "utf8");
     const merged = mergeFile(ours, base, file.content, version);
     if (sameContent(ours, merged.content)) {
@@ -671,7 +757,7 @@ function writeFiles(root, config, files, previous, { overwrite, dryRun, version
   return result;
 }
 function relativeImport(fromFile, toFile) {
-  const relative = path6.relative(path6.dirname(fromFile), toFile).split(path6.sep).join("/");
+  const relative = path7.relative(path7.dirname(fromFile), toFile).split(path7.sep).join("/");
   return relative.startsWith(".") ? relative : `./${relative}`;
 }
 
@@ -687,11 +773,11 @@ import {
   isObjectProperty,
   isSpreadElement
 } from "@babel/types";
-import { existsSync as existsSync6, readFileSync as readFileSync3 } from "fs";
-import path7 from "path";
+import { existsSync as existsSync7, readFileSync as readFileSync3 } from "fs";
+import path8 from "path";
 
 // src/setup/source-edit.ts
-import { parse } from "@babel/parser";
+import { parse as parse2 } from "@babel/parser";
 import {
   isImportDeclaration,
   isJSXAttribute,
@@ -701,7 +787,7 @@ import {
 } from "@babel/types";
 function parseModule(source, file) {
   try {
-    return parse(source, {
+    return parse2(source, {
       sourceType: "module",
       plugins: ["typescript", "jsx"]
     }).program;
@@ -794,7 +880,7 @@ function tailwindPackages(setup, range) {
 }
 function appDir(project) {
   const dir = APP_DIRS.find(
-    (candidate) => existsSync6(path7.join(project.root, candidate, "layout.tsx"))
+    (candidate) => existsSync7(path8.join(project.root, candidate, "layout.tsx"))
   );
   if (!dir)
     throw new CliError("No app/layout.tsx or src/app/layout.tsx found.");
@@ -810,7 +896,7 @@ function cssEntryPath(project) {
   return `${entryDir(project)}/nxds.css`;
 }
 function read(project, file) {
-  return readFileSync3(path7.join(project.root, file), "utf8");
+  return readFileSync3(path8.join(project.root, file), "utf8");
 }
 function cssEntry(config, withPreflight) {
   const tokens = relativeImport(config.css, `${config.dir}/tailwind/nxds.css`);
@@ -1021,9 +1107,9 @@ var NXDS_VITE_PLUGIN = {
 var VITE_ALIAS = "{ '@': '/src' }";
 function wireViteConfig(project, addTailwind, steps) {
   const configFile = findFile(project, VITE_CONFIGS) ?? "vite.config.ts";
-  const addScript = steps.has("add-head-script") && !existsSync6(path7.join(project.root, "nxds.vite.ts"));
+  const addScript = steps.has("add-head-script") && !existsSync7(path8.join(project.root, "nxds.vite.ts"));
   const changes = addScript ? [{ path: "nxds.vite.ts", content: VITE_PLUGIN, created: true }] : [];
-  const source = existsSync6(path7.join(project.root, configFile)) ? read(project, configFile) : "";
+  const source = existsSync7(path8.join(project.root, configFile)) ? read(project, configFile) : "";
   const program2 = source ? parseModule(source, configFile) : void 0;
   const object = program2 && configObject(program2);
   const plugins = object && pluginsArray(object);
@@ -1184,7 +1270,7 @@ function wireNextTailwind(project) {
   };
 }
 function createdUnlessExists(project, file, content) {
-  if (existsSync6(path7.join(project.root, file))) return NO_CHANGES;
+  if (existsSync7(path8.join(project.root, file))) return NO_CHANGES;
   return { changes: [{ path: file, content, created: true }], manual: [] };
 }
 function planWiring(project, config, addTailwind, setupSteps) {
@@ -1221,9 +1307,10 @@ function planWiring(project, config, addTailwind, setupSteps) {
 // src/commands/check.ts
 async function diff(cwd, registry, names) {
   const config = requireConfig(cwd);
-  const latest = await loadRelease(registry, "latest");
+  const target = { ...config, react: reactMajor(readProject(cwd)) };
+  const latest = await loadRelease(registry, "latest", target.react);
   const previous = await fetchRelease(registry, config.version);
-  const previousFiles = previous && releaseFiles(previous, config.framework);
+  const previousFiles = previous && releaseFiles(previous, config);
   const { known, removed } = splitInstalled(latest, config.items);
   const items = resolveItems(
     latest,
@@ -1248,7 +1335,7 @@ async function diff(cwd, registry, names) {
     return `has your edits; ${update2} merges nxds's changes into it, ${overwrite} replaces it`;
   }
   const files = items.flatMap(
-    (item) => variantOf(item, config.framework).files.map((file) => {
+    (item) => variantFor(item, target).files.map((file) => {
       const state = fileState(cwd, config, file, previousFiles);
       return {
         item: item.name,
@@ -1286,14 +1373,14 @@ function tailwindMessage(project) {
   return `tailwindcss ${declared}. nxds needs Tailwind CSS 4.`;
 }
 function read2(root, file) {
-  if (!file || !existsSync7(path8.join(root, file))) return "";
-  return readFileSync4(path8.join(root, file), "utf8");
+  if (!file || !existsSync8(path9.join(root, file))) return "";
+  return readFileSync4(path9.join(root, file), "utf8");
 }
 function sourcesNxdsDir(config, css) {
-  const entryDir2 = path8.posix.dirname(config.css);
+  const entryDir2 = path9.posix.dirname(config.css);
   return [...css.matchAll(/@source\s+(['"])(.*?)\1/g)].some(([, , source]) => {
     const base = (source ?? "").split(/[*{[]/)[0] ?? "";
-    const folder = path8.posix.join(entryDir2, base).replace(/\/+$/, "");
+    const folder = path9.posix.join(entryDir2, base).replace(/\/+$/, "");
     return folder === "." || /^\.\.(\/\.\.)*$/.test(folder) || config.dir === folder || config.dir.startsWith(`${folder}/`);
   });
 }
@@ -1307,10 +1394,42 @@ function unscannedReason(cwd, config, css) {
   }
   return null;
 }
+function installedMajor(project, name) {
+  const version = installedVersion(project, name);
+  return version === null ? null : major2(version);
+}
+function reactChecks(project, config) {
+  let react;
+  try {
+    react = reactMajor(project);
+  } catch (error) {
+    if (!(error instanceof CliError)) throw error;
+    return [{ name: "react", ok: false, message: error.message }];
+  }
+  const checks = [
+    {
+      name: "react",
+      ok: config.react === react,
+      message: config.react === react ? `The files are for React ${react}, which this app uses` : `The files are for React ${config.react}, and this app uses React ${react}. Run \`${CLI_COMMAND} update\` to switch them.`
+    }
+  ];
+  const reactInstalled = installedMajor(project, "react");
+  if (reactInstalled === null) return checks;
+  for (const name of ["react-dom", "@types/react", "@types/react-dom"]) {
+    if (name.startsWith("@types/") && !(name in project.dependencies)) continue;
+    const installed = installedMajor(project, name);
+    checks.push({
+      name,
+      ok: installed === reactInstalled,
+      message: installed === null ? `${name} is not installed` : installed === reactInstalled ? `${name} ${installed} matches react ${reactInstalled}` : `${name} ${installed} is installed with react ${reactInstalled}. Install the same major as react.`
+    });
+  }
+  return checks;
+}
 function packageProblems(project, config, items) {
   const needed = Object.assign(
     {},
-    ...items.map((item) => variantOf(item, config.framework).packages.npm)
+    ...items.map((item) => variantFor(item, config).packages.npm)
   );
   return Object.entries(needed).flatMap(([name, range]) => {
     if (!(name in project.dependencies))
@@ -1350,6 +1469,7 @@ async function doctor(cwd, registry) {
     majorVersion(project, "tailwindcss") === 4,
     tailwindMessage(project)
   );
+  checks.push(...reactChecks(project, config));
   const css = read2(cwd, config.css);
   const importsTokens = css.includes("tailwind/nxds.css");
   check(
@@ -1365,7 +1485,7 @@ async function doctor(cwd, registry) {
   );
   const entry = project.setup === "next-app" ? `${entryDir(project)}/layout.tsx` : findFile(project, VITE_ENTRIES);
   const entrySource = read2(cwd, entry);
-  const cssFile = path8.basename(config.css);
+  const cssFile = path9.basename(config.css);
   const importsCss = entrySource.includes(cssFile);
   check(
     "css import",
@@ -1393,8 +1513,8 @@ async function doctor(cwd, registry) {
   );
   const items = resolveItems(catalog, config.framework, known);
   const missingFiles = items.flatMap(
-    (item) => variantOf(item, config.framework).files.filter(
-      (file) => !existsSync7(path8.join(cwd, config.dir, file.path))
+    (item) => variantFor(item, config).files.filter(
+      (file) => !existsSync8(path9.join(cwd, config.dir, file.path))
     ).map((file) => `${item.name}: ${file.path}`)
   );
   check(
@@ -1406,7 +1526,7 @@ async function doctor(cwd, registry) {
     cwd,
     config,
     items.flatMap(
-      (item) => variantOf(item, config.framework).files.map((file) => file.path)
+      (item) => variantFor(item, config).files.map((file) => file.path)
     )
   ).map((file) => `${config.dir}/${file}`);
   check(
@@ -1436,13 +1556,347 @@ function report(checks) {
   };
 }
 
-// src/commands/install.ts
-import { existsSync as existsSync9, mkdirSync as mkdirSync2, writeFileSync as writeFileSync4 } from "fs";
+// ../claude-design/src/system-index.ts
+var IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+var PAGE_PATHS = ["manifest.json", "api/"];
+function mergeSystemIndex(current, exported) {
+  return {
+    ...current,
+    namespace: exported.namespace,
+    editing: exported.editing,
+    libraries: exported.libraries,
+    lastChange: exported.lastChange
+  };
+}
+function isPageGenerated(file) {
+  return PAGE_PATHS.some((page) => file === page || file.startsWith(page));
+}
+function validateIndex(index) {
+  const where = "design-system.json";
+  const errors = [];
+  if (index["v"] !== 3 || index["layout"] !== "files") {
+    errors.push(`${where}: needs "v": 3 and "layout": "files".`);
+  }
+  if (!index["createdOnFiles"] && !index["convertedFrom"]) {
+    errors.push(`${where}: needs the createdOnFiles marker.`);
+  }
+  if (typeof index["title"] !== "string" || !index["title"]) {
+    errors.push(`${where}: needs a title.`);
+  }
+  if (typeof index["namespace"] !== "string" || !IDENTIFIER.test(index["namespace"])) {
+    errors.push(`${where}: namespace must be a JS identifier.`);
+  }
+  const lastChange = index["lastChange"];
+  if (!lastChange || typeof lastChange["by"] !== "string" || Number.isNaN(Date.parse(String(lastChange["at"])))) {
+    errors.push(`${where}: lastChange needs "by" and an ISO-8601 "at".`);
+  }
+  return errors;
+}
+
+// src/commands/export.ts
+import { createHash } from "crypto";
+import {
+  existsSync as existsSync9,
+  lstatSync,
+  mkdirSync as mkdirSync2,
+  mkdtempSync,
+  readdirSync,
+  readFileSync as readFileSync5,
+  renameSync,
+  rmSync,
+  writeFileSync as writeFileSync3
+} from "fs";
+import { tmpdir } from "os";
 import path10 from "path";
+import { x as extract } from "tar";
+import { EnvHttpProxyAgent as EnvHttpProxyAgent2, fetch as fetch2 } from "undici";
+var CLAUDE_DESIGN_PACKAGE = "@nxds/claude-design";
+var DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
+var DEFAULT_EXPORT_DIR = "nxds-design-system";
+var FETCH_TIMEOUT_MS2 = 6e4;
+var dispatcher2 = new EnvHttpProxyAgent2();
+async function download(url) {
+  let response;
+  try {
+    response = await fetch2(url, {
+      dispatcher: dispatcher2,
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS2)
+    });
+  } catch (error) {
+    const { message, cause } = error;
+    const reason = cause instanceof Error ? cause.message : message;
+    throw new CliError(
+      `Could not reach ${url} (${reason}). Check your connection, or set HTTPS_PROXY if you are behind a proxy, then run the command again.`
+    );
+  }
+  if (!response.ok) {
+    throw new CliError(
+      `${url} answered ${response.status}. Run the command again later.`
+    );
+  }
+  return Buffer.from(await response.arrayBuffer());
+}
+function packageUrl(registry) {
+  return `${registry.replace(/\/+$/, "")}/${CLAUDE_DESIGN_PACKAGE.replace("/", "%2f")}`;
+}
+async function resolveTarball(registry, release) {
+  const url = packageUrl(registry);
+  const body = (await download(url)).toString("utf8");
+  let packument;
+  try {
+    packument = JSON.parse(body);
+  } catch {
+    throw new CliError(
+      `${url} didn't answer with JSON. Check --npm-registry, or your proxy, then run the command again.`
+    );
+  }
+  const version = packument["dist-tags"]?.[release] ?? release;
+  const dist = packument.versions?.[version]?.dist;
+  if (!dist?.tarball || !dist.integrity) {
+    const known = Object.keys(packument.versions ?? {}).slice(-5).join(", ");
+    throw new UsageError(
+      `${CLAUDE_DESIGN_PACKAGE} has no release ${release}. Recent releases: ${known || "none"}.`
+    );
+  }
+  return { version, tarball: dist.tarball, integrity: dist.integrity };
+}
+function checkIntegrity(bytes, integrity, tarball) {
+  const expected = integrity.split(/\s+/).find((entry) => entry.startsWith("sha512-"));
+  if (!expected) {
+    throw new CliError(
+      `${tarball} has no sha512 integrity to check it against.`
+    );
+  }
+  const actual = `sha512-${createHash("sha512").update(bytes).digest("base64")}`;
+  if (actual !== expected) {
+    throw new CliError(
+      `${tarball} doesn't match its published integrity. Run the command again; if it keeps failing, report it.`
+    );
+  }
+}
+async function fetchPackage(registry, release) {
+  const { version, tarball, integrity } = await resolveTarball(
+    registry,
+    release
+  );
+  const bytes = await download(tarball);
+  checkIntegrity(bytes, integrity, tarball);
+  const folder = mkdtempSync(path10.join(tmpdir(), "nxds-claude-design-"));
+  const cleanup = () => rmSync(folder, { recursive: true, force: true });
+  try {
+    const file = path10.join(folder, "package.tgz");
+    writeFileSync3(file, bytes);
+    const unpacked = path10.join(folder, "package");
+    mkdirSync2(unpacked);
+    await extract({
+      file,
+      cwd: unpacked,
+      strip: 1,
+      filter: (_, entry) => "type" in entry && (entry.type === "File" || entry.type === "Directory")
+    });
+    return { version, root: unpacked, cleanup };
+  } catch (error) {
+    cleanup();
+    throw error;
+  }
+}
+function localPackage(source) {
+  if (!existsSync9(path10.join(source, "project"))) {
+    throw new UsageError(
+      `${source} has no project/ folder. Point --source at a built @nxds/claude-design dist folder.`
+    );
+  }
+  const manifest = existsSync9(path10.join(source, "package.json")) ? readJson(path10.join(source, "package.json")) : {};
+  return {
+    version: manifest.version ?? "local",
+    root: source,
+    cleanup: () => {
+    }
+  };
+}
+function assertWritable(out, overwrite) {
+  if (!existsSync9(out) || readdirSync(out).length === 0 || overwrite) return;
+  throw new UsageError(
+    `${out} already has files. Pass --overwrite to replace its project/ folder, or choose another --out.`
+  );
+}
+function readPaths(file) {
+  const value = readJson(file);
+  if (!Array.isArray(value) || !value.every((entry) => typeof entry === "string")) {
+    throw new UsageError(
+      `${file} must be a JSON array of the system's file paths.`
+    );
+  }
+  return value;
+}
+function stalePaths(existing, exported) {
+  return existing.filter((file) => file.startsWith("project/")).filter((file) => !isPageGenerated(file.slice("project/".length))).filter((file) => !exported.has(file)).sort();
+}
+function readManifest(root) {
+  const file = path10.join(root, "files.json");
+  if (!existsSync9(file)) {
+    throw new CliError(
+      `${root} has no files.json. Export from an @nxds/claude-design release or a built dist folder.`
+    );
+  }
+  const value = readJson(file);
+  if (!Array.isArray(value) || !value.every(
+    (entry) => typeof entry?.path === "string" && typeof entry.sha256 === "string"
+  )) {
+    throw new CliError(
+      `${file} must be a JSON array of { path, sha256 } entries.`
+    );
+  }
+  return value;
+}
+function readProject2(root) {
+  const projectDir = path10.join(root, "project");
+  const files = /* @__PURE__ */ new Map();
+  for (const entry of readManifest(root)) {
+    const file = path10.join(projectDir, entry.path);
+    const relative = path10.relative(projectDir, file);
+    if (relative.split(path10.sep)[0] === ".." || path10.isAbsolute(relative)) {
+      throw new CliError(`files.json lists ${entry.path}, outside project/.`);
+    }
+    if (!existsSync9(file) || !lstatSync(file).isFile()) {
+      throw new CliError(
+        `project/${entry.path} is missing from the release, or isn't a regular file.`
+      );
+    }
+    const bytes = readFileSync5(file);
+    if (createHash("sha256").update(bytes).digest("hex") !== entry.sha256) {
+      throw new CliError(
+        `project/${entry.path} doesn't match the release's files.json, so nothing was written.`
+      );
+    }
+    files.set(entry.path, bytes);
+  }
+  return files;
+}
+function mergeIndex(files, currentFile) {
+  const exported = files.get("design-system.json");
+  if (!exported) throw new CliError("The release has no design-system.json.");
+  const merged = mergeSystemIndex(
+    readJson(currentFile),
+    JSON.parse(exported.toString("utf8"))
+  );
+  const errors = validateIndex(merged);
+  if (errors.length > 0) {
+    throw new UsageError(
+      `${currentFile} merges into an index the page can't read, so nothing was written:
+${errors.map((error) => `  ${error}`).join("\n")}`
+    );
+  }
+  files.set(
+    "design-system.json",
+    Buffer.from(`${JSON.stringify(merged, null, 2)}
+`)
+  );
+}
+function writeProject(out, files) {
+  mkdirSync2(out, { recursive: true });
+  const staging = makeStaging(path10.dirname(out), out);
+  const next = path10.join(staging, "next");
+  const previous = path10.join(staging, "previous");
+  const projectDir = path10.join(out, "project");
+  try {
+    for (const [file, bytes] of files) {
+      mkdirSync2(path10.dirname(path10.join(next, file)), { recursive: true });
+      writeFileSync3(path10.join(next, file), bytes);
+    }
+    if (existsSync9(projectDir)) renameSync(projectDir, previous);
+    renameSync(next, projectDir);
+  } catch (error) {
+    restore(previous, projectDir, error);
+    rmSync(staging, { recursive: true, force: true });
+    throw renameError(error, out);
+  }
+  rmSync(staging, { recursive: true, force: true });
+}
+function makeStaging(parent, out) {
+  try {
+    return mkdtempSync(path10.join(parent, ".nxds-project-"));
+  } catch (error) {
+    const { code, message } = error;
+    if (code !== "EACCES" && code !== "EPERM" && code !== "EROFS") throw error;
+    throw new UsageError(
+      `The export stages project/ in ${parent}, beside ${out}, so ${parent} must be writable (${message}).`
+    );
+  }
+}
+function restore(previous, projectDir, cause) {
+  if (!existsSync9(previous)) return;
+  try {
+    renameSync(previous, projectDir);
+  } catch (error) {
+    throw new CliError(
+      `The export failed (${cause.message}) and couldn't put the old project/ back (${error.message}). It is in ${previous}.`
+    );
+  }
+}
+function renameError(error, out) {
+  if (error.code !== "EXDEV") return error;
+  return new UsageError(
+    `${out} is on another filesystem from its parent folder, so project/ can't be moved into it. Pass an --out folder inside ${out}.`
+  );
+}
+async function exportClaudeDesign(cwd, options) {
+  const out = path10.resolve(cwd, options.out ?? DEFAULT_EXPORT_DIR);
+  assertWritable(out, options.overwrite);
+  const pkg = options.source ? localPackage(path10.resolve(cwd, options.source)) : await fetchPackage(
+    options.npmRegistry ?? DEFAULT_NPM_REGISTRY,
+    options.release ?? "latest"
+  );
+  try {
+    const files = readProject2(pkg.root);
+    if (options.index) mergeIndex(files, path10.resolve(cwd, options.index));
+    const exported = new Set(
+      [...files.keys()].map((file) => `project/${file}`)
+    );
+    const removed = options.existing ? stalePaths(readPaths(path10.resolve(cwd, options.existing)), exported) : [];
+    const coverageFile = path10.join(pkg.root, "coverage.md");
+    const coverage = existsSync9(coverageFile) ? readFileSync5(coverageFile) : void 0;
+    writeProject(out, files);
+    if (coverage) writeFileSync3(path10.join(out, "coverage.md"), coverage);
+    if (options.existing) {
+      writeFileSync3(
+        path10.join(out, "removed.json"),
+        `${JSON.stringify(removed, null, 2)}
+`
+      );
+    }
+    const relative = path10.relative(cwd, out) || ".";
+    const lines2 = [
+      `Exported nxds ${pkg.version} as a Claude Design System: ${files.size} files in ${path10.join(relative, "project")}.`,
+      `Publish ${relative} as a Design System artifact in Claude, with ${relative} as the root.`
+    ];
+    if (removed.length > 0) {
+      lines2.push(
+        `Remove the ${removed.length} files the system has and this release doesn't: they're listed in ${path10.join(relative, "removed.json")}.`
+      );
+    }
+    if (coverage) {
+      lines2.push(
+        `The props the canvas can't set are in ${path10.join(relative, "coverage.md")}.`
+      );
+    }
+    return {
+      ok: true,
+      lines: lines2,
+      data: { version: pkg.version, out, files: files.size, removed }
+    };
+  } finally {
+    pkg.cleanup();
+  }
+}
+
+// src/commands/install.ts
+import { existsSync as existsSync11, mkdirSync as mkdirSync3, writeFileSync as writeFileSync5 } from "fs";
+import path12 from "path";
 
 // src/install.ts
-import { existsSync as existsSync8, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
-import path9 from "path";
+import { existsSync as existsSync10, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
+import path11 from "path";
 function emptyInstallResult() {
   return {
     items: [],
@@ -1458,11 +1912,11 @@ function emptyInstallResult() {
 }
 function addCssImports(project, config, files, dryRun) {
   if (files.length === 0) return [];
-  const entry = path9.join(project.root, config.css);
-  const current = existsSync8(entry) ? readFileSync5(entry, "utf8") : "";
+  const entry = path11.join(project.root, config.css);
+  const current = existsSync10(entry) ? readFileSync6(entry, "utf8") : "";
   const added = [...new Set(files)].map((file) => cssImportLine(config, file)).filter((line) => !current.includes(line));
   if (added.length > 0 && !dryRun) {
-    writeFileSync3(entry, `${current.trimEnd()}
+    writeFileSync4(entry, `${current.trimEnd()}
 ${added.join("\n")}
 `);
   }
@@ -1470,7 +1924,7 @@ ${added.join("\n")}
 }
 function installItems(catalog, project, config, names, previous, options) {
   const items = resolveItems(catalog, config.framework, names);
-  const variants = items.map((item) => variantOf(item, config.framework));
+  const variants = items.map((item) => variantFor(item, config));
   const files = new Map(
     variants.flatMap((variant) => variant.files).map((file) => [file.path, file])
   );
@@ -1536,6 +1990,12 @@ function installLines(config, result, options) {
 function settled(result) {
   return result.skipped.length === 0 && result.conflicted.length === 0 && result.unresolved.length === 0;
 }
+function assertFilesMatchReact(config, react) {
+  if (config.react === react) return;
+  throw new CliError(
+    `nxds.json has React ${config.react} files, and this app uses React ${react}. Run \`${CLI_COMMAND} update\` to switch them, then run this command again.`
+  );
+}
 function nxdsDir(dir) {
   const normalized = relativePath(dir);
   if (normalized) return normalized;
@@ -1568,11 +2028,17 @@ async function init(cwd, registry, options) {
       "nxds components are TypeScript. Add a tsconfig.json to your app, then run init again."
     );
   }
+  const react = reactMajor(project);
   const addTailwind = !("tailwindcss" in project.dependencies);
   if (!addTailwind) assertTailwind4(project);
   const dir = options.dir ? nxdsDir(options.dir) : void 0;
   const existing = readConfig(cwd);
-  const catalog = await loadRelease(registry, existing?.version ?? "latest");
+  const catalog = await loadRelease(
+    registry,
+    existing?.version ?? "latest",
+    react
+  );
+  if (existing) assertFilesMatchReact(existing, react);
   if (existing && dir && dir !== existing.dir) {
     throw new CliError(
       `nxds is already set up in ${existing.dir}. Run init without --dir, or move the folder and change "dir" in nxds.json.`
@@ -1580,12 +2046,13 @@ async function init(cwd, registry, options) {
   }
   const config = existing ?? {
     framework: "react",
+    react,
     version: catalog.version,
     dir: dir ?? defaultDir(project),
     css: cssEntryPath(project),
     items: []
   };
-  const setup = setupVariant(catalog, config.framework);
+  const setup = setupVariant(catalog, config);
   const wiring = planWiring(project, config, addTailwind, setup.steps);
   const tailwind = packagesToInstall(
     project,
@@ -1604,9 +2071,9 @@ async function init(cwd, registry, options) {
   );
   if (!options.dryRun) {
     for (const change of wiring.changes) {
-      const target = path10.join(project.root, change.path);
-      mkdirSync2(path10.dirname(target), { recursive: true });
-      writeFileSync4(target, change.content);
+      const target = path12.join(project.root, change.path);
+      mkdirSync3(path12.dirname(target), { recursive: true });
+      writeFileSync5(target, change.content);
     }
     writeConfig(cwd, config);
   }
@@ -1616,6 +2083,7 @@ async function init(cwd, registry, options) {
   return {
     data: {
       setup: project.setup,
+      react: config.react,
       version: config.version,
       dir: config.dir,
       css: config.css,
@@ -1627,7 +2095,7 @@ async function init(cwd, registry, options) {
       manual: wiring.manual
     },
     lines: [
-      `nxds ${config.version} in ${config.dir}`,
+      `nxds ${config.version} in ${config.dir}, for React ${config.react}`,
       ...installLines(config, { ...installed, packages }, options),
       ...wiring.changes.map(
         (change) => `${change.created ? createVerb : editVerb} ${change.path}`
@@ -1649,10 +2117,12 @@ function manualLines(manual) {
 }
 async function add(cwd, registry, names, options) {
   const config = requireConfig(cwd);
-  const catalog = await loadRelease(registry, config.version);
+  const project = readProject(cwd);
+  assertFilesMatchReact(config, reactMajor(project));
+  const catalog = await loadRelease(registry, config.version, config.react);
   const installed = installItems(
     catalog,
-    readProject(cwd),
+    project,
     config,
     names,
     null,
@@ -1670,32 +2140,34 @@ async function add(cwd, registry, names, options) {
     ok: settled(installed)
   };
 }
-function filesOf(catalog, framework, names) {
+function filesOf(catalog, target, names) {
   return new Set(
-    resolveItems(catalog, framework, names).flatMap(
-      (item) => variantOf(item, framework).files.map((file) => file.path)
+    resolveItems(catalog, target.framework, names).flatMap(
+      (item) => variantFor(item, target).files.map((file) => file.path)
     )
   );
 }
 async function update(cwd, registry, options) {
   const config = requireConfig(cwd);
+  const project = readProject(cwd);
   const from = config.version;
-  const latest = await loadRelease(registry, "latest");
+  const fromReact = config.react;
+  const react = reactMajor(project);
+  const latest = await loadRelease(registry, "latest", react);
   const { known, removed } = splitInstalled(latest, config.items);
-  const current = filesOf(latest, config.framework, known);
+  const current = filesOf(latest, { ...config, react }, known);
   const previous = await fetchRelease(registry, from);
-  const installedBefore = previous ? filesOf(
-    previous,
-    config.framework,
-    splitInstalled(previous, config.items).known
-  ) : /* @__PURE__ */ new Set();
-  const unresolved = from === latest.version || options.overwrite ? [] : conflictedFiles(cwd, config, /* @__PURE__ */ new Set([...current, ...installedBefore]));
+  const installedBefore = previous ? filesOf(previous, config, splitInstalled(previous, config.items).known) : /* @__PURE__ */ new Set();
+  const unchanged = from === latest.version && fromReact === react;
+  const unresolved = unchanged || options.overwrite ? [] : conflictedFiles(cwd, config, /* @__PURE__ */ new Set([...current, ...installedBefore]));
   if (unresolved.length > 0) {
     const data2 = {
       ...emptyInstallResult(),
       dryRun: options.dryRun,
       from,
       version: from,
+      fromReact,
+      react: fromReact,
       unresolved,
       removed: [],
       orphaned: []
@@ -1710,24 +2182,30 @@ async function update(cwd, registry, options) {
     };
   }
   const orphaned = [...installedBefore].filter(
-    (file) => !current.has(file) && existsSync9(path10.join(cwd, config.dir, file))
+    (file) => !current.has(file) && existsSync11(path12.join(cwd, config.dir, file))
   );
+  const previousFiles = previous && releaseFiles(previous, config);
   config.items = known;
   const installed = installItems(
     latest,
-    readProject(cwd),
-    config,
+    project,
+    { ...config, react },
     known,
-    previous && releaseFiles(previous, config.framework),
+    previousFiles,
     options
   );
-  const stays = from !== latest.version && installed.skipped.length > 0;
-  if (!stays) config.version = latest.version;
+  const stays = !unchanged && installed.skipped.length > 0;
+  if (!stays) {
+    config.version = latest.version;
+    config.react = react;
+  }
   if (!options.dryRun) writeConfig(cwd, config);
   const data = {
     dryRun: options.dryRun,
     from,
     version: config.version,
+    fromReact,
+    react: config.react,
     ...installed,
     removed,
     orphaned
@@ -1745,6 +2223,9 @@ async function update(cwd, registry, options) {
       ...orphaned.map(
         (file) => `No installed item uses ${config.dir}/${file} any more. Delete it once nothing in your app imports it.`
       ),
+      ...fromReact !== react && !stays ? [
+        `${options.dryRun ? "Would switch" : "Switched"} the files from React ${fromReact} to React ${react}.`
+      ] : [],
       stays ? `nxds.json stays on ${from} until every file above is resolved or replaced.` : `nxds ${from === latest.version ? "is on" : `${options.dryRun ? "would move" : "moved"} from ${from} to`} ${latest.version}.`
     ],
     ok: settled(installed)
@@ -1755,7 +2236,7 @@ async function update(cwd, registry, options) {
 function context(command) {
   const { cwd, registry } = command.optsWithGlobals();
   return {
-    cwd: path11.resolve(cwd ?? process.cwd()),
+    cwd: path13.resolve(cwd ?? process.cwd()),
     registry: resolveRegistry(registry)
   };
 }
@@ -1777,7 +2258,7 @@ function program(done, write) {
     // Errors are printed once, by `main`, as text or JSON.
     outputError: () => {
     }
-  }).exitOverride().name(CLI_COMMAND).description("Add nxds to your app.").version("0.2.0", "-v, --version", "print the version").helpOption("-h, --help", "show help").helpCommand("help [command]", "show help for a command").option("--json", "print machine-readable JSON").option("--cwd <path>", "run in another folder").addOption(
+  }).exitOverride().name(CLI_COMMAND).description("Add nxds to your app.").version("0.4.0", "-v, --version", "print the version").helpOption("-h, --help", "show help").helpCommand("help [command]", "show help for a command").option("--json", "print machine-readable JSON").option("--cwd <path>", "run in another folder").addOption(
     new Option(
       "--registry <url|path>",
       "where to get nxds releases (default: https://nxds.dev/r)"
@@ -1837,6 +2318,28 @@ Docs: https://nxds.dev/getting-started/install`
     const { cwd, registry } = context(command);
     done(await diff(cwd, registry, items));
   });
+  cli.command("export").description(
+    "export nxds as a Claude Design System folder, ready to publish"
+  ).addArgument(
+    new Argument("<target>", "what to export").choices(["claude-design"])
+  ).option("--out <path>", `folder to write (default: ${DEFAULT_EXPORT_DIR})`).option("--release <version>", "nxds release to export (default: latest)").option(
+    "--index <path>",
+    "the system's current design-system.json, to keep its title and creation date"
+  ).option(
+    "--existing <path>",
+    "a JSON list of the system's current file paths, to list the ones this release removes"
+  ).option("--overwrite", "replace the project/ folder in --out", false).option(
+    "--source <path>",
+    "a built @nxds/claude-design dist folder, instead of the npm release"
+  ).addOption(
+    new Option(
+      "--npm-registry <url>",
+      `npm registry to download from (default: ${DEFAULT_NPM_REGISTRY})`
+    ).env("npm_config_registry")
+  ).action(async (_target, _options, command) => {
+    const { cwd } = context(command);
+    done(await exportClaudeDesign(cwd, command.opts()));
+  });
   cli.command("doctor").description("check that nxds is wired up correctly").action(async (_options, command) => {
     const { cwd, registry } = context(command);
     done(await doctor(cwd, registry));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nxds-cli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Install nxds components, blocks and setup into your app.",
   "keywords": [
@@ -36,6 +36,7 @@
     "commander": "^14.0.3",
     "node-diff3": "^3.2.1",
     "semver": "^7.8.5",
+    "tar": "^7.5.22",
     "undici": "^7.30.1",
     "zod": "^4.6.7"
   },
@@ -44,7 +45,8 @@
     "@types/semver": "^7.8.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "@nxds/catalog": "0.0.0"
+    "@nxds/catalog": "0.0.0",
+    "@nxds/claude-design": "0.6.0"
   },
   "scripts": {
     "build": "tsup",