@decantr/cli 1.7.28 → 1.8.0

package/dist/chunk-RSDCWAHD.js

@@ -0,0 +1,328 @@
+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";
+function collectCheckIssues(projectRoot = process.cwd(), options = {}) {
+  const essencePath = join2(projectRoot, "decantr.essence.json");
+  if (!existsSync2(essencePath)) {
+    return {
+      essence: null,
+      issues: [
+        {
+          type: "error",
+          rule: "essence-missing",
+          message: "No decantr.essence.json found. Run `decantr init` first."
+        }
+      ],
+      missingEssence: true
+    };
+  }
+  const essence = JSON.parse(readFileSync2(essencePath, "utf-8"));
+  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}`
+      });
+    }
+  }
+  return { essence, issues, missingEssence: false };
+}
+async function cmdHeal(projectRoot = process.cwd(), options = {}) {
+  const result = collectCheckIssues(projectRoot, options);
+  console.log("Scanning for issues...\n");
+  if (result.missingEssence) {
+    console.error(result.issues[0]?.message ?? "No decantr.essence.json found.");
+    process.exitCode = 1;
+    return;
+  }
+  const issues = result.issues;
+  const essence = result.essence ?? {};
+  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 {
+  collectCheckIssues,
+  cmdHeal
+};

package/dist/{chunk-GCDFX7UE.js → chunk-USOO77A5.js}

@@ -2865,7 +2865,8 @@ function resolvePatternAlias(item, patterns) {
   return item;
 }
 function buildEssenceV3(options, archetypeData, themeHints) {
-  let pages = [{ id: "home", layout: ["hero"] }];
+  const isBrownfieldAttach = options.workflowMode === "brownfield-attach";
+  let pages = isBrownfieldAttach ? [{ id: "observed-app", layout: ["existing-surface"] }] : [{ id: "home", layout: ["hero"] }];
   let features = options.features;
   let defaultShell = options.shell || "sidebar-main";
   if (archetypeData?.pages) {
@@ -3710,10 +3711,10 @@ function generateDecantrMdV31(params) {
     WORKFLOW_GUIDANCE: params.workflowMode === "brownfield-attach" ? params.analysisArtifacts ? `This project is using Decantr in **brownfield attach** mode with **${params.adoptionMode || "contract-only"}** adoption.
 
 Read \`.decantr/analysis.json\` first for the detected framework, routes, styling, layout, and dependency facts.
-Then read \`.decantr/init-seed.json\` for the recommended attach defaults.
-Then read \`.decantr/context/scaffold-pack.md\` and \`.decantr/context/scaffold.md\` to understand the Decantr contract you are layering onto the existing app.
+Then read \`.decantr/doctrine-map.json\`, \`.decantr/ambient-context.json\`, and \`.decantr/brownfield-report.md\` for ranked source precedence, existing assistant rules, docs, design-system evidence, and unresolved doctrine risks.
+Then read \`.decantr/context/scaffold-pack.md\` and \`.decantr/context/scaffold.md\` to understand the accepted Decantr contract.
 
-Preserve the current framework, package manager, router, and working runtime structure unless the contract gives you a reviewed reason to change them. Map existing routes and components onto the declared Decantr sections/pages before creating new files. Registry content is optional in this workflow unless the task explicitly asks for it.` : `This project is using Decantr in **brownfield attach** mode with **${params.adoptionMode || "contract-only"}** adoption.
+Treat Decantr as the reconciled contract layer and the original docs/rules as cited evidence. Preserve the current framework, package manager, router, styling system, data boundaries, and working runtime structure unless the contract gives you a reviewed reason to change them. Registry content is optional in this workflow unless the task explicitly asks for it.` : `This project is using Decantr in **brownfield attach** mode with **${params.adoptionMode || "contract-only"}** adoption.
 
 No \`.decantr/analysis.json\` or \`.decantr/init-seed.json\` was present when this context was generated. Inventory the current framework, routes, styling, layout, package manager, and rule files before changing runtime code. Then read \`.decantr/context/scaffold-pack.md\` and \`.decantr/context/scaffold.md\` to understand the Decantr contract you are layering onto the existing app.
 
@@ -3755,7 +3756,16 @@ Start implementation from the shell layouts and shared route structure before fi
   }
   briefLines.push(`- **Guard mode:** ${params.guardMode}`);
   briefLines.push("");
-  const escDecCell = (s) => s.replace(/\|/g, "\\|");
+  const escDecCell = (s) => {
+    let escaped = "";
+    for (const char of s) {
+      if (char === "\\") escaped += "\\\\";
+      else if (char === "|") escaped += "\\|";
+      else if (char === "\n" || char === "\r") escaped += "<br>";
+      else escaped += char;
+    }
+    return escaped;
+  };
   if (params.decoratorDefinitions && Object.keys(params.decoratorDefinitions).length > 0) {
     briefLines.push("### Decorator Quick Reference");
     briefLines.push(