@decantr/cli 1.8.0 → 1.10.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
 ```
@@ -95,10 +97,14 @@ decantr health --markdown --output health.md
 decantr health --ci --fail-on error
 decantr health --ci --fail-on warn
 decantr health --prompt <finding-id>
+decantr health init-ci
+decantr health init-ci --fail-on warn --cli-version latest --force
 ```
 
 Use `--json` for machines and schema validation, `--markdown` for CI summaries, and `--prompt <finding-id>` when you want a scoped remediation prompt for an AI assistant. `--ci --fail-on error` fails only when blocking errors exist; `--ci --fail-on warn` also fails on warnings.
 
+`decantr health init-ci` installs `.github/workflows/decantr-health.yml` for GitHub Actions. The generated workflow installs project dependencies, writes `decantr-health.json`, gates with `decantr health --ci --fail-on error --markdown --output decantr-health.md`, appends the markdown report to the GitHub step summary, and uploads both files as artifacts. Use `--force` to replace an existing workflow, `--fail-on warn` for stricter repositories, or `--cli-version <version|latest>` to pin the package used by CI.
+
 `decantr studio` starts a local-only dashboard powered by the same report. It uses Node built-ins only and serves `GET /`, `GET /api/health`, and `POST /api/refresh`.
 
 ```bash
@@ -108,6 +114,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:
@@ -182,7 +203,7 @@ Recommended read order for AI-assisted scaffolding:
 
 Treat the compiled execution packs as the source of truth. Use the narrative docs as secondary explanation, start with the shell and route structure first, and run `decantr check` plus `decantr audit` after implementation.
 
-For a broader health pass, run `decantr health` after `refresh`, before opening a pull request, or inside CI. Findings include remediation commands and can be turned into focused AI prompts with `decantr health --prompt <finding-id>`.
+For a broader health pass, run `decantr health` after `refresh`, before opening a pull request, or inside CI. Install the default GitHub Actions gate with `decantr health init-ci`. Findings include remediation commands and can be turned into focused AI prompts with `decantr health --prompt <finding-id>`.
 
 For cold-start harness or certification runs, use only the scaffolded workspace files as the contract. If local scaffold files disagree, stop and report the mismatch rather than relying on repo-global Decantr assumptions.
 

package/dist/bin.js

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

package/dist/{chunk-Y45MCRGI.js → chunk-FLZVSNB5.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,8 @@ ${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 health init-ci [--force] [--fail-on <error|warn|none>] [--cli-version <version|latest>]
+  decantr content-health [--json] [--markdown] [--ci]
   decantr rules preview [--project=<path>]
   decantr rules apply [--project=<path>]
   decantr validate [path]
@@ -6963,7 +6966,8 @@ ${BOLD6}Commands:${RESET13}
   ${cyan3("magic")}       Greenfield-first intent flow; steers existing apps into analyze + init
   ${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("health")}      Generate a local Project Health report [--json] [--markdown] [--ci]; use health init-ci to install a GitHub Actions gate
+  ${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
@@ -7002,7 +7006,9 @@ ${BOLD6}Examples:${RESET13}
   decantr rules apply
   decantr status
   decantr health
+  decantr health init-ci
   decantr health --ci --fail-on error
+  decantr content-health --ci --fail-on error
   decantr studio
   decantr audit
   decantr audit src/pages/HomePage.tsx
@@ -7184,7 +7190,7 @@ async function main() {
     }
     case "health": {
       try {
-        const { cmdHealth, parseHealthArgs } = await import("./health-VSL4MROO.js");
+        const { cmdHealth, parseHealthArgs } = await import("./health-SIKAOE2Z.js");
         await cmdHealth(process.cwd(), parseHealthArgs(args));
       } catch (e) {
         console.error(error3(e.message));
@@ -7192,9 +7198,19 @@ 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");
+        const { cmdStudio, parseStudioArgs } = await import("./studio-EQSSNA6D.js");
         await cmdStudio(process.cwd(), parseStudioArgs(args));
       } catch (e) {
         console.error(error3(e.message));

package/dist/{chunk-DONMNPS7.js → chunk-K5KCZSEI.js}

@@ -3,8 +3,9 @@ import {
 } from "./chunk-RSDCWAHD.js";
 
 // src/commands/health.ts
-import { existsSync, readFileSync, writeFileSync } from "fs";
-import { join } from "path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
 import {
   auditProject
 } from "@decantr/verifier";
@@ -16,6 +17,11 @@ var GREEN = "\x1B[32m";
 var CYAN = "\x1B[36m";
 var YELLOW = "\x1B[33m";
 var PROJECT_HEALTH_SCHEMA_URL = "https://decantr.ai/schemas/project-health-report.v1.json";
+var DEFAULT_HEALTH_CI_WORKFLOW_PATH = ".github/workflows/decantr-health.yml";
+var DEFAULT_HEALTH_CI_REPORT_PATH = "decantr-health.md";
+var DEFAULT_HEALTH_CI_JSON_PATH = "decantr-health.json";
+var DEFAULT_HEALTH_CI_CLI_VERSION = "latest";
+var __dirname = dirname(fileURLToPath(import.meta.url));
 function readProjectMetadata(projectRoot) {
   const projectJsonPath = join(projectRoot, ".decantr", "project.json");
   if (!existsSync(projectJsonPath)) {
@@ -34,6 +40,91 @@ function readProjectMetadata(projectRoot) {
     return { workflowMode: null, adoptionMode: null, autoBrownfield: false };
   }
 }
+function loadHealthTemplate(name) {
+  const fromDist = join(__dirname, "..", "src", "templates", name);
+  if (existsSync(fromDist)) return readFileSync(fromDist, "utf-8");
+  const fromSrc = join(__dirname, "..", "templates", name);
+  if (existsSync(fromSrc)) return readFileSync(fromSrc, "utf-8");
+  const fromCommandSrc = join(__dirname, "..", "..", "templates", name);
+  if (existsSync(fromCommandSrc)) return readFileSync(fromCommandSrc, "utf-8");
+  throw new Error(`Template not found: ${name}`);
+}
+function renderTemplate(template, vars) {
+  let result = template;
+  for (const [key, value] of Object.entries(vars)) {
+    result = result.replace(new RegExp(`\\{\\{${key}\\}\\}`, "g"), value);
+  }
+  return result;
+}
+function normalizeCliPackageSpecifier(version) {
+  const value = (version || DEFAULT_HEALTH_CI_CLI_VERSION).trim();
+  if (!value) return `@decantr/cli@${DEFAULT_HEALTH_CI_CLI_VERSION}`;
+  const versionToken = value.startsWith("@decantr/cli@") ? value.slice("@decantr/cli@".length) : value;
+  if (!/^[A-Za-z0-9._~^*-]+$/.test(versionToken)) {
+    throw new Error(
+      "Invalid --cli-version value. Use a package version or dist-tag such as latest, 1.10.0, or next."
+    );
+  }
+  return `@decantr/cli@${versionToken}`;
+}
+function normalizeHealthFailOn(value) {
+  const failOn = value ?? "error";
+  if (!["error", "warn", "none"].includes(failOn)) {
+    throw new Error("Invalid --fail-on value. Use error, warn, or none.");
+  }
+  return failOn;
+}
+function validateWorkflowPath(value) {
+  const normalized = value.trim();
+  if (!normalized || normalized.startsWith("/") || normalized.startsWith("-") || normalized.includes("..") || normalized.includes("\\") || /\s/.test(normalized)) {
+    throw new Error(
+      "Invalid --workflow-path value. Use a relative path without spaces or parent-directory segments."
+    );
+  }
+  return normalized;
+}
+function validateArtifactPath(value, flag) {
+  const normalized = value.trim();
+  if (!normalized || normalized.startsWith("/") || normalized.startsWith("-") || normalized.includes("..") || normalized.includes("\\") || /\s/.test(normalized)) {
+    throw new Error(
+      `Invalid ${flag} value. Use a relative artifact path without spaces or parent-directory segments.`
+    );
+  }
+  return normalized;
+}
+function renderProjectHealthCiWorkflow(options = {}) {
+  const failOn = normalizeHealthFailOn(options.failOn);
+  const template = loadHealthTemplate("decantr-health.workflow.yml.template");
+  return renderTemplate(template, {
+    CLI_PACKAGE: normalizeCliPackageSpecifier(options.cliVersion),
+    FAIL_ON: failOn,
+    REPORT_PATH: validateArtifactPath(
+      options.reportPath || DEFAULT_HEALTH_CI_REPORT_PATH,
+      "--report-path"
+    ),
+    JSON_PATH: validateArtifactPath(options.jsonPath || DEFAULT_HEALTH_CI_JSON_PATH, "--json-path")
+  });
+}
+function writeProjectHealthCiWorkflow(projectRoot, options = {}) {
+  const workflowRelativePath = validateWorkflowPath(
+    options.workflowPath || DEFAULT_HEALTH_CI_WORKFLOW_PATH
+  );
+  const workflowPath = join(projectRoot, workflowRelativePath);
+  const alreadyExists = existsSync(workflowPath);
+  if (alreadyExists && !options.force) {
+    throw new Error(
+      `${workflowRelativePath} already exists. Re-run with --force to replace it, or use --workflow-path <file>.`
+    );
+  }
+  mkdirSync(dirname(workflowPath), { recursive: true });
+  writeFileSync(workflowPath, renderProjectHealthCiWorkflow(options), "utf-8");
+  return {
+    path: workflowRelativePath,
+    created: !alreadyExists,
+    cliPackage: normalizeCliPackageSpecifier(options.cliVersion),
+    failOn: normalizeHealthFailOn(options.failOn)
+  };
+}
 function collectDeclaredRoutes(essence) {
   if (!essence || typeof essence !== "object") return [];
   const record = essence;
@@ -393,6 +484,19 @@ function shouldFailHealth(report, failOn) {
   return report.summary.errorCount > 0;
 }
 async function cmdHealth(projectRoot = process.cwd(), options = {}) {
+  if (options.initCi) {
+    try {
+      const result = writeProjectHealthCiWorkflow(projectRoot, options.initCi);
+      const action = result.created ? "Created" : "Updated";
+      console.log(`${GREEN}${action} Decantr Project Health workflow:${RESET} ${result.path}`);
+      console.log(`${DIM}CLI package: ${result.cliPackage}${RESET}`);
+      console.log(`${DIM}CI gate: decantr health --ci --fail-on ${result.failOn}${RESET}`);
+    } catch (e) {
+      console.error(`${RED}${e.message}${RESET}`);
+      process.exitCode = 1;
+    }
+    return;
+  }
   const report = await createProjectHealthReport(projectRoot);
   if (options.promptId) {
     const finding = report.findings.find((entry) => entry.id === options.promptId);
@@ -420,6 +524,39 @@ async function cmdHealth(projectRoot = process.cwd(), options = {}) {
 }
 function parseHealthArgs(args) {
   const options = {};
+  if (args[1] === "init-ci") {
+    options.initCi = {};
+    for (let index = 2; index < args.length; index += 1) {
+      const arg = args[index];
+      if (arg === "--force") {
+        options.initCi.force = true;
+      } else if (arg === "--fail-on" && args[index + 1]) {
+        options.initCi.failOn = args[++index];
+      } else if (arg.startsWith("--fail-on=")) {
+        options.initCi.failOn = arg.split("=")[1];
+      } else if ((arg === "--cli-version" || arg === "--cli") && args[index + 1]) {
+        options.initCi.cliVersion = args[++index];
+      } else if (arg.startsWith("--cli-version=")) {
+        options.initCi.cliVersion = arg.split("=")[1];
+      } else if (arg.startsWith("--cli=")) {
+        options.initCi.cliVersion = arg.split("=")[1];
+      } else if (arg === "--workflow-path" && args[index + 1]) {
+        options.initCi.workflowPath = args[++index];
+      } else if (arg.startsWith("--workflow-path=")) {
+        options.initCi.workflowPath = arg.split("=")[1];
+      } else if (arg === "--report-path" && args[index + 1]) {
+        options.initCi.reportPath = args[++index];
+      } else if (arg.startsWith("--report-path=")) {
+        options.initCi.reportPath = arg.split("=")[1];
+      } else if (arg === "--json-path" && args[index + 1]) {
+        options.initCi.jsonPath = args[++index];
+      } else if (arg.startsWith("--json-path=")) {
+        options.initCi.jsonPath = arg.split("=")[1];
+      }
+    }
+    normalizeHealthFailOn(options.initCi.failOn);
+    return options;
+  }
   for (let index = 1; index < args.length; index += 1) {
     const arg = args[index];
     if (arg === "--json") {
@@ -456,6 +593,8 @@ function parseHealthArgs(args) {
 }
 
 export {
+  renderProjectHealthCiWorkflow,
+  writeProjectHealthCiWorkflow,
   createProjectHealthReport,
   formatProjectHealthText,
   formatProjectHealthMarkdown,