@decantr/cli 2.9.1 → 2.9.3

package/README.md

@@ -19,11 +19,13 @@ 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 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
 ```
@@ -138,7 +142,7 @@ decantr showcase verification --json
 
 `decantr doctor` explains project/workspace state, adoption mode, generated artifacts, local law, visual evidence, design authority signals, CI wiring, and the next command to run. It is the command to reach for when an app is in a monorepo, has stale Decantr files, or someone is not sure what Decantr expects next.
 
-`decantr ci` is the blessed non-mutating automation gate. It runs the Project Health surface with adoption-mode-aware local law checks and emits a schema-backed CI report. `decantr ci init` writes root GitHub workflows or portable generic snippets using the detected package manager and pinned local CLI command instead of `@latest`.
+`decantr ci` is the blessed non-mutating automation gate. It runs the Project Health surface with adoption-mode-aware local law checks and emits a schema-backed CI report. `decantr ci init` writes root GitHub workflows or portable generic snippets using the detected package manager and pinned local CLI command instead of `@latest`; if the root manifest has not pinned Decantr yet, it prints the exact install command first.
 
 `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.
 
@@ -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,9 +176,9 @@ 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>` 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`.
+`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:
 

package/dist/bin.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import "./chunk-6UDJDQPT.js";
+import "./chunk-VMNUJOEH.js";
 import "./chunk-RXF7ZYGK.js";
-import "./chunk-FKM4OQDF.js";
-import "./chunk-TMOCTDYY.js";
+import "./chunk-ARR3EPS2.js";
+import "./chunk-XZFKK6V7.js";
 import "./chunk-34TZXWIF.js";

package/dist/{chunk-FKM4OQDF.js → chunk-ARR3EPS2.js}

@@ -1,101 +1,12 @@
 import {
-  createProjectHealthReport
-} from "./chunk-TMOCTDYY.js";
+  createProjectHealthReport,
+  listWorkspaceAppCandidates
+} from "./chunk-XZFKK6V7.js";
 
 // src/commands/workspace.ts
 import { execFileSync } from "child_process";
-import { existsSync as existsSync2, mkdirSync, readdirSync as readdirSync2, readFileSync as readFileSync2, writeFileSync } from "fs";
-import { dirname as dirname2, join as join2, relative, resolve as resolve2 } from "path";
-
-// src/workspace.ts
-import { existsSync, readdirSync, readFileSync } from "fs";
-import { dirname, join, resolve } from "path";
-function readPackageJson(dir) {
-  const path = join(dir, "package.json");
-  if (!existsSync(path)) return null;
-  try {
-    return JSON.parse(readFileSync(path, "utf-8"));
-  } catch {
-    return null;
-  }
-}
-function hasWorkspaceMarker(dir) {
-  if (existsSync(join(dir, "pnpm-workspace.yaml")) || existsSync(join(dir, "turbo.json")) || existsSync(join(dir, "nx.json"))) {
-    return true;
-  }
-  const pkg = readPackageJson(dir);
-  return Boolean(pkg?.workspaces);
-}
-function findWorkspaceRoot(startDir) {
-  let current = resolve(startDir);
-  while (true) {
-    if (hasWorkspaceMarker(current)) return current;
-    const parent = dirname(current);
-    if (parent === current) return null;
-    current = parent;
-  }
-}
-function looksLikeApp(dir, options = {}) {
-  const allowSourceDirs = options.allowSourceDirs ?? true;
-  const allowPackageDeps = options.allowPackageDeps ?? true;
-  const pkg = readPackageJson(dir);
-  const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
-  const hasFrontendDependency = Boolean(
-    deps.react || deps["react-dom"] || deps.next || deps.vue || deps.svelte || deps["@angular/core"] || deps.astro || deps.nuxt
-  );
-  const hasServerOnlyDependency = Boolean(
-    deps.hono || deps.express || deps.fastify || deps.koa || deps["@hapi/hapi"]
-  );
-  if (existsSync(join(dir, "next.config.js")) || existsSync(join(dir, "next.config.ts")) || existsSync(join(dir, "next.config.mjs")) || existsSync(join(dir, "vite.config.ts")) || existsSync(join(dir, "vite.config.js")) || existsSync(join(dir, "angular.json")) || existsSync(join(dir, "svelte.config.js")) || existsSync(join(dir, "svelte.config.ts")) || existsSync(join(dir, "astro.config.mjs"))) {
-    return true;
-  }
-  if (allowSourceDirs && (existsSync(join(dir, "src")) || existsSync(join(dir, "app")) || existsSync(join(dir, "pages")))) {
-    if (hasFrontendDependency) return true;
-    if (hasServerOnlyDependency) return false;
-    return true;
-  }
-  if (!allowPackageDeps) return false;
-  return hasFrontendDependency;
-}
-function listWorkspaceApps(workspaceRoot) {
-  const candidates = [];
-  for (const base of ["apps", "packages"]) {
-    const baseDir = join(workspaceRoot, base);
-    if (!existsSync(baseDir)) continue;
-    for (const entry of readdirSync(baseDir, { withFileTypes: true })) {
-      if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
-      const candidate = join(baseDir, entry.name);
-      if (looksLikeApp(candidate, {
-        allowSourceDirs: base === "apps",
-        allowPackageDeps: base === "apps"
-      })) {
-        candidates.push(`${base}/${entry.name}`);
-      }
-    }
-  }
-  return candidates.sort();
-}
-function listWorkspaceAppCandidates(workspaceRoot) {
-  return listWorkspaceApps(resolve(workspaceRoot));
-}
-function resolveWorkspaceInfo(cwd, projectArg) {
-  const absoluteCwd = resolve(cwd);
-  const workspaceRoot = findWorkspaceRoot(absoluteCwd) ?? absoluteCwd;
-  const appRoot = projectArg ? resolve(absoluteCwd, 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;
-  return {
-    cwd: absoluteCwd,
-    workspaceRoot,
-    appRoot,
-    projectScope,
-    appCandidates,
-    requiresProjectSelection
-  };
-}
-
-// src/commands/workspace.ts
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join, relative, resolve } from "path";
 var BOLD = "\x1B[1m";
 var DIM = "\x1B[2m";
 var GREEN = "\x1B[32m";
@@ -114,12 +25,12 @@ var DEFAULT_IGNORES = /* @__PURE__ */ new Set([
   "playwright-report"
 ]);
 function workspaceConfigPath(root) {
-  return join2(root, ".decantr", "workspace.json");
+  return join(root, ".decantr", "workspace.json");
 }
 function readWorkspaceConfig(root) {
   const path = workspaceConfigPath(root);
-  if (!existsSync2(path)) return null;
-  return JSON.parse(readFileSync2(path, "utf-8"));
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, "utf-8"));
 }
 function normalizeProjectPath(raw) {
   const normalized = raw.replace(/^\.\/+/, "").replace(/\/+$/, "");
@@ -138,21 +49,21 @@ function discoverProjectPaths(root, config) {
     if (depth > 6) return;
     const rel = relative(root, dir).replace(/\\/g, "/");
     if (rel && [...ignored].some((entry) => rel === entry || rel.startsWith(`${entry}/`))) return;
-    if (existsSync2(join2(dir, "decantr.essence.json"))) {
+    if (existsSync(join(dir, "decantr.essence.json"))) {
       results.add(rel || ".");
       return;
     }
-    for (const entry of readdirSync2(dir, { withFileTypes: true })) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
       if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
       if (ignored.has(entry.name)) continue;
-      walk(join2(dir, entry.name), depth + 1);
+      walk(join(dir, entry.name), depth + 1);
     }
   }
   walk(root, 0);
   return [...results].sort();
 }
 function listWorkspaceProjects(root = process.cwd()) {
-  const workspaceRoot = resolve2(root);
+  const workspaceRoot = resolve(root);
   const config = readWorkspaceConfig(workspaceRoot);
   const byPath = /* @__PURE__ */ new Map();
   for (const project of config?.projects ?? []) {
@@ -160,7 +71,7 @@ function listWorkspaceProjects(root = process.cwd()) {
     byPath.set(path, {
       id: project.id ?? projectIdFromPath(path),
       path,
-      absolutePath: resolve2(workspaceRoot, path),
+      absolutePath: resolve(workspaceRoot, path),
       owner: project.owner ?? null,
       tags: project.tags ?? [],
       criticality: project.criticality ?? "normal",
@@ -173,7 +84,7 @@ function listWorkspaceProjects(root = process.cwd()) {
     byPath.set(path, {
       id: projectIdFromPath(path),
       path,
-      absolutePath: resolve2(workspaceRoot, path),
+      absolutePath: resolve(workspaceRoot, path),
       owner: null,
       tags: [],
       criticality: "normal",
@@ -240,7 +151,7 @@ async function mapLimited(items, concurrency, fn) {
   return results;
 }
 async function createWorkspaceHealthReport(root = process.cwd(), options = {}) {
-  const workspaceRoot = resolve2(root);
+  const workspaceRoot = resolve(root);
   const config = readWorkspaceConfig(workspaceRoot);
   const since = options.since ?? "origin/main";
   const changed = options.changedOnly ? changedPaths(workspaceRoot, since) : /* @__PURE__ */ new Set();
@@ -420,8 +331,8 @@ async function cmdWorkspace(workspaceRoot = process.cwd(), args = ["workspace"])
   const payload = options.json ? `${JSON.stringify(report, null, 2)}
 ` : options.markdown ? formatWorkspaceHealthMarkdown(report) : formatWorkspaceHealthText(report);
   if (options.output) {
-    mkdirSync(dirname2(resolve2(workspaceRoot, options.output)), { recursive: true });
-    writeFileSync(resolve2(workspaceRoot, options.output), payload, "utf-8");
+    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}`);
   } else {
@@ -433,7 +344,6 @@ async function cmdWorkspace(workspaceRoot = process.cwd(), args = ["workspace"])
 }
 
 export {
-  resolveWorkspaceInfo,
   listWorkspaceProjects,
   listWorkspaceCandidates,
   createWorkspaceHealthReport,