@jmylchreest/aide-plugin 0.0.54 → 0.0.56

package/src/core/read-tracking.ts

@@ -0,0 +1,151 @@
+/**
+ * Read tracking — platform-agnostic core logic.
+ *
+ * Tracks file reads per session and checks file freshness against
+ * the aide code index. Used by both Claude Code hooks and OpenCode plugin
+ * to provide smart read hints (suggest code_outline/code_symbols over
+ * redundant file re-reads).
+ *
+ * Gated behind AIDE_CODE_WATCH=1 (file watcher must be enabled).
+ */
+
+import { execFileSync } from "child_process";
+import { isAbsolute, relative, resolve } from "path";
+import { setState, getState } from "./aide-client.js";
+import { debug } from "../lib/logger.js";
+
+const SOURCE = "read-tracking";
+
+/** Prefix for state keys tracking file reads */
+const STATE_KEY_PREFIX = "file-read:";
+
+/**
+ * Result from checking file freshness against the code index.
+ */
+export interface ReadCheckResult {
+  indexed: boolean;
+  fresh: boolean;
+  symbols: number;
+  outline_available: boolean;
+  estimated_tokens: number;
+}
+
+/**
+ * Normalize a file path to a relative path from cwd.
+ * Ensures consistent state keys regardless of absolute/relative input.
+ */
+function toRelativePath(cwd: string, filePath: string): string {
+  const abs = isAbsolute(filePath) ? filePath : resolve(cwd, filePath);
+  return relative(cwd, abs);
+}
+
+/**
+ * Record that a file was read in this session.
+ * Sets a state key so subsequent reads can be detected.
+ *
+ * No-op if AIDE_CODE_WATCH is not enabled.
+ */
+export function recordFileRead(
+  binary: string,
+  cwd: string,
+  filePath: string,
+): void {
+  if (process.env.AIDE_CODE_WATCH !== "1") return;
+
+  try {
+    const relPath = toRelativePath(cwd, filePath);
+    const key = STATE_KEY_PREFIX + relPath;
+    setState(binary, cwd, key, new Date().toISOString());
+    debug(SOURCE, `Recorded read: ${relPath}`);
+  } catch (err) {
+    debug(SOURCE, `Failed to record read: ${err}`);
+  }
+}
+
+/**
+ * Check if a file was previously read in this session.
+ * Returns the ISO timestamp of the last read, or null if not read.
+ *
+ * Returns null if AIDE_CODE_WATCH is not enabled.
+ */
+export function getPreviousRead(
+  binary: string,
+  cwd: string,
+  filePath: string,
+): string | null {
+  if (process.env.AIDE_CODE_WATCH !== "1") return null;
+
+  try {
+    const relPath = toRelativePath(cwd, filePath);
+    const key = STATE_KEY_PREFIX + relPath;
+    return getState(binary, cwd, key);
+  } catch (err) {
+    debug(SOURCE, `Failed to check previous read: ${err}`);
+    return null;
+  }
+}
+
+/**
+ * Check whether a file is indexed and whether its content is fresh
+ * (unchanged since last indexing) by calling `aide code read-check`.
+ *
+ * Returns null on any error (binary not found, command failed, etc.).
+ */
+export function checkFileReadFreshness(
+  binary: string,
+  cwd: string,
+  filePath: string,
+): ReadCheckResult | null {
+  try {
+    const relPath = toRelativePath(cwd, filePath);
+    const output = execFileSync(binary, ["code", "read-check", relPath, "--json"], {
+      cwd,
+      encoding: "utf-8",
+      timeout: 5000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    const result = JSON.parse(output.trim()) as ReadCheckResult;
+    debug(SOURCE, `Read check ${relPath}: indexed=${result.indexed} fresh=${result.fresh} symbols=${result.symbols}`);
+    return result;
+  } catch (err) {
+    debug(SOURCE, `Read check failed: ${err}`);
+    return null;
+  }
+}
+
+/**
+ * Record a token event via `aide token record`.
+ * Fire-and-forget — errors are logged but not propagated.
+ */
+export function recordTokenEvent(
+  binary: string,
+  cwd: string,
+  eventType: string,
+  tool: string,
+  filePath: string,
+  tokens: number,
+  tokensSaved: number = 0,
+): void {
+  try {
+    const args = ["token", "record", eventType, tool, filePath, String(tokens)];
+    if (tokensSaved > 0) {
+      args.push(String(tokensSaved));
+    }
+    execFileSync(binary, args, {
+      cwd,
+      timeout: 3000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    debug(SOURCE, `Token event: ${eventType} ${tool} ${filePath} tokens=${tokens} saved=${tokensSaved}`);
+  } catch (err) {
+    debug(SOURCE, `Failed to record token event: ${err}`);
+  }
+}
+
+/**
+ * Estimate tokens for a file by its size, using the default ratio.
+ * This is a rough client-side estimate; the Go binary has per-language ratios.
+ */
+export function estimateTokensFromSize(sizeBytes: number): number {
+  return Math.round(sizeBytes / 3.0);
+}

package/src/core/session-init.ts

@@ -15,7 +15,7 @@ import {
   unlinkSync,
   statSync,
 } from "fs";
-import { join } from "path";
+import { basename, join } from "path";
 import { execFileSync } from "child_process";
 import { homedir } from "os";
 import type {
@@ -182,7 +182,7 @@ export function getProjectName(cwd: string): string {
     // Not a git repo or no remote
   }
 
-  return cwd.split("/").pop() || "unknown";
+  return basename(cwd) || "unknown";
 }
 
 /**

package/src/core/session-summary-logic.ts

@@ -41,6 +41,78 @@ export function getSessionCommits(cwd: string, startedAt?: string): string[] {
   }
 }
 
+interface TranscriptEntry {
+  type?: string;
+  tool_name?: string;
+  tool_input?: { file_path?: string; [key: string]: unknown };
+  content?:
+    | string
+    | {
+        text?: string;
+        tool_use?: { name?: string; input?: { file_path?: string } };
+      };
+}
+
+interface TranscriptData {
+  filesModified: Set<string>;
+  toolsUsed: Set<string>;
+  userMessages: string[];
+}
+
+/**
+ * Parse raw JSONL transcript lines into structured data.
+ */
+function parseTranscript(lines: string[]): TranscriptData {
+  const entries: TranscriptEntry[] = [];
+  for (const line of lines) {
+    try {
+      const parsed: unknown = JSON.parse(line);
+      if (
+        typeof parsed === "object" &&
+        parsed !== null &&
+        !Array.isArray(parsed)
+      ) {
+        entries.push(parsed as TranscriptEntry);
+      }
+    } catch {
+      // Skip malformed
+    }
+  }
+
+  const filesModified = new Set<string>();
+  const toolsUsed = new Set<string>();
+  const userMessages: string[] = [];
+
+  for (const entry of entries) {
+    const contentObj =
+      typeof entry.content === "object" ? entry.content : null;
+    if (
+      entry.type === "tool_use" ||
+      (entry.type === "assistant" && contentObj?.tool_use)
+    ) {
+      const toolName = entry.tool_name || contentObj?.tool_use?.name;
+      if (toolName) toolsUsed.add(toolName);
+
+      const toolInput = entry.tool_input || contentObj?.tool_use?.input;
+      if (toolInput?.file_path && toolName) {
+        if (["Write", "Edit"].includes(toolName)) {
+          filesModified.add(toolInput.file_path);
+        }
+      }
+    }
+
+    if (entry.type === "human" || entry.type === "user") {
+      const text =
+        typeof entry.content === "string" ? entry.content : contentObj?.text;
+      if (text && text.length > 10 && text.length < 500) {
+        userMessages.push(text.slice(0, 200));
+      }
+    }
+  }
+
+  return { filesModified, toolsUsed, userMessages };
+}
+
 /**
  * Build a session summary from transcript data.
  *
@@ -61,64 +133,7 @@ export function buildSessionSummary(
 
     if (lines.length < 5) return null;
 
-    interface TranscriptEntry {
-      type?: string;
-      tool_name?: string;
-      tool_input?: { file_path?: string; [key: string]: unknown };
-      content?:
-        | string
-        | {
-            text?: string;
-            tool_use?: { name?: string; input?: { file_path?: string } };
-          };
-    }
-
-    const entries: TranscriptEntry[] = [];
-    for (const line of lines) {
-      try {
-        const parsed: unknown = JSON.parse(line);
-        if (
-          typeof parsed === "object" &&
-          parsed !== null &&
-          !Array.isArray(parsed)
-        ) {
-          entries.push(parsed as TranscriptEntry);
-        }
-      } catch {
-        // Skip malformed
-      }
-    }
-
-    const filesModified = new Set<string>();
-    const toolsUsed = new Set<string>();
-    const userMessages: string[] = [];
-
-    for (const entry of entries) {
-      const contentObj =
-        typeof entry.content === "object" ? entry.content : null;
-      if (
-        entry.type === "tool_use" ||
-        (entry.type === "assistant" && contentObj?.tool_use)
-      ) {
-        const toolName = entry.tool_name || contentObj?.tool_use?.name;
-        if (toolName) toolsUsed.add(toolName);
-
-        const toolInput = entry.tool_input || contentObj?.tool_use?.input;
-        if (toolInput?.file_path && toolName) {
-          if (["Write", "Edit"].includes(toolName)) {
-            filesModified.add(toolInput.file_path);
-          }
-        }
-      }
-
-      if (entry.type === "human" || entry.type === "user") {
-        const text =
-          typeof entry.content === "string" ? entry.content : contentObj?.text;
-        if (text && text.length > 10 && text.length < 500) {
-          userMessages.push(text.slice(0, 200));
-        }
-      }
-    }
+    const { filesModified, toolsUsed, userMessages } = parseTranscript(lines);
 
     const commits = getSessionCommits(cwd, startedAt);
 

package/src/core/skill-matcher.ts

@@ -8,11 +8,11 @@
 import { existsSync, readFileSync, readdirSync } from "fs";
 import { join, basename, extname } from "path";
 import { homedir } from "os";
-import { execSync } from "child_process";
+import which from "which";
 import type { Skill, SkillMatchResult } from "./types.js";
 
 /**
- * Cache of binary existence checks to avoid repeated shell invocations.
+ * Cache of binary existence checks to avoid repeated lookups.
  * Maps binary name to boolean (exists on PATH).
  */
 const binaryExistsCache = new Map<string, boolean>();
@@ -25,16 +25,9 @@ function binaryExists(name: string): boolean {
   const cached = binaryExistsCache.get(name);
   if (cached !== undefined) return cached;
 
-  try {
-    const cmd =
-      process.platform === "win32" ? `where ${name}` : `command -v ${name}`;
-    execSync(cmd, { stdio: "ignore", timeout: 2000 });
-    binaryExistsCache.set(name, true);
-    return true;
-  } catch {
-    binaryExistsCache.set(name, false);
-    return false;
-  }
+  const found = which.sync(name, { nothrow: true }) !== null;
+  binaryExistsCache.set(name, found);
+  return found;
 }
 
 // Skill search locations relative to cwd

package/src/core/tool-tracking.ts

@@ -5,6 +5,7 @@
  * Tracks tool usage per-agent and updates session statistics.
  */
 
+import { basename } from "path";
 import { setState, getState } from "./aide-client.js";
 import type { ToolUseInfo } from "./types.js";
 
@@ -31,7 +32,7 @@ export function formatToolDescription(
     case "Read":
       if (toolInput.file_path) {
         const filename =
-          toolInput.file_path.split("/").pop() || toolInput.file_path;
+          basename(toolInput.file_path);
         return `Read(${filename})`;
       }
       return toolName;
@@ -40,7 +41,7 @@ export function formatToolDescription(
     case "Write":
       if (toolInput.file_path) {
         const filename =
-          toolInput.file_path.split("/").pop() || toolInput.file_path;
+          basename(toolInput.file_path);
         return `${toolName}(${filename})`;
       }
       return toolName;

package/src/lib/hud.ts

@@ -290,6 +290,87 @@ async function refreshUsageCache(): Promise<void> {
   }
 }
 
+type ElementFormatter = (
+  state: SessionState,
+  agents: AgentState[],
+  config: HudConfig,
+  cwd: string,
+) => string | null;
+
+const elementFormatters: Record<string, ElementFormatter> = {
+  mode: (state, _agents, config) => {
+    const modeName = state.activeMode || "idle";
+    const toolSuffix = state.lastTool ? `(${state.lastTool})` : "";
+    if (config.format === "icons") {
+      const icon = ICONS.mode[state.activeMode || "none"] || ICONS.mode.none;
+      return `${icon} ${modeName}${toolSuffix}`;
+    }
+    return `mode:${modeName}${toolSuffix}`;
+  },
+
+  agents: (_state, agents, config) => {
+    const runningCount = agents.filter((a) => a.status === "running").length;
+    if (runningCount <= 0) return null;
+    if (config.format === "icons") {
+      return `${ICONS.agents} ${runningCount}`;
+    }
+    return `agents:${runningCount}`;
+  },
+
+  duration: (state, _agents, config) => {
+    const duration = formatDuration(state.startedAt);
+    if (config.format === "icons") {
+      return `${ICONS.time} ${duration}`;
+    }
+    return duration;
+  },
+
+  tools: (state, _agents, config) => {
+    if (state.toolCalls <= 0) return null;
+    if (config.format === "icons") {
+      return `🔧 ${state.toolCalls}`;
+    }
+    return `tools:${state.toolCalls}`;
+  },
+
+  usage: (_state, _agents, config, cwd) => {
+    const cacheTTL = config.usageCacheTTL
+      ? config.usageCacheTTL * 1000
+      : undefined;
+    const usage = getUsageSummary(cwd, cacheTTL);
+    if (!usage) return null;
+
+    const fmt = (n: number) =>
+      n >= 1000000
+        ? `${(n / 1000000).toFixed(1)}M`
+        : n >= 1000
+          ? `${(n / 1000).toFixed(0)}K`
+          : `${n}`;
+
+    let usageStr: string;
+    if (usage.fiveHourPercent !== null) {
+      // API-sourced percentages (accurate)
+      const remainStr =
+        usage.fiveHourRemain && usage.fiveHourRemain !== "expired"
+          ? ` ~${usage.fiveHourRemain}`
+          : "";
+      const weekStr =
+        usage.weeklyPercent !== null
+          ? ` wk:${Math.round(usage.weeklyPercent)}%`
+          : "";
+      usageStr = `5h:${Math.round(usage.fiveHourPercent)}%${remainStr}${weekStr}`;
+    } else {
+      // Fallback to weighted token counts
+      usageStr = `5h:${fmt(usage.window5hTokens)}`;
+    }
+
+    if (config.format === "icons") {
+      return `📊 ${usageStr}`;
+    }
+    return usageStr;
+  },
+};
+
 /**
  * Format HUD output based on config
  */
@@ -304,92 +385,10 @@ export function formatHud(
   const parts: string[] = [];
 
   for (const element of config.elements) {
-    switch (element) {
-      case "mode": {
-        const modeName = state.activeMode || "idle";
-        const toolSuffix = state.lastTool ? `(${state.lastTool})` : "";
-        if (config.format === "icons") {
-          const icon =
-            ICONS.mode[state.activeMode || "none"] || ICONS.mode.none;
-          parts.push(`${icon} ${modeName}${toolSuffix}`);
-        } else {
-          parts.push(`mode:${modeName}${toolSuffix}`);
-        }
-        break;
-      }
-
-      case "agents": {
-        const runningCount = agents.filter(
-          (a) => a.status === "running",
-        ).length;
-        if (runningCount > 0) {
-          if (config.format === "icons") {
-            parts.push(`${ICONS.agents} ${runningCount}`);
-          } else {
-            parts.push(`agents:${runningCount}`);
-          }
-        }
-        break;
-      }
-
-      case "duration": {
-        const duration = formatDuration(state.startedAt);
-        if (config.format === "icons") {
-          parts.push(`${ICONS.time} ${duration}`);
-        } else {
-          parts.push(duration);
-        }
-        break;
-      }
-
-      case "tools":
-        if (state.toolCalls > 0) {
-          if (config.format === "icons") {
-            parts.push(`🔧 ${state.toolCalls}`);
-          } else {
-            parts.push(`tools:${state.toolCalls}`);
-          }
-        }
-        break;
-
-      case "usage": {
-        const cacheTTL = config.usageCacheTTL
-          ? config.usageCacheTTL * 1000
-          : undefined;
-        const usage = getUsageSummary(cwd, cacheTTL);
-        if (usage) {
-          const fmt = (n: number) =>
-            n >= 1000000
-              ? `${(n / 1000000).toFixed(1)}M`
-              : n >= 1000
-                ? `${(n / 1000).toFixed(0)}K`
-                : `${n}`;
-
-          let usageStr: string;
-          if (usage.fiveHourPercent !== null) {
-            // API-sourced percentages (accurate)
-            const remainStr =
-              usage.fiveHourRemain && usage.fiveHourRemain !== "expired"
-                ? ` ~${usage.fiveHourRemain}`
-                : "";
-            const weekStr =
-              usage.weeklyPercent !== null
-                ? ` wk:${Math.round(usage.weeklyPercent)}%`
-                : "";
-            usageStr = `5h:${Math.round(usage.fiveHourPercent)}%${remainStr}${weekStr}`;
-          } else {
-            // Fallback to weighted token counts
-            usageStr = `5h:${fmt(usage.window5hTokens)}`;
-          }
-
-          if (config.format === "icons") {
-            parts.push(`📊 ${usageStr}`);
-          } else {
-            parts.push(usageStr);
-          }
-        }
-        break;
-      }
+    const formatter = elementFormatters[element];
+    if (formatter) {
+      const part = formatter(state, agents, config, cwd);
+      if (part) parts.push(part);
     }
   }
 

package/src/lib/logger.ts

@@ -2,7 +2,9 @@
  * AIDE Debug Logger
  *
  * Provides timing and tracing for hooks and operations.
- * Disabled by default - enable with AIDE_DEBUG=1 environment variable.
+ * Disabled by default. Enable with either:
+ *   1. AIDE_DEBUG=1 environment variable
+ *   2. touch .aide/.debug sentinel file (no restart needed)
  *
  * Usage:
  *   import { Logger } from '../lib/logger';
@@ -13,7 +15,8 @@
  *   log.flush();  // Write all logs to file
  *
  * Enable logging:
- *   AIDE_DEBUG=1 claude
+ *   AIDE_DEBUG=1 claude          # env var (requires restart)
+ *   touch .aide/.debug           # sentinel file (live toggle)
  */
 
 import { existsSync, mkdirSync, appendFileSync, writeFileSync } from "fs";
@@ -46,10 +49,11 @@ export class Logger {
   private sessionStart: number;
 
   constructor(source: string, cwd?: string) {
-    const debugEnv = process.env.AIDE_DEBUG || "";
-    this.enabled = debugEnv === "1" || debugEnv === "true";
     this.source = source;
     this.cwd = cwd || process.cwd();
+    // Set debugLogCwd so isDebugEnabled() can check the sentinel file
+    if (cwd) setDebugCwd(cwd);
+    this.enabled = isDebugEnabled();
     this.logDir = join(this.cwd, ".aide", "_logs");
     this.logFile = join(this.logDir, "startup.log");
     this.sessionStart = Date.now();
@@ -329,16 +333,39 @@ export function getLogger(source: string, cwd?: string): Logger {
   return defaultLogger;
 }
 
+// Debug log state - tracks cwd for file-based logging
+let debugLogCwd = process.cwd();
+
+// Cache sentinel file check per cwd to avoid repeated stat calls
+let debugSentinelCwd = "";
+let debugSentinelResult = false;
+
 /**
- * Quick check if debug logging is enabled
+ * Quick check if debug logging is enabled.
+ *
+ * Checks (in order):
+ * 1. AIDE_DEBUG=1 environment variable
+ * 2. .aide/.debug sentinel file in the project root
+ *
+ * The sentinel file allows enabling debug without restarting Claude.
+ * Create it with: touch .aide/.debug
+ * Remove it with: rm .aide/.debug
  */
 export function isDebugEnabled(): boolean {
   const debugEnv = process.env.AIDE_DEBUG || "";
-  return debugEnv === "1" || debugEnv === "true";
-}
+  if (debugEnv === "1" || debugEnv === "true") return true;
 
-// Debug log state - tracks cwd for file-based logging
-let debugLogCwd = process.cwd();
+  // Check sentinel file (cached per cwd)
+  if (debugLogCwd !== debugSentinelCwd) {
+    debugSentinelCwd = debugLogCwd;
+    try {
+      debugSentinelResult = existsSync(join(debugLogCwd, ".aide", ".debug"));
+    } catch {
+      debugSentinelResult = false;
+    }
+  }
+  return debugSentinelResult;
+}
 
 /**
  * Set the working directory for debug logging.
@@ -346,6 +373,8 @@ let debugLogCwd = process.cwd();
  */
 export function setDebugCwd(cwd: string): void {
   debugLogCwd = cwd;
+  // Invalidate sentinel cache so next isDebugEnabled() re-checks
+  debugSentinelCwd = "";
 }
 
 /**