nxds-cli 0.3.0 → 0.4.1

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { Command, CommanderError, Option } from "commander";
-import path12 from "path";
+import { Argument, Command, CommanderError, Option } from "commander";
+import path13 from "path";
 
 // ../catalog/scripts/catalog-schema.ts
 import path from "path";
@@ -178,17 +178,42 @@ function readJson(file) {
   }
 }
 
+// src/url.ts
+function httpUrl(value) {
+  const url = URL.canParse(value) ? new URL(value) : void 0;
+  return url?.protocol === "http:" || url?.protocol === "https:" ? url : void 0;
+}
+function assertRegistryUrl(flag, value, privateRegistryHint) {
+  const url = httpUrl(value);
+  if (!url) {
+    throw new UsageError(
+      `${flag} is not a valid http or https URL. ${privateRegistryHint}`
+    );
+  }
+  if (url.username || url.password || /[?#]/.test(value)) {
+    throw new UsageError(
+      `${flag} can't include a user name, password, query or fragment. nxds-cli sends no registry login, and it adds file paths to the URL. ${privateRegistryHint}`
+    );
+  }
+}
+
 // src/catalog.ts
 var SETUP = "setup";
 var DEFAULT_REGISTRY = "https://nxds.dev/r";
 var FETCH_TIMEOUT_MS = 3e4;
 var dispatcher = new EnvHttpProxyAgent();
 function isUrl(registry) {
-  return /^https?:\/\//.test(registry);
+  return /^\s*[a-z][a-z\d+.-]+:/i.test(registry);
 }
 function resolveRegistry(option) {
   if (!option) return DEFAULT_REGISTRY;
-  return isUrl(option) ? option.replace(/\/+$/, "") : path2.resolve(option);
+  if (!isUrl(option)) return path2.resolve(option);
+  assertRegistryUrl(
+    "--registry (or NXDS_REGISTRY_URL)",
+    option,
+    "For a private registry, download its latest.json and <version>.json files to a folder, and pass the folder with --registry."
+  );
+  return option.replace(/\/+$/, "");
 }
 function timeoutError(url, error) {
   if (!(error instanceof Error) || error.name !== "TimeoutError") return null;
@@ -244,7 +269,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.3.0"}. Run \`${CLI_COMMAND}\` to get the newest one.`
+      `${release} needs a newer nxds-cli than ${"0.4.1"}. Run \`${CLI_COMMAND}\` to get the newest one.`
     );
   }
   const invalid = (problems) => new CliError(
@@ -1556,13 +1581,361 @@ function report(checks) {
   };
 }
 
+// ../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();
+function redactUrl(url) {
+  const redacted = httpUrl(url);
+  if (!redacted) return "<invalid URL>";
+  redacted.username = "";
+  redacted.password = "";
+  redacted.search = "";
+  return redacted.href;
+}
+async function download(url) {
+  const shown = redactUrl(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).replaceAll(url, () => shown);
+    throw new CliError(
+      `Could not reach ${shown} (${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(
+      `${shown} 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) {
+  assertRegistryUrl(
+    "--npm-registry (or npm_config_registry)",
+    registry,
+    `For a private registry, unpack the tarball from \`npm pack ${CLAUDE_DESIGN_PACKAGE}\` and pass its package folder with --source.`
+  );
+  const url = packageUrl(registry);
+  const body = (await download(url)).toString("utf8");
+  let packument;
+  try {
+    packument = JSON.parse(body);
+  } catch {
+    throw new CliError(
+      `${redactUrl(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(
+      `${redactUrl(tarball)} has no sha512 integrity to check it against.`
+    );
+  }
+  const actual = `sha512-${createHash("sha512").update(bytes).digest("base64")}`;
+  if (actual !== expected) {
+    throw new CliError(
+      `${redactUrl(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 existsSync10, mkdirSync as mkdirSync2, writeFileSync as writeFileSync4 } from "fs";
-import path11 from "path";
+import { existsSync as existsSync11, mkdirSync as mkdirSync3, writeFileSync as writeFileSync5 } from "fs";
+import path12 from "path";
 
 // src/install.ts
-import { existsSync as existsSync9, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
-import path10 from "path";
+import { existsSync as existsSync10, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
+import path11 from "path";
 function emptyInstallResult() {
   return {
     items: [],
@@ -1578,11 +1951,11 @@ function emptyInstallResult() {
 }
 function addCssImports(project, config, files, dryRun) {
   if (files.length === 0) return [];
-  const entry = path10.join(project.root, config.css);
-  const current = existsSync9(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")}
 `);
   }
@@ -1737,9 +2110,9 @@ async function init(cwd, registry, options) {
   );
   if (!options.dryRun) {
     for (const change of wiring.changes) {
-      const target = path11.join(project.root, change.path);
-      mkdirSync2(path11.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);
   }
@@ -1848,7 +2221,7 @@ async function update(cwd, registry, options) {
     };
   }
   const orphaned = [...installedBefore].filter(
-    (file) => !current.has(file) && existsSync10(path11.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;
@@ -1899,12 +2272,13 @@ async function update(cwd, registry, options) {
 }
 
 // src/cli.ts
+function cwdOf(command) {
+  const { cwd } = command.optsWithGlobals();
+  return path13.resolve(cwd ?? process.cwd());
+}
 function context(command) {
-  const { cwd, registry } = command.optsWithGlobals();
-  return {
-    cwd: path12.resolve(cwd ?? process.cwd()),
-    registry: resolveRegistry(registry)
-  };
+  const { registry } = command.optsWithGlobals();
+  return { cwd: cwdOf(command), registry: resolveRegistry(registry) };
 }
 function installOptions(command) {
   const flags = command.opts();
@@ -1924,7 +2298,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.3.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.1", "-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)"
@@ -1978,12 +2352,35 @@ Docs: https://nxds.dev/getting-started/install`
     done(await view(cwd, registry, item));
   });
   cli.command("info").description("show what the CLI detects in this app").action((_options, command) => {
-    done(info(context(command).cwd));
+    done(info(cwdOf(command)));
   });
   cli.command("diff").description("compare your nxds files with the latest release").argument("[items...]", "item names (default: every installed item)").action(async (items, _options, command) => {
     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) => {
+    done(
+      await exportClaudeDesign(cwdOf(command), 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.3.0",
+  "version": "0.4.1",
   "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,6 +45,7 @@
     "@types/semver": "^7.8.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
+    "@nxds/claude-design": "0.8.1",
     "@nxds/catalog": "0.0.0"
   },
   "scripts": {