nxds-cli 0.6.1 → 0.8.0

package/dist/index.js

@@ -1,5 +1,26 @@
 #!/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(" ");
+}
+
+// ../core/src/token-source/ui-scale.ts
+var UI_SCALES = {
+  small: { spacing: 0.9, text: 12 / 14, icon: 14 / 16 },
+  default: { spacing: 1, text: 1, icon: 1 },
+  large: { spacing: 1.1, text: 16 / 14, icon: 18 / 16 },
+  larger: { spacing: 1.25, text: 18 / 14, icon: 20 / 16 }
+};
+var NON_DEFAULT_UI_SCALES = Object.keys(UI_SCALES).filter((scale) => scale !== "default");
+var TEXT_SIZES = [12, 13, 14, 15, 16];
+var MIN_TEXT_PX = 8;
+
 // ../../node_modules/culori/src/rgb/parseNumber.js
 var parseNumber = (color, len) => {
   if (typeof color !== "number") return;
@@ -3838,6 +3859,13 @@ var BASE_TONE_OPTIONS = [
   { value: "slate", label: "Slate", color: "#717376" },
   { value: "gray", label: "Gray", color: "#707274" }
 ];
+var UI_SCALE_OPTIONS = [
+  { value: "small", label: "Small" },
+  { value: "default", label: "Default" },
+  { value: "large", label: "Large" },
+  { value: "larger", label: "Larger" }
+];
+var TEXT_SIZE_OPTIONS = TEXT_SIZES.map((value) => ({ value, label: `${value}px` }));
 var DENSITY_OPTIONS = [
   { value: "tight", label: "Tight" },
   { value: "compact", label: "Compact" },
@@ -3871,6 +3899,8 @@ var DEFAULT_NXDS_APPEARANCE = {
   surfaceTone: "zinc",
   lightContrast: 50,
   darkContrast: 50,
+  uiScale: "default",
+  textSize: 14,
   density: "default",
   corners: "subtle",
   elevation: "quiet",
@@ -3879,18 +3909,21 @@ var DEFAULT_NXDS_APPEARANCE = {
     uiFont: '-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
     headingFont: null,
     codeFont: 'ui-monospace, "SF Mono", Menlo, monospace',
-    uiFontSize: 14,
     codeFontSize: 12,
     reduceMotion: false,
     pointerCursors: false,
     fontSmoothing: false
   }
 };
-var FONT_SIZE_PX_MIN = 8;
+var FONT_SIZE_PX_MIN = MIN_TEXT_PX;
 var FONT_SIZE_PX_MAX = 32;
 var SURFACE_TONES = new Set(
   BASE_TONE_OPTIONS.map((option) => option.value)
 );
+var SCALES = new Set(
+  UI_SCALE_OPTIONS.map((option) => option.value)
+);
+var TEXT_SIZE_VALUES = new Set(TEXT_SIZES);
 var DENSITIES = new Set(
   DENSITY_OPTIONS.map((option) => option.value)
 );
@@ -4043,20 +4076,6 @@ function contrastField(flag, key, description) {
     })
   };
 }
-function fontSizeField(flag, key, description) {
-  return {
-    kind: "integer",
-    flag,
-    key: `prefs.${key}`,
-    description,
-    min: FONT_SIZE_PX_MIN,
-    max: FONT_SIZE_PX_MAX,
-    read: (theme) => String(theme.appearance.prefs[key]),
-    write: (theme, value) => withPrefs(theme, {
-      [key]: integer(flag, value, FONT_SIZE_PX_MIN, FONT_SIZE_PX_MAX)
-    })
-  };
-}
 function fontField(flag, key, description, categories, fallback) {
   const fonts = FONT_OPTIONS.filter(
     (font) => categories.includes(font.category)
@@ -4087,6 +4106,9 @@ function fontField(flag, key, description, categories, fallback) {
     }
   };
 }
+var TEXT_SIZES2 = TEXT_SIZE_OPTIONS.map((option) => option.value);
+var TEXT_SIZE_MIN = Math.min(...TEXT_SIZES2);
+var TEXT_SIZE_MAX = Math.max(...TEXT_SIZES2);
 var DEFAULT_PREFS = DEFAULT_NXDS_APPEARANCE.prefs;
 var TEXT_FONTS = ["sans", "serif"];
 var NXDS_THEME_FIELDS = [
@@ -4107,6 +4129,30 @@ var NXDS_THEME_FIELDS = [
     "neutral tone of backgrounds and borders",
     BASE_TONE_OPTIONS.map((option) => option.value)
   ),
+  enumField(
+    "ui-scale",
+    "uiScale",
+    "size of text, icons and spacing together",
+    UI_SCALE_OPTIONS.map((option) => option.value)
+  ),
+  {
+    kind: "integer",
+    flag: "text-size",
+    key: "textSize",
+    description: `label text size in px at the default UI scale, ${TEXT_SIZE_MIN} to ${TEXT_SIZE_MAX}`,
+    min: TEXT_SIZE_MIN,
+    max: TEXT_SIZE_MAX,
+    read: (theme) => String(theme.appearance.textSize),
+    write: (theme, value) => withAppearance(theme, {
+      // Every whole number from the minimum to the maximum is a text size.
+      textSize: integer(
+        "text-size",
+        value,
+        TEXT_SIZE_MIN,
+        TEXT_SIZE_MAX
+      )
+    })
+  },
   enumField(
     "density",
     "density",
@@ -4157,8 +4203,23 @@ var NXDS_THEME_FIELDS = [
     value: "system",
     family: DEFAULT_PREFS.codeFont
   }),
-  fontSizeField("font-size", "uiFontSize", "UI text size in px"),
-  fontSizeField("code-font-size", "codeFontSize", "code text size in px"),
+  {
+    kind: "integer",
+    flag: "code-font-size",
+    key: "prefs.codeFontSize",
+    description: "code text size in px",
+    min: FONT_SIZE_PX_MIN,
+    max: FONT_SIZE_PX_MAX,
+    read: (theme) => String(theme.appearance.prefs.codeFontSize),
+    write: (theme, value) => withPrefs(theme, {
+      codeFontSize: integer(
+        "code-font-size",
+        value,
+        FONT_SIZE_PX_MIN,
+        FONT_SIZE_PX_MAX
+      )
+    })
+  },
   {
     kind: "choice",
     flag: "icons",
@@ -4543,7 +4604,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.1"}. Run \`${CLI_COMMAND}\` to get the newest one.`
+      `${release} needs a newer nxds-cli than ${"0.8.0"}. Run \`${CLI_COMMAND}\` to get the newest one.`
     );
   }
   const invalid2 = (problems) => new CliError(
@@ -6123,14 +6184,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 +6244,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>";
@@ -6313,9 +6379,8 @@ function stalePaths(existing, exported) {
 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 isEntryList = (value) => Array.isArray(value) && value.every(
-  (entry) => typeof entry?.path === "string" && typeof entry.sha256 === "string"
-);
+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)) {
@@ -6324,12 +6389,12 @@ function readManifest(root) {
     );
   }
   const value = readJson(file);
-  if (!isEntryList(value?.project) || !isEntryList(value.root)) {
+  if (!isEntryList(value?.project) || !isEntryList(value.root) || !(value.theme === void 0 || isEntry(value.theme) && value.theme.path === THEME_FILE)) {
     throw new CliError(
-      `${file} must hold project and root, each 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 { project: value.project, root: value.root };
+  return { project: value.project, root: value.root, theme: value.theme };
 }
 function readEntries(dir, entries, prefix) {
   const files = /* @__PURE__ */ new Map();
@@ -6373,7 +6438,8 @@ function readRelease(root) {
   }
   return {
     files: readEntries(projectDir, manifest.project, "project/"),
-    rootFiles: readEntries(root, manifest.root, "")
+    rootFiles: readEntries(root, manifest.root, ""),
+    themeModule: manifest.theme ? readEntries(root, [manifest.theme], "").get(THEME_FILE) : void 0
   };
 }
 function droppedRootFiles(out, rootFiles) {
@@ -6417,13 +6483,132 @@ function writeManifest(out, files, rootFiles) {
 `
   );
 }
-function mergeIndex(files, currentFile) {
+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".`
+      );
+    }
+    throw new UsageError(
+      `${indexFile} theme: "${flag}" isn't a theme flag nxds ${version} takes. Remove it from "theme".`
+    );
+  }
+}
+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 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(
@@ -6431,11 +6616,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 });
@@ -6492,8 +6673,31 @@ async function exportClaudeDesign(cwd, options) {
     options.release ?? "latest"
   );
   try {
-    const { files, rootFiles } = readRelease(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}`)
     );
@@ -6514,6 +6718,11 @@ 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")}.`
@@ -6537,6 +6746,7 @@ async function exportClaudeDesign(cwd, options) {
       lines: lines2,
       data: {
         version: pkg.version,
+        theme: themed,
         out,
         files: files.size,
         removed,
@@ -6976,7 +7186,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.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(
+  }).exitOverride().name(CLI_COMMAND).description("Add nxds to your app.").version("0.8.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)"
@@ -7058,13 +7268,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"
@@ -7076,9 +7286,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.1",
+  "version": "0.8.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/catalog": "0.0.1",
-    "@nxds/claude-design": "0.13.2",
-    "@nxds/core": "0.12.0"
+    "@nxds/catalog": "0.0.3",
+    "@nxds/claude-design": "0.17.0",
+    "@nxds/core": "0.14.0"
   },
   "scripts": {
     "build": "tsup",