@jmylchreest/aide-plugin 0.0.43 → 0.0.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmylchreest/aide-plugin",
-  "version": "0.0.43",
+  "version": "0.0.45",
   "description": "aide plugin for OpenCode — multi-agent orchestration, memory, skills, and persistence",
   "type": "module",
   "main": "./src/opencode/index.ts",

package/skills/survey/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: survey
+description: Explore codebase structure, entry points, tech stack, hotspots, and call graphs
+triggers:
+  - survey
+  - codebase structure
+  - what is this codebase
+  - tech stack
+  - entry points
+  - entrypoints
+  - what modules
+  - what packages
+  - code churn
+  - hotspots
+  - call graph
+  - who calls
+  - what calls
+  - orient me
+  - onboard
+  - codebase overview
+---
+
+# Codebase Survey
+
+**Recommended model tier:** balanced (sonnet) - this skill performs structured queries
+
+Understand the structure, technology, entry points, and change hotspots of a codebase.
+Survey describes WHAT the codebase IS — not code problems (use `findings` for that).
+
+## Available Tools
+
+### 1. Survey Stats (`mcp__plugin_aide_aide__survey_stats`)
+
+**Start here.** Get an overview of what has been surveyed: total entries, breakdown by analyzer and kind.
+
+```
+Is the codebase surveyed?
+→ Uses survey_stats
+→ Returns: counts by analyzer (topology, entrypoints, churn) and kind
+```
+
+### 2. Survey Run (`mcp__plugin_aide_aide__survey_run`)
+
+Run analyzers to populate survey data. Three analyzers available:
+
+- **topology** — Modules, packages, workspaces, build systems, tech stack detection
+- **entrypoints** — main() functions, HTTP handlers, gRPC services, CLI roots (cobra/urfave). Uses code index when available; falls back to file scanning
+- **churn** — Git history hotspots (files/dirs that change most often)
+
+```
+Survey this codebase
+→ Uses survey_run (no analyzer param = run all)
+→ Returns: entry counts per analyzer
+```
+
+### 3. Survey List (`mcp__plugin_aide_aide__survey_list`)
+
+Browse entries filtered by analyzer, kind, or file path. No search query needed.
+
+**Kinds:** module, entrypoint, dependency, tech_stack, churn, submodule, workspace, arch_pattern
+
+```
+What modules are in this codebase?
+→ Uses survey_list with kind=module
+→ Returns: all module entries
+
+What technologies does this use?
+→ Uses survey_list with kind=tech_stack
+→ Returns: detected frameworks, languages, build systems
+
+What files change most?
+→ Uses survey_list with kind=churn
+→ Returns: high-churn files ranked by commit count
+```
+
+### 4. Survey Search (`mcp__plugin_aide_aide__survey_search`)
+
+Full-text search across entry names, titles, and details. Use when looking for specific modules or technologies.
+
+```
+Find anything related to "auth"
+→ Uses survey_search with query="auth"
+→ Returns: modules, entrypoints, churn entries matching "auth"
+```
+
+### 5. Call Graph (`mcp__plugin_aide_aide__survey_graph`)
+
+Build a call graph for a symbol showing callers, callees, or both. BFS traversal over the code index.
+
+```
+Who calls BuildCallGraph?
+→ Uses survey_graph with symbol="BuildCallGraph" direction="callers"
+→ Returns: graph of calling symbols with file:line locations
+
+What does handleSurveyRun call?
+→ Uses survey_graph with symbol="handleSurveyRun" direction="callees"
+→ Returns: graph of called symbols
+
+Show call neighborhood of RunTopology
+→ Uses survey_graph with symbol="RunTopology" direction="both"
+→ Returns: both callers and callees
+```
+
+**Parameters:**
+
+- `symbol` (required): Function/method name
+- `direction`: "both" (default), "callers", "callees"
+- `max_depth`: BFS hops (default 2)
+- `max_nodes`: Max nodes (default 50)
+
+**Requires:** Code index must be populated (`aide code index`).
+
+## Workflow
+
+### Orienting in an unfamiliar codebase
+
+1. **Check survey status:**
+   - Use `survey_stats` to see if data exists
+   - If empty, run `survey_run` to populate
+
+2. **Understand the structure:**
+   - `survey_list kind=module` — What are the major modules?
+   - `survey_list kind=tech_stack` — What technologies are used?
+   - `survey_list kind=workspace` — Is this a monorepo?
+
+3. **Find entry points:**
+   - `survey_list kind=entrypoint` — Where does execution start?
+   - Identifies main() functions, HTTP handlers, CLI roots
+
+4. **Identify hotspots:**
+   - `survey_list kind=churn` — What files change most? (complexity/bug magnets)
+
+5. **Trace call relationships:**
+   - `survey_graph symbol="handleRequest"` — Map the call neighborhood
+   - Use `direction=callers` to find who invokes a function
+   - Use `direction=callees` to understand what a function depends on
+
+### Answering specific questions
+
+| Question                      | Tool            | Parameters                  |
+| ----------------------------- | --------------- | --------------------------- |
+| "What is this codebase?"      | `survey_list`   | kind=module                 |
+| "What tech stack?"            | `survey_list`   | kind=tech_stack             |
+| "Where are the entry points?" | `survey_list`   | kind=entrypoint             |
+| "What changes most?"          | `survey_list`   | kind=churn                  |
+| "Is there an auth module?"    | `survey_search` | query="auth"                |
+| "Who calls this function?"    | `survey_graph`  | symbol=X, direction=callers |
+| "What does this call?"        | `survey_graph`  | symbol=X, direction=callees |
+
+## Survey vs Findings vs Code Search
+
+| Tool            | Purpose              | Example                                  |
+| --------------- | -------------------- | ---------------------------------------- |
+| **Survey**      | WHAT the codebase IS | Modules, tech stack, entry points, churn |
+| **Findings**    | Code PROBLEMS        | Complexity, security issues, duplication |
+| **Code Search** | Symbol DEFINITIONS   | Find function signatures, call sites     |
+
+Survey gives you the big picture. Code search gives you specific symbols. Findings gives you problems to fix.
+
+## Prerequisites
+
+- **Survey data:** Run `aide survey run` or use `survey_run` tool
+- **Code index (for entrypoints + graph):** Run `aide code index`
+- **Git history (for churn):** Must be a git repository (uses go-git, no git binary needed)
+
+**Binary location:** The aide binary is at `.aide/bin/aide`. If it's on your `$PATH`, you can use `aide` directly.
+
+## Notes
+
+- Survey results are cached in BoltDB — re-run analyzers to refresh after significant changes
+- Topology analyzer inspects the filesystem (build files, directory structure)
+- Entrypoints analyzer uses the code index when available; falls back to file scanning
+- Churn analyzer uses go-git to read git history directly (no git binary required)
+- Call graph is computed on demand from the code index (not stored)

package/src/core/comment-checker.ts

@@ -126,6 +126,48 @@ function isObviousComment(line: string): boolean {
   return OBVIOUS_PATTERNS.some((p) => p.test(line));
 }
 
+/**
+ * Track /* ... * / block comment state.
+ * Returns [shouldSkip, newInBlockState].
+ */
+function isInBlockComment(
+  trimmed: string,
+  inBlock: boolean,
+): [boolean, boolean] {
+  if (trimmed.startsWith("/*")) {
+    // Single-line block comments: /* ... */
+    const closed = trimmed.includes("*/");
+    return [true, !closed];
+  }
+  if (inBlock) {
+    const closed = trimmed.includes("*/");
+    return [true, !closed];
+  }
+  return [false, false];
+}
+
+/**
+ * Track Python/Ruby docstring state (triple quotes).
+ * Returns [shouldSkip, newInDocstringState].
+ */
+function isInDocstring(
+  trimmed: string,
+  ext: string,
+  inDocstring: boolean,
+): [boolean, boolean] {
+  if (ext !== ".py" && ext !== ".rb") {
+    return [false, inDocstring];
+  }
+  const tripleQuoteCount = (trimmed.match(/"""|'''/g) || []).length;
+  if (tripleQuoteCount === 1) {
+    return [true, !inDocstring];
+  }
+  if (inDocstring) {
+    return [true, inDocstring];
+  }
+  return [false, inDocstring];
+}
+
 /**
  * Extract comment lines from code content.
  * Returns only single-line comments (// or #), not block comments or docstrings.
@@ -137,39 +179,23 @@ function extractCommentLines(
   const lines = content.split("\n");
   const comments: { line: string; lineNumber: number }[] = [];
   const usesHash = HASH_COMMENT_EXTENSIONS.has(ext);
-  let inBlockComment = false;
-  let inDocstring = false;
+  let inBlock = false;
+  let inDoc = false;
 
   for (let i = 0; i < lines.length; i++) {
     const trimmed = lines[i].trim();
 
-    // Track block comments (/* ... */)
-    if (!inDocstring) {
-      if (trimmed.startsWith("/*")) {
-        inBlockComment = true;
-        // Single-line block comments
-        if (trimmed.includes("*/")) {
-          inBlockComment = false;
-        }
-        continue;
-      }
-      if (inBlockComment) {
-        if (trimmed.includes("*/")) {
-          inBlockComment = false;
-        }
-        continue;
-      }
+    // Track block comments (/* ... */), but not inside docstrings
+    if (!inDoc) {
+      const [skipBlock, newBlock] = isInBlockComment(trimmed, inBlock);
+      inBlock = newBlock;
+      if (skipBlock) continue;
     }
 
     // Track Python/Ruby docstrings
-    if (ext === ".py" || ext === ".rb") {
-      const tripleQuoteCount = (trimmed.match(/"""|'''/g) || []).length;
-      if (tripleQuoteCount === 1) {
-        inDocstring = !inDocstring;
-        continue;
-      }
-      if (inDocstring) continue;
-    }
+    const [skipDoc, newDoc] = isInDocstring(trimmed, ext, inDoc);
+    inDoc = newDoc;
+    if (skipDoc) continue;
 
     // Single-line comments
     if (trimmed.startsWith("//")) {

package/src/lib/aide-downloader.ts

@@ -351,7 +351,7 @@ export async function ensureAideBinary(cwd?: string): Promise<EnsureResult> {
 
   // Step 1: Check for existing binary
   let binaryPath = findAideBinary(cwd);
-  let binaryVersion = binaryPath ? getBinaryVersion(binaryPath) : null;
+  const binaryVersion = binaryPath ? getBinaryVersion(binaryPath) : null;
 
   // Step 2: Check version match
   // Skip download if the binary is a dev build with base version >= plugin version
@@ -407,7 +407,6 @@ export async function ensureAideBinary(cwd?: string): Promise<EnsureResult> {
 
     if (result.success && result.path) {
       binaryPath = result.path;
-      binaryVersion = getBinaryVersion(result.path);
       downloaded = true;
     } else {
       // Download failed - return error with manual instructions

package/src/opencode/index.ts

@@ -36,9 +36,9 @@
  * ```
  */
 
-import { dirname, join, resolve } from "path";
+import { basename, dirname, join, resolve } from "path";
 import { fileURLToPath } from "url";
-import { existsSync, statSync } from "fs";
+import { existsSync, readFileSync, statSync } from "fs";
 import { createHooks } from "./hooks.js";
 import type { Plugin, PluginInput, Hooks } from "./types.js";
 
@@ -62,8 +62,16 @@ if (!process.env.AIDE_PLUGIN_ROOT) {
  *   ctx.project.worktree — `dirname(git rev-parse --git-common-dir)` (main repo root)
  *
  * Priority:
- *   1. ctx.worktree — the git sandbox root (correct for both normal repos and worktrees)
- *   2. ctx.directory — where OpenCode was invoked (fallback for non-git)
+ *   1. ctx.project.worktree — the main repo root (shared across all worktrees)
+ *   2. ctx.worktree — the git sandbox root (fallback if project.worktree missing)
+ *   3. ctx.directory — where OpenCode was invoked (fallback for non-git)
+ *
+ * IMPORTANT: We use ctx.project.worktree (git common dir parent) rather than
+ * ctx.worktree (show-toplevel) so that all git worktrees resolve to the SAME
+ * main repository root. This matches the Go binary's findProjectRoot() which
+ * follows .git worktree pointers to the main repo. Without this, each worktree
+ * would create its own .aide/ directory while the Go binary opens the database
+ * in the main repo's .aide/, causing BoltDB/SQLite lock contention.
  *
  * Both ctx.worktree and ctx.directory are "/" for non-git projects, so we
  * detect that case and skip initialization.
@@ -72,18 +80,23 @@ function resolveProjectRoot(ctx: PluginInput): {
   root: string;
   hasProjectRoot: boolean;
 } {
-  // ctx.worktree is the git working tree root (from `git rev-parse --show-toplevel`).
-  // For non-git projects, OpenCode sets this to "/".
-  const worktree = ctx.worktree;
   const directory = ctx.directory;
 
-  // OpenCode sets worktree to "/" for non-git projects — treat as no project.
-  // Also guard against empty strings.
+  // Prefer ctx.project.worktree — this is dirname(git rev-parse --git-common-dir),
+  // i.e. the main repo root that is shared across all worktrees.
+  // This matches the Go binary's resolveWorktreeRoot() behavior.
+  const projectWorktree = ctx.project?.worktree;
+  if (projectWorktree && projectWorktree !== "/") {
+    return { root: resolve(projectWorktree), hasProjectRoot: true };
+  }
+
+  // Fallback: ctx.worktree is git rev-parse --show-toplevel (per-worktree root).
+  // For normal (non-worktree) repos, this equals the main repo root anyway.
+  // For non-git projects, OpenCode sets this to "/".
+  const worktree = ctx.worktree;
   const isNonGitWorktree = !worktree || worktree === "/";
 
   if (!isNonGitWorktree) {
-    // The worktree is a valid git root — use it directly.
-    // No need to walk up the filesystem; OpenCode already resolved it.
     return { root: resolve(worktree), hasProjectRoot: true };
   }
 
@@ -110,6 +123,10 @@ function resolveProjectRoot(ctx: PluginInput): {
 /**
  * Walk up from `startDir` looking for .aide/ or .git/ directories.
  * Returns the project root path, or null if none found.
+ *
+ * For git worktrees, .git is a file containing "gitdir: <path>".
+ * We follow it to the main repo root, matching the Go binary's
+ * resolveWorktreeRoot() behavior.
  */
 function walkUpForProjectRoot(startDir: string): string | null {
   let dir = resolve(startDir);
@@ -121,8 +138,16 @@ function walkUpForProjectRoot(startDir: string): string | null {
     if (existsSync(gitPath)) {
       try {
         const stat = statSync(gitPath);
-        // .git can be a directory (normal repo) or a file (worktree pointer)
-        if (stat.isDirectory() || stat.isFile()) {
+        if (stat.isDirectory()) {
+          // Normal git repo
+          return dir;
+        }
+        if (stat.isFile()) {
+          // Worktree: .git is a file containing "gitdir: <path>"
+          // Follow it to the main repo root.
+          const mainRoot = resolveWorktreeGitFile(gitPath);
+          if (mainRoot) return mainRoot;
+          // Fallback to current dir if resolution fails
           return dir;
         }
       } catch {
@@ -137,6 +162,42 @@ function walkUpForProjectRoot(startDir: string): string | null {
   }
 }
 
+/**
+ * Read a .git worktree file and resolve to the main repository root.
+ * Mirrors the Go binary's resolveWorktreeRoot() in main.go.
+ *
+ * The file contains "gitdir: /path/to/repo/.git/worktrees/<name>".
+ * We walk up from that gitdir path to find the .git directory,
+ * then return its parent.
+ */
+function resolveWorktreeGitFile(gitFilePath: string): string | null {
+  try {
+    const content = readFileSync(gitFilePath, "utf-8").trim();
+    if (!content.startsWith("gitdir:")) return null;
+
+    let gitdir = content.slice("gitdir:".length).trim();
+    // Make absolute if relative
+    if (!gitdir.startsWith("/")) {
+      gitdir = resolve(dirname(gitFilePath), gitdir);
+    }
+
+    // Walk up from .git/worktrees/<name> to find the .git directory,
+    // then return its parent as the repo root.
+    let candidate = gitdir;
+    for (;;) {
+      const parent = dirname(candidate);
+      if (parent === candidate) break;
+      if (basename(candidate) === ".git") {
+        return parent;
+      }
+      candidate = parent;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 export const AidePlugin: Plugin = async (ctx: PluginInput): Promise<Hooks> => {
   // Log raw plugin input BEFORE any resolution for diagnostics.
   // This is the key to understanding what OpenCode actually passes.