@sourcescape/ds-cli 0.1.0 → 0.2.0

package/dist/cli.js

@@ -5,17 +5,30 @@ 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);
+import { join, resolve } from "path";
+function getSystemsRoot() {
+  const dir = process.env.DESIGN_SYSTEMS_DIR;
+  if (!dir) {
+    console.error("Error: DESIGN_SYSTEMS_DIR environment variable is required.");
+    console.error("Set it to the path containing your design system definitions.");
+    process.exit(1);
+  }
+  return resolve(dir);
+}
+function readComponentJson(componentDir) {
+  const jsonPath = join(componentDir, "description.json");
+  if (!existsSync(jsonPath)) return null;
+  try {
+    return JSON.parse(readFileSync(jsonPath, "utf-8"));
+  } catch {
+    return null;
+  }
 }
 function listSystems() {
-  return readdirSync(SYSTEMS_ROOT, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort();
+  return readdirSync(getSystemsRoot(), { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort();
 }
 function systemDir(system) {
-  return join(SYSTEMS_ROOT, system);
+  return join(getSystemsRoot(), system);
 }
 function systemExists(system) {
   return existsSync(systemDir(system));
@@ -64,12 +77,24 @@ function listComponents(system) {
     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)
-      });
+      const compDir = join(kindDir, name);
+      const json = readComponentJson(compDir);
+      if (json) {
+        results.push({
+          name,
+          kind,
+          description: json.description,
+          tag: json.tag,
+          example: json.example
+        });
+      } else {
+        const descPath = join(compDir, "description.md");
+        results.push({
+          name,
+          kind,
+          description: readFirstParagraph(descPath)
+        });
+      }
     }
   }
   return results;
@@ -95,77 +120,67 @@ function allComponentNames(system) {
   }
   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 readComponentMeta(system, componentName) {
+  const found = findComponent(system, componentName);
+  if (!found) return { name: componentName, tag: "", description: "" };
+  const descPath = join(found.dir, "description.md");
+  if (!existsSync(descPath)) return { name: componentName, tag: "", description: "" };
+  const lines = readFileSync(descPath, "utf-8").split("\n");
+  let name = componentName;
+  let tag = "";
+  let description = "";
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.startsWith("# ")) {
+      name = line.slice(2).trim();
+      continue;
+    }
+    if (!tag && /^`<.+>`$/.test(line.trim())) {
+      tag = line.trim();
+      continue;
+    }
+    if (name && line.trim().length > 0 && !line.startsWith("#") && !line.startsWith("`")) {
+      description = line.trim();
+      break;
+    }
+  }
+  return { name, tag: tag || "*(auto)*", description };
+}
+function readFullDescription(system, name, kind) {
+  const compDir = join(systemDir(system), "components", kind, name);
+  if (!existsSync(compDir)) return "";
+  const mdPath = join(compDir, "description.md");
+  if (existsSync(mdPath)) {
+    return readFileSync(mdPath, "utf-8");
+  }
+  const json = readComponentJson(compDir);
+  return json?.description ?? "";
+}
+function descriptionMtime(system, name, kind) {
+  const compDir = join(systemDir(system), "components", kind, name);
+  if (!existsSync(compDir)) return 0;
+  const mdPath = join(compDir, "description.md");
+  if (existsSync(mdPath)) {
+    return statSync(mdPath).mtimeMs;
+  }
+  const jsonPath = join(compDir, "description.json");
+  if (existsSync(jsonPath)) {
+    return statSync(jsonPath).mtimeMs;
+  }
+  return 0;
+}
 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");
+  const scriptPath = join(found.dir, "component.js");
   if (existsSync(stylePath)) css.push(stylePath);
   if (existsSync(scriptPath)) js.push(scriptPath);
   return { css, js };
@@ -181,12 +196,6 @@ 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));
@@ -196,9 +205,6 @@ function descriptionList(items, indent = 2) {
     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) {
@@ -229,82 +235,15 @@ function commandList() {
   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
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { join as join2 } from "path";
+function loadManifest(system) {
+  const path = join2(systemDir(system), "references", "manifest.json");
+  if (!existsSync2(path)) return [];
+  const data = JSON.parse(readFileSync2(path, "utf-8"));
+  return data.references || [];
+}
 function commandShow(system) {
   if (!systemExists(system)) {
     const available = listSystems();
@@ -321,48 +260,312 @@ function commandShow(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);
+  console.log("\n## Component Inventory");
+  function printTable(label, items) {
+    const metas = items.map((c) => readComponentMeta(system, c.name));
+    console.log(`
+### ${label} (${items.length} active)
+`);
+    console.log("| Component | Tag | Description |");
+    console.log("|---|---|---|");
+    for (const m of metas) {
+      console.log(`| ${m.name} | ${m.tag} | ${m.description} |`);
+    }
+  }
+  if (molecules.length > 0) printTable("Molecules", molecules);
+  if (cells.length > 0) printTable("Cells", cells);
+  const refs = loadManifest(system);
+  if (refs.length > 0) {
+    console.log("\n## References\n");
+    for (const ref of refs) {
+      console.log(`- \`${ref.file}\` \u2014 ${ref.description}`);
+    }
+  }
   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";
+import { join as join4, basename, relative } from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync4, readdirSync as readdirSync2 } from "fs";
+
+// src/search/tfidf.ts
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "the",
+  "and",
+  "or",
+  "but",
+  "in",
+  "on",
+  "at",
+  "to",
+  "for",
+  "of",
+  "with",
+  "by",
+  "from",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "has",
+  "have",
+  "had",
+  "do",
+  "does",
+  "did",
+  "will",
+  "would",
+  "could",
+  "should",
+  "may",
+  "might",
+  "can",
+  "this",
+  "that",
+  "these",
+  "those",
+  "it",
+  "its",
+  "not",
+  "no",
+  "as",
+  "if",
+  "so",
+  "than",
+  "up",
+  "out",
+  "about",
+  "into",
+  "over",
+  "after",
+  "before",
+  "between",
+  "under",
+  "such",
+  "each",
+  "all",
+  "any",
+  "both",
+  "more",
+  "other",
+  "some"
+]);
+function stripMarkdown(text) {
+  return text.replace(/^#{1,6}\s+/gm, "").replace(/```[\s\S]*?```/g, "").replace(/`[^`]+`/g, "").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/[|─┌┐└┘├┤┬┴┼]/g, " ").replace(/<[^>]+>/g, "").replace(/\*\*([^*]+)\*\*/g, "$1").replace(/\*([^*]+)\*/g, "$1").replace(/!\[[^\]]*\]\([^)]+\)/g, "").replace(/^[-*]\s+/gm, "").replace(/^\d+\.\s+/gm, "").replace(/^>\s+/gm, "");
+}
+function tokenize(text) {
+  return text.toLowerCase().replace(/[^a-z0-9-]/g, " ").split(/\s+/).filter((t) => t.length > 1 && !STOP_WORDS.has(t));
+}
+function computeTF(tokens) {
+  const counts = {};
+  for (const t of tokens) {
+    counts[t] = (counts[t] || 0) + 1;
+  }
+  const len = tokens.length || 1;
+  const tf = {};
+  for (const [term, count] of Object.entries(counts)) {
+    tf[term] = count / len;
+  }
+  return tf;
+}
+function computeIDF(documents) {
+  const N = documents.length || 1;
+  const docFreq = {};
+  for (const tokens of documents) {
+    const seen = new Set(tokens);
+    for (const t of seen) {
+      docFreq[t] = (docFreq[t] || 0) + 1;
+    }
+  }
+  const idf = {};
+  for (const [term, df] of Object.entries(docFreq)) {
+    idf[term] = Math.log(1 + N / df);
+  }
+  return idf;
+}
+function computeTFIDF(tf, idf) {
+  const tfidf = {};
+  for (const [term, tfVal] of Object.entries(tf)) {
+    const idfVal = idf[term] ?? Math.log(1 + 1);
+    tfidf[term] = tfVal * idfVal;
+  }
+  return tfidf;
+}
+function cosineSimilarity(a, b) {
+  let dot = 0;
+  let magA = 0;
+  let magB = 0;
+  for (const [term, val] of Object.entries(a)) {
+    magA += val * val;
+    if (term in b) {
+      dot += val * b[term];
+    }
+  }
+  for (const val of Object.values(b)) {
+    magB += val * val;
+  }
+  const denom = Math.sqrt(magA) * Math.sqrt(magB);
+  return denom === 0 ? 0 : dot / denom;
+}
+
+// src/search/indexer.ts
+import { readFileSync as readFileSync3, writeFileSync, existsSync as existsSync3 } from "fs";
+import { join as join3 } from "path";
+var INDEX_FILE = ".search-index.json";
+function indexPath(system) {
+  return join3(systemDir(system), INDEX_FILE);
+}
+function buildSearchIndex(system) {
+  const components = listComponents(system);
+  const docTokens = [];
+  const rawEntries = [];
+  for (const comp of components) {
+    const fullDesc = readFullDescription(system, comp.name, comp.kind);
+    const plain = stripMarkdown(fullDesc || comp.description);
+    const tokens = tokenize(`${comp.name} ${plain}`);
+    const unique = [...new Set(tokens)];
+    docTokens.push(unique);
+    rawEntries.push({
+      name: comp.name,
+      kind: comp.kind,
+      summary: comp.description.slice(0, 200),
+      tokens: unique,
+      tf: computeTF(tokens),
+      mtime: descriptionMtime(system, comp.name, comp.kind)
+    });
+  }
+  const idf = computeIDF(docTokens);
+  const entries = rawEntries.map((raw) => ({
+    name: raw.name,
+    kind: raw.kind,
+    summary: raw.summary,
+    tfidf: computeTFIDF(raw.tf, idf),
+    tokens: raw.tokens,
+    descriptionMtime: raw.mtime
+  }));
+  return {
+    version: 1,
+    buildTime: (/* @__PURE__ */ new Date()).toISOString(),
+    systemName: system,
+    documentCount: entries.length,
+    idf,
+    entries
+  };
+}
+function writeSearchIndex(system, index) {
+  try {
+    writeFileSync(indexPath(system), JSON.stringify(index, null, 2), "utf-8");
+  } catch {
+  }
+}
+function loadSearchIndex(system) {
+  const path = indexPath(system);
+  if (!existsSync3(path)) return null;
+  try {
+    const data = JSON.parse(readFileSync3(path, "utf-8"));
+    if (data.version !== 1) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}
+function isStale(system, index) {
+  for (const entry of index.entries) {
+    const currentMtime = descriptionMtime(system, entry.name, entry.kind);
+    if (currentMtime !== entry.descriptionMtime) return true;
+  }
+  const currentCount = listComponents(system).length;
+  if (currentCount !== index.documentCount) return true;
+  return false;
+}
+function ensureSearchIndex(system) {
+  const existing = loadSearchIndex(system);
+  if (existing && !isStale(system, existing)) {
+    return existing;
+  }
+  const index = buildSearchIndex(system);
+  writeSearchIndex(system, index);
+  return index;
+}
+
+// src/search/search.ts
+var NAME_WEIGHT = 0.4;
+var KEYWORD_WEIGHT = 0.3;
+var TFIDF_WEIGHT = 0.3;
+function nameScore(queryTokens, componentName) {
+  const name = componentName.toLowerCase();
+  const parts = name.split("-");
+  let matched = 0;
+  for (const qt of queryTokens) {
+    if (name.includes(qt) || parts.some((p) => p.includes(qt) || qt.includes(p))) {
+      matched++;
+    }
+  }
+  return queryTokens.length === 0 ? 0 : matched / queryTokens.length;
+}
+function keywordScore(queryTokens, docTokens) {
+  if (queryTokens.length === 0) return 0;
+  const docSet = new Set(docTokens);
+  let matched = 0;
+  for (const qt of queryTokens) {
+    if (docSet.has(qt)) {
+      matched++;
+    } else {
+      for (const dt of docTokens) {
+        if (dt.includes(qt) || qt.includes(dt)) {
+          matched += 0.5;
+          break;
+        }
+      }
+    }
+  }
+  return matched / queryTokens.length;
+}
+function searchComponents(system, query) {
+  const index = ensureSearchIndex(system);
+  const queryTokens = tokenize(query);
+  if (queryTokens.length === 0) return [];
+  const queryTF = computeTF(queryTokens);
+  const queryVec = computeTFIDF(queryTF, index.idf);
+  const results = [];
+  for (const entry of index.entries) {
+    const ns = nameScore(queryTokens, entry.name);
+    const ks = keywordScore(queryTokens, entry.tokens);
+    const ts = cosineSimilarity(queryVec, entry.tfidf);
+    const score = NAME_WEIGHT * ns + KEYWORD_WEIGHT * ks + TFIDF_WEIGHT * ts;
+    if (score > 0.01) {
+      results.push({
+        name: entry.name,
+        kind: entry.kind,
+        summary: entry.summary,
+        score: Math.round(score * 100) / 100
+      });
+    }
+  }
+  results.sort((a, b) => b.score - a.score);
+  return results;
+}
+
+// src/commands/components.ts
 async function commandComponents(system, args) {
   const [subcommand, ...rest] = args;
   if (!subcommand || subcommand === "list") {
     return listAllComponents(system);
   }
+  if (subcommand === "inventory") {
+    return showInventory(system);
+  }
   if (subcommand === "details") {
     const name = rest[0];
     if (!name) {
@@ -371,6 +574,17 @@ async function commandComponents(system, args) {
     }
     return showDetails(system, name);
   }
+  if (subcommand === "search") {
+    const query = rest.join(" ");
+    if (!query) {
+      error("Usage: ds <system> components search <query>");
+      return 1;
+    }
+    return showSearch(system, query);
+  }
+  if (subcommand === "index") {
+    return rebuildIndex(system);
+  }
   return showDetails(system, subcommand);
 }
 function listAllComponents(system) {
@@ -385,14 +599,20 @@ function listAllComponents(system) {
   if (molecules.length > 0) {
     subheading(`Molecules (${molecules.length})`);
     descriptionList(
-      molecules.map((c) => ({ name: c.name, description: c.description })),
+      molecules.map((c) => ({
+        name: c.tag ? `${c.name}  ${c.tag}` : c.name,
+        description: c.description
+      })),
       4
     );
   }
   if (cells.length > 0) {
     subheading(`Cells (${cells.length})`);
     descriptionList(
-      cells.map((c) => ({ name: c.name, description: c.description })),
+      cells.map((c) => ({
+        name: c.tag ? `${c.name}  ${c.tag}` : c.name,
+        description: c.description
+      })),
       4
     );
   }
@@ -408,49 +628,272 @@ function showDetails(system, name) {
   }
   const sysDir = systemDir(system);
   const relPath = relative(sysDir, found.dir);
+  const json = readComponentJson(found.dir);
   heading(`${name}`);
   console.log(`  Kind:  ${found.kind}`);
+  if (json?.tag) console.log(`  Tag:   ${json.tag}`);
   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)) {
+  if (json?.description) {
     subheading("Description");
     blank();
+    console.log(`  ${json.description}`);
+    blank();
+  }
+  if (json?.example) {
+    subheading("Example");
+    blank();
+    console.log("```xml");
+    console.log(json.example);
+    console.log("```");
+    blank();
+  }
+  const descPath = join4(found.dir, "description.md");
+  if (existsSync4(descPath)) {
+    subheading("Description (full)");
+    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)}`);
+      subheading(`Source CSS: ${basename(cssPath)}`);
       blank();
       console.log("```css");
-      console.log(readFileSync2(cssPath, "utf-8").trimEnd());
+      console.log(readFileSync4(cssPath, "utf-8").trimEnd());
       console.log("```");
       blank();
     }
   }
   if (sources.js.length > 0) {
     for (const jsPath of sources.js) {
-      subheading(`Source JS: ${basename2(jsPath)}`);
+      subheading(`Source JS: ${basename(jsPath)}`);
       blank();
       console.log("```js");
-      console.log(readFileSync2(jsPath, "utf-8").trimEnd());
+      console.log(readFileSync4(jsPath, "utf-8").trimEnd());
       console.log("```");
       blank();
     }
   }
   return 0;
 }
+function showInventory(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");
+  const printTable = (items) => {
+    console.log("| Name | Tag | Description |");
+    console.log("|------|-----|-------------|");
+    for (const c of items) {
+      const tag = c.tag ? `\`${c.tag}\`` : "";
+      console.log(`| ${c.name} | ${tag} | ${c.description} |`);
+    }
+  };
+  console.log(`# ${system} \u2014 Component Inventory
+`);
+  if (molecules.length > 0) {
+    console.log(`## Molecules (${molecules.length})
+`);
+    printTable(molecules);
+    console.log();
+  }
+  if (cells.length > 0) {
+    console.log(`## Cells (${cells.length})
+`);
+    printTable(cells);
+    console.log();
+  }
+  return 0;
+}
+function showSearch(system, query) {
+  const results = searchComponents(system, query);
+  const total = listComponents(system).length;
+  console.log(`
+Search: "${query}" (${total} components indexed)`);
+  console.log("\u2500".repeat(50));
+  if (results.length === 0) {
+    console.log("\n  No matches found.\n");
+    return 0;
+  }
+  console.log(`
+  Results (${results.length} match${results.length === 1 ? "" : "es"})
+`);
+  const maxName = Math.max(...results.map((r) => r.name.length));
+  const maxKind = Math.max(...results.map((r) => r.kind.length + 2));
+  for (const r of results) {
+    const name = r.name.padEnd(maxName);
+    const kind = `(${r.kind})`.padEnd(maxKind);
+    const score = r.score.toFixed(2);
+    console.log(`  ${name}  ${kind}  ${score}  ${r.summary}`);
+  }
+  blank();
+  return 0;
+}
+function rebuildIndex(system) {
+  console.log(`Building search index for ${system}...`);
+  const index = buildSearchIndex(system);
+  writeSearchIndex(system, index);
+  console.log(`  Documents: ${index.documentCount}`);
+  console.log(`  Terms:     ${Object.keys(index.idf).length}`);
+  console.log(`  Written:   ${index.buildTime}`);
+  return 0;
+}
+
+// src/commands/references.ts
+import { existsSync as existsSync5, readFileSync as readFileSync5, readdirSync as readdirSync3 } from "fs";
+import { join as join5, extname } from "path";
+function referencesDir(system) {
+  return join5(systemDir(system), "references");
+}
+function loadManifest2(system) {
+  const path = join5(referencesDir(system), "manifest.json");
+  if (!existsSync5(path)) return null;
+  return JSON.parse(readFileSync5(path, "utf-8"));
+}
+function listReferenceFiles(system) {
+  const dir = referencesDir(system);
+  if (!existsSync5(dir)) return [];
+  return readdirSync3(dir).filter((f) => f !== "manifest.json").sort();
+}
+function commandReferences(system, segments) {
+  const dir = referencesDir(system);
+  if (!existsSync5(dir)) {
+    error(`No references directory for "${system}"`);
+    return 1;
+  }
+  if (segments.length === 0) {
+    const files = listReferenceFiles(system);
+    if (files.length === 0) {
+      console.log("No reference files.");
+      return 0;
+    }
+    const manifest = loadManifest2(system);
+    const lookup = /* @__PURE__ */ new Map();
+    if (manifest) {
+      for (const entry of manifest.references) {
+        lookup.set(entry.file, entry);
+      }
+    }
+    heading(`References (${files.length})`);
+    descriptionList(
+      files.map((f) => {
+        const entry = lookup.get(f);
+        return {
+          name: f,
+          description: entry ? entry.description : ""
+        };
+      })
+    );
+    return 0;
+  }
+  const fileName = segments.join("/");
+  const filePath = join5(dir, fileName);
+  if (!existsSync5(filePath)) {
+    const files = listReferenceFiles(system);
+    const suggestions = files.filter(
+      (f) => f.includes(fileName) || fileName.includes(f.replace(extname(f), ""))
+    );
+    error(`Reference "${fileName}" not found`, suggestions);
+    return 1;
+  }
+  const content = readFileSync5(filePath, "utf-8");
+  process.stdout.write(content);
+  return 0;
+}
 
 // src/commands/render.ts
-import { readFileSync as readFileSync4, existsSync as existsSync5 } from "fs";
+import { readFileSync as readFileSync8, existsSync as existsSync8 } 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";
+import { readFileSync as readFileSync7, existsSync as existsSync6 } from "fs";
+import { join as join7, relative as relative2 } from "path";
+
+// src/tokens.ts
+import { readFileSync as readFileSync6, readdirSync as readdirSync4 } from "fs";
+import { join as join6, basename as basename2 } from "path";
+function loadTokens(system) {
+  const dir = join6(systemDir(system), "tokens");
+  const files = readdirSync4(dir).filter((f) => f.endsWith(".json")).sort();
+  return files.map((f) => ({
+    name: basename2(f, ".json"),
+    data: JSON.parse(readFileSync6(join6(dir, f), "utf-8"))
+  }));
+}
+function walkTokens(obj, path = []) {
+  const leaves = [];
+  for (const [key, val] of Object.entries(obj)) {
+    if (key.startsWith("$")) continue;
+    const child = val;
+    if (child.$type !== void 0 && child.$value !== void 0) {
+      leaves.push({ path: [...path, key], type: child.$type, value: child.$value });
+    } else if (typeof child === "object" && child !== null) {
+      leaves.push(...walkTokens(child, [...path, key]));
+    }
+  }
+  return leaves;
+}
+function toCssVarName(path) {
+  return `--${path.join("-")}`;
+}
+function formatValue(type, value) {
+  switch (type) {
+    case "color":
+    case "dimension":
+    case "gradient":
+    case "duration":
+      return String(value);
+    case "fontFamily": {
+      const families = value;
+      const generics = ["serif", "sans-serif", "monospace", "cursive", "fantasy", "system-ui"];
+      return families.map((f) => {
+        if (generics.includes(f) || !/\s/.test(f)) return f;
+        return f.includes("'") ? `"${f}"` : `'${f}'`;
+      }).join(", ");
+    }
+    // Composite types — skip
+    case "typography":
+    case "object":
+    case "cubicBezier":
+      return null;
+    default:
+      return null;
+  }
+}
+function generateTokensCss(system) {
+  const tokenFiles = loadTokens(system);
+  const groups = [];
+  for (const { name, data } of tokenFiles) {
+    const leaves = walkTokens(data);
+    const vars = [];
+    for (const leaf of leaves) {
+      const formatted = formatValue(leaf.type, leaf.value);
+      if (formatted !== null) {
+        vars.push(`    ${toCssVarName(leaf.path)}: ${formatted};`);
+      }
+    }
+    if (vars.length > 0) {
+      groups.push({ name, vars });
+    }
+  }
+  const lines = ["@layer tokens {", "  :root {"];
+  for (let i = 0; i < groups.length; i++) {
+    const { name, vars } = groups[i];
+    if (i > 0) lines.push("");
+    lines.push(`    /* ${name}.json */`);
+    lines.push(...vars);
+  }
+  lines.push("  }", "}");
+  return lines.join("\n") + "\n";
+}
+
+// src/resolve-deps.ts
 function buildRegistry(system) {
   const components = listComponents(system);
   const entries = [];
@@ -458,14 +901,14 @@ function buildRegistry(system) {
   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 scriptPath = join7(found.dir, "component.js");
+    const stylePath = join7(found.dir, "style.css");
+    const hasJs = existsSync6(scriptPath);
+    const hasCss = existsSync6(stylePath);
     const tags = [];
     const dynamicTags = [];
     if (hasJs) {
-      const js = readFileSync3(scriptPath, "utf-8");
+      const js = readFileSync7(scriptPath, "utf-8");
       for (const m of js.matchAll(/customElements\.define\(\s*['"]([^'"]+)['"]/g)) {
         tags.push(m[1]);
       }
@@ -480,7 +923,7 @@ function buildRegistry(system) {
       }
     }
     if (hasCss) {
-      const css = readFileSync3(stylePath, "utf-8");
+      const css = readFileSync7(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);
@@ -538,35 +981,43 @@ function resolveMarkup(registry, markup) {
   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"));
+    if (entry.hasCss) cssFiles.push(join7(entry.dir, "style.css"));
+    if (entry.hasJs) jsFiles.push(join7(entry.dir, "component.js"));
   }
   return { cssFiles, jsFiles, unmatchedTags };
 }
-function buildPreviewHtml(system, markup, deps) {
+async function bundleJs(system) {
+  const entrypoint = join7(systemDir(system), "src", "index.js");
+  if (!existsSync6(entrypoint)) return null;
+  const result = await Bun.build({
+    entrypoints: [entrypoint],
+    bundle: true
+  });
+  if (!result.success) {
+    console.warn("Bundle failed:", result.logs);
+    return null;
+  }
+  return await result.outputs[0].text();
+}
+function buildPreviewHtml(system, markup, deps, bundledJs) {
   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"));
-    }
+  const blocks = ["@layer tokens, base, components;"];
+  const tokensCss = generateTokensCss(system);
+  blocks.push("/* tokens (generated) */");
+  blocks.push(tokensCss);
+  const baseCss = join7(sysDir, "src", "_shared", "_base.css");
+  if (existsSync6(baseCss)) {
+    blocks.push(`/* ${relative2(sysDir, baseCss)} */`);
+    blocks.push(readFileSync7(baseCss, "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"));
+    blocks.push(readFileSync7(p, "utf-8"));
   }
   const inlinedCss = blocks.join("\n");
-  const scriptTags = deps.jsFiles.map((p) => `  <script type="module" src="/${relative2(sysDir, p)}"></script>`).join("\n");
+  const scriptTags = bundledJs ? `  <script>
+${bundledJs}
+  </script>` : deps.jsFiles.map((p) => `  <script type="module" src="/${relative2(sysDir, p)}"></script>`).join("\n");
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -585,9 +1036,9 @@ ${scriptTags}
 
 // src/preview-server.ts
 import { createServer } from "http";
-import { join as join4, extname } from "path";
+import { join as join8, extname as extname2 } from "path";
 import { readFile as readFile2 } from "fs/promises";
-import { existsSync as existsSync4 } from "fs";
+import { existsSync as existsSync7 } from "fs";
 var MIME_TYPES = {
   ".html": "text/html; charset=utf-8",
   ".css": "text/css; charset=utf-8",
@@ -613,15 +1064,15 @@ function startPreviewServer(systemDir2, opts) {
         res.end(opts.html);
         return;
       }
-      const filePath = join4(systemDir2, decodeURIComponent(url.pathname));
-      if (!existsSync4(filePath)) {
+      const filePath = join8(systemDir2, decodeURIComponent(url.pathname));
+      if (!existsSync7(filePath)) {
         res.writeHead(404);
         res.end("Not found");
         return;
       }
       try {
         const data = await readFile2(filePath);
-        const ext = extname(filePath).toLowerCase();
+        const ext = extname2(filePath).toLowerCase();
         const contentType = MIME_TYPES[ext] ?? "application/octet-stream";
         res.writeHead(200, { "Content-Type": contentType });
         res.end(data);
@@ -672,18 +1123,19 @@ async function commandRender(system, fileArg, flags) {
     markup = await readStdin();
   } else {
     const filePath = resolve2(fileArg);
-    if (!existsSync5(filePath)) {
+    if (!existsSync8(filePath)) {
       error(`File not found: ${filePath}`);
       return 1;
     }
-    markup = readFileSync4(filePath, "utf-8");
+    markup = readFileSync8(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);
+  const js = await bundleJs(system);
+  const html = buildPreviewHtml(system, markup, deps, js);
   if (flags.html) {
     process.stdout.write(html);
     return 0;
@@ -720,27 +1172,12 @@ async function commandBrowse(system, path, flags) {
   switch (section) {
     case "components":
       return commandComponents(system, segments.slice(1));
+    case "references":
+      return commandReferences(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"
-      ]);
+      error(`Unknown section "${section}"`, ["components", "references"]);
       return 1;
   }
 }
@@ -748,198 +1185,6 @@ 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() {
@@ -950,25 +1195,21 @@ 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 inventory     Generate markdown inventory table
   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> components search <q>    Search components by query
+  design-system <system> components index         Rebuild search index
+  design-system <system> references               List reference files
+  design-system <system> references <file>        Display reference file
   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
+
+Environment:
+  DESIGN_SYSTEMS_DIR   Path to directory containing design system definitions (required)
 `);
 }
 async function main() {
@@ -976,18 +1217,11 @@ async function main() {
     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" }
+      html: { type: "boolean" }
     },
     allowPositionals: true,
     strict: true
   });
-  if (values["systems-dir"]) {
-    setSystemsRoot(values["systems-dir"]);
-  }
   if (values.help && positionals.length === 0) {
     showHelp();
     process.exit(0);
@@ -1012,9 +1246,6 @@ async function main() {
     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));