@decantr/cli 2.7.0 → 2.8.1

package/README.md

@@ -20,7 +20,7 @@ npx @decantr/cli new my-app --blueprint=esports-hq
 Use `decantr setup` when you are unsure which path applies. It detects whether the repo is empty, already attached, or a Brownfield app and recommends the next command.
 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, and only applies it when you explicitly accept or merge it.
-Use `decantr task` before asking an LLM to modify a route, and `decantr verify` after the edit. Use `decantr codify` when you want project-owned UI patterns such as local button/card/shell standards to appear in future task context.
+Use `decantr task` before asking an LLM to modify a route, and `decantr verify` after the edit. 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.
 Use `decantr init`, `decantr analyze`, `decantr check`, and `decantr health` as advanced primitives when you need direct control over one step.
 
 Current starter adapter availability:
@@ -38,11 +38,11 @@ Explicit workflow/adoption flags:
 
 ```bash
 decantr setup
-decantr adopt --base-url http://localhost:3000 --evidence --yes
-decantr task /feed "add saved recipe actions"
-decantr verify --brownfield
-decantr codify
+decantr adopt --yes
+decantr codify --from-audit
 decantr codify --accept
+decantr task /feed "add saved recipe actions"
+decantr verify --brownfield --local-patterns
 decantr init --workflow=greenfield --adoption=contract-only
 decantr analyze
 decantr init --existing --accept-proposal
@@ -61,11 +61,18 @@ Adoption modes:
 - `style-bridge` writes bridge tokens/files that map Decantr intent onto an existing style system without requiring `@decantr/css`.
 - `decantr-css` writes the full Decantr CSS files and runtime guidance.
 
-Monorepos store both `workspaceRoot` and `appRoot`. In non-interactive workspace-root runs with multiple app candidates, pass `--project=<path>` so Decantr attaches to the intended app.
+Monorepos store both `workspaceRoot` and `appRoot`. Install Decantr at the workspace root if that is where dependencies are managed, but attach Decantr to an app root with `--project=<path>`.
+
+```bash
+pnpm add -D -w @decantr/cli
+pnpm exec decantr setup
+pnpm exec decantr workspace list
+pnpm exec decantr adopt --project apps/web --yes
+```
 
 Assistant rule integration is preview-first: `--assistant-bridge=preview` writes `.decantr/context/assistant-bridge.md`, `decantr rules preview` prints the bridge, and `--assistant-bridge=apply` or `decantr rules apply` mutates supported rule files with idempotent marked blocks.
 
-Brownfield analysis also writes `.decantr/doctrine-map.json`, a ranked source-precedence map across security/data, architecture, design-system, workflow/CI, feature/business, assistant-specific, stale, and unsafe-to-cite evidence. It also writes `.decantr/brownfield-intelligence.json`, `.decantr/theme-inventory.json`, and `.decantr/enrichment-backlog.md`. The proposal groups routes into observed semantic domains such as auth, RBAC, billing, reporting, facilities, settings, and public surfaces across Next App/Pages Router, React Router, Angular Router, SvelteKit, Vue Router, and Nuxt file routes. Existing styling systems such as Tailwind, Bootstrap, MUI, Chakra, plain CSS, and Decantr CSS are observed as evidence instead of replaced. Theme variants are observed in the theme inventory without changing Essence V4. `decantr verify --brownfield` uses the Brownfield guard layer to flag actionable missing doctrine coverage, unsafe context, missing assistant bridges, style drift, and unsafe defaults without treating current database migrations as stale docs.
+Brownfield analysis also writes `.decantr/doctrine-map.json`, a ranked source-precedence map across security/data, architecture, design-system, workflow/CI, feature/business, assistant-specific, stale, and unsafe-to-cite evidence. It also writes `.decantr/brownfield-intelligence.json`, `.decantr/theme-inventory.json`, and `.decantr/enrichment-backlog.md`. The proposal groups routes into observed semantic domains such as auth, RBAC, billing, reporting, facilities, settings, and public surfaces across Next App/Pages Router, React Router, Angular Router, SvelteKit, Vue Router, and Nuxt file routes. Existing styling systems such as Tailwind, Bootstrap, MUI, Chakra, plain CSS, and Decantr CSS are observed as evidence instead of replaced. Theme variants are observed in the theme inventory without changing Essence V4. `decantr codify --from-audit` proposes `.decantr/local-patterns.proposal.json` and `.decantr/rules.proposal.json`; after review, `decantr codify --accept` promotes `.decantr/local-patterns.json` and `.decantr/rules.json`. `decantr verify --brownfield --local-patterns` uses the Brownfield guard layer plus accepted local law to flag actionable missing doctrine coverage, unsafe context, missing assistant bridges, style drift, raw local-rule violations, and unsafe defaults without treating current database migrations as stale docs.
 
 ## What It Does
 
@@ -86,10 +93,13 @@ Brownfield analysis also writes `.decantr/doctrine-map.json`, a ranked source-pr
 ```bash
 decantr setup
 decantr new my-app --blueprint=esports-hq
-decantr adopt --base-url http://localhost:3000 --evidence --yes
+decantr adopt --yes
+decantr adopt --project apps/web --yes
+decantr codify --from-audit
+decantr codify --accept
 decantr task /feed "add saved recipe actions"
 decantr verify --brownfield --local-patterns
-decantr codify
+decantr verify --base-url http://localhost:3000 --evidence
 decantr init --existing --blueprint=esports-hq
 decantr init --workflow=greenfield --adoption=contract-only
 decantr rules preview
@@ -114,13 +124,14 @@ decantr showcase verification --json
 
 ## Project Health And Studio
 
-`decantr verify` is the workflow command most users should run locally and in CI. It delegates to Project Health, can add Brownfield guard validation with `--brownfield`, requires an accepted local pattern pack with `--local-patterns`, supports workspace mode, and writes evidence to `.decantr/evidence/latest.json` by default when `--evidence` is used.
+`decantr verify` is the workflow command most users should run locally and in CI. It delegates to Project Health, can add Brownfield guard validation with `--brownfield`, requires an accepted local pattern pack with `--local-patterns`, scans `.decantr/rules.json` when present, supports workspace mode, and writes evidence to `.decantr/evidence/latest.json` by default when `--evidence` is used.
 
 `decantr health` remains the advanced project observability primitive. It composes the existing verifier audit, guard checks, brownfield route drift checks, runtime evidence, and execution-pack files into a `ProjectHealthReport` with a status, score, route summary, pack summary, findings, and AI-ready remediation prompts.
 
 ```bash
 decantr verify
 decantr verify --brownfield --local-patterns
+decantr verify --brownfield --local-patterns --fail-on warn
 decantr verify --base-url http://localhost:3000 --evidence
 decantr verify --since-baseline
 decantr verify init-ci --project apps/registry
@@ -149,7 +160,7 @@ Use `--json` for machines and schema validation, `--markdown` for CI summaries,
 
 `decantr verify init-ci` installs `.github/workflows/decantr-health.yml` for GitHub Actions. The generated workflow installs project dependencies, writes JSON/markdown health artifacts, gates with the Project Health CI command, 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. Use `--workspace` to generate an aggregate gate that runs `decantr workspace health` from the repository root and uploads `.decantr/workspace-health.json` plus `.decantr/workspace-health.md`.
 
-`decantr workspace` is the monorepo reliability namespace. It discovers Decantr projects from `.decantr/workspace.json` or by finding `decantr.essence.json` files, 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. 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,4 +1,5 @@
 #!/usr/bin/env node
-import "./chunk-ZYHR3BGT.js";
+import "./chunk-RKZMHS2K.js";
 import "./chunk-V3XAQWKD.js";
+import "./chunk-VE6N3XWG.js";
 import "./chunk-KT2ROK2D.js";

package/dist/{chunk-ICSLIYSX.js → chunk-FV6DGYD7.js}

@@ -1,3 +1,6 @@
+import {
+  listWorkspaceAppCandidates
+} from "./chunk-VE6N3XWG.js";
 import {
   createProjectHealthReport
 } from "./chunk-PAF4PBD3.js";
@@ -93,6 +96,14 @@ function listWorkspaceProjects(root = process.cwd()) {
   }
   return [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path));
 }
+function listWorkspaceCandidates(root = process.cwd(), projects = listWorkspaceProjects(root)) {
+  const attached = new Set(projects.map((project) => project.path));
+  return listWorkspaceAppCandidates(root).map((path) => ({
+    path,
+    attached: attached.has(path),
+    suggestedAdoptCommand: `decantr adopt --project ${path} --yes`
+  }));
+}
 function changedPaths(root, since) {
   try {
     const output = execFileSync("git", ["diff", "--name-only", since, "--"], {
@@ -100,7 +111,9 @@ function changedPaths(root, since) {
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "ignore"]
     });
-    return new Set(output.split("\n").map((line) => line.trim()).filter(Boolean));
+    return new Set(
+      output.split("\n").map((line) => line.trim()).filter(Boolean)
+    );
   } catch {
     return /* @__PURE__ */ new Set();
   }
@@ -116,7 +129,10 @@ function projectChanged(project, changed) {
 async function withTimeout(promise, timeoutMs, label) {
   let timeout;
   const timer = new Promise((_, reject) => {
-    timeout = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+    timeout = setTimeout(
+      () => reject(new Error(`${label} timed out after ${timeoutMs}ms`)),
+      timeoutMs
+    );
   });
   try {
     return await Promise.race([promise, timer]);
@@ -265,9 +281,11 @@ function parseWorkspaceArgs(args) {
     else if (arg.startsWith("--since=")) options.since = arg.split("=")[1];
     else if (arg === "--output" && args[index + 1]) options.output = args[++index];
     else if (arg.startsWith("--output=")) options.output = arg.split("=")[1];
-    else if (arg === "--fail-on" && args[index + 1]) options.failOn = parseHealthFailOn(args[++index]);
+    else if (arg === "--fail-on" && args[index + 1])
+      options.failOn = parseHealthFailOn(args[++index]);
     else if (arg.startsWith("--fail-on=")) options.failOn = parseHealthFailOn(arg.split("=")[1]);
-    else if (arg === "--concurrency" && args[index + 1]) options.concurrency = Number(args[++index]);
+    else if (arg === "--concurrency" && args[index + 1])
+      options.concurrency = Number(args[++index]);
     else if (arg.startsWith("--concurrency=")) options.concurrency = Number(arg.split("=")[1]);
     else if (arg === "--timeout-ms" && args[index + 1]) options.timeoutMs = Number(args[++index]);
     else if (arg.startsWith("--timeout-ms=")) options.timeoutMs = Number(arg.split("=")[1]);
@@ -278,15 +296,36 @@ async function cmdWorkspace(workspaceRoot = process.cwd(), args = ["workspace"])
   const options = parseWorkspaceArgs(args);
   if (options.subcommand === "list") {
     const projects = listWorkspaceProjects(workspaceRoot);
-    const payload2 = `${JSON.stringify({ projects }, null, 2)}
+    const candidates = listWorkspaceCandidates(workspaceRoot, projects);
+    const unattachedCandidates = candidates.filter((candidate) => !candidate.attached);
+    const payload2 = `${JSON.stringify({ projects, candidates }, null, 2)}
 `;
     if (options.json) {
       process.stdout.write(payload2);
       return;
     }
     console.log(`${BOLD}Decantr workspace projects${RESET}`);
-    for (const project of projects) {
-      console.log(`${project.path} ${DIM}${project.source}${RESET}`);
+    console.log("");
+    console.log("Attached Decantr projects:");
+    if (projects.length === 0) {
+      console.log(`  ${DIM}(none yet)${RESET}`);
+    } else {
+      for (const project of projects) {
+        console.log(`  ${project.path} ${DIM}${project.source}${RESET}`);
+      }
+    }
+    if (candidates.length > 0) {
+      console.log("");
+      console.log("App candidates:");
+      for (const candidate of candidates) {
+        const status = candidate.attached ? `${GREEN}attached${RESET}` : `${YELLOW}unattached${RESET}`;
+        console.log(`  ${candidate.path} ${DIM}${status}${RESET}`);
+      }
+    }
+    if (unattachedCandidates.length > 0) {
+      console.log("");
+      console.log("Start by attaching one app:");
+      console.log(`  ${unattachedCandidates[0].suggestedAdoptCommand}`);
     }
     return;
   }
@@ -296,7 +335,8 @@ async function cmdWorkspace(workspaceRoot = process.cwd(), args = ["workspace"])
   if (options.output) {
     mkdirSync(dirname(resolve(workspaceRoot, options.output)), { recursive: true });
     writeFileSync(resolve(workspaceRoot, options.output), payload, "utf-8");
-    if (!options.ci) console.log(`${GREEN}Wrote Decantr workspace health:${RESET} ${options.output}`);
+    if (!options.ci)
+      console.log(`${GREEN}Wrote Decantr workspace health:${RESET} ${options.output}`);
   } else {
     process.stdout.write(payload);
   }
@@ -307,6 +347,7 @@ async function cmdWorkspace(workspaceRoot = process.cwd(), args = ["workspace"])
 
 export {
   listWorkspaceProjects,
+  listWorkspaceCandidates,
   createWorkspaceHealthReport,
   formatWorkspaceHealthText,
   formatWorkspaceHealthMarkdown,