ashlr-plugin 1.36.4

package/docs/telemetry.md

@@ -0,0 +1,194 @@
+# ashlr-plugin Telemetry
+
+## Overview
+
+ashlr-plugin includes an **opt-in, privacy-first** telemetry pipeline that helps the maintainer tune heuristics (edit thresholds, embedding similarity cutoffs, LLM routing) with real-world data instead of guesses.
+
+**Default: OFF.** Nothing is ever collected unless you explicitly enable it.
+
+---
+
+## How to opt in
+
+**Via environment variable (session-scoped):**
+
+```sh
+export ASHLR_TELEMETRY=on
+```
+
+**Via config file (persistent):**
+
+```json
+// ~/.ashlr/config.json
+{
+  "telemetry": "opt-in"
+}
+```
+
+On first opt-in, a one-line notice is printed at session start confirming what is collected and how to disable.
+
+---
+
+## How to opt out
+
+**Environment variable (highest priority — overrides config):**
+
+```sh
+export ASHLR_TELEMETRY=off
+```
+
+**Config file:**
+
+```json
+// ~/.ashlr/config.json
+{
+  "telemetry": "off"
+}
+```
+
+Either method immediately disables collection and flushing. No data is sent after the kill switch is set. The local buffer at `~/.ashlr/telemetry-buffer.jsonl` can be deleted manually at any time.
+
+---
+
+## What is collected
+
+Only anonymized, aggregate-friendly event shapes. **No file paths, no grep patterns, no command content, no user identifiers, no repo names.**
+
+### Event types
+
+| Kind | Fields |
+|------|--------|
+| `tool_call` | `tool`, `rawBytes`, `compactBytes`, `fellBack`, `providerUsed`, `durationMs` |
+| `pretooluse_block` | `tool`, `blockedTo`, `sizeRange` (`small`/`medium`/`large` bucket — never raw bytes) |
+| `pretooluse_passthrough` | `tool`, `reason` (`below-threshold` / `out-of-cwd` / `plugin-tree` / `micro-edit` / `bypass`) |
+| `version` | `pluginVersion`, `bunVersion`, `platform`, `arch` |
+
+All events also include:
+
+- `ts` — epoch seconds (not milliseconds, to save bytes)
+- `kind` — event type string
+- `sessionId` — a per-session opaque hex string (SHA-256 fold of a random seed; re-generated each session)
+
+### What `sessionId` is
+
+A 16-character hex string derived from a random seed at session start. It is deleted at session end. It allows the maintainer to correlate events *within* one session without identifying the user across sessions or installations. Re-installs and new sessions always generate a fresh value.
+
+---
+
+## What is NEVER collected
+
+- File paths (absolute or relative)
+- Grep search patterns
+- File content, command arguments, or any user-authored text
+- User names, email addresses, or identifiers
+- Repo names, organization names, or project paths
+- IP addresses (the server receives them transiently in HTTP headers but they are not stored)
+
+A path-safety guard in the buffer writer (`looksLikePath`) rejects any event whose string values look like an absolute filesystem path. Events that fail this check are silently dropped rather than written.
+
+---
+
+## Local buffer
+
+Events are buffered locally at:
+
+```
+~/.ashlr/telemetry-buffer.jsonl
+```
+
+The buffer is capped at **5,000 lines**. Older entries are evicted when the cap is exceeded. The buffer is a plain JSONL file — you can inspect it at any time:
+
+```sh
+cat ~/.ashlr/telemetry-buffer.jsonl | head -5
+```
+
+---
+
+## Flusher
+
+The buffer is flushed to the maintainer's collection endpoint:
+
+1. **On session end** — spawned from the `session-end-consolidate` hook.
+2. **On demand** — `bun run scripts/telemetry-flush.ts`.
+
+The flusher has a **10-second network timeout**. On failure (network error, non-2xx response) the buffer is left untouched and retried on the next flush cycle. Failures are logged to stderr but never surfaced to the user.
+
+---
+
+## Endpoint contract
+
+### POST `/v1/events`
+
+**URL:** `https://telemetry.ashlr.ai/v1/events` (override with `ASHLR_TELEMETRY_URL` env var)
+
+**Request:**
+
+```json
+{
+  "sessionId": "a1b2c3d4e5f6a7b8",
+  "events": [
+    {
+      "ts": 1720000000,
+      "kind": "tool_call",
+      "sessionId": "a1b2c3d4e5f6a7b8",
+      "tool": "ashlr__read",
+      "rawBytes": 8200,
+      "compactBytes": 1100,
+      "fellBack": false,
+      "providerUsed": "anthropic",
+      "durationMs": 42
+    }
+  ]
+}
+```
+
+**Response (2xx):**
+
+```json
+{ "accepted": 1 }
+```
+
+On `2xx`, the flusher truncates the buffer to entries newer than the flush horizon (the `ts` of the last event in the batch). On any other status or network error, the buffer is left intact.
+
+### Server-side requirements (for the maintainer)
+
+To start receiving events, stand up a simple HTTPS function (Vercel/Cloudflare Workers/etc.) that:
+
+1. Accepts `POST /v1/events` with `Content-Type: application/json`.
+2. Parses `{ sessionId, events }` from the body.
+3. Validates that no event field contains path-like strings (defense-in-depth).
+4. Appends events to a time-series store (e.g. Tinybird, ClickHouse, Postgres `jsonb`).
+5. Returns `{ accepted: N }` with status `200`.
+6. Does NOT log request IP addresses to permanent storage.
+
+**The endpoint does not need to exist for the plugin to function.** When the endpoint is unreachable, events are buffered locally and retried silently.
+
+---
+
+## Data retention promise
+
+- **Raw events:** purged from the server after **30 days**.
+- **Aggregate statistics** (e.g., p50 raw/compact byte ratios per tool per week): retained indefinitely for heuristic tuning.
+- **Session IDs:** not cross-referenced with any user identity. Treated as opaque correlation tokens within a single session.
+
+---
+
+## Viewing telemetry status
+
+Run `/ashlr-status` in Claude Code. The `## Telemetry snapshot` section includes:
+
+```
+  opt-in telemetry: OFF (default) · to enable: ASHLR_TELEMETRY=on
+```
+
+or when enabled:
+
+```
+  opt-in telemetry: ON · buffer: 42 events · to disable: ASHLR_TELEMETRY=off
+```
+
+---
+
+## `/ashlr-settings telemetry off`
+
+Running `/ashlr-settings telemetry off` writes `{ "telemetry": "off" }` into `~/.ashlr/config.json`, which disables collection and flushing for all future sessions.

package/docs/test-isolation.md

@@ -0,0 +1,100 @@
+# Test Isolation in the ashlr-plugin Suite
+
+## Why Bun shares module state across test files
+
+Bun runs all test files in a single worker process (by default). Every `import`
+resolves against a shared module cache, so a module imported by `a.test.ts` and
+then imported again by `b.test.ts` returns the *same* object — not a fresh copy.
+
+Consequences:
+
+- **Module-level variables** (caches, flags, counters) survive between files.
+- **`mock.module(specifier, factory)`** replaces the module in that shared cache
+  and is *not* automatically restored when the test file finishes. Bun's
+  `mock.restore()` only clears `mockFn` spies, not `mock.module` overrides.
+- **`process.env` mutations** are visible to all subsequent imports and code that
+  reads env at call-time.
+
+## Patterns to follow
+
+### 1. Save and restore `process.env` in outer scope
+
+If a test must set an env var, capture the original value before `beforeEach`
+and restore it in `afterEach`:
+
+```ts
+let origHome: string | undefined;
+
+beforeEach(() => { origHome = process.env.HOME; process.env.HOME = tmpDir; });
+afterEach(() => {
+  if (origHome !== undefined) process.env.HOME = origHome;
+  else delete process.env.HOME;
+});
+```
+
+### 2. Never use `mock.module` for shared packages
+
+`mock.module` leaks permanently into the module cache. Prefer **dependency
+injection**: add an optional `retriever` / `logger` / `handler` parameter to
+the production function, defaulting to the real implementation.  Tests pass
+stubs via that parameter — no module patching needed.
+
+```ts
+// production code
+export async function retrieveCached(
+  root: string, pattern: string, limit: number,
+  retriever: Retriever = _retrieveSectionsV2,  // real default
+) { ... }
+
+// test code — no mock.module
+await retrieveCached(root, "foo", 4000, stubRetriever);
+```
+
+### 3. Clear module-level caches in `beforeEach`
+
+Any module that exposes a `_clearCache()` / `_resetXxx()` test hook must be
+called in `beforeEach`, not just `afterEach`. Running it only in `afterEach`
+leaves stale state if the previous test in another file did not clean up.
+
+### 4. Use `ASHLR_STATS_SYNC=1` when asserting on-disk state
+
+`_stats.ts` debounces file writes by 250 ms. Tests that assert a stats file was
+written must either:
+
+- set `ASHLR_STATS_SYNC=1` in the test environment (disables debounce), or
+- poll with a bounded wait loop after the action.
+
+### 5. Spawn subprocesses with a minimal env
+
+When a test spawns an MCP server subprocess to verify event emission, pass only
+the env vars the subprocess actually needs:
+
+```ts
+env: { HOME: isolatedTmpDir, PATH: process.env.PATH ?? "/usr/bin:/bin" }
+```
+
+Stripping the full `process.env` prevents a previously mutated `HOME` or
+`ASHLR_SESSION_LOG_PATH` from leaking into the subprocess.
+
+## Fixes applied in this repo
+
+### Leaker: `__tests__/genome-cache.test.ts`
+
+**What leaked:** A top-level `mock.module("@ashlr/core-efficiency", ...)` call
+that replaced the entire package — including `estimateTokensFromString: () => 0`
+— in Bun's shared module cache.  Every test file loaded after
+`genome-cache.test.ts` (alphabetically: `genome-init`, `genome-live`, …,
+`run-benchmark`, …) received the stubbed module.  `run-benchmark.test.ts`
+calls `estimateTokensFromString` to measure token savings; with the stub
+returning 0, every ratio computed as `0 / 0 → 1`, making the
+`medium/large ratio < 1` assertion fail.
+
+**Fix:** Refactored `servers/_genome-cache.ts` to accept an optional `retriever`
+parameter (defaulting to the real `retrieveSectionsV2`). Rewrote
+`genome-cache.test.ts` to pass a stub directly — no `mock.module` needed.
+
+### Affected skip removed: `run-benchmark.test.ts`
+
+`test.skip("ashlr__edit medium and large samples have ratio < 1 …")` was
+un-skipped once the `genome-cache.test.ts` leak was fixed. The test passes
+reliably in both isolation and the full suite.

package/docs/upgrade.md

@@ -0,0 +1,159 @@
+# ashlr upgrade — terminal-native free-to-pro flow
+
+Run `/ashlr-upgrade` inside Claude Code to go from free to Pro or Team in
+under 90 seconds without leaving the terminal.
+
+## Quick start
+
+```
+/ashlr-upgrade
+```
+
+That's it. The flow handles sign-in, plan selection, Stripe checkout, and
+activation confirmation automatically.
+
+## What happens step by step
+
+```
+  ╔══════════════════════════════════╗
+  ║      ashlr  ·  upgrade           ║
+  ╚══════════════════════════════════╝
+
+▬▬▬ STEP 1/5: Checking current tier ▬▬▬
+  ✓  Not signed in yet.
+
+▬▬▬ STEP 2/5: Sign in ▬▬▬
+  No active Pro token found. Let's sign you in first.
+  [ASHLR_PROMPT: Email to sign in?] you@example.com
+  ✓  Magic link sent to you@example.com. Check your inbox — click the link to continue.
+     Waiting for you to click the link (up to 3 minutes)...
+  Waiting ...
+  ✓  Sign-in confirmed.
+  ✓  Token saved to ~/.ashlr/pro-token and ~/.ashlr/env (auto-loaded on next session).
+
+▬▬▬ STEP 3/5: Choose your plan ▬▬▬
+
+  1)  Pro  ·  $12/mo  [default]
+  2)  Pro  ·  $120/yr  (save 17%)
+  3)  Team ·  $24/user/mo
+  4)  Team ·  $240/user/yr  (save 17%)
+
+  [ASHLR_PROMPT: Choose a plan (1-4, default 1):] 1
+  ✓  Selected: Pro  ·  $12/mo
+
+▬▬▬ STEP 4/5: Open Stripe checkout ▬▬▬
+  ✓  Opened checkout in your browser. Complete payment to activate Pro.
+
+▬▬▬ STEP 5/5: Waiting for payment confirmation ▬▬▬
+     Polling for payment confirmation (up to 10 minutes)...
+  Waiting ...
+
+  ashlr Pro is now active.
+  Your API token is saved locally. All Pro features are unlocked.
+
+  What just changed:
+  - Hosted LLM summarizer — Ollama not required
+  - Cross-machine stats sync
+  - Leaderboard participation
+  - Priority support at support@ashlr.ai
+
+  Next: run /ashlr-dashboard to see your usage.
+```
+
+## Already on Pro
+
+If `ASHLR_PRO_TOKEN` is set and your account is already Pro or Team, the
+flow exits immediately:
+
+```
+▬▬▬ STEP 1/5: Checking current tier ▬▬▬
+  ✓  You're already on Pro.
+     Run /ashlr-dashboard to see usage.
+```
+
+## Flags
+
+| Flag | Effect |
+|------|--------|
+| `--tier pro\|team` | Pre-select tier, skip the plan prompt |
+| `--annual` | Pre-select annual billing |
+| `--email <addr>` | Pre-supply email, skip the email prompt |
+| `--no-poll` | Skip the activation polling step (useful for testing or CI) |
+
+Example — skip all interactive prompts:
+
+```
+/ashlr-upgrade --tier pro --annual --email you@example.com
+```
+
+## Headless / SSH sessions (no browser)
+
+Set `ASHLR_NO_BROWSER=1` to suppress the automatic browser open. The
+checkout URL is printed to the terminal instead:
+
+```sh
+ASHLR_NO_BROWSER=1
+```
+
+Then copy the printed URL and open it in a browser on any device.
+
+## If the browser fails to open
+
+If `open` / `xdg-open` / `start` is not available (remote server, Docker,
+minimal Linux), the flow falls back gracefully:
+
+```
+  !  Could not open a browser automatically.
+
+  Open this URL manually:
+
+  https://checkout.stripe.com/c/pay/cs_live_...
+```
+
+The activation poller continues running. Complete payment in your browser and
+the terminal will detect it automatically.
+
+## Manually pasting a token
+
+If you already have an API token (from the web dashboard at
+plugin.ashlr.ai), you can skip the magic-link flow entirely:
+
+1. Save the token: `echo "export ASHLR_PRO_TOKEN=<token>" >> ~/.ashlr/env`
+2. Source it: `source ~/.ashlr/env`
+3. Verify: `/ashlr-upgrade` will see your Pro status and exit immediately.
+
+## What happens if the poll times out
+
+After you open checkout, the script polls `/billing/status` every 5 seconds
+for up to 10 minutes. If payment isn't detected within that window, you'll see:
+
+```
+  !  Haven't detected payment yet.
+     Once you complete checkout, run /ashlr-upgrade again to verify and activate.
+```
+
+Run `/ashlr-upgrade` again after completing payment — step 1 will detect the
+new tier and exit immediately.
+
+## Token storage
+
+After sign-in the API token is saved in two places:
+
+| File | Purpose |
+|------|---------|
+| `~/.ashlr/pro-token` | Raw token (mode 0600) |
+| `~/.ashlr/env` | `export ASHLR_PRO_TOKEN=<token>` — sourced by the SessionStart hook |
+
+The SessionStart hook reads `~/.ashlr/env` on every new Claude Code session,
+so `ASHLR_PRO_TOKEN` is available automatically without a shell restart.
+
+## Pro features unlocked
+
+| Feature | Free | Pro |
+|---------|------|-----|
+| Hosted LLM summarizer | No (local Ollama required) | Yes |
+| Cross-machine stats sync | No | Yes |
+| Leaderboard | No | Yes |
+| Priority support | No | Yes (support@ashlr.ai) |
+
+See [billing.md](billing.md) for full tier comparison and lifecycle details.

package/hooks/_hook-errors.ts

@@ -0,0 +1,87 @@
+/**
+ * _hook-errors.ts — shared error-surfacing helper for hooks.
+ *
+ * Hooks are best-effort and never block tool calls, but silent catches make
+ * production failures undebuggable. This helper surfaces errors two ways:
+ *   1. stderr — visible in `claude --debug` and most harness log captures
+ *   2. ~/.ashlr/hook-errors.jsonl — persistent ring buffer (cap 1000 lines)
+ *
+ * Never throws. Never blocks. Safe to call from any catch block.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+
+const MAX_LINES = 1000;
+const TRIM_TO = 800;
+
+function errorsPath(): string {
+  const home =
+    process.env.ASHLR_HOME_OVERRIDE?.trim() ||
+    process.env.HOME ||
+    homedir();
+  return join(home, ".ashlr", "hook-errors.jsonl");
+}
+
+function trimIfOversized(p: string): void {
+  try {
+    const raw = readFileSync(p, "utf-8");
+    const lines = raw.split("\n");
+    if (lines.length <= MAX_LINES) return;
+    const kept = lines.slice(lines.length - TRIM_TO).join("\n");
+    writeFileSync(p, kept, "utf-8");
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Safe JSON.parse wrapper — the canonical helper for all hook stdin / config
+ * file parsing. Returns `fallback` on any parse error and optionally records
+ * the failure via `noteHookError` so it shows up in hook-errors.jsonl.
+ *
+ * Usage:
+ *   const payload = safeParse<MyType>(raw, {}, "my-hook", "stdin");
+ *
+ * @param raw      - Raw string to parse (may be empty, truncated, or garbage).
+ * @param fallback - Value to return when parsing fails.
+ * @param hook     - Hook name for error logging (optional; omit to skip logging).
+ * @param context  - Context label for error logging (optional).
+ */
+export function safeParse<T>(
+  raw: string,
+  fallback: T,
+  hook?: string,
+  context?: string,
+): T {
+  try {
+    return JSON.parse(raw) as T;
+  } catch (e) {
+    if (hook) noteHookError(hook, context ?? "JSON.parse", e);
+    return fallback;
+  }
+}
+
+export function noteHookError(hook: string, context: string, error: unknown): void {
+  const msg = error instanceof Error ? error.message : String(error);
+  try {
+    process.stderr.write(`[ashlr ${hook}] ${context}: ${msg}\n`);
+  } catch {
+    /* stderr may be closed in some hook harnesses — swallow */
+  }
+  try {
+    const p = errorsPath();
+    mkdirSync(dirname(p), { recursive: true });
+    const line = JSON.stringify({
+      ts: new Date().toISOString(),
+      hook,
+      context,
+      error: msg,
+    });
+    appendFileSync(p, line + "\n", "utf-8");
+    if (Math.random() < 0.01) trimIfOversized(p);
+  } catch {
+    /* persistence is best-effort */
+  }
+}

package/hooks/_hook-perf-emit.ts

@@ -0,0 +1,113 @@
+#!/usr/bin/env bun
+/**
+ * _hook-perf-emit.ts — SessionEnd helper: read hook-timings.jsonl,
+ * compute per-hook p50/p99, and emit one `hook_perf` telemetry event per hook.
+ *
+ * Called from session-end-consolidate.ts (fire-and-forget). Also exported
+ * for direct use in tests and future callers.
+ *
+ * Privacy: only hook names and latency percentiles are emitted — no file
+ * paths, no tool arguments, no content.
+ */
+
+import { readHookTimings, computeAggregates } from "../scripts/hook-timings-report";
+import { logHookPerfEvent, isTelemetryEnabled } from "../servers/_telemetry";
+
+// ---------------------------------------------------------------------------
+// p99 helper (computeAggregates only exposes p95; we need p99 for the spec)
+// ---------------------------------------------------------------------------
+
+function percentile(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  if (sorted.length === 1) return sorted[0]!;
+  const idx = (p / 100) * (sorted.length - 1);
+  const lo = Math.floor(idx);
+  const hi = Math.ceil(idx);
+  if (lo === hi) return sorted[lo]!;
+  const frac = idx - lo;
+  return Math.round(sorted[lo]! + frac * (sorted[hi]! - sorted[lo]!));
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface HookPerfSummary {
+  hook_name: string;
+  p50_ms: number;
+  p99_ms: number;
+  count: number;
+}
+
+/**
+ * Read hook-timings.jsonl from `timingsPath` (default: ~/.ashlr/hook-timings.jsonl),
+ * compute per-hook p50/p99 over the last `windowHours` hours, and return summaries.
+ */
+export function computeHookPerfSummaries(opts: {
+  timingsPath?: string;
+  windowHours?: number;
+} = {}): HookPerfSummary[] {
+  const { timingsPath, windowHours = 24 } = opts;
+  const records = readHookTimings(timingsPath);
+  if (records.length === 0) return [];
+
+  // Use computeAggregates for the p50 + grouping, then recompute p99
+  // from the raw records since the aggregate only exposes p95.
+  const aggregates = computeAggregates(records, windowHours);
+
+  // Build a map: hook → sorted durations (within the window)
+  const cutoff = Date.now() - windowHours * 3_600_000;
+  const byHook = new Map<string, number[]>();
+  for (const rec of records) {
+    const t = new Date(rec.ts).getTime();
+    if (isNaN(t) || t < cutoff) continue;
+    const arr = byHook.get(rec.hook) ?? [];
+    arr.push(rec.durationMs);
+    byHook.set(rec.hook, arr);
+  }
+
+  return aggregates.map((agg) => {
+    const durations = (byHook.get(agg.hook) ?? []).sort((a, b) => a - b);
+    return {
+      hook_name: agg.hook,
+      p50_ms: agg.p50,
+      p99_ms: percentile(durations, 99),
+      count: agg.calls,
+    };
+  });
+}
+
+/**
+ * Emit one `hook_perf` telemetry event per hook. No-op when telemetry is off.
+ * Returns the number of events emitted (0 when telemetry off or no records).
+ */
+export function emitHookPerfEvents(opts: {
+  timingsPath?: string;
+  windowHours?: number;
+  homeDir?: string;
+} = {}): number {
+  if (!isTelemetryEnabled(opts.homeDir)) return 0;
+  const summaries = computeHookPerfSummaries(opts);
+  for (const s of summaries) {
+    logHookPerfEvent({
+      hook_name: s.hook_name,
+      p50_ms: s.p50_ms,
+      p99_ms: s.p99_ms,
+      count: s.count,
+    }, opts.homeDir);
+  }
+  return summaries.length;
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry (called from session-end-consolidate.ts as fire-and-forget)
+// ---------------------------------------------------------------------------
+
+if (import.meta.main) {
+  try {
+    emitHookPerfEvents();
+  } catch {
+    // best-effort — never disturb session exit
+  }
+  process.exit(0);
+}