@decantr/cli 2.3.0 → 2.4.0

package/README.md

@@ -23,8 +23,13 @@ Use `decantr init` to attach Decantr contract/context files to an existing proje
 
 Current starter adapter availability:
 
-- `react-vite` is the runnable bootstrap adapter in this wave
+- `react-vite` is the React + Vite runnable bootstrap adapter
 - `next-app` is the runnable Next.js App Router adapter
+- `vanilla-vite` is the plain HTML/CSS/JS runnable bootstrap adapter
+- `vue-vite` is the Vue 3 + Vite runnable bootstrap adapter
+- `sveltekit` is the SvelteKit runnable bootstrap adapter
+- `angular` is the Angular standalone runnable bootstrap adapter
+- `solid-vite` is the Solid + Vite runnable bootstrap adapter
 - other contract targets use the `generic-web` contract-only adapter until their runnable adapters land
 
 Explicit workflow/adoption flags:
@@ -60,9 +65,10 @@ Brownfield analysis also writes `.decantr/doctrine-map.json`, a ranked source-pr
 - supports explicit workflow lanes: greenfield blueprint, greenfield contract-only, brownfield adoption, and hybrid composition
 - generates execution-pack context files for AI coding assistants
 - audits projects against Decantr contracts
-- produces local Project Health reports and a localhost Studio dashboard for end-user drift triage
+- produces local Project Health reports, Evidence Bundles, workspace health, and a localhost Studio dashboard for end-user drift triage
 - audits local registry content repositories with Content Health reports for schema, reference, and quality coverage
 - searches the registry and showcase benchmark corpus
+- syncs paginated hosted registry content into a full slug-keyed local cache for offline guards and context generation
 - validates, refreshes, and maintains `decantr.essence.json`
 
 ## Common Commands
@@ -82,6 +88,7 @@ decantr check
 decantr health --ci --fail-on error
 decantr studio --port 4319 --host 127.0.0.1
 decantr telemetry status
+decantr telemetry explain
 decantr telemetry link --enable --org <org-slug>
 decantr content-health --ci --fail-on error
 decantr registry summary --namespace @official --json
@@ -99,15 +106,31 @@ decantr health --markdown --output health.md
 decantr health --ci --fail-on error
 decantr health --ci --fail-on warn
 decantr health --prompt <finding-id>
+decantr health --evidence --output .decantr/evidence/latest.json
+decantr health --browser --base-url http://localhost:3000 --evidence
+decantr health --design-tokens .decantr/design/figma-tokens.json
 decantr health --json --output decantr-health.json
 decantr health init-ci
 decantr health init-ci --fail-on warn --cli-version latest --force
 decantr health init-ci --project apps/registry
+decantr health init-ci --workspace
+decantr workspace list
+decantr workspace health --changed --since origin/main
+decantr export --to figma-tokens
 ```
 
-Use `--json` for machines and schema validation, `--markdown` for CI summaries, 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. `--ci --fail-on error` fails only when blocking errors exist; `--ci --fail-on warn` also fails on warnings.
+Use `--json` for machines and schema validation, `--markdown` for CI 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/`; missing Playwright becomes a setup finding, not a crash. `--design-tokens <path>` compares a Tokens Studio/Figma token JSON export against Decantr CSS token names. `--ci --fail-on error` fails only when blocking errors exist; `--ci --fail-on warn` also fails on warnings.
 
-`decantr health init-ci` installs `.github/workflows/decantr-health.yml` for GitHub Actions. The generated workflow installs project dependencies, writes `decantr-health.json`, gates with `decantr health --ci --fail-on error --markdown --output decantr-health.md`, 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.
+`decantr health init-ci` installs `.github/workflows/decantr-health.yml` for GitHub Actions. The generated workflow installs project dependencies, writes JSON/markdown health artifacts, gates with `decantr health --ci --fail-on error --markdown --output decantr-health.md`, 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:
+
+```bash
+decantr workspace list
+decantr workspace health
+decantr workspace health --json --output .decantr/workspace-health.json
+decantr workspace health --changed --since origin/main
+```
 
 `decantr studio` starts a local-only dashboard powered by the same report. It uses Node built-ins only and serves `GET /`, `GET /api/health`, and `POST /api/refresh`.
 
@@ -115,10 +138,13 @@ Use `--json` for machines and schema validation, `--markdown` for CI summaries,
 decantr studio
 decantr studio --port 4319 --host 127.0.0.1
 decantr studio --report decantr-health.json
+decantr studio --workspace
 ```
 
 Studio is for local triage, not Decantr admin telemetry. The Overview keeps the first decision simple: pick the issue to fix first, review the full AI repair prompt before copying it, switch to manual guidance or commands, and expand project details when route/runtime/pack evidence matters. The tabs cover Overview, Routes, Drift, Findings, Remediation, CI, and Packs without uploading source code, prompts, file paths, or project data.
 
+Workspace Studio uses `decantr workspace health` behind `GET /api/workspace` and `POST /api/workspace/refresh` so large monorepos can triage many Decantr projects from one local dashboard.
+
 Use report mode for customer-controlled reporting from CI artifacts:
 
 ```bash
@@ -135,12 +161,16 @@ If the project has explicitly enabled Decantr CLI telemetry, `new --telemetry`,
 ```bash
 decantr telemetry status
 decantr telemetry status --json
+decantr telemetry explain
+decantr telemetry explain --json
 decantr login --api-key=<key>
 decantr telemetry link --enable --org <org-slug>
 ```
 
 `telemetry link` calls the hosted `/v1/me/telemetry-link` endpoint with only opaque ids, optional org slug, and optional label. The API verifies org membership, writes `telemetry_identity_aliases`, clears the actor-resolution cache, audit logs the change, and emits `telemetry.identity_linked`.
 
+`telemetry explain` prints the CLI event catalog subset, aggregate field categories, current opaque ids if they already exist, and the explicit never-collected list. It is designed for security review and customer trust conversations before a team opts in.
+
 ## Content Health
 
 `decantr content-health` is the local supply-chain observability command for registry content repositories such as `decantr-content`. It is separate from Project Health: Project Health checks an end-user app against its Decantr contract, while Content Health checks published content inputs before they flow into the hosted registry.
@@ -185,6 +215,8 @@ DECANTR_CONTENT_DIR=/path/to/decantr-content decantr new my-app --blueprint=agen
 
 If a requested offline blueprint, archetype, or theme cannot be resolved from local cache/custom content or `DECANTR_CONTENT_DIR`, the CLI now stops explicitly instead of silently falling back to the default scaffold.
 
+Run `decantr sync` before offline-heavy or CI-heavy workflows that depend on hosted registry content. Sync paginates the official registry list endpoints, then fetches and stores each item by slug as a full content record under `.decantr/cache/@official/`. That keeps guard checks, Project Health, and context generation aligned with the canonical registry contract instead of abbreviated public list summaries.
+
 ## Workflow Certification
 
 The broader workflow matrix now has its own certification entrypoint:

package/dist/bin.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import "./chunk-FSZ6OIAC.js";
-import "./chunk-WDA4SHIQ.js";
+import "./chunk-H6TIXG5K.js";
+import "./chunk-PEGMSXDJ.js";
 import "./chunk-IEW2QFYI.js";

package/dist/chunk-AUQXYJ7T.js

@@ -0,0 +1,316 @@
+import {
+  createProjectHealthReport
+} from "./chunk-OD46PCR6.js";
+
+// src/commands/workspace.ts
+import { execFileSync } from "child_process";
+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";
+var RED = "\x1B[31m";
+var YELLOW = "\x1B[33m";
+var RESET = "\x1B[0m";
+var WORKSPACE_HEALTH_SCHEMA_URL = "https://decantr.ai/schemas/workspace-health-report.v1.json";
+var DEFAULT_IGNORES = /* @__PURE__ */ new Set([
+  ".git",
+  ".next",
+  ".turbo",
+  ".vercel",
+  "coverage",
+  "dist",
+  "node_modules",
+  "playwright-report"
+]);
+function workspaceConfigPath(root) {
+  return join(root, ".decantr", "workspace.json");
+}
+function readWorkspaceConfig(root) {
+  const path = workspaceConfigPath(root);
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, "utf-8"));
+}
+function normalizeProjectPath(raw) {
+  const normalized = raw.replace(/^\.\/+/, "").replace(/\/+$/, "");
+  if (!normalized || normalized.startsWith("/") || normalized.includes("..") || normalized.includes("\\") || /\s/.test(normalized)) {
+    throw new Error(`Invalid workspace project path: ${raw}`);
+  }
+  return normalized;
+}
+function projectIdFromPath(path) {
+  return path.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "project";
+}
+function discoverProjectPaths(root, config) {
+  const ignored = /* @__PURE__ */ new Set([...config?.ignore ?? [], ...DEFAULT_IGNORES]);
+  const results = /* @__PURE__ */ new Set();
+  function walk(dir, depth) {
+    if (depth > 6) return;
+    const rel = relative(root, dir).replace(/\\/g, "/");
+    if (rel && [...ignored].some((entry) => rel === entry || rel.startsWith(`${entry}/`))) return;
+    if (existsSync(join(dir, "decantr.essence.json"))) {
+      results.add(rel || ".");
+      return;
+    }
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+      if (ignored.has(entry.name)) continue;
+      walk(join(dir, entry.name), depth + 1);
+    }
+  }
+  walk(root, 0);
+  return [...results].sort();
+}
+function listWorkspaceProjects(root = process.cwd()) {
+  const workspaceRoot = resolve(root);
+  const config = readWorkspaceConfig(workspaceRoot);
+  const byPath = /* @__PURE__ */ new Map();
+  for (const project of config?.projects ?? []) {
+    const path = normalizeProjectPath(project.path);
+    byPath.set(path, {
+      id: project.id ?? projectIdFromPath(path),
+      path,
+      absolutePath: resolve(workspaceRoot, path),
+      owner: project.owner ?? null,
+      tags: project.tags ?? [],
+      criticality: project.criticality ?? "normal",
+      browser: project.browser ?? config?.browser ?? false,
+      source: "manifest"
+    });
+  }
+  for (const path of discoverProjectPaths(workspaceRoot, config)) {
+    if (byPath.has(path)) continue;
+    byPath.set(path, {
+      id: projectIdFromPath(path),
+      path,
+      absolutePath: resolve(workspaceRoot, path),
+      owner: null,
+      tags: [],
+      criticality: "normal",
+      browser: config?.browser ?? false,
+      source: "auto"
+    });
+  }
+  return [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+function changedPaths(root, since) {
+  try {
+    const output = execFileSync("git", ["diff", "--name-only", since, "--"], {
+      cwd: root,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    return new Set(output.split("\n").map((line) => line.trim()).filter(Boolean));
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+}
+function projectChanged(project, changed) {
+  if (changed.size === 0) return false;
+  const prefix = project.path === "." ? "" : `${project.path}/`;
+  for (const path of changed) {
+    if (project.path === "." || path === project.path || path.startsWith(prefix)) return true;
+  }
+  return false;
+}
+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);
+  });
+  try {
+    return await Promise.race([promise, timer]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+async function mapLimited(items, concurrency, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+  async function worker() {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await fn(items[index]);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.max(1, concurrency) }, () => worker()));
+  return results;
+}
+async function createWorkspaceHealthReport(root = process.cwd(), options = {}) {
+  const workspaceRoot = resolve(root);
+  const config = readWorkspaceConfig(workspaceRoot);
+  const since = options.since ?? "origin/main";
+  const changed = options.changedOnly ? changedPaths(workspaceRoot, since) : /* @__PURE__ */ new Set();
+  const allProjects = listWorkspaceProjects(workspaceRoot);
+  const projects = options.changedOnly ? allProjects.filter((project) => projectChanged(project, changed)) : allProjects;
+  const concurrency = options.concurrency ?? config?.concurrency ?? 4;
+  const timeoutMs = options.timeoutMs ?? config?.timeoutMs ?? 12e4;
+  const checked = await mapLimited(projects, concurrency, async (project) => {
+    const startedAt = Date.now();
+    try {
+      const report = await withTimeout(
+        createProjectHealthReport(project.absolutePath, {
+          browser: options.browser ?? project.browser
+        }),
+        timeoutMs,
+        project.path
+      );
+      return {
+        id: project.id,
+        path: project.path,
+        status: report.status,
+        score: report.score,
+        errorCount: report.summary.errorCount,
+        warnCount: report.summary.warnCount,
+        infoCount: report.summary.infoCount,
+        findingCount: report.summary.findingCount,
+        durationMs: Date.now() - startedAt,
+        changed: options.changedOnly ? projectChanged(project, changed) : false,
+        source: project.source,
+        error: null
+      };
+    } catch (error) {
+      return {
+        id: project.id,
+        path: project.path,
+        status: "failed",
+        score: 0,
+        errorCount: 1,
+        warnCount: 0,
+        infoCount: 0,
+        findingCount: 1,
+        durationMs: Date.now() - startedAt,
+        changed: options.changedOnly ? projectChanged(project, changed) : false,
+        source: project.source,
+        error: error.message
+      };
+    }
+  });
+  return {
+    $schema: WORKSPACE_HEALTH_SCHEMA_URL,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    workspaceRoot,
+    changedOnly: options.changedOnly ?? false,
+    since: options.changedOnly ? since : null,
+    summary: {
+      projectCount: allProjects.length,
+      checkedCount: checked.length,
+      healthyCount: checked.filter((project) => project.status === "healthy").length,
+      warningCount: checked.filter((project) => project.status === "warning").length,
+      errorCount: checked.filter((project) => project.status === "error").length,
+      failedCount: checked.filter((project) => project.status === "failed").length
+    },
+    projects: checked
+  };
+}
+function formatWorkspaceHealthText(report) {
+  const lines = [
+    `${BOLD}Decantr Workspace Health${RESET}`,
+    "",
+    `Projects: ${report.summary.checkedCount}/${report.summary.projectCount}`,
+    `Healthy: ${report.summary.healthyCount} | Warnings: ${report.summary.warningCount} | Errors: ${report.summary.errorCount} | Failed: ${report.summary.failedCount}`,
+    ""
+  ];
+  for (const project of report.projects) {
+    const color = project.status === "healthy" ? GREEN : project.status === "warning" ? YELLOW : RED;
+    lines.push(
+      `${color}${String(project.status).toUpperCase()}${RESET} ${project.path} score ${project.score}/100 findings ${project.findingCount}`
+    );
+    if (project.error) lines.push(`  ${DIM}${project.error}${RESET}`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+function formatWorkspaceHealthMarkdown(report) {
+  const lines = [
+    "# Decantr Workspace Health",
+    "",
+    `- Projects checked: **${report.summary.checkedCount}/${report.summary.projectCount}**`,
+    `- Healthy: ${report.summary.healthyCount}`,
+    `- Warnings: ${report.summary.warningCount}`,
+    `- Errors: ${report.summary.errorCount}`,
+    `- Failed: ${report.summary.failedCount}`,
+    "",
+    "| Project | Status | Score | Findings | Source |",
+    "| --- | --- | ---: | ---: | --- |"
+  ];
+  for (const project of report.projects) {
+    lines.push(
+      `| \`${project.path}\` | ${project.status} | ${project.score} | ${project.findingCount} | ${project.source} |`
+    );
+  }
+  return `${lines.join("\n")}
+`;
+}
+function shouldFailWorkspaceHealth(report, failOn = "error") {
+  if (failOn === "none") return false;
+  if (report.summary.failedCount > 0 || report.summary.errorCount > 0) return true;
+  return failOn === "warn" && report.summary.warningCount > 0;
+}
+function parseHealthFailOn(value) {
+  if (value === "warn" || value === "none") return value;
+  return "error";
+}
+function parseWorkspaceArgs(args) {
+  const subcommand = args[1] === "health" ? "health" : "list";
+  const options = { subcommand };
+  for (let index = 2; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--json") options.json = true;
+    else if (arg === "--markdown") options.markdown = true;
+    else if (arg === "--ci") options.ci = true;
+    else if (arg === "--browser") options.browser = true;
+    else if (arg === "--changed") options.changedOnly = true;
+    else if (arg === "--since" && args[index + 1]) options.since = args[++index];
+    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.startsWith("--fail-on=")) options.failOn = parseHealthFailOn(arg.split("=")[1]);
+    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]);
+  }
+  return options;
+}
+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)}
+`;
+    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}`);
+    }
+    return;
+  }
+  const report = await createWorkspaceHealthReport(workspaceRoot, options);
+  const payload = options.json ? `${JSON.stringify(report, null, 2)}
+` : options.markdown ? formatWorkspaceHealthMarkdown(report) : formatWorkspaceHealthText(report);
+  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}`);
+  } else {
+    process.stdout.write(payload);
+  }
+  if (options.ci && shouldFailWorkspaceHealth(report, options.failOn ?? "error")) {
+    process.exitCode = 1;
+  }
+}
+
+export {
+  listWorkspaceProjects,
+  createWorkspaceHealthReport,
+  formatWorkspaceHealthText,
+  formatWorkspaceHealthMarkdown,
+  shouldFailWorkspaceHealth,
+  parseWorkspaceArgs,
+  cmdWorkspace
+};