Skip to content

AGENTS.md

Latest commit

 

History

History
56 lines (40 loc) · 2.85 KB

AGENTS.md

File metadata and controls

56 lines (40 loc) · 2.85 KB
Raw

AGENTS.md

Commands

npm run check       # tsc --noEmit (type-check src + tests)
bun test tests/     # run all tests (Bun test runner)
npm run check && bun test tests/   # pre-publish verification

No build step — OpenCode loads .ts source files directly.

Architecture

Single-package OpenCode plugin — thin adapter wrapping @oh-my-pi/hashline core. All patch engine logic is upstream.

File Role
src/plugin.ts Entry — exports opencodeHashlinePlugin: Plugin (async function, not object)
src/tool-edit.ts edit tool override via tool() helper
src/hook-read.ts tool.execute.after hook — injects [path#TAG] into read output
src/read-snapshot.ts Records file snapshots (Node fs async)
src/store.ts Factory for InMemorySnapshotStore
src/prompt.d.ts Type declaration for .md imports from @oh-my-pi/hashline
tests/ 9 test files — bun:test, no vitest
docs/ test-design.md, comparison-report.md, publish.md

Key behaviors

  • Overrides built-in edit — registered as edit in hooks tool map; OpenCode custom tools take precedence over built-in.
  • Tag-verified edits — every edit needs [path#TAG] matching file's last-read snapshot. Stale/fabricated tags rejected.
  • SWAP.BLK N: / DEL.BLK N / INS.BLK.POST N: not supported — tree-sitter block resolution requires @oh-my-pi/pi-natives (N-API Rust addon), not bundled. Use explicit line ranges (SWAP N.=M:) instead. Impact: LLM must count closing lines itself, which it already does for most edits. A miscount is caught by tag verification → re-read → retry. Not worth ~30MB WASM dependency for marginal UX gain.
  • 3-way merge recovery — handled by Patcher's built-in Recovery (auto-created, no wiring needed). External changes to unrelated lines are merged automatically. Only truly unrecoverable conflicts (anchor line gone, same line modified by both external and edit) throw MismatchError → adapter returns "re-read and retry".

TypeScript quirks

  • .md imports use import ... with { type: "text" } → requires "module": "preserve" in tsconfig.
  • tool.schema helpers (tool.schema.string(), etc.) resolve to Zod schemas from @opencode-ai/plugin.

Dependencies

Package Role
@oh-my-pi/hashline Core patch engine (Bun-native)
@opencode-ai/plugin Plugin SDK — Plugin, tool(), ToolContext, Hooks

Distribution

opencode plugin @debugtalk/opencode-hashline       # install (auto-config)
opencode plugin @debugtalk/opencode-hashline --force # upgrade

Verify: grep "opencode-hashline" ~/.local/share/opencode/log/opencode.log → opencode-hashline plugin loaded

See docs/publish.md for npm release steps. Bugfixes/features go to oh-my-pi/packages/hashline.