token-pilot 0.32.0 → 0.33.1

package/dist/core/error-log.js

@@ -0,0 +1,228 @@
+/**
+ * v0.34.0 — error / diagnostic channel for token-pilot hooks + CLI.
+ *
+ * Why a separate file from `hook-events.jsonl`:
+ *   - hook-events lives in `<projectRoot>/.token-pilot/`. When the hook
+ *     itself fails BEFORE projectRoot is resolved (B8 WSL detection,
+ *     missing dir, ENOENT), there is nowhere to write the regular log.
+ *   - Errors must outlive a single project — when a user reports
+ *     "nothing logs anymore" we want one absolute path to look at.
+ *
+ * Layout:
+ *   ~/.token-pilot/hook-errors.jsonl
+ *
+ * Format: one JSON record per line. Schema in `HookErrorRecord` below.
+ *
+ * Discipline:
+ *   - Never throws. The error logger is itself the last line of defence —
+ *     a throw here would defeat the wrapper that calls it.
+ *   - Cap-and-rotate: when the file passes MAX_BYTES the writer renames
+ *     it to `hook-errors.<ts>.jsonl` and starts fresh. Old archives
+ *     past RETENTION_MS are pruned best-effort on each append.
+ *   - `TOKEN_PILOT_NO_ERROR_LOG=1` opts out entirely.
+ *
+ * Privacy:
+ *   - The `input` field is whatever the hook chose to record. Callers
+ *     MUST sanitize before passing it in — no full paths, no file
+ *     content, no prompts. Helpers `safeBasename()` / `safePathInfo()`
+ *     are provided for the common cases.
+ */
+import * as fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+// ─── constants ───────────────────────────────────────────────────────
+const MAX_BYTES = 5 * 1024 * 1024; // 5 MB before rotate
+const RETENTION_MS = 30 * 24 * 3600 * 1000; // 30d archive retention
+const ARCHIVE_RE = /^hook-errors\.(\d+)\.jsonl$/;
+const CURRENT = "hook-errors.jsonl";
+// ─── path resolution ─────────────────────────────────────────────────
+export function errorLogDir() {
+    return join(homedir(), ".token-pilot");
+}
+export function errorLogPath() {
+    return join(errorLogDir(), CURRENT);
+}
+// ─── env opt-out ─────────────────────────────────────────────────────
+function isOptedOut() {
+    return process.env.TOKEN_PILOT_NO_ERROR_LOG === "1";
+}
+// ─── sanitizers ──────────────────────────────────────────────────────
+/**
+ * Reduce a path to its basename. Use everywhere a path could leak:
+ * the user's project tree, file content, anything not strictly an
+ * identifier. Returns `"<empty>"` for missing input rather than null
+ * so the field stays shape-stable.
+ */
+export function safeBasename(p) {
+    if (typeof p !== "string" || p.length === 0)
+        return "<empty>";
+    return basename(p);
+}
+/**
+ * Capture only the metadata about a path — basename + length + ext —
+ * dropping the absolute path entirely. Useful when the analysis
+ * benefits from "kind of file" without revealing where it lived.
+ */
+export function safePathInfo(p) {
+    if (typeof p !== "string" || p.length === 0) {
+        return { name: "<empty>", ext: "" };
+    }
+    const name = basename(p);
+    const dot = name.lastIndexOf(".");
+    return {
+        name,
+        ext: dot >= 0 ? name.slice(dot).toLowerCase() : "",
+    };
+}
+// ─── error classification ────────────────────────────────────────────
+/**
+ * Map a thrown value to a stable, searchable `code`. The classifier
+ * is intentionally simple — node ErrnoException codes pass through,
+ * everything else falls into a coarse bucket. New cases land here
+ * only when a pattern shows up repeatedly in the wild.
+ */
+export function classifyError(err) {
+    if (err && typeof err === "object") {
+        const e = err;
+        if (typeof e.code === "string" && e.code.length > 0)
+            return e.code;
+        const name = e.name;
+        if (name === "SyntaxError")
+            return "parse_error";
+        if (name === "TypeError")
+            return "type_error";
+    }
+    if (err instanceof Error) {
+        const m = err.message.toLowerCase();
+        if (m.includes("timeout"))
+            return "timeout";
+        if (m.includes("not initialized"))
+            return "not_initialized";
+        if (m.includes("permission denied"))
+            return "EACCES";
+    }
+    return "unknown";
+}
+// ─── rotate + retention ──────────────────────────────────────────────
+async function rotateIfNeeded() {
+    const p = errorLogPath();
+    try {
+        const stat = await fs.stat(p);
+        if (stat.size < MAX_BYTES)
+            return;
+        const archive = join(errorLogDir(), `hook-errors.${Date.now()}.jsonl`);
+        await fs.rename(p, archive);
+    }
+    catch {
+        /* missing or stat failure — append will create */
+    }
+}
+async function pruneArchives() {
+    const dir = errorLogDir();
+    let entries;
+    try {
+        entries = await fs.readdir(dir);
+    }
+    catch {
+        return;
+    }
+    const cutoff = Date.now() - RETENTION_MS;
+    for (const name of entries) {
+        const m = name.match(ARCHIVE_RE);
+        if (!m)
+            continue;
+        const ts = Number(m[1]);
+        if (!Number.isFinite(ts))
+            continue;
+        if (ts < cutoff) {
+            try {
+                await fs.unlink(join(dir, name));
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    }
+}
+// ─── append ──────────────────────────────────────────────────────────
+export async function appendError(rec) {
+    if (isOptedOut())
+        return;
+    try {
+        await fs.mkdir(errorLogDir(), { recursive: true });
+        await rotateIfNeeded();
+        await fs.appendFile(errorLogPath(), JSON.stringify(rec) + "\n");
+        // best-effort retention sweep — not awaited tightly because a slow
+        // FS shouldn't slow the hook hot-path; failures are silent.
+        pruneArchives().catch(() => { });
+    }
+    catch {
+        /* logger of last resort — never throw */
+    }
+}
+export async function loadErrors(opts = {}) {
+    const p = opts.path ?? errorLogPath();
+    let raw;
+    try {
+        raw = await fs.readFile(p, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const rec = JSON.parse(line);
+            if (opts.code && rec.code !== opts.code)
+                continue;
+            if (opts.hook && rec.hook !== opts.hook)
+                continue;
+            if (opts.level && rec.level !== opts.level)
+                continue;
+            out.push(rec);
+        }
+        catch {
+            /* skip malformed */
+        }
+    }
+    // Newest first — most useful default ordering for a tail view.
+    out.sort((a, b) => (b.ts || 0) - (a.ts || 0));
+    if (opts.tail && opts.tail > 0) {
+        return out.slice(0, opts.tail);
+    }
+    return out;
+}
+// ─── format ──────────────────────────────────────────────────────────
+export function formatErrorList(records) {
+    if (records.length === 0) {
+        return "No errors logged.";
+    }
+    const counts = new Map();
+    for (const r of records) {
+        counts.set(r.code, (counts.get(r.code) ?? 0) + 1);
+    }
+    const top = Array.from(counts.entries())
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10);
+    const lines = [];
+    lines.push(`token-pilot errors — ${records.length} total`);
+    lines.push("");
+    lines.push("Top codes:");
+    for (const [code, n] of top) {
+        lines.push(`  ${String(n).padStart(4)}× ${code}`);
+    }
+    lines.push("");
+    lines.push("Most recent:");
+    const recent = records.slice(0, 20);
+    for (const r of recent) {
+        const when = new Date(r.ts).toISOString().slice(11, 19);
+        lines.push(`  [${when}] ${r.level.toUpperCase().padEnd(5)} ${r.hook} ${r.code} — ${r.msg}`);
+    }
+    return lines.join("\n");
+}
+// ─── exports for indirection from index.ts ───────────────────────────
+export { existsSync, resolve, dirname };
+//# sourceMappingURL=error-log.js.map

package/dist/core/event-log.d.ts

@@ -28,7 +28,7 @@ export interface HookEvent {
     /** null for top-level session; agent_type string inside a subagent. */
     agent_type: string | null;
     agent_id: string | null;
-    event: "denied" | "allowed" | "bypass" | "pass-through" | "task" | string;
+    event: "denied" | "allowed" | "bypass" | "pass-through" | "task" | "diagnostic" | string;
     file: string;
     lines: number;
     estTokens: number;
@@ -36,6 +36,18 @@ export interface HookEvent {
     summaryTokens: number;
     /** estTokens - summaryTokens; 0 for allow/bypass. */
     savedTokens: number;
+    /** "info" | "warn" | "error" — severity of the diagnostic. */
+    level?: "info" | "warn" | "error";
+    /** Stable searchable identifier — e.g. `force_subagents_no_agents`. */
+    code?: string;
+    /** Optional small map of context — must be sanitised by caller. */
+    detail?: Record<string, unknown>;
+    /**
+     * Wall-clock duration of the hook handler that emitted this event,
+     * milliseconds. Always optional — only the safe-runner wrapper sets
+     * it, and only on the FINAL diagnostic record per hook invocation.
+     */
+    duration_ms?: number;
     /** The subagent_type Claude Code dispatched (`tp-*` or `general-purpose`…). */
     subagent_type?: string;
     /**
@@ -78,12 +90,48 @@ export declare function retentionDeletions(files: Array<{
  * here must not break hook dispatch.
  */
 export declare function appendEvent(projectRoot: string, event: HookEvent): Promise<void>;
+/**
+ * v0.34.0 — convenience wrapper for emitting a `diagnostic` event.
+ *
+ * Diagnostics describe edge-case branches inside a normal handler
+ * run (matcher returned no agents, WSL path rejected, MCP arg
+ * coerced, etc.). They live in the project-local hook-events.jsonl
+ * alongside the regular events so `stats --diagnostics` can count
+ * them by code.
+ *
+ * If the projectRoot is not yet resolvable (the failure happened
+ * before detection), prefer `appendError` from `core/error-log.ts`
+ * — it falls back to a user-level path.
+ *
+ * Pure-ish: never throws. Same best-effort semantics as appendEvent.
+ */
+export declare function appendDiagnostic(projectRoot: string, args: {
+    code: string;
+    level?: "info" | "warn" | "error";
+    detail?: Record<string, unknown>;
+    sessionId?: string;
+    agentType?: string | null;
+    agentId?: string | null;
+    durationMs?: number;
+}): Promise<void>;
 /**
  * Read all events from the current log file. Malformed JSONL lines are
  * skipped silently (a corrupted line should not poison the whole
  * dataset). Returns [] if the file is missing.
  */
 export declare function loadEvents(projectRoot: string): Promise<HookEvent[]>;
+/**
+ * v0.33.0 (B5) — load events from EVERY `.token-pilot/hook-events.jsonl`
+ * found at or below `repoRoot`. The hook writer resolves its own
+ * project root from `process.cwd()` at the moment Claude Code spawns
+ * us, which can land in a subdirectory of the actual repo (apps/admin,
+ * apps/api, packages/prisma, …). Without this, `token-pilot stats`
+ * sees only the top-level log and reports a fraction of the savings.
+ *
+ * Walks up to `maxDepth` levels and merges chronologically. Pure on
+ * filesystem read errors — missing dirs are silently skipped.
+ */
+export declare function loadEventsTree(repoRoot: string, maxDepth?: number): Promise<HookEvent[]>;
 /**
  * Apply age + size retention. Safe to call on startup; no-op when the
  * directory does not exist.

package/dist/core/event-log.js

@@ -117,6 +117,40 @@ export async function appendEvent(projectRoot, event) {
         /* silent — telemetry is best-effort */
     }
 }
+/**
+ * v0.34.0 — convenience wrapper for emitting a `diagnostic` event.
+ *
+ * Diagnostics describe edge-case branches inside a normal handler
+ * run (matcher returned no agents, WSL path rejected, MCP arg
+ * coerced, etc.). They live in the project-local hook-events.jsonl
+ * alongside the regular events so `stats --diagnostics` can count
+ * them by code.
+ *
+ * If the projectRoot is not yet resolvable (the failure happened
+ * before detection), prefer `appendError` from `core/error-log.ts`
+ * — it falls back to a user-level path.
+ *
+ * Pure-ish: never throws. Same best-effort semantics as appendEvent.
+ */
+export async function appendDiagnostic(projectRoot, args) {
+    const rec = {
+        ts: Date.now(),
+        session_id: args.sessionId ?? "diagnostic",
+        agent_type: args.agentType ?? null,
+        agent_id: args.agentId ?? null,
+        event: "diagnostic",
+        file: "",
+        lines: 0,
+        estTokens: 0,
+        summaryTokens: 0,
+        savedTokens: 0,
+        level: args.level ?? "info",
+        code: args.code,
+        detail: args.detail,
+        duration_ms: args.durationMs,
+    };
+    await appendEvent(projectRoot, rec);
+}
 /**
  * Read all events from the current log file. Malformed JSONL lines are
  * skipped silently (a corrupted line should not poison the whole
@@ -143,6 +177,86 @@ export async function loadEvents(projectRoot) {
     }
     return out;
 }
+/**
+ * v0.33.0 (B5) — load events from EVERY `.token-pilot/hook-events.jsonl`
+ * found at or below `repoRoot`. The hook writer resolves its own
+ * project root from `process.cwd()` at the moment Claude Code spawns
+ * us, which can land in a subdirectory of the actual repo (apps/admin,
+ * apps/api, packages/prisma, …). Without this, `token-pilot stats`
+ * sees only the top-level log and reports a fraction of the savings.
+ *
+ * Walks up to `maxDepth` levels and merges chronologically. Pure on
+ * filesystem read errors — missing dirs are silently skipped.
+ */
+export async function loadEventsTree(repoRoot, maxDepth = 5) {
+    const PRUNE = new Set([
+        "node_modules",
+        ".git",
+        "dist",
+        "build",
+        ".next",
+        ".turbo",
+        ".cache",
+        "coverage",
+        ".vercel",
+        ".vite",
+    ]);
+    const seen = new Set();
+    const all = [];
+    async function visit(dir, depth) {
+        if (depth > maxDepth)
+            return;
+        let entries = [];
+        try {
+            entries = await fs.readdir(dir);
+        }
+        catch {
+            return;
+        }
+        if (entries.includes(".token-pilot")) {
+            const logPath = join(dir, ".token-pilot", CURRENT_FILE);
+            if (!seen.has(logPath)) {
+                seen.add(logPath);
+                try {
+                    const raw = await fs.readFile(logPath, "utf-8");
+                    for (const line of raw.split("\n")) {
+                        if (!line.trim())
+                            continue;
+                        try {
+                            all.push(JSON.parse(line));
+                        }
+                        catch {
+                            /* skip malformed */
+                        }
+                    }
+                }
+                catch {
+                    /* missing log */
+                }
+            }
+        }
+        for (const name of entries) {
+            if (PRUNE.has(name))
+                continue;
+            if (name.startsWith(".") && name !== ".claude")
+                continue;
+            const full = join(dir, name);
+            try {
+                const stat = await fs.stat(full);
+                if (stat.isDirectory()) {
+                    await visit(full, depth + 1);
+                }
+            }
+            catch {
+                /* skip */
+            }
+        }
+    }
+    await visit(repoRoot, 0);
+    // Sort chronologically so per-session aggregations stay correct.
+    all.sort((a, b) => (a.ts || 0) - (b.ts || 0));
+    return all;
+}
 /**
  * Enumerate all archive files (`hook-events.<ts>.jsonl`) with metadata
  * needed by `retentionDeletions`.

package/dist/core/validation.d.ts

@@ -1,3 +1,15 @@
+/**
+ * v0.33.0 (B9) — coerce an `unknown` argument value to an integer.
+ *
+ * MCP transports frequently round-trip numeric arguments through
+ * JSON or environment variables and re-emit them as strings (e.g.
+ * `"42"`). Accept that case and reject everything else, including
+ * non-finite numbers, decimals, and strings that don't parse cleanly.
+ *
+ * Returns the integer value or `null` when the input cannot be
+ * interpreted as one.
+ */
+export declare function coerceIntFromAny(value: unknown): number | null;
 /**
  * Resolve a user-provided path and validate it stays within projectRoot.
  * Prevents path traversal attacks (e.g. ../../etc/passwd).

package/dist/core/validation.js

@@ -1,4 +1,34 @@
 import { resolve, relative } from "node:path";
+/**
+ * v0.33.0 (B9) — coerce an `unknown` argument value to an integer.
+ *
+ * MCP transports frequently round-trip numeric arguments through
+ * JSON or environment variables and re-emit them as strings (e.g.
+ * `"42"`). Accept that case and reject everything else, including
+ * non-finite numbers, decimals, and strings that don't parse cleanly.
+ *
+ * Returns the integer value or `null` when the input cannot be
+ * interpreted as one.
+ */
+export function coerceIntFromAny(value) {
+    if (typeof value === "number") {
+        if (!Number.isFinite(value) || !Number.isInteger(value))
+            return null;
+        return value;
+    }
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (trimmed.length === 0)
+            return null;
+        if (!/^-?\d+$/.test(trimmed))
+            return null;
+        const n = Number(trimmed);
+        if (!Number.isFinite(n) || !Number.isInteger(n))
+            return null;
+        return n;
+    }
+    return null;
+}
 /**
  * Resolve a user-provided path and validate it stays within projectRoot.
  * Prevents path traversal attacks (e.g. ../../etc/passwd).
@@ -110,20 +140,20 @@ export function validateReadRangeArgs(args) {
     if (typeof a.path !== "string" || a.path.length === 0) {
         throw new Error('Required parameter "path" must be a non-empty string.');
     }
-    if (typeof a.start_line !== "number" ||
-        !Number.isInteger(a.start_line) ||
-        a.start_line < 1) {
+    // v0.33.0 (B9) — some MCP clients serialise numbers as strings;
+    // accept "10" the same as 10. Reject non-numeric strings.
+    const start = coerceIntFromAny(a.start_line);
+    if (start === null || start < 1) {
         throw new Error('Required parameter "start_line" must be a positive integer.');
     }
-    if (typeof a.end_line !== "number" ||
-        !Number.isInteger(a.end_line) ||
-        a.end_line < 1) {
+    const end = coerceIntFromAny(a.end_line);
+    if (end === null || end < 1) {
         throw new Error('Required parameter "end_line" must be a positive integer.');
     }
-    if (a.end_line < a.start_line) {
+    if (end < start) {
         throw new Error('"end_line" must be >= "start_line".');
     }
-    return { path: a.path, start_line: a.start_line, end_line: a.end_line };
+    return { path: a.path, start_line: start, end_line: end };
 }
 /**
  * Validate read_diff arguments.

package/dist/handlers/smart-log.js

@@ -14,14 +14,19 @@ const MAX_COUNT = 50;
 export async function handleSmartLog(args, projectRoot) {
     const count = Math.min(args.count ?? 10, MAX_COUNT);
     const ref = args.ref ?? 'HEAD';
-    // Build git log command with --numstat for file stats
+    // Build git log command with --numstat for file stats.
+    // v0.33.0 (B6) — `ref` MUST be a revision argument, not a pathspec.
+    // The previous version pushed `'--', ref` which made git interpret
+    // `HEAD` as a path (`git log -- HEAD`) and silently returned empty.
+    // Adding a path then produced `git log -- HEAD -- foo.ts` — invalid.
+    // Correct order: `git log <flags> <ref> [-- <path>]`.
     const gitArgs = [
         'log',
         `--format=${RECORD_SEPARATOR}%h${FIELD_SEPARATOR}%ad${FIELD_SEPARATOR}%an${FIELD_SEPARATOR}%s`,
         '--date=short',
         '--numstat',
         `-n`, `${count}`,
-        '--', ref,
+        ref,
     ];
     if (args.path) {
         gitArgs.push('--', args.path);

package/dist/hooks/installer.d.ts

@@ -14,6 +14,20 @@ export interface HookInstallOptions {
     /** Absolute path to the node binary. Defaults to process.execPath. */
     nodeExecPath?: string;
 }
+/**
+ * Detect a stale token-pilot hook command — one that points at a
+ * pinned npx-cache snapshot (`npx/_npx/<hash>/...`) or any other
+ * version-pinned path that won't follow plugin upgrades.
+ *
+ * v0.33.0 fix: users who ran `npx token-pilot init` early on got
+ * settings.json entries with literal `~/.npm/_npx/<hash>/...` paths.
+ * When the npx cache rotates or token-pilot publishes a new minor,
+ * those entries silently call the old binary, missing every hook
+ * shipped after install (e.g. v0.31.0 Task hooks). Removing the
+ * stale entry lets the next install or the bundled plugin's
+ * `hooks/hooks.json` (CLAUDE_PLUGIN_ROOT) take over.
+ */
+export declare function isStaleTokenPilotHookCommand(cmd: unknown): boolean;
 /**
  * Install Token Pilot hook into Claude Code settings.
  * Creates or updates .claude/settings.json with PreToolUse hook.
@@ -23,4 +37,30 @@ export declare function installHook(projectRoot: string, options?: HookInstallOp
  * Remove Token Pilot hook from Claude Code settings.
  */
 export declare function uninstallHook(projectRoot: string): Promise<HookUninstallResult>;
+export interface CleanStaleResult {
+    scanned: string[];
+    cleaned: string[];
+    staleEntriesRemoved: number;
+    message: string;
+}
+/**
+ * Scan a settings.json (user-level or project-level) and remove every
+ * token-pilot hook entry whose command points at a pinned npx-cache
+ * snapshot or a literal plugin-cache version path. The plugin's bundled
+ * `hooks/hooks.json` (resolved through `${CLAUDE_PLUGIN_ROOT}` at
+ * runtime) supersedes them.
+ *
+ * Pure-ish: writes only when something changed. Never throws — bad JSON
+ * or missing file are reported in the result so callers (CLI, init)
+ * can surface them without aborting.
+ */
+export declare function cleanStaleHookEntries(settingsPath: string): Promise<CleanStaleResult>;
+/**
+ * Inspect `~/.claude/settings.json` to determine whether the user has
+ * enabled the bundled `token-pilot` plugin in Claude Code. When true,
+ * the plugin's own `hooks/hooks.json` is the source of truth and any
+ * additional hook entries written by the npm CLI are duplicates that
+ * also lock the user to whichever binary path the CLI captured.
+ */
+export declare function isTokenPilotPluginEnabled(homeDir: string): Promise<boolean>;
 //# sourceMappingURL=installer.d.ts.map