@codacy/verity-cli 0.20.1 → 0.21.0

package/README.md

@@ -24,13 +24,25 @@ source ~/.zshrc
 npm install -g @codacy/verity-cli
 ```
 
-## Upgrade to v0.16.0
+## Upgrade
 
 ```bash
 npm install -g @codacy/verity-cli@latest
 ```
 
-Existing projects work without changes. New compound features (knowledge extraction, graph memory, pre-work injection) activate automatically. Run `/verity-setup` again to add the CLAUDE.md knowledge base pointer and reflection instructions.
+Existing projects keep working — new compound features (knowledge extraction, graph memory, pre-work injection) activate automatically.
+
+### Coming from GATE.md (`@codacy/gate-cli`)?
+
+GATE.md is now Verity. One-time switch:
+
+```bash
+npm rm -g @codacy/gate-cli
+npm install -g @codacy/verity-cli
+verity init   # per project — moves .gate→.verity, keeps your token, Standard & memory
+```
+
+No re-setup needed: your token, Standard, and run history all carry over.
 
 ## Quick reference
 

package/bin/verity.js

@@ -14824,6 +14824,7 @@ async function runMigration(opts = {}) {
   migrateGlobalCredentials(home, actions);
   await migrateLegacyHooks(root, actions);
   await migrateClaudeMd(root, actions);
+  migrateStandardFile(root, actions);
   removeLegacyPackage(movedProjectDir, npmRemover, actions);
   return { actions, migrated: actions.length > 0 };
 }
@@ -14919,6 +14920,24 @@ async function migrateClaudeMd(root, actions) {
     printWarn(`Could not rewrite CLAUDE.md block: ${err.message}`);
   }
 }
+function migrateStandardFile(root, actions) {
+  const gateMd = (0, import_node_path14.join)(root, "GATE.md");
+  const verityMd = (0, import_node_path14.join)(root, "VERITY.md");
+  if (!(0, import_node_fs20.existsSync)(gateMd) || (0, import_node_fs20.existsSync)(verityMd)) return;
+  let moved = false;
+  if (isGitRepo(root) && isGitTracked(root, "GATE.md")) {
+    try {
+      (0, import_node_child_process8.execSync)("git mv GATE.md VERITY.md", { cwd: root, stdio: "pipe" });
+      moved = true;
+    } catch {
+    }
+  }
+  if (!moved) moveFile(gateMd, verityMd);
+  const content = readFileSyncSafe(verityMd);
+  const refreshed = content.split("GATE.md").join("VERITY.md");
+  if (refreshed !== content) (0, import_node_fs20.writeFileSync)(verityMd, refreshed);
+  actions.push("Renamed GATE.md \u2192 VERITY.md");
+}
 function removeLegacyPackage(movedProjectDir, npmRemover, actions) {
   if (!movedProjectDir) return;
   try {
@@ -15024,6 +15043,9 @@ async function needsMigration(root = repoRoot()) {
   if ((0, import_node_fs20.existsSync)(claudeMd) && hasLegacyMemoryBlock(readFileSyncSafe(claudeMd))) {
     return true;
   }
+  if ((0, import_node_fs20.existsSync)((0, import_node_path14.join)(root, "GATE.md")) && !(0, import_node_fs20.existsSync)((0, import_node_path14.join)(root, "VERITY.md"))) {
+    return true;
+  }
   if (await hasLegacyHooksAt(root)) return true;
   return false;
 }
@@ -15778,8 +15800,143 @@ function registerRunCommand(program2) {
   });
 }
 
+// src/lib/telemetry.ts
+var import_promises13 = require("node:fs/promises");
+var import_node_path18 = require("node:path");
+var SETTINGS_LOCAL_FILE2 = ".claude/settings.local.json";
+var GITIGNORE_FILE = ".gitignore";
+var GITIGNORE_ENTRY = ".claude/settings.local.json";
+function deriveOtlpEndpoint(serviceUrl) {
+  return serviceUrl.replace(/\/+$/, "").replace(/\/v1$/, "") + "/v1/otlp";
+}
+function buildTelemetryEnv(serviceUrl, token) {
+  return {
+    CLAUDE_CODE_ENABLE_TELEMETRY: "1",
+    OTEL_METRICS_EXPORTER: "otlp",
+    OTEL_TRACES_EXPORTER: "otlp",
+    CLAUDE_CODE_ENHANCED_TELEMETRY_BETA: "1",
+    OTEL_EXPORTER_OTLP_PROTOCOL: "http/json",
+    OTEL_EXPORTER_OTLP_ENDPOINT: deriveOtlpEndpoint(serviceUrl),
+    // <token> is whatever is in .verity/credentials — verity_ OR legacy gate_.
+    // The server hashes the raw token regardless of prefix.
+    OTEL_EXPORTER_OTLP_HEADERS: `Authorization=Bearer ${token}`,
+    OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE: "delta",
+    OTEL_LOG_USER_PROMPTS: "0",
+    OTEL_LOG_TOOL_DETAILS: "0",
+    OTEL_LOG_TOOL_CONTENT: "0",
+    OTEL_METRICS_INCLUDE_SESSION_ID: "true",
+    OTEL_METRICS_INCLUDE_ACCOUNT_UUID: "false",
+    OTEL_METRICS_INCLUDE_VERSION: "false",
+    OTEL_METRIC_EXPORT_INTERVAL: "60000"
+  };
+}
+var VERITY_TELEMETRY_KEYS = Object.keys(buildTelemetryEnv("", ""));
+async function readSettingsLocal() {
+  try {
+    return JSON.parse(await (0, import_promises13.readFile)(projectPath(SETTINGS_LOCAL_FILE2), "utf-8"));
+  } catch {
+    return {};
+  }
+}
+async function writeSettingsLocal(settings) {
+  const file = projectPath(SETTINGS_LOCAL_FILE2);
+  await (0, import_promises13.mkdir)((0, import_node_path18.dirname)(file), { recursive: true });
+  await (0, import_promises13.writeFile)(file, JSON.stringify(settings, null, 2) + "\n");
+}
+async function ensureGitignore() {
+  const file = projectPath(GITIGNORE_FILE);
+  let content = "";
+  try {
+    content = await (0, import_promises13.readFile)(file, "utf-8");
+  } catch {
+  }
+  const lines = content.split("\n").map((l) => l.trim());
+  if (lines.includes(GITIGNORE_ENTRY) || lines.includes(".claude/") || lines.includes(".claude")) {
+    return;
+  }
+  const block = "# Verity telemetry \u2014 holds your project token\n" + GITIGNORE_ENTRY + "\n";
+  const next = content ? content + (content.endsWith("\n") ? "" : "\n") + "\n" + block : block;
+  await (0, import_promises13.writeFile)(file, next);
+}
+async function installTelemetry(serviceUrl, token) {
+  const env = buildTelemetryEnv(serviceUrl, token);
+  const settings = await readSettingsLocal();
+  settings.env = { ...settings.env ?? {}, ...env };
+  await writeSettingsLocal(settings);
+  await ensureGitignore();
+  return { ok: true, data: { endpoint: env.OTEL_EXPORTER_OTLP_ENDPOINT } };
+}
+async function checkTelemetry() {
+  const env = (await readSettingsLocal()).env ?? {};
+  const enabled = env.CLAUDE_CODE_ENABLE_TELEMETRY === "1" && !!env.OTEL_EXPORTER_OTLP_ENDPOINT;
+  return { enabled, endpoint: env.OTEL_EXPORTER_OTLP_ENDPOINT ?? null, settingsPath: SETTINGS_LOCAL_FILE2 };
+}
+async function uninstallTelemetry() {
+  const settings = await readSettingsLocal();
+  if (!settings.env) return { ok: true, data: { removed: 0 } };
+  let removed = 0;
+  for (const key of VERITY_TELEMETRY_KEYS) {
+    if (key in settings.env) {
+      delete settings.env[key];
+      removed++;
+    }
+  }
+  if (Object.keys(settings.env).length === 0) delete settings.env;
+  await writeSettingsLocal(settings);
+  return { ok: true, data: { removed } };
+}
+
+// src/commands/telemetry.ts
+function registerTelemetryCommands(program2) {
+  const telemetry = program2.command("telemetry").description("Manage Claude Code OpenTelemetry export to Verity (cost & usage)");
+  telemetry.command("install").description("Enable Claude Code telemetry export to Verity (writes .claude/settings.local.json)").action(async () => {
+    const globals = program2.opts();
+    const tokenResult = await resolveToken(globals.token);
+    if (!tokenResult.ok) {
+      printError(tokenResult.error);
+      process.exit(1);
+    }
+    const urlResult = await resolveServiceUrl(globals.serviceUrl);
+    if (!urlResult.ok) {
+      printError(urlResult.error);
+      process.exit(1);
+    }
+    const result = await installTelemetry(urlResult.data, tokenResult.data.token);
+    if (!result.ok) {
+      printError(result.error);
+      process.exit(1);
+    }
+    printInfo(`Telemetry enabled \u2192 ${result.data.endpoint}`);
+    printInfo(`  wrote ${SETTINGS_LOCAL_FILE2} (gitignored \u2014 it holds your project token)`);
+    printInfo("  takes effect on your NEXT Claude Code session; first metrics appear within ~60s of activity");
+    printInfo("  view cost & usage at /usage");
+  });
+  telemetry.command("check").description("Show whether Claude Code telemetry export to Verity is enabled").option("--json", "Output status as JSON").action(async (opts) => {
+    const status = await checkTelemetry();
+    if (opts.json) {
+      printJson(status);
+      return;
+    }
+    if (status.enabled) {
+      printInfo(`Telemetry: enabled \u2192 ${status.endpoint}`);
+    } else {
+      printWarn('Telemetry: disabled. Run "verity telemetry install" to enable cost & usage tracking.');
+    }
+  });
+  telemetry.command("uninstall").description("Disable Claude Code telemetry export to Verity").action(async () => {
+    const result = await uninstallTelemetry();
+    if (!result.ok) {
+      printError(result.error);
+      process.exit(1);
+    }
+    printInfo(
+      result.data.removed > 0 ? `Telemetry disabled (${result.data.removed} keys removed from ${SETTINGS_LOCAL_FILE2})` : "Telemetry was not enabled \u2014 nothing to remove."
+    );
+  });
+}
+
 // src/cli.ts
-program.name("verity").description("CLI for Verity quality gate service").version("0.20.1").option("--token <token>", "Override authentication token").option("--service-url <url>", "Override service URL").option("--verbose", "Log HTTP requests/responses to stderr");
+program.name("verity").description("CLI for Verity quality gate service").version("0.21.0").option("--token <token>", "Override authentication token").option("--service-url <url>", "Override service URL").option("--verbose", "Log HTTP requests/responses to stderr");
 registerAuthCommands(program);
 registerHooksCommands(program);
 registerIntentCommands(program);
@@ -15797,4 +15954,5 @@ registerReflectCommand(program);
 registerMemoryCommand(program);
 registerRunCommand(program);
 registerMigrateCommand(program);
+registerTelemetryCommands(program);
 program.parse();

package/data/skills/verity-setup/SKILL.md

@@ -75,6 +75,36 @@ Default to `balanced` if the user says "default" or doesn't specify a preference
 
 ---
 
+## Step 3b: Ask about cost & usage telemetry (opt-in)
+
+Cost & usage observability is **opt-in** and **required** for the `/usage` dashboard — all
+cost and token data comes from Claude Code's own OpenTelemetry export, so with telemetry off
+the dashboard stays empty.
+
+First check the current state (so you don't re-ask if it's already on):
+
+```bash
+verity telemetry check
+```
+
+- If it reports **enabled**, don't re-ask — tell the user telemetry is already on and continue
+  (mention `verity telemetry uninstall` only if they want to turn it off).
+- If **disabled**, use the **AskUserQuestion** tool:
+
+> **Enable Claude Code cost & usage telemetry for this project?**
+> Verity can show cost, tokens, a per-agent / per-session / model breakdown, and a fleet cost
+> tree — by receiving Claude Code's built-in **OpenTelemetry** export. This sends usage
+> **metrics and traces only** (model names, token counts, USD cost, agent types, session IDs).
+> It does **NOT** send your prompts, code, or tool input/output. Without it, the `/usage`
+> dashboard stays empty.
+> - **Yes** (recommended) — enable telemetry
+> - **No** — skip (you can enable later with `verity telemetry install`)
+
+Remember the answer; you act on it in Step 7b (the token must exist first). **Declining is
+fine and reversible** — nothing is written, and the next `/verity-setup` re-offers it.
+
+---
+
 ## Step 4: Synthesize the Standard
 
 Read `.claude/skills/verity-setup/patterns-reference.yaml` and `.claude/skills/verity-setup/standard-template.yaml` from the project root.
@@ -301,6 +331,25 @@ This derives a small set of descriptive memory nodes from what you already analy
 
 ---
 
+## Step 7b: Enable telemetry (only if the user opted in at Step 3b)
+
+If — and only if — the user said **Yes** in Step 3b, enable the Claude Code telemetry export
+now (the token from Step 6 must already exist):
+
+```bash
+verity telemetry install
+```
+
+This writes the `OTEL_*` env block to the gitignored `.claude/settings.local.json` (which
+holds your token) and points Claude Code's OpenTelemetry exporter at Verity's OTLP endpoint.
+Tell the user it takes effect on their **next** Claude Code session, that first metrics appear
+within ~60s of activity, and point them at `/usage`.
+
+If the user declined, skip this step and note that `/usage` will stay empty until they run
+`verity telemetry install`.
+
+---
+
 ## Step 8: Generate VERITY.md file
 
 Create `VERITY.md` at the project root with this content:
@@ -404,8 +453,12 @@ Add these entries to `.gitignore` (create it if it doesn't exist, append if it d
 .verity/.last-intent
 .verity/.memory-sync-state.json
 .verity/memory/log.md
+.claude/settings.local.json
 ```
 
+`.claude/settings.local.json` holds the telemetry env block **including your token**, so it
+must never be committed (`verity telemetry install` also adds this entry automatically).
+
 Do NOT gitignore `.verity/standard.yaml` or `VERITY.md` — those should be committed.
 
 **Commit the knowledge graph, but not its log.** The nodes under `.verity/memory/<domain>/` and `.verity/memory/index.md` are durable project knowledge meant to be committed and reviewed. But `.verity/memory/log.md` is an append-only, per-run timestamped activity log — it churns on every analysis and carries no reviewable content, so it is gitignored above. If a project already committed it, untrack it once with `git rm --cached .verity/memory/log.md`.
@@ -431,12 +484,14 @@ Standard:     v1 (4 quality, 7 security, N custom patterns)
 Tools:        ${TOOL_LIST}
 Service:      registered (project_id: ${PROJECT_ID})
 Hooks:        installed (verity analyze + verity intent capture)
+Telemetry:    ${TELEMETRY_STATUS}   (enabled → cost+usage at /usage, or disabled)
 
 Files created:
   .verity/standard.yaml        — Quality standard
   .codacy/codacy.config.json   — Analysis CLI config
   VERITY.md                    — Project quality overview
   .claude/settings.json        — Hook configuration (verified)
+  .claude/settings.local.json  — Telemetry env (only if enabled; gitignored)
   .gitignore                   — Updated with Verity entries
 
 Next: You should now be seeing the first analysis happening below. The hook will fire automatically every time your agent stops working on something.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codacy/verity-cli",
-  "version": "0.20.1",
+  "version": "0.21.0",
   "description": "CLI for Verity quality gate service",
   "homepage": "https://verity.md",
   "repository": {