@jmylchreest/aide-plugin 0.0.54 → 0.0.55

package/bin/aide-wrapper.ts

@@ -0,0 +1,353 @@
+#!/usr/bin/env bun
+/**
+ * aide-wrapper.ts - Ensures aide binary exists before executing
+ *
+ * Cross-platform TypeScript replacement for aide-wrapper.sh.
+ * Called by an assistant's MCP server configuration.
+ * Finds the aide binary, downloads it if missing, then delegates to it.
+ *
+ * Plugin root resolution order:
+ *   1. AIDE_PLUGIN_ROOT  (canonical, platform-agnostic)
+ *   2. CLAUDE_PLUGIN_ROOT (set by Claude Code)
+ *   3. SCRIPT_DIR/..      (fallback: infer from wrapper location)
+ *
+ * Lives at: <plugin-root>/bin/aide-wrapper.ts
+ * Binary at: <plugin-root>/bin/aide[.exe]
+ *
+ * Logs written to: .aide/_logs/wrapper.log
+ */
+
+import { execFileSync, spawnSync } from "child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  appendFileSync,
+  unlinkSync,
+  writeFileSync,
+  rmdirSync,
+} from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+
+const isWindows = process.platform === "win32";
+const EXT = isWindows ? ".exe" : "";
+
+// Resolve symlinks so that invoking via node_modules/.bin/aide-wrapper
+// (which is a symlink to the real package) gives us the real package dir.
+const __filename = fileURLToPath(import.meta.url);
+let scriptDir: string;
+try {
+  scriptDir = dirname(realpathSync(__filename));
+} catch {
+  scriptDir = dirname(__filename);
+}
+
+const PLUGIN_ROOT =
+  process.env.AIDE_PLUGIN_ROOT ||
+  process.env.CLAUDE_PLUGIN_ROOT ||
+  resolve(scriptDir, "..");
+
+const BINARY = join(PLUGIN_ROOT, "bin", `aide${EXT}`);
+const BIN_DIR = join(PLUGIN_ROOT, "bin");
+
+// Setup logging
+const LOG_DIR = join(PLUGIN_ROOT, ".aide", "_logs");
+const LOG_FILE = join(LOG_DIR, "wrapper.log");
+try {
+  mkdirSync(LOG_DIR, { recursive: true });
+} catch {
+  // ignore
+}
+
+function log(msg: string): void {
+  const timestamp = new Date().toISOString().replace("T", " ").replace(/\..+/, "");
+  const line = `[${timestamp}] [aide-wrapper] ${msg}`;
+  process.stderr.write(line + "\n");
+  try {
+    appendFileSync(LOG_FILE, line + "\n");
+  } catch {
+    // ignore log write failures
+  }
+}
+
+/**
+ * Compare semantic versions: returns true if a >= b
+ */
+function versionGte(a: string, b: string): boolean {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const va = pa[i] || 0;
+    const vb = pb[i] || 0;
+    if (va > vb) return true;
+    if (va < vb) return false;
+  }
+  return true;
+}
+
+/**
+ * Get the version string from the aide binary
+ */
+function getBinaryVersion(binary: string): string | null {
+  try {
+    const output = execFileSync(binary, ["version"], {
+      stdio: "pipe",
+      timeout: 5000,
+    })
+      .toString()
+      .trim();
+    const match = output.match(
+      /(\d+\.\d+\.\d+(?:-[a-zA-Z0-9.+]+)?)/,
+    );
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the plugin version from plugin.json or package.json
+ */
+function getPluginVersion(): string | null {
+  for (const relPath of [
+    ".claude-plugin/plugin.json",
+    "package.json",
+  ]) {
+    try {
+      const content = readFileSync(join(PLUGIN_ROOT, relPath), "utf-8");
+      const match = content.match(/"version"\s*:\s*"(\d+\.\d+\.\d+)/);
+      if (match) return match[1];
+    } catch {
+      // skip
+    }
+  }
+  return null;
+}
+
+/**
+ * Check if the binary exists and is executable
+ */
+function binaryExists(): boolean {
+  if (!existsSync(BINARY)) return false;
+  // On Windows, existence is sufficient (no execute bit)
+  if (isWindows) return true;
+  try {
+    execFileSync(BINARY, ["version"], { stdio: "pipe", timeout: 5000 });
+    return true;
+  } catch {
+    // Binary exists but can't execute — might need re-download
+    return false;
+  }
+}
+
+/**
+ * Simple cross-platform file lock.
+ * Uses mkdir as an atomic operation (works on all platforms).
+ * Returns a cleanup function to release the lock.
+ */
+function acquireLock(lockPath: string, timeoutMs: number = 60000): () => void {
+  const start = Date.now();
+  const pollMs = 200;
+
+  while (true) {
+    try {
+      mkdirSync(lockPath);
+      // Write our PID for debugging
+      try {
+        writeFileSync(join(lockPath, "pid"), String(process.pid));
+      } catch {
+        // ignore
+      }
+      return () => {
+        try {
+          unlinkSync(join(lockPath, "pid"));
+        } catch { /* ignore */ }
+        try {
+          // rmdir only works on empty dirs — that's what we want
+          rmdirSync(lockPath);
+        } catch { /* ignore */ }
+      };
+    } catch (err: unknown) {
+      if (
+        err &&
+        typeof err === "object" &&
+        "code" in err &&
+        (err as { code: string }).code === "EEXIST"
+      ) {
+        // Lock held by another process
+        if (Date.now() - start > timeoutMs) {
+          log("ERROR: Timed out waiting for download lock");
+          // Force-remove stale lock and try once more
+          try {
+            unlinkSync(join(lockPath, "pid"));
+          } catch { /* ignore */ }
+          try {
+            rmdirSync(lockPath);
+          } catch { /* ignore */ }
+          throw new Error("Timed out waiting for download lock");
+        }
+        // Poll — use Bun.sleepSync for cross-platform millisecond sleep
+        Bun.sleepSync(pollMs);
+        continue;
+      }
+      throw err;
+    }
+  }
+}
+
+/**
+ * Download the aide binary using the TypeScript downloader
+ */
+function downloadBinary(): void {
+  const LOCKDIR = join(BIN_DIR, ".aide-download.lock");
+
+  // Resolve the downloader script — prefer src/ (dev) but fall back to dist/ (npm install)
+  let downloader: string;
+  if (existsSync(join(PLUGIN_ROOT, "src", "lib", "aide-downloader.ts"))) {
+    downloader = join(PLUGIN_ROOT, "src", "lib", "aide-downloader.ts");
+  } else if (existsSync(join(PLUGIN_ROOT, "dist", "lib", "aide-downloader.js"))) {
+    downloader = join(PLUGIN_ROOT, "dist", "lib", "aide-downloader.js");
+  } else {
+    log(`ERROR: Cannot find aide-downloader in src/ or dist/ under ${PLUGIN_ROOT}`);
+    process.exit(1);
+  }
+
+  // Remove stale/outdated binary before locking
+  if (existsSync(BINARY)) {
+    log("Removing outdated binary before download");
+    try {
+      unlinkSync(BINARY);
+    } catch {
+      // ignore
+    }
+  }
+
+  const releaseLock = acquireLock(LOCKDIR);
+  try {
+    // Re-check after acquiring lock — another process may have finished the download
+    if (existsSync(BINARY)) {
+      log("Binary appeared while waiting for lock (downloaded by another process)");
+      return;
+    }
+
+    log("Downloading binary...");
+    log(`Using downloader: ${downloader}`);
+
+    // Determine runner based on file extension
+    let runner: string;
+    let runnerArgs: string[];
+
+    if (downloader.endsWith(".ts")) {
+      runner = "bun";
+      runnerArgs = [downloader, "--dest", BIN_DIR];
+    } else {
+      runner = "node";
+      runnerArgs = [downloader, "--dest", BIN_DIR];
+    }
+
+    // Use cross-spawn for cross-platform compatibility (lazy import to
+    // survive missing node_modules during bootstrap).
+    const crossSpawn = require("cross-spawn");
+    const result = crossSpawn.sync(runner, runnerArgs, {
+      stdio: ["ignore", "inherit", "inherit"],
+      timeout: 120000,
+    });
+
+    if (result.status !== 0) {
+      log("ERROR: Downloader failed");
+      process.exit(1);
+    }
+
+    if (!existsSync(BINARY)) {
+      log("ERROR: Binary not found after download");
+      process.exit(1);
+    }
+  } finally {
+    releaseLock();
+  }
+
+  log(`Binary ready at ${BINARY}`);
+}
+
+// --- Ensure dependencies ---
+
+// After a Claude Code marketplace autoUpdate (git pull), node_modules/
+// may be missing since it's gitignored. Detect and self-heal before any
+// imports that depend on npm packages (e.g. 'which', 'cross-spawn').
+function ensureDependencies(): void {
+  const nodeModules = join(PLUGIN_ROOT, "node_modules");
+  if (!existsSync(nodeModules)) {
+    log("node_modules missing — running bun install to restore dependencies");
+    try {
+      const result = spawnSync("bun", ["install", "--frozen-lockfile"], {
+        cwd: PLUGIN_ROOT,
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 60000,
+      });
+      if (result.status === 0) {
+        log("bun install completed successfully");
+      } else {
+        const stderr = result.stderr?.toString().trim();
+        log(`WARNING: bun install failed (status ${result.status}): ${stderr}`);
+      }
+    } catch (err) {
+      log(`WARNING: bun install error: ${err}`);
+    }
+  }
+}
+
+ensureDependencies();
+
+// --- Main ---
+
+log(
+  `Starting wrapper (pid=${process.pid}, args=${process.argv.slice(2).join(" ")})`,
+);
+log(`PLUGIN_ROOT=${PLUGIN_ROOT}`);
+log(`BINARY=${BINARY}`);
+
+let needsDownload = false;
+
+if (!binaryExists()) {
+  needsDownload = true;
+  log("Binary not found or not executable");
+} else {
+  const binaryVersion = getBinaryVersion(BINARY);
+  log(`Binary version: ${binaryVersion ?? "unknown"}`);
+
+  if (binaryVersion && binaryVersion.includes("-dev.")) {
+    // Dev build — check base version against plugin version
+    const baseVersion = binaryVersion.split("-")[0];
+    const pluginVersion = getPluginVersion();
+
+    if (pluginVersion && versionGte(baseVersion, pluginVersion)) {
+      log(
+        `Dev build v${binaryVersion} (base ${baseVersion} >= plugin v${pluginVersion}), using local build`,
+      );
+    } else {
+      needsDownload = true;
+      log(
+        `Dev build v${binaryVersion} is older than plugin v${pluginVersion ?? "unknown"}, re-downloading`,
+      );
+    }
+  } else {
+    log(`Release binary v${binaryVersion ?? "unknown"}`);
+  }
+}
+
+if (needsDownload) {
+  downloadBinary();
+}
+
+// Execute the aide binary, replacing this process
+log(`Executing: ${BINARY} ${process.argv.slice(2).join(" ")}`);
+
+const result = spawnSync(BINARY, process.argv.slice(2), {
+  stdio: "inherit",
+  env: process.env,
+});
+
+// Forward the exit code
+process.exit(result.status ?? 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmylchreest/aide-plugin",
-  "version": "0.0.54",
+  "version": "0.0.55",
   "description": "aide plugin for OpenCode — multi-agent orchestration, memory, skills, and persistence",
   "type": "module",
   "main": "./src/opencode/index.ts",
@@ -20,7 +20,7 @@
   ],
   "bin": {
     "aide-plugin": "./src/cli/index.ts",
-    "aide-wrapper": "./bin/aide-wrapper.sh"
+    "aide-wrapper": "./bin/aide-wrapper.ts"
   },
   "scripts": {
     "prebuild": "bun run copy-src",
@@ -48,5 +48,8 @@
   "engines": {
     "bun": ">=1.0.0"
   },
-  "dependencies": {}
+  "dependencies": {
+    "cross-spawn": "^7.0.6",
+    "which": "^6.0.1"
+  }
 }

package/src/cli/mcp.ts

@@ -1,5 +1,5 @@
 /**
- * MCP subcommand — delegates to aide-wrapper.sh to start the MCP server.
+ * MCP subcommand — delegates to aide-wrapper.ts to start the MCP server.
  *
  * This is the entry point used by OpenCode's MCP config:
  *   "command": ["bunx", "-y", "@jmylchreest/aide-plugin", "mcp"]
@@ -7,27 +7,27 @@
  * The wrapper handles binary discovery/download, then exec's `aide mcp`.
  */
 
-import { execFileSync } from "child_process";
+import spawn from "cross-spawn";
 import { existsSync } from "fs";
 import { dirname, join, resolve } from "path";
 import { fileURLToPath } from "url";
 
 /**
- * Find the aide-wrapper.sh script relative to this CLI module.
+ * Find the aide-wrapper.ts script relative to this CLI module.
  *
  * Resolution: this file lives at <plugin-root>/src/cli/mcp.ts,
- * so the wrapper is at <plugin-root>/bin/aide-wrapper.sh.
+ * so the wrapper is at <plugin-root>/bin/aide-wrapper.ts.
  */
 function findWrapper(): string {
   // __dirname equivalent for ESM
   const thisDir = dirname(fileURLToPath(import.meta.url));
   // src/cli -> src -> plugin-root
   const pluginRoot = resolve(thisDir, "..", "..");
-  const wrapper = join(pluginRoot, "bin", "aide-wrapper.sh");
+  const wrapper = join(pluginRoot, "bin", "aide-wrapper.ts");
 
   if (!existsSync(wrapper)) {
     throw new Error(
-      `aide-wrapper.sh not found at ${wrapper}\n` +
+      `aide-wrapper.ts not found at ${wrapper}\n` +
         `Expected plugin root: ${pluginRoot}\n` +
         `Ensure the package is installed correctly.`,
     );
@@ -37,27 +37,22 @@ function findWrapper(): string {
 }
 
 /**
- * Start the MCP server by exec'ing aide-wrapper.sh with "mcp" + any extra args.
+ * Start the MCP server by exec'ing aide-wrapper.ts with "mcp" + any extra args.
  * This replaces the current process so stdio is inherited directly.
  */
 export async function mcp(extraArgs: string[]): Promise<void> {
   const wrapper = findWrapper();
-  const args = ["mcp", ...extraArgs];
+  const args = [wrapper, "mcp", ...extraArgs];
 
-  // Use execFileSync with stdio inherit so the MCP JSON-RPC protocol
+  // Use bun (via cross-spawn for Windows .cmd resolution) to run the
+  // TypeScript wrapper. stdio is inherited so the MCP JSON-RPC protocol
   // flows directly between OpenCode and the aide binary.
-  // The wrapper will exec() into the aide binary, replacing itself.
-  try {
-    execFileSync(wrapper, args, {
-      stdio: "inherit",
-      env: process.env,
-    });
-  } catch (err: unknown) {
-    // execFileSync throws on non-zero exit. If the process was killed
-    // by a signal (e.g. OpenCode shutting down), exit cleanly.
-    if (err && typeof err === "object" && "status" in err) {
-      process.exit((err as { status: number }).status ?? 1);
-    }
-    throw err;
+  const result = spawn.sync("bun", args, {
+    stdio: "inherit",
+    env: process.env,
+  });
+
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
   }
 }

package/src/core/aide-client.ts

@@ -10,11 +10,14 @@
 
 import { execFileSync } from "child_process";
 import { existsSync, realpathSync } from "fs";
-import { join } from "path";
+import { dirname, join } from "path";
+import which from "which";
 import type { FindBinaryOptions } from "./types.js";
 import { debug } from "../lib/logger.js";
 
 const SOURCE = "aide-client";
+const IS_WINDOWS = process.platform === "win32";
+const BINARY_NAME = IS_WINDOWS ? "aide.exe" : "aide";
 
 /**
  * Find the aide binary — platform-agnostic implementation.
@@ -40,44 +43,51 @@ export function findAideBinary(opts: FindBinaryOptions = {}): string | null {
 
   // 1. Plugin root bin/
   if (pluginRoot) {
-    const pluginBinary = join(pluginRoot, "bin", "aide");
+    const pluginBinary = join(pluginRoot, "bin", BINARY_NAME);
     if (existsSync(pluginBinary)) {
+      ensureBinInPath(dirname(pluginBinary));
       return pluginBinary;
     }
   }
 
   // 2. Project-local .aide/bin/
   if (cwd) {
-    const projectBinary = join(cwd, ".aide", "bin", "aide");
+    const projectBinary = join(cwd, ".aide", "bin", BINARY_NAME);
     if (existsSync(projectBinary)) {
+      ensureBinInPath(dirname(projectBinary));
       return projectBinary;
     }
   }
 
   // 3. Additional paths
   for (const searchPath of additionalPaths) {
-    const binary = join(searchPath, "aide");
+    const binary = join(searchPath, BINARY_NAME);
     if (existsSync(binary)) {
+      ensureBinInPath(dirname(binary));
       return binary;
     }
   }
 
-  // 4. PATH fallback
-  try {
-    const result = execFileSync("which", ["aide"], {
-      stdio: "pipe",
-      timeout: 2000,
-    })
-      .toString()
-      .trim();
-    if (result) return result;
-  } catch (err) {
-    debug(SOURCE, `aide not found in PATH: ${err}`);
-  }
+  // 4. PATH fallback (already on PATH, no injection needed)
+  const fromPath = which.sync("aide", { nothrow: true });
+  if (fromPath) return fromPath;
 
+  debug(SOURCE, `aide binary not found (checked pluginRoot=${pluginRoot || "none"}, cwd=${cwd || "none"}, PATH)`);
   return null;
 }
 
+/**
+ * Ensure a directory is on PATH so child processes can find the aide binary.
+ * Only prepends if not already present.
+ */
+function ensureBinInPath(binDir: string): void {
+  const currentPath = process.env.PATH || "";
+  const sep = process.platform === "win32" ? ";" : ":";
+  if (!currentPath.split(sep).includes(binDir)) {
+    process.env.PATH = `${binDir}${sep}${currentPath}`;
+  }
+}
+
 /**
  * Run an aide command and return stdout, or null on failure.
  */

package/src/core/context-guard.ts

@@ -15,10 +15,11 @@
  */
 
 import { statSync, readFileSync, writeFileSync, existsSync } from "fs";
-import { resolve, isAbsolute, normalize } from "path";
+import { resolve, isAbsolute, normalize, extname } from "path";
 import { tmpdir } from "os";
 import { join } from "path";
 import { debug } from "../lib/logger.js";
+import { getPreviousRead, checkFileReadFreshness } from "./read-tracking.js";
 
 const SOURCE = "context-guard";
 
@@ -212,3 +213,102 @@ export function checkContextGuard(
   debug(SOURCE, `Advisory for ${filePath}: ${estLines} lines, ${sizeKB}KB`);
   return { shouldAdvise: true, advisory };
 }
+
+// ============================================================================
+// Smart Read Hint — suggest code index tools over redundant file re-reads
+// ============================================================================
+
+export interface SmartReadHintResult {
+  /** Whether to inject a hint message */
+  shouldHint: boolean;
+  /** Hint message to inject */
+  hint?: string;
+}
+
+/**
+ * Check whether a Read call should receive a smart-read hint suggesting
+ * the agent use code_outline/code_symbols/code_references instead.
+ *
+ * Triggers when:
+ *   1. The file was already read this session (tracked via state store)
+ *   2. The file hasn't changed since last indexing (mtime comparison)
+ *   3. The file is indexed with symbols (code_outline would be useful)
+ *
+ * Gated behind AIDE_CODE_WATCH=1 and requires a valid aide binary.
+ */
+export function checkSmartReadHint(
+  toolName: string,
+  toolInput: Record<string, unknown>,
+  cwd: string,
+  binary: string | null,
+): SmartReadHintResult {
+  // Only advise on Read tool calls (case-insensitive for OpenCode compat)
+  if (toolName.toLowerCase() !== "read") {
+    return { shouldHint: false };
+  }
+
+  // Require code watcher to be enabled
+  if (process.env.AIDE_CODE_WATCH !== "1") {
+    return { shouldHint: false };
+  }
+
+  // Require aide binary
+  if (!binary) {
+    return { shouldHint: false };
+  }
+
+  // Extract file path from tool input (check multiple variants)
+  // Precedence matches checkContextGuard and checkWriteGuard
+  const filePath =
+    (toolInput.filePath as string) ||
+    (toolInput.file_path as string) ||
+    (toolInput.path as string);
+
+  if (!filePath) {
+    return { shouldHint: false };
+  }
+
+  // Skip targeted reads (agent already using offset/limit)
+  const offset = toolInput.offset as number | undefined;
+  const limit = toolInput.limit as number | undefined;
+  if (offset !== undefined && offset > 1) {
+    return { shouldHint: false };
+  }
+  if (limit !== undefined && limit < 100) {
+    return { shouldHint: false };
+  }
+
+  // Skip non-source-code files
+  const ext = extname(filePath).toLowerCase();
+  if (SKIP_EXTENSIONS.has(ext)) {
+    return { shouldHint: false };
+  }
+
+  // Check if this file was already read this session
+  const previousRead = getPreviousRead(binary, cwd, filePath);
+  if (!previousRead) {
+    // First read — no hint needed
+    return { shouldHint: false };
+  }
+
+  // Check if the file is indexed and fresh
+  const readCheck = checkFileReadFreshness(binary, cwd, filePath);
+  if (!readCheck) {
+    return { shouldHint: false };
+  }
+
+  if (readCheck.indexed && readCheck.fresh && readCheck.outline_available) {
+    const tokens = readCheck.estimated_tokens;
+    const tokenInfo = tokens > 0 ? ` (~${tokens} tokens)` : "";
+    const hint =
+      `[aide:smart-read] This file was already read this session and hasn't changed${tokenInfo}. ` +
+      `Consider using code_outline (for structure, ~5-15% of full tokens), ` +
+      `code_symbols (for API surface), or code_references (for call sites) ` +
+      `to avoid re-reading the full file.`;
+
+    debug(SOURCE, `Smart read hint for: ${filePath} (${tokens} tokens)`);
+    return { shouldHint: true, hint };
+  }
+
+  return { shouldHint: false };
+}