token-pilot 0.31.0 → 0.33.0

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).
@@ -22,7 +34,7 @@ export declare function validateReadSymbolArgs(args: unknown): {
     symbol: string;
     context_before?: number;
     context_after?: number;
-    show?: 'full' | 'head' | 'tail' | 'outline';
+    show?: "full" | "head" | "tail" | "outline";
 };
 /**
  * Validate read_symbols arguments (batch multi-symbol read).
@@ -32,7 +44,7 @@ export declare function validateReadSymbolsArgs(args: unknown): {
     symbols: string[];
     context_before?: number;
     context_after?: number;
-    show?: 'full' | 'head' | 'tail' | 'outline';
+    show?: "full" | "head" | "tail" | "outline";
 };
 /**
  * Validate read_range arguments.
@@ -56,11 +68,11 @@ export declare function validateReadDiffArgs(args: unknown): {
 export interface FindUsagesArgs {
     symbol: string;
     scope?: string;
-    kind?: 'definitions' | 'imports' | 'usages' | 'all';
+    kind?: "definitions" | "imports" | "usages" | "all";
     limit?: number;
     lang?: string;
     context_lines?: number;
-    mode?: 'full' | 'list';
+    mode?: "full" | "list";
 }
 export declare function validateFindUsagesArgs(args: unknown): FindUsagesArgs;
 /**
@@ -105,8 +117,12 @@ export declare function validateFindUnusedArgs(args: unknown): {
     export_only?: boolean;
     limit?: number;
 };
+export declare function validateCallTreeArgs(args: unknown): {
+    symbol: string;
+    depth?: number;
+};
 export interface CodeAuditArgs {
-    check: 'pattern' | 'todo' | 'deprecated' | 'annotations' | 'all';
+    check: "pattern" | "todo" | "deprecated" | "annotations" | "all";
     pattern?: string;
     name?: string;
     lang?: string;
@@ -118,7 +134,7 @@ export declare function validateCodeAuditArgs(args: unknown): CodeAuditArgs;
  * v1.1: added include filter.
  */
 export interface ProjectOverviewArgs {
-    include?: Array<'stack' | 'ci' | 'quality' | 'architecture'>;
+    include?: Array<"stack" | "ci" | "quality" | "architecture">;
 }
 export declare function validateProjectOverviewArgs(args: unknown): ProjectOverviewArgs;
 /**
@@ -126,14 +142,14 @@ export declare function validateProjectOverviewArgs(args: unknown): ProjectOverv
  */
 export interface ModuleInfoArgs {
     module: string;
-    check?: 'deps' | 'dependents' | 'api' | 'unused-deps' | 'all';
+    check?: "deps" | "dependents" | "api" | "unused-deps" | "all";
 }
 export declare function validateModuleInfoArgs(args: unknown): ModuleInfoArgs;
 /**
  * Validate smart_diff arguments.
  */
 export interface SmartDiffArgs {
-    scope?: 'unstaged' | 'staged' | 'commit' | 'branch';
+    scope?: "unstaged" | "staged" | "commit" | "branch";
     path?: string;
     ref?: string;
 }
@@ -143,7 +159,7 @@ export declare function validateSmartDiffArgs(args: unknown): SmartDiffArgs;
  */
 export interface ExploreAreaArgs {
     path: string;
-    include?: Array<'outline' | 'imports' | 'tests' | 'changes'>;
+    include?: Array<"outline" | "imports" | "tests" | "changes">;
 }
 export declare function validateExploreAreaArgs(args: unknown): ExploreAreaArgs;
 export interface SmartLogArgs {