@nanonets/graft 0.10.0 → 0.12.0

package/dist/telemetry/key.js

@@ -0,0 +1,49 @@
+/**
+ * The PostHog project key, and the reason forks stay silent.
+ *
+ * `BAKED_KEY` is empty in the repository and is rewritten in place by
+ * `scripts/stamp-telemetry-key.mjs`, which runs from `prepublishOnly`. So the
+ * key exists only in the published tarball: a clone, a fork, and a plain
+ * `npm run build` all compile to `''`, and every send path short-circuits. A
+ * contributor cannot accidentally send us their own usage, and a fork cannot
+ * send us anything at all.
+ *
+ * `GRAFT_POSTHOG_KEY` overrides it at runtime so a maintainer can exercise the
+ * real path locally without publishing.
+ *
+ * Public project keys are write-only ingestion keys — they authorise capture and
+ * nothing else — which is why one may sit in a published artifact at all. It is
+ * still not committed here: an empty default is what makes "forks never send"
+ * true by construction rather than by policy.
+ */
+/** Rewritten at publish time. Do not hand-edit — see the module comment. */
+const BAKED_KEY = '';
+/**
+ * Nanonets' own PostHog host, not `us.i.posthog.com`.
+ *
+ * Every Nanonets product ingests through a nanonets.com proxy rather than
+ * PostHog directly, on one shared project token, so pointing graft at PostHog
+ * Cloud would put its events in a project nobody looks at.
+ *
+ * `events.` rather than `e.` because graft is server-side, and this is the host
+ * the other server-side integration already uses (the agents-platform Go
+ * backend sets `POSTHOG_HOST=https://events.nanonets.com`). The one documented
+ * objection to it — 400 `invalid_payload` — was gzip-compressed ingest from
+ * `posthog-js` in a browser, fixed there with `disable_compression: true`. We
+ * send plain uncompressed JSON from Node, so that failure mode cannot apply.
+ *
+ * Probed directly, that host answers 401 to a well-formed batch with a bad key,
+ * so it serves `/batch/` and parses the body — see the note in send.ts.
+ *
+ * The HOST is safe to commit; the KEY is not, and stays empty here. That
+ * asymmetry is the point: with no key, a fork built from this source sends
+ * nothing no matter where the host points.
+ */
+const BAKED_HOST = 'https://events.nanonets.com';
+export function posthogKey() {
+    return process.env.GRAFT_POSTHOG_KEY || BAKED_KEY;
+}
+export function posthogHost() {
+    return (process.env.GRAFT_POSTHOG_HOST || BAKED_HOST).replace(/\/+$/, '');
+}
+//# sourceMappingURL=key.js.map

package/dist/telemetry/key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.js","sourceRoot":"","sources":["../../src/telemetry/key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,4EAA4E;AAC5E,MAAM,SAAS,GAAG,EAAE,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,GAAG,6BAA6B,CAAC;AAEjD,MAAM,UAAU,UAAU;IACxB,OAAO,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,SAAS,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,UAAU,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAC5E,CAAC"}

package/dist/telemetry/notice.d.ts

@@ -0,0 +1,19 @@
+export declare const TELEMETRY_DOC_URL = "https://github.com/NanoNets/context-graph-engine/blob/main/TELEMETRY.md";
+export declare const NOTICE: string;
+/**
+ * The notice text the first time it is due, then null forever after. Marks it as
+ * shown before returning, so two concurrent commands print it at most twice
+ * rather than every time.
+ */
+export declare function firstRunNotice(home?: string, env?: NodeJS.ProcessEnv): string | null;
+/** `graft telemetry status`. `env` is a test seam, as elsewhere in this module —
+ *  a real run must be gated on the real `DO_NOT_TRACK` and CI variables. */
+export declare function formatStatus(home?: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * `graft telemetry debug` — Next.js's `NEXT_TELEMETRY_DEBUG` and Astro's
+ * `DEBUG=astro:telemetry` in command form. Prints the pending queue and the
+ * literal JSON body a flush would POST, and sends nothing. The point is that a
+ * user never has to take our word for the contract.
+ */
+export declare function formatDebug(home?: string): string;
+//# sourceMappingURL=notice.d.ts.map

package/dist/telemetry/notice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notice.d.ts","sourceRoot":"","sources":["../../src/telemetry/notice.ts"],"names":[],"mappings":"AAqBA,eAAO,MAAM,iBAAiB,4EAA4E,CAAC;AAE3G,eAAO,MAAM,MAAM,QAGP,CAAC;AAEb;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,GAAG,IAAI,CASpF;AAED;4EAC4E;AAC5E,wBAAgB,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAoB3E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAkBjD"}

package/dist/telemetry/notice.js

@@ -0,0 +1,90 @@
+/**
+ * The one-time disclosure, and the `graft telemetry` command's output.
+ *
+ * The notice is the whole reason this design is defensible. Every telemetry
+ * backlash in the tools we looked at — the GitHub CLI's silent 2.91.0 rollout,
+ * Gatsby's on-by-default addition, the .NET SDK's opt-out that distributors now
+ * patch out — was about a tool that started sending without saying so. Homebrew
+ * does exactly what is done here and is uncontroversial: print once, in plain
+ * language, before anything leaves, and say how to turn it off in the same
+ * breath.
+ *
+ * Once per MACHINE, not per repo: a dev with twelve checkouts should read this
+ * one time. `graft init`'s picker is the other disclosure surface, for the users
+ * who see it — this catches everyone else.
+ */
+import { patchState, readState } from './identity.js';
+import { explainOff, offReason } from './gate.js';
+import { peek } from './queue.js';
+import { buildBatch } from './send.js';
+import { posthogHost } from './key.js';
+export const TELEMETRY_DOC_URL = 'https://github.com/NanoNets/context-graph-engine/blob/main/TELEMETRY.md';
+export const NOTICE = [
+    '· graft collects anonymous usage stats (no code, no file paths, no queries).',
+    `  What exactly: ${TELEMETRY_DOC_URL} — turn it off with \`graft telemetry disable\`.`,
+].join('\n');
+/**
+ * The notice text the first time it is due, then null forever after. Marks it as
+ * shown before returning, so two concurrent commands print it at most twice
+ * rather than every time.
+ */
+export function firstRunNotice(home, env) {
+    try {
+        if (offReason(home, env) !== null)
+            return null; // nothing to disclose if nothing can be sent
+        if (readState(home)?.noticeShownAt)
+            return null;
+        patchState({ noticeShownAt: new Date().toISOString() }, home);
+        return NOTICE;
+    }
+    catch {
+        return null;
+    }
+}
+/** `graft telemetry status`. `env` is a test seam, as elsewhere in this module —
+ *  a real run must be gated on the real `DO_NOT_TRACK` and CI variables. */
+export function formatStatus(home, env) {
+    const reason = offReason(home, env);
+    const pending = peek(home).length;
+    const lines = [
+        reason === null
+            ? 'telemetry: on — anonymous, aggregate-only'
+            : `telemetry: ${explainOff(reason)}`,
+        `  contract:  ${TELEMETRY_DOC_URL}`,
+    ];
+    if (reason === null || reason === 'disabled') {
+        lines.push(`  endpoint:  ${posthogHost()}`);
+        lines.push(`  queued:    ${pending} event${pending === 1 ? '' : 's'} waiting for the next daily flush`);
+    }
+    lines.push(reason === 'disabled'
+        ? '  enable:    graft telemetry enable'
+        : '  disable:   graft telemetry disable  (or set DO_NOT_TRACK=1)');
+    lines.push('  inspect:   graft telemetry debug   (prints the exact batch, sends nothing)');
+    return lines.join('\n');
+}
+/**
+ * `graft telemetry debug` — Next.js's `NEXT_TELEMETRY_DEBUG` and Astro's
+ * `DEBUG=astro:telemetry` in command form. Prints the pending queue and the
+ * literal JSON body a flush would POST, and sends nothing. The point is that a
+ * user never has to take our word for the contract.
+ */
+export function formatDebug(home) {
+    const events = peek(home);
+    if (events.length === 0) {
+        return [
+            'telemetry: nothing queued.',
+            '  Run a graft command first — events are written locally and flushed once a day.',
+        ].join('\n');
+    }
+    // A literal placeholder, never the key itself. This output is written to be
+    // pasted into an issue; the project key is not the user's to share and is not
+    // needed to audit what graft sends.
+    const body = { api_key: '<omitted — graft\'s own ingestion key>', ...buildBatch(events) };
+    return [
+        `telemetry: ${events.length} event(s) queued. This is the exact body a flush would POST`,
+        `to ${posthogHost()}/batch/ — running this command sends nothing.`,
+        '',
+        JSON.stringify(body, null, 2),
+    ].join('\n');
+}
+//# sourceMappingURL=notice.js.map

package/dist/telemetry/notice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notice.js","sourceRoot":"","sources":["../../src/telemetry/notice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC,MAAM,CAAC,MAAM,iBAAiB,GAAG,yEAAyE,CAAC;AAE3G,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,8EAA8E;IAC9E,mBAAmB,iBAAiB,kDAAkD;CACvF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAa,EAAE,GAAuB;IACnE,IAAI,CAAC;QACH,IAAI,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC,CAAC,6CAA6C;QAC7F,IAAI,SAAS,CAAC,IAAI,CAAC,EAAE,aAAa;YAAE,OAAO,IAAI,CAAC;QAChD,UAAU,CAAC,EAAE,aAAa,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;QAC9D,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;4EAC4E;AAC5E,MAAM,UAAU,YAAY,CAAC,IAAa,EAAE,GAAuB;IACjE,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;IAClC,MAAM,KAAK,GAAG;QACZ,MAAM,KAAK,IAAI;YACb,CAAC,CAAC,2CAA2C;YAC7C,CAAC,CAAC,cAAc,UAAU,CAAC,MAAM,CAAC,EAAE;QACtC,gBAAgB,iBAAiB,EAAE;KACpC,CAAC;IACF,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;QAC7C,KAAK,CAAC,IAAI,CAAC,gBAAgB,WAAW,EAAE,EAAE,CAAC,CAAC;QAC5C,KAAK,CAAC,IAAI,CAAC,gBAAgB,OAAO,SAAS,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,mCAAmC,CAAC,CAAC;IAC1G,CAAC;IACD,KAAK,CAAC,IAAI,CACR,MAAM,KAAK,UAAU;QACnB,CAAC,CAAC,qCAAqC;QACvC,CAAC,CAAC,+DAA+D,CACpE,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,8EAA8E,CAAC,CAAC;IAC3F,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,IAAa;IACvC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO;YACL,4BAA4B;YAC5B,kFAAkF;SACnF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IACD,4EAA4E;IAC5E,8EAA8E;IAC9E,oCAAoC;IACpC,MAAM,IAAI,GAAG,EAAE,OAAO,EAAE,wCAAwC,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;IAC1F,OAAO;QACL,cAAc,MAAM,CAAC,MAAM,6DAA6D;QACxF,MAAM,WAAW,EAAE,+CAA+C;QAClE,EAAE;QACF,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;KAC9B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/telemetry/queue.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The ceiling on the queue. An unflushable machine — permanently offline, or a
+ * key that never works — must not grow a file in someone's home forever.
+ *
+ * Bytes are the bound, because size is the only thing cheap enough to check on
+ * every append (one `statSync`); counting lines would mean reading the whole
+ * file each time. {@link TRIM_TO_EVENTS} is not a second ceiling — it is how
+ * FAR a trim cuts back, so a queue of unusually small events sheds a worthwhile
+ * amount rather than one line at a time. Between trims the file can hold more
+ * than that many events, and can exceed the byte bound by one append.
+ */
+export declare const MAX_QUEUE_BYTES: number;
+export declare const TRIM_TO_EVENTS = 500;
+export declare function queuePath(home?: string): string;
+/**
+ * Append one event. Never throws — a full disk or a read-only home must not fail
+ * the command the user actually ran.
+ */
+export declare function enqueue(event: unknown, home?: string): void;
+/**
+ * Take everything pending, leaving an empty queue behind.
+ *
+ * The rename is what makes this safe against a concurrent append: from the
+ * instant it returns, other processes are writing to a brand-new file. Malformed
+ * lines are skipped rather than poisoning the batch — a torn write from a crash
+ * mid-append should cost one event, not the whole queue.
+ */
+export declare function drain(home?: string): unknown[];
+/** Read without draining, for `graft telemetry debug`. */
+export declare function peek(home?: string): unknown[];
+/** Put a failed batch back, so a flush that could not reach the network does not
+ *  silently discard a week of events. Oldest-first, ahead of anything queued
+ *  since the drain. */
+export declare function requeue(events: unknown[], home?: string): void;
+//# sourceMappingURL=queue.d.ts.map

package/dist/telemetry/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/telemetry/queue.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,QAAa,CAAC;AAC1C,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC,wBAAgB,SAAS,CAAC,IAAI,GAAE,MAAkB,GAAG,MAAM,CAE1D;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAO3D;AA6BD;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,EAAE,CAa9C;AAED,0DAA0D;AAC1D,wBAAgB,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,EAAE,CAS7C;AAED;;uBAEuB;AACvB,wBAAgB,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAS9D"}

package/dist/telemetry/queue.js

@@ -0,0 +1,162 @@
+/**
+ * The local event queue: one NDJSON line per event in `~/.graft/`.
+ *
+ * The queue exists because graft is a CLI, not an app. Every other tool we
+ * studied sends from a process that is already running and can afford to wait;
+ * `graft ask` lives for two seconds and its whole value proposition is being
+ * faster than reading files. So nothing is ever sent inline — events are
+ * appended here, and a detached child (`graft _telemetry-flush`, once a day)
+ * does the network. A user who is offline for a week loses nothing; a user on a
+ * hostile network never notices, because no command ever waits on a socket.
+ *
+ * Concurrency: appends are a single `appendFileSync` of one short line to a file
+ * opened `O_APPEND`, which POSIX makes atomic below PIPE_BUF (4 KB — an event is
+ * ~300 bytes). Two graft processes interleaving cannot produce a torn line.
+ *
+ * Draining renames the file first and reads the renamed copy, so events appended
+ * during a flush land in a fresh queue instead of being dropped by the truncate.
+ */
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { appendFileSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+/**
+ * The ceiling on the queue. An unflushable machine — permanently offline, or a
+ * key that never works — must not grow a file in someone's home forever.
+ *
+ * Bytes are the bound, because size is the only thing cheap enough to check on
+ * every append (one `statSync`); counting lines would mean reading the whole
+ * file each time. {@link TRIM_TO_EVENTS} is not a second ceiling — it is how
+ * FAR a trim cuts back, so a queue of unusually small events sheds a worthwhile
+ * amount rather than one line at a time. Between trims the file can hold more
+ * than that many events, and can exceed the byte bound by one append.
+ */
+export const MAX_QUEUE_BYTES = 256 * 1024;
+export const TRIM_TO_EVENTS = 500;
+export function queuePath(home = homedir()) {
+    return join(home, '.graft', 'telemetry-queue.ndjson');
+}
+/**
+ * Append one event. Never throws — a full disk or a read-only home must not fail
+ * the command the user actually ran.
+ */
+export function enqueue(event, home) {
+    const path = queuePath(home);
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        appendFileSync(path, JSON.stringify(event) + '\n');
+        trim(path);
+    }
+    catch { /* unwritable home, full disk — telemetry is never worth an error */ }
+}
+/**
+ * Enforce the cap by dropping the OLDEST events. Newest-wins because the recent
+ * ones describe the version the user is on now; a year-old queue from 0.9
+ * answers nothing. Only rewrites when actually over, so the common path is one
+ * `statSync`.
+ */
+function trim(path) {
+    let size;
+    try {
+        size = statSync(path).size;
+    }
+    catch {
+        return;
+    }
+    if (size <= MAX_QUEUE_BYTES)
+        return;
+    try {
+        const lines = readFileSync(path, 'utf8').split('\n').filter(Boolean);
+        // Walk backwards from the newest, taking lines while both budgets hold, so
+        // the file left behind always satisfies the byte bound — a count-only trim
+        // would leave 500 large events well over it.
+        const kept = [];
+        let bytes = 0;
+        for (let i = lines.length - 1; i >= 0 && kept.length < TRIM_TO_EVENTS; i--) {
+            bytes += Buffer.byteLength(lines[i]) + 1;
+            if (bytes > MAX_QUEUE_BYTES)
+                break;
+            kept.push(lines[i]);
+        }
+        kept.reverse();
+        writeFileSync(path, kept.length ? kept.join('\n') + '\n' : '');
+    }
+    catch { /* leave it; the next drain clears it anyway */ }
+}
+/**
+ * Take everything pending, leaving an empty queue behind.
+ *
+ * The rename is what makes this safe against a concurrent append: from the
+ * instant it returns, other processes are writing to a brand-new file. Malformed
+ * lines are skipped rather than poisoning the batch — a torn write from a crash
+ * mid-append should cost one event, not the whole queue.
+ */
+export function drain(home) {
+    const path = queuePath(home);
+    const taken = `${path}.${process.pid}.sending`;
+    try {
+        renameSync(path, taken);
+    }
+    catch {
+        return [];
+    } // nothing queued
+    let text = '';
+    try {
+        text = readFileSync(taken, 'utf8');
+    }
+    catch { /* fall through to cleanup */ }
+    try {
+        rmSync(taken, { force: true });
+    }
+    catch { /* best effort */ }
+    const out = [];
+    for (const line of text.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch { /* torn line — skip just this one */ }
+    }
+    return out;
+}
+/** Read without draining, for `graft telemetry debug`. */
+export function peek(home) {
+    const out = [];
+    let text = '';
+    try {
+        text = readFileSync(queuePath(home), 'utf8');
+    }
+    catch {
+        return out;
+    }
+    for (const line of text.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch { /* skip */ }
+    }
+    return out;
+}
+/** Put a failed batch back, so a flush that could not reach the network does not
+ *  silently discard a week of events. Oldest-first, ahead of anything queued
+ *  since the drain. */
+export function requeue(events, home) {
+    if (events.length === 0)
+        return;
+    const path = queuePath(home);
+    try {
+        const pending = (() => { try {
+            return readFileSync(path, 'utf8');
+        }
+        catch {
+            return '';
+        } })();
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, events.map((e) => JSON.stringify(e)).join('\n') + '\n' + pending);
+        trim(path);
+    }
+    catch { /* best effort */ }
+}
+//# sourceMappingURL=queue.js.map

package/dist/telemetry/queue.js.map

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

package/dist/telemetry/send.d.ts

@@ -0,0 +1,19 @@
+export interface SendResult {
+    ok: boolean;
+    status?: number;
+    /** Why it failed, for `graft telemetry debug` only — never itself reported. */
+    error?: string;
+}
+/**
+ * The events as PostHog wants them — everything the wire body contains EXCEPT
+ * the project key.
+ *
+ * The key is deliberately not in here. `graft telemetry debug` prints this
+ * object so a user can audit exactly what graft sends, and a command that exists
+ * to be pasted into a bug report must not also paste our ingestion key into it.
+ * `sendBatch` adds the key at the moment of the request and nowhere else, which
+ * keeps the key entirely out of every code path that can reach a terminal.
+ */
+export declare function buildBatch(events: unknown[]): Record<string, unknown>;
+export declare function sendBatch(events: unknown[]): Promise<SendResult>;
+//# sourceMappingURL=send.d.ts.map

package/dist/telemetry/send.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"send.d.ts","sourceRoot":"","sources":["../../src/telemetry/send.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgBrE;AAkBD,wBAAsB,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAmBtE"}

package/dist/telemetry/send.js

@@ -0,0 +1,84 @@
+/**
+ * The one network call in graft that is not an LLM request.
+ *
+ * A single POST of the whole queued batch to PostHog's capture endpoint, with
+ * `fetch` and no SDK. `posthog-node` would be the conventional choice, but it is
+ * a runtime dependency in a CLI whose install weight users notice, it wants to
+ * own batching and flushing (both of which the queue already does, and does
+ * differently because we are a short-lived process), and "an analytics library
+ * that can see everything" is precisely the objection this whole design exists
+ * to disarm. Twenty lines of `fetch` is auditable in a sitting.
+ *
+ * `$process_person_profile: false` on every event is what makes these ANONYMOUS
+ * events in PostHog: no person profile is created, no identity is stored, and
+ * the `distinct_id` is only ever the random install UUID.
+ */
+import { posthogKey, posthogHost } from './key.js';
+/** Anything longer and the detached child is just holding a socket open. */
+const SEND_TIMEOUT_MS = 8000;
+/**
+ * The events as PostHog wants them — everything the wire body contains EXCEPT
+ * the project key.
+ *
+ * The key is deliberately not in here. `graft telemetry debug` prints this
+ * object so a user can audit exactly what graft sends, and a command that exists
+ * to be pasted into a bug report must not also paste our ingestion key into it.
+ * `sendBatch` adds the key at the moment of the request and nowhere else, which
+ * keeps the key entirely out of every code path that can reach a terminal.
+ */
+export function buildBatch(events) {
+    return {
+        batch: events.map((e) => {
+            const ev = e;
+            return {
+                event: ev.event,
+                timestamp: ev.timestamp,
+                properties: {
+                    ...(ev.properties ?? {}),
+                    distinct_id: ev.distinct_id,
+                    // Anonymous event: PostHog stores it without creating a person.
+                    $process_person_profile: false,
+                },
+            };
+        }),
+    };
+}
+/**
+ * The ingest path.
+ *
+ * `/batch/` only, with no fallback. An earlier revision also tried `/e/`,
+ * because assign's `frontend/src/lib/posthog.ts` documents `events.nanonets.com`
+ * as serving the older path and answering `400 invalid_payload` to bodies it
+ * will not take. Probed directly, that host returns **401** to a well-formed
+ * batch with a bad key — so `/batch/` is there and does parse the body, and the
+ * historical 400 was gzip from `posthog-js` in a browser, which we never send.
+ *
+ * The fallback was therefore a second request that could not fire, and a branch
+ * production never exercises is worse than no branch. If a future host needs
+ * `/e/`, point `GRAFT_POSTHOG_HOST` at it and add the path back with evidence.
+ */
+const INGEST_PATH = '/batch/';
+export async function sendBatch(events) {
+    if (events.length === 0)
+        return { ok: true };
+    const key = posthogKey();
+    if (!key)
+        return { ok: false, error: 'no key' };
+    try {
+        const res = await fetch(`${posthogHost()}${INGEST_PATH}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            // The one place the key is ever attached: the request body itself.
+            body: JSON.stringify({ api_key: key, ...buildBatch(events) }),
+            signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+        });
+        // A 4xx is our bug (a bad key, a malformed body) and retrying it forever
+        // would pin the queue at its cap; only 5xx and transport errors go back on
+        // the queue — see shouldRequeue in flush.ts.
+        return { ok: res.ok, status: res.status };
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.name : 'unknown' };
+    }
+}
+//# sourceMappingURL=send.js.map

package/dist/telemetry/send.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"send.js","sourceRoot":"","sources":["../../src/telemetry/send.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEnD,4EAA4E;AAC5E,MAAM,eAAe,GAAG,IAAI,CAAC;AAS7B;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CAAC,MAAiB;IAC1C,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACtB,MAAM,EAAE,GAAG,CAAqG,CAAC;YACjH,OAAO;gBACL,KAAK,EAAE,EAAE,CAAC,KAAK;gBACf,SAAS,EAAE,EAAE,CAAC,SAAS;gBACvB,UAAU,EAAE;oBACV,GAAG,CAAC,EAAE,CAAC,UAAU,IAAI,EAAE,CAAC;oBACxB,WAAW,EAAE,EAAE,CAAC,WAAW;oBAC3B,gEAAgE;oBAChE,uBAAuB,EAAE,KAAK;iBAC/B;aACF,CAAC;QACJ,CAAC,CAAC;KACH,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,GAAG,SAAS,CAAC;AAE9B,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAAiB;IAC/C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IAC7C,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;IACzB,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;IAChD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,WAAW,EAAE,GAAG,WAAW,EAAE,EAAE;YACxD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,mEAAmE;YACnE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7D,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,eAAe,CAAC;SAC7C,CAAC,CAAC;QACH,yEAAyE;QACzE,2EAA2E;QAC3E,6CAA6C;QAC7C,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;IAC5C,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;IACvE,CAAC;AACH,CAAC"}

package/dist/telemetry/sessions.d.ts

@@ -0,0 +1,8 @@
+/** Untouched for this long and the session is treated as over. */
+export declare const SESSION_IDLE_MS: number;
+/**
+ * Queue a `session_summary` for every closed, not-yet-summarised session in this
+ * repo. Returns how many were queued (for tests). Never throws.
+ */
+export declare function flushClosedSessions(repo: string, now?: number, home?: string, env?: NodeJS.ProcessEnv): number;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/telemetry/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../../src/telemetry/sessions.ts"],"names":[],"mappings":"AA2BA,kEAAkE;AAClE,eAAO,MAAM,eAAe,QAAqB,CAAC;AAMlD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,GAAG,SAAa,EAChB,IAAI,CAAC,EAAE,MAAM,EACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GACtB,MAAM,CAoCR"}

package/dist/telemetry/sessions.js

@@ -0,0 +1,81 @@
+/**
+ * Rolling a finished agent session up into one `session_summary` event.
+ *
+ * This is the event that justifies the whole exercise. Everything else here
+ * counts commands; this one answers the question the product actually rests on —
+ * when an agent had both graft and grep available, which did it reach for, and
+ * how many tokens did that save? The counters already exist: the Claude Code
+ * hooks have been writing `graftReads`, `sourceReads` and `savedTokens` per
+ * session into `graft/.cache/session/` since well before telemetry did. Nothing
+ * new is measured here; a closed session is simply bucketed and queued.
+ *
+ * "Closed" is inferred from mtime rather than observed, because there is no
+ * reliable end-of-session hook — `Stop` fires per turn, and an editor that
+ * crashes fires nothing at all. A session untouched for two hours is over.
+ *
+ * Called from the session-start hook, which is the one place guaranteed to run
+ * again after a session ends. A hook must never touch the network (see the note
+ * atop upkeep.ts) and this doesn't: it only appends to the local queue.
+ */
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { cacheDir } from '../util/state.js';
+import { readSession, writeSession } from '../claude/state.js';
+import { countBucket, savedTokensBucket } from './contract.js';
+import { track } from './track.js';
+import { telemetryOn } from './gate.js';
+/** Untouched for this long and the session is treated as over. */
+export const SESSION_IDLE_MS = 2 * 60 * 60 * 1000;
+/** Never roll up more than this in one hook run — a repo with a huge backlog of
+ *  session files must not slow down a session start. The rest wait for the next. */
+const MAX_PER_RUN = 20;
+/**
+ * Queue a `session_summary` for every closed, not-yet-summarised session in this
+ * repo. Returns how many were queued (for tests). Never throws.
+ */
+export function flushClosedSessions(repo, now = Date.now(), home, env) {
+    try {
+        if (!telemetryOn(home, env))
+            return 0;
+        const dir = join(cacheDir(repo), 'session');
+        let files;
+        try {
+            files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+        }
+        catch {
+            return 0;
+        }
+        let queued = 0;
+        for (const file of files.sort()) {
+            if (queued >= MAX_PER_RUN)
+                break;
+            let mtime;
+            try {
+                mtime = statSync(join(dir, file)).mtimeMs;
+            }
+            catch {
+                continue;
+            }
+            if (now - mtime < SESSION_IDLE_MS)
+                continue;
+            const id = file.slice(0, -'.json'.length);
+            const s = readSession(repo, id);
+            if (s.summarized)
+                continue;
+            // An empty session — opened, nothing asked — is still a fact worth having:
+            // it is the difference between "graft is installed" and "graft is used".
+            track('session_summary', {
+                graft_reads_bucket: countBucket(s.graftReads ?? 0),
+                source_reads_bucket: countBucket(s.sourceReads ?? 0),
+                saved_tokens_bucket: savedTokensBucket(s.savedTokens ?? 0),
+            }, { repo, host: 'claude-code', home, env });
+            writeSession(repo, id, { ...s, summarized: true });
+            queued++;
+        }
+        return queued;
+    }
+    catch {
+        return 0; // a session start is never worth failing over a metric
+    }
+}
+//# sourceMappingURL=sessions.js.map

package/dist/telemetry/sessions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.js","sourceRoot":"","sources":["../../src/telemetry/sessions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC,kEAAkE;AAClE,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAElD;oFACoF;AACpF,MAAM,WAAW,GAAG,EAAE,CAAC;AAEvB;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAY,EACZ,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,EAChB,IAAa,EACb,GAAuB;IAEvB,IAAI,CAAC;QACH,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,GAAG,CAAC;YAAE,OAAO,CAAC,CAAC;QACtC,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC;QAC5C,IAAI,KAAe,CAAC;QACpB,IAAI,CAAC;YAAC,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,OAAO,CAAC,CAAC;QAAC,CAAC;QAExF,IAAI,MAAM,GAAG,CAAC,CAAC;QACf,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;YAChC,IAAI,MAAM,IAAI,WAAW;gBAAE,MAAM;YACjC,IAAI,KAAa,CAAC;YAClB,IAAI,CAAC;gBAAC,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC;gBAAC,SAAS;YAAC,CAAC;YACtE,IAAI,GAAG,GAAG,KAAK,GAAG,eAAe;gBAAE,SAAS;YAE5C,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAC1C,MAAM,CAAC,GAAG,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAChC,IAAI,CAAC,CAAC,UAAU;gBAAE,SAAS;YAE3B,2EAA2E;YAC3E,yEAAyE;YACzE,KAAK,CACH,iBAAiB,EACjB;gBACE,kBAAkB,EAAE,WAAW,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC;gBAClD,mBAAmB,EAAE,WAAW,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC;gBACpD,mBAAmB,EAAE,iBAAiB,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC;aAC3D,EACD,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,GAAG,EAAE,CACzC,CAAC;YACF,YAAY,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;YACnD,MAAM,EAAE,CAAC;QACX,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC,CAAC,uDAAuD;IACnE,CAAC;AACH,CAAC"}

package/dist/telemetry/track.d.ts

@@ -0,0 +1,43 @@
+import type { AgentHost } from './contract.js';
+/** One queued event, exactly as it will be sent. */
+export interface QueuedEvent {
+    event: string;
+    properties: Record<string, string>;
+    /** ISO timestamp, so a batch flushed a day late still lands on the right day. */
+    timestamp: string;
+    /** The install id, used as PostHog's `distinct_id` at send time. */
+    distinct_id: string;
+}
+export interface TrackContext {
+    /** Repo root, when the call site has one — supplies `repo_id`. */
+    repo?: string;
+    /** Which surface is calling. Defaults to the CLI. */
+    host?: AgentHost;
+    /** Test seam: a scratch `$HOME`. Production callers never pass this. */
+    home?: string;
+    /** Test seam: an environment to gate against. Production callers never pass
+     *  this — a real run must be gated on the real `DO_NOT_TRACK` and `CI`. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Which agent graft is running under, from the surface plus one env probe.
+ *
+ * Only the PRESENCE of `CLAUDECODE` is read, never its value — the distinction
+ * matters: a value could be anything a user's shell profile put there, presence
+ * is a boolean. Anything unrecognised is `cli`, which is the honest answer.
+ */
+export declare function detectHost(explicit?: AgentHost, env?: NodeJS.ProcessEnv): AgentHost;
+/**
+ * Record one event, if the contract allows it and the gates are open.
+ *
+ * Returns the event that was queued, or null — the return value exists for
+ * tests and for `graft telemetry debug`, not for control flow at call sites.
+ */
+export declare function track(event: string, props?: Record<string, string | undefined>, ctx?: TrackContext): QueuedEvent | null;
+/**
+ * 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.
+ */
+export declare function trackFirstRunIfNew(ctx?: TrackContext): void;
+//# sourceMappingURL=track.d.ts.map

package/dist/telemetry/track.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"track.d.ts","sourceRoot":"","sources":["../../src/telemetry/track.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAM/C,oDAAoD;AACpD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;+EAC2E;IAC3E,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,QAAQ,CAAC,EAAE,SAAS,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,SAAS,CAIhG;AAmBD;;;;;GAKG;AACH,wBAAgB,KAAK,CACnB,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAM,EAC9C,GAAG,GAAE,YAAiB,GACrB,WAAW,GAAG,IAAI,CA0BpB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,YAAiB,GAAG,IAAI,CAM/D"}