Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
feat(telemetry): count npm installs, so the funnel has a top (#273)
anirudhkumar-nanonetsa0ae727b2218
diff --git a/TELEMETRY.md b/TELEMETRY.mdindex 8d00e542..dcb57d75 100644--- a/TELEMETRY.md+++ b/TELEMETRY.md@@ -16,6 +16,12 @@ Nothing is ever sent from a command you run. Events are appended to a local fileand a detached background process posts them at most once a day, so no `graftask` ever waits on the network.+The one exception is the `install` event below, which the npm postinstall hook+records and hands to that same detached process immediately — an install that+never runs a command would otherwise never reach a flush, and "installed and+never used" is a number we need to see. `npm install` itself still waits on+nothing: the child is detached and its output discarded.+## What is sentEvery event carries only these common properties:@@ -34,7 +40,8 @@ The events:| Event | Extra properties | When || --- | --- | --- |-| `first_run` | — | Once, the first time graft runs on a machine |+| `install` | `global` (`true` for `npm i -g`, `false` for a project dependency) | The npm postinstall hook runs — once per machine per version |+| `first_run` | — | Once, the first time a graft command runs on a machine || `init_completed` | `agents` (the ids you selected, sorted), `consent` | `graft init` finishes || `build_completed` | `files_bucket`, `langs`, `mode` (`fast`/`deep`), `duration_bucket`, `incremental` | A build succeeds || `build_failed` | `stage`, `code` — both fixed enums | A build throws |diff --git a/scripts/postinstall.mjs b/scripts/postinstall.mjsindex 221237d8..8d4422d6 100644--- a/scripts/postinstall.mjs+++ b/scripts/postinstall.mjs@@ -1,9 +1,48 @@-// Prints a one-line nudge after install. Never fails the install.+// Prints a one-line nudge after install, and records the anonymous `install`+// event. Never fails the install.+import { existsSync } from 'node:fs';+import { spawn } from 'node:child_process';+import { dirname, join } from 'node:path';+import { fileURLToPath, pathToFileURL } from 'node:url';++const root = dirname(dirname(fileURLToPath(import.meta.url)));++/**+ * Record the install, then hand the queue straight to a detached child.+ *+ * Sending here rather than letting the daily flush pick it up is the entire+ * point of the event: the machine we most want to count is the one that installs+ * graft and never runs a command, and that machine never reaches a flush. The+ * child is detached with stdio ignored, so npm waits on no socket and an offline+ * install looks like any other.+ *+ * Every gate still applies — a fork or a local build has no key, and CI,+ * `DO_NOT_TRACK` and `graft telemetry disable` all close it. See TELEMETRY.md.+ */+async function recordInstall() {+ // `dist/` is absent when this runs from a clone, where `prepare` builds AFTER+ // postinstall. Nothing to record there, and a fork has no key regardless.+ const entry = join(root, 'dist', 'telemetry', 'index.js');+ const cli = join(root, 'dist', 'cli.js');+ if (!existsSync(entry) || !existsSync(cli)) return;+ const mod = await import(pathToFileURL(entry).href);+ // A `dist/` from an older version has no such export. Absent, not broken.+ if (typeof mod.trackInstallIfNew !== 'function') return;+ // npm sets this for `npm i -g`; only its value 'true' means global.+ mod.trackInstallIfNew({ global: process.env.npm_config_global === 'true' });+ const child = spawn(process.execPath, [cli, '_telemetry-flush'], {+ detached: true,+ stdio: 'ignore',+ });+ child.unref();+}+try {if (process.env.CI) process.exit(0);- const { existsSync } = await import('node:fs');- const { join } = await import('node:path');const dir = process.env.INIT_CWD || process.cwd();+ // Its own catch: the nudge is the part a user sees, and a telemetry fault must+ // not be able to silence it.+ try { await recordInstall(); } catch { /* telemetry is never worth an error */ }if (existsSync(join(dir, '.claude', 'helpers', 'graft-statusline.cjs'))) process.exit(0);console.log('\n Graft installed. Run `npx graft init` to enable the Claude Code integration (statusline + hooks + auto-sync).\n');} catch {diff --git a/src/telemetry/contract.ts b/src/telemetry/contract.tsindex f62884d3..10663153 100644--- a/src/telemetry/contract.ts+++ b/src/telemetry/contract.ts@@ -30,7 +30,16 @@* centrally by `track()` and are deliberately not repeated per event.*/export const EVENTS: Record<string, ReadonlySet<string>> = {- /** Once per machine, when the install id is first minted. The denominator. */+ /** Once per machine per version, from the npm postinstall hook. The real+ * denominator: a machine that installs graft and never runs a command emits+ * this event and no other, so it is the only place the "installed, never+ * used" leak is visible at all. Version-scoped rather than once-ever so an+ * upgrade counts; distinct install ids still give unique machines.+ * `global` separates `npm i -g graft` from a project dependency, which is+ * roughly the difference between a person and a lockfile. */+ install: new Set<string>(['global']),+ /** Once per machine, the first time a command actually runs. Paired with+ * `install`, the gap between the two is the top of the funnel. */first_run: new Set<string>(),/** `graft init` completed. Tells us which agents people actually wire, and* how many decline telemetry at the picker. */diff --git a/src/telemetry/identity.ts b/src/telemetry/identity.tsindex a77f515f..042284a9 100644--- a/src/telemetry/identity.ts+++ b/src/telemetry/identity.ts@@ -31,6 +31,13 @@ export interface TelemetryState {enabled?: boolean;/** ISO stamp of the one-time first-run notice, so it prints exactly once. */noticeShownAt?: string;+ /** ISO stamp of the `first_run` event. Its own field rather than "did this+ * call mint the install id", because the postinstall hook now mints the id+ * before any command runs — see `trackFirstRunIfNew`. */+ firstRunAt?: string;+ /** The version the `install` event was last sent for, so an upgrade counts as+ * an install and a repeated `npm install` of the same version does not. */+ installedVersion?: string;/** Epoch ms of the last flush ATTEMPT, mirroring `UpdateCache.checkedAt`. */flushedAt?: number;}diff --git a/src/telemetry/index.ts b/src/telemetry/index.tsindex eab62bac..0880932c 100644--- a/src/telemetry/index.ts+++ b/src/telemetry/index.ts@@ -8,7 +8,7 @@*/export { EVENTS, COMMON_KEYS, isTrackedCommand, errorCode, filesBucket, durationBucket, countBucket, savedTokensBucket, langsValue } from './contract.js';export type { AgentHost, Surface, TrackedCommand, BuildStage, ErrorCode } from './contract.js';-export { track, trackFirstRunIfNew, detectHost } from './track.js';+export { track, trackFirstRunIfNew, trackInstallIfNew, detectHost } from './track.js';export type { QueuedEvent, TrackContext } from './track.js';export { telemetryOn, offReason, explainOff } from './gate.js';export { maybeFlushInBackground, runFlush } from './flush.js';diff --git a/src/telemetry/track.ts b/src/telemetry/track.tsindex f60a5a54..e57f8fb1 100644--- a/src/telemetry/track.ts+++ b/src/telemetry/track.ts@@ -21,7 +21,7 @@ import { EVENTS } from './contract.js';import type { AgentHost } from './contract.js';import { enqueue } from './queue.js';import { telemetryOn } from './gate.js';-import { installId, repoId } from './identity.js';+import { installId, patchState, readState, repoId } from './identity.js';import { runningVersion } from '../upkeep.js';/** One queued event, exactly as it will be sent. */@@ -115,14 +115,41 @@ export function track(}/**- * The `first_run` event, fired the once. Separate from `track` because it is the- * only event whose trigger is "the id did not exist a moment ago", which only- * `installId()` can know.+ * The `first_run` event, fired the once. Separate from `track` because its+ * trigger is a comparison against persisted state rather than anything a call+ * site knows.+ *+ * Gated on `firstRunAt` and NOT on `installId().firstRun`, which is the whole+ * reason this field exists: the npm postinstall hook mints the install id before+ * any command runs, so "did this call mint the id" is false on the genuine first+ * command and would have silenced this event permanently.*/export function trackFirstRunIfNew(ctx: TrackContext = {}): void {try {if (!telemetryOn(ctx.home, ctx.env)) return;- if (!installId(ctx.home).firstRun) return;+ if (readState(ctx.home)?.firstRunAt) return;track('first_run', {}, ctx);+ patchState({ firstRunAt: new Date().toISOString() }, ctx.home);+ } catch { /* never */ }+}++/**+ * The `install` event, fired from the npm postinstall hook.+ *+ * Once per machine per version: an upgrade is a real install and worth counting,+ * a second `npm install` of a version already recorded is not. Unique machines+ * are then distinct install ids, exactly as for every other event.+ *+ * Nothing here is an exception to the gates — a fork with no key, CI,+ * `DO_NOT_TRACK` and `graft telemetry disable` all still close it. It is only a+ * call site that happens to run outside a command.+ */+export function trackInstallIfNew(ctx: TrackContext & { global?: boolean } = {}): void {+ try {+ if (!telemetryOn(ctx.home, ctx.env)) return;+ const version = runningVersion();+ if (readState(ctx.home)?.installedVersion === version) return;+ track('install', { global: String(ctx.global ?? false) }, ctx);+ patchState({ installedVersion: version }, ctx.home);} catch { /* never */ }}diff --git a/test/telemetry-contract.test.ts b/test/telemetry-contract.test.tsindex 423d3c79..a9c65200 100644--- a/test/telemetry-contract.test.ts+++ b/test/telemetry-contract.test.ts@@ -73,9 +73,10 @@ test('every event carries the common properties, and no identifier beyond them',assert.match(ev.distinct_id, /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);});-test('the contract lists exactly the six documented events', () => {+test('the contract lists exactly the seven documented events', () => {assert.deepEqual(Object.keys(EVENTS).sort(), [- 'build_completed', 'build_failed', 'first_run', 'init_completed', 'query', 'session_summary',+ 'build_completed', 'build_failed', 'first_run', 'init_completed', 'install', 'query',+ 'session_summary',]);});diff --git a/test/telemetry-install.test.ts b/test/telemetry-install.test.tsnew file mode 100644index 00000000..271e5b5d--- /dev/null+++ b/test/telemetry-install.test.ts@@ -0,0 +1,75 @@+/**+ * The `install` event — the top of the funnel, and the one event recorded from+ * outside a command.+ *+ * The regression these tests exist for is subtle and expensive: the postinstall+ * hook mints the install id before any command runs, which used to be exactly+ * the condition `first_run` fired on. Get it wrong and every install still+ * counts while `first_run` silently drops to zero, so the funnel looks like+ * nobody who installs graft ever runs it.+ */+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { mkdirSync } from 'node:fs';+import { join } from 'node:path';+import { patchState, readState } from '../src/telemetry/identity.js';+import { peek } from '../src/telemetry/queue.js';+import { trackFirstRunIfNew, trackInstallIfNew } from '../src/telemetry/track.js';+import { tmpRepo } from './helpers.js';++const OPEN: NodeJS.ProcessEnv = {};++function sandbox(tag: string): string {+ const home = tmpRepo(tag);+ mkdirSync(join(home, '.graft'), { recursive: true });+ process.env.GRAFT_POSTHOG_KEY = 'phc_test_key';+ return home;+}++function names(home: string): string[] {+ return peek(home).map((e) => (e as { event: string }).event);+}++test('install fires once per version, not once per npm install', () => {+ const home = sandbox('tel-install-once');+ trackInstallIfNew({ home, env: OPEN });+ trackInstallIfNew({ home, env: OPEN });+ assert.deepEqual(names(home), ['install']);+});++test('an upgrade counts as a new install', () => {+ const home = sandbox('tel-install-upgrade');+ trackInstallIfNew({ home, env: OPEN });+ // What an upgrade looks like from here: the recorded version is no longer the+ // running one.+ assert.ok(readState(home)?.installedVersion);+ patchState({ installedVersion: '0.0.1-old' }, home);+ trackInstallIfNew({ home, env: OPEN });+ assert.deepEqual(names(home), ['install', 'install']);+});++test('first_run still fires after the postinstall hook minted the install id', () => {+ const home = sandbox('tel-install-then-first-run');+ trackInstallIfNew({ home, env: OPEN });+ trackFirstRunIfNew({ home, env: OPEN });+ assert.deepEqual(names(home), ['install', 'first_run']);+ // And still exactly once.+ trackFirstRunIfNew({ home, env: OPEN });+ assert.deepEqual(names(home), ['install', 'first_run']);+});++test('the global flag is the only property, and it is a string', () => {+ const home = sandbox('tel-install-global');+ trackInstallIfNew({ home, env: OPEN, global: true });+ const ev = peek(home)[0] as { properties: Record<string, string> };+ assert.equal(ev.properties.global, 'true');+});++test('every gate closes the install event', () => {+ const off = sandbox('tel-install-gated');+ trackInstallIfNew({ home: off, env: { DO_NOT_TRACK: '1' } });+ assert.deepEqual(names(off), []);+ const ci = sandbox('tel-install-ci');+ trackInstallIfNew({ home: ci, env: { CI: 'true' } });+ assert.deepEqual(names(ci), []);+});