@decantr/cli 2.3.0 → 2.3.1

package/README.md

@@ -82,6 +82,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
@@ -135,12 +136,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.

package/dist/bin.js

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

package/dist/{chunk-FSZ6OIAC.js → chunk-2JWVKBNB.js}

@@ -4184,6 +4184,7 @@ function resolveDriftEntries(projectRoot, options) {
 }
 
 // src/commands/telemetry.ts
+import { DECANTR_TELEMETRY_EVENT_CATALOG } from "@decantr/telemetry";
 var BOLD5 = "\x1B[1m";
 var CYAN6 = "\x1B[36m";
 var DIM11 = "\x1B[2m";
@@ -4201,6 +4202,10 @@ async function cmdTelemetry(args, projectRoot = process.cwd()) {
     printTelemetryStatus(projectRoot, options);
     return;
   }
+  if (subcommand === "explain") {
+    printTelemetryExplain(projectRoot, options);
+    return;
+  }
   if (subcommand === "link") {
     await linkTelemetryIdentity(projectRoot, options);
     return;
@@ -4213,11 +4218,13 @@ ${BOLD5}decantr telemetry${RESET11} \u2014 Inspect and link privacy-filtered CLI
 
 ${BOLD5}Usage:${RESET11}
   decantr telemetry status [--json]
+  decantr telemetry explain [--json]
   decantr telemetry link [--enable] [--org <slug>] [--label <label>] [--api-key <key>] [--api-url <url>]
 
 ${BOLD5}Examples:${RESET11}
   decantr init --telemetry
   decantr telemetry status
+  decantr telemetry explain
   decantr login --api-key=<your-key>
   decantr telemetry link --org my-team --label "CI runner"
 `);
@@ -4242,6 +4249,82 @@ ${BOLD5}Decantr telemetry${RESET11}`);
     console.log(DIM11 + "Run `decantr init --telemetry` or `decantr telemetry link --enable` to opt in." + RESET11);
   }
 }
+function printTelemetryExplain(projectRoot, options) {
+  const status = getCliTelemetryIdentityStatus(projectRoot, { create: false });
+  const cliEvents = DECANTR_TELEMETRY_EVENT_CATALOG.filter((entry) => entry.allowedSources.includes("cli")).map((entry) => ({
+    name: entry.name,
+    bucket: entry.bucket,
+    privacy: entry.privacy,
+    publicIngest: entry.publicIngest,
+    notes: entry.privacyNotes
+  }));
+  const report = {
+    source: "cli",
+    enabled: status.enabled,
+    hasProjectConfig: status.hasProjectConfig,
+    identifiers: {
+      installId: status.installId ?? null,
+      projectId: status.projectId ?? null,
+      meaning: "Opaque Decantr-generated ids used only when this project has opted into CLI telemetry."
+    },
+    endpoint: process.env.DECANTR_TELEMETRY_ENDPOINT ?? "https://api.decantr.ai/v1/telemetry/events",
+    events: cliEvents,
+    aggregateFields: [
+      "command name",
+      "success or failure",
+      "duration",
+      "workflow and adoption mode",
+      "project scope",
+      "registry source",
+      "aggregate analyze counts",
+      "Project Health status, score, and finding counts",
+      "CI gate outcome",
+      "Studio start and refresh activity",
+      "remediation prompt request outcome"
+    ],
+    neverCollected: [
+      "source code",
+      "prompt text",
+      "local file paths",
+      "repository names",
+      "emails",
+      "secrets",
+      "raw route names",
+      "private package slugs",
+      "health report bodies",
+      "finding evidence"
+    ],
+    controls: {
+      optIn: "Run decantr init --telemetry, decantr new --telemetry, or decantr telemetry link --enable.",
+      optOut: 'Set "telemetry": false in .decantr/project.json.',
+      link: "Run decantr telemetry link after login to attach opaque ids to your Decantr account/org."
+    }
+  };
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  console.log(`
+${BOLD5}Decantr telemetry explanation${RESET11}`);
+  console.log(`  Source:     cli`);
+  console.log(`  Enabled:    ${status.enabled ? `${GREEN11}yes${RESET11}` : "no"}`);
+  console.log(`  Install ID: ${status.installId ?? `${DIM11}not created yet${RESET11}`}`);
+  console.log(`  Project ID: ${status.projectId ?? `${DIM11}not created yet${RESET11}`}`);
+  console.log(`  Events:     ${cliEvents.length} CLI event types in the public catalog`);
+  console.log(`
+${BOLD5}Aggregate fields${RESET11}`);
+  for (const field of report.aggregateFields) {
+    console.log(`  - ${field}`);
+  }
+  console.log(`
+${BOLD5}Never collected${RESET11}`);
+  for (const field of report.neverCollected) {
+    console.log(`  - ${field}`);
+  }
+  console.log(`
+${DIM11}${report.controls.optOut}${RESET11}`);
+  console.log(`${DIM11}${report.controls.link}${RESET11}`);
+}
 async function linkTelemetryIdentity(projectRoot, options) {
   if (options.enable && !isOptedIn(projectRoot)) {
     optIn(projectRoot);
@@ -7233,6 +7316,7 @@ ${BOLD7}Usage:${RESET14}
   decantr content-health [--json] [--markdown] [--ci]
   decantr studio [--port 4319] [--host 127.0.0.1] [--report decantr-health.json]
   decantr telemetry status [--json]
+  decantr telemetry explain [--json]
   decantr telemetry link [--enable] [--org <slug>]
   decantr rules preview [--project=<path>]
   decantr rules apply [--project=<path>]
@@ -7320,6 +7404,7 @@ ${BOLD7}Examples:${RESET14}
   decantr studio
   decantr studio --report decantr-health.json
   decantr telemetry status
+  decantr telemetry explain
   decantr telemetry link --enable --org my-team
   decantr audit
   decantr audit src/pages/HomePage.tsx

package/dist/index.js

@@ -1,3 +1,3 @@
-import "./chunk-FSZ6OIAC.js";
+import "./chunk-2JWVKBNB.js";
 import "./chunk-WDA4SHIQ.js";
 import "./chunk-IEW2QFYI.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decantr/cli",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Decantr CLI - scaffold, audit, inspect Project Health, and maintain Decantr projects from the terminal",
   "author": "Decantr AI",
   "license": "MIT",
@@ -32,10 +32,10 @@
   "dependencies": {
     "ajv": "^8.20.0",
     "@decantr/core": "2.0.0",
-    "@decantr/telemetry": "2.2.0",
-    "@decantr/registry": "2.0.0",
+    "@decantr/telemetry": "2.2.1",
+    "@decantr/essence-spec": "2.0.1",
     "@decantr/verifier": "2.0.0",
-    "@decantr/essence-spec": "2.0.1"
+    "@decantr/registry": "2.0.0"
   },
   "scripts": {
     "build": "tsup",