@decantr/cli 1.8.0 → 1.9.0

package/README.md

@@ -61,6 +61,7 @@ Brownfield analysis also writes `.decantr/doctrine-map.json`, a ranked source-pr
 - generates execution-pack context files for AI coding assistants
 - audits projects against Decantr contracts
 - produces local Project Health reports and a localhost Studio dashboard for end-user drift triage
+- audits local registry content repositories with Content Health reports for schema, reference, and quality coverage
 - searches the registry and showcase benchmark corpus
 - validates, refreshes, and maintains `decantr.essence.json`
 
@@ -80,6 +81,7 @@ decantr audit
 decantr check
 decantr health --ci --fail-on error
 decantr studio --port 4319 --host 127.0.0.1
+decantr content-health --ci --fail-on error
 decantr registry summary --namespace @official --json
 decantr showcase verification --json
 ```
@@ -108,6 +110,21 @@ decantr studio --port 4319 --host 127.0.0.1
 
 Studio is for local triage, not Decantr admin telemetry. The tabs cover Overview, Routes, Drift, Findings, Remediation, CI, and Packs without uploading source code, prompts, file paths, or project data.
 
+## Content Health
+
+`decantr content-health` is the local supply-chain observability command for registry content repositories such as `decantr-content`. It is separate from Project Health: Project Health checks an end-user app against its Decantr contract, while Content Health checks published content inputs before they flow into the hosted registry.
+
+```bash
+decantr content-health
+decantr content-health --json
+decantr content-health --markdown --output content-health.md
+decantr content-health --ci --fail-on error
+decantr content-health --ci --fail-on warn
+decantr content-health --prompt <finding-id>
+```
+
+The report validates local `patterns/`, `themes/`, `blueprints/`, `archetypes/`, and `shells/` against the published registry schemas, checks hard references such as blueprint themes and composed archetypes, summarizes softer generation-coverage gaps such as missing pattern coverage, and emits AI-ready remediation prompts. It does not call the hosted registry by default; use the existing registry drift audits when you need live publish parity.
+
 ## Greenfield Certification
 
 Use the built-in certification harness before releases when you want to prove that representative blueprints still scaffold into runnable starter projects:

package/dist/bin.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import "./chunk-Y45MCRGI.js";
+import "./chunk-PKJSI6IH.js";
 import "./chunk-USOO77A5.js";
 import "./chunk-DI2PLOJ6.js";

package/dist/{chunk-Y45MCRGI.js → chunk-PKJSI6IH.js}

@@ -6481,6 +6481,7 @@ ${YELLOW9}You're offline. Scaffolding Decantr default.${RESET13}`);
   console.log("  Commands:");
   console.log(`    ${cyan3("decantr status")}     Project health`);
   console.log(`    ${cyan3("decantr health")}     Contract health report`);
+  console.log(`    ${cyan3("decantr content-health")} Registry content health report`);
   console.log(`    ${cyan3("decantr studio")}     Local health dashboard`);
   console.log(`    ${cyan3("decantr search")}     Search registry`);
   console.log(`    ${cyan3("decantr get")}        Fetch content details`);
@@ -6926,6 +6927,7 @@ ${BOLD6}Usage:${RESET13}
   decantr registry get-pack <manifest|scaffold|review|section|page|mutation> [id] [--namespace <namespace>] [--json] [--essence <path>] [--write-context]
   decantr registry critique-file <file> [--namespace <namespace>] [--json] [--essence <path>] [--treatments <path>]
   decantr registry audit-project [--namespace <namespace>] [--json] [--essence <path>] [--dist <path>] [--sources <dir>]
+  decantr content-health [--json] [--markdown] [--ci]
   decantr rules preview [--project=<path>]
   decantr rules apply [--project=<path>]
   decantr validate [path]
@@ -6964,6 +6966,7 @@ ${BOLD6}Commands:${RESET13}
   ${cyan3("init")}        Attach Decantr contract/context files to an existing project or empty workspace
   ${cyan3("status")}      Show project status, DNA axioms, and blueprint info
   ${cyan3("health")}      Generate a local Project Health report [--json] [--markdown] [--ci]
+  ${cyan3("content-health")} Generate a local registry content health report [--json] [--markdown] [--ci]
   ${cyan3("studio")}      Open a local Project Health dashboard backed by the same report
   ${cyan3("sync")}        Sync registry content from API
   ${cyan3("audit")}       Audit the project or critique a specific file against compiled packs
@@ -7003,6 +7006,7 @@ ${BOLD6}Examples:${RESET13}
   decantr status
   decantr health
   decantr health --ci --fail-on error
+  decantr content-health --ci --fail-on error
   decantr studio
   decantr audit
   decantr audit src/pages/HomePage.tsx
@@ -7192,6 +7196,16 @@ async function main() {
       }
       break;
     }
+    case "content-health": {
+      try {
+        const { cmdContentHealth, parseContentHealthArgs } = await import("./content-health-QQHBR6XG.js");
+        await cmdContentHealth(process.cwd(), parseContentHealthArgs(args));
+      } catch (e) {
+        console.error(error3(e.message));
+        process.exitCode = 1;
+      }
+      break;
+    }
     case "studio": {
       try {
         const { cmdStudio, parseStudioArgs } = await import("./studio-BCTWKXFH.js");

package/dist/content-health-QQHBR6XG.js

@@ -0,0 +1,1057 @@
+// src/commands/content-health.ts
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "fs";
+import { createRequire } from "module";
+import { basename, join } from "path";
+import Ajv2020 from "ajv/dist/2020.js";
+var BOLD = "\x1B[1m";
+var DIM = "\x1B[2m";
+var RESET = "\x1B[0m";
+var RED = "\x1B[31m";
+var GREEN = "\x1B[32m";
+var CYAN = "\x1B[36m";
+var YELLOW = "\x1B[33m";
+var CONTENT_HEALTH_SCHEMA_URL = "https://decantr.ai/schemas/content-health-report.v1.json";
+var DEFAULT_IGNORED_LOCAL_PREFIXES = ["recipefork"];
+var CONTENT_DIRECTORIES = [
+  {
+    type: "pattern",
+    directory: "patterns",
+    schemaSpecifier: "@decantr/registry/schema/pattern.v2.json",
+    expectedSchema: "https://decantr.ai/schemas/pattern.v2.json"
+  },
+  {
+    type: "theme",
+    directory: "themes",
+    schemaSpecifier: "@decantr/registry/schema/theme.v1.json",
+    expectedSchema: "https://decantr.ai/schemas/theme.v1.json"
+  },
+  {
+    type: "blueprint",
+    directory: "blueprints",
+    schemaSpecifier: "@decantr/registry/schema/blueprint.v1.json",
+    expectedSchema: "https://decantr.ai/schemas/blueprint.v1.json"
+  },
+  {
+    type: "archetype",
+    directory: "archetypes",
+    schemaSpecifier: "@decantr/registry/schema/archetype.v2.json",
+    expectedSchema: "https://decantr.ai/schemas/archetype.v2.json"
+  },
+  {
+    type: "shell",
+    directory: "shells",
+    schemaSpecifier: "@decantr/registry/schema/shell.v1.json",
+    expectedSchema: "https://decantr.ai/schemas/shell.v1.json"
+  }
+];
+var TYPE_DIRECTORY = Object.fromEntries(
+  CONTENT_DIRECTORIES.map((entry) => [entry.type, entry.directory])
+);
+var require2 = createRequire(import.meta.url);
+function loadJsonSchema(specifier) {
+  return JSON.parse(readFileSync(require2.resolve(specifier), "utf-8"));
+}
+function createValidators() {
+  const ajv = new Ajv2020({
+    allErrors: true,
+    strict: false,
+    allowUnionTypes: true
+  });
+  ajv.addSchema(loadJsonSchema("@decantr/registry/schema/common.v1.json"));
+  return Object.fromEntries(
+    CONTENT_DIRECTORIES.map((entry) => [
+      entry.type,
+      ajv.compile(loadJsonSchema(entry.schemaSpecifier))
+    ])
+  );
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function toStringArray(value) {
+  return Array.isArray(value) ? value.filter((entry) => isNonEmptyString(entry)) : [];
+}
+function formatSchemaError(error) {
+  const instancePath = error.instancePath || "/";
+  return `${instancePath} ${error.message}`.trim();
+}
+function slugify(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
+}
+function isIgnoredLocalContentFile(fileName) {
+  return DEFAULT_IGNORED_LOCAL_PREFIXES.some((prefix) => fileName.startsWith(prefix));
+}
+function commandsForFinding(source) {
+  switch (source) {
+    case "schema":
+      return ["npm run validate", "decantr content-health"];
+    case "reference":
+      return ["decantr content-health", "npm run validate"];
+    case "quality":
+    case "coverage":
+      return ["decantr content-health --markdown --output content-health.md"];
+    default:
+      return ["decantr content-health"];
+  }
+}
+function buildRemediationPrompt(input) {
+  return [
+    "You are fixing one Decantr Content Health finding in a registry content repository.",
+    "",
+    "Read the referenced JSON content file and the matching Decantr schema before editing. Preserve the item id, published intent, and registry content type unless the finding explicitly says the id or type is wrong.",
+    "",
+    `Finding: ${input.id}`,
+    `Source: ${input.source}`,
+    `Severity: ${input.severity}`,
+    `Category: ${input.category}`,
+    input.type ? `Content type: ${input.type}` : null,
+    input.itemId ? `Item id: ${input.itemId}` : null,
+    input.file ? `File: ${input.file}` : null,
+    `Message: ${input.message}`,
+    input.evidence.length > 0 ? `Evidence:
+${input.evidence.map((entry) => `- ${entry}`).join("\n")}` : null,
+    input.suggestedFix ? `Suggested fix: ${input.suggestedFix}` : null,
+    "",
+    "Make the smallest coherent content change that resolves this finding. Do not add new source-code runtime dependencies for content-only fixes.",
+    "",
+    `After the fix, run:
+${input.commands.map((command) => `- ${command}`).join("\n")}`
+  ].filter((line) => Boolean(line)).join("\n");
+}
+function createContentFinding(input) {
+  const idBase = input.baseId || input.rule || `${input.category}-${input.file ?? ""}-${input.message}`;
+  const id = `${input.source}-${slugify(idBase)}`;
+  const commands = commandsForFinding(input.source);
+  const remediation = {
+    summary: input.suggestedFix || `Resolve ${input.category.toLowerCase()} finding.`,
+    commands,
+    prompt: buildRemediationPrompt({
+      id,
+      source: input.source,
+      category: input.category,
+      severity: input.severity,
+      message: input.message,
+      evidence: input.evidence ?? [],
+      file: input.file,
+      type: input.type,
+      itemId: input.itemId,
+      suggestedFix: input.suggestedFix,
+      commands
+    })
+  };
+  return {
+    id,
+    source: input.source,
+    category: input.category,
+    severity: input.severity,
+    message: input.message,
+    evidence: input.evidence ?? [],
+    file: input.file,
+    type: input.type,
+    itemId: input.itemId,
+    rule: input.rule,
+    suggestedFix: input.suggestedFix,
+    remediation
+  };
+}
+function countFindings(findings) {
+  return {
+    errorCount: findings.filter((finding) => finding.severity === "error").length,
+    warnCount: findings.filter((finding) => finding.severity === "warn").length,
+    infoCount: findings.filter((finding) => finding.severity === "info").length
+  };
+}
+function statusFromCounts(counts) {
+  if (counts.errorCount > 0) return "error";
+  if (counts.warnCount > 0) return "warning";
+  return "healthy";
+}
+function scoreFromCounts(counts) {
+  const warningPenalty = Math.min(counts.warnCount * 2, 75);
+  const infoPenalty = Math.min(counts.infoCount * 0.5, 10);
+  return Math.round(Math.max(0, Math.min(100, 100 - counts.errorCount * 15 - warningPenalty - infoPenalty)));
+}
+function percentage(count, total) {
+  if (total === 0) return 1;
+  return Math.round(count / total * 1e3) / 1e3;
+}
+function patternIdsFromReference(value) {
+  if (isNonEmptyString(value)) return [value];
+  if (!isRecord(value)) return [];
+  if (isNonEmptyString(value.pattern)) return [value.pattern];
+  if (Array.isArray(value.cols)) {
+    return value.cols.flatMap((item) => patternIdsFromReference(item));
+  }
+  return [];
+}
+function collectDependencyReferences(data) {
+  if (!isRecord(data.dependencies)) return [];
+  const map = {
+    patterns: "pattern",
+    themes: "theme",
+    blueprints: "blueprint",
+    archetypes: "archetype",
+    shells: "shell"
+  };
+  const refs = [];
+  for (const [group, values] of Object.entries(data.dependencies)) {
+    const referencedType = map[group];
+    if (!referencedType || !isRecord(values)) continue;
+    for (const id of Object.keys(values)) {
+      refs.push({
+        referencedType,
+        id,
+        rule: `dependency-${referencedType}`,
+        suggestedFix: `Add ${referencedType} "${id}" or remove the stale dependency reference.`
+      });
+    }
+  }
+  return refs;
+}
+function collectBlueprintReferences(item) {
+  const refs = [];
+  const data = item.data;
+  if (isRecord(data.theme) && isNonEmptyString(data.theme.id)) {
+    refs.push({
+      referencedType: "theme",
+      id: data.theme.id,
+      rule: "blueprint-theme",
+      severity: "error",
+      suggestedFix: `Add theme "${data.theme.id}" or choose an existing theme id.`
+    });
+  }
+  if (isNonEmptyString(data.archetype)) {
+    refs.push({
+      referencedType: "archetype",
+      id: data.archetype,
+      rule: "blueprint-archetype",
+      severity: "error",
+      suggestedFix: `Add archetype "${data.archetype}" or update the blueprint archetype field.`
+    });
+  }
+  for (const entry of Array.isArray(data.compose) ? data.compose : []) {
+    const archetype = isNonEmptyString(entry) ? entry : isRecord(entry) && isNonEmptyString(entry.archetype) ? entry.archetype : null;
+    if (archetype) {
+      refs.push({
+        referencedType: "archetype",
+        id: archetype,
+        rule: "blueprint-compose-archetype",
+        severity: "error",
+        suggestedFix: `Add archetype "${archetype}" or remove it from blueprint compose.`
+      });
+    }
+  }
+  for (const theme of toStringArray(data.suggested_themes)) {
+    refs.push({
+      referencedType: "theme",
+      id: theme,
+      rule: "blueprint-suggested-theme",
+      severity: "warn",
+      suggestedFix: `Add suggested theme "${theme}" or remove it from suggested_themes.`
+    });
+  }
+  if (isRecord(data.routes)) {
+    for (const [route, routeConfig] of Object.entries(data.routes)) {
+      if (!isRecord(routeConfig)) continue;
+      if (isNonEmptyString(routeConfig.archetype)) {
+        refs.push({
+          referencedType: "archetype",
+          id: routeConfig.archetype,
+          rule: "blueprint-route-archetype",
+          severity: "error",
+          suggestedFix: `Add archetype "${routeConfig.archetype}" or update route "${route}".`
+        });
+      }
+      if (isNonEmptyString(routeConfig.shell)) {
+        refs.push({
+          referencedType: "shell",
+          id: routeConfig.shell,
+          rule: "blueprint-route-shell",
+          severity: "error",
+          suggestedFix: `Add shell "${routeConfig.shell}" or update route "${route}".`
+        });
+      }
+    }
+  }
+  for (const dependency of collectDependencyReferences(data)) {
+    refs.push({
+      ...dependency,
+      severity: "error"
+    });
+  }
+  return refs;
+}
+function collectArchetypeReferences(item) {
+  const refs = [];
+  const data = item.data;
+  if (Array.isArray(data.pages)) {
+    for (const page of data.pages) {
+      if (!isRecord(page)) continue;
+      if (isNonEmptyString(page.shell) && page.shell !== "inherit") {
+        refs.push({
+          referencedType: "shell",
+          id: page.shell,
+          rule: "archetype-page-shell",
+          severity: "error",
+          suggestedFix: `Add shell "${page.shell}" or update the page shell reference.`
+        });
+      }
+      for (const patternId of Array.isArray(page.default_layout) ? page.default_layout.flatMap((entry) => patternIdsFromReference(entry)) : []) {
+        refs.push({
+          referencedType: "pattern",
+          id: patternId,
+          rule: "archetype-page-layout-pattern",
+          severity: "warn",
+          suggestedFix: `Add pattern "${patternId}" for stronger generation guidance or update the page default_layout reference to an existing pattern.`
+        });
+      }
+      for (const patternId of Array.isArray(page.patterns) ? page.patterns.flatMap((entry) => patternIdsFromReference(entry)) : []) {
+        refs.push({
+          referencedType: "pattern",
+          id: patternId,
+          rule: "archetype-page-pattern",
+          severity: "warn",
+          suggestedFix: `Add pattern "${patternId}" for stronger generation guidance or update the page patterns reference to an existing pattern.`
+        });
+      }
+    }
+  }
+  if (isRecord(data.suggested_theme)) {
+    for (const theme of toStringArray(data.suggested_theme.ids)) {
+      refs.push({
+        referencedType: "theme",
+        id: theme,
+        rule: "archetype-suggested-theme",
+        severity: "warn",
+        suggestedFix: `Add suggested theme "${theme}" or remove it from suggested_theme.ids.`
+      });
+    }
+  }
+  for (const dependency of collectDependencyReferences(data)) {
+    refs.push({
+      ...dependency,
+      severity: "error"
+    });
+  }
+  return refs;
+}
+function collectItemReferences(item) {
+  if (item.type === "blueprint") return collectBlueprintReferences(item);
+  if (item.type === "archetype") return collectArchetypeReferences(item);
+  return collectDependencyReferences(item.data).map((dependency) => ({
+    ...dependency,
+    severity: "error"
+  }));
+}
+function addQualityFindings(item, findings) {
+  const { data, file, type, id } = item;
+  if (type === "pattern") {
+    if (!data.visual_brief && !data.layout_hints) {
+      findings.push(
+        createContentFinding({
+          source: "quality",
+          category: "Pattern Guidance",
+          severity: "warn",
+          message: "Pattern is missing both visual_brief and layout_hints.",
+          evidence: ["AI scaffolds rely on visual guidance to avoid generic layouts."],
+          file,
+          type,
+          itemId: id,
+          rule: "pattern-guidance-missing",
+          suggestedFix: "Add a visual_brief or layout_hints that describes the intended composition.",
+          baseId: `${file}-pattern-guidance-missing`
+        })
+      );
+    }
+    if (!Array.isArray(data.components) || data.components.length === 0) {
+      findings.push(
+        createContentFinding({
+          source: "quality",
+          category: "Pattern Components",
+          severity: "warn",
+          message: "Pattern has no component inventory.",
+          evidence: ["components[] is empty or missing."],
+          file,
+          type,
+          itemId: id,
+          rule: "pattern-components-missing",
+          suggestedFix: "Add a compact components array naming the expected UI building blocks.",
+          baseId: `${file}-pattern-components-missing`
+        })
+      );
+    }
+    if (isRecord(data.presets)) {
+      for (const [presetName, preset] of Object.entries(data.presets)) {
+        if (isRecord(preset) && isNonEmptyString(preset.description) && preset.description.length < 30) {
+          findings.push(
+            createContentFinding({
+              source: "quality",
+              category: "Preset Guidance",
+              severity: "warn",
+              message: `Preset "${presetName}" description is too short to guide generation.`,
+              evidence: [`Description length: ${preset.description.length}`],
+              file,
+              type,
+              itemId: id,
+              rule: "preset-description-short",
+              suggestedFix: "Expand the preset description with layout, density, and usage intent.",
+              baseId: `${file}-${presetName}-preset-description-short`
+            })
+          );
+        }
+      }
+    }
+  }
+  if (type === "theme") {
+    const paletteSize = isRecord(data.palette) ? Object.keys(data.palette).length : 0;
+    if (paletteSize > 0 && paletteSize < 5) {
+      findings.push(
+        createContentFinding({
+          source: "quality",
+          category: "Theme Palette",
+          severity: "warn",
+          message: "Theme palette has fewer than five semantic colors.",
+          evidence: [`Palette entries: ${paletteSize}`],
+          file,
+          type,
+          itemId: id,
+          rule: "theme-palette-shallow",
+          suggestedFix: "Add semantic palette entries for background, surface, text, muted text, and accent roles.",
+          baseId: `${file}-theme-palette-shallow`
+        })
+      );
+    }
+    if (!isRecord(data.decorators) || Object.keys(data.decorators).length === 0) {
+      findings.push(
+        createContentFinding({
+          source: "quality",
+          category: "Theme Decorators",
+          severity: "warn",
+          message: "Theme has no decorator definitions.",
+          evidence: ["decorators is missing or empty."],
+          file,
+          type,
+          itemId: id,
+          rule: "theme-decorators-missing",
+          suggestedFix: "Add theme-specific decorator classes that can be rendered into DECANTR.md and section packs.",
+          baseId: `${file}-theme-decorators-missing`
+        })
+      );
+    } else {
+      for (const [decorator, description] of Object.entries(data.decorators)) {
+        if (typeof description === "string" && description.length < 20) {
+          findings.push(
+            createContentFinding({
+              source: "quality",
+              category: "Theme Decorators",
+              severity: "warn",
+              message: `Decorator "${decorator}" description is too short.`,
+              evidence: [`Description length: ${description.length}`],
+              file,
+              type,
+              itemId: id,
+              rule: "theme-decorator-description-short",
+              suggestedFix: "Describe where and how this decorator should be applied.",
+              baseId: `${file}-${decorator}-theme-decorator-description-short`
+            })
+          );
+        }
+      }
+    }
+  }
+  if (type === "blueprint") {
+    const personality = data.personality;
+    const personalityMissing = personality === void 0 || personality === null || Array.isArray(personality) && personality.length === 0 || typeof personality === "string" && personality.trim().length === 0;
+    if (personalityMissing) {
+      findings.push(
+        createContentFinding({
+          source: "quality",
+          category: "Blueprint Personality",
+          severity: "warn",
+          message: "Blueprint is missing personality guidance.",
+          evidence: ["personality is missing or empty."],
+          file,
+          type,
+          itemId: id,
+          rule: "blueprint-personality-missing",
+          suggestedFix: "Add a concise but specific personality string or trait array.",
+          baseId: `${file}-blueprint-personality-missing`
+        })
+      );
+    } else if (typeof personality === "string" && personality.length < 100) {
+      findings.push(
+        createContentFinding({
+          source: "quality",
+          category: "Blueprint Personality",
+          severity: "warn",
+          message: "Blueprint personality is shorter than 100 characters.",
+          evidence: [`Length: ${personality.length}`],
+          file,
+          type,
+          itemId: id,
+          rule: "blueprint-personality-short",
+          suggestedFix: "Expand personality with visual direction, tone, density, and interaction posture.",
+          baseId: `${file}-blueprint-personality-short`
+        })
+      );
+    }
+    if (!isRecord(data.voice)) {
+      findings.push(
+        createContentFinding({
+          source: "coverage",
+          category: "Blueprint Voice",
+          severity: "info",
+          message: "Blueprint has no voice guidance.",
+          evidence: ["voice is missing."],
+          file,
+          type,
+          itemId: id,
+          rule: "blueprint-voice-missing",
+          suggestedFix: "Add voice.tone, cta_verbs, avoid words, and state copy guidance when this blueprint needs product copy consistency.",
+          baseId: `${file}-blueprint-voice-missing`
+        })
+      );
+    }
+  }
+  if (type === "archetype" && !isRecord(data.page_briefs)) {
+    findings.push(
+      createContentFinding({
+        source: "coverage",
+        category: "Archetype Page Briefs",
+        severity: "info",
+        message: "Archetype has no page_briefs.",
+        evidence: ["page_briefs is missing."],
+        file,
+        type,
+        itemId: id,
+        rule: "archetype-page-briefs-missing",
+        suggestedFix: "Add page_briefs when route-level visual direction should be more specific than page names.",
+        baseId: `${file}-archetype-page-briefs-missing`
+      })
+    );
+  }
+}
+function typeSummary(config, items, findings, invalidFiles, ignoredCount) {
+  const typeFindings = findings.filter((finding) => finding.type === config.type);
+  return {
+    type: config.type,
+    directory: config.directory,
+    itemCount: items.length,
+    validCount: items.filter((item) => !invalidFiles.has(item.file)).length,
+    ...countFindings(typeFindings),
+    ignoredCount
+  };
+}
+function missingByTypeInitial() {
+  return {
+    pattern: 0,
+    theme: 0,
+    blueprint: 0,
+    archetype: 0,
+    shell: 0
+  };
+}
+async function createContentHealthReport(contentRoot = process.cwd(), options = {}) {
+  const validators = createValidators();
+  const findings = [];
+  const invalidFiles = /* @__PURE__ */ new Set();
+  const allItems = [];
+  const itemsByType = /* @__PURE__ */ new Map();
+  const ignoredCounts = /* @__PURE__ */ new Map();
+  let contentDirectoryCount = 0;
+  for (const config of CONTENT_DIRECTORIES) {
+    const directoryPath = join(contentRoot, config.directory);
+    const typeItems = /* @__PURE__ */ new Map();
+    itemsByType.set(config.type, typeItems);
+    ignoredCounts.set(config.type, 0);
+    if (!existsSync(directoryPath)) {
+      findings.push(
+        createContentFinding({
+          source: "content",
+          category: "Content Directory",
+          severity: "warn",
+          message: `Missing ${config.directory}/ directory.`,
+          evidence: [`Expected ${config.directory}/ under the content root.`],
+          type: config.type,
+          rule: "content-directory-missing",
+          suggestedFix: `Create ${config.directory}/ when this repository is expected to publish ${config.type} content.`,
+          baseId: `${config.directory}-content-directory-missing`
+        })
+      );
+      continue;
+    }
+    contentDirectoryCount += 1;
+    const files = readdirSync(directoryPath).filter((file) => file.endsWith(".json")).sort();
+    for (const fileName of files) {
+      if (!options.includeIgnored && isIgnoredLocalContentFile(fileName)) {
+        ignoredCounts.set(config.type, (ignoredCounts.get(config.type) ?? 0) + 1);
+        continue;
+      }
+      const relativeFile = `${config.directory}/${fileName}`;
+      const expectedId = basename(fileName, ".json");
+      let data;
+      try {
+        data = JSON.parse(readFileSync(join(contentRoot, relativeFile), "utf-8"));
+      } catch (e) {
+        invalidFiles.add(relativeFile);
+        findings.push(
+          createContentFinding({
+            source: "schema",
+            category: "JSON Parse",
+            severity: "error",
+            message: `Invalid JSON: ${e.message}`,
+            evidence: [`File: ${relativeFile}`],
+            file: relativeFile,
+            type: config.type,
+            itemId: expectedId,
+            rule: "json-invalid",
+            suggestedFix: "Repair the JSON syntax.",
+            baseId: `${relativeFile}-json-invalid`
+          })
+        );
+        continue;
+      }
+      if (!isRecord(data)) {
+        invalidFiles.add(relativeFile);
+        findings.push(
+          createContentFinding({
+            source: "schema",
+            category: "Content Shape",
+            severity: "error",
+            message: "Content item must be a JSON object.",
+            evidence: [`File: ${relativeFile}`],
+            file: relativeFile,
+            type: config.type,
+            itemId: expectedId,
+            rule: "content-object-required",
+            suggestedFix: "Replace the file with a JSON object matching the content schema.",
+            baseId: `${relativeFile}-content-object-required`
+          })
+        );
+        continue;
+      }
+      const id = isNonEmptyString(data.id) ? data.id : isNonEmptyString(data.slug) ? data.slug : expectedId;
+      const item = {
+        type: config.type,
+        directory: config.directory,
+        file: relativeFile,
+        id,
+        data
+      };
+      allItems.push(item);
+      if (typeItems.has(id)) {
+        invalidFiles.add(relativeFile);
+        findings.push(
+          createContentFinding({
+            source: "schema",
+            category: "Duplicate Content ID",
+            severity: "error",
+            message: `${config.type} id "${id}" is declared more than once.`,
+            evidence: [`Duplicate file: ${relativeFile}`],
+            file: relativeFile,
+            type: config.type,
+            itemId: id,
+            rule: "content-id-duplicate",
+            suggestedFix: "Make ids unique within each content type.",
+            baseId: `${relativeFile}-content-id-duplicate`
+          })
+        );
+      } else {
+        typeItems.set(id, item);
+      }
+      if (data.$schema !== config.expectedSchema) {
+        invalidFiles.add(relativeFile);
+        findings.push(
+          createContentFinding({
+            source: "schema",
+            category: "Schema URL",
+            severity: "error",
+            message: `$schema must be "${config.expectedSchema}".`,
+            evidence: [`Found: ${typeof data.$schema === "string" ? data.$schema : "missing"}`],
+            file: relativeFile,
+            type: config.type,
+            itemId: id,
+            rule: "schema-url-mismatch",
+            suggestedFix: `Set $schema to ${config.expectedSchema}.`,
+            baseId: `${relativeFile}-schema-url-mismatch`
+          })
+        );
+      }
+      if (id !== expectedId) {
+        invalidFiles.add(relativeFile);
+        findings.push(
+          createContentFinding({
+            source: "schema",
+            category: "Content ID",
+            severity: "error",
+            message: `id must match filename (${expectedId}).`,
+            evidence: [`Found id: ${id}`],
+            file: relativeFile,
+            type: config.type,
+            itemId: id,
+            rule: "content-id-filename-mismatch",
+            suggestedFix: `Rename the file or set id to "${expectedId}".`,
+            baseId: `${relativeFile}-content-id-filename-mismatch`
+          })
+        );
+      }
+      const validate = validators[config.type];
+      if (!validate(data)) {
+        invalidFiles.add(relativeFile);
+        for (const schemaError of (validate.errors || []).slice(0, 6)) {
+          findings.push(
+            createContentFinding({
+              source: "schema",
+              category: "Schema Validation",
+              severity: "error",
+              message: `Schema validation failed: ${formatSchemaError(schemaError)}`,
+              evidence: [`File: ${relativeFile}`],
+              file: relativeFile,
+              type: config.type,
+              itemId: id,
+              rule: "schema-validation-failed",
+              suggestedFix: "Update the content item to match the published schema.",
+              baseId: `${relativeFile}-${formatSchemaError(schemaError)}`
+            })
+          );
+        }
+      }
+    }
+  }
+  if (contentDirectoryCount === 0 || allItems.length === 0) {
+    findings.push(
+      createContentFinding({
+        source: "content",
+        category: "Content Root",
+        severity: "error",
+        message: "No Decantr registry content was found in this directory.",
+        evidence: ["Expected one or more of patterns/, themes/, blueprints/, archetypes/, shells/."],
+        rule: "content-root-empty",
+        suggestedFix: "Run this command from a decantr-content style repository.",
+        baseId: "content-root-empty"
+      })
+    );
+  }
+  let referencesChecked = 0;
+  const missingByType = missingByTypeInitial();
+  const missingReferenceGroups = /* @__PURE__ */ new Map();
+  for (const item of allItems) {
+    for (const reference of collectItemReferences(item)) {
+      referencesChecked += 1;
+      const referenced = itemsByType.get(reference.referencedType)?.has(reference.id);
+      if (referenced) continue;
+      missingByType[reference.referencedType] += 1;
+      const key = `${item.file}|${reference.rule}|${reference.severity}|${reference.referencedType}`;
+      const group = missingReferenceGroups.get(key);
+      if (group) {
+        group.ids.push(reference.id);
+      } else {
+        missingReferenceGroups.set(key, {
+          item,
+          referencedType: reference.referencedType,
+          rule: reference.rule,
+          severity: reference.severity,
+          ids: [reference.id],
+          suggestedFix: reference.suggestedFix
+        });
+      }
+    }
+  }
+  for (const group of missingReferenceGroups.values()) {
+    const missingList = [...new Set(group.ids)].sort();
+    const preview = missingList.slice(0, 12);
+    findings.push(
+      createContentFinding({
+        source: "reference",
+        category: "Missing Reference",
+        severity: group.severity,
+        message: missingList.length === 1 ? `${group.item.type} "${group.item.id}" references missing ${group.referencedType} "${missingList[0]}".` : `${group.item.type} "${group.item.id}" references ${missingList.length} missing ${group.referencedType} items.`,
+        evidence: [
+          `Reference directory: ${TYPE_DIRECTORY[group.referencedType]}/`,
+          `Rule: ${group.rule}`,
+          `Missing ${group.referencedType}: ${preview.join(", ")}${missingList.length > preview.length ? `, and ${missingList.length - preview.length} more` : ""}`
+        ],
+        file: group.item.file,
+        type: group.item.type,
+        itemId: group.item.id,
+        rule: group.rule,
+        suggestedFix: missingList.length === 1 ? group.suggestedFix : `Add the missing ${group.referencedType} items or update stale ${group.rule} references.`,
+        baseId: `${group.item.file}-${group.rule}-${group.referencedType}-missing`
+      })
+    );
+  }
+  for (const item of allItems) {
+    addQualityFindings(item, findings);
+  }
+  const byType = CONTENT_DIRECTORIES.map(
+    (config) => typeSummary(
+      config,
+      allItems.filter((item) => item.type === config.type),
+      findings,
+      invalidFiles,
+      ignoredCounts.get(config.type) ?? 0
+    )
+  );
+  const counts = countFindings(findings);
+  const validCount = allItems.filter((item) => !invalidFiles.has(item.file)).length;
+  const ignoredCount = [...ignoredCounts.values()].reduce((sum, count) => sum + count, 0);
+  const patterns = allItems.filter((item) => item.type === "pattern");
+  const themes = allItems.filter((item) => item.type === "theme");
+  const blueprints = allItems.filter((item) => item.type === "blueprint");
+  const archetypes = allItems.filter((item) => item.type === "archetype");
+  return {
+    $schema: CONTENT_HEALTH_SCHEMA_URL,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    contentRoot,
+    status: statusFromCounts(counts),
+    score: scoreFromCounts(counts),
+    summary: {
+      itemCount: allItems.length,
+      validCount,
+      ...counts,
+      findingCount: findings.length,
+      ignoredCount,
+      contentDirectoryCount
+    },
+    content: byType,
+    references: {
+      checked: referencesChecked,
+      missing: Object.values(missingByType).reduce((sum, count) => sum + count, 0),
+      missingByType
+    },
+    quality: {
+      patternVisualBriefCoverage: percentage(
+        patterns.filter((item) => item.data.visual_brief || item.data.layout_hints).length,
+        patterns.length
+      ),
+      patternInteractionCoverage: percentage(
+        patterns.filter((item) => Array.isArray(item.data.interactions) && item.data.interactions.length > 0).length,
+        patterns.length
+      ),
+      themeDecoratorCoverage: percentage(
+        themes.filter((item) => isRecord(item.data.decorators) && Object.keys(item.data.decorators).length > 0).length,
+        themes.length
+      ),
+      blueprintPersonalityCoverage: percentage(
+        blueprints.filter((item) => {
+          const personality = item.data.personality;
+          return isNonEmptyString(personality) || Array.isArray(personality) && personality.some((entry) => isNonEmptyString(entry));
+        }).length,
+        blueprints.length
+      ),
+      blueprintVoiceCoverage: percentage(blueprints.filter((item) => isRecord(item.data.voice)).length, blueprints.length),
+      archetypePageBriefCoverage: percentage(
+        archetypes.filter((item) => isRecord(item.data.page_briefs)).length,
+        archetypes.length
+      )
+    },
+    ci: {
+      recommendedCommand: "decantr content-health --ci --fail-on error",
+      failOn: "error"
+    },
+    findings
+  };
+}
+function colorForStatus(status) {
+  if (status === "healthy") return GREEN;
+  if (status === "warning") return YELLOW;
+  return RED;
+}
+function percentLabel(value) {
+  return `${Math.round(value * 100)}%`;
+}
+function formatContentHealthText(report) {
+  const color = colorForStatus(report.status);
+  const lines = [
+    `${BOLD}Decantr Content Health${RESET}`,
+    "",
+    `${color}${report.status.toUpperCase()}${RESET}  score ${report.score}/100`,
+    `${DIM}${report.contentRoot}${RESET}`,
+    "",
+    `${BOLD}Summary:${RESET}`,
+    `  Items: ${report.summary.itemCount} total, ${report.summary.validCount} valid, ${report.summary.ignoredCount} ignored`,
+    `  Findings: ${report.summary.errorCount} error(s), ${report.summary.warnCount} warn(s), ${report.summary.infoCount} info`,
+    `  References: ${report.references.checked} checked, ${report.references.missing} missing`,
+    `  Quality: pattern guidance ${percentLabel(report.quality.patternVisualBriefCoverage)} | theme decorators ${percentLabel(report.quality.themeDecoratorCoverage)} | blueprint voice ${percentLabel(report.quality.blueprintVoiceCoverage)}`,
+    "",
+    `${BOLD}Content:${RESET}`
+  ];
+  for (const entry of report.content) {
+    lines.push(
+      `  ${entry.directory.padEnd(10)} ${entry.itemCount} item(s), ${entry.validCount} valid, ${entry.errorCount} error(s), ${entry.warnCount} warn(s), ${entry.ignoredCount} ignored`
+    );
+  }
+  lines.push("");
+  lines.push(`${BOLD}Findings:${RESET}`);
+  if (report.findings.length === 0) {
+    lines.push(`  ${GREEN}No findings. Content supply chain is healthy.${RESET}`);
+  } else {
+    for (const finding of report.findings.slice(0, 40)) {
+      const findingColor = finding.severity === "error" ? RED : finding.severity === "warn" ? YELLOW : CYAN;
+      lines.push(
+        `  ${findingColor}[${finding.severity.toUpperCase()}]${RESET} ${finding.id}: ${finding.message}`
+      );
+      if (finding.file) lines.push(`    ${DIM}${finding.file}${RESET}`);
+      if (finding.suggestedFix) lines.push(`    ${DIM}Fix: ${finding.suggestedFix}${RESET}`);
+      lines.push(`    ${DIM}Prompt: decantr content-health --prompt ${finding.id}${RESET}`);
+    }
+    if (report.findings.length > 40) {
+      lines.push(`  ${DIM}Showing first 40 of ${report.findings.length} findings. Use --json for the full report.${RESET}`);
+    }
+  }
+  lines.push("");
+  lines.push(`${BOLD}CI:${RESET} ${report.ci.recommendedCommand}`);
+  return `${lines.join("\n")}
+`;
+}
+function formatContentHealthMarkdown(report) {
+  const lines = [
+    "# Decantr Content Health",
+    "",
+    `- Status: **${report.status}**`,
+    `- Score: **${report.score}/100**`,
+    `- Content root: \`${report.contentRoot}\``,
+    `- Items: ${report.summary.itemCount} total, ${report.summary.validCount} valid, ${report.summary.ignoredCount} ignored`,
+    `- Findings: ${report.summary.errorCount} error(s), ${report.summary.warnCount} warn(s), ${report.summary.infoCount} info`,
+    `- References: ${report.references.checked} checked, ${report.references.missing} missing`,
+    "",
+    "## Content",
+    "",
+    "| Type | Items | Valid | Errors | Warnings | Info | Ignored |",
+    "| --- | ---: | ---: | ---: | ---: | ---: | ---: |"
+  ];
+  for (const entry of report.content) {
+    lines.push(
+      `| ${entry.type} | ${entry.itemCount} | ${entry.validCount} | ${entry.errorCount} | ${entry.warnCount} | ${entry.infoCount} | ${entry.ignoredCount} |`
+    );
+  }
+  lines.push("");
+  lines.push("## Quality Coverage");
+  lines.push("");
+  lines.push(`- Pattern visual guidance: ${percentLabel(report.quality.patternVisualBriefCoverage)}`);
+  lines.push(`- Pattern interactions: ${percentLabel(report.quality.patternInteractionCoverage)}`);
+  lines.push(`- Theme decorators: ${percentLabel(report.quality.themeDecoratorCoverage)}`);
+  lines.push(`- Blueprint personality: ${percentLabel(report.quality.blueprintPersonalityCoverage)}`);
+  lines.push(`- Blueprint voice: ${percentLabel(report.quality.blueprintVoiceCoverage)}`);
+  lines.push(`- Archetype page briefs: ${percentLabel(report.quality.archetypePageBriefCoverage)}`);
+  lines.push("");
+  lines.push("## Findings");
+  lines.push("");
+  if (report.findings.length === 0) {
+    lines.push("No findings. Content supply chain is healthy.");
+  } else {
+    for (const finding of report.findings) {
+      lines.push(`### ${finding.id}`);
+      lines.push("");
+      lines.push(`- Severity: ${finding.severity}`);
+      lines.push(`- Source: ${finding.source}`);
+      lines.push(`- Category: ${finding.category}`);
+      if (finding.file) lines.push(`- File: \`${finding.file}\``);
+      if (finding.type) lines.push(`- Type: ${finding.type}`);
+      if (finding.itemId) lines.push(`- Item: \`${finding.itemId}\``);
+      lines.push(`- Message: ${finding.message}`);
+      if (finding.suggestedFix) lines.push(`- Fix: ${finding.suggestedFix}`);
+      if (finding.evidence.length > 0) {
+        lines.push("- Evidence:");
+        for (const evidence of finding.evidence) lines.push(`  - ${evidence}`);
+      }
+      lines.push(`- Prompt: \`decantr content-health --prompt ${finding.id}\``);
+      lines.push("");
+    }
+  }
+  lines.push("## CI");
+  lines.push("");
+  lines.push(`\`${report.ci.recommendedCommand}\``);
+  return `${lines.join("\n")}
+`;
+}
+function formatContentHealthJson(report) {
+  return `${JSON.stringify(report, null, 2)}
+`;
+}
+function resolveFormat(options) {
+  if (options.json) return "json";
+  if (options.markdown) return "markdown";
+  return options.format ?? "text";
+}
+function shouldFailContentHealth(report, failOn) {
+  if (failOn === "none") return false;
+  if (failOn === "warn") return report.summary.errorCount > 0 || report.summary.warnCount > 0;
+  return report.summary.errorCount > 0;
+}
+async function cmdContentHealth(contentRoot = process.cwd(), options = {}) {
+  const report = await createContentHealthReport(contentRoot, options);
+  if (options.promptId) {
+    const finding = report.findings.find((entry) => entry.id === options.promptId);
+    if (!finding) {
+      console.error(`${RED}No content health finding found for id: ${options.promptId}${RESET}`);
+      process.exitCode = 1;
+      return;
+    }
+    console.log(finding.remediation.prompt);
+    return;
+  }
+  const format = resolveFormat(options);
+  const payload = format === "json" ? formatContentHealthJson(report) : format === "markdown" ? formatContentHealthMarkdown(report) : formatContentHealthText(report);
+  if (options.output) {
+    writeFileSync(options.output, payload, "utf-8");
+    if (!options.ci) {
+      console.log(`${GREEN}Wrote Decantr content health report:${RESET} ${options.output}`);
+    }
+  } else {
+    process.stdout.write(payload);
+  }
+  if (options.ci && shouldFailContentHealth(report, options.failOn ?? "error")) {
+    process.exitCode = 1;
+  }
+}
+function parseContentHealthArgs(args) {
+  const options = {};
+  for (let index = 1; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--json") {
+      options.json = true;
+    } else if (arg === "--markdown") {
+      options.markdown = true;
+    } else if (arg === "--ci") {
+      options.ci = true;
+    } else if (arg === "--include-ignored") {
+      options.includeIgnored = true;
+    } else if (arg === "--format" && args[index + 1]) {
+      options.format = args[++index];
+    } else if (arg.startsWith("--format=")) {
+      options.format = arg.split("=")[1];
+    } else if (arg === "--output" && args[index + 1]) {
+      options.output = args[++index];
+    } else if (arg.startsWith("--output=")) {
+      options.output = arg.split("=")[1];
+    } else if (arg === "--fail-on" && args[index + 1]) {
+      options.failOn = args[++index];
+    } else if (arg.startsWith("--fail-on=")) {
+      options.failOn = arg.split("=")[1];
+    } else if (arg === "--prompt" && args[index + 1]) {
+      options.promptId = args[++index];
+    } else if (arg.startsWith("--prompt=")) {
+      options.promptId = arg.split("=")[1];
+    }
+  }
+  if (options.format && !["text", "json", "markdown"].includes(options.format)) {
+    throw new Error("Invalid --format value. Use text, json, or markdown.");
+  }
+  if (options.failOn && !["error", "warn", "none"].includes(options.failOn)) {
+    throw new Error("Invalid --fail-on value. Use error, warn, or none.");
+  }
+  return options;
+}
+export {
+  cmdContentHealth,
+  createContentHealthReport,
+  formatContentHealthJson,
+  formatContentHealthMarkdown,
+  formatContentHealthText,
+  parseContentHealthArgs,
+  shouldFailContentHealth
+};

package/dist/index.js

@@ -1,3 +1,3 @@
-import "./chunk-Y45MCRGI.js";
+import "./chunk-PKJSI6IH.js";
 import "./chunk-USOO77A5.js";
 import "./chunk-DI2PLOJ6.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decantr/cli",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Decantr CLI - scaffold, audit, inspect Project Health, and maintain Decantr projects from the terminal",
   "author": "Decantr AI",
   "license": "MIT",
@@ -30,10 +30,11 @@
     "access": "public"
   },
   "dependencies": {
+    "ajv": "^8.18.0",
     "@decantr/core": "1.0.6",
     "@decantr/essence-spec": "1.0.7",
+    "@decantr/registry": "1.1.0",
     "@decantr/verifier": "1.1.0",
-    "@decantr/registry": "1.0.4",
     "@decantr/telemetry": "0.1.2"
   },
   "scripts": {