opencode-repos 0.2.0 → 0.3.1

package/AGENTS.md

@@ -0,0 +1,180 @@
+# AGENTS.md - opencode-repos
+
+Guidelines for AI agents working in this repository.
+
+## Build & Development Commands
+
+```bash
+bun install              # Install dependencies
+bunx tsc --noEmit        # Type checking
+bun test                 # Run all tests
+bun test src/__tests__/git.test.ts           # Run single file
+bun test --test-name-pattern "parseRepoSpec" # Run matching tests
+bun test --watch         # Watch mode
+```
+
+## Project Structure
+
+```
+opencode-repos/
+├── index.ts                  # Main plugin - tool definitions
+├── src/
+│   ├── manifest.ts           # Manifest CRUD + file locking
+│   ├── git.ts                # Git operations (clone, update, parse)
+│   ├── scanner.ts            # Local filesystem repo scanner
+│   ├── agents/repo-explorer.ts
+│   └── __tests__/            # Test files (*.test.ts)
+├── package.json
+└── tsconfig.json
+```
+
+## Code Style
+
+### Runtime: Bun (NOT Node.js)
+
+This project uses Bun exclusively. Do not use Node.js, npm, pnpm, or yarn.
+
+```typescript
+import { $ } from "bun"
+await $`git clone ${url} ${dest}`.quiet()  // Shell commands
+
+const file = Bun.file(path)                // File operations
+await Bun.write(path, content)
+await Bun.sleep(100)                       // Sleep
+```
+
+### Imports
+
+Order: types → external → internal → relative. Use `node:` prefix for built-ins.
+
+```typescript
+import type { Plugin } from "@opencode-ai/plugin"
+import { tool } from "@opencode-ai/plugin"
+import { $ } from "bun"
+import { homedir } from "node:os"
+import { parseRepoSpec } from "./src/git"
+```
+
+### TypeScript
+
+- Strict mode enabled
+- Never use `any`, `@ts-ignore`, or `@ts-expect-error`
+- Export interfaces for public types
+- Use type guards: `(r): r is LocalRepoInfo => r !== null`
+
+### Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Functions/Variables | camelCase | `parseRepoSpec`, `repoPath` |
+| Constants | SCREAMING_SNAKE | `CACHE_DIR`, `LOCK_STALE_MS` |
+| Interfaces/Types | PascalCase | `RepoEntry`, `CloneOptions` |
+| Files | kebab-case | `repo-explorer.ts` |
+
+### Error Handling
+
+```typescript
+// Type-narrow errors
+try {
+  await cloneRepo(url, destPath, { branch })
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error)
+  throw new Error(`Failed to clone ${repoKey}: ${message}`)
+}
+
+// Cleanup on failure
+try {
+  await $`git clone ...`.quiet()
+} catch (error) {
+  try { await rm(destPath, { recursive: true, force: true }) } catch {}
+  throw error
+}
+
+// Silent catch for optional cleanup
+await unlink(LOCK_PATH).catch(() => {})
+```
+
+### Async Patterns
+
+- Use Promise.all for parallel operations
+- Use `.quiet()` on shell commands
+
+```typescript
+const [remote, branch] = await Promise.all([
+  $`git -C ${path} remote get-url origin`.text(),
+  $`git -C ${path} branch --show-current`.text(),
+])
+```
+
+### Testing
+
+```typescript
+import { test, expect, describe } from "bun:test"
+
+describe("parseRepoSpec", () => {
+  test("parses owner/repo without branch", () => {
+    expect(parseRepoSpec("vercel/next.js")).toEqual({
+      owner: "vercel", repo: "next.js", branch: null
+    })
+  })
+
+  test("throws on invalid input", () => {
+    expect(() => parseRepoSpec("invalid")).toThrow("Invalid repo spec")
+  })
+})
+```
+
+### Tool Definitions
+
+```typescript
+repo_clone: tool({
+  description: "Brief description with example usage",
+  args: {
+    repo: tool.schema.string().describe("Format: 'owner/repo@branch'"),
+    force: tool.schema.boolean().optional().default(false).describe("..."),
+  },
+  async execute(args) {
+    return `## Markdown formatted response`
+  },
+})
+```
+
+### Formatting
+
+- Only add comments for complex logic
+- No emojis in logs or comments
+- Use ISO 8601: `new Date().toISOString()`
+
+### File Locking
+
+Use `withManifestLock` for any manifest mutations:
+
+```typescript
+await withManifestLock(async () => {
+  const manifest = await loadManifest()
+  manifest.repos[key] = entry
+  await saveManifest(manifest)
+})
+```
+
+## Key Patterns
+
+### Repo Spec Parsing
+
+Format: `owner/repo` or `owner/repo@branch`
+
+```typescript
+const spec = parseRepoSpec("vercel/next.js@canary")
+// { owner: "vercel", repo: "next.js", branch: "canary" }
+```
+
+### Tool Return Format
+
+Tools return markdown-formatted strings:
+
+```typescript
+return `## Repository Cloned
+
+**Repository**: ${args.repo}
+**Path**: ${result.path}`
+```

package/README.md

@@ -1,6 +1,6 @@
 # opencode-repos
 
-Repository cache, registry, and cross-codebase intelligence for OpenCode agents.
+Repository cache, registry, and cross-codebase intelligence for opencode agents.
 
 ## Features
 
@@ -55,11 +55,17 @@ repo_explore({
   repo: "vercel/next.js", 
   question: "How does the App Router work?" 
 })
+
+// Resolve a repo automatically and explore it
+repo_query({
+  query: "react",
+  question: "How does the reconciliation algorithm work?"
+})
 ```
 
 ## Configuration
 
-Create `~/.config/opencode/opencode-repos.json` to configure local repository scanning:
+Create `~/.config/opencode/opencode-repos.json` to configure the plugin:
 
 ```json
 {
@@ -67,10 +73,53 @@ Create `~/.config/opencode/opencode-repos.json` to configure local repository sc
     "~/projects",
     "~/personal/projects",
     "~/code"
-  ]
+  ],
+  "includeProjectParent": true,
+  "cleanupMaxAgeDays": 30,
+  "cacheDir": "/tmp/opencode-repos",
+  "useHttps": false,
+  "autoSyncOnExplore": true,
+  "autoSyncIntervalHours": 24,
+  "defaultBranch": "main",
+  "debug": false,
+  "repoExplorerModel": "opencode/grok-code",
+  "debugLogPath": "~/.cache/opencode-repos/debug.log"
 }
 ```
 
+| Option | Default | Description |
+|--------|---------|-------------|
+| `localSearchPaths` | `[]` | Directories to scan for local git repositories |
+| `includeProjectParent` | `true` | Also search the parent of the current project directory |
+| `cleanupMaxAgeDays` | `30` | Auto-delete cached repos not accessed in this many days |
+| `cacheDir` | `/tmp/opencode-repos` | Where to store cloned repositories |
+| `useHttps` | `false` | Use HTTPS instead of SSH for cloning (useful behind firewalls) |
+| `autoSyncOnExplore` | `true` | Auto-fetch latest before exploring a repo |
+| `autoSyncIntervalHours` | `24` | Minimum hours between auto-fetch updates |
+| `defaultBranch` | `"main"` | Default branch when none specified (some repos use "master") |
+| `debug` | `false` | Include debug details in tool responses |
+| `repoExplorerModel` | `"opencode/grok-code"` | Model used by the repo-explorer subagent |
+| `debugLogPath` | `"~/.cache/opencode-repos/debug.log"` | File path for debug logs |
+
+Cleanup runs automatically on plugin load.
+
+To avoid repeated prompts when exploring external repos, update your OpenCode permissions (`~/.config/opencode/opencode.jsonc`) to allow external directories as needed.
+
+Example permission config:
+
+```json
+{
+  "permission": {
+    "external_directory": {
+      "*": "ask",
+      "/tmp/opencode-repos/*": "allow"
+    }
+}
+}
+```
+
+If you hit intermittent subagent session errors, enable debug logging and retry. The plugin includes a small retry/backoff when prompting the repo-explorer subagent.
+
 ## Tools
 
 ### repo_find
@@ -101,6 +150,56 @@ repo_find({ query: "react" })
 
 ---
 
+### repo_query
+
+Resolve a repository automatically and explore it with the repo-explorer agent. If multiple repos match, it asks you to disambiguate. Accepts explicit repo lists for multi-repo questions.
+
+**Arguments:**
+- `query` (string, optional): Repository name, owner/repo, or absolute local path. Examples: `"next.js"`, `"vercel/next.js"`, `"/Users/me/projects/app"`
+- `repos` (string[], optional): Explicit repositories to explore (`owner/repo` or `owner/repo@branch`)
+- `question` (string, required): What you want to understand about the codebase
+
+**Examples:**
+```typescript
+// Automatic resolution
+repo_query({
+  query: "react",
+  question: "How does reconciliation work?"
+})
+
+// Absolute local path
+repo_query({
+  query: "/Users/me/projects/firmware",
+  question: "Where is the BLE handshake implemented?"
+})
+
+// Explicit repo list
+repo_query({
+  repos: ["acme/firmware", "acme/app"],
+  question: "Where is the BLE handshake implemented?"
+})
+```
+
+**Returns:** Exploration output from one or more repositories
+
+---
+
+### repo_pick_dir
+
+Open a native folder picker and return the selected path. Call this immediately after the user asks for a local repo to avoid delayed popups if they step away.
+
+**Arguments:**
+- `prompt` (string, optional): Prompt text shown in the picker dialog
+
+**Examples:**
+```typescript
+repo_pick_dir({ prompt: "Select your firmware repo" })
+```
+
+**Returns:** Selected folder path
+
+---
+
 ### repo_clone
 
 Clone a repository to local cache or return path if already cached.
@@ -354,6 +453,7 @@ repo_read({ repo: "my-org/api-service", path: "src/routes/*.ts" })
 - **GitHub only**: Remote URL parsing only supports GitHub (SSH and HTTPS formats)
 - **Read-only for local repos**: The plugin never modifies local repositories (type: "local")
 - **No diff/blame**: Use git directly for advanced git operations
+- **Single branch per repo**: Each repo has one directory; switching branches replaces the working tree (no parallel branch access)
 
 ---