opencode-context 1.0.6 → 1.0.7

package/README.md

@@ -2,6 +2,38 @@
 
 Smart file finder for codebases with relevance scoring. Includes an OpenCode plugin.
 
+---
+
+## Quick Reference for AI Agents
+
+**Tool:** `find_files`  
+**Purpose:** Find relevant files before reading them  
+**When to use:** User asks to find, locate, search, or "where is X"
+
+### Arguments
+
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| query | string | **YES** | - | What to find (e.g., "auth", "database models") |
+| maxFiles | number | no | 5 | Number of results |
+| minScore | number | no | 15 | Relevance threshold (0-100) |
+| includeTests | boolean | no | false | Include *.test.*, *.spec.* |
+| includeConfigs | boolean | no | false | Include *.config.*, .rc files |
+| includeDocs | boolean | no | false | Include *.md, docs/ |
+
+### Examples
+
+```
+find_files query="authentication middleware"
+find_files query="database" maxFiles=10 includeTests=true
+find_files query="config" includeConfigs=true
+```
+
+**Scoring:** Filename (highest) > Path > Content > Imports/Exports  
+**Tip:** If no results, try `minScore=5` for broader search
+
+---
+
 ## Installation
 
 ### For Humans

package/dist/install.d.ts

@@ -1,3 +1,5 @@
 #!/usr/bin/env bun
-export {};
+declare function updateAgentsMd(): Promise<void>;
+declare function updateOpencodeConfig(): Promise<void>;
+export { updateAgentsMd, updateOpencodeConfig };
 //# sourceMappingURL=install.d.ts.map

package/dist/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":""}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":";AAuGA,iBAAe,cAAc,kBAyB5B;AAED,iBAAe,oBAAoB,kBA+BlC;AAwBD,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,CAAC"}

package/dist/install.js

@@ -4,7 +4,9 @@
 // src/install.ts
 import { promises as fs } from "fs";
 import { join, dirname } from "path";
-var CONFIG_PATH = join(process.env.HOME || "", ".config/opencode/opencode.json");
+import { homedir } from "os";
+var CONFIG_PATH = join(process.env.HOME || homedir(), ".config/opencode/opencode.json");
+var AGENTS_PATH = join(process.env.HOME || homedir(), ".config/opencode/AGENTS.md");
 async function ensureConfigDir() {
   const dir = dirname(CONFIG_PATH);
   try {
@@ -25,31 +27,136 @@ async function writeConfig(config) {
   await fs.writeFile(CONFIG_PATH, JSON.stringify(config, null, 2) + `
 `);
 }
-async function install() {
-  console.log(`Installing opencode-context plugin...
-`);
-  await ensureConfigDir();
+async function readAgentsMd() {
+  try {
+    return await fs.readFile(AGENTS_PATH, "utf-8");
+  } catch {
+    return "";
+  }
+}
+async function writeAgentsMd(content) {
+  await fs.writeFile(AGENTS_PATH, content);
+}
+var TOOL_DOCUMENTATION = `
+## find_files Tool (opencode-context plugin)
+
+**Purpose:** Semantic file search for locating relevant code files before reading them.
+
+**When to use:**
+- User asks to find, locate, or search for files
+- Before reading multiple files to understand a codebase
+- Looking for specific functionality (auth, database, config, etc.)
+- User mentions "where is X defined" or "find Y"
+
+**Arguments:**
+
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| query | string | YES | - | Search query describing what to find (e.g., "auth middleware", "user model") |
+| maxFiles | number | NO | 5 | Maximum number of files to return |
+| minScore | number | NO | 15 | Minimum relevance score (0-100). Lower = more results |
+| includeTests | boolean | NO | false | Include test files (*.test.*, *.spec.*, etc.) |
+| includeConfigs | boolean | NO | false | Include configuration files (*.config.*, .rc files) |
+| includeDocs | boolean | NO | false | Include documentation (*.md, README, docs/) |
+
+**Usage examples:**
+
+\`\`\`
+# Basic search
+find_files query="authentication"
+
+# More results with tests
+find_files query="database" maxFiles=10 includeTests=true
+
+# Find config files
+find_files query="webpack" includeConfigs=true
+
+# Low threshold for broader search
+find_files query="utils" minScore=5
+\`\`\`
+
+**Scoring algorithm:**
+- Filename matches (highest weight)
+- Directory path matches
+- Content matches (function names, class names)
+- Import/export statements
+- File type (tests ranked lower unless requested)
+
+**Best practices:**
+1. Call this BEFORE reading files when user asks to find something
+2. Use maxFiles=10+ when doing initial codebase exploration
+3. Set includeTests=true only when user specifically asks about tests
+4. If no results, try lowering minScore to 5 or using broader terms
+5. Results include relevance scores - files above 50 are highly relevant
+`;
+async function updateAgentsMd() {
+  const existingContent = await readAgentsMd();
+  const toolMarker = "## find_files Tool (opencode-context plugin)";
+  if (existingContent.includes(toolMarker)) {
+    const beforeTool = existingContent.split(toolMarker)[0];
+    const afterTool = existingContent.split(toolMarker)[1];
+    const nextHeading = afterTool.search(/\n## /);
+    const rest = nextHeading >= 0 ? afterTool.slice(nextHeading) : "";
+    const newContent = beforeTool + TOOL_DOCUMENTATION + `
+` + rest;
+    await writeAgentsMd(newContent);
+    console.log("\u2713 Updated AGENTS.md with find_files documentation");
+  } else {
+    const header = existingContent.includes("# Available Tools") ? existingContent : existingContent.trim() ? existingContent + `
+
+# Available Tools
+` : `# Available Tools
+`;
+    const newContent = header + `
+` + TOOL_DOCUMENTATION;
+    await writeAgentsMd(newContent);
+    console.log("\u2713 Created/updated AGENTS.md with find_files documentation");
+  }
+}
+async function updateOpencodeConfig() {
   const config = await readConfig();
   if (!config.plugin) {
     config.plugin = [];
   }
   const pluginName = "opencode-context@latest";
-  if (config.plugin.includes(pluginName)) {
-    console.log("\u2713 opencode-context already in plugins");
-  } else {
+  if (!config.plugin.includes(pluginName)) {
     config.plugin.push(pluginName);
     console.log("\u2713 Added opencode-context@latest to plugins");
+  } else {
+    console.log("\u2713 opencode-context already in plugins");
+  }
+  if (!config.instructions) {
+    config.instructions = [];
+  }
+  const agentsRef = "~/.config/opencode/AGENTS.md";
+  if (!config.instructions.includes(agentsRef)) {
+    config.instructions.push(agentsRef);
+    console.log("\u2713 Added AGENTS.md to instructions");
+  } else {
+    console.log("\u2713 AGENTS.md already in instructions");
   }
   await writeConfig(config);
+}
+async function install() {
+  console.log(`Installing opencode-context plugin...
+`);
+  await ensureConfigDir();
+  await updateOpencodeConfig();
+  await updateAgentsMd();
   console.log(`
 \u2713 Installation complete!`);
   console.log(`
 To use:`);
-  console.log("  1. Run opencode in your project");
-  console.log('  2. Ask: "Find files related to auth"');
-  console.log(`  3. The agent will use find_files tool
+  console.log("  1. Restart opencode if running");
+  console.log("  2. The AI agent will now see find_files in available tools");
+  console.log(`  3. Try: "Find files related to authentication"
 `);
 }
-if (__require.main == __require.module) {
+var isMainModule = process.argv[1]?.includes("install.js") || process.argv[1]?.includes("install.ts");
+if (isMainModule) {
   install().catch(console.error);
 }
+export {
+  updateOpencodeConfig,
+  updateAgentsMd
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-context",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "Smart file finder for codebases - semantic search with confidence scoring. Also available as an OpenCode plugin.",
   "type": "module",
   "main": "./dist/plugin.js",
@@ -14,13 +14,15 @@
   "files": [
     "dist/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "plugin.json"
   ],
   "scripts": {
     "build": "bun build ./src/index.ts --outfile ./dist/index.js --target node && bun build ./src/plugin.ts --outfile ./dist/plugin.js --target node && bun build ./src/install.ts --outfile ./dist/install.js --target node && echo '#!/usr/bin/env node' | cat - ./dist/index.js > temp && mv temp ./dist/index.js && chmod +x ./dist/index.js",
     "build:types": "tsc --emitDeclarationOnly",
     "dev": "bun run src/index.ts",
     "test": "bun test",
+    "postinstall": "node dist/install.js || echo 'Run: bunx opencode-context@latest install'",
     "prepublishOnly": "bun run build && bun run build:types"
   },
   "dependencies": {

package/plugin.json

@@ -0,0 +1,87 @@
+{
+  "name": "opencode-context",
+  "version": "1.0.6",
+  "description": "Smart file finder for codebases with semantic search and relevance scoring",
+  "main": "dist/plugin.js",
+  "tools": [
+    {
+      "name": "find_files",
+      "description": "Find relevant files in the codebase based on a semantic search query. Use this to locate files related to a task before reading them. Returns ranked results with relevance scores.",
+      "whenToUse": [
+        "User asks to find, locate, or search for files",
+        "Before reading multiple files to understand a codebase",
+        "Looking for specific functionality (auth, database, config, etc.)",
+        "User mentions 'where is X defined' or 'find Y'"
+      ],
+      "args": {
+        "query": {
+          "type": "string",
+          "required": true,
+          "description": "Search query describing what to find (e.g., 'auth middleware', 'user model')"
+        },
+        "maxFiles": {
+          "type": "number",
+          "required": false,
+          "default": 5,
+          "description": "Maximum number of files to return"
+        },
+        "minScore": {
+          "type": "number",
+          "required": false,
+          "default": 15,
+          "description": "Minimum relevance score (0-100). Lower = more results"
+        },
+        "includeTests": {
+          "type": "boolean",
+          "required": false,
+          "default": false,
+          "description": "Include test files (*.test.*, *.spec.*, etc.)"
+        },
+        "includeConfigs": {
+          "type": "boolean",
+          "required": false,
+          "default": false,
+          "description": "Include configuration files (*.config.*, .rc files)"
+        },
+        "includeDocs": {
+          "type": "boolean",
+          "required": false,
+          "default": false,
+          "description": "Include documentation (*.md, README, docs/)"
+        }
+      },
+      "examples": [
+        {
+          "description": "Basic search",
+          "usage": "find_files query='authentication'"
+        },
+        {
+          "description": "More results with tests",
+          "usage": "find_files query='database' maxFiles=10 includeTests=true"
+        },
+        {
+          "description": "Find config files",
+          "usage": "find_files query='webpack' includeConfigs=true"
+        },
+        {
+          "description": "Low threshold for broader search",
+          "usage": "find_files query='utils' minScore=5"
+        }
+      ],
+      "bestPractices": [
+        "Call this BEFORE reading files when user asks to find something",
+        "Use maxFiles=10+ when doing initial codebase exploration",
+        "Set includeTests=true only when user specifically asks about tests",
+        "If no results, try lowering minScore to 5 or using broader terms",
+        "Results include relevance scores - files above 50 are highly relevant"
+      ],
+      "scoringFactors": [
+        "Filename matches (highest weight)",
+        "Directory path matches",
+        "Content matches (function names, class names)",
+        "Import/export statements",
+        "File type (tests ranked lower unless requested)"
+      ]
+    }
+  ]
+}