@eco-ds/registry-doctor 0.1.0

package/README.md

@@ -0,0 +1,123 @@
+# @eco-ds/registry-doctor
+
+> **Status: EXPERIMENTAL / DRAFT**
+> This package is not yet published. It is read-only and will never modify your project.
+
+Diagnoses whether a consuming project is correctly set up to use [DTN Design System](https://eco-design-system-2.dtn.com) registry components.
+
+A component can compile and render but still not match the DTN registry preview if the theme, component file, font setup, Tailwind token mapping, or app shell is incomplete. This tool checks all of that.
+
+---
+
+## Usage
+
+### After publish (product teams)
+
+```bash
+# Check current directory
+npx @eco-ds/registry-doctor
+
+# Check a specific component
+npx @eco-ds/registry-doctor --component button
+
+# JSON output for CI
+npx @eco-ds/registry-doctor --json
+```
+
+### Local development (maintainers, from repo root)
+
+```bash
+node packages/registry-doctor/bin/registry-doctor.js \
+  --project . \
+  --registry-root ./public/r \
+  --registry-json ./registry.json \
+  --component button
+```
+
+Or via the npm script (forwards all args):
+
+```bash
+npm run registry:doctor -- --project . --component button
+npm run registry:doctor -- --project ../my-app --component brand-header --json
+```
+
+---
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--project <path>` | cwd | Target consuming project |
+| `--component <name>` | `button` | Component to check |
+| `--registry <url>` | `https://eco-design-system-2.dtn.com/r/registry.json` | Registry JSON URL |
+| `--registry-root <path>` | — | Local registry output root (e.g. `./public/r`). When provided, loads `registry.json` from this directory and skips remote fetch. |
+| `--registry-json <path>` | — | Local source `registry.json`. Skips remote fetch. |
+| `--live` | disabled | Extra reachability checks (pings registry URL) |
+| `--json` | disabled | Output structured JSON |
+| `--help`, `-h` | — | Show usage |
+
+When `--registry-root` and `--registry-json` are both omitted, the CLI fetches metadata from the deployed registry URL. This requires network access.
+
+---
+
+## What It Checks
+
+| # | Check | Severity | Description |
+|---|-------|----------|-------------|
+| 1 | `components-json` | FAIL | `components.json` exists and is valid |
+| 2 | `registry-mapping` | WARN | `@dtn` registry mapping configured |
+| 3 | `tailwind-installed` | FAIL | Tailwind CSS in dependencies (v4 preferred) |
+| 4 | `shadcn-setup` | WARN | shadcn/ui style configured |
+| 5 | `global-css` | FAIL | Global CSS file exists with Tailwind imports |
+| 6 | `theme-tokens` | FAIL/WARN | DTN theme tokens present in CSS |
+| 7 | `theme-inline` | WARN | `@theme inline` directive (Tailwind v4) |
+| 8 | `component-tokens` | WARN/SKIP | Component-specific CSS variables |
+| 9 | `component-match` | FAIL/WARN | Local component matches registry version |
+| 10 | `dependencies` | WARN | Required npm dependencies installed |
+| 11 | `font-setup` | WARN | Inter font loaded and bound to `--font-sans` |
+| 12 | `app-shell-css` | FAIL | Root layout imports global CSS |
+| 13 | `registry-reachable` | FAIL | Registry URL responds (requires `--live`) |
+| 14 | `component-collisions` | WARN/SKIP | Generic shadcn components that should be DTN |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | All checks passed (warnings are acceptable) |
+| `1` | One or more checks failed, or registry metadata could not be loaded |
+
+---
+
+## Remote vs Local Mode
+
+**Remote mode** (default, no `--registry-root`):
+- Fetches `registry.json` and component JSON from the deployed registry URL
+- Requires network access
+- `--live` adds an extra explicit ping check on top of the required fetches
+
+**Local mode** (`--registry-root ./public/r`):
+- Loads `registry.json` from `<registry-root>/registry.json` automatically
+- Reads all packaged item JSON from local files
+- No network required
+- Combine with `--registry-json ./registry.json` to use the repo root source registry instead
+
+---
+
+## Publishing
+
+This package is not yet published. When ready:
+
+1. Confirm the package name `@eco-ds/registry-doctor` is available on your npm registry
+2. Update `publishConfig.registry` in `package.json` if using a private registry
+3. Remove the `UNLICENSED` license and add the appropriate license
+4. Run `npm publish` from `packages/registry-doctor/`
+
+The `publishConfig.access` is set to `"restricted"` — change to `"public"` for public npm.
+
+---
+
+## Notes
+
+- **Read-only**: never modifies the target project
+- **No external dependencies**: uses only Node.js built-ins
+- **CommonJS**: compatible with Node.js ≥ 18

package/bin/registry-doctor.js

@@ -0,0 +1,1152 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const path = require("node:path");
+const https = require("node:https");
+const http = require("node:http");
+
+// ---------------------------------------------------------------------------
+// CLI Argument Parsing
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+
+function getArg(name) {
+  const idx = args.indexOf(name);
+  if (idx === -1) return undefined;
+  return args[idx + 1];
+}
+
+function hasFlag(name) {
+  return args.includes(name);
+}
+
+const projectPath = getArg("--project") || process.cwd();
+const componentName = getArg("--component") || "button";
+const registryUrl =
+  getArg("--registry") || "https://eco-design-system-2.dtn.com/r/registry.json";
+const registryRoot = getArg("--registry-root") || null; // e.g. ./public/r
+const registryJsonPath = getArg("--registry-json") || null; // e.g. ./registry.json
+const liveCheck = hasFlag("--live");
+const jsonOutput = hasFlag("--json");
+const helpFlag = hasFlag("--help") || hasFlag("-h");
+
+// Derive base URL from the registry URL (strip /registry.json suffix)
+const REGISTRY_BASE_URL = registryUrl.replace(/\/r\/registry\.json$/, "");
+const REGISTRY_R_BASE = `${REGISTRY_BASE_URL}/r`;
+
+if (helpFlag) {
+  console.log(`
+@eco-ds/registry-doctor — DTN Registry Readiness Checker (EXPERIMENTAL)
+
+Usage:
+  npx @eco-ds/registry-doctor [options]
+  node packages/registry-doctor/bin/registry-doctor.js [options]
+
+Options:
+  --project <path>          Target consuming project (default: cwd)
+  --component <name>        Component to check (default: button)
+  --registry <url>          Registry JSON URL
+                            (default: https://eco-design-system-2.dtn.com/r/registry.json)
+  --registry-root <path>    Local registry output root (e.g. ./public/r)
+                            When provided, loads registry.json from this
+                            directory and skips remote fetch.
+                            Combine with --registry-json to use a different
+                            source registry.json (e.g. the repo root one).
+  --registry-json <path>    Local source registry.json (e.g. ./registry.json)
+                            Skips remote fetch when provided.
+  --live                    Enable extra reachability checks beyond required
+                            metadata fetches (registry URL ping)
+  --json                    Output structured JSON
+  --help, -h                Show this help
+
+Examples:
+  # Product team — fetches metadata from deployed registry
+  npx @eco-ds/registry-doctor --project .
+  npx @eco-ds/registry-doctor --project . --component brand-header --json
+
+  # Maintainer — uses local registry output (no network required)
+  node packages/registry-doctor/bin/registry-doctor.js \\
+    --project . \\
+    --registry-root ./public/r \\
+    --registry-json ./registry.json \\
+    --component button
+`);
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// Result Collection
+// ---------------------------------------------------------------------------
+
+const results = [];
+
+function pass(id, message, details) {
+  results.push({ status: "pass", id, message, details });
+}
+
+function fail(id, message, details) {
+  results.push({ status: "fail", id, message, details });
+}
+
+function warn(id, message, details) {
+  results.push({ status: "warn", id, message, details });
+}
+
+function skip(id, message, details) {
+  results.push({ status: "skip", id, message, details });
+}
+
+// ---------------------------------------------------------------------------
+// HTTP Fetch Helper (no external dependencies)
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch a URL and return the response body as a string.
+ * Uses Node's built-in http/https modules.
+ */
+function fetchUrl(url, timeoutMs = 10000) {
+  return new Promise((resolve, reject) => {
+    const client = url.startsWith("https://") ? https : http;
+    const req = client.get(url, { timeout: timeoutMs }, (res) => {
+      if (res.statusCode !== 200) {
+        res.resume();
+        reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+        return;
+      }
+      const chunks = [];
+      res.on("data", (chunk) => chunks.push(chunk));
+      res.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+      res.on("error", reject);
+    });
+    req.on("error", reject);
+    req.on("timeout", () => {
+      req.destroy();
+      reject(new Error(`Timeout fetching ${url}`));
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Registry Metadata Loading
+// ---------------------------------------------------------------------------
+
+/**
+ * Classify a registry item type to its output subdirectory.
+ */
+function classifyItemType(itemType) {
+  switch (itemType) {
+    case "registry:ui":
+      return "styles";
+    case "registry:component":
+      return "components";
+    case "registry:block":
+      return "blocks";
+    case "registry:theme":
+    case "registry:style":
+      return "themes";
+    default:
+      return "styles";
+  }
+}
+
+/**
+ * Load the source registry index (registry.json).
+ * Priority:
+ *   1. --registry-json <path>  (explicit local file)
+ *   2. --registry-root <path>/registry.json  (implicit local file when root is given)
+ *   3. Remote fetch from --registry URL
+ */
+async function loadRegistryIndex() {
+  if (registryJsonPath) {
+    const resolved = path.resolve(registryJsonPath);
+    if (!fs.existsSync(resolved)) {
+      throw new Error(`--registry-json path not found: ${resolved}`);
+    }
+    return JSON.parse(fs.readFileSync(resolved, "utf8"));
+  }
+  if (registryRoot) {
+    const implicit = path.join(path.resolve(registryRoot), "registry.json");
+    if (fs.existsSync(implicit)) {
+      return JSON.parse(fs.readFileSync(implicit, "utf8"));
+    }
+    // registry-root given but no registry.json inside it — fall through to remote
+  }
+  // Remote fetch
+  const body = await fetchUrl(registryUrl);
+  return JSON.parse(body);
+}
+
+/**
+ * Load a packaged item JSON by name.
+ * Uses local file if --registry-root is provided, otherwise fetches remotely.
+ * Requires the registry index to determine item type.
+ */
+async function loadPackagedItem(name, registryIndex) {
+  const item = registryIndex.items.find((i) => i.name === name);
+  if (!item) return null;
+
+  const subDir = classifyItemType(item.type);
+
+  if (registryRoot) {
+    const resolved = path.resolve(registryRoot);
+    const jsonPath = path.join(resolved, subDir, `${name}.json`);
+    if (!fs.existsSync(jsonPath)) return null;
+    return JSON.parse(fs.readFileSync(jsonPath, "utf8"));
+  }
+
+  // Remote fetch
+  const url = `${REGISTRY_R_BASE}/${subDir}/${name}.json`;
+  try {
+    const body = await fetchUrl(url);
+    return JSON.parse(body);
+  } catch (err) {
+    throw new Error(
+      `Failed to fetch packaged item "${name}" from ${url}: ${err.message}`,
+    );
+  }
+}
+
+/**
+ * Load the packaged theme.json.
+ * Uses local file if --registry-root is provided, otherwise fetches remotely.
+ */
+async function loadTheme() {
+  if (registryRoot) {
+    const resolved = path.resolve(registryRoot);
+    const themePath = path.join(resolved, "themes", "theme.json");
+    if (!fs.existsSync(themePath)) return null;
+    return JSON.parse(fs.readFileSync(themePath, "utf8"));
+  }
+  const url = `${REGISTRY_R_BASE}/themes/theme.json`;
+  try {
+    const body = await fetchUrl(url);
+    return JSON.parse(body);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Derive expected theme tokens from a loaded theme object.
+ */
+function deriveThemeTokens(theme) {
+  if (!theme) {
+    return [
+      "--background",
+      "--foreground",
+      "--primary",
+      "--primary-foreground",
+      "--secondary",
+      "--muted",
+      "--border",
+      "--ring",
+      "--radius",
+    ];
+  }
+  const vars = theme.cssVars || {};
+  const keys = new Set();
+  for (const section of ["theme", "light", "dark"]) {
+    if (vars[section]) {
+      for (const key of Object.keys(vars[section])) {
+        keys.add(`--${key}`);
+      }
+    }
+  }
+  if (theme.files) {
+    for (const file of theme.files) {
+      if (file.content) {
+        const matches = file.content.match(/--[\w-]+/g);
+        if (matches) {
+          for (const m of matches) keys.add(m);
+        }
+      }
+    }
+  }
+  return [...keys];
+}
+
+// ---------------------------------------------------------------------------
+// Project File Helpers
+// ---------------------------------------------------------------------------
+
+function resolveProjectPath(...segments) {
+  return path.resolve(projectPath, ...segments);
+}
+
+function fileExists(...segments) {
+  return fs.existsSync(resolveProjectPath(...segments));
+}
+
+function readProjectFile(...segments) {
+  const p = resolveProjectPath(...segments);
+  if (!fs.existsSync(p)) return null;
+  return fs.readFileSync(p, "utf8");
+}
+
+/**
+ * Resolve a registry file target to a local path using components.json aliases.
+ * Handles both src/ and non-src/ project layouts.
+ */
+function resolveTarget(target, componentsJson) {
+  const aliases = componentsJson?.aliases || {};
+  const hasSrcDir = fs.existsSync(resolveProjectPath("src"));
+
+  if (fileExists(target)) return resolveProjectPath(target);
+  if (hasSrcDir && fileExists("src", target))
+    return resolveProjectPath("src", target);
+
+  for (const [, aliasValue] of Object.entries(aliases)) {
+    const aliasPath = aliasValue.replace(/^@\//, "");
+    if (target.startsWith(`${aliasPath}/`) || target.startsWith(aliasPath)) {
+      if (hasSrcDir) {
+        const resolved = resolveProjectPath("src", target);
+        if (fs.existsSync(resolved)) return resolved;
+      }
+      const resolved = resolveProjectPath(target);
+      if (fs.existsSync(resolved)) return resolved;
+    }
+  }
+
+  const patterns = [
+    target,
+    `src/${target}`,
+    target.replace("components/", "src/components/"),
+  ];
+  for (const p of patterns) {
+    const resolved = resolveProjectPath(p);
+    if (fs.existsSync(resolved)) return resolved;
+  }
+
+  return null;
+}
+
+/**
+ * Extract bare npm package specifiers from file content.
+ * Skips relative imports, @/ aliases, and node: builtins.
+ */
+function extractBareImports(content) {
+  const importRegex =
+    /(?:import|export)\s+(?:[\w\s{},*]+\s+from\s+)?["']([^"']+)["']/g;
+  const requireRegex = /require\s*\(\s*["']([^"']+)["']\s*\)/g;
+  const packages = new Set();
+
+  for (const regex of [importRegex, requireRegex]) {
+    const matches = content.matchAll(regex);
+    for (const match of matches) {
+      const specifier = match[1];
+      if (
+        specifier.startsWith(".") ||
+        specifier.startsWith("@/") ||
+        specifier.startsWith("node:")
+      ) {
+        continue;
+      }
+      if (specifier.startsWith("@")) {
+        const parts = specifier.split("/");
+        if (parts.length >= 2) packages.add(`${parts[0]}/${parts[1]}`);
+      } else {
+        packages.add(specifier.split("/")[0]);
+      }
+    }
+  }
+  return [...packages];
+}
+
+// ---------------------------------------------------------------------------
+// Checks
+// ---------------------------------------------------------------------------
+
+function checkComponentsJson() {
+  const content = readProjectFile("components.json");
+  if (!content) {
+    fail(
+      "components-json",
+      "components.json not found",
+      "Run `npx shadcn@latest init` to create it, or manually create components.json with DTN registry configuration.",
+    );
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(content);
+    pass("components-json", "components.json exists and is valid JSON");
+    return parsed;
+  } catch (e) {
+    fail(
+      "components-json",
+      "components.json exists but is not valid JSON",
+      e.message,
+    );
+    return null;
+  }
+}
+
+function checkRegistryMapping(componentsJson) {
+  if (!componentsJson) {
+    skip("registry-mapping", "Skipped (components.json not available)");
+    return;
+  }
+  const registries = componentsJson.registries;
+  const hasRegistryUrl =
+    JSON.stringify(componentsJson).includes("eco-design-system");
+  if (registries?.["@dtn"]) {
+    pass(
+      "registry-mapping",
+      `@dtn registry mapping found: ${registries["@dtn"].url || registries["@dtn"]}`,
+    );
+  } else if (hasRegistryUrl) {
+    pass(
+      "registry-mapping",
+      "DTN registry URL found in components.json configuration",
+    );
+  } else {
+    warn(
+      "registry-mapping",
+      "No explicit @dtn registry mapping found in components.json",
+      `Components can still be installed with --registry flag: npx shadcn@latest add button --registry ${REGISTRY_BASE_URL}/r/registry.json`,
+    );
+  }
+}
+
+function checkTailwind() {
+  const pkgContent = readProjectFile("package.json");
+  if (!pkgContent) {
+    fail(
+      "tailwind-installed",
+      "package.json not found — cannot verify Tailwind installation",
+    );
+    return;
+  }
+  const pkg = JSON.parse(pkgContent);
+  const allDeps = {
+    ...pkg.dependencies,
+    ...pkg.devDependencies,
+    ...pkg.peerDependencies,
+  };
+  if (!allDeps.tailwindcss) {
+    fail(
+      "tailwind-installed",
+      "tailwindcss not found in dependencies",
+      "Install with: npm install -D tailwindcss @tailwindcss/postcss postcss",
+    );
+    return;
+  }
+  const twVersion = allDeps.tailwindcss;
+  if (
+    twVersion.includes("4") ||
+    twVersion.startsWith("^4") ||
+    twVersion.startsWith("~4")
+  ) {
+    pass("tailwind-installed", `Tailwind CSS v4 found: ${twVersion}`);
+  } else if (twVersion.includes("3") || twVersion.startsWith("^3")) {
+    warn(
+      "tailwind-installed",
+      `Tailwind CSS v3 found (${twVersion}) — DTN registry uses v4 with @theme inline`,
+      "Consider upgrading to Tailwind v4 for full compatibility.",
+    );
+  } else {
+    pass("tailwind-installed", `Tailwind CSS found: ${twVersion}`);
+  }
+}
+
+function checkShadcnSetup(componentsJson) {
+  if (!componentsJson) {
+    skip("shadcn-setup", "Skipped (components.json not available)");
+    return;
+  }
+  if (componentsJson.style) {
+    pass(
+      "shadcn-setup",
+      `shadcn/ui configured with style: "${componentsJson.style}"`,
+    );
+  } else {
+    warn(
+      "shadcn-setup",
+      "No style field in components.json",
+      "DTN registry uses 'new-york' style. Run `npx shadcn@latest init` to configure.",
+    );
+  }
+}
+
+function checkGlobalCss(componentsJson) {
+  const cssPath = componentsJson?.tailwind?.css || componentsJson?.css;
+  const candidates = [
+    cssPath,
+    "src/app/globals.css",
+    "app/globals.css",
+    "src/styles/globals.css",
+    "styles/globals.css",
+    "src/index.css",
+    "index.css",
+  ].filter(Boolean);
+
+  let foundCssPath = null;
+  let cssContent = null;
+  for (const candidate of candidates) {
+    const content = readProjectFile(candidate);
+    if (content !== null) {
+      foundCssPath = candidate;
+      cssContent = content;
+      break;
+    }
+  }
+
+  if (!cssContent) {
+    fail(
+      "global-css",
+      "No global CSS file found",
+      `Checked: ${candidates.join(", ")}. Create a globals.css with Tailwind imports.`,
+    );
+    return { cssContent: null, cssPath: null };
+  }
+
+  const hasTailwindImport =
+    cssContent.includes('@import "tailwindcss"') ||
+    cssContent.includes("@import 'tailwindcss'") ||
+    cssContent.includes("@tailwind base") ||
+    cssContent.includes("@tailwind components") ||
+    cssContent.includes("@tailwind utilities");
+
+  if (hasTailwindImport) {
+    pass(
+      "global-css",
+      `Global CSS found at ${foundCssPath} with Tailwind imports`,
+    );
+  } else {
+    fail(
+      "global-css",
+      `Global CSS found at ${foundCssPath} but missing Tailwind imports`,
+      'Add `@import "tailwindcss";` at the top of your CSS file (Tailwind v4) or @tailwind directives (v3).',
+    );
+  }
+  return { cssContent, cssPath: foundCssPath };
+}
+
+function checkThemeTokens(cssContent, cssPath, expectedTokens) {
+  if (!cssContent) {
+    skip("theme-tokens", "Skipped (no global CSS found)");
+    return;
+  }
+  const missingTokens = expectedTokens.filter((t) => !cssContent.includes(t));
+  const total = expectedTokens.length;
+  const presentCount = total - missingTokens.length;
+
+  if (missingTokens.length === 0) {
+    pass("theme-tokens", `All ${total} DTN theme tokens present in global CSS`);
+  } else if (missingTokens.length <= Math.ceil(total * 0.1)) {
+    const sample = missingTokens.slice(0, 5).join(", ");
+    warn(
+      "theme-tokens",
+      `${missingTokens.length}/${total} theme tokens missing from ${cssPath} (sample: ${sample})`,
+      `Install the DTN theme: npx shadcn@latest add theme --registry ${REGISTRY_BASE_URL}/r/registry.json --overwrite`,
+    );
+  } else {
+    const sample = missingTokens.slice(0, 5).join(", ");
+    fail(
+      "theme-tokens",
+      `${missingTokens.length}/${total} theme tokens missing from ${cssPath} (${presentCount} present, sample missing: ${sample})`,
+      `Install the DTN theme: npx shadcn@latest add theme --registry ${REGISTRY_BASE_URL}/r/registry.json --overwrite`,
+    );
+  }
+}
+
+function checkThemeInline(cssContent, cssPath) {
+  if (!cssContent) {
+    skip("theme-inline", "Skipped (no global CSS found)");
+    return;
+  }
+  if (cssContent.includes("@theme inline") || cssContent.includes("@theme")) {
+    pass(
+      "theme-inline",
+      "@theme directive found in global CSS (Tailwind v4 compatible)",
+    );
+  } else if (cssContent.includes("@tailwind base")) {
+    warn(
+      "theme-inline",
+      "Using Tailwind v3 directives — DTN registry uses @theme inline (Tailwind v4)",
+      "If using Tailwind v4, add `@theme inline { ... }` block with your design tokens.",
+    );
+  } else {
+    warn(
+      "theme-inline",
+      `No @theme inline directive found in ${cssPath}`,
+      "DTN theme uses Tailwind v4's @theme inline for token registration. This may affect utility class generation.",
+    );
+  }
+}
+
+function checkComponentTokens(cssContent) {
+  if (!cssContent) {
+    skip("component-tokens", "Skipped (no global CSS found)");
+    return;
+  }
+  const componentPrefix = `--${componentName}`;
+  if (cssContent.includes(componentPrefix)) {
+    pass(
+      "component-tokens",
+      `Component-specific tokens found for "${componentName}" (${componentPrefix}-*)`,
+    );
+  } else if (componentName === "button") {
+    if (
+      cssContent.includes("--button-primary") ||
+      cssContent.includes("--button-")
+    ) {
+      pass("component-tokens", "Button-specific tokens found (--button-*)");
+    } else {
+      warn(
+        "component-tokens",
+        "No button-specific tokens (--button-*) found in global CSS",
+        "The DTN button uses dedicated CSS variables. Install theme to get them.",
+      );
+    }
+  } else {
+    skip(
+      "component-tokens",
+      `No dedicated tokens for "${componentName}" (not all components require them)`,
+    );
+  }
+}
+
+function checkComponentMatch(componentsJson, packaged) {
+  if (!componentsJson) {
+    skip("component-match", "Skipped (components.json not available)");
+    return;
+  }
+  if (!packaged) {
+    skip(
+      "component-match",
+      `"${componentName}" not found in registry metadata — cannot compare`,
+    );
+    return;
+  }
+
+  // Blocks: verify file targets exist locally (exact comparison is too broad)
+  if (packaged.type === "registry:block") {
+    const mainFiles = (packaged.files || []).filter(
+      (f) => f.target && !f.target.includes("demo"),
+    );
+    const missingTargets = [];
+    for (const file of mainFiles.slice(0, 5)) {
+      if (!resolveTarget(file.target, componentsJson))
+        missingTargets.push(file.target);
+    }
+    if (missingTargets.length === 0) {
+      pass(
+        "component-match",
+        `Block "${componentName}" — checked ${mainFiles.length} file targets, all found locally`,
+      );
+    } else {
+      warn(
+        "component-match",
+        `Block "${componentName}" — ${missingTargets.length} target(s) not found locally: ${missingTargets.slice(0, 3).join(", ")}`,
+        `Install with: npx shadcn@latest add ${componentName} --registry ${REGISTRY_BASE_URL}/r/registry.json --overwrite`,
+      );
+    }
+    return;
+  }
+
+  // ui/component: find main file and compare content
+  const mainFile = (packaged.files || []).find(
+    (f) => f.target && !f.target.includes("demo"),
+  );
+  if (!mainFile) {
+    skip(
+      "component-match",
+      `"${componentName}" has no installable target in registry metadata`,
+    );
+    return;
+  }
+
+  const localFile = resolveTarget(mainFile.target, componentsJson);
+  if (!localFile) {
+    fail(
+      "component-match",
+      `Component "${componentName}" not found locally (expected at ${mainFile.target})`,
+      `Install with: npx shadcn@latest add ${componentName} --registry ${REGISTRY_BASE_URL}/r/registry.json --overwrite`,
+    );
+    return;
+  }
+
+  if (mainFile.content) {
+    const localContent = fs.readFileSync(localFile, "utf8");
+    if (localContent === mainFile.content) {
+      pass(
+        "component-match",
+        `Local "${componentName}" matches registry version exactly`,
+      );
+    } else {
+      warn(
+        "component-match",
+        `Local "${componentName}" differs from packaged DTN registry item (may be customized or outdated)`,
+        `To sync: npx shadcn@latest add ${componentName} --registry ${REGISTRY_BASE_URL}/r/registry.json --overwrite`,
+      );
+    }
+  } else {
+    pass(
+      "component-match",
+      `Component "${componentName}" found locally at ${path.relative(projectPath, localFile)}`,
+    );
+  }
+}
+
+function checkDependencies(packaged, registryIndex) {
+  const pkgContent = readProjectFile("package.json");
+  if (!pkgContent) {
+    skip("dependencies", "Skipped (no package.json)");
+    return;
+  }
+  const pkg = JSON.parse(pkgContent);
+  const projectDeps = {
+    ...pkg.dependencies,
+    ...pkg.devDependencies,
+    ...pkg.peerDependencies,
+  };
+
+  const requiredSet = new Set();
+  if (packaged) {
+    for (const dep of packaged.dependencies || []) requiredSet.add(dep);
+    for (const dep of packaged.devDependencies || []) requiredSet.add(dep);
+    for (const file of packaged.files || []) {
+      if (file.content) {
+        for (const p of extractBareImports(file.content)) requiredSet.add(p);
+      }
+    }
+    // First-level registryDependencies
+    for (const dep of packaged.registryDependencies || []) {
+      const depName = dep.includes("/")
+        ? dep.split("/").pop().replace(".json", "")
+        : dep;
+      const depItem = registryIndex?.items?.find((i) => i.name === depName);
+      if (depItem) {
+        for (const d of depItem.dependencies || []) requiredSet.add(d);
+      }
+    }
+  }
+  requiredSet.add("class-variance-authority");
+  requiredSet.add("tailwind-merge");
+  requiredSet.add("clsx");
+
+  const builtins = new Set(["react", "react-dom", "next"]);
+  const allRequired = [...requiredSet].filter((d) => !builtins.has(d));
+  const missing = allRequired.filter((dep) => !projectDeps[dep]);
+
+  if (missing.length === 0) {
+    pass(
+      "dependencies",
+      `All required dependencies resolved (${allRequired.length} checked)`,
+    );
+  } else {
+    const sample = missing.slice(0, 8).join(", ");
+    const extra = missing.length > 8 ? ` (+${missing.length - 8} more)` : "";
+    warn(
+      "dependencies",
+      `${missing.length} missing dependencies: ${sample}${extra}`,
+      `Install with: npm install ${missing.slice(0, 10).join(" ")}`,
+    );
+  }
+}
+
+function checkFontSetup() {
+  const layoutCandidates = [
+    "src/app/layout.tsx",
+    "src/app/layout.jsx",
+    "app/layout.tsx",
+    "app/layout.jsx",
+    "src/pages/_app.tsx",
+    "src/pages/_app.jsx",
+    "pages/_app.tsx",
+    "pages/_app.jsx",
+  ];
+  let layoutContent = null;
+  let layoutPath = null;
+  for (const candidate of layoutCandidates) {
+    const content = readProjectFile(candidate);
+    if (content !== null) {
+      layoutContent = content;
+      layoutPath = candidate;
+      break;
+    }
+  }
+  if (!layoutContent) {
+    warn(
+      "font-setup",
+      "No layout file found — cannot verify font configuration",
+      `Checked: ${layoutCandidates.slice(0, 4).join(", ")}`,
+    );
+    return;
+  }
+  const hasInter =
+    layoutContent.includes("Inter") || layoutContent.includes("inter");
+  const hasGeist =
+    layoutContent.includes("Geist") || layoutContent.includes("geist");
+  const hasFontSansBinding =
+    layoutContent.includes("--font-sans") ||
+    layoutContent.includes("font-sans");
+
+  if (hasInter && hasFontSansBinding) {
+    pass(
+      "font-setup",
+      `Inter font loaded and bound to --font-sans in ${layoutPath}`,
+    );
+  } else if (hasInter && !hasFontSansBinding) {
+    warn(
+      "font-setup",
+      `Inter font found in ${layoutPath} but --font-sans binding not detected`,
+      "Ensure Inter is bound to the --font-sans CSS variable for DTN theme compatibility.",
+    );
+  } else if (hasGeist && !hasInter) {
+    warn(
+      "font-setup",
+      `${layoutPath} loads Geist font (Next.js default) but DTN theme expects Inter`,
+      "Replace Geist with Inter and bind to --font-sans. Example:\n" +
+        "  import { Inter } from 'next/font/google'\n" +
+        "  const inter = Inter({ subsets: ['latin'], variable: '--font-sans' })",
+    );
+  } else {
+    warn(
+      "font-setup",
+      `Inter font not detected in ${layoutPath}`,
+      "DTN theme expects Inter bound to --font-sans. Add:\n" +
+        "  import { Inter } from 'next/font/google'\n" +
+        "  const inter = Inter({ subsets: ['latin'], variable: '--font-sans' })",
+    );
+  }
+}
+
+function checkAppShellCssImport(cssPath) {
+  if (!cssPath) {
+    skip("app-shell-css", "Skipped (no global CSS path determined)");
+    return;
+  }
+  const layoutCandidates = [
+    "src/app/layout.tsx",
+    "src/app/layout.jsx",
+    "app/layout.tsx",
+    "app/layout.jsx",
+  ];
+  let layoutContent = null;
+  let layoutFilePath = null;
+  for (const candidate of layoutCandidates) {
+    const content = readProjectFile(candidate);
+    if (content !== null) {
+      layoutContent = content;
+      layoutFilePath = candidate;
+      break;
+    }
+  }
+  if (!layoutContent) {
+    skip("app-shell-css", "No app layout found — cannot verify CSS import");
+    return;
+  }
+  const cssFileName = path.basename(cssPath);
+  const hasCssImport =
+    layoutContent.includes(cssFileName) ||
+    layoutContent.includes("globals.css") ||
+    layoutContent.includes("global.css") ||
+    layoutContent.includes("index.css");
+
+  if (hasCssImport) {
+    pass("app-shell-css", `App shell (${layoutFilePath}) imports global CSS`);
+  } else {
+    fail(
+      "app-shell-css",
+      `App shell (${layoutFilePath}) does not appear to import global CSS`,
+      `Add: import "./${cssFileName}" or import "@/app/globals.css" to your root layout.`,
+    );
+  }
+}
+
+async function checkRegistryReachable() {
+  if (!liveCheck) {
+    skip(
+      "registry-reachable",
+      "Skipped (use --live flag to enable extra reachability checks)",
+    );
+    return;
+  }
+  try {
+    await fetchUrl(registryUrl, 10000);
+    pass("registry-reachable", `Registry URL reachable: ${registryUrl}`);
+  } catch (err) {
+    fail(
+      "registry-reachable",
+      `Registry URL unreachable: ${registryUrl}`,
+      `Error: ${err.message}. Check network connectivity.`,
+    );
+  }
+}
+
+function checkComponentCollisions(componentsJson, registryIndex) {
+  if (!componentsJson) {
+    skip("component-collisions", "Skipped (components.json not available)");
+    return;
+  }
+  const hasSrcDir = fs.existsSync(resolveProjectPath("src"));
+  const uiDir = hasSrcDir
+    ? resolveProjectPath("src", "components", "ui")
+    : resolveProjectPath("components", "ui");
+
+  if (!fs.existsSync(uiDir)) {
+    skip("component-collisions", "No components/ui directory found");
+    return;
+  }
+
+  const localComponents = fs
+    .readdirSync(uiDir)
+    .filter((f) => f.endsWith(".tsx") || f.endsWith(".ts"))
+    .map((f) => f.replace(/\.(tsx|ts)$/, ""));
+
+  const registryNames = (registryIndex?.items || [])
+    .filter((item) => item.type === "registry:ui")
+    .map((item) => item.name);
+
+  const potentialCollisions = localComponents.filter((name) =>
+    registryNames.includes(name),
+  );
+  if (potentialCollisions.length === 0) {
+    pass("component-collisions", "No component collisions detected");
+    return;
+  }
+
+  // Without packaged content (remote mode without fetching all items), we can only
+  // report the count of potential collisions, not whether they match.
+  // The collision detail check is best-effort: only runs when registry-root is available.
+  if (!registryRoot) {
+    skip(
+      "component-collisions",
+      `${potentialCollisions.length} local components overlap with registry names — run with --registry-root for content comparison`,
+    );
+    return;
+  }
+
+  const genericComponents = [];
+  for (const name of potentialCollisions) {
+    const subDir = classifyItemType(
+      registryIndex.items.find((i) => i.name === name)?.type ?? "registry:ui",
+    );
+    const jsonPath = path.join(
+      path.resolve(registryRoot),
+      subDir,
+      `${name}.json`,
+    );
+    if (!fs.existsSync(jsonPath)) continue;
+
+    const packaged = JSON.parse(fs.readFileSync(jsonPath, "utf8"));
+    const mainFile = (packaged.files || []).find(
+      (f) => f.target && !f.target.includes("demo") && f.content,
+    );
+    if (!mainFile) continue;
+
+    const targetBasename = path.basename(mainFile.target);
+    const localViaTarget = path.join(uiDir, targetBasename);
+    const localViaName = path.join(uiDir, `${name}.tsx`);
+
+    let localContent = null;
+    if (fs.existsSync(localViaTarget)) {
+      localContent = fs.readFileSync(localViaTarget, "utf8");
+    } else if (fs.existsSync(localViaName)) {
+      localContent = fs.readFileSync(localViaName, "utf8");
+    }
+    if (!localContent) continue;
+    if (localContent === mainFile.content) continue;
+    genericComponents.push(name);
+  }
+
+  if (genericComponents.length > 0) {
+    warn(
+      "component-collisions",
+      `${genericComponents.length} component(s) differ from packaged DTN registry: ${genericComponents.slice(0, 10).join(", ")}`,
+      `Overwrite with DTN versions: npx shadcn@latest add ${genericComponents.slice(0, 5).join(" ")} --registry ${REGISTRY_BASE_URL}/r/registry.json --overwrite`,
+    );
+  } else {
+    pass(
+      "component-collisions",
+      `${potentialCollisions.length} registry components found locally (all match packaged DTN versions)`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const resolvedProject = path.resolve(projectPath);
+  if (!fs.existsSync(resolvedProject)) {
+    console.error(`❌ Project path does not exist: ${resolvedProject}`);
+    process.exit(1);
+  }
+
+  if (!jsonOutput) {
+    console.log("");
+    console.log(
+      "═══════════════════════════════════════════════════════════════",
+    );
+    console.log("  DTN Registry Readiness Checker (EXPERIMENTAL)");
+    console.log(
+      "═══════════════════════════════════════════════════════════════",
+    );
+    console.log(`  Project:   ${resolvedProject}`);
+    console.log(`  Component: ${componentName}`);
+    const metadataSource = registryRoot
+      ? `local (${registryRoot})`
+      : registryUrl;
+    console.log(`  Metadata:  ${metadataSource}`);
+    console.log(
+      `  Live:      ${liveCheck ? "enabled" : "disabled (use --live)"}`,
+    );
+    console.log(
+      "═══════════════════════════════════════════════════════════════\n",
+    );
+  }
+
+  // Load registry metadata (local or remote)
+  let registryIndex = null;
+  let packaged = null;
+  let theme = null;
+
+  try {
+    registryIndex = await loadRegistryIndex();
+  } catch (err) {
+    const source =
+      registryJsonPath ||
+      (registryRoot
+        ? path.join(path.resolve(registryRoot), "registry.json")
+        : registryUrl);
+    if (jsonOutput) {
+      console.log(
+        JSON.stringify(
+          {
+            error: {
+              message: "Failed to load registry index",
+              details: err.message,
+              source,
+            },
+            summary: {
+              total: 0,
+              passed: 0,
+              failed: 1,
+              warnings: 0,
+              skipped: 0,
+            },
+          },
+          null,
+          2,
+        ),
+      );
+    } else {
+      console.error(`❌ Failed to load registry index: ${err.message}`);
+      console.error(`   Source: ${source}`);
+      console.error(
+        "   Check network connectivity or provide --registry-root / --registry-json for local mode.",
+      );
+    }
+    process.exit(1);
+  }
+
+  try {
+    packaged = await loadPackagedItem(componentName, registryIndex);
+  } catch (err) {
+    // Non-fatal: checks that need packaged data will skip
+    if (!jsonOutput) {
+      console.error(
+        `⚠️  Could not load packaged item "${componentName}": ${err.message}`,
+      );
+    }
+  }
+
+  try {
+    theme = await loadTheme();
+  } catch {
+    // Non-fatal: theme token check will use fallback
+  }
+
+  const expectedTokens = deriveThemeTokens(theme);
+
+  // Run all checks
+  const componentsJson = checkComponentsJson();
+  checkRegistryMapping(componentsJson);
+  checkTailwind();
+  checkShadcnSetup(componentsJson);
+  const { cssContent, cssPath } = checkGlobalCss(componentsJson);
+  checkThemeTokens(cssContent, cssPath, expectedTokens);
+  checkThemeInline(cssContent, cssPath);
+  checkComponentTokens(cssContent);
+  checkComponentMatch(componentsJson, packaged);
+  checkDependencies(packaged, registryIndex);
+  checkFontSetup();
+  checkAppShellCssImport(cssPath);
+  await checkRegistryReachable();
+  checkComponentCollisions(componentsJson, registryIndex);
+
+  // Output
+  if (jsonOutput) {
+    const output = {
+      project: resolvedProject,
+      component: componentName,
+      timestamp: new Date().toISOString(),
+      results,
+      summary: {
+        total: results.length,
+        passed: results.filter((r) => r.status === "pass").length,
+        failed: results.filter((r) => r.status === "fail").length,
+        warnings: results.filter((r) => r.status === "warn").length,
+        skipped: results.filter((r) => r.status === "skip").length,
+      },
+    };
+    console.log(JSON.stringify(output, null, 2));
+  } else {
+    const statusIcons = { pass: "✅", fail: "❌", warn: "⚠️ ", skip: "⏭️ " };
+    for (const result of results) {
+      console.log(
+        `${statusIcons[result.status]} [${result.id}] ${result.message}`,
+      );
+      if (
+        result.details &&
+        result.status !== "pass" &&
+        result.status !== "skip"
+      ) {
+        for (const line of result.details.split("\n")) {
+          console.log(`     ${line}`);
+        }
+      }
+    }
+
+    const passed = results.filter((r) => r.status === "pass").length;
+    const failed = results.filter((r) => r.status === "fail").length;
+    const warnings = results.filter((r) => r.status === "warn").length;
+    const skipped = results.filter((r) => r.status === "skip").length;
+
+    console.log("");
+    console.log(
+      "───────────────────────────────────────────────────────────────",
+    );
+    console.log(
+      `  Results: ${passed} passed, ${failed} failed, ${warnings} warnings, ${skipped} skipped`,
+    );
+    console.log(
+      "───────────────────────────────────────────────────────────────",
+    );
+
+    if (failed > 0) {
+      console.log(
+        "\n  ❌ READINESS CHECK FAILED — Fix the issues above before using DTN components.\n",
+      );
+    } else if (warnings > 0) {
+      console.log(
+        "\n  ⚠️  READINESS CHECK PASSED WITH WARNINGS — Components may work but review warnings.\n",
+      );
+    } else {
+      console.log(
+        "\n  ✅ READINESS CHECK PASSED — Project is ready for DTN registry components.\n",
+      );
+    }
+  }
+
+  process.exit(results.some((r) => r.status === "fail") ? 1 : 0);
+}
+
+main().catch((err) => {
+  console.error("Unexpected error:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@eco-ds/registry-doctor",
+  "version": "0.1.0",
+  "description": "DTN Registry Readiness Checker — diagnoses whether a consuming project is correctly set up to use DTN Design System registry components (EXPERIMENTAL / DRAFT)",
+  "keywords": [
+    "dtn",
+    "design-system",
+    "registry",
+    "shadcn",
+    "diagnostics",
+    "experimental"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "eco-ds-registry-doctor": "bin/registry-doctor.js"
+  },
+  "files": [
+    "bin/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org"
+  }
+}