@sourcescape/ds-cli 0.2.0 → 0.4.0

package/dist/cli.js

@@ -1,191 +1,29 @@
 #!/usr/bin/env node
+import {
+  buildPreviewHtml,
+  buildRegistry,
+  bundleJs,
+  descriptionMtime,
+  findComponent,
+  findComponentSources,
+  getSystemInfo,
+  listComponents,
+  listSystems,
+  readComponentJson,
+  readComponentMeta,
+  readDescription,
+  readFile,
+  readFullDescription,
+  resolveMarkup,
+  startPreviewServer,
+  suggestComponent,
+  systemDir,
+  systemExists
+} from "./chunk-U44UTENA.js";
 
 // src/cli.ts
 import { parseArgs } from "util";
 
-// src/systems.ts
-import { readFileSync, readdirSync, existsSync, statSync } from "fs";
-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(getSystemsRoot(), { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort();
-}
-function systemDir(system) {
-  return join(getSystemsRoot(), 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 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;
-}
-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 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, "component.js");
-  if (existsSync(stylePath)) css.push(stylePath);
-  if (existsSync(scriptPath)) js.push(scriptPath);
-  return { css, js };
-}
-
 // src/format.ts
 function heading(text) {
   console.log(`
@@ -236,12 +74,12 @@ function commandList() {
 }
 
 // src/commands/show.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
-import { join as join2 } from "path";
+import { existsSync, readFileSync } from "fs";
+import { join } 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"));
+  const path = join(systemDir(system), "references", "manifest.json");
+  if (!existsSync(path)) return [];
+  const data = JSON.parse(readFileSync(path, "utf-8"));
   return data.references || [];
 }
 function commandShow(system) {
@@ -292,8 +130,8 @@ function commandShow(system) {
 import { exec } from "child_process";
 
 // src/commands/components.ts
-import { join as join4, basename, relative } from "path";
-import { existsSync as existsSync4, readFileSync as readFileSync4, readdirSync as readdirSync2 } from "fs";
+import { join as join3, basename, relative } from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync3, readdirSync } from "fs";
 
 // src/search/tfidf.ts
 var STOP_WORDS = /* @__PURE__ */ new Set([
@@ -420,11 +258,11 @@ function cosineSimilarity(a, b) {
 }
 
 // src/search/indexer.ts
-import { readFileSync as readFileSync3, writeFileSync, existsSync as existsSync3 } from "fs";
-import { join as join3 } from "path";
+import { readFileSync as readFileSync2, writeFileSync, existsSync as existsSync2 } from "fs";
+import { join as join2 } from "path";
 var INDEX_FILE = ".search-index.json";
 function indexPath(system) {
-  return join3(systemDir(system), INDEX_FILE);
+  return join2(systemDir(system), INDEX_FILE);
 }
 function buildSearchIndex(system) {
   const components = listComponents(system);
@@ -471,9 +309,9 @@ function writeSearchIndex(system, index) {
 }
 function loadSearchIndex(system) {
   const path = indexPath(system);
-  if (!existsSync3(path)) return null;
+  if (!existsSync2(path)) return null;
   try {
-    const data = JSON.parse(readFileSync3(path, "utf-8"));
+    const data = JSON.parse(readFileSync2(path, "utf-8"));
     if (data.version !== 1) return null;
     return data;
   } catch {
@@ -633,7 +471,7 @@ function showDetails(system, name) {
   console.log(`  Kind:  ${found.kind}`);
   if (json?.tag) console.log(`  Tag:   ${json.tag}`);
   console.log(`  Path:  ${relPath}`);
-  const files = readdirSync2(found.dir);
+  const files = readdirSync(found.dir);
   console.log(`  Files: ${files.join(", ")}`);
   blank();
   if (json?.description) {
@@ -650,8 +488,8 @@ function showDetails(system, name) {
     console.log("```");
     blank();
   }
-  const descPath = join4(found.dir, "description.md");
-  if (existsSync4(descPath)) {
+  const descPath = join3(found.dir, "description.md");
+  if (existsSync3(descPath)) {
     subheading("Description (full)");
     blank();
     console.log(readFile(descPath));
@@ -662,7 +500,7 @@ function showDetails(system, name) {
       subheading(`Source CSS: ${basename(cssPath)}`);
       blank();
       console.log("```css");
-      console.log(readFileSync4(cssPath, "utf-8").trimEnd());
+      console.log(readFileSync3(cssPath, "utf-8").trimEnd());
       console.log("```");
       blank();
     }
@@ -672,7 +510,7 @@ function showDetails(system, name) {
       subheading(`Source JS: ${basename(jsPath)}`);
       blank();
       console.log("```js");
-      console.log(readFileSync4(jsPath, "utf-8").trimEnd());
+      console.log(readFileSync3(jsPath, "utf-8").trimEnd());
       console.log("```");
       blank();
     }
@@ -746,24 +584,24 @@ function rebuildIndex(system) {
 }
 
 // src/commands/references.ts
-import { existsSync as existsSync5, readFileSync as readFileSync5, readdirSync as readdirSync3 } from "fs";
-import { join as join5, extname } from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync4, readdirSync as readdirSync2 } from "fs";
+import { join as join4, extname } from "path";
 function referencesDir(system) {
-  return join5(systemDir(system), "references");
+  return join4(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"));
+  const path = join4(referencesDir(system), "manifest.json");
+  if (!existsSync4(path)) return null;
+  return JSON.parse(readFileSync4(path, "utf-8"));
 }
 function listReferenceFiles(system) {
   const dir = referencesDir(system);
-  if (!existsSync5(dir)) return [];
-  return readdirSync3(dir).filter((f) => f !== "manifest.json").sort();
+  if (!existsSync4(dir)) return [];
+  return readdirSync2(dir).filter((f) => f !== "manifest.json").sort();
 }
 function commandReferences(system, segments) {
   const dir = referencesDir(system);
-  if (!existsSync5(dir)) {
+  if (!existsSync4(dir)) {
     error(`No references directory for "${system}"`);
     return 1;
   }
@@ -793,8 +631,8 @@ function commandReferences(system, segments) {
     return 0;
   }
   const fileName = segments.join("/");
-  const filePath = join5(dir, fileName);
-  if (!existsSync5(filePath)) {
+  const filePath = join4(dir, fileName);
+  if (!existsSync4(filePath)) {
     const files = listReferenceFiles(system);
     const suggestions = files.filter(
       (f) => f.includes(fileName) || fileName.includes(f.replace(extname(f), ""))
@@ -802,301 +640,14 @@ function commandReferences(system, segments) {
     error(`Reference "${fileName}" not found`, suggestions);
     return 1;
   }
-  const content = readFileSync5(filePath, "utf-8");
+  const content = readFileSync4(filePath, "utf-8");
   process.stdout.write(content);
   return 0;
 }
 
 // src/commands/render.ts
-import { readFileSync as readFileSync8, existsSync as existsSync8 } from "fs";
-import { resolve as resolve2 } from "path";
-
-// src/resolve-deps.ts
-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 = [];
-  const tagMap = /* @__PURE__ */ new Map();
-  for (const comp of components) {
-    const found = findComponent(system, comp.name);
-    if (!found) continue;
-    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 = readFileSync7(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 = 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);
-      }
-    }
-    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(join7(entry.dir, "style.css"));
-    if (entry.hasJs) jsFiles.push(join7(entry.dir, "component.js"));
-  }
-  return { cssFiles, jsFiles, unmatchedTags };
-}
-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 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(readFileSync7(p, "utf-8"));
-  }
-  const inlinedCss = blocks.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>
-  <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 join8, extname as extname2 } from "path";
-import { readFile as readFile2 } from "fs/promises";
-import { existsSync as existsSync7 } 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 = join8(systemDir2, decodeURIComponent(url.pathname));
-      if (!existsSync7(filePath)) {
-        res.writeHead(404);
-        res.end("Not found");
-        return;
-      }
-      try {
-        const data = await readFile2(filePath);
-        const ext = extname2(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
+import { readFileSync as readFileSync5, existsSync as existsSync5 } from "fs";
+import { resolve } from "path";
 async function readStdin() {
   const chunks = [];
   for await (const chunk of process.stdin) chunks.push(chunk);
@@ -1122,12 +673,12 @@ async function commandRender(system, fileArg, flags) {
   if (fileArg === "-") {
     markup = await readStdin();
   } else {
-    const filePath = resolve2(fileArg);
-    if (!existsSync8(filePath)) {
+    const filePath = resolve(fileArg);
+    if (!existsSync5(filePath)) {
       error(`File not found: ${filePath}`);
       return 1;
     }
-    markup = readFileSync8(filePath, "utf-8");
+    markup = readFileSync5(filePath, "utf-8");
   }
   const registry = buildRegistry(system);
   const deps = resolveMarkup(registry, markup);
@@ -1186,6 +737,317 @@ function openInBrowser(target) {
   exec(`${cmd} "${target}"`);
 }
 
+// src/commands/health.ts
+import { readFileSync as readFileSync6, existsSync as existsSync6, readdirSync as readdirSync3 } from "fs";
+import { join as join5 } from "path";
+function pass(label) {
+  return { label, passed: true };
+}
+function fail(label, detail) {
+  return { label, passed: false, detail };
+}
+function commandHealth(system) {
+  if (!systemExists(system)) {
+    const suggestions = listSystems().filter(
+      (s) => s.includes(system) || system.includes(s)
+    );
+    error(`Design system "${system}" not found`, suggestions);
+    return 1;
+  }
+  const sysDir = systemDir(system);
+  const results = [];
+  heading("Folder \u2194 Tag consistency");
+  for (const kind of ["molecules", "cells"]) {
+    const kindDir = join5(sysDir, "components", kind);
+    if (!existsSync6(kindDir)) continue;
+    for (const d of readdirSync3(kindDir, { withFileTypes: true })) {
+      if (!d.isDirectory()) continue;
+      const compDir = join5(kindDir, d.name);
+      const json = readComponentJson(compDir);
+      if (!json?.tag) {
+        results.push(fail(
+          `${kind}/${d.name}: tag`,
+          "missing tag in description.json"
+        ));
+        continue;
+      }
+      const tagName = json.tag.replace(/^<|>$/g, "");
+      if (tagName !== d.name) {
+        results.push(fail(
+          `${kind}/${d.name}: tag`,
+          `folder "${d.name}" \u2260 tag "${tagName}"`
+        ));
+      } else {
+        results.push(pass(`${kind}/${d.name}: tag`));
+      }
+    }
+  }
+  heading("Required files");
+  for (const kind of ["molecules", "cells"]) {
+    const kindDir = join5(sysDir, "components", kind);
+    if (!existsSync6(kindDir)) continue;
+    for (const d of readdirSync3(kindDir, { withFileTypes: true })) {
+      if (!d.isDirectory()) continue;
+      const compDir = join5(kindDir, d.name);
+      if (!existsSync6(join5(compDir, "description.json"))) {
+        results.push(fail(`${kind}/${d.name}: description.json`, "missing"));
+      } else {
+        results.push(pass(`${kind}/${d.name}: description.json`));
+      }
+      if (!existsSync6(join5(compDir, "style.css"))) {
+        results.push(fail(`${kind}/${d.name}: style.css`, "missing"));
+      } else {
+        results.push(pass(`${kind}/${d.name}: style.css`));
+      }
+    }
+  }
+  heading("description.json completeness");
+  for (const kind of ["molecules", "cells"]) {
+    const kindDir = join5(sysDir, "components", kind);
+    if (!existsSync6(kindDir)) continue;
+    for (const d of readdirSync3(kindDir, { withFileTypes: true })) {
+      if (!d.isDirectory()) continue;
+      const compDir = join5(kindDir, d.name);
+      const json = readComponentJson(compDir);
+      if (!json) continue;
+      for (const field of ["description", "tag", "example"]) {
+        const val = json[field];
+        if (!val || typeof val === "string" && val.trim() === "") {
+          results.push(fail(
+            `${kind}/${d.name}: ${field}`,
+            `empty or missing "${field}" field`
+          ));
+        } else {
+          results.push(pass(`${kind}/${d.name}: ${field}`));
+        }
+      }
+    }
+  }
+  heading("index.js imports");
+  const indexPath2 = join5(sysDir, "src", "index.js");
+  if (!existsSync6(indexPath2)) {
+    results.push(fail("src/index.js", "file not found"));
+  } else {
+    const indexSrc = readFileSync6(indexPath2, "utf-8");
+    const importPaths = [...indexSrc.matchAll(/import\s+['"]([^'"]+)['"]/g)].map(
+      (m) => m[1]
+    );
+    for (const imp of importPaths) {
+      const resolved = join5(sysDir, "src", imp);
+      if (!existsSync6(resolved)) {
+        results.push(fail(`import: ${imp}`, "file not found"));
+      } else {
+        results.push(pass(`import: ${imp}`));
+      }
+    }
+    for (const kind of ["molecules", "cells"]) {
+      const kindDir = join5(sysDir, "components", kind);
+      if (!existsSync6(kindDir)) continue;
+      for (const d of readdirSync3(kindDir, { withFileTypes: true })) {
+        if (!d.isDirectory()) continue;
+        const jsPath = join5(kindDir, d.name, "component.js");
+        if (!existsSync6(jsPath)) continue;
+        const expectedFragment = `components/${kind}/${d.name}/component.js`;
+        const imported = importPaths.some((p) => p.includes(expectedFragment));
+        if (!imported) {
+          results.push(fail(
+            `${kind}/${d.name}: import`,
+            `component.js exists but not imported in index.js`
+          ));
+        } else {
+          results.push(pass(`${kind}/${d.name}: import`));
+        }
+      }
+    }
+  }
+  heading("Token files");
+  const tokensDir = join5(sysDir, "tokens");
+  for (const required of ["colors.json", "effects.json", "layout.json"]) {
+    if (!existsSync6(join5(tokensDir, required))) {
+      results.push(fail(`tokens/${required}`, "missing"));
+    } else {
+      results.push(pass(`tokens/${required}`));
+    }
+  }
+  heading("Assets");
+  const fontsDir = join5(sysDir, "assets", "fonts");
+  if (!existsSync6(fontsDir)) {
+    results.push(fail("assets/fonts", "directory not found"));
+  } else {
+    const fontFamilies = readdirSync3(fontsDir, { withFileTypes: true }).filter(
+      (d) => d.isDirectory()
+    );
+    if (fontFamilies.length === 0) {
+      results.push(fail("assets/fonts", "no font family directories"));
+    } else {
+      let hasWoff2 = false;
+      for (const fam of fontFamilies) {
+        const files = readdirSync3(join5(fontsDir, fam.name));
+        if (files.some((f) => f.endsWith(".woff2"))) hasWoff2 = true;
+      }
+      if (!hasWoff2) {
+        results.push(fail("assets/fonts", "no .woff2 files found"));
+      } else {
+        results.push(pass("assets/fonts"));
+      }
+    }
+  }
+  const passed = results.filter((r) => r.passed).length;
+  const failed = results.filter((r) => !r.passed).length;
+  if (failed > 0) {
+    heading("Failures");
+    for (const r of results) {
+      if (!r.passed) {
+        console.log(`  FAIL  ${r.label}  \u2014  ${r.detail}`);
+      }
+    }
+  }
+  console.log();
+  console.log(
+    `${passed} passed, ${failed} failed`
+  );
+  return failed > 0 ? 1 : 0;
+}
+
+// src/commands/check.ts
+import { readFileSync as readFileSync7, existsSync as existsSync7 } from "fs";
+import { resolve as resolve2 } from "path";
+function pass2(label) {
+  return { label, passed: true };
+}
+function fail2(label, detail) {
+  return { label, passed: false, detail };
+}
+async function readStdin2() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf-8");
+}
+function extractCustomElements(markup) {
+  const results = [];
+  const lines = markup.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const lineText = lines[i];
+    for (const m of lineText.matchAll(/<([a-z][a-z0-9]*-[a-z0-9-]*)([^>]*)/g)) {
+      results.push({
+        tag: m[1],
+        line: i + 1,
+        attrs: m[2]
+      });
+    }
+  }
+  return results;
+}
+function checkAttributes(registry, elements) {
+  const results = [];
+  for (const el of elements) {
+    const entry = registry.tagMap.get(el.tag);
+    if (!entry) continue;
+    for (const m of el.attrs.matchAll(/(\w+)=""/g)) {
+      results.push(fail2(
+        `line ${el.line}: <${el.tag}>`,
+        `empty attribute "${m[1]}"`
+      ));
+    }
+  }
+  return results;
+}
+async function commandCheck(system, fileArg) {
+  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> check <file|->", [
+      "ds fw-prd check page.xml",
+      "cat page.xml | ds fw-prd check -"
+    ]);
+    return 1;
+  }
+  let markup;
+  let fileName;
+  if (fileArg === "-") {
+    markup = await readStdin2();
+    fileName = "<stdin>";
+  } else {
+    const filePath = resolve2(fileArg);
+    if (!existsSync7(filePath)) {
+      error(`File not found: ${filePath}`);
+      return 1;
+    }
+    markup = readFileSync7(filePath, "utf-8");
+    fileName = fileArg;
+  }
+  const results = [];
+  heading(`Checking ${fileName}`);
+  const registry = buildRegistry(system);
+  const deps = resolveMarkup(registry, markup);
+  const elements = extractCustomElements(markup);
+  const uniqueTags = new Set(elements.map((e) => e.tag));
+  console.log(`  ${uniqueTags.size} unique custom elements found`);
+  console.log(`  ${elements.length} total usages
+`);
+  heading("Tag resolution");
+  for (const tag of uniqueTags) {
+    if (registry.tagMap.has(tag)) {
+      const entry = registry.tagMap.get(tag);
+      results.push(pass2(`<${tag}> \u2192 ${entry.kind}/${entry.name}`));
+    } else {
+      const lines = elements.filter((e) => e.tag === tag).map((e) => e.line);
+      results.push(fail2(
+        `<${tag}>`,
+        `unknown element (lines: ${lines.join(", ")})`
+      ));
+    }
+  }
+  heading("Dependencies");
+  const matchedCount = uniqueTags.size - deps.unmatchedTags.length;
+  console.log(`  ${deps.cssFiles.length} CSS files needed`);
+  console.log(`  ${deps.jsFiles.length} JS files needed`);
+  for (const f of [...deps.cssFiles, ...deps.jsFiles]) {
+    if (!existsSync7(f)) {
+      results.push(fail2(`dependency: ${f}`, "file not found"));
+    }
+  }
+  heading("Attributes");
+  const attrResults = checkAttributes(registry, elements);
+  results.push(...attrResults);
+  if (attrResults.length === 0) {
+    console.log("  No attribute issues found");
+  }
+  heading("Structure");
+  for (const tag of uniqueTags) {
+    const opens = (markup.match(new RegExp(`<${tag}[\\s>]`, "g")) || []).length;
+    const closes = (markup.match(new RegExp(`</${tag}>`, "g")) || []).length;
+    const selfClosing = (markup.match(new RegExp(`<${tag}[^>]*/\\s*>`, "g")) || []).length;
+    const expectedCloses = opens - selfClosing;
+    if (expectedCloses > 0 && closes < expectedCloses) {
+      results.push(fail2(
+        `<${tag}>`,
+        `${opens} opens, ${closes} closes (${expectedCloses - closes} unclosed)`
+      ));
+    } else {
+      results.push(pass2(`<${tag}>: balanced`));
+    }
+  }
+  const passed = results.filter((r) => r.passed).length;
+  const failed = results.filter((r) => !r.passed).length;
+  if (failed > 0) {
+    heading("Failures");
+    for (const r of results) {
+      if (!r.passed) {
+        console.log(`  FAIL  ${r.label}  \u2014  ${r.detail}`);
+      }
+    }
+  }
+  console.log();
+  console.log(`${passed} passed, ${failed} failed`);
+  return failed > 0 ? 1 : 0;
+}
+
 // src/cli.ts
 function showHelp() {
   console.log(`
@@ -1203,6 +1065,9 @@ Usage:
   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> health                   Check design system consistency
+  design-system <system> check <file>             Validate markup against design system
+  design-system <system> check -                  Validate from stdin
 
 Flags:
   --html       Dump raw HTML to stdout
@@ -1245,6 +1110,12 @@ async function main() {
   if (rest[0] === "render") {
     process.exit(await commandRender(first, rest.slice(1).join(" "), { html: values.html }));
   }
+  if (rest[0] === "health") {
+    process.exit(commandHealth(first));
+  }
+  if (rest[0] === "check") {
+    process.exit(await commandCheck(first, rest.slice(1).join(" ")));
+  }
   const flags = {
     html: values.html
   };