codesift-mcp 0.9.10 → 0.10.0

package/dist/storage/_shared.js.map

@@ -1 +1 @@
-{"version":3,"file":"_shared.js","sourceRoot":"","sources":["../../src/storage/_shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,UAAkB,EAClB,OAAe;IAEf,MAAM,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAChC,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEtC,0EAA0E;IAC1E,4EAA4E;IAC5E,2DAA2D;IAC3D,MAAM,OAAO,GAAG,GAAG,UAAU,QAAQ,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IAE3G,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC3C,MAAM,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC;YAAC,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,yBAAyB,CAAC,CAAC;QAClE,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}
+{"version":3,"file":"_shared.js","sourceRoot":"","sources":["../../src/storage/_shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,UAAkB,EAClB,OAAe;IAEf,MAAM,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAChC,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEtC,0EAA0E;IAC1E,4EAA4E;IAC5E,2DAA2D;IAC3D,MAAM,OAAO,GAAG,GAAG,UAAU,QAAQ,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IAE3G,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC3C,MAAM,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC;YAAC,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,yBAAyB,CAAC,CAAC;QAClE,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,UAAkB,EAClB,GAAW;IAEX,MAAM,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAChC,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEtC,MAAM,OAAO,GAAG,GAAG,UAAU,QAAQ,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IAE3G,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC9B,MAAM,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC;YAAC,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,yBAAyB,CAAC,CAAC;QAClE,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/storage/telemetry/aggregator.d.ts

@@ -0,0 +1,52 @@
+import type { UsageEntry } from "../usage-tracker.js";
+export interface ToolAggregate {
+    tool: string;
+    day: string;
+    count: number;
+    p50_ms: number;
+    p95_ms: number;
+    max_ms: number;
+    error_rate: number;
+    empty_result_rate: number;
+    cache_hit_rate: number;
+}
+export interface HintEmission {
+    day: string;
+    hint_code: string;
+    emitted: number;
+    applied: number;
+}
+export interface PlanTurnFunnel {
+    day: string;
+    recommended: number;
+    used: number;
+}
+/**
+ * Pure aggregation over a set of usage entries. Groups by (tool, day) and
+ * derives count, latency p50/p95/max, error_rate, empty_result_rate and
+ * cache_hit_rate. Cache-served calls (`cache_hit === true`) are counted only
+ * toward cache_hit_rate — never latency/error/empty (they didn't execute).
+ * `empty_result_rate` uses result_chunks===0 — a query/path-free "did this
+ * call find anything" signal already on the entry.
+ */
+export declare function aggregateToolMetrics(entries: UsageEntry[]): ToolAggregate[];
+/**
+ * Hint efficacy funnel (spec §1): per (day, code), how often a hint was emitted
+ * on a call that had a follow-up, and how often that follow-up actually acted on
+ * it. Correlation is per session, in ts order, and reads only args_summary keys
+ * locally — the wire payload carries just the counts.
+ */
+export declare function aggregateHintFunnel(entries: UsageEntry[]): HintEmission[];
+/**
+ * Discovery funnel (spec §1): per day, how often plan_turn recommended >=1 tool
+ * (on a call with a follow-up) and how often the next call used one of them —
+ * i.e. is the router's advice actually taken?
+ */
+export declare function aggregatePlanTurnFunnel(entries: UsageEntry[]): PlanTurnFunnel[];
+/**
+ * Read + parse the local usage.jsonl (best-effort — skips malformed lines).
+ * `afterTs` is EXCLUSIVE (strictly greater) so it composes with an upload
+ * watermark (the max ts already sent) without re-sending the boundary entry.
+ */
+export declare function readLocalUsageEntries(afterTs?: number): Promise<UsageEntry[]>;
+//# sourceMappingURL=aggregator.d.ts.map

package/dist/storage/telemetry/aggregator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregator.d.ts","sourceRoot":"","sources":["../../../src/storage/telemetry/aggregator.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAyBD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,aAAa,EAAE,CA2C3E;AAiCD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,YAAY,EAAE,CAyBzE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,cAAc,EAAE,CAiB/E;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,SAAI,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAkB9E"}

package/dist/storage/telemetry/aggregator.js

@@ -0,0 +1,188 @@
+// Client-side aggregation: raw local usage entries → per-tool-per-day metrics.
+// We send aggregates, never raw events (spec §3) — smaller payload, less leak
+// surface. Only reads fields that already exist on UsageEntry.
+import { readFile } from "node:fs/promises";
+import { getUsagePath } from "../usage-tracker.js";
+function dayOf(ts) {
+    return new Date(ts).toISOString().slice(0, 10);
+}
+/** Nearest-rank percentile over an already-sorted-ascending array. */
+function percentile(sortedAsc, p) {
+    if (sortedAsc.length === 0)
+        return 0;
+    const idx = Math.min(sortedAsc.length - 1, Math.max(0, Math.ceil(p * sortedAsc.length) - 1));
+    return sortedAsc[idx];
+}
+const round3 = (n) => Math.round(n * 1000) / 1000;
+/**
+ * Pure aggregation over a set of usage entries. Groups by (tool, day) and
+ * derives count, latency p50/p95/max, error_rate, empty_result_rate and
+ * cache_hit_rate. Cache-served calls (`cache_hit === true`) are counted only
+ * toward cache_hit_rate — never latency/error/empty (they didn't execute).
+ * `empty_result_rate` uses result_chunks===0 — a query/path-free "did this
+ * call find anything" signal already on the entry.
+ */
+export function aggregateToolMetrics(entries) {
+    const buckets = new Map();
+    for (const e of entries) {
+        if (!e || typeof e.tool !== "string" || typeof e.ts !== "number")
+            continue;
+        const day = dayOf(e.ts);
+        const key = `${e.tool}\0${day}`;
+        let b = buckets.get(key);
+        if (!b) {
+            b = { tool: e.tool, day, latencies: [], errors: 0, empties: 0, executed: 0, cacheHits: 0 };
+            buckets.set(key, b);
+        }
+        if (e.cache_hit === true) {
+            b.cacheHits++;
+            continue;
+        }
+        b.executed++;
+        if (typeof e.elapsed_ms === "number" && Number.isFinite(e.elapsed_ms)) {
+            b.latencies.push(e.elapsed_ms);
+        }
+        if (e.error === true)
+            b.errors++;
+        if (e.result_chunks === 0)
+            b.empties++;
+    }
+    const out = [];
+    for (const b of buckets.values()) {
+        const sorted = b.latencies.slice().sort((a, c) => a - c);
+        const total = b.executed + b.cacheHits;
+        out.push({
+            tool: b.tool,
+            day: b.day,
+            count: total,
+            p50_ms: percentile(sorted, 0.5),
+            p95_ms: percentile(sorted, 0.95),
+            max_ms: sorted.length ? sorted[sorted.length - 1] : 0,
+            error_rate: b.executed ? round3(b.errors / b.executed) : 0,
+            empty_result_rate: b.executed ? round3(b.empties / b.executed) : 0,
+            cache_hit_rate: total ? round3(b.cacheHits / total) : 0,
+        });
+    }
+    // Deterministic order (day desc, then tool) — stable payloads, easier diffing.
+    out.sort((a, c) => (a.day === c.day ? a.tool.localeCompare(c.tool) : c.day.localeCompare(a.day)));
+    return out;
+}
+/** Group entries into per-session chains sorted by ts, for next-call correlation. */
+function sessionChains(entries) {
+    const bySession = new Map();
+    for (const e of entries) {
+        if (!e || typeof e.ts !== "number")
+            continue;
+        const s = typeof e.session_id === "string" ? e.session_id : "?";
+        (bySession.get(s) ?? bySession.set(s, []).get(s)).push(e);
+    }
+    for (const chain of bySession.values())
+        chain.sort((a, b) => a.ts - b.ts);
+    return [...bySession.values()];
+}
+const has = (e, k) => e.args_summary != null && typeof e.args_summary === "object" && k in e.args_summary;
+/** Did the follow-up call `n` act on hint `code`? Codes without a rule are
+ *  counted as emitted but never applied (honest under-report). */
+const HINT_APPLIED = {
+    H1: (n) => has(n, "group_by_file") && n.args_summary["group_by_file"] === true,
+    H2: (n) => n.tool === "get_symbols" || n.tool === "codebase_retrieval",
+    H3: (n) => n.tool !== "list_repos",
+    H4: (n) => has(n, "file_pattern"),
+    H5: (n) => n.tool !== "get_file_tree",
+    H6: (n) => has(n, "detail_level"),
+    H7: (n) => n.tool === "get_context_bundle",
+    H8: (n) => n.tool === "assemble_context",
+    H9: (n) => n.tool === "semantic_search" || n.tool === "codebase_retrieval",
+    H10: (n) => n.tool === "get_session_snapshot",
+    H12: (n) => n.tool === "codebase_retrieval",
+};
+/**
+ * Hint efficacy funnel (spec §1): per (day, code), how often a hint was emitted
+ * on a call that had a follow-up, and how often that follow-up actually acted on
+ * it. Correlation is per session, in ts order, and reads only args_summary keys
+ * locally — the wire payload carries just the counts.
+ */
+export function aggregateHintFunnel(entries) {
+    const acc = new Map();
+    for (const chain of sessionChains(entries)) {
+        for (let i = 0; i < chain.length - 1; i++) {
+            const e = chain[i];
+            const next = chain[i + 1];
+            if (!Array.isArray(e.hints_emitted))
+                continue;
+            const day = dayOf(e.ts);
+            for (const code of e.hints_emitted) {
+                if (typeof code !== "string")
+                    continue;
+                const key = `${day}\0${code}`;
+                const a = acc.get(key) ?? { emitted: 0, applied: 0 };
+                a.emitted++;
+                if (HINT_APPLIED[code]?.(next))
+                    a.applied++;
+                acc.set(key, a);
+            }
+        }
+    }
+    const out = [];
+    for (const [key, v] of acc) {
+        const [day, code] = key.split("\0");
+        out.push({ day: day, hint_code: code, emitted: v.emitted, applied: v.applied });
+    }
+    out.sort((a, c) => (a.day === c.day ? a.hint_code.localeCompare(c.hint_code) : c.day.localeCompare(a.day)));
+    return out;
+}
+/**
+ * Discovery funnel (spec §1): per day, how often plan_turn recommended >=1 tool
+ * (on a call with a follow-up) and how often the next call used one of them —
+ * i.e. is the router's advice actually taken?
+ */
+export function aggregatePlanTurnFunnel(entries) {
+    const acc = new Map();
+    for (const chain of sessionChains(entries)) {
+        for (let i = 0; i < chain.length - 1; i++) {
+            const e = chain[i];
+            if (e.tool !== "plan_turn" || !Array.isArray(e.recommended_tools) || e.recommended_tools.length === 0)
+                continue;
+            const day = dayOf(e.ts);
+            const a = acc.get(day) ?? { recommended: 0, used: 0 };
+            a.recommended++;
+            if (e.recommended_tools.includes(chain[i + 1].tool))
+                a.used++;
+            acc.set(day, a);
+        }
+    }
+    const out = [];
+    for (const [day, v] of acc)
+        out.push({ day, recommended: v.recommended, used: v.used });
+    out.sort((a, c) => c.day.localeCompare(a.day));
+    return out;
+}
+/**
+ * Read + parse the local usage.jsonl (best-effort — skips malformed lines).
+ * `afterTs` is EXCLUSIVE (strictly greater) so it composes with an upload
+ * watermark (the max ts already sent) without re-sending the boundary entry.
+ */
+export async function readLocalUsageEntries(afterTs = 0) {
+    let raw;
+    try {
+        raw = await readFile(getUsagePath(), "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const line of raw.split("\n")) {
+        if (!line)
+            continue;
+        try {
+            const e = JSON.parse(line);
+            if (typeof e.ts === "number" && e.ts > afterTs)
+                entries.push(e);
+        }
+        catch {
+            /* skip torn/partial line */
+        }
+    }
+    return entries;
+}
+//# sourceMappingURL=aggregator.js.map

package/dist/storage/telemetry/aggregator.js.map

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

package/dist/storage/telemetry/anon-id.d.ts

@@ -0,0 +1,11 @@
+export declare function getAnonIdPath(): string;
+/**
+ * Return the persistent anon id, creating it on first call. Purely random
+ * (UUID v4). Best-effort: if the file can't be written (read-only FS), a
+ * fresh random id is returned for this process so telemetry still works —
+ * it just won't be stable across restarts on that box.
+ */
+export declare function getAnonId(): string;
+/** Test-only: drop the in-process cache. */
+export declare function _resetAnonIdCacheForTests(): void;
+//# sourceMappingURL=anon-id.d.ts.map

package/dist/storage/telemetry/anon-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anon-id.d.ts","sourceRoot":"","sources":["../../../src/storage/telemetry/anon-id.ts"],"names":[],"mappings":"AAYA,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAID;;;;;GAKG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAkClC;AAED,4CAA4C;AAC5C,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/dist/storage/telemetry/anon-id.js

@@ -0,0 +1,62 @@
+// Stable random anonymous ID — generated once on first use, persisted, and
+// NEVER derived from hardware / hostname / username (spec §1). Lets the
+// collector count unique installs without identifying anyone.
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { homedir } from "node:os";
+function dataDir() {
+    return process.env["CODESIFT_DATA_DIR"] ?? join(homedir(), ".codesift");
+}
+export function getAnonIdPath() {
+    return join(dataDir(), "telemetry-id");
+}
+let cached = null;
+/**
+ * Return the persistent anon id, creating it on first call. Purely random
+ * (UUID v4). Best-effort: if the file can't be written (read-only FS), a
+ * fresh random id is returned for this process so telemetry still works —
+ * it just won't be stable across restarts on that box.
+ */
+export function getAnonId() {
+    if (cached)
+        return cached;
+    const path = getAnonIdPath();
+    try {
+        const existing = readFileSync(path, "utf-8").trim();
+        if (existing) {
+            cached = existing;
+            return existing;
+        }
+    }
+    catch {
+        /* not created yet */
+    }
+    const id = randomUUID();
+    try {
+        mkdirSync(dataDir(), { recursive: true });
+        writeFileSync(path, id + "\n", { encoding: "utf-8", flag: "wx" });
+        cached = id;
+        return id;
+    }
+    catch {
+        // Lost a race (another process created it) or FS is read-only.
+        try {
+            const raced = readFileSync(path, "utf-8").trim();
+            if (raced) {
+                cached = raced;
+                return raced;
+            }
+        }
+        catch {
+            /* still unwritable — fall through to ephemeral */
+        }
+        cached = id;
+        return id;
+    }
+}
+/** Test-only: drop the in-process cache. */
+export function _resetAnonIdCacheForTests() {
+    cached = null;
+}
+//# sourceMappingURL=anon-id.js.map

package/dist/storage/telemetry/anon-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anon-id.js","sourceRoot":"","sources":["../../../src/storage/telemetry/anon-id.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,wEAAwE;AACxE,8DAA8D;AAC9D,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC,SAAS,OAAO;IACd,OAAO,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,WAAW,CAAC,CAAC;AAC1E,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,cAAc,CAAC,CAAC;AACzC,CAAC;AAED,IAAI,MAAM,GAAkB,IAAI,CAAC;AAEjC;;;;;GAKG;AACH,MAAM,UAAU,SAAS;IACvB,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,IAAI,GAAG,aAAa,EAAE,CAAC;IAC7B,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;QACpD,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,GAAG,QAAQ,CAAC;YAClB,OAAO,QAAQ,CAAC;QAClB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,qBAAqB;IACvB,CAAC;IAED,MAAM,EAAE,GAAG,UAAU,EAAE,CAAC;IACxB,IAAI,CAAC;QACH,SAAS,CAAC,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1C,aAAa,CAAC,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAClE,MAAM,GAAG,EAAE,CAAC;QACZ,OAAO,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,+DAA+D;QAC/D,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;YACjD,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,GAAG,KAAK,CAAC;gBACf,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,kDAAkD;QACpD,CAAC;QACD,MAAM,GAAG,EAAE,CAAC;QACZ,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,yBAAyB;IACvC,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC"}

package/dist/storage/telemetry/config.d.ts

@@ -0,0 +1,37 @@
+export type TelemetryLevel = "off" | "anon" | "full";
+/** Bump when the L1 payload shape changes. Collector tolerates unknown versions. */
+export declare const TELEMETRY_SCHEMA_VERSION = 1;
+export declare function getConfigPath(): string;
+interface StoredConfig {
+    telemetry?: string | {
+        level?: string;
+    };
+}
+/** Best-effort read of ~/.codesift/config.json — never throws. */
+export declare function readStoredConfig(): StoredConfig;
+/**
+ * Resolve the effective telemetry level. Precedence (first match wins):
+ *   1. DO_NOT_TRACK truthy            → off   (respect the cross-tool standard)
+ *   2. CODESIFT_TELEMETRY env         → off | anon | full
+ *   3. config.json `telemetry`        → off | anon | full   (level string or {level})
+ *   4. default                        → anon  (opt-out model — spec decision)
+ */
+export declare function resolveTelemetryLevel(): TelemetryLevel;
+/**
+ * Persist the telemetry level into ~/.codesift/config.json (merging with any
+ * existing config). Atomic tmp+rename. Used by `codesift telemetry on|off|full`.
+ */
+export declare function writeStoredTelemetryLevel(level: TelemetryLevel): void;
+/**
+ * Print the one-time consent notice to STDERR (spec §4). Shown once per machine
+ * when telemetry is anon, then a marker file suppresses it. STDERR so it never
+ * corrupts the MCP stdio protocol. Best-effort — never throws.
+ */
+export declare function maybePrintFirstRunNotice(): void;
+/** Human-readable reason for the current level — powers `codesift telemetry show`. */
+export declare function telemetrySource(): {
+    level: TelemetryLevel;
+    reason: string;
+};
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/storage/telemetry/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/storage/telemetry/config.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;AAErD,oFAAoF;AACpF,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAM1C,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,UAAU,YAAY;IACpB,SAAS,CAAC,EAAE,MAAM,GAAG;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACzC;AAED,kEAAkE;AAClE,wBAAgB,gBAAgB,IAAI,YAAY,CAS/C;AAiBD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,cAAc,CAatD;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAcrE;AAMD;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAoB/C;AAED,sFAAsF;AACtF,wBAAgB,eAAe,IAAI;IAAE,KAAK,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAc3E"}

package/dist/storage/telemetry/config.js

@@ -0,0 +1,130 @@
+// Telemetry level resolution + opt-out. No network here — this module only
+// decides WHETHER and at what level telemetry runs. See spec
+// docs/specs/2026-07-19-telemetry-spec.md §4.
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+/** Bump when the L1 payload shape changes. Collector tolerates unknown versions. */
+export const TELEMETRY_SCHEMA_VERSION = 1;
+function dataDir() {
+    return process.env["CODESIFT_DATA_DIR"] ?? join(homedir(), ".codesift");
+}
+export function getConfigPath() {
+    return join(dataDir(), "config.json");
+}
+/** Best-effort read of ~/.codesift/config.json — never throws. */
+export function readStoredConfig() {
+    try {
+        const raw = readFileSync(getConfigPath(), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object")
+            return parsed;
+    }
+    catch {
+        /* absent or malformed → defaults */
+    }
+    return {};
+}
+function normalizeLevel(v) {
+    if (typeof v !== "string")
+        return null;
+    const s = v.trim().toLowerCase();
+    if (s === "off" || s === "0" || s === "false" || s === "no")
+        return "off";
+    if (s === "full")
+        return "full";
+    if (s === "anon" || s === "on" || s === "1" || s === "true" || s === "anonymous")
+        return "anon";
+    return null;
+}
+function isTruthyEnv(v) {
+    if (!v)
+        return false;
+    const s = v.trim().toLowerCase();
+    return s !== "" && s !== "0" && s !== "false" && s !== "no";
+}
+/**
+ * Resolve the effective telemetry level. Precedence (first match wins):
+ *   1. DO_NOT_TRACK truthy            → off   (respect the cross-tool standard)
+ *   2. CODESIFT_TELEMETRY env         → off | anon | full
+ *   3. config.json `telemetry`        → off | anon | full   (level string or {level})
+ *   4. default                        → anon  (opt-out model — spec decision)
+ */
+export function resolveTelemetryLevel() {
+    if (isTruthyEnv(process.env["DO_NOT_TRACK"]))
+        return "off";
+    const fromEnv = normalizeLevel(process.env["CODESIFT_TELEMETRY"]);
+    if (fromEnv)
+        return fromEnv;
+    const stored = readStoredConfig().telemetry;
+    const fromStore = normalizeLevel(typeof stored === "object" && stored !== null ? stored.level : stored);
+    if (fromStore)
+        return fromStore;
+    return "anon";
+}
+/**
+ * Persist the telemetry level into ~/.codesift/config.json (merging with any
+ * existing config). Atomic tmp+rename. Used by `codesift telemetry on|off|full`.
+ */
+export function writeStoredTelemetryLevel(level) {
+    const path = getConfigPath();
+    let cfg = {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (parsed && typeof parsed === "object")
+            cfg = parsed;
+    }
+    catch {
+        /* absent/malformed → start fresh */
+    }
+    cfg["telemetry"] = { level };
+    mkdirSync(dataDir(), { recursive: true });
+    const tmp = path + ".tmp";
+    writeFileSync(tmp, JSON.stringify(cfg, null, 2) + "\n", "utf-8");
+    renameSync(tmp, path);
+}
+function noticePath() {
+    return join(dataDir(), "telemetry-notice-shown");
+}
+/**
+ * Print the one-time consent notice to STDERR (spec §4). Shown once per machine
+ * when telemetry is anon, then a marker file suppresses it. STDERR so it never
+ * corrupts the MCP stdio protocol. Best-effort — never throws.
+ */
+export function maybePrintFirstRunNotice() {
+    try {
+        if (resolveTelemetryLevel() !== "anon")
+            return;
+        const marker = noticePath();
+        try {
+            readFileSync(marker, "utf-8");
+            return; // already shown
+        }
+        catch {
+            /* not shown yet */
+        }
+        process.stderr.write("[codesift] Anonymous usage stats are ON (tool names, latencies, error/empty rates,\n" +
+            "  bucketed env — NO queries, paths, repo names or code). See exactly what is sent:\n" +
+            "  `codesift telemetry show`.  Opt out: CODESIFT_TELEMETRY=off (or DO_NOT_TRACK=1).\n");
+        mkdirSync(dataDir(), { recursive: true });
+        writeFileSync(marker, String(Date.now()) + "\n", "utf-8");
+    }
+    catch {
+        /* ignore */
+    }
+}
+/** Human-readable reason for the current level — powers `codesift telemetry show`. */
+export function telemetrySource() {
+    if (isTruthyEnv(process.env["DO_NOT_TRACK"])) {
+        return { level: "off", reason: "DO_NOT_TRACK env is set" };
+    }
+    const fromEnv = normalizeLevel(process.env["CODESIFT_TELEMETRY"]);
+    if (fromEnv)
+        return { level: fromEnv, reason: `CODESIFT_TELEMETRY=${process.env["CODESIFT_TELEMETRY"]}` };
+    const stored = readStoredConfig().telemetry;
+    const fromStore = normalizeLevel(typeof stored === "object" && stored !== null ? stored.level : stored);
+    if (fromStore)
+        return { level: fromStore, reason: `config.json telemetry=${fromStore}` };
+    return { level: "anon", reason: "default (anonymous, opt-out)" };
+}
+//# sourceMappingURL=config.js.map

package/dist/storage/telemetry/config.js.map

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

package/dist/storage/telemetry/env-profile.d.ts

@@ -0,0 +1,19 @@
+export interface EnvProfile {
+    platform: string;
+    arch: string;
+    ram_bucket: string;
+    cores: number;
+    node_ver: string;
+    codesift_ver: string;
+    repo_size_bucket?: string;
+    top3_ext?: string[];
+}
+export declare function repoSizeBucket(fileCount: number): string;
+export declare function getCodesiftVersion(): string;
+/** Build the environment profile. Repo dimensions are optional — omitted when
+ *  no repo is in scope (e.g. `telemetry show` outside a project). */
+export declare function buildEnvProfile(repo?: {
+    fileCount: number;
+    topExts: string[];
+}): EnvProfile;
+//# sourceMappingURL=env-profile.d.ts.map

package/dist/storage/telemetry/env-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-profile.d.ts","sourceRoot":"","sources":["../../../src/storage/telemetry/env-profile.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAWD,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAKxD;AAID,wBAAgB,kBAAkB,IAAI,MAAM,CAiB3C;AAED;qEACqE;AACrE,wBAAgB,eAAe,CAAC,IAAI,CAAC,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,UAAU,CAe3F"}

package/dist/storage/telemetry/env-profile.js

@@ -0,0 +1,67 @@
+// Bucketed environment profile — coarse enough that it can never identify a
+// machine, precise enough to slice behaviour by config (spec §1). No hostnames,
+// no paths, no exact counts that could fingerprint.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import * as os from "node:os";
+function ramBucket(bytes) {
+    const gb = bytes / 1024 ** 3;
+    if (gb < 8)
+        return "<8gb";
+    if (gb < 16)
+        return "8-16gb";
+    if (gb < 32)
+        return "16-32gb";
+    if (gb < 64)
+        return "32-64gb";
+    return ">=64gb";
+}
+export function repoSizeBucket(fileCount) {
+    if (fileCount < 1000)
+        return "<1k";
+    if (fileCount < 10_000)
+        return "1-10k";
+    if (fileCount < 50_000)
+        return "10-50k";
+    return ">50k";
+}
+let versionCache = null;
+export function getCodesiftVersion() {
+    if (versionCache)
+        return versionCache;
+    // package.json sits at the repo root; this module is src|dist/storage/telemetry/.
+    for (const rel of ["../../../package.json", "../../../../package.json"]) {
+        try {
+            const p = fileURLToPath(new URL(rel, import.meta.url));
+            const pkg = JSON.parse(readFileSync(p, "utf-8"));
+            if (pkg.name === "codesift-mcp" && typeof pkg.version === "string") {
+                versionCache = pkg.version;
+                return versionCache;
+            }
+        }
+        catch {
+            /* try next */
+        }
+    }
+    versionCache = "unknown";
+    return versionCache;
+}
+/** Build the environment profile. Repo dimensions are optional — omitted when
+ *  no repo is in scope (e.g. `telemetry show` outside a project). */
+export function buildEnvProfile(repo) {
+    const nodeMajor = process.versions.node.split(".")[0] ?? process.versions.node;
+    const profile = {
+        platform: os.platform(),
+        arch: os.arch(),
+        ram_bucket: ramBucket(os.totalmem()),
+        cores: os.cpus().length,
+        node_ver: nodeMajor,
+        codesift_ver: getCodesiftVersion(),
+    };
+    if (repo) {
+        profile.repo_size_bucket = repoSizeBucket(repo.fileCount);
+        profile.top3_ext = repo.topExts.slice(0, 3);
+    }
+    return profile;
+}
+//# sourceMappingURL=env-profile.js.map

package/dist/storage/telemetry/env-profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-profile.js","sourceRoot":"","sources":["../../../src/storage/telemetry/env-profile.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,gFAAgF;AAChF,oDAAoD;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAa9B,SAAS,SAAS,CAAC,KAAa;IAC9B,MAAM,EAAE,GAAG,KAAK,GAAG,IAAI,IAAI,CAAC,CAAC;IAC7B,IAAI,EAAE,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC;IAC1B,IAAI,EAAE,GAAG,EAAE;QAAE,OAAO,QAAQ,CAAC;IAC7B,IAAI,EAAE,GAAG,EAAE;QAAE,OAAO,SAAS,CAAC;IAC9B,IAAI,EAAE,GAAG,EAAE;QAAE,OAAO,SAAS,CAAC;IAC9B,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,IAAI,SAAS,GAAG,IAAI;QAAE,OAAO,KAAK,CAAC;IACnC,IAAI,SAAS,GAAG,MAAM;QAAE,OAAO,OAAO,CAAC;IACvC,IAAI,SAAS,GAAG,MAAM;QAAE,OAAO,QAAQ,CAAC;IACxC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,IAAI,YAAY,GAAkB,IAAI,CAAC;AAEvC,MAAM,UAAU,kBAAkB;IAChC,IAAI,YAAY;QAAE,OAAO,YAAY,CAAC;IACtC,kFAAkF;IAClF,KAAK,MAAM,GAAG,IAAI,CAAC,uBAAuB,EAAE,0BAA0B,CAAC,EAAE,CAAC;QACxE,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YACvD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,EAAE,OAAO,CAAC,CAAwC,CAAC;YACxF,IAAI,GAAG,CAAC,IAAI,KAAK,cAAc,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;gBACnE,YAAY,GAAG,GAAG,CAAC,OAAO,CAAC;gBAC3B,OAAO,YAAY,CAAC;YACtB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,cAAc;QAChB,CAAC;IACH,CAAC;IACD,YAAY,GAAG,SAAS,CAAC;IACzB,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;qEACqE;AACrE,MAAM,UAAU,eAAe,CAAC,IAA+C;IAC7E,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;IAC/E,MAAM,OAAO,GAAe;QAC1B,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE;QACvB,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE;QACf,UAAU,EAAE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC;QACpC,KAAK,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM;QACvB,QAAQ,EAAE,SAAS;QACnB,YAAY,EAAE,kBAAkB,EAAE;KACnC,CAAC;IACF,IAAI,IAAI,EAAE,CAAC;QACT,OAAO,CAAC,gBAAgB,GAAG,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC1D,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/storage/telemetry/payload.d.ts

@@ -0,0 +1,8 @@
+import { type Level1Payload } from "./sanitizer.js";
+/**
+ * Build the exact Level-1 payload that would be sent right now, from the local
+ * usage.jsonl. Repo dimensions are omitted here (added per-context at push
+ * time). Runs the sanitizer guard so `telemetry show` proves the allowlist.
+ */
+export declare function buildCurrentLevel1Payload(now: number, sinceTs?: number): Promise<Level1Payload>;
+//# sourceMappingURL=payload.d.ts.map

package/dist/storage/telemetry/payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../../src/storage/telemetry/payload.ts"],"names":[],"mappings":"AAKA,OAAO,EAAuC,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEzF;;;;GAIG;AACH,wBAAsB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,SAAI,GAAG,OAAO,CAAC,aAAa,CAAC,CAShG"}