opencode-repos 0.1.0

package/package.json

@@ -0,0 +1,32 @@
+{
+	"name": "opencode-repos",
+	"version": "0.1.0",
+	"description": "Repository cache, registry, and cross-codebase intelligence for OpenCode agents",
+	"main": "index.ts",
+	"type": "module",
+	"keywords": [
+		"opencode",
+		"opencode-plugin",
+		"repos",
+		"repository",
+		"cache",
+		"codebase"
+	],
+	"author": "Liam Vinberg",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/liamjv1/opencode-repos"
+	},
+	"peerDependencies": {
+		"@opencode-ai/plugin": "*"
+	},
+	"dependencies": {
+		"glob": "^10.0.0"
+	},
+	"devDependencies": {
+		"@opencode-ai/plugin": "^1.1.25",
+		"@types/bun": "^1.2.0",
+		"typescript": "^5.0.0"
+	}
+}

package/src/__tests__/git.test.ts

@@ -0,0 +1,141 @@
+import { test, expect, describe, beforeAll, afterAll } from "bun:test"
+import { rm, mkdir } from "node:fs/promises"
+import { join } from "node:path"
+import { tmpdir } from "node:os"
+import {
+  parseRepoSpec,
+  buildGitUrl,
+  cloneRepo,
+  updateRepo,
+  getRepoInfo,
+} from "../git"
+
+describe("parseRepoSpec", () => {
+  test("parses owner/repo without branch", () => {
+    const result = parseRepoSpec("vercel/next.js")
+    expect(result).toEqual({
+      owner: "vercel",
+      repo: "next.js",
+      branch: null,
+    })
+  })
+
+  test("parses owner/repo@branch", () => {
+    const result = parseRepoSpec("vercel/next.js@canary")
+    expect(result).toEqual({
+      owner: "vercel",
+      repo: "next.js",
+      branch: "canary",
+    })
+  })
+
+  test("handles branch with special characters", () => {
+    const result = parseRepoSpec("owner/repo@feature/my-branch")
+    expect(result).toEqual({
+      owner: "owner",
+      repo: "repo",
+      branch: "feature/my-branch",
+    })
+  })
+
+  test("throws on missing slash", () => {
+    expect(() => parseRepoSpec("invalid")).toThrow(
+      'Invalid repo spec: must be in format "owner/repo"'
+    )
+  })
+
+  test("throws on empty owner", () => {
+    expect(() => parseRepoSpec("/repo")).toThrow(
+      "Invalid repo spec: owner and repo cannot be empty"
+    )
+  })
+
+  test("throws on empty repo", () => {
+    expect(() => parseRepoSpec("owner/")).toThrow(
+      "Invalid repo spec: owner and repo cannot be empty"
+    )
+  })
+
+  test("throws on empty branch after @", () => {
+    expect(() => parseRepoSpec("owner/repo@")).toThrow(
+      "Invalid repo spec: branch cannot be empty after @"
+    )
+  })
+
+  test("throws on repo with extra slash", () => {
+    expect(() => parseRepoSpec("owner/repo/extra")).toThrow(
+      'Invalid repo spec: repo name cannot contain "/"'
+    )
+  })
+})
+
+describe("buildGitUrl", () => {
+  test("builds SSH URL correctly", () => {
+    const url = buildGitUrl("vercel", "next.js")
+    expect(url).toBe("git@github.com:vercel/next.js.git")
+  })
+
+  test("handles various owner/repo names", () => {
+    expect(buildGitUrl("facebook", "react")).toBe(
+      "git@github.com:facebook/react.git"
+    )
+    expect(buildGitUrl("microsoft", "TypeScript")).toBe(
+      "git@github.com:microsoft/TypeScript.git"
+    )
+  })
+})
+
+describe("git operations (integration)", () => {
+  const testDir = join(tmpdir(), `opencode-repos-test-${Date.now()}`)
+  const repoPath = join(testDir, "test-repo")
+
+  beforeAll(async () => {
+    await mkdir(testDir, { recursive: true })
+  })
+
+  afterAll(async () => {
+    await rm(testDir, { recursive: true, force: true })
+  })
+
+  test("cloneRepo clones a public repository", async () => {
+    await cloneRepo(
+      "https://github.com/octocat/Hello-World.git",
+      repoPath,
+      { branch: "master" }
+    )
+
+    const exists = await Bun.file(join(repoPath, ".git/config")).exists()
+    expect(exists).toBe(true)
+  })
+
+  test("getRepoInfo returns correct information", async () => {
+    const info = await getRepoInfo(repoPath)
+
+    expect(info.remote).toBe("https://github.com/octocat/Hello-World.git")
+    expect(info.branch).toBe("master")
+    expect(info.commit).toMatch(/^[a-f0-9]{40}$/)
+  })
+
+  test("updateRepo fetches and resets", async () => {
+    await updateRepo(repoPath, "master")
+    const infoAfter = await getRepoInfo(repoPath)
+
+    expect(infoAfter.branch).toBe("master")
+    expect(infoAfter.commit).toMatch(/^[a-f0-9]{40}$/)
+  })
+
+  test("cloneRepo cleans up on failure", async () => {
+    const badPath = join(testDir, "bad-clone")
+
+    try {
+      await cloneRepo(
+        "https://github.com/nonexistent-user-12345/nonexistent-repo-67890.git",
+        badPath
+      )
+      expect(true).toBe(false)
+    } catch {
+      const exists = await Bun.file(badPath).exists()
+      expect(exists).toBe(false)
+    }
+  })
+})

package/src/__tests__/manifest.test.ts

@@ -0,0 +1,249 @@
+import { test, expect, beforeEach, afterEach, describe } from "bun:test"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { mkdir, rm } from "node:fs/promises"
+import { loadManifest, saveManifest, withManifestLock, type Manifest } from "../manifest"
+
+const originalCacheDir = join(homedir(), ".cache", "opencode-repos")
+
+describe("loadManifest", () => {
+  beforeEach(async () => {
+    await rm(originalCacheDir, { recursive: true, force: true })
+  })
+
+  afterEach(async () => {
+    await rm(originalCacheDir, { recursive: true, force: true })
+  })
+
+  test("creates empty manifest if file does not exist", async () => {
+    const manifest = await loadManifest()
+
+    expect(manifest).toEqual({
+      version: 1,
+      repos: {},
+      localIndex: {},
+    })
+  })
+
+  test("returns existing manifest when file exists", async () => {
+    await mkdir(originalCacheDir, { recursive: true })
+
+    const existingManifest: Manifest = {
+      version: 1,
+      repos: {
+        "owner/repo@main": {
+          type: "cached",
+          path: "/some/path",
+          lastAccessed: "2024-01-01T00:00:00.000Z",
+          defaultBranch: "main",
+          shallow: true,
+        },
+      },
+      localIndex: {
+        "https://github.com/owner/repo.git": "/local/path",
+      },
+    }
+
+    await Bun.write(
+      join(originalCacheDir, "manifest.json"),
+      JSON.stringify(existingManifest, null, 2)
+    )
+
+    const manifest = await loadManifest()
+
+    expect(manifest).toEqual(existingManifest)
+  })
+
+  test("handles corrupted JSON gracefully", async () => {
+    await mkdir(originalCacheDir, { recursive: true })
+    await Bun.write(join(originalCacheDir, "manifest.json"), "{ invalid json }")
+
+    const manifest = await loadManifest()
+
+    expect(manifest).toEqual({
+      version: 1,
+      repos: {},
+      localIndex: {},
+    })
+  })
+})
+
+describe("saveManifest", () => {
+  beforeEach(async () => {
+    await rm(originalCacheDir, { recursive: true, force: true })
+  })
+
+  afterEach(async () => {
+    await rm(originalCacheDir, { recursive: true, force: true })
+  })
+
+  test("creates directory if it does not exist", async () => {
+    const manifest: Manifest = {
+      version: 1,
+      repos: {},
+      localIndex: {},
+    }
+
+    await saveManifest(manifest)
+
+    const file = Bun.file(join(originalCacheDir, "manifest.json"))
+    expect(await file.exists()).toBe(true)
+  })
+
+  test("writes manifest atomically using tmp file", async () => {
+    const manifest: Manifest = {
+      version: 1,
+      repos: {
+        "test/repo@main": {
+          type: "cached",
+          path: "/test/path",
+          lastAccessed: "2024-01-01T00:00:00.000Z",
+          defaultBranch: "main",
+          shallow: false,
+        },
+      },
+      localIndex: {},
+    }
+
+    await saveManifest(manifest)
+
+    const savedContent = await Bun.file(join(originalCacheDir, "manifest.json")).text()
+    const savedManifest = JSON.parse(savedContent)
+
+    expect(savedManifest).toEqual(manifest)
+
+    const tmpFile = Bun.file(join(originalCacheDir, "manifest.json.tmp"))
+    expect(await tmpFile.exists()).toBe(false)
+  })
+
+  test("overwrites existing manifest", async () => {
+    const manifest1: Manifest = {
+      version: 1,
+      repos: { "first/repo@main": { type: "cached", path: "/first", lastAccessed: "2024-01-01T00:00:00.000Z", defaultBranch: "main", shallow: true } },
+      localIndex: {},
+    }
+
+    const manifest2: Manifest = {
+      version: 1,
+      repos: { "second/repo@main": { type: "local", path: "/second", lastAccessed: "2024-02-01T00:00:00.000Z", defaultBranch: "main", shallow: false } },
+      localIndex: { "url": "/path" },
+    }
+
+    await saveManifest(manifest1)
+    await saveManifest(manifest2)
+
+    const savedContent = await Bun.file(join(originalCacheDir, "manifest.json")).text()
+    const savedManifest = JSON.parse(savedContent)
+
+    expect(savedManifest).toEqual(manifest2)
+  })
+})
+
+describe("withManifestLock", () => {
+  beforeEach(async () => {
+    await rm(originalCacheDir, { recursive: true, force: true })
+  })
+
+  afterEach(async () => {
+    await rm(originalCacheDir, { recursive: true, force: true })
+  })
+
+  test("executes callback and returns result", async () => {
+    const result = await withManifestLock(async () => {
+      return "test-result"
+    })
+
+    expect(result).toBe("test-result")
+  })
+
+  test("releases lock after callback completes", async () => {
+    await withManifestLock(async () => {
+      return "done"
+    })
+
+    const lockFile = Bun.file(join(originalCacheDir, "manifest.lock"))
+    expect(await lockFile.exists()).toBe(false)
+  })
+
+  test("releases lock even if callback throws", async () => {
+    try {
+      await withManifestLock(async () => {
+        throw new Error("test error")
+      })
+    } catch {
+      // expected
+    }
+
+    const lockFile = Bun.file(join(originalCacheDir, "manifest.lock"))
+    expect(await lockFile.exists()).toBe(false)
+  })
+
+  test("prevents concurrent access", async () => {
+    const results: number[] = []
+
+    const task1 = withManifestLock(async () => {
+      results.push(1)
+      await Bun.sleep(50)
+      results.push(2)
+      return "task1"
+    })
+
+    await Bun.sleep(10)
+
+    const task2 = withManifestLock(async () => {
+      results.push(3)
+      return "task2"
+    })
+
+    await Promise.all([task1, task2])
+
+    expect(results).toEqual([1, 2, 3])
+  })
+
+  test("handles stale lock by removing it", async () => {
+    await mkdir(originalCacheDir, { recursive: true })
+
+    const staleTime = Date.now() - (6 * 60 * 1000)
+    await Bun.write(join(originalCacheDir, "manifest.lock"), String(staleTime))
+
+const { utimes } = await import("node:fs/promises")
+    const staleDate = new Date(staleTime)
+    await utimes(join(originalCacheDir, "manifest.lock"), staleDate, staleDate)
+
+    const result = await withManifestLock(async () => {
+      return "acquired-after-stale"
+    })
+
+    expect(result).toBe("acquired-after-stale")
+  })
+})
+
+describe("integration", () => {
+  beforeEach(async () => {
+    await rm(originalCacheDir, { recursive: true, force: true })
+  })
+
+  afterEach(async () => {
+    await rm(originalCacheDir, { recursive: true, force: true })
+  })
+
+  test("load, modify, and save manifest with lock", async () => {
+    await withManifestLock(async () => {
+      const manifest = await loadManifest()
+
+      manifest.repos["new/repo@main"] = {
+        type: "cached",
+        path: "/new/path",
+        lastAccessed: new Date().toISOString(),
+        defaultBranch: "main",
+        shallow: true,
+      }
+
+      await saveManifest(manifest)
+    })
+
+    const loaded = await loadManifest()
+    expect(loaded.repos["new/repo@main"]).toBeDefined()
+    expect(loaded.repos["new/repo@main"].type).toBe("cached")
+  })
+})

package/src/__tests__/setup.test.ts

@@ -0,0 +1,5 @@
+import { test, expect } from "bun:test";
+
+test("project setup is valid", () => {
+  expect(true).toBe(true);
+});

package/src/agents/repo-explorer.ts

@@ -0,0 +1,52 @@
+import type { AgentConfig } from "@opencode-ai/sdk"
+
+export function createRepoExplorerAgent(): AgentConfig {
+  return {
+    description:
+      "Specialized agent for exploring external codebases. Use when you need to understand another project's architecture, APIs, patterns, or implementation details to integrate with it or learn from it.",
+    mode: "subagent",
+    temperature: 0.1,
+    permission: {
+      edit: "deny",
+    },
+    prompt: `You are a codebase exploration specialist. Your job is to deeply understand external codebases and report your findings clearly.
+
+## Your Capabilities
+- Read and analyze source code across any programming language
+- Search for patterns and implementations using grep, glob, and AST tools
+- Understand project structure and architecture
+- Identify APIs, interfaces, and integration points
+- Trace code paths and data flows
+- Explain complex implementations in simple terms
+
+## Your Approach
+1. **Start high-level**: Begin with README, package.json, main entry points to understand the project's purpose
+2. **Map the structure**: Identify key directories and their purposes (src/, lib/, tests/, etc.)
+3. **Trace relevant paths**: Follow the code paths relevant to the specific question
+4. **Be specific**: Always cite file paths and line numbers
+5. **Show examples**: Include relevant code snippets to illustrate your findings
+6. **Explain interactions**: Describe how components, modules, and APIs interact
+
+## Output Format
+- **Be specific**: Always cite file paths (with line numbers if relevant)
+- **Include code snippets**: Show relevant portions of code with context
+- **Explain architecture**: Describe how components interact
+- **Note patterns**: Highlight any patterns, conventions, or best practices used
+- **Provide examples**: Give concrete examples of how to use discovered APIs
+
+## Important Constraints
+- You are **READ-ONLY**: You cannot modify, create, or delete any files
+- You cannot spawn tasks or sub-agents
+- Your job is to explore and report, not to modify
+- Focus on understanding and explaining, not implementing
+
+## Example Questions You Might Answer
+- "How does authentication work in this codebase?"
+- "What's the API for creating a new user?"
+- "How does the routing system work?"
+- "Find all places where database transactions are used"
+- "What patterns does this project use for error handling?"
+
+Remember: Be thorough but concise. Focus on what's relevant to the question while providing enough context for understanding.`,
+  }
+}

package/src/git.ts

@@ -0,0 +1,90 @@
+import { $ } from "bun"
+import { rm } from "node:fs/promises"
+
+export interface RepoSpec {
+  owner: string
+  repo: string
+  branch: string | null
+}
+
+export interface RepoInfo {
+  remote: string
+  branch: string
+  commit: string
+}
+
+export interface CloneOptions {
+  branch?: string
+}
+
+export function parseRepoSpec(spec: string): RepoSpec {
+  const atIndex = spec.indexOf("@")
+  let repoPath: string
+  let branch: string | null = null
+
+  if (atIndex !== -1) {
+    repoPath = spec.slice(0, atIndex)
+    branch = spec.slice(atIndex + 1)
+    if (!branch) {
+      throw new Error(`Invalid repo spec: branch cannot be empty after @`)
+    }
+  } else {
+    repoPath = spec
+  }
+
+  const slashIndex = repoPath.indexOf("/")
+  if (slashIndex === -1) {
+    throw new Error(`Invalid repo spec: must be in format "owner/repo" or "owner/repo@branch"`)
+  }
+
+  const owner = repoPath.slice(0, slashIndex)
+  const repo = repoPath.slice(slashIndex + 1)
+
+  if (!owner || !repo) {
+    throw new Error(`Invalid repo spec: owner and repo cannot be empty`)
+  }
+
+  if (repo.includes("/")) {
+    throw new Error(`Invalid repo spec: repo name cannot contain "/"`)
+  }
+
+  return { owner, repo, branch }
+}
+
+export function buildGitUrl(owner: string, repo: string): string {
+  return `git@github.com:${owner}/${repo}.git`
+}
+
+export async function cloneRepo(
+  url: string,
+  destPath: string,
+  options: CloneOptions = {}
+): Promise<void> {
+  const branch = options.branch || "main"
+
+  try {
+    await $`git clone --depth=1 --single-branch --branch ${branch} --config core.hooksPath=/dev/null ${url} ${destPath}`.quiet()
+  } catch (error) {
+    try {
+      await rm(destPath, { recursive: true, force: true })
+    } catch {}
+    throw error
+  }
+}
+
+export async function updateRepo(path: string, branch: string = "main"): Promise<void> {
+  await $`git -C ${path} fetch origin ${branch} --depth=1`.quiet()
+  await $`git -C ${path} reset --hard origin/${branch}`.quiet()
+}
+
+export async function getRepoInfo(path: string): Promise<RepoInfo> {
+  const remote = await $`git -C ${path} remote get-url origin`.text()
+  const branch = await $`git -C ${path} branch --show-current`.text()
+  const commit = await $`git -C ${path} rev-parse HEAD`.text()
+
+  return {
+    remote: remote.trim(),
+    branch: branch.trim(),
+    commit: commit.trim(),
+  }
+}

package/src/manifest.ts

@@ -0,0 +1,116 @@
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { mkdir, rename, unlink, stat } from "node:fs/promises"
+
+export interface RepoEntry {
+  type: "cached" | "local"
+  path: string
+  clonedAt?: string
+  lastAccessed: string
+  lastUpdated?: string
+  sizeBytes?: number
+  defaultBranch: string
+  shallow: boolean
+}
+
+export interface Manifest {
+  version: 1
+  repos: Record<string, RepoEntry>
+  localIndex: Record<string, string>
+}
+
+export interface Config {
+  localSearchPaths: string[]
+}
+
+const CACHE_DIR = join(homedir(), ".cache", "opencode-repos")
+const MANIFEST_PATH = join(CACHE_DIR, "manifest.json")
+const MANIFEST_TMP_PATH = join(CACHE_DIR, "manifest.json.tmp")
+const LOCK_PATH = join(CACHE_DIR, "manifest.lock")
+const LOCK_STALE_MS = 5 * 60 * 1000
+
+function createEmptyManifest(): Manifest {
+  return {
+    version: 1,
+    repos: {},
+    localIndex: {},
+  }
+}
+
+export async function loadManifest(): Promise<Manifest> {
+  const file = Bun.file(MANIFEST_PATH)
+  const exists = await file.exists()
+
+  if (!exists) {
+    return createEmptyManifest()
+  }
+
+  try {
+    const content = await file.text()
+    const parsed = JSON.parse(content) as Manifest
+    return parsed
+  } catch {
+    console.warn("[opencode-repos] Manifest corrupted, returning empty manifest")
+    return createEmptyManifest()
+  }
+}
+
+export async function saveManifest(manifest: Manifest): Promise<void> {
+  await mkdir(CACHE_DIR, { recursive: true })
+  await Bun.write(MANIFEST_TMP_PATH, JSON.stringify(manifest, null, 2))
+  await rename(MANIFEST_TMP_PATH, MANIFEST_PATH)
+}
+
+async function isLockStale(): Promise<boolean> {
+  try {
+    const lockStat = await stat(LOCK_PATH)
+    const age = Date.now() - lockStat.mtimeMs
+    return age > LOCK_STALE_MS
+  } catch {
+    return true
+  }
+}
+
+async function acquireLock(): Promise<void> {
+  const maxAttempts = 50
+  const retryDelayMs = 100
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const lockFile = Bun.file(LOCK_PATH)
+    const exists = await lockFile.exists()
+
+    if (exists) {
+      if (await isLockStale()) {
+        await unlink(LOCK_PATH).catch(() => {})
+      } else {
+        await Bun.sleep(retryDelayMs)
+        continue
+      }
+    }
+
+    try {
+      await mkdir(CACHE_DIR, { recursive: true })
+      await Bun.write(LOCK_PATH, String(Date.now()))
+      return
+    } catch {
+      await Bun.sleep(retryDelayMs)
+    }
+  }
+
+  throw new Error("Failed to acquire manifest lock after maximum attempts")
+}
+
+async function releaseLock(): Promise<void> {
+  await unlink(LOCK_PATH).catch(() => {})
+}
+
+export async function withManifestLock<T>(
+  callback: () => Promise<T>
+): Promise<T> {
+  await acquireLock()
+  try {
+    return await callback()
+  } finally {
+    await releaseLock()
+  }
+}