@decantr/cli 3.8.0 → 3.8.1

package/README.md

@@ -21,8 +21,8 @@ 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 right entry path.
 Use `decantr scan` when you want a zero-commit Brownfield preview. It reads local files through the shared verifier discovery substrate, detects workspace/app scope, package manager, framework, language, route signals, taskable routes, component inventory confidence, styling/static-hosting/assistant-rule signals, previews typed Contract graph readiness in memory when a Decantr contract already exists, reports the contract capsule source-handle count and limit, prints a terminal report, and writes no `.decantr` files or report artifacts. Add `--json` when automation needs the `ScanReportV2` payload.
 Use `decantr new` for a greenfield workspace in a fresh directory. With a blueprint or archetype it creates a contract-only Decantr workspace by default; runnable legacy Decantr CSS adapters require explicit `--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 studio` after adoption when you want a local Control Room for routes, findings, evidence, authority, and next actions. Use `decantr connect cursor` when the opened workspace should get Cursor Agent MCP and project-rule activation; in monorepos use `decantr connect cursor --project apps/web` so the rule keeps the app scope. Use `decantr doctor` when the next step is unclear, `decantr task <route> "<intent>"` before asking an LLM to modify a route, `decantr verify` after the edit, `decantr resolve` when source and contract disagree, and `decantr ci` in required automation. If runtime source and Decantr context disagree, report the drift instead of guessing; in Brownfield the existing source is observed truth, accepted local law/style bridge is project authority where present, Essence V4 is the structural contract, and hosted packs stay advisory until mapped into local law. Use `decantr graph` when you want the Decantr 3 typed Contract graph, typed graph diff summary, manifest, content-addressed snapshot history, and cache-friendly contract capsule written under `.decantr/graph`; the capsule includes a bounded SourceArtifact path index so agents can discover valid file-impact handles without reading the full snapshot, and `--capsule-source-limit <count>` can tune that index for large repos. Add `--route /feed --task "improve loading" --json` when you want the exact task-ranked route-scoped subgraph an agent should inspect before editing, `--node cmp:button --impact --json` when you need the graph-shaped blast radius for a component, token, rule, finding, or source artifact, or `--file src/app/page.tsx --impact --json` when the agent knows the source file it is about to change. Route and impact ranking use deterministic weighted traversal plus local personalized PageRank and task boosts. Use `--snapshot-id <id>` to inspect a replayable history snapshot and `--compare-to <id> --include-diff-ops --json` to compare the selected/current graph against a prior snapshot. Use `decantr codify --from-audit --style-bridge` when you want project-owned UI patterns, optional `behavior_obligations`, local rules, and token/class bridge mappings such as button/card/shell/theme standards to appear in future task context and verification. Once accepted, that local law is the first Hybrid lane: the app still owns source and styling, but Decantr treats accepted local patterns, behavior obligations, rules, and style bridge mappings as project authority.
+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 content API execution packs when online, and only applies the contract when you explicitly accept or merge it.
+Use `decantr studio` after adoption when you want a local Control Room for routes, findings, evidence, authority, and next actions. Use `decantr connect cursor` when the opened workspace should get Cursor Agent MCP and project-rule activation; in monorepos use `decantr connect cursor --project apps/web` so the rule keeps the app scope. Use `decantr doctor` when the next step is unclear, `decantr task <route> "<intent>"` before asking an LLM to modify a route, `decantr verify` after the edit, `decantr resolve` when source and contract disagree, and `decantr ci` in required automation. If runtime source and Decantr context disagree, report the drift instead of guessing; in Brownfield the existing source is observed truth, accepted local law/style bridge is project authority where present, Essence V4 is the structural contract, and content packs stay advisory until mapped into local law. Use `decantr graph` when you want the Decantr 3 typed Contract graph, typed graph diff summary, manifest, content-addressed snapshot history, and cache-friendly contract capsule written under `.decantr/graph`; the capsule includes a bounded SourceArtifact path index so agents can discover valid file-impact handles without reading the full snapshot, and `--capsule-source-limit <count>` can tune that index for large repos. Add `--route /feed --task "improve loading" --json` when you want the exact task-ranked route-scoped subgraph an agent should inspect before editing, `--node cmp:button --impact --json` when you need the graph-shaped blast radius for a component, token, rule, finding, or source artifact, or `--file src/app/page.tsx --impact --json` when the agent knows the source file it is about to change. Route and impact ranking use deterministic weighted traversal plus local personalized PageRank and task boosts. Use `--snapshot-id <id>` to inspect a replayable history snapshot and `--compare-to <id> --include-diff-ops --json` to compare the selected/current graph against a prior snapshot. Use `decantr codify --from-audit --style-bridge` when you want project-owned UI patterns, optional `behavior_obligations`, local rules, and token/class bridge mappings such as button/card/shell/theme standards to appear in future task context and verification. Once accepted, that local law is the first Hybrid lane: the app still owns source and styling, but Decantr treats accepted local patterns, behavior obligations, rules, and style bridge mappings as project authority.
 In monorepos, app-scoped commands accept `--project <app-path>`. `setup` shows attach guidance before adoption and the day-two loop after adoption. Candidate discovery ranks product UI apps ahead of docs, Storybook, API, MCP helper, workbench, and package surfaces; `decantr workspace list --json` includes rank, category, score, and reason metadata so automation can explain why `apps/web`, `apps/remix`, or `apps/dashboard` was suggested first. Once an app path is selected, scan/setup/adopt/doctor/task/verify/ci/connect preserve that app scope and inherit package-manager evidence from the workspace root, so a React app inside a pnpm Angular/React monorepo is reported as the React app, not the root or sibling app. Content pack hydration also follows the essence path: `decantr content compile-packs apps/web/decantr.essence.json --write-context` writes into `apps/web/.decantr/context`. In contract-only/offline Brownfield, deferred 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.
 
@@ -166,7 +166,7 @@ decantr check
 decantr studio --port 4319 --host 127.0.0.1
 decantr telemetry status
 decantr telemetry explain
-decantr telemetry link --enable --org <org-slug>
+decantr telemetry link --api-url https://telemetry.example/v1 --api-key <key>
 decantr content check --ci --fail-on error
 decantr content summary --namespace @official --json
 decantr list blueprints --blueprint-set featured
@@ -259,22 +259,22 @@ decantr health --json --output decantr-health.json
 decantr studio --report decantr-health.json
 ```
 
-If the project has explicitly enabled Decantr CLI telemetry, `new --telemetry`, `init --telemetry`, `analyze`, `check --telemetry`, `health`, and `studio` emit only aggregate product-activation metadata such as lifecycle command outcome, analyze counts, status, score, finding counts, CI failure outcome, Studio usage, and remediation prompt requests. They never upload the health report, finding evidence, local paths, route names, source code, package names, or prompt text.
+If a project has explicitly enabled Decantr CLI telemetry and configured `DECANTR_TELEMETRY_ENDPOINT`, `new --telemetry`, `init --telemetry`, `analyze`, `check --telemetry`, `health`, and `studio` may emit only aggregate product-activation metadata to that caller-controlled private sink. They never upload the health report, finding evidence, local paths, route names, source code, package names, or prompt text. Without the endpoint, opt-in remains a local preference and no events or opaque identifiers are created.
 
-## Opted-In Telemetry Identity
+## Private Telemetry Identity
 
-`decantr telemetry` lets users inspect and link the opaque install/project ids used by opted-in CLI telemetry. This is how customer org attribution becomes durable without collecting repository names, local paths, source code, prompts, private package slugs, emails, or secrets.
+`decantr telemetry` reports whether a caller-controlled event sink is configured and exposes the aggregate event contract for review. Decantr does not operate a hosted telemetry sink or identity service.
 
 ```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>
+DECANTR_TELEMETRY_ENDPOINT=https://telemetry.example/v1/events decantr init --telemetry
+decantr telemetry link --api-url https://telemetry.example/v1 --api-key <key> --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 link` is retained for private deployments only. It requires an explicit `--api-url` or `DECANTR_TELEMETRY_IDENTITY_API_URL` plus an API key; it never falls back to `api.decantr.ai` or `DECANTR_API_URL`. Only after those values are validated can it create and send opaque install/project ids, optional org slug, and optional label.
 
 `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.
 

package/dist/bin.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import "./chunk-VULJMJJP.js";
-import "./chunk-IP2CCX2W.js";
-import "./chunk-56HUEUO3.js";
-import "./chunk-WAGVDMJV.js";
-import "./chunk-24JR4ZNG.js";
+import "./chunk-CI2R5W36.js";
+import "./chunk-JK3DYOHA.js";
+import "./chunk-W242I6CS.js";
+import "./chunk-PFFNEN7L.js";
+import "./chunk-2UC6YYVZ.js";

package/dist/{chunk-24JR4ZNG.js → chunk-2UC6YYVZ.js}

@@ -1731,22 +1731,24 @@ import {
   createTelemetryClient,
   isTelemetryActorType
 } from "@decantr/telemetry";
-var TELEMETRY_ENDPOINT = "https://api.decantr.ai/v1/telemetry/guard";
-var DEFAULT_TELEMETRY_EVENTS_ENDPOINT = "https://api.decantr.ai/v1/telemetry/events";
 var TELEMETRY_TIMEOUT_MS = 3e3;
 var DNA_RULES = /* @__PURE__ */ new Set(["theme", "style", "density", "accessibility", "theme-mode"]);
 async function sendGuardMetrics(metrics) {
+  const endpoint = readConfiguredEndpoint("DECANTR_TELEMETRY_GUARD_ENDPOINT");
+  if (!endpoint) return;
+  let timer;
   try {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), TELEMETRY_TIMEOUT_MS);
-    await fetch(TELEMETRY_ENDPOINT, {
+    timer = setTimeout(() => controller.abort(), TELEMETRY_TIMEOUT_MS);
+    await fetch(endpoint, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(metrics),
       signal: controller.signal
     });
-    clearTimeout(timer);
   } catch {
+  } finally {
+    if (timer) clearTimeout(timer);
   }
 }
 function isOptedIn(projectRoot) {
@@ -1780,6 +1782,10 @@ async function captureCliTelemetryEvent(input) {
   if (!isOptedIn(projectRoot)) {
     return;
   }
+  const endpoint = getTelemetryEventsEndpoint();
+  if (!endpoint) {
+    return;
+  }
   const identities = ensureTelemetryIdentities(projectRoot);
   if (!identities) {
     return;
@@ -1787,7 +1793,7 @@ async function captureCliTelemetryEvent(input) {
   const registrySource = input.registrySource ?? getRegistrySourceProperty(input.properties) ?? inferRegistrySource(input.args ?? []);
   const client = createTelemetryClient({
     sink: createFetchTelemetrySink({
-      endpoint: getTelemetryEventsEndpoint(),
+      endpoint,
       timeoutMs: TELEMETRY_TIMEOUT_MS
     })
   });
@@ -2057,8 +2063,11 @@ function getCliTelemetryIdentityStatus(projectRoot, options = {}) {
   const hasProjectConfig = existsSync9(projectJsonPath);
   const identities = options.create ? ensureTelemetryIdentities(projectRoot) : null;
   const projectData = readProjectJson2(projectRoot);
+  const endpoint = getTelemetryEventsEndpoint();
   return {
     enabled: projectData?.telemetry === true,
+    endpoint,
+    endpointConfigured: Boolean(endpoint),
     hasProjectConfig,
     installId: identities?.installId ?? readExistingInstallId(),
     projectId: identities?.projectId ?? readStringProperty(projectData, "telemetryProjectId"),
@@ -2124,7 +2133,12 @@ function getConfigDir() {
   return process.env.DECANTR_CONFIG_DIR || join9(homedir(), ".config", "decantr");
 }
 function getTelemetryEventsEndpoint() {
-  return process.env.DECANTR_TELEMETRY_ENDPOINT || DEFAULT_TELEMETRY_EVENTS_ENDPOINT;
+  return readConfiguredEndpoint("DECANTR_TELEMETRY_ENDPOINT");
+}
+function readConfiguredEndpoint(name) {
+  const value = process.env[name]?.trim();
+  if (!value) return void 0;
+  return value.replace(/\/+$/, "");
 }
 function getTelemetryActorType() {
   const configured = process.env.DECANTR_TELEMETRY_ACTOR_TYPE;
@@ -2398,10 +2412,10 @@ ${YELLOW}Warnings found. Review the issues above or set stricter gates in CI.${R
 async function maybeSendTelemetry(projectRoot, essence, issues, options) {
   if (options.telemetry && !isOptedIn(projectRoot)) {
     optIn(projectRoot);
-    console.log(
-      `
-${CYAN}Telemetry enabled.${RESET} Decantr will send privacy-filtered CLI product telemetry for this project.`
-    );
+    const telemetry = getCliTelemetryIdentityStatus(projectRoot);
+    const message = telemetry.endpointConfigured ? "Privacy-filtered CLI telemetry can be sent to the configured private endpoint." : "The local preference is enabled, but no events are sent until DECANTR_TELEMETRY_ENDPOINT is configured.";
+    console.log(`
+${CYAN}Telemetry preference enabled.${RESET} ${message}`);
     console.log(`${DIM}Set "telemetry": false in .decantr/project.json to opt out.${RESET}`);
   }
   if (isOptedIn(projectRoot)) {