@decantr/cli 2.9.2 → 2.9.4

package/README.md

@@ -21,9 +21,11 @@ Use `decantr setup` when you are unsure which path applies. It detects whether t
 Use `decantr new` for a greenfield workspace in a fresh directory. With a blueprint/archetype it uses the runnable adapter and Decantr CSS; without registry content it creates a contract-only workspace unless you explicitly pass `--adoption=decantr-css`.
 Use `decantr adopt` when you already have an app and want Decantr governance without adopting a blueprint. Brownfield attach is proposal-driven: Decantr inventories the app, writes an observed essence proposal, hydrates hosted execution packs when online, and only applies the contract when you explicitly accept or merge it.
 Use `decantr doctor` when the next step is unclear, `decantr task` before asking an LLM to modify a route, `decantr verify` after the edit, and `decantr ci` in required automation. Use `decantr codify --from-audit` when you want project-owned UI patterns and local rules such as button/card/shell/theme standards to appear in future task context and verification.
-In monorepos, app-scoped commands accept `--project <app-path>`. Hosted pack hydration also follows the essence path: `decantr registry compile-packs apps/web/decantr.essence.json --write-context` writes into `apps/web/.decantr/context`.
+In monorepos, app-scoped commands accept `--project <app-path>`. `setup` shows attach guidance before adoption and the day-two loop after adoption. Hosted pack hydration also follows the essence path: `decantr registry compile-packs apps/web/decantr.essence.json --write-context` writes into `apps/web/.decantr/context`. In contract-only/offline Brownfield, deferred hosted packs are optional context unless a present manifest references missing files.
 Use `decantr init`, `decantr analyze`, `decantr check`, and `decantr health` as advanced primitives when you need direct control over one step.
 
+App-scoped primitives now share the same `--project` posture as the primary workflow commands. From a workspace root, `health`, `status`, `upgrade`, `add`, `remove`, `theme`, `export`, `suggest`, `magic`, `rules`, and `telemetry` target the selected app instead of the root. Task/read paths, local-law summaries, and refresh change summaries are printed as openable workspace paths. Nonexistent project paths fail immediately, and Brownfield adoption refuses component packages unless you intentionally pass `--force-package`.
+
 Current starter adapter availability:
 
 - `react-vite` is the React + Vite runnable bootstrap adapter
@@ -128,6 +130,8 @@ decantr list blueprints --blueprint-set featured
 decantr list blueprints --blueprint-set certified
 decantr search dashboard --type blueprint --blueprint-set labs
 decantr suggest "recipe feed with infinite scroll" --route /feed --from-code
+decantr suggest --from-code --file app/page.tsx --project apps/web
+decantr suggest "standardize buttons" --project apps/web
 decantr list patterns
 decantr showcase verification --json
 ```
@@ -156,6 +160,7 @@ decantr health
 decantr health --format json
 decantr health --markdown --output health.md
 decantr health --prompt <finding-id>
+decantr health --project apps/registry --prompt <finding-id>
 decantr health --evidence --output .decantr/evidence/latest.json
 decantr health --browser --base-url http://localhost:3000 --evidence
 decantr health --save-baseline
@@ -171,11 +176,11 @@ decantr verify --workspace --changed --since origin/main
 decantr export --to figma-tokens
 ```
 
-Use `--json` for machines and schema validation, `--markdown` for summaries, `--evidence` for the privacy-redacted Evidence Bundle, and `--prompt <finding-id>` when you want a scoped remediation prompt for an AI assistant. The prompt command prints instructions only; it does not modify source files. `--browser` uses a project-local Playwright install and a supplied base URL to capture local route screenshots under `.decantr/evidence/screenshots/` and write `.decantr/evidence/visual-manifest.json`; missing Playwright becomes a setup finding, not a crash. `--save-baseline` writes `.decantr/health-baseline.json`; `--since-baseline` writes `.decantr/health-baseline-diff.json` with changed files, route impact, finding deltas, screenshot hash drift, and contract drift. `--design-tokens <path>` compares a Tokens Studio/Figma token JSON export against Decantr CSS token names. `decantr ci --fail-on error` fails only when blocking errors exist; `decantr ci --fail-on warn` also fails on warnings.
+Use `--json` for machines and schema validation, `--markdown` for summaries, `--evidence` for the privacy-redacted Evidence Bundle, and `--prompt <finding-id>` when you want a scoped remediation prompt for an AI assistant. The prompt command prints instructions only; it does not modify source files. In monorepos, prompt commands preserve `--project <path>`, include app-prefixed read targets such as `apps/web/DECANTR.md`, and use root-safe runtime commands such as `pnpm --dir apps/web build` so the finding resolves from the same app that produced it. `--browser` uses a project-local Playwright install and a supplied base URL to capture local route screenshots under `.decantr/evidence/screenshots/` and write `.decantr/evidence/visual-manifest.json`; missing Playwright becomes a visible setup finding/message, not a crash or silent skip. `--save-baseline` writes `.decantr/health-baseline.json`; `--since-baseline` writes `.decantr/health-baseline-diff.json` with changed files, route impact, finding deltas, screenshot hash drift, and contract drift. `--design-tokens <path>` compares a Tokens Studio/Figma token JSON export against Decantr CSS token names. `decantr ci --fail-on error` fails only when blocking errors exist; `decantr ci --fail-on warn` also fails on warnings.
 
 `decantr ci init` installs `.github/workflows/decantr-ci.yml` for GitHub Actions. The generated workflow installs dependencies at the workspace root, writes JSON/markdown CI artifacts, gates with `decantr ci`, appends the markdown report to the GitHub step summary, and uploads both files as artifacts. Use `--force` to replace an existing workflow or `--fail-on warn` for stricter repositories. In monorepos, add `--project <path>` from the repository root; dependency install stays at the root while CI evaluates the app contract and uploads app-scoped artifacts. Use `--workspace` to generate an aggregate gate. Use `--provider generic` for Jenkins, Please, Buildkite, GitLab, Azure DevOps, or internal deployment tools. Generated CI uses the pinned local package-manager command and does not depend on `@latest`. Project Health remediation prompts are also monorepo-aware, so missing-pack fixes use `apps/web/decantr.essence.json` and CI recommendations include `--project apps/web`.
 
-`decantr workspace` is the monorepo reliability namespace. Before attach, `workspace list` shows app candidates. After attach, it also discovers Decantr projects from `.decantr/workspace.json` or by finding `decantr.essence.json` files. Workspace health runs projects with deterministic ordering, concurrency, per-project timeout, failure isolation, and aggregate JSON, and can limit a run to changed projects:
+`decantr workspace` is the monorepo reliability namespace. Before attach, `workspace list` shows app candidates. After attach, it also discovers Decantr projects from `.decantr/workspace.json` or by finding `decantr.essence.json` files, and it distinguishes "attach another app" from the empty-workspace first attach. Workspace health runs projects with deterministic ordering, concurrency, per-project timeout, failure isolation, and aggregate JSON, and can limit a run to changed projects:
 
 ```bash
 decantr workspace list

package/dist/bin.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import "./chunk-AXMGQ5IB.js";
+import "./chunk-GDGZFGMK.js";
 import "./chunk-RXF7ZYGK.js";
-import "./chunk-R57DMFLF.js";
-import "./chunk-DX2UDORT.js";
-import "./chunk-34TZXWIF.js";
+import "./chunk-VCUFZB45.js";
+import "./chunk-FACL3NXU.js";
+import "./chunk-WONPNSSI.js";

package/dist/{chunk-DX2UDORT.js → chunk-FACL3NXU.js}

@@ -3,14 +3,14 @@ import {
   sendProjectHealthCiFailedTelemetry,
   sendProjectHealthPromptTelemetry,
   sendProjectHealthReportTelemetry
-} from "./chunk-34TZXWIF.js";
+} from "./chunk-WONPNSSI.js";
 
 // src/commands/health.ts
 import { execFileSync } from "child_process";
 import { createHash } from "crypto";
 import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
 import { createRequire } from "module";
-import { dirname as dirname2, isAbsolute, join as join2, relative, resolve as resolve2 } from "path";
+import { dirname as dirname2, isAbsolute as isAbsolute2, join as join2, relative, resolve as resolve2 } from "path";
 import { fileURLToPath } from "url";
 import {
   auditProject,
@@ -20,7 +20,7 @@ import {
 
 // src/workspace.ts
 import { existsSync, readdirSync, readFileSync } from "fs";
-import { dirname, join, resolve } from "path";
+import { dirname, isAbsolute, join, resolve } from "path";
 function readPackageJson(dir) {
   const path = join(dir, "package.json");
   if (!existsSync(path)) return null;
@@ -92,7 +92,7 @@ function listWorkspaceAppCandidates(workspaceRoot) {
 function resolveWorkspaceInfo(cwd, projectArg) {
   const absoluteCwd = resolve(cwd);
   const workspaceRoot = findWorkspaceRoot(absoluteCwd) ?? absoluteCwd;
-  const appRoot = projectArg ? resolve(absoluteCwd, projectArg) : absoluteCwd;
+  const appRoot = projectArg ? resolve(isAbsolute(projectArg) ? "/" : workspaceRoot, projectArg) : absoluteCwd;
   const appCandidates = listWorkspaceApps(workspaceRoot);
   const projectScope = workspaceRoot !== appRoot || appCandidates.length > 0 ? "workspace-app" : "single-app";
   const requiresProjectSelection = !projectArg && workspaceRoot === absoluteCwd && appCandidates.length > 0;
@@ -333,6 +333,9 @@ function contractAssertionApplies(assertion, metadata) {
   if (assertion.rule === "tokens-file-present" && metadata.adoptionMode === "contract-only") {
     return false;
   }
+  if (metadata.adoptionMode === "contract-only" && (assertion.rule === "pack-manifest-present" || assertion.rule === "review-pack-present")) {
+    return false;
+  }
   return true;
 }
 function slugify(value) {
@@ -380,20 +383,67 @@ function commandsForFinding(source) {
       return ["decantr audit", "decantr health"];
   }
 }
+function detectPackageManager(root) {
+  const pkg = readJsonFile(join2(root, "package.json"));
+  const declared = pkg?.packageManager?.split("@")[0];
+  if (declared === "pnpm" || declared === "npm" || declared === "yarn" || declared === "bun") {
+    return declared;
+  }
+  if (existsSync2(join2(root, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync2(join2(root, "package-lock.json"))) return "npm";
+  if (existsSync2(join2(root, "yarn.lock"))) return "yarn";
+  if (existsSync2(join2(root, "bun.lock")) || existsSync2(join2(root, "bun.lockb"))) return "bun";
+  return "unknown";
+}
+function buildCommandForProject(workspaceRoot, projectPath) {
+  const packageManager = detectPackageManager(workspaceRoot);
+  if (projectPath) {
+    switch (packageManager) {
+      case "pnpm":
+        return `pnpm --dir ${projectPath} build`;
+      case "yarn":
+        return `yarn --cwd ${projectPath} build`;
+      case "bun":
+        return `bun --cwd ${projectPath} run build`;
+      case "npm":
+        return `npm --prefix ${projectPath} run build`;
+      default:
+        return `cd ${projectPath} && npm run build`;
+    }
+  }
+  switch (packageManager) {
+    case "pnpm":
+      return "pnpm build";
+    case "yarn":
+      return "yarn build";
+    case "bun":
+      return "bun run build";
+    case "npm":
+      return "npm run build";
+    default:
+      return "npm run build";
+  }
+}
 function commandContextForProject(projectRoot) {
   const workspaceInfo = resolveWorkspaceInfo(projectRoot);
-  const relativeProjectPath = relative(workspaceInfo.workspaceRoot, projectRoot).replace(/\\/g, "/");
-  const projectPath = relativeProjectPath && !relativeProjectPath.startsWith("..") && !isAbsolute(relativeProjectPath) ? relativeProjectPath : null;
+  const relativeProjectPath = relative(workspaceInfo.workspaceRoot, projectRoot).replace(
+    /\\/g,
+    "/"
+  );
+  const projectPath = relativeProjectPath && !relativeProjectPath.startsWith("..") && !isAbsolute2(relativeProjectPath) ? relativeProjectPath : null;
   const projectFlag = projectPath ? ` --project ${projectPath}` : "";
   const essencePath = projectPath ? `${projectPath}/decantr.essence.json` : "decantr.essence.json";
   return {
     projectPath,
+    buildCommand: buildCommandForProject(workspaceInfo.workspaceRoot, projectPath),
     compilePacksCommand: `decantr registry compile-packs ${essencePath} --write-context`,
     verifyCommand: `decantr verify${projectFlag}`,
-    ciCommand: `decantr ci${projectFlag} --fail-on error`
+    ciCommand: `decantr ci${projectFlag} --fail-on error`,
+    promptCommand: (id) => `decantr health${projectFlag} --prompt ${id}`
   };
 }
 function rewriteHealthCommand(command, context) {
+  if (command === "npm run build") return context.buildCommand;
   let rewritten = command.replace(
     /decantr registry compile-packs decantr\.essence\.json --write-context/g,
     context.compilePacksCommand
@@ -403,8 +453,14 @@ function rewriteHealthCommand(command, context) {
     /^decantr init --existing\b/,
     `decantr init --project ${context.projectPath} --existing`
   );
-  rewritten = rewritten.replace(/^decantr analyze\b/, `decantr analyze --project ${context.projectPath}`);
-  rewritten = rewritten.replace(/^decantr check\b/, `decantr check --project ${context.projectPath}`);
+  rewritten = rewritten.replace(
+    /^decantr analyze\b/,
+    `decantr analyze --project ${context.projectPath}`
+  );
+  rewritten = rewritten.replace(
+    /^decantr check\b/,
+    `decantr check --project ${context.projectPath}`
+  );
   rewritten = rewritten.replace(/^decantr audit\b/, context.verifyCommand);
   rewritten = rewritten.replace(/^decantr health\b/, context.verifyCommand);
   return rewritten;
@@ -448,17 +504,25 @@ function scopeHealthFindingsToProject(projectRoot, findings) {
           message: finding.message,
           evidence: finding.evidence,
           suggestedFix,
-          commands
+          commands,
+          projectPath: context.projectPath
         })
       }
     };
   });
 }
 function buildRemediationPrompt(input) {
+  const prefix = input.projectPath ? `${input.projectPath}/` : "";
+  const readTargets = [
+    `${prefix}DECANTR.md`,
+    `${prefix}decantr.essence.json`,
+    `${prefix}.decantr/context/scaffold-pack.md`,
+    `${prefix}.decantr/context/scaffold.md`
+  ];
   return [
     "You are fixing one Decantr Project Health finding in this local workspace.",
     "",
-    "Read `DECANTR.md`, `decantr.essence.json`, and `.decantr/context/scaffold-pack.md` if they exist. For route or page work, read the matching page/section packs before editing.",
+    `Read project-scoped Decantr files if they exist: ${readTargets.map((target) => `\`${target}\``).join(", ")}. For route or page work, read the matching page/section packs before editing.`,
     "",
     `Finding: ${input.id}`,
     `Source: ${input.source}`,
@@ -509,6 +573,69 @@ function createHealthFinding(input) {
     remediation
   };
 }
+function collectContractPackConsistencyFindings(projectRoot, essence, manifest) {
+  if (!essence || typeof essence !== "object") return [];
+  const record = essence;
+  const blueprint = record.blueprint;
+  if (!blueprint || typeof blueprint !== "object") return [];
+  const bp = blueprint;
+  const routes = bp.routes && typeof bp.routes === "object" && !Array.isArray(bp.routes) ? bp.routes : {};
+  const routeTargets = new Set(
+    Object.values(routes).filter(
+      (entry) => Boolean(entry) && typeof entry === "object"
+    ).map((entry) => `${String(entry.section ?? "")}/${String(entry.page ?? "")}`)
+  );
+  const pages = [];
+  for (const section of Array.isArray(bp.sections) ? bp.sections : []) {
+    if (!section || typeof section !== "object") continue;
+    const sectionRecord = section;
+    const sectionId = typeof sectionRecord.id === "string" ? sectionRecord.id : "unknown";
+    for (const page of Array.isArray(sectionRecord.pages) ? sectionRecord.pages : []) {
+      if (!page || typeof page !== "object") continue;
+      const pageRecord = page;
+      const pageId = typeof pageRecord.id === "string" ? pageRecord.id : "unknown";
+      const route = typeof pageRecord.route === "string" ? pageRecord.route : null;
+      pages.push({ section: sectionId, page: pageId, route });
+    }
+  }
+  const findings = [];
+  const routeLess = pages.filter(
+    (page) => !page.route && !routeTargets.has(`${page.section}/${page.page}`)
+  );
+  if (routeLess.length > 0) {
+    findings.push(
+      createHealthFinding({
+        source: "assertion",
+        category: "Contract Route Topology",
+        severity: "error",
+        message: "One or more blueprint pages have no route and cannot be addressed by task-time context.",
+        evidence: routeLess.slice(0, 8).map(
+          (page) => `${page.section}/${page.page} has no page.route or blueprint.routes entry`
+        ),
+        rule: "page-route-required",
+        suggestedFix: "Add a route for each page or rerun the add-page flow with a route-aware Decantr CLI.",
+        baseId: "page-route-required"
+      })
+    );
+  }
+  const pagePackCount = manifest && "pages" in manifest && Array.isArray(manifest.pages) ? manifest.pages.length : 0;
+  if (manifest && pages.length !== pagePackCount) {
+    const context = commandContextForProject(projectRoot);
+    findings.push(
+      createHealthFinding({
+        source: "pack",
+        category: "Generated Artifacts",
+        severity: "warn",
+        message: `Compiled page pack count (${pagePackCount}) does not match the contract page count (${pages.length}).`,
+        evidence: ["Page packs should be regenerated after adding, removing, or re-routing pages."],
+        rule: "page-pack-count-mismatch",
+        suggestedFix: context.compilePacksCommand,
+        baseId: "page-pack-count-mismatch"
+      })
+    );
+  }
+  return findings;
+}
 function countFindings(findings) {
   return {
     errorCount: findings.filter((finding) => finding.severity === "error").length,
@@ -541,7 +668,7 @@ function isDuplicateFinding(existing, finding) {
 }
 function resolveOptionalPath(projectRoot, path) {
   if (!path) return void 0;
-  return isAbsolute(path) ? path : resolve2(projectRoot, path);
+  return isAbsolute2(path) ? path : resolve2(projectRoot, path);
 }
 function hasProjectPlaywright(projectRoot) {
   try {
@@ -758,7 +885,7 @@ function parseDecantrCssTokenNames(projectRoot) {
 function collectDesignTokenEvidence(projectRoot, designTokensPath) {
   const resolved = resolveOptionalPath(projectRoot, designTokensPath);
   if (!resolved) return void 0;
-  const sourceLabel = isAbsolute(designTokensPath ?? "") ? "<design-tokens>" : designTokensPath ?? "<design-tokens>";
+  const sourceLabel = isAbsolute2(designTokensPath ?? "") ? "<design-tokens>" : designTokensPath ?? "<design-tokens>";
   if (!existsSync2(resolved)) {
     return {
       source: sourceLabel,
@@ -1033,6 +1160,13 @@ async function createProjectHealthReport(projectRoot = process.cwd(), options =
   }
   const declaredRoutes = collectDeclaredRoutes(audit.essence);
   const manifest = audit.packManifest;
+  for (const consistencyFinding of collectContractPackConsistencyFindings(
+    projectRoot,
+    audit.essence,
+    manifest
+  )) {
+    if (!isDuplicateFinding(seen, consistencyFinding)) findings.push(consistencyFinding);
+  }
   const browserVerification = await collectBrowserVerification(
     projectRoot,
     options,
@@ -1092,6 +1226,7 @@ function colorForStatus(status) {
 }
 function formatProjectHealthText(report) {
   const color = colorForStatus(report.status);
+  const commandContext = commandContextForProject(report.projectRoot);
   const lines = [
     `${BOLD}Decantr Project Health${RESET}`,
     "",
@@ -1121,7 +1256,7 @@ function formatProjectHealthText(report) {
       if (finding.suggestedFix) {
         lines.push(`    ${DIM}Fix: ${finding.suggestedFix}${RESET}`);
       }
-      lines.push(`    ${DIM}Prompt: decantr health --prompt ${finding.id}${RESET}`);
+      lines.push(`    ${DIM}Prompt: ${commandContext.promptCommand(finding.id)}${RESET}`);
     }
   }
   lines.push("");
@@ -1130,6 +1265,7 @@ function formatProjectHealthText(report) {
 `;
 }
 function formatProjectHealthMarkdown(report) {
+  const commandContext = commandContextForProject(report.projectRoot);
   const lines = [
     "# Decantr Project Health",
     "",
@@ -1158,7 +1294,7 @@ function formatProjectHealthMarkdown(report) {
         lines.push("- Evidence:");
         for (const evidence of finding.evidence) lines.push(`  - ${evidence}`);
       }
-      lines.push(`- Prompt: \`decantr health --prompt ${finding.id}\``);
+      lines.push(`- Prompt: \`${commandContext.promptCommand(finding.id)}\``);
       lines.push("");
     }
   }
@@ -1252,17 +1388,25 @@ async function cmdHealth(projectRoot = process.cwd(), options = {}) {
   }
   const format = resolveFormat(options);
   const failOn = options.failOn ?? "error";
-  const basePayload = options.evidence ? `${JSON.stringify(await createProjectEvidenceBundle(projectRoot, report, reportOptions), null, 2)}
+  const evidenceBundle = options.evidence ? await createProjectEvidenceBundle(projectRoot, report, reportOptions) : null;
+  const basePayload = options.evidence ? `${JSON.stringify(evidenceBundle, null, 2)}
 ` : format === "json" ? formatProjectHealthJson(report) : format === "markdown" ? formatProjectHealthMarkdown(report) : formatProjectHealthText(report);
   const payload = baselineComparison && !options.evidence && format === "text" ? `${basePayload}${formatBaselineComparisonText(baselineComparison)}` : basePayload;
   if (options.output) {
-    const outputPath = isAbsolute(options.output) ? options.output : join2(projectRoot, options.output);
+    const outputPath = isAbsolute2(options.output) ? options.output : join2(projectRoot, options.output);
     mkdirSync(dirname2(outputPath), { recursive: true });
     writeFileSync(outputPath, payload, "utf-8");
     if (!options.ci) {
       console.log(
         `${GREEN}Wrote Decantr ${options.evidence ? "evidence bundle" : "health report"}:${RESET} ${options.output}`
       );
+      if (options.browser && evidenceBundle?.browser?.status === "unavailable") {
+        const reason = evidenceBundle.browser.findings[0] ?? "Playwright is not available to Decantr in this project.";
+        console.log(`${YELLOW}Browser evidence unavailable:${RESET} ${reason}`);
+        console.log(
+          `${DIM}Static evidence was still written. Install Playwright or rerun without --browser if screenshots are not needed.${RESET}`
+        );
+      }
     }
   } else {
     process.stdout.write(payload);