opencode-readseek 0.5.19

package/README.md

@@ -0,0 +1,37 @@
+# opencode-readseek
+
+`opencode-readseek` exposes ReadSeek's hash-anchored reads and structural code
+navigation as OpenCode tools. It intentionally does not replace OpenCode's
+built-in `read`, `edit`, or `write` tools.
+
+## Installation
+
+Add the plugin to `opencode.json`:
+
+```json
+{
+  "plugin": ["opencode-readseek"]
+}
+```
+
+OpenCode installs the package and its supported-platform `@jarkkojs/readseek`
+binary dependency with Bun at startup.
+
+## Tools
+
+- `readseek_read`: read text with `LINE:HASH` anchors.
+- `readseek_map`: generate a structural symbol map.
+- `readseek_search`: AST-pattern search.
+- `readseek_def`, `readseek_refs`, `readseek_hover`: symbol navigation.
+- `readseek_rename`: generate a rename plan without writing files.
+- `readseek_check`: parse diagnostics.
+
+The plugin discards remembered anchors after OpenCode reports `file.edited`,
+records anchors from successful ReadSeek tool results, refuses any attempt to
+apply a rename directly, and adds current anchors plus a pending rename plan to
+the OpenCode compaction context.
+
+## Licensing
+
+This package is Apache-2.0. `@jarkkojs/readseek` is licensed separately as
+Apache-2.0 AND LGPL-2.1-or-later.

package/index.ts

@@ -0,0 +1,267 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) Jarkko Sakkinen 2026
+
+import { createRequire } from "node:module";
+import path from "node:path";
+
+import { tool, type Plugin } from "@opencode-ai/plugin";
+
+const require = createRequire(import.meta.url);
+const readseekScript = require.resolve("@jarkkojs/readseek/bin/readseek.js");
+
+class SessionAnchors {
+  #pathsBySession = new Map<string, Set<string>>();
+  #renamePlans = new Map<string, string>();
+
+  mark(sessionID: string, filePath: string): void {
+    let paths = this.#pathsBySession.get(sessionID);
+    if (!paths) {
+      paths = new Set<string>();
+      this.#pathsBySession.set(sessionID, paths);
+    }
+    paths.add(filePath);
+  }
+
+  forget(filePath: string): void {
+    for (const paths of this.#pathsBySession.values()) paths.delete(filePath);
+  }
+
+  planRename(sessionID: string, output: unknown): void {
+    if (!output || typeof output !== "object") return;
+    const { old_name: oldName, new_name: newName } = output as Record<string, unknown>;
+    if (typeof oldName === "string" && typeof newName === "string") {
+      this.#renamePlans.set(sessionID, `${oldName} -> ${newName}`);
+    }
+  }
+
+  render(sessionID: string): string | undefined {
+    const paths = this.#pathsBySession.get(sessionID);
+    const sections: string[] = [];
+    if (paths?.size) {
+      sections.push(`## ReadSeek Anchors\nThe following files have fresh LINE:HASH anchors:\n${[...paths]
+      .sort()
+      .map((filePath) => `- ${filePath}`)
+      .join("\n")}`);
+    }
+    const renamePlan = this.#renamePlans.get(sessionID);
+    if (renamePlan) sections.push(`## Pending ReadSeek Rename Plan\n- ${renamePlan}`);
+    return sections.length === 0 ? undefined : sections.join("\n\n");
+  }
+}
+
+function resolvePath(directory: string, filePath: string): string {
+  return path.resolve(directory, filePath);
+}
+
+function optionalFlag(args: string[], enabled: boolean | undefined, flag: string): void {
+  if (enabled) args.push(flag);
+}
+
+async function runReadSeek(directory: string, args: string[]): Promise<unknown> {
+  const child = Bun.spawn([process.execPath, readseekScript, ...args], {
+    cwd: directory,
+    stderr: "pipe",
+    stdout: "pipe",
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ]);
+  if (exitCode !== 0) throw new Error(stderr.trim() || `readseek exited with status ${exitCode}`);
+
+  try {
+    return JSON.parse(stdout) as unknown;
+  } catch {
+    throw new Error(`readseek returned invalid JSON: ${stdout.trim()}`);
+  }
+}
+
+function render(value: unknown): string {
+  return JSON.stringify(value, null, 2);
+}
+
+function collectFiles(value: unknown, files: Set<string>): void {
+  if (Array.isArray(value)) {
+    for (const item of value) collectFiles(item, files);
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+
+  for (const [key, item] of Object.entries(value)) {
+    if (key === "file" && typeof item === "string") files.add(item);
+    else collectFiles(item, files);
+  }
+}
+
+function readseekTool(
+  description: string,
+  args: Record<string, any>,
+  execute: (args: any, directory: string) => Promise<unknown>,
+) {
+  return tool({
+    description,
+    args,
+    async execute(args, context) {
+      return render(await execute(args, context.directory));
+    },
+  });
+}
+
+/**
+ * Adds readseek's anchored reads and structural navigation without replacing
+ * OpenCode's built-in file tools.
+ */
+export const ReadSeekPlugin: Plugin = async () => {
+  const anchors = new SessionAnchors();
+  const withSearchFlags = (args: string[], input: { cached?: boolean; others?: boolean; ignored?: boolean }) => {
+    optionalFlag(args, input.cached, "--cached");
+    optionalFlag(args, input.others, "--others");
+    optionalFlag(args, input.ignored, "--ignored");
+  };
+
+  return {
+    tool: {
+      readseek_read: readseekTool(
+        "Read a text file with stable LINE:HASH anchors. Use those anchors when describing a later edit.",
+        {
+          path: tool.schema.string().describe("Path relative to the project directory"),
+          offset: tool.schema.number().int().positive().optional().describe("One-based starting line"),
+          limit: tool.schema.number().int().positive().optional().describe("Maximum number of lines"),
+        },
+        async (input, directory) => {
+          const filePath = resolvePath(directory, input.path as string);
+          const args = ["read", input.offset === undefined ? filePath : `${filePath}:${input.offset}`];
+          if (input.limit !== undefined) args.push("--end", String((input.offset as number) + (input.limit as number) - 1));
+          return runReadSeek(directory, args);
+        },
+      ),
+      readseek_map: readseekTool(
+        "Build a structural symbol map for a source file.",
+        { path: tool.schema.string().describe("Path relative to the project directory") },
+        async (input, directory) => runReadSeek(directory, ["map", resolvePath(directory, input.path as string)]),
+      ),
+      readseek_search: readseekTool(
+        "Search source code using an ast-grep structural pattern. Results include LINE:HASH anchors.",
+        {
+          pattern: tool.schema.string().describe("AST pattern"),
+          path: tool.schema.string().optional().describe("File or directory, defaulting to the project directory"),
+          language: tool.schema.string().optional().describe("ast-grep language"),
+          cached: tool.schema.boolean().optional(),
+          others: tool.schema.boolean().optional(),
+          ignored: tool.schema.boolean().optional(),
+        },
+        async (input, directory) => {
+          const target = resolvePath(directory, (input.path as string | undefined) ?? ".");
+          const args = ["search", target, input.pattern as string];
+          if (input.language) args.push("--language", input.language as string);
+          withSearchFlags(args, input);
+          const result = await runReadSeek(directory, args);
+          return result;
+        },
+      ),
+      readseek_def: readseekTool(
+        "Find structural definitions of a symbol. Results include LINE:HASH anchors.",
+        {
+          name: tool.schema.string().describe("Symbol name"),
+          path: tool.schema.string().optional().describe("File or directory, defaulting to the project directory"),
+          language: tool.schema.string().optional(),
+          cached: tool.schema.boolean().optional(),
+          others: tool.schema.boolean().optional(),
+          ignored: tool.schema.boolean().optional(),
+        },
+        async (input, directory) => {
+          const args = ["def", resolvePath(directory, (input.path as string | undefined) ?? "."), "--format", "plain", input.name as string];
+          if (input.language) args.push("--language", input.language as string);
+          withSearchFlags(args, input);
+          return runReadSeek(directory, args);
+        },
+      ),
+      readseek_refs: readseekTool(
+        "Find references to an identifier. Use scope with a cursor to identify a specific binding.",
+        {
+          name: tool.schema.string().describe("Identifier name"),
+          path: tool.schema.string().optional().describe("File or directory, defaulting to the project directory"),
+          language: tool.schema.string().optional(),
+          scope: tool.schema.boolean().optional(),
+          line: tool.schema.number().int().positive().optional(),
+          column: tool.schema.number().int().positive().optional(),
+          cached: tool.schema.boolean().optional(),
+          others: tool.schema.boolean().optional(),
+          ignored: tool.schema.boolean().optional(),
+        },
+        async (input, directory) => {
+          const args = ["refs", resolvePath(directory, (input.path as string | undefined) ?? "."), input.name as string];
+          optionalFlag(args, input.scope as boolean | undefined, "--scope");
+          if (input.line) args.push("--line", String(input.line));
+          if (input.column) args.push("--column", String(input.column));
+          if (input.language) args.push("--language", input.language as string);
+          withSearchFlags(args, input);
+          return runReadSeek(directory, args);
+        },
+      ),
+      readseek_hover: readseekTool(
+        "Identify the token and enclosing symbol at a source cursor.",
+        {
+          path: tool.schema.string().describe("Path relative to the project directory"),
+          line: tool.schema.number().int().positive().describe("One-based cursor line"),
+          column: tool.schema.number().int().positive().optional().describe("One-based cursor byte column"),
+          language: tool.schema.string().optional(),
+        },
+        async (input, directory) => {
+          const args = ["identify", `${resolvePath(directory, input.path as string)}:${input.line}`];
+          if (input.column) args.push("--column", String(input.column));
+          if (input.language) args.push("--language", input.language as string);
+          return runReadSeek(directory, args);
+        },
+      ),
+      readseek_rename: readseekTool(
+        "Plan a binding-aware rename. This tool never writes files; apply the returned plan through OpenCode's normal edit tools.",
+        {
+          path: tool.schema.string().describe("Path relative to the project directory"),
+          line: tool.schema.number().int().positive().describe("One-based cursor line of the binding"),
+          column: tool.schema.number().int().positive().optional().describe("One-based cursor byte column"),
+          to: tool.schema.string().min(1).describe("New binding name"),
+          workspace: tool.schema.boolean().optional().describe("Include project-wide occurrences"),
+        },
+        async (input, directory) => {
+          const args = ["rename", resolvePath(directory, input.path as string), "--line", String(input.line), "--to", input.to as string];
+          if (input.column) args.push("--column", String(input.column));
+          if (input.workspace) args.push("--workspace", directory);
+          return runReadSeek(directory, args);
+        },
+      ),
+      readseek_check: readseekTool(
+        "Check a source file for parser errors and missing syntax.",
+        { path: tool.schema.string().describe("Path relative to the project directory") },
+        async (input, directory) => runReadSeek(directory, ["check", resolvePath(directory, input.path as string)]),
+      ),
+    },
+    event: async ({ event }) => {
+      if (event.type !== "file.edited") return;
+      anchors.forget(path.resolve(event.properties.file));
+    },
+    "tool.execute.before": async (input, output) => {
+      if (input.tool === "readseek_rename" && output.args.apply === true) {
+        throw new Error("readseek_rename only creates plans; apply its edits with OpenCode's edit tools");
+      }
+    },
+    "tool.execute.after": async (input, output) => {
+      if (!input.tool.startsWith("readseek_")) return;
+      try {
+        const result = JSON.parse(output.output) as unknown;
+        if (input.tool === "readseek_rename") anchors.planRename(input.sessionID, result);
+
+        const files = new Set<string>();
+        collectFiles(result, files);
+        for (const filePath of files) anchors.mark(input.sessionID, path.resolve(filePath));
+      } catch {
+        // A failed tool result has no valid anchors to retain.
+      }
+    },
+    "experimental.session.compacting": async (input, output) => {
+      const context = anchors.render(input.sessionID);
+      if (context) output.context.push(context);
+    },
+  };
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "opencode-readseek",
+  "version": "0.5.19",
+  "description": "OpenCode plugin for readseek-backed structural code navigation",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "readseek",
+    "structural-search"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jarkkojs/readseek.git"
+  },
+  "license": "Apache-2.0",
+  "files": [
+    "index.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@jarkkojs/readseek": "^0.5.19",
+    "@opencode-ai/plugin": "^1.17.20"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "typescript": "^5.9.3"
+  }
+}