nxds-cli 0.6.0 → 0.7.0

package/dist/index.js

@@ -1,5 +1,15 @@
 #!/usr/bin/env node
 
+// ../claude-design/src/theme-fields.ts
+var isExportThemeFlag = (flag) => flag !== "mode" && flag !== "icons";
+function shellValue(value) {
+  if (/^[\w.-]+$/.test(value)) return value;
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function formatThemeFlags(flags) {
+  return flags.map(({ flag, value }) => `--${flag} ${shellValue(value)}`).join(" ");
+}
+
 // ../../node_modules/culori/src/rgb/parseNumber.js
 var parseNumber = (color, len) => {
   if (typeof color !== "number") return;
@@ -3829,6 +3839,9 @@ for (const pair of APCA_PAIRS) {
   group.pairs.push(pair);
 }
 
+// ../core/src/lib/typography-scale.ts
+var TYPOGRAPHY_BASE_PX = 14;
+
 // ../core/src/lib/appearance-model.ts
 var DEFAULT_BRAND_COLOR = "#0a0a0a";
 var BASE_TONE_OPTIONS = [
@@ -3879,7 +3892,7 @@ var DEFAULT_NXDS_APPEARANCE = {
     uiFont: '-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
     headingFont: null,
     codeFont: 'ui-monospace, "SF Mono", Menlo, monospace',
-    uiFontSize: 14,
+    uiFontSize: TYPOGRAPHY_BASE_PX,
     codeFontSize: 12,
     reduceMotion: false,
     pointerCursors: false,
@@ -4543,7 +4556,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.6.0"}. Run \`${CLI_COMMAND}\` to get the newest one.`
+      `${release} needs a newer nxds-cli than ${"0.7.0"}. Run \`${CLI_COMMAND}\` to get the newest one.`
     );
   }
   const invalid2 = (problems) => new CliError(
@@ -6123,14 +6136,18 @@ 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,
+function mergeSystemIndex(current, exported, { retitle }) {
+  const { theme: _theme, ...kept } = current;
+  const merged = {
+    ...kept,
     namespace: exported.namespace,
     editing: exported.editing,
     libraries: exported.libraries,
     lastChange: exported.lastChange
   };
+  if (retitle) merged["title"] = exported.title;
+  if (exported.theme) merged["theme"] = exported.theme;
+  return merged;
 }
 function isPageGenerated(file) {
   return PAGE_PATHS.some((page) => file === page || file.startsWith(page));
@@ -6179,6 +6196,7 @@ var DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
 var DEFAULT_EXPORT_DIR = "nxds-design-system";
 var FETCH_TIMEOUT_MS2 = 6e4;
 var dispatcher2 = new EnvHttpProxyAgent2();
+var THEME_FILE = "theme.js";
 function redactUrl(url) {
   const redacted = httpUrl(url);
   if (!redacted) return "<invalid URL>";
@@ -6310,6 +6328,11 @@ function readPaths(file) {
 function stalePaths(existing, exported) {
   return existing.filter((file) => file.startsWith("project/")).filter((file) => !isPageGenerated(file.slice("project/".length))).filter((file) => !exported.has(file)).sort();
 }
+var EXPORT_NAMES = /* @__PURE__ */ new Set(["project", "files.json", "removed.json"]);
+var isRootName = (name) => name !== "" && name !== "." && name !== ".." && path10.basename(name) === name && !EXPORT_NAMES.has(name);
+var sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+var isEntry = (value) => typeof value?.path === "string" && typeof value.sha256 === "string";
+var isEntryList = (value) => Array.isArray(value) && value.every(isEntry);
 function readManifest(root) {
   const file = path10.join(root, "files.json");
   if (!existsSync9(file)) {
@@ -6318,66 +6341,226 @@ function readManifest(root) {
     );
   }
   const value = readJson(file);
-  if (!Array.isArray(value) || !value.every(
-    (entry) => typeof entry?.path === "string" && typeof entry.sha256 === "string"
-  )) {
+  if (!isEntryList(value?.project) || !isEntryList(value.root) || !(value.theme === void 0 || isEntry(value.theme) && value.theme.path === THEME_FILE)) {
     throw new CliError(
-      `${file} must be a JSON array of { path, sha256 } entries.`
+      `${file} must hold project and root, each a JSON array of { path, sha256 } entries, and may hold theme, the { path, sha256 } entry for ${THEME_FILE}.`
     );
   }
-  return value;
+  return { project: value.project, root: value.root, theme: value.theme };
 }
-function readProject2(root) {
-  const projectDir = path10.join(root, "project");
+function readEntries(dir, entries, prefix) {
   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/.`);
-    }
+  for (const entry of entries) {
+    const file = path10.join(dir, entry.path);
     if (!existsSync9(file) || !lstatSync(file).isFile()) {
       throw new CliError(
-        `project/${entry.path} is missing from the release, or isn't a regular file.`
+        `${prefix}${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) {
+    if (sha256(bytes) !== entry.sha256) {
       throw new CliError(
-        `project/${entry.path} doesn't match the release's files.json, so nothing was written.`
+        `${prefix}${entry.path} doesn't match the release's files.json, so nothing was written.`
       );
     }
     files.set(entry.path, bytes);
   }
   return files;
 }
-var ROOT_FILES = ["coverage.md", "SETUP.md"];
-function readRootFiles(root) {
-  const files = /* @__PURE__ */ new Map();
-  for (const name of ROOT_FILES) {
-    const file = path10.join(root, name);
+function readRelease(root) {
+  const manifest = readManifest(root);
+  const projectDir = path10.join(root, "project");
+  for (const { path: file } of manifest.project) {
+    const relative = path10.relative(projectDir, path10.join(projectDir, file));
+    if (relative.split(path10.sep)[0] === ".." || path10.isAbsolute(relative)) {
+      throw new CliError(`files.json lists ${file}, outside project/.`);
+    }
+  }
+  for (const { path: file } of manifest.root) {
+    if (!isRootName(file)) {
+      throw new CliError(
+        `files.json lists ${file || "an empty path"} as a root file. A root file is one name beside project/, other than project, files.json and removed.json.`
+      );
+    }
+  }
+  if (!manifest.root.some((entry) => entry.path === "SETUP.md")) {
+    throw new CliError(
+      "The release's files.json lists no SETUP.md, so there's no guide to follow."
+    );
+  }
+  return {
+    files: readEntries(projectDir, manifest.project, "project/"),
+    rootFiles: readEntries(root, manifest.root, ""),
+    themeModule: manifest.theme ? readEntries(root, [manifest.theme], "").get(THEME_FILE) : void 0
+  };
+}
+function droppedRootFiles(out, rootFiles) {
+  const file = path10.join(out, "files.json");
+  if (!existsSync9(file)) return [];
+  const value = readJson(file);
+  if (!isEntryList(value?.root)) {
+    throw new UsageError(
+      `${file} must hold root, a JSON array of { path, sha256 } entries. Delete it, then run the command again.`
+    );
+  }
+  return value.root.filter(
+    (entry) => isRootName(entry.path) && !rootFiles.has(entry.path)
+  );
+}
+function removeDroppedRootFiles(out, dropped) {
+  const edited = [];
+  for (const entry of dropped) {
+    const file = path10.join(out, entry.path);
     if (!existsSync9(file)) continue;
-    if (!lstatSync(file).isFile()) {
-      throw new CliError(`The release's ${name} isn't a regular file.`);
+    const unchanged = lstatSync(file).isFile() && sha256(readFileSync5(file)) === entry.sha256;
+    if (unchanged) rmSync(file);
+    else edited.push(entry.path);
+  }
+  return edited;
+}
+function writeRootFiles(out, rootFiles) {
+  for (const [name, bytes] of rootFiles) {
+    writeFileSync3(path10.join(out, name), bytes);
+  }
+}
+var entriesOf = (files) => [...files].map(([file, bytes]) => ({ path: file, sha256: sha256(bytes) }));
+function writeManifest(out, files, rootFiles) {
+  const manifest = {
+    project: entriesOf(files),
+    root: entriesOf(rootFiles)
+  };
+  writeFileSync3(
+    path10.join(out, "files.json"),
+    `${JSON.stringify(manifest, null, 2)}
+`
+  );
+}
+function readIndex(file) {
+  const index = readJson(file);
+  if (typeof index !== "object" || index === null || Array.isArray(index)) {
+    throw new UsageError(`${file} must be a system's design-system.json.`);
+  }
+  return index;
+}
+function storedTheme(index, file) {
+  const theme = index["theme"];
+  if (theme === void 0) return {};
+  if (typeof theme !== "object" || theme === null || Array.isArray(theme) || !Object.values(theme).every((value) => typeof value === "string")) {
+    throw new UsageError(
+      `${file}: "theme" must be an object of theme flag values, such as {"corners": "round"}. Fix it, or remove it to export the default theme.`
+    );
+  }
+  return theme;
+}
+function layeredTheme(stored, passed) {
+  const flags = { ...stored, ...passed };
+  for (const [flag, value] of Object.entries(passed)) {
+    if (value === "") delete flags[flag];
+  }
+  return flags;
+}
+var noFlagError = (flag, version) => new UsageError(
+  `nxds ${version} has no --${flag}. Pass --release latest to export a release that has it.`
+);
+function noThemeModuleError(theme, { passed, indexFile, version }) {
+  const flag = Object.keys(theme).find((name) => name in passed);
+  if (flag !== void 0) return noFlagError(flag, version);
+  return new UsageError(
+    `${indexFile} has a theme, and nxds ${version} can't theme an export. Pass --release latest to keep the theme.`
+  );
+}
+function assertThemeFlags(flags, taken, { passed, indexFile, version }) {
+  for (const flag of Object.keys(flags)) {
+    if (taken.includes(flag)) continue;
+    if (flag in passed) throw noFlagError(flag, version);
+    if (flag === "mode" || flag === "icons") {
+      throw new UsageError(
+        `${indexFile} theme: a system carries Light and Dark and one icon library, so it has no "${flag}". Remove it from "theme".`
+      );
     }
-    files.set(name, readFileSync5(file));
+    throw new UsageError(
+      `${indexFile} theme: "${flag}" isn't a theme flag nxds ${version} takes. Remove it from "theme".`
+    );
   }
-  return files;
 }
-function writeRootFiles(out, files) {
-  for (const name of ROOT_FILES) {
-    const bytes = files.get(name);
-    if (bytes) writeFileSync3(path10.join(out, name), bytes);
-    else rmSync(path10.join(out, name), { force: true });
+var isThemeModule = (value) => typeof value === "object" && value !== null && value.api === 1 && Array.isArray(value.flags) && typeof value.render === "function" && typeof value.title === "function";
+async function importTheme(bytes, version) {
+  let imported;
+  try {
+    imported = await import(`data:text/javascript;base64,${bytes.toString("base64")}`);
+  } catch (error) {
+    throw new CliError(
+      `nxds ${version}'s theme.js failed to load (${error.message}). Report it at https://github.com/nexuslabs-ai/nxds/issues.`
+    );
+  }
+  if (!isThemeModule(imported.default)) {
+    throw new CliError(
+      `nxds ${version}'s theme.js is newer than this nxds-cli. Run \`npx nxds-cli@latest\` to get the newest one.`
+    );
+  }
+  return imported.default;
+}
+var isRendered = (value) => {
+  const rendered = value;
+  return typeof rendered?.guide === "function" && typeof rendered.index?.title === "string" && typeof rendered.index.theme === "object" && ["tokens.json", "tokens.css", "README.md"].every(
+    (file) => typeof rendered.project?.[file] === "string"
+  );
+};
+function themeError(error, { passed, indexFile, version }) {
+  const { message, flag } = error;
+  if (typeof flag === "string" && flag in passed) {
+    return new UsageError(message);
+  }
+  if (typeof flag === "string" && indexFile !== void 0) {
+    return new UsageError(
+      `${indexFile} theme: ${message} Pass --${flag} <value> to change it, or --${flag}= to reset it.`
+    );
+  }
+  return new CliError(`nxds ${version}'s theme.js failed: ${message}`);
+}
+function renderTheme(theme, flags, source) {
+  const { version } = source;
+  let rendered;
+  try {
+    rendered = theme.render(flags);
+  } catch (error) {
+    throw themeError(error, source);
+  }
+  if (!isRendered(rendered)) {
+    throw new CliError(
+      `nxds ${version}'s theme.js rendered no token files, README or setup guide.`
+    );
+  }
+  return rendered;
+}
+function storedThemeTitle(stored, module, defaultTitle) {
+  if (Object.keys(stored).length === 0) return defaultTitle;
+  try {
+    return module?.title(stored);
+  } catch {
+    return void 0;
   }
 }
-function mergeIndex(files, currentFile) {
+function exportedIndex(files) {
   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"))
+  return JSON.parse(exported.toString("utf8"));
+}
+var jsonBytes = (value) => Buffer.from(`${JSON.stringify(value, null, 2)}
+`);
+function applyTheme(rendered, files, rootFiles) {
+  const { project } = rendered;
+  files.set("tokens.json", Buffer.from(project["tokens.json"]));
+  files.set("tokens.css", Buffer.from(project["tokens.css"]));
+  files.set("README.md", Buffer.from(project["README.md"]));
+  files.set(
+    "design-system.json",
+    jsonBytes({ ...exportedIndex(files), ...rendered.index })
   );
+  rootFiles.set("SETUP.md", Buffer.from(rendered.guide(files.size)));
+}
+function mergeIndex(files, current, currentFile, retitle) {
+  const merged = mergeSystemIndex(current, exportedIndex(files), { retitle });
   const errors = validateIndex(merged);
   if (errors.length > 0) {
     throw new UsageError(
@@ -6385,11 +6568,7 @@ function mergeIndex(files, currentFile) {
 ${errors.map((error) => `  ${error}`).join("\n")}`
     );
   }
-  files.set(
-    "design-system.json",
-    Buffer.from(`${JSON.stringify(merged, null, 2)}
-`)
-  );
+  files.set("design-system.json", jsonBytes(merged));
 }
 function writeProject(out, files) {
   mkdirSync2(out, { recursive: true });
@@ -6446,15 +6625,40 @@ async function exportClaudeDesign(cwd, options) {
     options.release ?? "latest"
   );
   try {
-    const files = readProject2(pkg.root);
-    const rootFiles = readRootFiles(pkg.root);
-    if (options.index) mergeIndex(files, path10.resolve(cwd, options.index));
+    const { files, rootFiles, themeModule } = readRelease(pkg.root);
+    const indexFile = options.index && path10.resolve(cwd, options.index);
+    const current = indexFile ? readIndex(indexFile) : void 0;
+    const passed = options.theme;
+    const stored = current && indexFile ? storedTheme(current, indexFile) : {};
+    const theme = layeredTheme(stored, passed);
+    const source = {
+      passed,
+      indexFile: options.index,
+      version: pkg.version
+    };
+    const defaultTitle = exportedIndex(files).title;
+    const module = themeModule && (Object.keys(theme).length > 0 || Object.keys(stored).length > 0) ? await importTheme(themeModule, pkg.version) : void 0;
+    let themed = {};
+    if (Object.keys(theme).length > 0) {
+      if (!module) throw noThemeModuleError(theme, source);
+      assertThemeFlags(theme, module.flags, source);
+      const rendered = renderTheme(module, theme, source);
+      applyTheme(rendered, files, rootFiles);
+      themed = rendered.index.theme;
+    }
+    if (current && indexFile) {
+      const retitle = current["title"] === storedThemeTitle(stored, module, defaultTitle);
+      mergeIndex(files, current, indexFile, retitle);
+    }
     const exported = new Set(
       [...files.keys()].map((file) => `project/${file}`)
     );
     const removed = options.existing ? stalePaths(readPaths(path10.resolve(cwd, options.existing)), exported) : [];
+    const dropped = droppedRootFiles(out, rootFiles);
     writeProject(out, files);
+    const kept = removeDroppedRootFiles(out, dropped);
     writeRootFiles(out, rootFiles);
+    writeManifest(out, files, rootFiles);
     const removedFile = path10.join(out, "removed.json");
     if (options.existing) {
       writeFileSync3(removedFile, `${JSON.stringify(removed, null, 2)}
@@ -6466,27 +6670,39 @@ async function exportClaudeDesign(cwd, options) {
     const lines2 = [
       `Exported nxds ${pkg.version} as a Claude Design System: ${files.size} files in ${path10.join(relative, "project")}.`
     ];
+    if (Object.keys(themed).length > 0) {
+      lines2.push(
+        `Themed with ${formatThemeFlags(Object.entries(themed).map(([flag, value]) => ({ flag, value })))}.`
+      );
+    }
     if (rootFiles.has("coverage.md")) {
       lines2.push(
         `The props the canvas can't set are in ${path10.join(relative, "coverage.md")}.`
       );
     }
+    for (const name of kept) {
+      lines2.push(
+        `Kept ${path10.join(relative, name)}: this release doesn't ship it, and you edited it.`
+      );
+    }
     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")}.`
       );
     }
     lines2.push(
-      rootFiles.has("SETUP.md") ? `Read ${path10.join(relative, "SETUP.md")} and follow it. It publishes the system, installs it on a canvas and checks it.` : `Publish ${relative} as a Design System artifact in Claude, with ${relative} as the root.`
+      `Read ${path10.join(relative, "SETUP.md")} and follow it. It publishes the system, installs it on a canvas and checks it.`
     );
     return {
-      ok: true,
+      ok: kept.length === 0,
       lines: lines2,
       data: {
         version: pkg.version,
+        theme: themed,
         out,
         files: files.size,
         removed,
+        kept: kept.map((name) => path10.join(out, name)),
         root: [...rootFiles.keys()].map((name) => path10.join(out, name))
       }
     };
@@ -6922,7 +7138,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.6.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.7.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)"
@@ -7004,13 +7220,13 @@ 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"
+  const exportCommand = cli.command("export").description(
+    "export nxds as a Claude Design System folder, ready to publish. Theme flags set the system's theme, as they do for init; with --index, one left out keeps the system's value, and an empty one, such as --density=, resets it"
   ).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"
+    "the system's current design-system.json, to keep its title, creation date and theme"
   ).option(
     "--existing <path>",
     "a JSON list of the system's current file paths, to list the ones this release removes"
@@ -7022,9 +7238,34 @@ Docs: https://nxds.dev/getting-started/install`
       "--npm-registry <url>",
       `npm registry to download from (default: ${DEFAULT_NPM_REGISTRY})`
     ).env("npm_config_registry")
-  ).action(async (_target, _options, command) => {
+  );
+  const exportThemeOptions = NXDS_THEME_FIELDS.filter(
+    (field) => isExportThemeFlag(field.flag)
+  ).map((field) => {
+    const option = new Option(`--${field.flag} <value>`, field.description);
+    exportCommand.addOption(option);
+    return { flag: field.flag, key: option.attributeName() };
+  });
+  exportCommand.action(async (_target, _options, command) => {
+    const options = command.opts();
+    const theme = Object.fromEntries(
+      exportThemeOptions.flatMap(({ flag, key }) => {
+        const value = options[key];
+        return value === void 0 ? [] : [[flag, value]];
+      })
+    );
+    const { out, release, source, npmRegistry, index, existing, overwrite } = command.opts();
     done(
-      await exportClaudeDesign(cwdOf(command), command.opts())
+      await exportClaudeDesign(cwdOf(command), {
+        out,
+        release,
+        source,
+        npmRegistry,
+        index,
+        existing,
+        overwrite,
+        theme
+      })
     );
   });
   cli.command("doctor").description("check that nxds is wired up correctly").action(async (_options, command) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nxds-cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "Install nxds components, blocks and setup into your app.",
   "keywords": [
@@ -45,9 +45,9 @@
     "@types/semver": "^7.8.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "@nxds/claude-design": "0.13.0",
-    "@nxds/core": "0.12.0",
-    "@nxds/catalog": "0.0.1"
+    "@nxds/catalog": "0.0.2",
+    "@nxds/claude-design": "0.14.0",
+    "@nxds/core": "0.13.0"
   },
   "scripts": {
     "build": "tsup",