homegraph 0.9.10 → 1.1.1

package/dist/sync/worktree.js

@@ -2,9 +2,9 @@
 /**
  * Git Worktree Awareness
  *
- * A CodeGraph index lives in a `.homegraph/` directory and is resolved by
+ * A HomeGraph index lives in a `.homegraph/` directory and is resolved by
  * walking up parent directories to the nearest one (see
- * `findNearestCodeGraphRoot`). That walk is unaware of git worktrees: when a
+ * `findNearestHomeGraphRoot`). That walk is unaware of git worktrees: when a
  * worktree is created *inside* the main checkout (e.g. some tools place them
  * under `.gitignore`d paths like `.claude/worktrees/<name>/`), a command run
  * from the worktree walks up and silently resolves the MAIN checkout's index.
@@ -82,7 +82,7 @@ function gitWorktreeRoot(dir) {
 }
 /**
  * Detect when `startPath` lives in one git working tree but the resolved
- * CodeGraph index (`indexRoot`) belongs to a *different* working tree.
+ * HomeGraph index (`indexRoot`) belongs to a *different* working tree.
  *
  * Returns null — meaning "nothing to warn about" — when:
  *   - `startPath` isn't in a git repo (or git is unavailable),
@@ -107,7 +107,7 @@ function detectWorktreeIndexMismatch(startPath, indexRoot) {
 }
 /** One-line-per-fact warning describing a detected mismatch. */
 function worktreeMismatchWarning(m) {
-    return (`This CodeGraph index belongs to a different git working tree.\n` +
+    return (`This HomeGraph index belongs to a different git working tree.\n` +
         `  Running in: ${m.worktreeRoot}\n` +
         `  Index from: ${m.indexRoot}\n` +
         `Results reflect that tree's code (often a different branch), not this worktree — ` +
@@ -120,7 +120,7 @@ function worktreeMismatchWarning(m) {
  * the agent is already reading — a multi-line block would bury the result.
  */
 function worktreeMismatchNotice(m) {
-    return (`⚠ CodeGraph results below come from a different git worktree (${m.indexRoot}), ` +
+    return (`⚠ HomeGraph results below come from a different git worktree (${m.indexRoot}), ` +
         `not where you're working (${m.worktreeRoot}) — they may reflect another branch, ` +
         `and symbols changed only here are missing. Run "homegraph init -i" here for a ` +
         `worktree-local index.`);

package/dist/telemetry/index.d.ts

@@ -0,0 +1,143 @@
+/**
+ * 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.gethomegraph.com/v1/events";
+export declare const TELEMETRY_DOCS = "https://github.com/colbymchenry/homegraph/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+';
+/**
+ * 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>;
+    };
+}, 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' | 'HOMEGRAPH_TELEMETRY' | 'config' | 'default';
+    machineId: string | null;
+    configPath: string;
+}
+export interface TelemetryOptions {
+    /** Global state dir; defaults to ~/.homegraph. 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 > HOMEGRAPH_TELEMETRY=0|1 > stored config > default on.
+     */
+    getStatus(): TelemetryStatus;
+    isEnabled(): boolean;
+    /**
+     * Persist an explicit user choice (installer toggle or `homegraph
+     * 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/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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"}