@decantr/cli 1.7.28 → 1.7.29

package/dist/heal-YHLXO5QL.js

@@ -0,0 +1,307 @@
+import {
+  buildGuardRegistryContext,
+  collectMetrics,
+  createDoctrineMap,
+  isOptedIn,
+  optIn,
+  readDoctrineMap,
+  scanAmbientContext,
+  scanProjectInteractions,
+  scanRoutes,
+  scanStyling,
+  sendGuardMetrics
+} from "./chunk-DI2PLOJ6.js";
+
+// src/commands/heal.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { join as join2 } from "path";
+import { evaluateGuard, isV3, validateEssence } from "@decantr/essence-spec";
+
+// src/brownfield-check.ts
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+function readProjectJson(projectRoot) {
+  const path = join(projectRoot, ".decantr", "project.json");
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function essenceRoutes(essence) {
+  const fromRouteMap = Object.keys(essence.blueprint.routes ?? {});
+  const fromPages = essence.blueprint.sections?.flatMap(
+    (section) => section.pages.map((page) => page.route).filter((route) => Boolean(route))
+  ) ?? essence.blueprint.pages?.map((page) => page.route).filter((route) => Boolean(route)) ?? [];
+  return /* @__PURE__ */ new Set([...fromRouteMap, ...fromPages]);
+}
+function routeLabel(routes) {
+  if (routes.length <= 6) return routes.join(", ");
+  return `${routes.slice(0, 6).join(", ")} (+${routes.length - 6} more)`;
+}
+function hasDoctrineEffect(essence, key) {
+  const effects = essence.dna.constraints?.effects;
+  return Boolean(effects && effects[key]);
+}
+function hasActionableDoctrineSource(doctrine, area) {
+  return doctrine.sources.some(
+    (source) => source.area === area && source.currency === "current" && source.safeToCite && source.confidence >= 0.72 && source.precedence >= 75
+  );
+}
+function hasAssistantBridge(projectRoot) {
+  const previewPath = join(projectRoot, ".decantr", "context", "assistant-bridge.md");
+  if (existsSync(previewPath)) return true;
+  const candidateFiles = [
+    "CLAUDE.md",
+    "AGENTS.md",
+    "GEMINI.md",
+    "copilot-instructions.md",
+    ".github/copilot-instructions.md",
+    ".cursorrules",
+    ".windsurfrules",
+    ".claude/rules/decantr.md",
+    ".cursor/rules/decantr.mdc"
+  ];
+  return candidateFiles.some((rel) => {
+    const path = join(projectRoot, rel);
+    if (!existsSync(path)) return false;
+    try {
+      return readFileSync(path, "utf-8").includes("decantr:assistant-bridge:start");
+    } catch {
+      return false;
+    }
+  });
+}
+function scanBrownfieldIssues(projectRoot, essence) {
+  const projectJson = readProjectJson(projectRoot);
+  const routes = scanRoutes(projectRoot);
+  const styling = scanStyling(projectRoot);
+  const ambient = scanAmbientContext(projectRoot);
+  const doctrine = readDoctrineMap(projectRoot) ?? createDoctrineMap(ambient);
+  const issues = [];
+  const declaredRoutes = essenceRoutes(essence);
+  const observedRoutes = new Set(routes.routes.map((route) => route.path));
+  const missingFromEssence = [...observedRoutes].filter((route) => !declaredRoutes.has(route));
+  const missingFromSource = [...declaredRoutes].filter((route) => !observedRoutes.has(route));
+  if (routes.routes.length > 0 && declaredRoutes.size === 0) {
+    issues.push({
+      type: "error",
+      rule: "brownfield-route-coverage",
+      message: `The app has ${routes.routes.length} observed route(s), but the Decantr essence declares no routes.`,
+      suggestion: "Run `decantr analyze`, review the proposal, then `decantr init --existing --accept-proposal` or `--merge-proposal`."
+    });
+  } else if (missingFromEssence.length > 0) {
+    issues.push({
+      type: "error",
+      rule: "brownfield-route-drift",
+      message: `Observed routes are missing from the Decantr contract: ${routeLabel(missingFromEssence)}.`,
+      suggestion: "Regenerate a brownfield proposal and merge the missing routes into the essence."
+    });
+  }
+  if (routes.routes.length > 0 && declaredRoutes.size === 1 && declaredRoutes.has("/") && routes.routes.length > 1) {
+    issues.push({
+      type: "error",
+      rule: "brownfield-generic-contract",
+      message: "The essence only declares `/` while the app has multiple observed routes.",
+      suggestion: "Accept or merge an observed brownfield proposal instead of using a generic scaffold contract."
+    });
+  }
+  if (missingFromSource.length > 0 && routes.routes.length > 0) {
+    issues.push({
+      type: "warning",
+      rule: "brownfield-stale-route",
+      message: `Essence routes were not observed in source: ${routeLabel(missingFromSource)}.`,
+      suggestion: "Confirm whether these are generated/dynamic routes or stale contract entries."
+    });
+  }
+  const adoptionMode = projectJson.initialized?.adoptionMode;
+  const themeId = essence.dna.theme.id;
+  if (adoptionMode === "contract-only" && themeId === "luminarum" && (styling.approach !== "unknown" || styling.cssVariables.length > 0)) {
+    issues.push({
+      type: "warning",
+      rule: "brownfield-theme-default",
+      message: "Contract-only brownfield essence still uses Decantr theme `luminarum` while the app has an existing styling system.",
+      suggestion: 'Use an observed proposal with `theme.id = "existing"` unless the user explicitly opts into a Decantr theme.'
+    });
+  }
+  for (const conflict of ambient.conflicts) {
+    issues.push({
+      type: "warning",
+      rule: "brownfield-doctrine-conflict",
+      message: conflict,
+      suggestion: "Resolve or document precedence before treating these rules as enforceable contract."
+    });
+  }
+  if (ambient.items.length === 0) {
+    issues.push({
+      type: "warning",
+      rule: "brownfield-context-missing",
+      message: "No ambient project context was detected for this brownfield check.",
+      suggestion: "Run `decantr analyze` to create `.decantr/ambient-context.json` and a proposal-backed report."
+    });
+  }
+  const hasBrownfieldArtifacts = Boolean(projectJson.initialized?.workflowMode === "brownfield-attach");
+  if (hasBrownfieldArtifacts && !existsSync(join(projectRoot, ".decantr", "doctrine-map.json"))) {
+    issues.push({
+      type: "warning",
+      rule: "brownfield-doctrine-map-missing",
+      message: "Brownfield attach metadata exists, but `.decantr/doctrine-map.json` is missing.",
+      suggestion: "Run `decantr analyze` to regenerate ranked doctrine evidence."
+    });
+  }
+  if (hasActionableDoctrineSource(doctrine, "security-data") && !hasDoctrineEffect(essence, "doctrine-security-data")) {
+    issues.push({
+      type: "warning",
+      rule: "brownfield-doctrine-coverage",
+      message: "Security/data doctrine was detected, but the essence does not record a security/data preservation constraint.",
+      suggestion: "Regenerate and merge a brownfield proposal so security/data doctrine is represented in `dna.constraints.effects`."
+    });
+  }
+  if (hasActionableDoctrineSource(doctrine, "design-system") && !hasDoctrineEffect(essence, "doctrine-design-system")) {
+    issues.push({
+      type: "warning",
+      rule: "brownfield-doctrine-coverage",
+      message: "Design-system doctrine was detected, but the essence does not record a design-system preservation constraint.",
+      suggestion: "Regenerate and merge a brownfield proposal so design-system doctrine is represented in `dna.constraints.effects`."
+    });
+  }
+  if (styling.approach !== "unknown") {
+    const palette = String(essence.dna.color.palette ?? "");
+    const observedPalette = palette === "observed" || palette === styling.approach;
+    if (themeId === "existing" && !observedPalette) {
+      issues.push({
+        type: "warning",
+        rule: "brownfield-style-drift",
+        message: `Observed styling approach is ${styling.approach}, but the essence color palette is ${palette || "unset"}.`,
+        suggestion: "Regenerate and merge a brownfield proposal so the contract reflects the existing styling system."
+      });
+    }
+  }
+  if (ambient.items.some((item) => item.role === "assistant-specific") && hasBrownfieldArtifacts && !hasAssistantBridge(projectRoot)) {
+    issues.push({
+      type: "warning",
+      rule: "brownfield-assistant-bridge-missing",
+      message: "Assistant-specific rule files were detected, but no Decantr assistant bridge preview or applied bridge block was found.",
+      suggestion: "Run `decantr rules preview` first, then `decantr rules apply` if the user explicitly approves rule-file mutation."
+    });
+  }
+  const unsafeSources = doctrine.sources.filter((source) => !source.safeToCite);
+  if (unsafeSources.length > 0) {
+    issues.push({
+      type: "warning",
+      rule: "brownfield-unsafe-context",
+      message: `Some ambient context should not be cited directly: ${unsafeSources.slice(0, 4).map((source) => source.path).join(", ")}${unsafeSources.length > 4 ? ` (+${unsafeSources.length - 4} more)` : ""}.`,
+      suggestion: "Keep unsafe source paths in the inventory, but do not paste their contents into assistant context."
+    });
+  }
+  return issues;
+}
+
+// src/commands/heal.ts
+var GREEN = "\x1B[32m";
+var RED = "\x1B[31m";
+var YELLOW = "\x1B[33m";
+var CYAN = "\x1B[36m";
+var RESET = "\x1B[0m";
+var DIM = "\x1B[2m";
+async function cmdHeal(projectRoot = process.cwd(), options = {}) {
+  const essencePath = join2(projectRoot, "decantr.essence.json");
+  if (!existsSync2(essencePath)) {
+    console.error("No decantr.essence.json found. Run `decantr init` first.");
+    process.exitCode = 1;
+    return;
+  }
+  const essence = JSON.parse(readFileSync2(essencePath, "utf-8"));
+  console.log("Scanning for issues...\n");
+  const issues = [];
+  const validation = validateEssence(essence);
+  if (!validation.valid) {
+    for (const err of validation.errors) {
+      issues.push({
+        type: "error",
+        rule: "schema",
+        message: err
+      });
+    }
+  }
+  let interactionIssues = [];
+  try {
+    interactionIssues = scanProjectInteractions(projectRoot);
+  } catch {
+  }
+  try {
+    const guardContext = buildGuardRegistryContext(projectRoot);
+    const violations = evaluateGuard(essence, {
+      ...guardContext,
+      interaction_issues: interactionIssues
+    });
+    for (const v of violations) {
+      issues.push({
+        type: v.severity === "error" ? "error" : "warning",
+        rule: v.rule,
+        message: v.message,
+        suggestion: v.suggestion
+      });
+    }
+  } catch {
+  }
+  if (options.brownfield) {
+    try {
+      if (isV3(essence)) {
+        const brownfieldIssues = scanBrownfieldIssues(projectRoot, essence);
+        issues.push(...brownfieldIssues);
+      } else {
+        issues.push({
+          type: "warning",
+          rule: "brownfield-check",
+          message: "Brownfield checks require a v3 Decantr essence."
+        });
+      }
+    } catch (e) {
+      issues.push({
+        type: "warning",
+        rule: "brownfield-check",
+        message: `Brownfield check could not complete: ${e.message}`
+      });
+    }
+  }
+  if (issues.length === 0) {
+    console.log(`${GREEN}No issues found. Project is healthy.${RESET}`);
+    await maybeSendTelemetry(projectRoot, essence, issues, options);
+    return;
+  }
+  console.log(`Found ${issues.length} issue(s):
+`);
+  for (const issue of issues) {
+    const icon = issue.type === "error" ? `${RED}x${RESET}` : `${YELLOW}!${RESET}`;
+    console.log(`${icon} [${issue.rule}] ${issue.message}`);
+    if (issue.suggestion) {
+      console.log(`  ${DIM}Suggestion: ${issue.suggestion}${RESET}`);
+    }
+  }
+  console.log(`
+${YELLOW}Manual fixes required. Review the issues above.${RESET}`);
+  const hasError = issues.some((i) => i.type === "error");
+  if (hasError) {
+    process.exitCode = 1;
+  }
+  await maybeSendTelemetry(projectRoot, essence, issues, options);
+}
+async function maybeSendTelemetry(projectRoot, essence, issues, options) {
+  if (options.telemetry && !isOptedIn(projectRoot)) {
+    optIn(projectRoot);
+    console.log(
+      `
+${CYAN}Telemetry enabled.${RESET} Anonymous guard metrics will be sent on future checks.`
+    );
+    console.log(`${DIM}Set "telemetry": false in .decantr/project.json to opt out.${RESET}`);
+  }
+  if (isOptedIn(projectRoot)) {
+    const metrics = collectMetrics(essence, issues);
+    sendGuardMetrics(metrics);
+  }
+}
+export {
+  cmdHeal
+};

package/dist/index.js

@@ -1,3 +1,3 @@
-import "./chunk-56VBV4MT.js";
-import "./chunk-GCDFX7UE.js";
-import "./chunk-RRRHQ45P.js";
+import "./chunk-US6RK5QT.js";
+import "./chunk-HULA6E2D.js";
+import "./chunk-DI2PLOJ6.js";

package/dist/{upgrade-XMY6LIPS.js → upgrade-EV23CKA3.js}

@@ -1,7 +1,7 @@
 import {
   RegistryClient,
   refreshDerivedFiles
-} from "./chunk-GCDFX7UE.js";
+} from "./chunk-HULA6E2D.js";
 
 // src/commands/upgrade.ts
 import { existsSync, readFileSync, writeFileSync } from "fs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decantr/cli",
-  "version": "1.7.28",
+  "version": "1.7.29",
   "description": "Decantr CLI — scaffold, audit, and maintain Decantr projects from the terminal",
   "author": "Decantr AI",
   "license": "MIT",
@@ -30,11 +30,11 @@
     "access": "public"
   },
   "dependencies": {
+    "@decantr/telemetry": "0.1.2",
     "@decantr/core": "1.0.6",
-    "@decantr/registry": "1.0.4",
+    "@decantr/essence-spec": "1.0.7",
     "@decantr/verifier": "1.0.6",
-    "@decantr/telemetry": "0.1.2",
-    "@decantr/essence-spec": "1.0.6"
+    "@decantr/registry": "1.0.4"
   },
   "scripts": {
     "build": "tsup",