@colbymchenry/codegraph-darwin-x64 0.9.9 → 1.0.0

package/lib/dist/telemetry/index.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Anonymous usage telemetry — client side.
+ *
+ * The contract for what may be collected lives in docs/design/telemetry.md
+ * (and user-facing TELEMETRY.md); the ingest endpoint that enforces it is
+ * public at telemetry-worker/. This module honors four invariants:
+ *
+ * 1. Zero hot-path cost: recording is an in-memory increment. Disk writes are
+ *    a tiny synchronous append at process exit (works under `process.exit()`,
+ *    where `beforeExit` never fires); network sends happen opportunistically
+ *    (startup of long-running commands, daemon interval, bounded await at the
+ *    end of install/init) and are fire-and-forget everywhere else.
+ * 2. Zero stdout: stdio is the MCP protocol channel. Notices and debug output
+ *    go to stderr only.
+ * 3. Off is off: when disabled, nothing is recorded, nothing is sent, and no
+ *    socket is opened — there is no "opted out" ping. Turning telemetry off
+ *    also deletes any buffered, unsent data.
+ * 4. Fail silent: offline, endpoint down, disk full — every failure mode is
+ *    silence, never a retry loop, never an error surfaced to the user/agent.
+ *
+ * Usage counts aggregate locally into per-day rollups; only *completed* (UTC)
+ * days are sent, so volume scales with active machines, not with tool calls.
+ */
+export declare const TELEMETRY_ENDPOINT = "https://telemetry.getcodegraph.com/v1/events";
+export declare const TELEMETRY_DOCS = "https://github.com/colbymchenry/codegraph/blob/main/TELEMETRY.md";
+export type UsageKind = 'mcp_tool' | 'cli_command';
+export type LifecycleEvent = 'install' | 'index' | 'uninstall';
+/** Coarse buckets — exact counts are deliberately not collected. */
+export declare function bucketFileCount(n: number): '<100' | '100-1k' | '1k-10k' | '10k+';
+export declare function bucketDuration(ms: number): '<10s' | '10-60s' | '1-5m' | '5m+';
+/** Collapse a backend identifier (e.g. `node-sqlite`) to the schema's enum. */
+export declare function backendKind(backend: string): 'native' | 'wasm';
+/**
+ * Shared "a full index completed" event (CLI init/index + installer local
+ * init): language names and coarse buckets only — never paths, file names,
+ * or exact counts. Structurally typed so callers don't need engine imports.
+ */
+export declare function recordIndexEvent(cg: {
+    getStats(): {
+        filesByLanguage: Record<string, number>;
+    };
+    getBackend(): string;
+}, result: {
+    filesIndexed: number;
+    durationMs: number;
+}): void;
+export interface ClientInfo {
+    name?: string;
+    version?: string;
+}
+export interface TelemetryStatus {
+    enabled: boolean;
+    /** What decided the current state — mirrors the precedence order. */
+    decidedBy: 'DO_NOT_TRACK' | 'CODEGRAPH_TELEMETRY' | 'config' | 'default';
+    machineId: string | null;
+    configPath: string;
+}
+export interface TelemetryOptions {
+    /** Global state dir; defaults to ~/.codegraph. Tests inject a temp dir. */
+    dir?: string;
+    fetchImpl?: typeof globalThis.fetch;
+    now?: () => Date;
+    env?: NodeJS.ProcessEnv;
+    stderr?: (line: string) => void;
+    /** Tests opt out so short-lived instances don't pile onto process 'exit'. */
+    installExitHook?: boolean;
+}
+export declare class Telemetry {
+    private readonly dir;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly env;
+    private readonly writeStderr;
+    private counts;
+    private events;
+    private readonly installExitHook;
+    private exitHookInstalled;
+    private configCache;
+    private intervalHandle;
+    constructor(opts?: TelemetryOptions);
+    get configPath(): string;
+    get queuePath(): string;
+    /**
+     * Resolution order (first match wins) — keep in sync with TELEMETRY.md:
+     * DO_NOT_TRACK=1 > CODEGRAPH_TELEMETRY=0|1 > stored config > default on.
+     */
+    getStatus(): TelemetryStatus;
+    isEnabled(): boolean;
+    /**
+     * Persist an explicit user choice (installer toggle or `codegraph
+     * telemetry on|off`). Turning telemetry off also deletes any buffered,
+     * unsent data — off means off.
+     */
+    setEnabled(enabled: boolean, source: 'installer' | 'cli'): void;
+    /** True once any consent decision (or the first-run notice) is on disk. */
+    hasStoredChoice(): boolean;
+    /** In-memory increment — safe on the MCP tool-call hot path. */
+    recordUsage(kind: UsageKind, name: string, ok: boolean, client?: ClientInfo): void;
+    /** install / index / uninstall — buffered like everything else. */
+    recordLifecycle(event: LifecycleEvent, props: Record<string, unknown>): void;
+    /**
+     * Fire-and-forget send of everything sendable. Never throws, never logs
+     * above debug. Safe to call at startup of long-running commands.
+     */
+    maybeFlush(): void;
+    /**
+     * Drain in-memory state to the buffer, then send completed-day rollups and
+     * lifecycle events. Bounded by `timeoutMs`; leftovers stay buffered for the
+     * next process. Awaited only where latency is invisible (install/init).
+     */
+    flushNow(timeoutMs?: number): Promise<void>;
+    /**
+     * Periodic flush for long-lived processes (MCP daemon / serve). Unref'd so
+     * it never keeps the process alive.
+     */
+    startInterval(everyMs?: number): void;
+    stopInterval(): void;
+    private utcDay;
+    private readConfig;
+    private writeConfig;
+    /**
+     * Default-on consent is gated by a one-time stderr notice (interactive
+     * installs record their choice explicitly and never reach this).
+     */
+    private firstRunNotice;
+    /**
+     * Synchronous, tiny, exit-safe: drain in-memory deltas to the JSONL queue.
+     * Runs on `process.on('exit')`, so it must never be async or slow.
+     */
+    persistSync(): void;
+    private appendLines;
+    /**
+     * Atomically claim the queue for sending (rename). Concurrent processes
+     * can't double-send; a crash mid-send leaves a claim file that
+     * `recoverStaleClaims` merges back after an hour.
+     */
+    private claimQueue;
+    private recoverStaleClaims;
+    /** Returns the lines that did NOT make it out (to be re-queued). */
+    private send;
+    private packageVersion;
+    private ensureExitHook;
+    private debug;
+}
+export declare function getTelemetry(): Telemetry;
+//# sourceMappingURL=index.d.ts.map

package/lib/dist/telemetry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"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"}