@sourcescape/ds-cli 0.1.0

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,1022 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { parseArgs } from "util";
+
+// src/systems.ts
+import { readFileSync, readdirSync, existsSync, statSync } from "fs";
+import { join, resolve, dirname } from "path";
+var REPO_ROOT = resolve(dirname(new URL(import.meta.url).pathname), "..", "..");
+var SYSTEMS_ROOT = join(REPO_ROOT, "systems");
+function setSystemsRoot(dir) {
+  SYSTEMS_ROOT = resolve(dir);
+}
+function listSystems() {
+  return readdirSync(SYSTEMS_ROOT, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort();
+}
+function systemDir(system) {
+  return join(SYSTEMS_ROOT, system);
+}
+function systemExists(system) {
+  return existsSync(systemDir(system));
+}
+function readFirstHeading(filePath) {
+  if (!existsSync(filePath)) return "";
+  const content = readFileSync(filePath, "utf-8");
+  const match = content.match(/^#\s+(.+)$/m);
+  return match ? match[1].trim() : "";
+}
+function readFirstParagraph(filePath) {
+  if (!existsSync(filePath)) return "";
+  const lines = readFileSync(filePath, "utf-8").split("\n");
+  let pastHeading = false;
+  for (const line of lines) {
+    if (line.startsWith("# ")) {
+      pastHeading = true;
+      continue;
+    }
+    if (pastHeading && line.trim().length > 0 && !line.startsWith("#")) {
+      return line.trim();
+    }
+  }
+  return "";
+}
+function readFile(filePath) {
+  return readFileSync(filePath, "utf-8");
+}
+function getSystemInfo(system) {
+  const descPath = join(systemDir(system), "DESCRIPTION.md");
+  return {
+    name: system,
+    description: readFirstHeading(descPath)
+  };
+}
+function readDescription(system) {
+  const descPath = join(systemDir(system), "DESCRIPTION.md");
+  if (!existsSync(descPath)) return "";
+  return readFile(descPath);
+}
+function listComponents(system) {
+  const compsDir = join(systemDir(system), "components");
+  const results = [];
+  for (const kind of ["molecules", "cells"]) {
+    const kindDir = join(compsDir, kind);
+    if (!existsSync(kindDir)) continue;
+    const dirs = readdirSync(kindDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort();
+    for (const name of dirs) {
+      const descPath = join(kindDir, name, "description.md");
+      results.push({
+        name,
+        kind,
+        description: readFirstParagraph(descPath)
+      });
+    }
+  }
+  return results;
+}
+function findComponent(system, name) {
+  const compsDir = join(systemDir(system), "components");
+  for (const kind of ["molecules", "cells"]) {
+    const dir = join(compsDir, kind, name);
+    if (existsSync(dir) && statSync(dir).isDirectory()) {
+      return { kind, dir };
+    }
+  }
+  return null;
+}
+function allComponentNames(system) {
+  const compsDir = join(systemDir(system), "components");
+  const results = [];
+  for (const kind of ["molecules", "cells"]) {
+    const kindDir = join(compsDir, kind);
+    if (!existsSync(kindDir)) continue;
+    const dirs = readdirSync(kindDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => ({ name: d.name, kind }));
+    results.push(...dirs);
+  }
+  return results;
+}
+function listTokenFiles(system) {
+  const tokensDir = join(systemDir(system), "tokens");
+  if (!existsSync(tokensDir)) return [];
+  return readdirSync(tokensDir).filter((f) => f.endsWith(".json")).map((f) => f.replace(".json", "")).sort();
+}
+function readTokenFile(system, name) {
+  const filePath = join(systemDir(system), "tokens", `${name}.json`);
+  if (!existsSync(filePath)) return null;
+  return JSON.parse(readFile(filePath));
+}
+function listPrinciples(system) {
+  const dir = join(systemDir(system), "principles");
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "index.md").map((f) => {
+    const name = f.replace(".md", "");
+    const title = readFirstHeading(join(dir, f));
+    return { name, title: title || name };
+  }).sort((a, b) => a.name.localeCompare(b.name));
+}
+function readPrinciple(system, name) {
+  const filePath = join(systemDir(system), "principles", `${name}.md`);
+  if (!existsSync(filePath)) return null;
+  return readFile(filePath);
+}
+function hasArchitecture(system) {
+  return existsSync(join(systemDir(system), "architecture"));
+}
+function listArchitecture(system, subpath) {
+  const baseDir = join(systemDir(system), "architecture");
+  const dir = subpath ? join(baseDir, subpath) : baseDir;
+  if (!existsSync(dir)) return { entries: [], indexContent: null };
+  const indexPath = join(dir, "index.md");
+  const indexContent = existsSync(indexPath) ? readFile(indexPath) : null;
+  const entries = readdirSync(dir, { withFileTypes: true }).filter((d) => d.name !== "index.md").map((d) => ({ name: d.name, isDir: d.isDirectory() })).sort((a, b) => {
+    if (a.isDir !== b.isDir) return a.isDir ? -1 : 1;
+    return a.name.localeCompare(b.name);
+  });
+  return { entries, indexContent };
+}
+function readArchitectureFile(system, subpath) {
+  const filePath = join(systemDir(system), "architecture", subpath);
+  if (!existsSync(filePath)) return null;
+  if (statSync(filePath).isDirectory()) return null;
+  return readFile(filePath);
+}
+function isArchitectureDir(system, subpath) {
+  const filePath = join(systemDir(system), "architecture", subpath);
+  return existsSync(filePath) && statSync(filePath).isDirectory();
+}
+function listExamples(system) {
+  const dir = join(systemDir(system), "examples");
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((f) => f.endsWith(".html")).sort();
+}
+function listReferences(system) {
+  const dir = join(systemDir(system), "references");
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true }).filter((d) => !d.isDirectory()).map((d) => d.name).sort();
+}
+function suggestComponent(system, query) {
+  const all = allComponentNames(system);
+  const q = query.toLowerCase();
+  return all.filter((c) => c.name.includes(q) || q.includes(c.name)).map((c) => `${c.name} (${c.kind})`);
+}
+function findComponentSources(system, name) {
+  const found = findComponent(system, name);
+  if (!found) return { css: [], js: [] };
+  const css = [];
+  const js = [];
+  const stylePath = join(found.dir, "style.css");
+  const scriptPath = join(found.dir, "script.js");
+  if (existsSync(stylePath)) css.push(stylePath);
+  if (existsSync(scriptPath)) js.push(scriptPath);
+  return { css, js };
+}
+
+// src/format.ts
+function heading(text) {
+  console.log(`
+${text}`);
+  console.log("\u2500".repeat(Math.min(text.length, 60)));
+}
+function subheading(text) {
+  console.log(`
+  ${text}`);
+}
+function list(items, indent = 2) {
+  const pad = " ".repeat(indent);
+  for (const item of items) {
+    console.log(`${pad}${item}`);
+  }
+}
+function descriptionList(items, indent = 2) {
+  if (items.length === 0) return;
+  const maxName = Math.max(...items.map((i) => i.name.length));
+  const pad = " ".repeat(indent);
+  for (const item of items) {
+    const desc = item.description ? `  ${item.description}` : "";
+    console.log(`${pad}${item.name.padEnd(maxName)}${desc}`);
+  }
+}
+function countLine(label, count) {
+  console.log(`  ${label}: ${count}`);
+}
+function error(message, suggestions) {
+  console.error(`Error: ${message}`);
+  if (suggestions && suggestions.length > 0) {
+    console.error(`Did you mean: ${suggestions.join(", ")}`);
+  }
+}
+function markdown(content) {
+  console.log(content);
+}
+function blank() {
+  console.log();
+}
+
+// src/commands/list.ts
+function commandList() {
+  const systems = listSystems();
+  if (systems.length === 0) {
+    console.log("No design systems found.");
+    return 0;
+  }
+  heading("Design Systems");
+  const items = systems.map((name) => {
+    const info = getSystemInfo(name);
+    return { name: info.name, description: info.description };
+  });
+  descriptionList(items);
+  console.log();
+  return 0;
+}
+
+// src/tokens.ts
+function isToken(obj) {
+  return typeof obj === "object" && obj !== null && "$value" in obj;
+}
+function flattenTokens(obj, prefix = "") {
+  const tokens = [];
+  for (const [key, value] of Object.entries(obj)) {
+    if (key.startsWith("$")) continue;
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (isToken(value)) {
+      tokens.push({
+        path,
+        $value: value.$value,
+        $type: value.$type ?? "unknown"
+      });
+    } else if (typeof value === "object" && value !== null) {
+      tokens.push(...flattenTokens(value, path));
+    }
+  }
+  return tokens;
+}
+function groupTokens(tokens) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const token of tokens) {
+    const category = token.path.split(".")[0];
+    if (!groups.has(category)) {
+      groups.set(category, []);
+    }
+    groups.get(category).push(token);
+  }
+  return Array.from(groups.entries()).map(([name, tokens2]) => ({
+    name,
+    tokens: tokens2
+  }));
+}
+function formatValue(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "number") return String(value);
+  if (typeof value === "object" && value !== null) {
+    return JSON.stringify(value);
+  }
+  return String(value);
+}
+function renderTokens(data) {
+  const tokens = flattenTokens(data);
+  const groups = groupTokens(tokens);
+  for (const group of groups) {
+    console.log(`
+${group.name}`);
+    console.log("\u2500".repeat(Math.min(group.name.length, 40)));
+    const maxPath = Math.max(...group.tokens.map((t) => t.path.length));
+    for (const token of group.tokens) {
+      const typeTag = token.$type !== "unknown" ? ` [${token.$type}]` : "";
+      console.log(`  ${token.path.padEnd(maxPath)}  ${formatValue(token.$value)}${typeTag}`);
+    }
+  }
+  console.log();
+}
+function renderFlat(data) {
+  const tokens = flattenTokens(data);
+  for (const token of tokens) {
+    console.log(`${token.path} = ${formatValue(token.$value)}`);
+  }
+}
+function renderJson(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+function tokenSummary(data) {
+  const tokens = flattenTokens(data);
+  const types = new Set(tokens.map((t) => t.$type));
+  const typeList = Array.from(types).filter((t) => t !== "unknown").sort();
+  const typeSuffix = typeList.length > 0 ? ` (${typeList.join(", ")})` : "";
+  return `${tokens.length} tokens${typeSuffix}`;
+}
+
+// src/commands/show.ts
+function commandShow(system) {
+  if (!systemExists(system)) {
+    const available = listSystems();
+    const suggestions = available.filter(
+      (s) => s.includes(system) || system.includes(s)
+    );
+    error(
+      `Design system "${system}" not found`,
+      suggestions.length > 0 ? suggestions : available
+    );
+    return 1;
+  }
+  const desc = readDescription(system);
+  if (desc) {
+    markdown(desc);
+  }
+  heading("Sections");
+  const components = listComponents(system);
+  const molecules = components.filter((c) => c.kind === "molecules");
+  const cells = components.filter((c) => c.kind === "cells");
+  countLine("Components", components.length);
+  if (molecules.length > 0) countLine("  Molecules", molecules.length);
+  if (cells.length > 0) countLine("  Cells", cells.length);
+  const tokenFiles = listTokenFiles(system);
+  if (tokenFiles.length > 0) {
+    countLine("Token files", tokenFiles.length);
+    for (const name of tokenFiles) {
+      const data = readTokenFile(system, name);
+      const summary = data ? tokenSummary(data) : "";
+      console.log(`    ${name}: ${summary}`);
+    }
+  }
+  const principles = listPrinciples(system);
+  if (principles.length > 0) countLine("Principles", principles.length);
+  if (hasArchitecture(system)) {
+    console.log("  Architecture: yes");
+  }
+  const examples = listExamples(system);
+  if (examples.length > 0) countLine("Examples", examples.length);
+  const references = listReferences(system);
+  if (references.length > 0) countLine("References", references.length);
+  blank();
+  return 0;
+}
+
+// src/commands/browse.ts
+import { join as join5 } from "path";
+import { existsSync as existsSync6 } from "fs";
+import { exec } from "child_process";
+
+// src/commands/components.ts
+import { join as join2, basename as basename2, relative } from "path";
+import { existsSync as existsSync2, readFileSync as readFileSync2, readdirSync as readdirSync2 } from "fs";
+async function commandComponents(system, args) {
+  const [subcommand, ...rest] = args;
+  if (!subcommand || subcommand === "list") {
+    return listAllComponents(system);
+  }
+  if (subcommand === "details") {
+    const name = rest[0];
+    if (!name) {
+      error("Usage: ds <system> components details <name>");
+      return 1;
+    }
+    return showDetails(system, name);
+  }
+  return showDetails(system, subcommand);
+}
+function listAllComponents(system) {
+  const components = listComponents(system);
+  if (components.length === 0) {
+    console.log(`No components found in ${system}.`);
+    return 0;
+  }
+  const molecules = components.filter((c) => c.kind === "molecules");
+  const cells = components.filter((c) => c.kind === "cells");
+  heading(`${system} \u2014 Components`);
+  if (molecules.length > 0) {
+    subheading(`Molecules (${molecules.length})`);
+    descriptionList(
+      molecules.map((c) => ({ name: c.name, description: c.description })),
+      4
+    );
+  }
+  if (cells.length > 0) {
+    subheading(`Cells (${cells.length})`);
+    descriptionList(
+      cells.map((c) => ({ name: c.name, description: c.description })),
+      4
+    );
+  }
+  blank();
+  return 0;
+}
+function showDetails(system, name) {
+  const found = findComponent(system, name);
+  if (!found) {
+    const suggestions = suggestComponent(system, name);
+    error(`Component "${name}" not found in ${system}`, suggestions);
+    return 1;
+  }
+  const sysDir = systemDir(system);
+  const relPath = relative(sysDir, found.dir);
+  heading(`${name}`);
+  console.log(`  Kind:  ${found.kind}`);
+  console.log(`  Path:  ${relPath}`);
+  const files = readdirSync2(found.dir);
+  console.log(`  Files: ${files.join(", ")}`);
+  blank();
+  const descPath = join2(found.dir, "description.md");
+  if (existsSync2(descPath)) {
+    subheading("Description");
+    blank();
+    console.log(readFile(descPath));
+  }
+  const sources = findComponentSources(system, name);
+  if (sources.css.length > 0) {
+    for (const cssPath of sources.css) {
+      subheading(`Source CSS: ${basename2(cssPath)}`);
+      blank();
+      console.log("```css");
+      console.log(readFileSync2(cssPath, "utf-8").trimEnd());
+      console.log("```");
+      blank();
+    }
+  }
+  if (sources.js.length > 0) {
+    for (const jsPath of sources.js) {
+      subheading(`Source JS: ${basename2(jsPath)}`);
+      blank();
+      console.log("```js");
+      console.log(readFileSync2(jsPath, "utf-8").trimEnd());
+      console.log("```");
+      blank();
+    }
+  }
+  return 0;
+}
+
+// src/commands/render.ts
+import { readFileSync as readFileSync4, existsSync as existsSync5 } from "fs";
+import { resolve as resolve2 } from "path";
+
+// src/resolve-deps.ts
+import { readFileSync as readFileSync3, existsSync as existsSync3 } from "fs";
+import { join as join3, relative as relative2 } from "path";
+function buildRegistry(system) {
+  const components = listComponents(system);
+  const entries = [];
+  const tagMap = /* @__PURE__ */ new Map();
+  for (const comp of components) {
+    const found = findComponent(system, comp.name);
+    if (!found) continue;
+    const scriptPath = join3(found.dir, "script.js");
+    const stylePath = join3(found.dir, "style.css");
+    const hasJs = existsSync3(scriptPath);
+    const hasCss = existsSync3(stylePath);
+    const tags = [];
+    const dynamicTags = [];
+    if (hasJs) {
+      const js = readFileSync3(scriptPath, "utf-8");
+      for (const m of js.matchAll(/customElements\.define\(\s*['"]([^'"]+)['"]/g)) {
+        tags.push(m[1]);
+      }
+      for (const m of js.matchAll(/document\.createElement\(\s*['"]([a-z][a-z0-9]*-[a-z0-9-]*)['"]\s*\)/g)) {
+        if (!tags.includes(m[1])) dynamicTags.push(m[1]);
+      }
+      for (const m of js.matchAll(/<([a-z][a-z0-9]*-[a-z0-9-]*)[>\s/'"]/g)) {
+        const tag = m[1];
+        if (!tags.includes(tag) && !dynamicTags.includes(tag)) {
+          dynamicTags.push(tag);
+        }
+      }
+    }
+    if (hasCss) {
+      const css = readFileSync3(stylePath, "utf-8");
+      for (const m of css.matchAll(/(?:^|[\s,}>+~])([a-z][a-z0-9]*-[a-z0-9-]*)(?=[\s,{[:.>+~]|$)/gm)) {
+        const tag = m[1];
+        if (!tags.includes(tag)) tags.push(tag);
+      }
+    }
+    const dirName = comp.name;
+    if (dirName.includes("-") && !tags.includes(dirName)) {
+      tags.push(dirName);
+    }
+    const prdName = `prd-${dirName}`;
+    if (!tags.includes(prdName)) {
+      tags.push(prdName);
+    }
+    const entry = {
+      name: comp.name,
+      kind: comp.kind,
+      dir: found.dir,
+      tags,
+      dynamicTags,
+      hasCss,
+      hasJs
+    };
+    entries.push(entry);
+    for (const tag of tags) {
+      if (!tagMap.has(tag)) tagMap.set(tag, entry);
+    }
+  }
+  return { tagMap, entries };
+}
+function resolveMarkup(registry, markup) {
+  const markupTags = /* @__PURE__ */ new Set();
+  for (const m of markup.matchAll(/<([a-z][a-z0-9]*-[a-z0-9-]*)/g)) {
+    markupTags.add(m[1]);
+  }
+  const matched = /* @__PURE__ */ new Set();
+  const unmatchedTags = [];
+  const resolved = /* @__PURE__ */ new Set();
+  const queue = [...markupTags];
+  while (queue.length > 0) {
+    const tag = queue.pop();
+    if (resolved.has(tag)) continue;
+    resolved.add(tag);
+    const entry = registry.tagMap.get(tag);
+    if (entry) {
+      if (!matched.has(entry)) {
+        matched.add(entry);
+        for (const dt of entry.dynamicTags) {
+          if (!resolved.has(dt)) queue.push(dt);
+        }
+      }
+    } else {
+      unmatchedTags.push(tag);
+    }
+  }
+  const cssFiles = [];
+  const jsFiles = [];
+  for (const entry of matched) {
+    if (entry.hasCss) cssFiles.push(join3(entry.dir, "style.css"));
+    if (entry.hasJs) jsFiles.push(join3(entry.dir, "script.js"));
+  }
+  return { cssFiles, jsFiles, unmatchedTags };
+}
+function buildPreviewHtml(system, markup, deps) {
+  const sysDir = systemDir(system);
+  const sharedCss = [
+    join3(sysDir, "src", "_shared", "_tokens.css"),
+    join3(sysDir, "src", "_shared", "_base.css")
+  ];
+  const utilitiesCss = join3(sysDir, "src", "_shared", "_utilities.css");
+  const blocks = ["@layer tokens, base, components, utilities;"];
+  for (const p of sharedCss) {
+    if (existsSync3(p)) {
+      blocks.push(`/* ${relative2(sysDir, p)} */`);
+      blocks.push(readFileSync3(p, "utf-8"));
+    }
+  }
+  for (const p of deps.cssFiles) {
+    blocks.push(`/* ${relative2(sysDir, p)} */`);
+    blocks.push(readFileSync3(p, "utf-8"));
+  }
+  if (existsSync3(utilitiesCss)) {
+    blocks.push(`/* ${relative2(sysDir, utilitiesCss)} */`);
+    blocks.push(readFileSync3(utilitiesCss, "utf-8"));
+  }
+  const inlinedCss = blocks.join("\n");
+  const scriptTags = deps.jsFiles.map((p) => `  <script type="module" src="/${relative2(sysDir, p)}"></script>`).join("\n");
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <style>
+${inlinedCss}
+  </style>
+</head>
+<body>
+${markup}
+${scriptTags}
+</body>
+</html>`;
+}
+
+// src/preview-server.ts
+import { createServer } from "http";
+import { join as join4, extname } from "path";
+import { readFile as readFile2 } from "fs/promises";
+import { existsSync as existsSync4 } from "fs";
+var MIME_TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".eot": "application/vnd.ms-fontobject"
+};
+function startPreviewServer(systemDir2, opts) {
+  return new Promise((resolve3, reject) => {
+    const server = createServer(async (req, res) => {
+      const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+      if (url.pathname === "/" && opts.html) {
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(opts.html);
+        return;
+      }
+      const filePath = join4(systemDir2, decodeURIComponent(url.pathname));
+      if (!existsSync4(filePath)) {
+        res.writeHead(404);
+        res.end("Not found");
+        return;
+      }
+      try {
+        const data = await readFile2(filePath);
+        const ext = extname(filePath).toLowerCase();
+        const contentType = MIME_TYPES[ext] ?? "application/octet-stream";
+        res.writeHead(200, { "Content-Type": contentType });
+        res.end(data);
+      } catch {
+        res.writeHead(500);
+        res.end("Internal server error");
+      }
+    });
+    server.listen(0, () => {
+      const addr = server.address();
+      if (!addr || typeof addr === "string") {
+        reject(new Error("Failed to get server address"));
+        return;
+      }
+      resolve3({
+        url: `http://localhost:${addr.port}`,
+        stop: () => server.close()
+      });
+    });
+    server.on("error", reject);
+  });
+}
+
+// src/commands/render.ts
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf-8");
+}
+async function commandRender(system, fileArg, flags) {
+  if (!systemExists(system)) {
+    const suggestions = listSystems().filter(
+      (s) => s.includes(system) || system.includes(s)
+    );
+    error(`Design system "${system}" not found`, suggestions);
+    return 1;
+  }
+  if (!fileArg) {
+    error("Usage: ds <system> render <file|->", [
+      "ds fw-prd render page.xml",
+      "cat page.xml | ds fw-prd render -",
+      "ds fw-prd render page.xml --html"
+    ]);
+    return 1;
+  }
+  let markup;
+  if (fileArg === "-") {
+    markup = await readStdin();
+  } else {
+    const filePath = resolve2(fileArg);
+    if (!existsSync5(filePath)) {
+      error(`File not found: ${filePath}`);
+      return 1;
+    }
+    markup = readFileSync4(filePath, "utf-8");
+  }
+  const registry = buildRegistry(system);
+  const deps = resolveMarkup(registry, markup);
+  for (const tag of deps.unmatchedTags) {
+    console.warn(`  warn: unmatched custom element <${tag}>`);
+  }
+  const html = buildPreviewHtml(system, markup, deps);
+  if (flags.html) {
+    process.stdout.write(html);
+    return 0;
+  }
+  const sysDir = systemDir(system);
+  const server = await startPreviewServer(sysDir, { html });
+  console.log(`Preview server running at ${server.url}`);
+  console.log(`Opening in browser... (Ctrl+C to stop)`);
+  openInBrowser(server.url);
+  await new Promise((resolve3) => {
+    process.on("SIGINT", () => {
+      server.stop();
+      resolve3();
+    });
+    process.on("SIGTERM", () => {
+      server.stop();
+      resolve3();
+    });
+  });
+  return 0;
+}
+
+// src/commands/browse.ts
+async function commandBrowse(system, path, flags) {
+  if (!systemExists(system)) {
+    const suggestions = listSystems().filter(
+      (s) => s.includes(system) || system.includes(s)
+    );
+    error(`Design system "${system}" not found`, suggestions);
+    return 1;
+  }
+  const segments = path.split("/").filter(Boolean);
+  const section = segments[0];
+  switch (section) {
+    case "components":
+      return commandComponents(system, segments.slice(1));
+    case "render":
+      return commandRender(system, segments.slice(1).join("/"), flags);
+    case "tokens":
+      return handleTokens(system, segments.slice(1), flags);
+    case "principles":
+      return handlePrinciples(system, segments.slice(1));
+    case "architecture":
+      return handleArchitecture(system, segments.slice(1));
+    case "examples":
+      return handleExamples(system, segments.slice(1), flags);
+    case "references":
+      return handleReferences(system, segments.slice(1));
+    default:
+      error(`Unknown section "${section}"`, [
+        "components",
+        "tokens",
+        "principles",
+        "architecture",
+        "examples",
+        "references"
+      ]);
+      return 1;
+  }
+}
+function openInBrowser(target) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  exec(`${cmd} "${target}"`);
+}
+function handleTokens(system, segments, flags) {
+  if (segments.length === 0) {
+    return listAllTokens(system);
+  }
+  return showTokenFile(system, segments[0], flags);
+}
+function listAllTokens(system) {
+  const files = listTokenFiles(system);
+  if (files.length === 0) {
+    console.log(`No token files found in ${system}.`);
+    return 0;
+  }
+  heading(`${system} \u2014 Tokens`);
+  for (const name of files) {
+    const data = readTokenFile(system, name);
+    if (!data) continue;
+    console.log(`  ${name}: ${tokenSummary(data)}`);
+  }
+  blank();
+  return 0;
+}
+function showTokenFile(system, name, flags) {
+  const data = readTokenFile(system, name);
+  if (!data) {
+    const available = listTokenFiles(system);
+    const suggestions = available.filter(
+      (f) => f.includes(name) || name.includes(f)
+    );
+    error(
+      `Token file "${name}" not found in ${system}`,
+      suggestions.length > 0 ? suggestions : available
+    );
+    return 1;
+  }
+  if (flags.json) {
+    renderJson(data);
+    return 0;
+  }
+  if (flags.flat) {
+    renderFlat(data);
+    return 0;
+  }
+  renderTokens(data);
+  return 0;
+}
+function handlePrinciples(system, segments) {
+  if (segments.length === 0) {
+    return listAllPrinciples(system);
+  }
+  return showPrinciple(system, segments[0]);
+}
+function listAllPrinciples(system) {
+  const principles = listPrinciples(system);
+  if (principles.length === 0) {
+    console.log(`No principles found in ${system}.`);
+    return 0;
+  }
+  heading(`${system} \u2014 Principles`);
+  descriptionList(
+    principles.map((p) => ({ name: p.name, description: p.title }))
+  );
+  blank();
+  return 0;
+}
+function showPrinciple(system, name) {
+  const content = readPrinciple(system, name);
+  if (!content) {
+    const available = listPrinciples(system);
+    const suggestions = available.filter((p) => p.name.includes(name) || name.includes(p.name)).map((p) => p.name);
+    error(
+      `Principle "${name}" not found in ${system}`,
+      suggestions.length > 0 ? suggestions : available.map((p) => p.name)
+    );
+    return 1;
+  }
+  markdown(content);
+  return 0;
+}
+function handleArchitecture(system, segments) {
+  if (!hasArchitecture(system)) {
+    console.log(`No architecture section in ${system}.`);
+    return 0;
+  }
+  const subpath = segments.length > 0 ? segments.join("/") : void 0;
+  if (subpath) {
+    const content = readArchitectureFile(system, subpath);
+    if (content !== null) {
+      markdown(content);
+      return 0;
+    }
+    const contentMd = readArchitectureFile(system, subpath + ".md");
+    if (contentMd !== null) {
+      markdown(contentMd);
+      return 0;
+    }
+    if (isArchitectureDir(system, subpath)) {
+      return listArchitectureDir(system, subpath);
+    }
+    error(`Architecture path "${subpath}" not found in ${system}`);
+    return 1;
+  }
+  return listArchitectureDir(system, void 0);
+}
+function listArchitectureDir(system, subpath) {
+  const { entries, indexContent } = listArchitecture(system, subpath);
+  const label = subpath ? `${system} \u2014 Architecture / ${subpath}` : `${system} \u2014 Architecture`;
+  heading(label);
+  if (indexContent) {
+    markdown(indexContent);
+    blank();
+  }
+  if (entries.length > 0) {
+    for (const entry of entries) {
+      const suffix = entry.isDir ? "/" : "";
+      console.log(`  ${entry.name}${suffix}`);
+    }
+    blank();
+  }
+  return 0;
+}
+function handleExamples(system, segments, flags) {
+  if (segments.length === 0) {
+    return listAllExamples(system);
+  }
+  return showExample(system, segments[0], flags);
+}
+function listAllExamples(system) {
+  const examples = listExamples(system);
+  if (examples.length === 0) {
+    console.log(`No examples found in ${system}.`);
+    return 0;
+  }
+  heading(`${system} \u2014 Examples`);
+  list(examples);
+  blank();
+  return 0;
+}
+function showExample(system, name, flags) {
+  let filename = name;
+  if (!filename.endsWith(".html")) filename += ".html";
+  const filePath = join5(systemDir(system), "examples", filename);
+  if (!existsSync6(filePath)) {
+    const available = listExamples(system);
+    const suggestions = available.filter(
+      (e) => e.includes(name) || name.includes(e.replace(".html", ""))
+    );
+    error(
+      `Example "${name}" not found in ${system}`,
+      suggestions.length > 0 ? suggestions.map((s) => s.replace(".html", "")) : available.map((s) => s.replace(".html", ""))
+    );
+    return 1;
+  }
+  if (flags.open) {
+    openInBrowser(filePath);
+    console.log(`Opening ${filename} in browser...`);
+    return 0;
+  }
+  console.log(`Example: ${filename}`);
+  console.log(`Path: ${filePath}`);
+  console.log(`Use --open to view in browser.`);
+  return 0;
+}
+function handleReferences(system, segments) {
+  if (segments.length === 0) {
+    return listAllReferences(system);
+  }
+  const name = segments.join("/");
+  const filePath = join5(systemDir(system), "references", name);
+  if (!existsSync6(filePath)) {
+    const available = listReferences(system);
+    error(`Reference "${name}" not found in ${system}`, available);
+    return 1;
+  }
+  if (name.endsWith(".md")) {
+    markdown(readFile(filePath));
+    return 0;
+  }
+  console.log(`Reference: ${name}`);
+  console.log(`Path: ${filePath}`);
+  return 0;
+}
+function listAllReferences(system) {
+  const refs = listReferences(system);
+  if (refs.length === 0) {
+    console.log(`No references found in ${system}.`);
+    return 0;
+  }
+  heading(`${system} \u2014 References`);
+  list(refs);
+  blank();
+  return 0;
+}
+
+// src/cli.ts
+function showHelp() {
+  console.log(`
+Design Systems CLI
+
+Usage:
+  design-system list                              List all design systems
+  design-system <system>                          Show system overview
+  design-system <system> components list          List all components
+  design-system <system> components details <n>   Component description + source CSS/JS
+  design-system <system> tokens                   List token files
+  design-system <system> tokens/<name>            Pretty-print token values
+  design-system <system> principles               List principles
+  design-system <system> principles/<name>        Show principle content
+  design-system <system> architecture             List architecture areas
+  design-system <system> architecture/<path>      Navigate architecture tree
+  design-system <system> render <file>            Render markup with resolved deps
+  design-system <system> render -                 Render from stdin
+  design-system <system> examples                 List example files
+  design-system <system> references               List reference files
+
+Flags:
+  --open       Open HTML file in browser (examples)
+  --json       Output raw JSON (tokens)
+  --flat       Output flat path = value lines (tokens)
+  --html       Dump raw HTML to stdout
+  --systems-dir <path>  Override default systems directory
+  --help, -h   Show this help message
+`);
+}
+async function main() {
+  const { values, positionals } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      help: { type: "boolean", short: "h" },
+      open: { type: "boolean" },
+      json: { type: "boolean" },
+      flat: { type: "boolean" },
+      html: { type: "boolean" },
+      "systems-dir": { type: "string" }
+    },
+    allowPositionals: true,
+    strict: true
+  });
+  if (values["systems-dir"]) {
+    setSystemsRoot(values["systems-dir"]);
+  }
+  if (values.help && positionals.length === 0) {
+    showHelp();
+    process.exit(0);
+  }
+  const [first, ...rest] = positionals;
+  const second = rest.join("/");
+  if (!first) {
+    showHelp();
+    process.exit(0);
+  }
+  if (first === "list") {
+    process.exit(commandList());
+  }
+  if (!second) {
+    if (values.help) {
+      showHelp();
+      process.exit(0);
+    }
+    process.exit(commandShow(first));
+  }
+  if (rest[0] === "render") {
+    process.exit(await commandRender(first, rest.slice(1).join(" "), { html: values.html }));
+  }
+  const flags = {
+    open: values.open,
+    json: values.json,
+    flat: values.flat,
+    html: values.html
+  };
+  process.exit(await commandBrowse(first, second, flags));
+}
+main();

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@sourcescape/ds-cli",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "CLI for browsing design system definitions",
+  "license": "MIT",
+  "bin": {
+    "design-system": "./dist/cli.js"
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/cli.ts --format esm --dts --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}