From 8cc00516511e141d0119985f77679e668481ea85 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Thu, 19 Nov 2026 16:46:20 +0530 Subject: [PATCH 1/8] feat: anonymous install, version and per-feature usage events (1.8.2) plugin_session_start at each session start (plugin and altimate-code versions, OS, a random install id kept in the plugin store) and plugin_feature_used for each panel, command and gate, sent in the background through altimate-code's `tool report-event`. ALTIMATE_TELEMETRY_DISABLED starts no CLI for any usage event and makes no install id; an older CLI's refusal is silent. Co-Authored-By: Claude Opus 5.5 --- .claude-plugin/marketplace.json | 2 +- PRIVACY.md | 24 +- .../altimate-code/.claude-plugin/plugin.json | 2 +- plugins/altimate-code/CHANGELOG.md | 9 + plugins/altimate-code/README.md | 2 + plugins/altimate-code/hooks/dbt-mods.tsx | 3 + .../altimate-code/hooks/features/comments.tsx | 3 + .../hooks/features/cost.test.tsx | 47 ++- plugins/altimate-code/hooks/features/cost.tsx | 4 + .../hooks/features/cte-profile.tsx | 8 +- .../altimate-code/hooks/features/health.tsx | 6 +- plugins/altimate-code/hooks/features/runs.tsx | 3 + .../hooks/features/sql-graph.tsx | 3 + .../altimate-code/hooks/features/to-model.tsx | 2 + plugins/altimate-code/hooks/health.test.tsx | 55 +++- plugins/altimate-code/hooks/integrations.tsx | 3 + plugins/altimate-code/hooks/lineage.tsx | 3 + .../altimate-code/hooks/task-impact.test.tsx | 15 + plugins/altimate-code/hooks/task-impact.tsx | 6 +- plugins/altimate-code/hooks/usage.test.tsx | 273 ++++++++++++++++++ plugins/altimate-code/hooks/usage.ts | 97 +++++++ 21 files changed, 557 insertions(+), 13 deletions(-) create mode 100644 plugins/altimate-code/hooks/usage.test.tsx create mode 100644 plugins/altimate-code/hooks/usage.ts diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 4ff3c997..0181c402 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -7,7 +7,7 @@ }, "metadata": { "description": "Altimate's Claude Code plugin — data tools through the altimate-code MCP server, or the model-free CLI where MCP is disallowed, plus delegation of long dbt jobs to the CLI agent.", - "version": "1.8.1" + "version": "1.8.2" }, "plugins": [ { diff --git a/PRIVACY.md b/PRIVACY.md index c86134b9..404adc15 100644 --- a/PRIVACY.md +++ b/PRIVACY.md @@ -1,7 +1,7 @@ # Privacy Policy — Altimate Code plugin for Claude Code **Effective date:** November 2, 2026 -**Last revised:** November 17, 2026 +**Last revised:** November 19, 2026 **Applies to:** the `altimate-code` Claude Code plugin distributed from this repository, and the data flows it initiates through the [altimate-code](https://github.com/AltimateAI/altimate-code) MCP server and CLI. This policy supplements the Altimate AI [Privacy Policy](https://www.altimate.ai/privacy) and [Terms](https://www.altimate.ai/terms), which govern Altimate services generally. Where this document is silent, the master policy applies. Questions: **info@altimate.ai**. @@ -16,11 +16,12 @@ This policy supplements the Altimate AI [Privacy Policy](https://www.altimate.ai - When a task **is** delegated, your task text is passed to the altimate-code CLI, which sends it to an LLM provider to plan and execute the work — the Altimate LLM Gateway by default, or a provider you configure (BYOK). - Warehouse queries, dbt commands, and file edits run **locally on your machine, under your credentials**. Your warehouse credentials are never sent to Altimate. - In a project linked to an Altimate workspace, the plugin copies the workspace's team skills into the project's `.claude/skills/` and refreshes them from Altimate in the background at session start and at most hourly. Their text loads into the Claude Code conversation like any project skill. `ALTIMATE_CLAUDE_SKILL_SYNC=0` turns this off and removes the copies at the next session start. +- The plugin counts its own use anonymously, through the altimate-code CLI's usage telemetry: one event at each session start (plugin and altimate-code versions, OS, a random install id) and one each time a panel or command opens or a gate holds or allows a command (its name and outcome). No project, model, column or file names, SQL or session text. `ALTIMATE_TELEMETRY_DISABLED=true` turns it off. See [Plugin usage events](#plugin-usage-events). - Installing the plugin is an explicit act — `/plugin marketplace add` does not install it, and `/plugin install` never auto-runs. Nothing is delegated until the plugin is installed and you send a task that matches the skill. ## What the plugin does and does not do -The plugin registers a local stdio MCP server through `.mcp.json`, provides routing skills and slash commands, and runs hooks: SessionStart prints a capability description and, with Stop, keeps the linked workspace's skills copied into the project (see below); in a linked project, the workspace-rules hooks (SessionStart, UserPromptSubmit and Stop) start the local altimate-code CLI (see [Workspace rules](#workspace-rules)); an opt-in PreToolUse guard checks Bash commands locally. The server reads configured connections and runs data tools under your local credentials. The plugin adds no analytics of its own; CLI telemetry is described below. +The plugin registers a local stdio MCP server through `.mcp.json`, provides routing skills and slash commands, and runs hooks: SessionStart prints a capability description and, with Stop, keeps the linked workspace's skills copied into the project (see below); in a linked project, the workspace-rules hooks (SessionStart, UserPromptSubmit and Stop) start the local altimate-code CLI (see [Workspace rules](#workspace-rules)); an opt-in PreToolUse guard checks Bash commands locally. The server reads configured connections and runs data tools under your local credentials. The plugin opens no network connection of its own for analytics: its anonymous usage events go through the altimate-code CLI's telemetry (see [Plugin usage events](#plugin-usage-events)), which is described below. ## Data flows through MCP tools @@ -105,7 +106,22 @@ To learn whether the report gets used, the plugin asks the local altimate-code C - `/lineage-report` was run; - the report was built, failed to build, or found no browser. -Each event carries the step and the Claude Code session id (`claude:`) only: no model, column, file or project names. It goes through Altimate's usage telemetry, described in [Usage telemetry](#usage-telemetry), and that section's opt-out turns it off. With an altimate-code that predates the command, nothing is sent. +Each event carries the step and the Claude Code session id (`claude:`) only: no model, column, file or project names. It goes through Altimate's usage telemetry, described in [Usage telemetry](#usage-telemetry), and that section's opt-out turns it off; with `ALTIMATE_TELEMETRY_DISABLED` set, the plugin does not start the CLI for it. With an altimate-code that predates the command, nothing is sent. + +## Plugin usage events + +To count installs, active use and which features are used, the plugin asks the local altimate-code CLI (`altimate-code tool report-event`) to send these events through Altimate's usage telemetry, described in [Usage telemetry](#usage-telemetry). The plugin itself contacts no server for them. + +| Event | When | Fields | +|---|---|---| +| `plugin_session_start` | Each time Claude Code starts a session with the plugin enabled | `plugin_version`; `altimate_code_version` (added by the CLI); `os`: `macos`, `linux`, `windows`, `wsl` or `unknown`; `install_id`; `session_id` (`claude:`) | +| `plugin_feature_used` | A panel or command opens: `/lineage` (`lineage`), `/dbt-show` (`dbt_show`), `/profile-ctes` (`profile_ctes`), `/scan-cost` (`scan_cost`), `/comments` (`comments`), `/sql-graph` (`sql_graph`), `/health` (`health`), `/runs` (`runs`), `/to-model` (`to_model`); the cost check holds a dbt command or `/allow-scan` allows it (`cost_gate`); with "Project health blocks git push" on, the push gate holds or lets through a `git push` (`health_push_gate`) | `feature` (the name in brackets); `outcome`: `opened`, `failed` (the panel could not open), `held` or `allowed`; `plugin_version`; `install_id`; `session_id` | + +- **`install_id`** is a random UUID the plugin makes the first time it sends an event and keeps in its own Claude Code plugin store (a JSON file under your Claude Code configuration directory), so it stays the same across sessions on this machine. It is not derived from your machine, account or project, and is not made while `ALTIMATE_TELEMETRY_DISABLED` is set. Removing the plugin's store data makes a new one. +- Beside these fields, each event carries what every altimate-code telemetry event carries (the CLI version, its anonymous machine id, a per-launch id), as described in [Usage telemetry](#usage-telemetry). +- No event contains project, model, column or file names, SQL, query results or session text. The CLI accepts each field only from a fixed list or pattern (a version, a UUID, one of the names above) and refuses anything else. +- **Turning it off:** `ALTIMATE_TELEMETRY_DISABLED=true` (or `1`) in the environment Claude Code starts in: the plugin then starts no CLI for these events, or for the lineage report's, and makes no install id. The CLI also drops them under its own opt-out (`ALTIMATE_TELEMETRY_DISABLED`, or `telemetry.disabled` in its config), as for every other event. +- The events are sent in the background and never delay a hook. An altimate-code that predates them refuses them, and nothing is sent or shown. ## Data flows when a task is delegated @@ -157,6 +173,8 @@ The plugin and the altimate-code CLI are professional developer tools, not direc We will update this document in this repository and revise the effective date when our practices change. Material changes to Altimate-wide practices are governed by the master [Privacy Policy](https://www.altimate.ai/privacy). +**November 19, 2026:** added [Plugin usage events](#plugin-usage-events) (plugin 1.8.2): the anonymous session start and feature-used events, and the plugin's own check of the telemetry opt-out. + **November 17, 2026:** added [dbt helpers](#dbt-helpers) (plugin 1.8.0): the dbt commands the plugin runs in a dbt project, and what it keeps of their results. **November 16, 2026:** added [The lineage report](#the-lineage-report) (plugin 1.6.0): the offline report page, and the usage events the altimate-code CLI sends for it. diff --git a/plugins/altimate-code/.claude-plugin/plugin.json b/plugins/altimate-code/.claude-plugin/plugin.json index ff11cbb0..801bf554 100644 --- a/plugins/altimate-code/.claude-plugin/plugin.json +++ b/plugins/altimate-code/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "altimate-code", "displayName": "Altimate Code", - "version": "1.8.1", + "version": "1.8.2", "description": "Gives Claude Code altimate-code's model-free data tools (column-level lineage, impact analysis, PII detection, data-diff, FinOps, query equivalence, dialect translation, warehouse queries) through its MCP server, or through `altimate tool run` when MCP servers are not allowed, with delegation to the altimate-code agent for long dbt jobs, access to a linked Altimate workspace's knowledge, and the workspace's team rules in each session.", "author": { "name": "AltimateAI", diff --git a/plugins/altimate-code/CHANGELOG.md b/plugins/altimate-code/CHANGELOG.md index 6031c1a6..a550d473 100644 --- a/plugins/altimate-code/CHANGELOG.md +++ b/plugins/altimate-code/CHANGELOG.md @@ -2,6 +2,15 @@ All notable changes to this plugin will be documented in this file. +## [1.8.2] — 2026-11-19 + +### Added +- Anonymous usage events, sent through altimate-code's usage telemetry (`altimate-code tool report-event`); the plugin opens no network connection of its own for them. `plugin_session_start` at each session start carries the plugin version, the altimate-code version (added by the CLI), the OS (`macos`, `linux`, `windows`, `wsl` or `unknown`) and an install id: a random UUID made on first use and kept in the plugin's Claude Code store, so it stays the same across sessions on the machine. `plugin_feature_used` carries the feature and its outcome when `/lineage`, `/dbt-show`, `/profile-ctes`, `/scan-cost`, `/comments`, `/sql-graph`, `/health`, `/runs` or `/to-model` opens (`opened`, or `failed` when its pane could not open), when the cost check holds a dbt command (`held`) or `/allow-scan` allows it (`allowed`), and, with "Project health blocks git push" on, when the push gate holds or lets through a `git push`. No project, model, column or file names, SQL or session text: the CLI takes each field only from a fixed list or pattern. Every event and field is listed in PRIVACY.md. +- The events need an altimate-code with the `plugin_session_start` and `plugin_feature_used` actions; an older one refuses them and nothing is sent or shown. They run in the background and never delay a hook. + +### Changed +- With `ALTIMATE_TELEMETRY_DISABLED` (or `OPENCODE_DISABLE_TELEMETRY`) set to `true` or `1`, the plugin no longer starts the CLI for any usage event (the lineage report's included) and makes no install id. The CLI's own opt-out (that variable, or `telemetry.disabled` in its config) still drops them too. + ## [1.8.1] — 2026-11-19 ### Fixed diff --git a/plugins/altimate-code/README.md b/plugins/altimate-code/README.md index 0a86ac8a..dc18d2b2 100644 --- a/plugins/altimate-code/README.md +++ b/plugins/altimate-code/README.md @@ -181,6 +181,8 @@ MCP tools and `tool run` run locally under your credentials; tool results Claude The dbt helpers run the project's dbt on this machine. What they add to Claude's context (dbt's errors, column names, the manifest's facts about a model) reaches its model provider like any tool result. The rows of the Query results pane are kept on this machine only, in Claude Code's plugin store, until you clear them (bookmarked queries keep their rows through **Clear history**, and turning `dbt_mods` off does not delete them; see PRIVACY.md). +The plugin counts its own use anonymously through the altimate-code CLI's usage telemetry (`altimate-code tool report-event`; no network connection of the plugin's own): `plugin_session_start` at each session start, with the plugin and altimate-code versions, the OS and a random install id kept in the plugin's Claude Code store; and `plugin_feature_used` when `/lineage`, `/dbt-show`, `/profile-ctes`, `/scan-cost`, `/comments`, `/sql-graph`, `/health`, `/runs` or `/to-model` opens, or the cost check or the health push gate holds or allows a command, with the feature's name and the outcome. No project, model, column or file names, SQL or session text. Set `ALTIMATE_TELEMETRY_DISABLED=true` to turn it off (with altimate-code's other telemetry). An altimate-code that predates these events drops them silently. Every event and field is listed in [PRIVACY.md](../../PRIVACY.md#plugin-usage-events). + Delegating a task with `altimate run` passes your prompt text to the altimate-code CLI, which sends it to your configured LLM provider — the Altimate LLM Gateway by default, or your own provider (BYOK), in which case Altimate never sees it. Warehouse credentials and query results stay on your machine. Full details: **[PRIVACY.md](../../PRIVACY.md)** · Security policy and disclosure: **[SECURITY.md](../../SECURITY.md)** · Terms: **[TERMS.md](../../TERMS.md)** diff --git a/plugins/altimate-code/hooks/dbt-mods.tsx b/plugins/altimate-code/hooks/dbt-mods.tsx index 430fae07..707ea1a6 100644 --- a/plugins/altimate-code/hooks/dbt-mods.tsx +++ b/plugins/altimate-code/hooks/dbt-mods.tsx @@ -6,6 +6,7 @@ import type { Args, EngineInterface, EventResult, On, PluginOptions, RenderEleme import type { CheckView, DoctorCheck, DoctorView, FailureView, QueryResult, SavedQuery } from '../types' import { later } from './altimate-cli' +import { featureUsed } from './usage' import { loadPaneSizesOnce, noteTerminal, paneTerminalColumns, paneRequest, sizeControls, type PaneSpec } from './pane-size' import { cellText, @@ -1778,8 +1779,10 @@ export function registerDbtMods(on: On, context: { options: PluginOptions }) { try { await $.ui.open({ id: RESULTS_PANE, title: RESULTS_TITLE, ...request, focus: true, closeOnEscape: true }) } catch (error) { + featureUsed($, 'dbt_show', 'failed') return { text: `Could not open the Query results pane: ${String(error)}` } } + featureUsed($, 'dbt_show', 'opened') if (!args) return { text: 'Query results are open. Run /dbt-show or /dbt-show select … to query.' } const isSql = /\s/.test(args) || /^(select|with)\b/i.test(args) later($, () => runShow($, root, isSql ? null : args, isSql ? args : null, SHOW_LIMIT, asked)) diff --git a/plugins/altimate-code/hooks/features/comments.tsx b/plugins/altimate-code/hooks/features/comments.tsx index 24b73f90..b7310f58 100644 --- a/plugins/altimate-code/hooks/features/comments.tsx +++ b/plugins/altimate-code/hooks/features/comments.tsx @@ -11,6 +11,7 @@ import type { Args, EngineInterface, EventResult, On, RenderElement, ToolCallRes import type { CommentsState, CommentsThread } from '../../types' import { later, runTool } from '../altimate-cli' +import { featureUsed } from '../usage' import type { BashCall, ContextLines, EditedFile, FileCall } from '../tool-chain' import type { BandUi, FeatureContext } from './index' @@ -99,11 +100,13 @@ export function register(on: On, context: FeatureContext) { on('command.run', { command: COMMAND }, async $ => { try { await $.ui.open({ id: PANE, title: PANE_TITLE, focus: true, closeOnEscape: true }) + featureUsed($, 'comments', 'opened') // Running the command again is how a missing tool is looked for again, after an update. await change($, current => ({ ...current, needs: null, note: null })) later($, () => open($)) return { text: 'Team comments opened in the side pane.' } } catch (error) { + featureUsed($, 'comments', 'failed') return { text: `Could not open team comments: ${String(error)}` } } }) diff --git a/plugins/altimate-code/hooks/features/cost.test.tsx b/plugins/altimate-code/hooks/features/cost.test.tsx index b17fbfd8..4ff5038e 100644 --- a/plugins/altimate-code/hooks/features/cost.test.tsx +++ b/plugins/altimate-code/hooks/features/cost.test.tsx @@ -32,6 +32,8 @@ type Options = { statusFails?: boolean /** The Bash tool runs this command only once this resolves. */ holdBash?: { command: string; until: Promise } + /** The environment the plugin reads, which turns the usage events on (none set) or off; unset, they are not sent. */ + env?: Record } /** The session beneath the plugin, a CLI whose dbt_cost_estimate is scripted, and a Bash tool that records what ran. */ @@ -42,6 +44,13 @@ async function start($: any, on: any, options: Options = {}) { const started: string[] = [] const ran: string[] = [] const statuses: (string | undefined)[] = [] + /** The usage events sent: feature and outcome. */ + const usage: string[][] = [] + if (options.env) { + mock.env(on, options.env) + mock.store(on) + on('session.id', () => ({ value: 'a1b2c3d4-0000-4000-8000-000000000001' })) + } on('command.register', (_: unknown, e: { name: string }) => ({ value: { command: e.name } })) on('turn.start', (_: unknown, e: { turnId: string }) => ({ turnId: e.turnId })) on('session.end', () => ({ sessionId: 'test' })) @@ -67,8 +76,12 @@ async function start($: any, on: any, options: Options = {}) { }) on('fs.exists', () => ({ value: false })) on('process.run', async (_: unknown, e: { argv: readonly string[] }) => { - const [, command, , tool] = e.argv + const [, command, sub, tool] = e.argv if (command !== 'tool') return { value: { exitCode: 1, stdout: '', stderr: 'not this test' } } + if (sub === 'report-event') { + if (tool === 'plugin_feature_used') usage.push([e.argv[e.argv.indexOf('--feature') + 1]!, e.argv[e.argv.indexOf('--outcome') + 1]!]) + return { value: { exitCode: 0, stdout: '', stderr: '' } } + } // Another feature's tool (runs asks dbt_run_results) has nothing to report here, and is not an estimate. if (tool !== 'dbt_cost_estimate') return { value: { exitCode: 0, stdout: JSON.stringify({ status: 'ok', output: '', metadata: { found: false } }), stderr: '' } } // The adapter starts the project's dbt: the call must carry write permission. @@ -95,7 +108,7 @@ async function start($: any, on: any, options: Options = {}) { }) await $.session.start({ cwd: ROOT, surface: 'terminal', isInteractive: true }) await clock.settle() - return { clock, estimates, ran, statuses, started } + return { clock, estimates, ran, statuses, started, usage } } const bq = (bytes: number, display: string, maxBytes = bytes) => ({ success: true, supported: true, adapter: 'bigquery', bytes, maxBytes, display }) @@ -1676,3 +1689,33 @@ test("on BigQuery, the band's held line is as before", async ($, on) => { await clock.settle() expect(await bandShows($, '⛔ held: orders would scan 20.0 GiB (limit 10.0 GiB) · /allow-scan')).toBe(true) }) + +test('a hold sends one cost_gate held usage event, /allow-scan one cost_gate allowed, and /scan-cost one scan_cost opened', async ($, on) => { + const { clock, usage } = await start($, on, { answers: { orders: OVER, small: UNDER }, env: {} }) + expect(((await $.tool.call(bash('dbt run -s orders'))) as any).deny).toBeDefined() + await clock.settle() + expect(usage).toEqual([['cost_gate', 'held']]) + await $.command.run({ command: 'allow-scan', args: '' } as any) + await clock.settle() + expect(usage).toEqual([['cost_gate', 'held'], ['cost_gate', 'allowed']]) + // A command under the limit is no use of the gate. + await $.tool.call(bash('dbt run -s small')) + await $.command.run({ command: 'scan-cost', args: 'small' } as any) + await clock.settle() + expect(usage).toEqual([['cost_gate', 'held'], ['cost_gate', 'allowed'], ['scan_cost', 'opened']]) +}) + +test('/allow-scan with nothing held sends no allowed event', async ($, on) => { + const { clock, usage } = await start($, on, { env: {} }) + await $.command.run({ command: 'allow-scan', args: '' } as any) + await clock.settle() + expect(usage).toEqual([]) +}) + +test('with ALTIMATE_TELEMETRY_DISABLED the gate holds and allows as before and sends nothing', async ($, on) => { + const { clock, usage } = await start($, on, { answers: { orders: OVER }, env: { ALTIMATE_TELEMETRY_DISABLED: 'true' } }) + expect(((await $.tool.call(bash('dbt run -s orders'))) as any).deny).toBeDefined() + expect((await $.command.run({ command: 'allow-scan', args: '' } as any)).text).toContain('runs once') + await clock.settle() + expect(usage).toEqual([]) +}) diff --git a/plugins/altimate-code/hooks/features/cost.tsx b/plugins/altimate-code/hooks/features/cost.tsx index 1303438f..7b831d71 100644 --- a/plugins/altimate-code/hooks/features/cost.tsx +++ b/plugins/altimate-code/hooks/features/cost.tsx @@ -13,6 +13,7 @@ import { atom, read, update } from 'claude-code' import type { Args, EngineInterface, EventResult, On, RenderElement, ToolCallResult } from 'claude-code' import { runTool, within } from '../altimate-cli' +import { featureUsed } from '../usage' import { parseDbtCommand, type DbtInvocation } from '../dbt-command' import { setStatusPart } from '../status-line' import type { BashCall, ContextLines, EditedFile, FileCall } from '../tool-chain' @@ -150,10 +151,12 @@ export function register(on: On, context: FeatureContext) { }) if (!held) return { text: 'Nothing is held: no dbt command is waiting on its scan size.' } if (!allowed) return { text: 'The held command changed meanwhile: run /allow-scan again to allow the one now held.' } + featureUsed($, 'cost_gate', 'allowed') return { text: `Allowed: ${held.target} (≈ ${held.display}${held.planner ? `, ${held.planner} plan estimate` : ''}) runs once when Claude runs the same command again; after that it is held again.` } }) on('command.run', { command: 'scan-cost' }, async ($, e) => { + featureUsed($, 'scan_cost', 'opened') const target = e.args.trim() if (!target) { const last = (await read($, costAtom))?.lastEstimate @@ -407,6 +410,7 @@ async function gate($: EngineInterface, e: BashCall, mine: { note?: object }): P return null } notes.delete(e.command) + featureUsed($, 'cost_gate', 'held') await showStatus($, `scan held ≈ ${worst.display}`) // The hold is decided on the upper bound, and the display is the rounded point estimate: either can read // as not over the limit when the scan is just past it. diff --git a/plugins/altimate-code/hooks/features/cte-profile.tsx b/plugins/altimate-code/hooks/features/cte-profile.tsx index be2b111d..92b53d90 100644 --- a/plugins/altimate-code/hooks/features/cte-profile.tsx +++ b/plugins/altimate-code/hooks/features/cte-profile.tsx @@ -12,6 +12,7 @@ import type { Args, EngineInterface, EventResult, On, RenderElement, ToolCallRes import type { CteProfileState, CteRow, CteTier } from '../../types' import type { BashCall, ContextLines, EditedFile, FileCall } from '../tool-chain' import { later, runTool } from '../altimate-cli' +import { featureUsed } from '../usage' import { setStatusPart } from '../status-line' import type { BandUi, FeatureContext } from './index' @@ -262,7 +263,10 @@ export function register(on: On, context: FeatureContext) { on('command.run', { command: COMMAND }, async ($, e) => { // Claimed before anything is awaited: two commands in a row cannot both start a run. if (active) { - await openPane($).catch(() => {}) + await openPane($).then( + () => featureUsed($, 'profile_ctes', 'opened'), + () => featureUsed($, 'profile_ctes', 'failed'), + ) return { text: 'A CTE profile is already running; the pane has a Stop button.' } } const model = modelFor(e.args) @@ -274,9 +278,11 @@ export function register(on: On, context: FeatureContext) { await openPane($) } catch (error) { active = false + featureUsed($, 'profile_ctes', 'failed') await say($, `Could not open the pane: ${String(error)}`) return { text: `Could not open Profile CTEs: ${String(error)}` } } + featureUsed($, 'profile_ctes', 'opened') // The command answers now; the queries go on and the pane fills in. later($, () => profile($, model, generation)) return { text: `Profiling the CTEs of ${model}: each one is a warehouse query, the pane shows them as they finish.` } diff --git a/plugins/altimate-code/hooks/features/health.tsx b/plugins/altimate-code/hooks/features/health.tsx index 030f5588..c9f36377 100644 --- a/plugins/altimate-code/hooks/features/health.tsx +++ b/plugins/altimate-code/hooks/features/health.tsx @@ -14,6 +14,7 @@ import type { Args, EngineInterface, EventResult, On, PluginOptions, RenderEleme import type { HealthInsight, HealthState } from '../../types' import { NOT_FOUND, later, runTool, within } from '../altimate-cli' +import { featureUsed } from '../usage' import { setStatusPart } from '../status-line' import type { BashCall, ContextLines, EditedFile, FileCall } from '../tool-chain' import type { BandUi, FeatureContext } from './index' @@ -626,6 +627,7 @@ async function wantsCheck($: EngineInterface, retry = false): Promise { export function register(on: On, context: FeatureContext) { options = context.options on('command.run', { command: COMMAND }, async $ => { + featureUsed($, 'health', 'opened') const state = await read($, healthAtom) if (!state || !enabled) return { text: 'Project health checks dbt projects: this session has none open yet.' } // Asking again retries a first check that failed, and checks changes not yet checked. @@ -710,7 +712,9 @@ export async function bashGate($: EngineInterface, e: BashCall): Promise<{ deny: } // The whole decision, folder lookups included, is bounded inside the chain's deadline: past it the gate is given up on and the push runs. const decided = await within($, GATE_WAIT_MS, decide($, e)) - return decided === null ? hold('the check of the changes could not be read in time.') : decided === 'run' ? null : decided + const verdict = decided === null ? hold('the check of the changes could not be read in time.') : decided === 'run' ? null : decided + featureUsed($, 'health_push_gate', verdict ? 'held' : 'allowed') + return verdict } const hold = (why: string) => ({ diff --git a/plugins/altimate-code/hooks/features/runs.tsx b/plugins/altimate-code/hooks/features/runs.tsx index 513fc285..9310d61f 100644 --- a/plugins/altimate-code/hooks/features/runs.tsx +++ b/plugins/altimate-code/hooks/features/runs.tsx @@ -8,6 +8,7 @@ import type { Args, EngineInterface, EventResult, On, RenderElement, ToolCallRes import type { RunRecord, RunRow, RunsState } from '../../types' import { runTool } from '../altimate-cli' +import { featureUsed } from '../usage' import { parseDbtCommand, type DbtInvocation } from '../dbt-command' import type { BashCall, ContextLines, EditedFile, FileCall } from '../tool-chain' import type { BandUi, FeatureContext } from './index' @@ -596,8 +597,10 @@ export function register(on: On, context: FeatureContext) { await load($, await $.session.root()) await $.ui.open({ id: PANE, title: PANE_TITLE, ...PANE_SIZE, focus: true, closeOnEscape: true }) } catch (error) { + featureUsed($, 'runs', 'failed') return { text: `Could not open the dbt runs: ${String(error)}` } } + featureUsed($, 'runs', 'opened') return { text: 'The dbt runs are open.' } }) diff --git a/plugins/altimate-code/hooks/features/sql-graph.tsx b/plugins/altimate-code/hooks/features/sql-graph.tsx index 155ad0ce..9581162a 100644 --- a/plugins/altimate-code/hooks/features/sql-graph.tsx +++ b/plugins/altimate-code/hooks/features/sql-graph.tsx @@ -10,6 +10,7 @@ import type { Args, EngineInterface, EventResult, On, RenderElement, ToolCallRes import type { SqlGraphState, SqlGraphView } from '../../types' import { later, runTool, within } from '../altimate-cli' +import { featureUsed } from '../usage' import { projectLayout } from '../lineage-graph' import type { BashCall, ContextLines, EditedFile, FileCall } from '../tool-chain' import type { BandUi, FeatureContext } from './index' @@ -204,8 +205,10 @@ export function register(on: On, context: FeatureContext) { try { await $.ui.open({ id: PANE, title: PANE_TITLE, ...PANE_SIZE, focus: true, closeOnEscape: true }) } catch (error) { + featureUsed($, 'sql_graph', 'failed') return { text: plain(`Could not open the SQL graph: ${String(error)}`) } } + featureUsed($, 'sql_graph', 'opened') // One backend call and one warehouse metadata read, per command, never per edit. const landed = await within($, COMMAND_WAIT_MS, load($, model)) if (landed === null) return { text: `The SQL graph for ${shownModel} is loading; the pane shows it when it is ready.` } diff --git a/plugins/altimate-code/hooks/features/to-model.tsx b/plugins/altimate-code/hooks/features/to-model.tsx index 2038afa2..60590f25 100644 --- a/plugins/altimate-code/hooks/features/to-model.tsx +++ b/plugins/altimate-code/hooks/features/to-model.tsx @@ -5,6 +5,7 @@ import { atom, read, update } from 'claude-code' import type { Args, EngineInterface, EventResult, On, RenderElement, ToolCallResult } from 'claude-code' import { MISSING_BINARY, later, runTool } from '../altimate-cli' +import { featureUsed } from '../usage' import type { BashCall, ContextLines, EditedFile, FileCall } from '../tool-chain' import type { ToModelState } from '../../types' import { projectLayout } from '../lineage-graph' @@ -185,6 +186,7 @@ function summary(rows: RelationRow[]): string { /** Adds this feature's own hooks. */ export function register(on: On, context: FeatureContext) { on('command.run', { command: COMMAND }, async ($, e) => { + featureUsed($, 'to_model', 'opened') const parsed = parseArgs(e.args) if ('error' in parsed) return { text: parsed.error } const got = await sqlOf($, parsed.path) diff --git a/plugins/altimate-code/hooks/health.test.tsx b/plugins/altimate-code/hooks/health.test.tsx index 4be2ac8e..45d23c9d 100644 --- a/plugins/altimate-code/hooks/health.test.tsx +++ b/plugins/altimate-code/hooks/health.test.tsx @@ -64,6 +64,8 @@ type Options = { onCall?: () => void /** Called at each project lookup; a promise it returns holds the lookup. */ onExists?: () => Promise | void + /** The environment the plugin reads, which turns the usage events on (none set) or off; unset, they are not sent. */ + env?: Record } async function start($: any, on: any, options: Options, session: { isInteractive?: boolean } = {}) { @@ -71,6 +73,13 @@ async function start($: any, on: any, options: Options, session: { isInteractive const calls: { tool: string; args: Record; argv: readonly string[] }[] = [] const toasts: string[] = [] const statuses: string[] = [] + /** The usage events sent: feature and outcome. */ + const usage: string[][] = [] + if (options.env) { + mock.env(on, options.env) + mock.store(on) + on('session.id', () => ({ value: 'a1b2c3d4-0000-4000-8000-000000000001' })) + } on('command.register', () => ({ value: { command: 'health' } })) on('turn.start', (_: unknown, e: { turnId: string }) => ({ turnId: e.turnId })) on('session.end', () => ({ sessionId: 'test' })) @@ -120,8 +129,12 @@ async function start($: any, on: any, options: Options, session: { isInteractive }) let run = 0 on('process.run', async (_: unknown, e: { argv: readonly string[] }) => { - const [, command, , tool = ''] = e.argv + const [, command, sub, tool = ''] = e.argv if (command !== 'tool') return { value: { exitCode: 1, stdout: '', stderr: 'not this test' } } + if (sub === 'report-event') { + if (tool === 'plugin_feature_used') usage.push([e.argv[e.argv.indexOf('--feature') + 1]!, e.argv[e.argv.indexOf('--outcome') + 1]!]) + return { value: { exitCode: 0, stdout: '', stderr: '' } } + } const args = JSON.parse(String(e.argv[e.argv.indexOf('--args') + 1] ?? '{}')) const index = run++ calls.push({ tool, args, argv: e.argv }) @@ -136,7 +149,7 @@ async function start($: any, on: any, options: Options, session: { isInteractive }) await $.session.start({ cwd: ROOT, surface: 'terminal', isInteractive: session.isInteractive ?? true }) await clock.settle() - return { clock, calls, toasts, statuses } + return { clock, calls, toasts, statuses, usage } } async function endTurn($: any, clock: any, id: string) { @@ -862,3 +875,41 @@ test('the band line and the report', () => { test('the push gate waits for less than the tool chain gives a phase, so a held push is never given up on', () => { expect(GATE_WAIT_MS).toBeLessThan(PHASE_TIMEOUT_MS) }) + +test('with the push gate on, a held push sends one health_push_gate held usage event, and /health one opened', { options: { healthBlocksPush: true } }, async ($, on) => { + const { clock, usage } = await start($, on, { runs: [[OLD_STG], [OLD_STG, NEW_STG]], env: {} }) + await $.tool.call(edit(STG)) + await endTurn($, clock, 't1') + expect(((await $.tool.call(command('git push'))) as any)?.deny).toContain('1 new project health issue') + await clock.settle() + expect(usage).toEqual([['health_push_gate', 'held']]) + await $.command.run({ command: 'health', args: '' } as any) + await clock.settle() + expect(usage).toEqual([['health_push_gate', 'held'], ['health', 'opened']]) +}) + +test('with the push gate on, a push it lets through sends one health_push_gate allowed; a command that is no push sends nothing', { options: { healthBlocksPush: true } }, async ($, on) => { + const { clock, usage } = await start($, on, { runs: [[OLD_STG]], env: {} }) + await $.tool.call(command('git status')) + expect(((await $.tool.call(command('git push'))) as any)?.deny).toBeUndefined() + await clock.settle() + expect(usage).toEqual([['health_push_gate', 'allowed']]) +}) + +test('with the push gate off, a push is no use of the gate: no usage event', async ($, on) => { + const { clock, usage } = await start($, on, { runs: [[OLD_STG]], env: {} }) + await $.tool.call(command('git push')) + await $.tool.call(command('git status')) + await clock.settle() + expect(usage).toEqual([]) +}) + +test('with ALTIMATE_TELEMETRY_DISABLED the push gate holds as before and sends nothing', { options: { healthBlocksPush: true } }, async ($, on) => { + const { clock, usage } = await start($, on, { runs: [[OLD_STG], [OLD_STG, NEW_STG]], env: { ALTIMATE_TELEMETRY_DISABLED: '1' } }) + await $.tool.call(edit(STG)) + await endTurn($, clock, 't1') + expect(((await $.tool.call(command('git push'))) as any)?.deny).toContain('1 new project health issue') + await $.command.run({ command: 'health', args: '' } as any) + await clock.settle() + expect(usage).toEqual([]) +}) diff --git a/plugins/altimate-code/hooks/integrations.tsx b/plugins/altimate-code/hooks/integrations.tsx index 2cd5be5f..0dfa5398 100644 --- a/plugins/altimate-code/hooks/integrations.tsx +++ b/plugins/altimate-code/hooks/integrations.tsx @@ -9,6 +9,7 @@ import { startReviewNotices } from './review-notices' import { clearStatusParts, setStatusPart } from './status-line' import { registerTaskImpact, startTaskImpact, taskBand } from './task-impact' import { installToolChain } from './tool-chain' +import { sessionStarted } from './usage' const PANE = 'altimate-integrations' const PANE_TITLE = 'Altimate integrations' @@ -571,6 +572,8 @@ export const register: Register = (on, options) => { name: COMMAND, description: 'One-click GitHub, Jira and Linear integrations for your Altimate workspace', }) + // One anonymous usage event per session start, in the background. + sessionStarted($) // The lineage half failing to start must not stop this pane's own setup below. await startLineage($).catch(error => $.ui.log(`lineage-pane · could not start: ${String(error)}`)) await startTaskImpact($).catch(error => $.ui.log(`lineage-summary · could not start: ${String(error)}`)) diff --git a/plugins/altimate-code/hooks/lineage.tsx b/plugins/altimate-code/hooks/lineage.tsx index 5aab355c..51fb5580 100644 --- a/plugins/altimate-code/hooks/lineage.tsx +++ b/plugins/altimate-code/hooks/lineage.tsx @@ -12,6 +12,7 @@ import type { WarehouseView, } from '../types' import { later, parseJson, runTool, textOf, within } from './altimate-cli' +import { featureUsed } from './usage' import { featuresSessionEnd, featuresTurnComplete, featuresTurnStart } from './features' import { forgetPaneSizes, loadPaneSizesOnce, noteTerminal, paneTerminalColumns, paneRequest, sizeControls, type PaneSpec } from './pane-size' import { columnOf, drawingSize, drawLayered, drawStack, endsView, foldersView, graphView, sliceRows, type Layered, type ViewKind } from './lineage-layout' @@ -1232,8 +1233,10 @@ export function registerLineage(on: On, options: Record = {}) { try { await openPane($) } catch (error) { + featureUsed($, 'lineage', 'failed') return { text: `Could not open Altimate lineage: ${String(error)}` } } + featureUsed($, 'lineage', 'opened') // Fullscreen docks the pane beside the chat from 110 columns; otherwise it sits above the prompt. const where = e.presentation?.isFullscreen && e.presentation.columns >= DOCK_COLUMNS ? 'beside the chat' : 'above the prompt' if (model) { diff --git a/plugins/altimate-code/hooks/task-impact.test.tsx b/plugins/altimate-code/hooks/task-impact.test.tsx index d72d04f5..24d1a223 100644 --- a/plugins/altimate-code/hooks/task-impact.test.tsx +++ b/plugins/altimate-code/hooks/task-impact.test.tsx @@ -222,6 +222,7 @@ test('a task start copies the manifest aside, never reading it', async ($, on) = }) test("each session's manifest copies carry its id, so another session's task never replaces them; a task's end clears copies a day old", async ($, on) => { + mock.env(on, {}) const { runs, turn, tools, clock } = await start($, on) await turn('t1', async () => { await $.tool.call({ tool: 'Edit', file_path: MODEL, old_string: 'sum(amount) as revenue', new_string: 'sum(amount) * 2 as revenue' }) @@ -596,6 +597,7 @@ test('when no browser opens, the band shows the report path as a link', async ($ }) test('each step of the report sends one usage event through the CLI, with the action and the session only', async ($, on) => { + mock.env(on, {}) const { runs, turn, clock } = await start($, on, { uname: 'Linux', openers: { 'xdg-open': 3 } }) await turn('t1', async () => { await $.tool.call({ tool: 'Edit', file_path: MODEL, old_string: 'sum(amount) as revenue', new_string: 'sum(amount) * 2 as revenue' }) @@ -617,6 +619,19 @@ test('each step of the report sends one usage event through the CLI, with the ac } }) +test('with ALTIMATE_TELEMETRY_DISABLED the report works as before and no usage event is sent: no CLI is started for one', async ($, on) => { + mock.env(on, { ALTIMATE_TELEMETRY_DISABLED: 'true' }) + const { runs, turn, clock } = await start($, on, { uname: 'Linux', openers: { 'xdg-open': 3 } }) + await turn('t1', async () => { + await $.tool.call({ tool: 'Edit', file_path: MODEL, old_string: 'sum(amount) as revenue', new_string: 'sum(amount) * 2 as revenue' }) + }) + await clock.settle() + await $.command.run({ command: 'lineage-report', args: '' } as any) + await clock.settle() + expect(runs.some(argv => argv.includes('xdg-open'))).toBe(true) + expect(runs.filter(argv => argv[2] === 'report-event')).toEqual([]) +}) + test('macOS opens with open; /lineage-report before any report says so', async ($, on) => { const { runs, turn } = await start($, on, { uname: 'Darwin', openers: { open: 0 } }) const none: any = await $.command.run({ command: 'lineage-report', args: '' } as any) diff --git a/plugins/altimate-code/hooks/task-impact.tsx b/plugins/altimate-code/hooks/task-impact.tsx index 51284221..facfb88d 100644 --- a/plugins/altimate-code/hooks/task-impact.tsx +++ b/plugins/altimate-code/hooks/task-impact.tsx @@ -6,6 +6,7 @@ import type { EngineInterface, On, RenderElement } from 'claude-code' import type { PlanImpactView, TaskSummaryView } from '../types' import { later, runAltimate, runTool, within } from './altimate-cli' +import { usageOff } from './usage' import { answerOf, changedColumns, @@ -313,11 +314,12 @@ export type ReportAction = 'summary_shown' | 'open_pressed' | 'command_run' | 'b /** * One usage event about the report, through altimate-code's telemetry (`tool report-event`), in the - * background. It carries the action and this session's id only, and the CLI drops it under the telemetry - * opt-out; an altimate-code without the command refuses it, and nothing else happens. + * background. It carries the action and this session's id only. Under the telemetry opt-out no CLI is + * started, and the CLI drops it under its own; an altimate-code without the command refuses it, and nothing else happens. */ export function reportEvent($: EngineInterface, action: ReportAction) { later($, async () => { + if (await usageOff($)) return const id = await $.session.id() await runAltimate($, ['tool', 'report-event', action, '--session', `claude:${id}`], 15_000).catch(() => null) }) diff --git a/plugins/altimate-code/hooks/usage.test.tsx b/plugins/altimate-code/hooks/usage.test.tsx new file mode 100644 index 00000000..8ff2cf6b --- /dev/null +++ b/plugins/altimate-code/hooks/usage.test.tsx @@ -0,0 +1,273 @@ +import { expect, mock, test } from 'claude-code/testing' + +import { nothingToReport } from './inert-features' + +const ROOT = '/work/acme_secret_project' +const MODEL = 'fct_orders' +const SESSION = 'a1b2c3d4-0000-4000-8000-000000000001' +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/ + +// What the CLI is allowed to receive: the flags of each action and the shape of each value. +const ALLOWED: Record = { + '--session': /^claude:[A-Za-z0-9_-]{1,128}$/, + '--plugin-version': /^(\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?|unknown)$/, + '--install-id': UUID, + '--os': /^(macos|linux|windows|wsl|unknown)$/, + '--feature': /^(lineage|dbt_show|profile_ctes|scan_cost|comments|sql_graph|health|runs|to_model|cost_gate|health_push_gate)$/, + '--outcome': /^(opened|failed|held|allowed)$/, +} + +type Options = { + /** The environment the plugin reads; unset means nothing is set. */ + env?: Record + /** What the store holds at the start; shared across sessions when the same object is passed. */ + store?: Map + /** How `altimate tool report-event` answers, in place of success. */ + event?: (argv: string[]) => Promise<{ exitCode: number; stdout: string; stderr: string }> | { exitCode: number; stdout: string; stderr: string } + /** The manifest's version. */ + version?: string + platform?: string + /** `$.ui.open` fails. */ + openFails?: boolean +} + +/** A dbt project, the CLI answering every other feature with nothing to report, and each usage event recorded. */ +async function start($: any, on: any, options: Options = {}) { + const clock = mock.clock(on) + mock.env(on, options.env ?? {}) + const store = options.store ?? new Map() + const events: string[][] = [] + const toasts: string[] = [] + const logs: { text: string; to?: string }[] = [] + on('store.get', (_: unknown, e: { key: string }) => ({ value: store.get(e.key) })) + on('store.set', (_: unknown, e: { key: string; value: unknown }) => { + store.set(e.key, JSON.parse(JSON.stringify(e.value))) + return { value: undefined } + }) + on('session.id', () => ({ value: SESSION })) + on('session.info', () => ({ value: { platform: options.platform ?? 'macos', isHosted: false } })) + on('session.start', (_: unknown, e: { cwd: string }) => ({ cwd: e.cwd })) + on('session.root', () => ({ value: ROOT })) + on('session.cwd', () => ({ value: ROOT })) + on('command.register', (_: unknown, e: { name: string }) => ({ value: { command: e.name } })) + on('turn.start', (_: unknown, e: { turnId: string }) => ({ turnId: e.turnId })) + on('turn.complete', (_: unknown, e: { answer: string }) => ({ text: e.answer })) + on('session.end', () => ({ sessionId: 'test' })) + on('ui.open', () => { + if (options.openFails) throw new Error('no room for a pane') + return { value: {} } + }) + on('ui.status', () => ({ value: undefined })) + on('ui.toast', (_: unknown, e: { text: string }) => { + // The dbt doctor's own toast at session start (no dbt here) is not this test's. + if (!e.text.startsWith('⚕ dbt doctor')) toasts.push(e.text) + return { value: undefined } + }) + on('ui.log', (_: unknown, e: { text: string; to?: string }) => { + logs.push(e) + return { value: undefined } + }) + on('ui.render', ($$: any, e: any) => { + const { Box } = $$.ui.resolve(e) + return + }) + on('fs.exists', (_: unknown, e: { path: string }) => ({ value: e.path === `${ROOT}/dbt_project.yml` })) + on('fs.stat', () => { + throw new Error('ENOENT') + }) + on('fs.list', () => ({ value: [] })) + on('fs.read', (_: unknown, e: { path: string }) => { + if (e.path.endsWith('/.claude-plugin/plugin.json')) return { value: JSON.stringify({ name: 'altimate-code', version: options.version ?? '1.8.2' }) } + if (e.path === `${ROOT}/dbt_project.yml`) return { value: "name: 'acme_secret_project'\n" } + if (e.path === `${ROOT}/models/${MODEL}.sql`) return { value: 'select order_id, secret_column from raw.orders' } + throw new Error('ENOENT ' + e.path) + }) + on('tool.list', () => ({ value: [] })) + on('mcp.connect', () => ({ value: { isConnected: false, reason: 'not_connected', message: 'off' } })) + on('tool.call', () => ({ result: { ok: true } })) + on('process.run', async (_: unknown, e: { argv: readonly string[] }) => { + const argv = [...e.argv] + if (argv[1] === 'tool' && argv[2] === 'report-event') { + events.push(argv) + return { value: options.event ? await options.event(argv) : { exitCode: 0, stdout: '', stderr: '' } } + } + const inert = nothingToReport(argv) + if (inert) return { value: inert } + return { value: { exitCode: 1, stdout: '', stderr: 'not this test' } } + }) + await $.session.start({ cwd: ROOT, surface: 'terminal', isInteractive: true }) + await clock.settle() + const usage = () => events.filter(argv => argv[3]?.startsWith('plugin_')) + const flag = (argv: string[], name: string) => argv[argv.indexOf(name) + 1] + return { clock, store, events, usage, flag, toasts, logs } +} + +const run = async ($: any, clock: any, command: string, args = '') => { + const answer = await $.command.run({ command, args } as any) + await clock.settle() + return answer +} + +test('a first session start sends exactly one plugin_session_start with the plugin version, the OS and a new install id', async ($, on) => { + const { usage, flag, store } = await start($, on) + const events = usage() + expect(events).toHaveLength(1) + const [argv] = events + expect(argv!.slice(0, 4)).toEqual(['altimate', 'tool', 'report-event', 'plugin_session_start']) + expect(flag(argv!, '--session')).toBe(`claude:${SESSION}`) + expect(flag(argv!, '--plugin-version')).toBe('1.8.2') + expect(flag(argv!, '--os')).toBe('macos') + expect(flag(argv!, '--install-id')).toMatch(UUID) + // The install id is the one kept in the plugin's store. + expect(store.get('usage.installId')).toBe(flag(argv!, '--install-id')) +}) + +test("the install id stays the same across sessions on the machine: the next session's start sends the one kept", async ($, on) => { + const store = new Map() + const first = await start($, on, { store }) + const id = first.flag(first.usage()[0]!, '--install-id') + await $.session.start({ cwd: ROOT, surface: 'terminal', isInteractive: true }) + await first.clock.settle() + const starts = first.usage().filter(argv => argv[3] === 'plugin_session_start') + expect(starts).toHaveLength(2) + expect(starts.map(argv => first.flag(argv, '--install-id'))).toEqual([id, id]) + expect([...store.keys()].filter(key => key === 'usage.installId')).toHaveLength(1) +}) + +test('an install id kept from an earlier run is sent as it is; one that is not a UUID is replaced', async ($, on) => { + const kept = '0f3c2a1e-6b7d-4c8e-9f10-1a2b3c4d5e6f' + const { usage, flag } = await start($, on, { store: new Map([['usage.installId', kept]]) }) + expect(flag(usage()[0]!, '--install-id')).toBe(kept) +}) + +test('a broken install id in the store is replaced with a fresh UUID', async ($, on) => { + const store = new Map([['usage.installId', '/Users/someone/project']]) + const { usage, flag } = await start($, on, { store }) + const id = flag(usage()[0]!, '--install-id') + expect(id).toMatch(UUID) + expect(store.get('usage.installId')).toBe(id) +}) + +test('the OS is sent as Claude Code names it, and anything else as unknown; an unreadable version as unknown', async ($, on) => { + const { usage, flag } = await start($, on, { platform: 'wsl', version: 'not a version' }) + expect(flag(usage()[0]!, '--os')).toBe('wsl') + expect(flag(usage()[0]!, '--plugin-version')).toBe('unknown') +}) + +test('each panel and command sends one plugin_feature_used with its name when opened', async ($, on) => { + const { clock, usage, flag } = await start($, on) + const commands: [string, string, string][] = [ + ['lineage', MODEL, 'lineage'], + ['dbt-show', MODEL, 'dbt_show'], + ['profile-ctes', MODEL, 'profile_ctes'], + ['scan-cost', '', 'scan_cost'], + ['comments', '', 'comments'], + ['sql-graph', MODEL, 'sql_graph'], + ['health', '', 'health'], + ['runs', '', 'runs'], + ['to-model', `models/${MODEL}.sql`, 'to_model'], + ] + for (const [command, args, feature] of commands) { + const before = usage().length + await run($, clock, command, args) + const sent = usage().slice(before) + expect({ command, sent: sent.map(argv => [argv[3], flag(argv, '--feature'), flag(argv, '--outcome')]) }).toEqual({ command, sent: [['plugin_feature_used', feature, 'opened']] }) + } +}) + +test('a panel that cannot open sends failed, not opened', async ($, on) => { + const { clock, usage, flag } = await start($, on, { openFails: true }) + for (const [command, args, feature] of [ + ['lineage', '', 'lineage'], + ['dbt-show', '', 'dbt_show'], + ['comments', '', 'comments'], + ['runs', '', 'runs'], + ['sql-graph', MODEL, 'sql_graph'], + ['profile-ctes', MODEL, 'profile_ctes'], + ] as const) { + const before = usage().length + await run($, clock, command, args) + expect(usage().slice(before).map(argv => [flag(argv, '--feature'), flag(argv, '--outcome')])).toEqual([[feature, 'failed']]) + } +}) + +test('no event carries a project, model or column name, SQL or a path: only the allowed flags, each value of its shape', async ($, on) => { + const { clock, usage } = await start($, on) + for (const [command, args] of [ + ['lineage', `${MODEL}.secret_column`], + ['dbt-show', 'select secret_column from raw.orders'], + ['sql-graph', MODEL], + ['to-model', `models/${MODEL}.sql`], + ['health', ''], + ]) + await run($, clock, command!, args) + const events = usage() + expect(events.length).toBeGreaterThan(5) + for (const argv of events) { + expect(argv.slice(0, 3)).toEqual(['altimate', 'tool', 'report-event']) + const flags = argv.slice(4) + expect(flags.length % 2).toBe(0) + for (let i = 0; i < flags.length; i += 2) { + const [name, value] = [flags[i]!, flags[i + 1]!] + expect(Object.keys(ALLOWED)).toContain(name) + expect(value).toMatch(ALLOWED[name]!) + } + expect(argv.join(' ')).not.toMatch(/acme|secret|fct_orders|orders|select|\/work|models/) + } +}) + +for (const [name, env] of [ + ['ALTIMATE_TELEMETRY_DISABLED=true', { ALTIMATE_TELEMETRY_DISABLED: 'true' }], + ['ALTIMATE_TELEMETRY_DISABLED=1', { ALTIMATE_TELEMETRY_DISABLED: '1' }], + ['ALTIMATE_TELEMETRY_DISABLED=TRUE', { ALTIMATE_TELEMETRY_DISABLED: 'TRUE' }], + ['OPENCODE_DISABLE_TELEMETRY=1', { OPENCODE_DISABLE_TELEMETRY: '1' }], +] as const) { + test(`with ${name} no event is sent, no CLI is started for one, and no install id is made`, async ($, on) => { + const { clock, events, store } = await start($, on, { env }) + for (const [command, args] of [ + ['lineage', MODEL], + ['runs', ''], + ['health', ''], + ['scan-cost', ''], + ]) + await run($, clock, command!, args) + expect(events).toEqual([]) + expect(store.has('usage.installId')).toBe(false) + }) +} + +test('ALTIMATE_TELEMETRY_DISABLED set to something else (false, 0) leaves usage on, as the CLI reads it', async ($, on) => { + const { usage } = await start($, on, { env: { ALTIMATE_TELEMETRY_DISABLED: 'false', OPENCODE_DISABLE_TELEMETRY: '0' } }) + expect(usage()).toHaveLength(1) +}) + +test('an altimate-code without the new actions refuses them: nothing is shown, no toast, nothing logged outside the debug log', async ($, on) => { + const refused = { exitCode: 1, stdout: '', stderr: 'the action must be one of summary_shown, open_pressed, command_run, built, build_failed, no_browser' } + const { clock, usage, toasts, logs } = await start($, on, { event: () => refused }) + const answer: any = await run($, clock, 'runs') + expect(answer.text).toBe('The dbt runs are open.') + expect(usage().map(argv => argv[3])).toEqual(['plugin_session_start', 'plugin_feature_used']) + expect(toasts).toEqual([]) + expect(logs.filter(log => log.to !== 'debug' && /report-event|usage|plugin_/.test(log.text))).toEqual([]) +}) + +test('an altimate-code without report-event at all, or none on PATH, is silent too', async ($, on) => { + const { clock, usage, toasts } = await start($, on, { + event: argv => { + if (argv[0] === 'altimate') throw new Error('spawn altimate ENOENT') + return { exitCode: 1, stdout: '', stderr: 'Unknown argument: report-event' } + }, + }) + await run($, clock, 'health') + // Both names are tried, as for every CLI call; neither answer is shown. + expect(usage().length).toBeGreaterThan(0) + expect(toasts).toEqual([]) +}) + +test('an event never holds a hook: a CLI that never answers leaves the session start and the command answering at once', async ($, on) => { + const never = new Promise(() => {}) + const { clock, usage } = await start($, on, { event: () => never }) + const answer: any = await run($, clock, 'runs') + expect(answer.text).toBe('The dbt runs are open.') + expect(usage().map(argv => argv[3])).toEqual(['plugin_session_start', 'plugin_feature_used']) +}) diff --git a/plugins/altimate-code/hooks/usage.ts b/plugins/altimate-code/hooks/usage.ts new file mode 100644 index 00000000..4e8fbd90 --- /dev/null +++ b/plugins/altimate-code/hooks/usage.ts @@ -0,0 +1,97 @@ +// Anonymous usage events, sent through altimate-code's own telemetry (`altimate tool report-event`): the +// plugin opens no network connection of its own. A session start carries the plugin version, the OS and a +// random install id kept in this plugin's Claude Code store (the CLI adds its own version); a feature +// used carries which panel, command or gate, and its outcome. Nothing else: no project, model, column or +// file names, SQL or session text. The CLI checks every value against a fixed list or pattern. +// +// Every event runs in the background and is never awaited by a hook. With the telemetry opt-out set, no +// CLI is started and no install id is made; the CLI also drops events under its own opt-out (its config). +// An altimate-code without these actions refuses them, and nothing is shown. +import type { EngineInterface } from 'claude-code' + +import { later, runAltimate } from './altimate-cli' + +export type Feature = + | 'lineage' + | 'dbt_show' + | 'profile_ctes' + | 'scan_cost' + | 'comments' + | 'sql_graph' + | 'health' + | 'runs' + | 'to_model' + | 'cost_gate' + | 'health_push_gate' + +/** A panel opened or could not open; a gate held a command or let it through. */ +export type Outcome = 'opened' | 'failed' | 'held' | 'allowed' + +const INSTALL_ID_KEY = 'usage.installId' +const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/ +const VERSION = /^\d{1,6}\.\d{1,6}\.\d{1,6}(?:-[0-9A-Za-z.-]{1,32})?$/ +const OS = new Set(['macos', 'linux', 'windows', 'wsl']) +const EVENT_TIMEOUT_MS = 15_000 + +// The CLI's own reading of its opt-out: "true" or "1", any case. +const isSet = (value: string | undefined) => value !== undefined && ['true', '1'].includes(value.toLowerCase()) + +/** True when the telemetry opt-out is set, or the environment cannot be read (then nothing is sent). */ +export async function usageOff($: EngineInterface): Promise { + try { + const [altimate, opencode] = await Promise.all([$.env.get('ALTIMATE_TELEMETRY_DISABLED'), $.env.get('OPENCODE_DISABLE_TELEMETRY')]) + return isSet(altimate) || isSet(opencode) + } catch { + return true + } +} + +/** The anonymous install id: made on first run and kept in this plugin's store, so it stays the same across sessions. */ +export async function installId($: EngineInterface): Promise { + const kept = await $.store.get(INSTALL_ID_KEY) + if (typeof kept === 'string' && UUID.test(kept)) return kept + const made = crypto.randomUUID().toLowerCase() + await $.store.set(INSTALL_ID_KEY, made) + return made +} + +let ownVersion: string | null = null + +/** This plugin's version from its manifest, or `unknown`. */ +async function pluginVersion($: EngineInterface): Promise { + if (ownVersion) return ownVersion + const version = await $.fs + .read(`${$.plugin.root}/.claude-plugin/plugin.json`) + .then(text => (JSON.parse(text) as { version?: unknown }).version) + .catch(() => undefined) + return (ownVersion = typeof version === 'string' && VERSION.test(version) ? version : 'unknown') +} + +async function send($: EngineInterface, action: 'plugin_session_start' | 'plugin_feature_used', fields: string[]) { + if (await usageOff($)) return + const session = await $.session.id() + const [version, install] = await Promise.all([pluginVersion($), installId($)]) + const argv = ['tool', 'report-event', action, '--session', `claude:${session}`, '--plugin-version', version, '--install-id', install, ...fields] + // An older CLI answers with an error: it is not this plugin's to show. + await runAltimate($, argv, EVENT_TIMEOUT_MS).catch(() => null) +} + +/** One `plugin_session_start`, in the background. Never throws: a usage event never stops a hook. */ +export function sessionStarted($: EngineInterface) { + try { + later($, async () => { + const platform = await $.session + .info() + .then(info => info.platform) + .catch(() => undefined) + await send($, 'plugin_session_start', ['--os', platform && OS.has(platform) ? platform : 'unknown']) + }) + } catch {} +} + +/** One `plugin_feature_used`, in the background. Never throws: a usage event never stops a hook. */ +export function featureUsed($: EngineInterface, feature: Feature, outcome: Outcome) { + try { + later($, () => send($, 'plugin_feature_used', ['--feature', feature, '--outcome', outcome])) + } catch {} +} From e1bd950809096fa81c9c1eff2bed2e92f7755480 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Thu, 19 Nov 2026 17:01:17 +0530 Subject: [PATCH 2/8] fix: every cost hold, the comments band's Open and /to-model's pane are counted once; one install id per first run Co-Authored-By: Claude Opus 5.5 --- PRIVACY.md | 2 +- .../altimate-code/hooks/features/comments.tsx | 16 ++++- .../hooks/features/cost.test.tsx | 12 ++++ plugins/altimate-code/hooks/features/cost.tsx | 3 +- .../altimate-code/hooks/features/to-model.tsx | 3 +- plugins/altimate-code/hooks/usage.test.tsx | 66 ++++++++++++++++++- plugins/altimate-code/hooks/usage.ts | 20 ++++-- 7 files changed, 111 insertions(+), 11 deletions(-) diff --git a/PRIVACY.md b/PRIVACY.md index 404adc15..9f54fa48 100644 --- a/PRIVACY.md +++ b/PRIVACY.md @@ -118,7 +118,7 @@ To count installs, active use and which features are used, the plugin asks the l | `plugin_feature_used` | A panel or command opens: `/lineage` (`lineage`), `/dbt-show` (`dbt_show`), `/profile-ctes` (`profile_ctes`), `/scan-cost` (`scan_cost`), `/comments` (`comments`), `/sql-graph` (`sql_graph`), `/health` (`health`), `/runs` (`runs`), `/to-model` (`to_model`); the cost check holds a dbt command or `/allow-scan` allows it (`cost_gate`); with "Project health blocks git push" on, the push gate holds or lets through a `git push` (`health_push_gate`) | `feature` (the name in brackets); `outcome`: `opened`, `failed` (the panel could not open), `held` or `allowed`; `plugin_version`; `install_id`; `session_id` | - **`install_id`** is a random UUID the plugin makes the first time it sends an event and keeps in its own Claude Code plugin store (a JSON file under your Claude Code configuration directory), so it stays the same across sessions on this machine. It is not derived from your machine, account or project, and is not made while `ALTIMATE_TELEMETRY_DISABLED` is set. Removing the plugin's store data makes a new one. -- Beside these fields, each event carries what every altimate-code telemetry event carries (the CLI version, its anonymous machine id, a per-launch id), as described in [Usage telemetry](#usage-telemetry). +- Beside these fields, each event carries the CLI's anonymous envelope (the CLI version, its random machine id, a per-launch id), as described in [Usage telemetry](#usage-telemetry). Unlike the CLI's other events, these never carry your Altimate account (no user id or tenant), even when you are signed in. - No event contains project, model, column or file names, SQL, query results or session text. The CLI accepts each field only from a fixed list or pattern (a version, a UUID, one of the names above) and refuses anything else. - **Turning it off:** `ALTIMATE_TELEMETRY_DISABLED=true` (or `1`) in the environment Claude Code starts in: the plugin then starts no CLI for these events, or for the lineage report's, and makes no install id. The CLI also drops them under its own opt-out (`ALTIMATE_TELEMETRY_DISABLED`, or `telemetry.disabled` in its config), as for every other event. - The events are sent in the background and never delay a hook. An altimate-code that predates them refuses them, and nothing is sent or shown. diff --git a/plugins/altimate-code/hooks/features/comments.tsx b/plugins/altimate-code/hooks/features/comments.tsx index b7310f58..bc1d1774 100644 --- a/plugins/altimate-code/hooks/features/comments.tsx +++ b/plugins/altimate-code/hooks/features/comments.tsx @@ -249,7 +249,21 @@ export async function bandLine($: EngineInterface, ui: BandUi): Promise -