@decantr/cli 1.9.0 → 1.11.0

package/README.md

@@ -97,10 +97,15 @@ 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
+decantr health init-ci --project apps/registry
 ```
 
 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. In monorepos, add `--project <path>` from the repository root; dependency install stays at the root while health runs inside the app contract and uploads artifacts from that project path.
+
 `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
@@ -199,7 +204,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-PKJSI6IH.js";
+import "./chunk-5RODH77L.js";
 import "./chunk-USOO77A5.js";
 import "./chunk-DI2PLOJ6.js";

package/dist/{chunk-PKJSI6IH.js → chunk-5RODH77L.js}

@@ -6927,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 health init-ci [--force] [--project <path>] [--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>]
@@ -6965,7 +6966,7 @@ ${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
@@ -7005,6 +7006,8 @@ ${BOLD6}Examples:${RESET13}
   decantr rules apply
   decantr status
   decantr health
+  decantr health init-ci
+  decantr health init-ci --project apps/web
   decantr health --ci --fail-on error
   decantr content-health --ci --fail-on error
   decantr studio
@@ -7188,7 +7191,7 @@ async function main() {
     }
     case "health": {
       try {
-        const { cmdHealth, parseHealthArgs } = await import("./health-VSL4MROO.js");
+        const { cmdHealth, parseHealthArgs } = await import("./health-3TJYYTX6.js");
         await cmdHealth(process.cwd(), parseHealthArgs(args));
       } catch (e) {
         console.error(error3(e.message));
@@ -7208,7 +7211,7 @@ async function main() {
     }
     case "studio": {
       try {
-        const { cmdStudio, parseStudioArgs } = await import("./studio-BCTWKXFH.js");
+        const { cmdStudio, parseStudioArgs } = await import("./studio-7TE7YXFG.js");
         await cmdStudio(process.cwd(), parseStudioArgs(args));
       } catch (e) {
         console.error(error3(e.message));

package/dist/{chunk-DONMNPS7.js → chunk-6YCFRZZI.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,122 @@ 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 validateProjectPath(value) {
+  if (value === void 0) return void 0;
+  const raw = value.trim();
+  if (!raw || raw === ".") return void 0;
+  const normalized = raw.replace(/^\.\/+/, "").replace(/\/+$/, "");
+  if (!normalized || normalized.startsWith("/") || normalized.startsWith("-") || normalized.includes("..") || normalized.includes("\\") || /\s/.test(normalized) || !/^[A-Za-z0-9._@/-]+$/.test(normalized)) {
+    throw new Error(
+      "Invalid --project value. Use a relative project path without spaces or parent-directory segments."
+    );
+  }
+  const segments = normalized.split("/");
+  if (segments.some((segment) => !segment || segment === "." || segment === "..")) {
+    throw new Error(
+      "Invalid --project value. Use a relative project path without empty or parent-directory segments."
+    );
+  }
+  return normalized;
+}
+function prefixArtifactPath(projectPath, artifactPath) {
+  return projectPath ? `${projectPath}/${artifactPath}` : artifactPath;
+}
+function renderProjectHealthCiWorkflow(options = {}) {
+  const failOn = normalizeHealthFailOn(options.failOn);
+  const projectPath = validateProjectPath(options.projectPath);
+  const reportPath = validateArtifactPath(
+    options.reportPath || DEFAULT_HEALTH_CI_REPORT_PATH,
+    "--report-path"
+  );
+  const jsonPath = validateArtifactPath(options.jsonPath || DEFAULT_HEALTH_CI_JSON_PATH, "--json-path");
+  const template = loadHealthTemplate("decantr-health.workflow.yml.template");
+  return renderTemplate(template, {
+    CLI_PACKAGE: normalizeCliPackageSpecifier(options.cliVersion),
+    FAIL_ON: failOn,
+    PROJECT_WORKING_DIRECTORY: projectPath ? `        working-directory: ${projectPath}
+` : "",
+    REPORT_PATH: reportPath,
+    JSON_PATH: jsonPath,
+    REPORT_ARTIFACT_PATH: prefixArtifactPath(projectPath, reportPath),
+    JSON_ARTIFACT_PATH: prefixArtifactPath(projectPath, jsonPath)
+  });
+}
+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");
+  const projectPath = validateProjectPath(options.projectPath);
+  const result = {
+    path: workflowRelativePath,
+    created: !alreadyExists,
+    cliPackage: normalizeCliPackageSpecifier(options.cliVersion),
+    failOn: normalizeHealthFailOn(options.failOn)
+  };
+  if (projectPath) result.projectPath = projectPath;
+  return result;
+}
 function collectDeclaredRoutes(essence) {
   if (!essence || typeof essence !== "object") return [];
   const record = essence;
@@ -393,6 +515,22 @@ 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}`);
+      if (result.projectPath) {
+        console.log(`${DIM}Project: ${result.projectPath}${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 +558,44 @@ 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];
+      } else if (arg === "--project" && args[index + 1]) {
+        options.initCi.projectPath = args[++index];
+      } else if (arg.startsWith("--project=")) {
+        options.initCi.projectPath = arg.split("=")[1];
+      }
+    }
+    normalizeHealthFailOn(options.initCi.failOn);
+    validateProjectPath(options.initCi.projectPath);
+    return options;
+  }
   for (let index = 1; index < args.length; index += 1) {
     const arg = args[index];
     if (arg === "--json") {
@@ -456,6 +632,8 @@ function parseHealthArgs(args) {
 }
 
 export {
+  renderProjectHealthCiWorkflow,
+  writeProjectHealthCiWorkflow,
   createProjectHealthReport,
   formatProjectHealthText,
   formatProjectHealthMarkdown,

package/dist/{health-VSL4MROO.js → health-3TJYYTX6.js}

@@ -5,8 +5,10 @@ import {
   formatProjectHealthMarkdown,
   formatProjectHealthText,
   parseHealthArgs,
-  shouldFailHealth
-} from "./chunk-DONMNPS7.js";
+  renderProjectHealthCiWorkflow,
+  shouldFailHealth,
+  writeProjectHealthCiWorkflow
+} from "./chunk-6YCFRZZI.js";
 import "./chunk-RSDCWAHD.js";
 import "./chunk-DI2PLOJ6.js";
 export {
@@ -16,5 +18,7 @@ export {
   formatProjectHealthMarkdown,
   formatProjectHealthText,
   parseHealthArgs,
-  shouldFailHealth
+  renderProjectHealthCiWorkflow,
+  shouldFailHealth,
+  writeProjectHealthCiWorkflow
 };

package/dist/index.js

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

package/dist/{studio-BCTWKXFH.js → studio-7TE7YXFG.js}

@@ -1,6 +1,6 @@
 import {
   createProjectHealthReport
-} from "./chunk-DONMNPS7.js";
+} from "./chunk-6YCFRZZI.js";
 import "./chunk-RSDCWAHD.js";
 import "./chunk-DI2PLOJ6.js";
 

package/package.json

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

package/src/templates/DECANTR.md.template

@@ -115,7 +115,7 @@ Read `.decantr/context/page-{name}-pack.md` for the most local compiled route co
 ### Validation
 
 Run `decantr check` to detect drift violations while editing and `decantr audit` to audit the whole project contract after implementation.
-Run `decantr health` for the broader Project Health view before handoff, pull requests, or CI. Use `decantr health --prompt <finding-id>` to generate a scoped remediation prompt for a specific issue, and `decantr studio` to inspect local drift, routes, findings, remediation, CI, and pack state in a localhost dashboard.
+Run `decantr health` for the broader Project Health view before handoff, pull requests, or CI. Use `decantr health init-ci` to install the default GitHub Actions health gate, `decantr health --prompt <finding-id>` to generate a scoped remediation prompt for a specific issue, and `decantr studio` to inspect local drift, routes, findings, remediation, CI, and pack state in a localhost dashboard.
 Declared command palettes and hotkeys must be implemented, not merely acknowledged.
 
 ### Quick Commands
@@ -123,6 +123,7 @@ Declared command palettes and hotkeys must be implemented, not merely acknowledg
 ```bash
 decantr status          # Project status overview
 decantr health          # Local contract health report
+decantr health init-ci  # Install GitHub Actions health gate
 decantr studio          # Local health dashboard
 decantr check           # Detect drift violations
 decantr get pattern X   # Fetch a pattern spec from registry

package/src/templates/decantr-health.workflow.yml.template

@@ -0,0 +1,62 @@
+name: Decantr Project Health
+
+on:
+  pull_request:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  health:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+
+      - name: Install dependencies
+        shell: bash
+        run: |
+          if [ -f pnpm-lock.yaml ]; then
+            corepack enable
+            pnpm install --frozen-lockfile
+          elif [ -f package-lock.json ]; then
+            npm ci
+          elif [ -f yarn.lock ]; then
+            corepack enable
+            yarn install --frozen-lockfile
+          elif [ -f package.json ]; then
+            npm install
+          else
+            echo "No package manifest found; skipping dependency install."
+          fi
+
+      - name: Generate Decantr health JSON
+{{PROJECT_WORKING_DIRECTORY}}        run: npx --yes {{CLI_PACKAGE}} health --json --output {{JSON_PATH}}
+
+      - name: Audit Decantr health
+{{PROJECT_WORKING_DIRECTORY}}        run: npx --yes {{CLI_PACKAGE}} health --ci --fail-on {{FAIL_ON}} --markdown --output {{REPORT_PATH}}
+
+      - name: Publish health summary
+        if: always()
+{{PROJECT_WORKING_DIRECTORY}}        shell: bash
+        run: |
+          if [ -f {{REPORT_PATH}} ]; then
+            cat {{REPORT_PATH}} >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+      - name: Upload health artifacts
+        if: always()
+        uses: actions/upload-artifact@v6
+        with:
+          name: decantr-project-health
+          path: |
+            {{JSON_ARTIFACT_PATH}}
+            {{REPORT_ARTIFACT_PATH}}
+          if-no-files-found: ignore