@vibe-forge/adapter-opencode 0.1.2

package/AGENTS.md

@@ -0,0 +1,13 @@
+# OpenCode Adapter 目录说明
+
+- `src/runtime/common/`：纯配置与参数映射层，只做 prompt、tools、permissions、model、mcp、session record 转换，不承载进程控制
+- `src/runtime/session/`：运行时层，负责 child env、skill bridge、direct/stream 会话执行与错误传播
+- `src/runtime/common.ts` / `src/runtime/session.ts`：稳定入口文件，只做 re-export 或轻量路由
+- `__tests__/runtime-*.spec.ts`：按能力拆分测试；公共 mock 和文件系统 helper 放在 `__tests__/runtime-test-helpers.ts`
+
+约束：
+
+- 单文件保持在 200 行以内；接近 160 行时优先继续拆，而不是继续堆分支
+- 新增逻辑先判断属于“映射层”还是“运行时层”，不要再把两类职责混回一个文件
+- 需要 mock `child_process` 的测试，mock 定义放在各自 spec 顶部；helper 不直接持有全局 mock 状态
+- 修改 adapter 行为时，至少补一条对应的 runtime 或 common 回归测试

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Vibe-Forge.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/__tests__/runtime-common.spec.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest'
+
+import { resolveOpenCodeBinaryPath } from '#~/paths.js'
+import {
+  buildOpenCodeRunArgs,
+  buildOpenCodeSessionTitle,
+  extractOpenCodeSessionRecords,
+  normalizeOpenCodePrompt,
+  resolveLocalAttachmentPath,
+  resolveOpenCodeAgent,
+  selectOpenCodeSessionByTitle
+} from '#~/runtime/common.js'
+
+describe('resolveOpenCodeBinaryPath', () => {
+  it('resolves to the adapter bundled binary by default', () => {
+    expect(resolveOpenCodeBinaryPath({})).toMatch(/node_modules\/\.bin\/opencode$/)
+  })
+
+  it('returns the env-specified path when set', () => {
+    expect(resolveOpenCodeBinaryPath({
+      __VF_PROJECT_AI_ADAPTER_OPENCODE_CLI_PATH__: '/usr/local/bin/opencode'
+    })).toBe('/usr/local/bin/opencode')
+  })
+})
+
+describe('OpenCode prompt and session helpers', () => {
+  it('normalizes prompt text and attachments', () => {
+    const result = normalizeOpenCodePrompt([
+      { type: 'text', text: 'Explain this diff' },
+      { type: 'image', url: 'file:///tmp/screenshot.png' }
+    ])
+
+    expect(result.prompt).toBe('Explain this diff')
+    expect(result.files).toEqual(['/tmp/screenshot.png'])
+  })
+
+  it('builds a deterministic session title', () => {
+    expect(buildOpenCodeSessionTitle('session-1', 'VF')).toBe('VF:session-1')
+  })
+
+  it('filters managed CLI flags from passthrough options', () => {
+    expect(buildOpenCodeRunArgs({
+      prompt: 'hello',
+      files: ['/tmp/a.txt'],
+      model: 'openai/gpt-5',
+      title: 'VF:session-1',
+      extraOptions: ['--log-level', 'DEBUG', '--format', 'json', '--session', 'abc']
+    })).toEqual([
+      'run',
+      '--format',
+      'default',
+      '--title',
+      'VF:session-1',
+      '--model',
+      'openai/gpt-5',
+      '--file',
+      '/tmp/a.txt',
+      '--log-level',
+      'DEBUG',
+      'hello'
+    ])
+  })
+
+  it('extracts session records from common JSON shapes', () => {
+    const records = extractOpenCodeSessionRecords({
+      sessions: [
+        { id: 'sess-old', title: 'VF:one', updatedAt: '2026-03-25T10:00:00.000Z' },
+        { sessionId: 'sess-new', title: 'VF:one', updated_at: '2026-03-25T11:00:00.000Z' }
+      ]
+    })
+
+    expect(records).toHaveLength(2)
+    expect(selectOpenCodeSessionByTitle(records, 'VF:one')?.id).toBe('sess-new')
+  })
+
+  it('resolves only local attachment paths', () => {
+    expect(resolveLocalAttachmentPath('file:///tmp/file.txt')).toBe('/tmp/file.txt')
+    expect(resolveLocalAttachmentPath('/tmp/file.txt')).toBe('/tmp/file.txt')
+    expect(resolveLocalAttachmentPath('https://example.com/file.txt')).toBeUndefined()
+  })
+
+  it('uses the plan agent by default in plan mode', () => {
+    expect(resolveOpenCodeAgent({ permissionMode: 'plan' })).toBe('plan')
+    expect(resolveOpenCodeAgent({
+      permissionMode: 'plan',
+      agent: 'build',
+      planAgent: false
+    })).toBe('build')
+    expect(resolveOpenCodeAgent({
+      permissionMode: 'plan',
+      agent: 'build',
+      planAgent: 'review'
+    })).toBe('review')
+  })
+})

package/__tests__/runtime-config.spec.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest'
+
+import { buildInlineConfigContent, resolveOpenCodeModel } from '#~/runtime/common.js'
+
+describe('OpenCode config and model helpers', () => {
+  it('builds inline config overrides for permissions, mcp, tools, and instructions', () => {
+    const config = buildInlineConfigContent({
+      envConfigContent: {
+        instructions: ['CONTRIBUTING.md']
+      },
+      adapterConfigContent: {
+        provider: {
+          existing: {
+            name: 'Existing'
+          }
+        }
+      },
+      permissionMode: 'default',
+      tools: {
+        exclude: ['write']
+      },
+      mcpServers: {
+        include: ['local-docs']
+      },
+      availableMcpServers: {
+        'local-docs': {
+          command: 'npx',
+          args: ['-y', '@modelcontextprotocol/server-everything']
+        }
+      },
+      systemPromptFile: '/tmp/system.md',
+      providerConfig: {
+        custom: {
+          npm: '@ai-sdk/openai-compatible'
+        }
+      }
+    })
+
+    expect(config).toMatchObject({
+      instructions: ['CONTRIBUTING.md', '/tmp/system.md'],
+      permission: {
+        '*': 'allow',
+        bash: 'ask',
+        edit: 'deny',
+        task: 'ask'
+      },
+      tools: {
+        write: false
+      },
+      mcp: {
+        'local-docs': {
+          type: 'local',
+          command: ['npx', '-y', '@modelcontextprotocol/server-everything'],
+          enabled: true
+        }
+      },
+      provider: {
+        existing: {
+          name: 'Existing'
+        },
+        custom: {
+          npm: '@ai-sdk/openai-compatible'
+        }
+      }
+    })
+  })
+
+  it('maps custom model services to an OpenCode provider/model pair', () => {
+    const result = resolveOpenCodeModel('gateway,gpt-5', {
+      gateway: {
+        apiBaseUrl: 'https://example.test/v1',
+        apiKey: 'secret',
+        title: 'Gateway',
+        timeoutMs: 600000,
+        maxOutputTokens: 8192
+      }
+    })
+
+    expect(result.cliModel).toBe('gateway/gpt-5')
+    expect(result.providerConfig).toMatchObject({
+      gateway: {
+        npm: '@ai-sdk/openai-compatible',
+        options: {
+          apiKey: 'secret',
+          baseURL: 'https://example.test/v1',
+          timeout: 600000,
+          chunkTimeout: 600000
+        },
+        models: {
+          'gpt-5': {
+            name: 'gpt-5',
+            limit: {
+              output: 8192
+            },
+            options: {
+              maxOutputTokens: 8192
+            }
+          }
+        }
+      }
+    })
+  })
+
+  it('preserves provider prefix when explicit service syntax has no local mapping', () => {
+    expect(resolveOpenCodeModel('openrouter,claude-sonnet-4.5', {})).toEqual({
+      cliModel: 'openrouter/claude-sonnet-4.5',
+      providerConfig: undefined
+    })
+  })
+
+  it('does not inject permission overrides when no runtime permission inputs are provided', () => {
+    expect(buildInlineConfigContent({})).not.toHaveProperty('permission')
+  })
+
+  it('preserves inherited string permission config when runtime permission is unset', () => {
+    expect(buildInlineConfigContent({
+      adapterConfigContent: {
+        permission: 'ask'
+      }
+    })).toMatchObject({
+      permission: 'ask'
+    })
+  })
+})

package/__tests__/runtime-permissions.spec.ts

@@ -0,0 +1,181 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  buildInlineConfigContent,
+  buildToolConfig,
+  buildToolPermissionConfig
+} from '#~/runtime/common.js'
+
+describe('OpenCode permission and tool helpers', () => {
+  it('derives permission overrides from tool selection aliases', () => {
+    expect(buildToolPermissionConfig({
+      include: ['grep', 'view'],
+      exclude: ['bash']
+    })).toEqual({
+      '*': 'deny',
+      bash: 'deny',
+      edit: 'deny',
+      glob: 'deny',
+      grep: 'allow',
+      question: 'deny',
+      read: 'allow',
+      list: 'deny',
+      lsp: 'deny',
+      skill: 'deny',
+      task: 'deny',
+      todoread: 'deny',
+      todowrite: 'deny',
+      webfetch: 'deny',
+      websearch: 'deny',
+      codesearch: 'deny'
+    })
+  })
+
+  it('preserves permission mode semantics for included tools', () => {
+    expect(buildToolPermissionConfig(
+      { include: ['bash', 'write'] },
+      { '*': 'allow', bash: 'ask', edit: 'deny' }
+    )).toMatchObject({
+      '*': 'deny',
+      bash: 'ask',
+      edit: 'deny'
+    })
+  })
+
+  it('preserves custom tool permissions and nested rules when includes are narrowed', () => {
+    expect(buildToolPermissionConfig(
+      {
+        include: ['bash', 'mcp__docs__*'],
+        exclude: ['websearch']
+      },
+      {
+        bash: {
+          '*': 'ask',
+          'rm *': 'deny'
+        },
+        'mcp__docs__*': 'ask'
+      } as any
+    )).toMatchObject({
+      '*': 'deny',
+      bash: {
+        '*': 'ask',
+        'rm *': 'deny'
+      },
+      'mcp__docs__*': 'ask',
+      websearch: 'deny',
+      edit: 'deny'
+    })
+  })
+
+  it('normalizes tool aliases to OpenCode tool names', () => {
+    expect(buildToolConfig({
+      include: ['view', 'fetch', 'question', 'mcp__docs__*', 'agent'],
+      exclude: ['ls', 'write', 'task', 'custom-tool']
+    })).toEqual({
+      read: true,
+      webfetch: true,
+      question: true,
+      'mcp__docs__*': true,
+      list: false,
+      write: false,
+      'custom-tool': false
+    })
+  })
+
+  it('treats wildcard include as a no-op for tool toggles while preserving explicit excludes', () => {
+    expect(buildToolConfig({
+      include: ['*', 'agent'],
+      exclude: ['bash', '*']
+    })).toEqual({
+      bash: false
+    })
+
+    expect(buildToolPermissionConfig({
+      include: ['*'],
+      exclude: ['bash']
+    })).toEqual({
+      bash: 'deny'
+    })
+  })
+
+  it('keeps dontAsk mode non-interactive while preserving explicit denies', () => {
+    const config = buildInlineConfigContent({
+      adapterConfigContent: {
+        permission: {
+          bash: 'ask',
+          edit: 'deny',
+          skill: {
+            '*': 'ask',
+            'internal-*': 'deny'
+          }
+        }
+      },
+      permissionMode: 'dontAsk'
+    })
+
+    expect(config).toMatchObject({
+      permission: {
+        '*': 'allow',
+        bash: 'allow',
+        edit: 'deny',
+        skill: {
+          '*': 'allow',
+          'internal-*': 'deny'
+        }
+      }
+    })
+  })
+
+  it('lets bypassPermissions clear inherited denies recursively', () => {
+    expect(buildInlineConfigContent({
+      adapterConfigContent: {
+        permission: {
+          '*': 'deny',
+          bash: 'ask',
+          skill: {
+            '*': 'deny',
+            'internal-*': 'deny'
+          }
+        }
+      },
+      permissionMode: 'bypassPermissions'
+    })).toMatchObject({
+      permission: {
+        '*': 'allow',
+        bash: 'allow',
+        skill: {
+          '*': 'allow',
+          'internal-*': 'allow'
+        }
+      }
+    })
+  })
+
+  it('preserves nested skill permission config while applying runtime overrides', () => {
+    expect(buildInlineConfigContent({
+      adapterConfigContent: {
+        permission: {
+          skill: {
+            '*': 'allow',
+            'internal-*': 'deny'
+          }
+        }
+      },
+      permissionMode: 'default',
+      tools: {
+        exclude: ['bash']
+      }
+    })).toMatchObject({
+      permission: {
+        '*': 'allow',
+        bash: 'deny',
+        edit: 'ask',
+        task: 'ask',
+        skill: {
+          '*': 'allow',
+          'internal-*': 'deny'
+        }
+      }
+    })
+  })
+})

package/__tests__/runtime-test-helpers.ts

@@ -0,0 +1,142 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { PassThrough } from 'node:stream'
+
+import { afterEach, beforeEach, vi } from 'vitest'
+
+const tempDirs: string[] = []
+
+function makeMockLogger() {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn()
+  }
+}
+
+export function registerRuntimeTestHooks() {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    delete process.env.HOME
+  })
+
+  afterEach(async () => {
+    await Promise.all(tempDirs.splice(0).map(dir => rm(dir, { recursive: true, force: true })))
+  })
+}
+
+export function makeCtx(overrides: {
+  env?: Record<string, string | null | undefined>
+  configs?: [unknown?, unknown?]
+  cacheSeed?: Record<string, unknown>
+  cwd?: string
+} = {}) {
+  const cacheStore = new Map<string, unknown>(Object.entries(overrides.cacheSeed ?? {}))
+
+  return {
+    cacheStore,
+    ctx: {
+      ctxId: 'test-ctx',
+      cwd: overrides.cwd ?? '/tmp',
+      env: overrides.env ?? {},
+      cache: {
+        set: async (key: string, value: unknown) => {
+          cacheStore.set(key, value)
+          return { cachePath: `/tmp/${key}.json` }
+        },
+        get: async (key: string) => cacheStore.get(key)
+      },
+      logger: makeMockLogger(),
+      configs: overrides.configs ?? [undefined, undefined]
+    } as any
+  }
+}
+
+export const createWorkspace = async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'opencode-adapter-'))
+  tempDirs.push(dir)
+  return dir
+}
+
+export const writeDocument = async (filePath: string, content: string) => {
+  await mkdir(dirname(filePath), { recursive: true })
+  await writeFile(filePath, content)
+}
+
+export function makeProc(options: {
+  stdout?: string
+  stderr?: string
+  exitCode?: number
+  pid?: number
+} = {}) {
+  const stdout = new PassThrough()
+  const stderr = new PassThrough()
+  const handlers = new Map<string, (...args: any[]) => void>()
+
+  const proc = {
+    stdout,
+    stderr,
+    pid: options.pid ?? 4321,
+    on: vi.fn((event: string, handler: (...args: any[]) => void) => {
+      handlers.set(event, handler)
+      return proc
+    }),
+    kill: vi.fn(() => {
+      queueMicrotask(() => handlers.get('exit')?.(130))
+      return true
+    })
+  } as any
+
+  queueMicrotask(() => {
+    if (options.stdout) stdout.write(options.stdout)
+    stdout.end()
+    if (options.stderr) stderr.write(options.stderr)
+    stderr.end()
+    handlers.get('exit')?.(options.exitCode ?? 0)
+  })
+
+  return proc
+}
+
+export function makeErrorProc(error: Error) {
+  const stdout = new PassThrough()
+  const stderr = new PassThrough()
+  const handlers = new Map<string, (...args: any[]) => void>()
+
+  const proc = {
+    stdout,
+    stderr,
+    pid: 4321,
+    on: vi.fn((event: string, handler: (...args: any[]) => void) => {
+      handlers.set(event, handler)
+      return proc
+    }),
+    kill: vi.fn(() => true)
+  } as any
+
+  queueMicrotask(() => handlers.get('error')?.(error))
+  return proc
+}
+
+export function mockExecFileJsonResponses(
+  execFileMock: { mockImplementation: (impl: (...args: unknown[]) => unknown) => unknown },
+  ...payloads: unknown[]
+) {
+  execFileMock.mockImplementation(((...args: unknown[]) => {
+    const callback = args.at(-1) as ((err: Error | null, stdout: string, stderr: string) => void) | undefined
+    const payload = payloads.shift() ?? []
+    queueMicrotask(() => {
+      callback?.(null, JSON.stringify(payload), '')
+    })
+    return {} as any
+  }) as any)
+}
+
+export async function flushAsyncWork() {
+  await new Promise(resolve => setTimeout(resolve, 50))
+}