opencode-plannotator-tui 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.2.0
+
+Initial public release of the OpenCode adapter for Plannotator TUI.
+
+- `/annotate [file]` and `/annotate-last` for replies or local Markdown/text documents.
+- Same-terminal handoff and confirmed feedback to the captured session.
+- Paginated completed-reply lookup and isolated document snapshots.
+- Original document path and snapshot hash included in feedback.
+- Recovery drafts on failure and preservation of archived annotations.
+- Fourteen behavior tests and real terminal/API smoke coverage.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nxxxsooo
+
+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/README.md

@@ -0,0 +1,169 @@
+# Plannotator TUI for OpenCode
+
+[![npm](https://img.shields.io/npm/v/opencode-plannotator-tui)](https://www.npmjs.com/package/opencode-plannotator-tui)
+[![CI](https://github.com/nxxxsooo/opencode-plannotator-tui/actions/workflows/ci.yml/badge.svg)](https://github.com/nxxxsooo/opencode-plannotator-tui/actions/workflows/ci.yml)
+[![MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+**Annotate an AI reply or a document in your terminal, then send the feedback straight back to OpenCode.**
+
+This is an **unofficial OpenCode adapter** for [Plannotator TUI](https://github.com/plannotator/plannotator-tui).
+Plannotator TUI provides the annotation interface. This plugin supplies the commands,
+session targeting, terminal handoff and confirmed feedback delivery. It is not an
+official OpenCode or Plannotator release.
+
+```text
+/annotate                         Review the last completed assistant reply
+/annotate docs/plan.md            Review a Markdown document
+/annotate "docs/release plan.md"  Review a path containing spaces
+/annotate ~/Documents/notes.txt   Review a plain-text document
+```
+
+`/annotate-last` is an alias with the same optional file argument.
+
+## Install
+
+Requires **OpenCode 2.0.22+** and a separately installed `plannotator-tui` on your PATH.
+Tested with OpenCode 2.0.24 and Plannotator TUI 0.9.4 on macOS; unit tests also run on
+Linux. Windows terminal handoff has not been verified.
+
+Install the upstream TUI on macOS or Linux:
+
+```sh
+brew install plannotator/tap/plannotator-tui
+```
+
+Homebrew 6 may first require `brew trust plannotator/tap`. Alternatively, use
+`cargo install plannotator-tui --locked` or the upstream
+[prebuilt binaries](https://github.com/plannotator/plannotator-tui/releases).
+
+Then install the adapter:
+
+```sh
+opencode plugin add opencode-plannotator-tui@latest
+```
+
+OpenCode detects its TUI-only entrypoint and adds it to your global **`cli.json`**.
+It does not need a server-plugin entry. Reopen the terminal client if its command
+list has not refreshed.
+
+Manual configuration, preserving other entries:
+
+```json
+{
+  "plugins": ["opencode-plannotator-tui@latest"]
+}
+```
+
+## Review and send
+
+1. Run `/annotate` or `/annotate path/to/file.md` in a session.
+2. Select text by dragging, or press `v` and use movement keys.
+3. Press `c` to comment, `a` for “looks good,” or `d` to request deletion.
+   Without a selection, `c` comments on the current block. Enter saves a comment.
+4. Press **`q`** to return to OpenCode.
+5. Choose **发送并继续** (“Send and continue”) to submit the annotations. Escape or
+   **取消** cancels. The adapter's confirmation and status messages are currently Chinese.
+
+The upstream **`E`** action copies to the clipboard. This adapter's automatic
+delivery path is **q → confirm** and does not need clipboard access.
+
+Opening a review makes no model call. Confirming sends a normal user prompt and
+resumes the **original session**, even if the active tab changes. Empty and
+cancelled reviews submit nothing.
+
+## What it reviews
+
+**Replies:** the latest completed text reply, with paginated history lookup.
+Reasoning, in-progress messages and tool-call commentary are excluded.
+
+**Documents:** local UTF-8 `.md`, `.mdx`, `.markdown` and `.txt` files up to 2 MiB.
+Relative paths resolve against the captured session's working directory, not the
+directory from which the terminal client happened to start. Absolute and `~/`
+paths work too. The file must exist on the machine running the terminal client.
+
+The TUI reads a fixed snapshot and does not edit the original document. Feedback
+includes the original path and snapshot hash, with instructions to re-read the
+current file before applying suggestions. Document review works even before the
+session has an assistant reply.
+
+## Updates and uninstall
+
+`@latest` selects the npm release channel. OpenCode caches installed packages;
+it does not follow this repository's commits. Update just this plugin with:
+
+```sh
+opencode plugin update opencode-plannotator-tui@latest
+```
+
+Reopen your terminal client to load updated package code. No shared background
+service restart is required. Check the installed version with `opencode plugin list`.
+
+To remove it:
+
+```sh
+opencode plugin remove opencode-plannotator-tui@latest
+```
+
+## Configuration
+
+Set `binary` if Plannotator TUI is installed outside the terminal client's PATH:
+
+```json
+{
+  "plugins": [
+    {
+      "package": "opencode-plannotator-tui@latest",
+      "options": { "binary": "/path/to/plannotator-tui" }
+    }
+  ]
+}
+```
+
+## Draft recovery
+
+Each review has its own private temporary source and annotation store. Successful,
+empty and cancelled reviews are cleaned up. Failures and archived notes retain the
+store, and a status message gives its directory.
+
+`review.json` records the session, original source and relative `snapshot` path.
+`feedback.md` holds exported feedback when available. To recover a retained review:
+
+```sh
+PLANNOTATOR_DATA_DIR="<retained-directory>/data" \
+  plannotator-tui "<retained-directory>/<snapshot>"
+```
+
+Use the `snapshot` value from `review.json`. Press `H` to restore archived notes,
+then `E` to copy them for pasting into OpenCode. An upstream **E → F** archive is
+preserved even when `--export` reports “No annotations.”
+
+## Development
+
+```sh
+npm ci
+npm run check
+npm run test:smoke
+```
+
+Unit tests use the real upstream annotation/export binary. The optional smoke test
+also requires Python 3, tmux and OpenCode. It runs a detached terminal, verifies
+commands and feedback through the actual API, then removes its test session.
+Its submission uses `resume: false`, so it makes no model call or visible window.
+
+For development loading, add this checkout's absolute directory to `cli.json`
+instead of the npm package. Use only one installation at a time.
+
+See [release instructions](docs/releasing.md) and [changelog](CHANGELOG.md).
+
+## 中文速用
+
+这是 **Plannotator TUI 的非官方 OpenCode 适配插件**。
+
+- `/annotate`：批注上一条完整回复。
+- `/annotate 文档.md`：批注文档，支持中文、空格和相对路径。
+- `/annotate-last`：同义入口，也可带文件路径。
+- 选中文字 → `c` 写批注 → Enter 保存 → `q` 返回 →「发送并继续」。
+- 文档采用独立快照，反馈附原文件路径，确认后发回发起批注的会话。
+- 更新：`opencode plugin update opencode-plannotator-tui@latest`，然后重新打开终端客户端。
+
+MIT licensed. The annotation UI is maintained upstream by the Plannotator project.

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "opencode-plannotator-tui",
+  "version": "0.2.0",
+  "description": "Unofficial OpenCode adapter for Plannotator TUI: annotate replies and documents without leaving your terminal.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    "./tui": "./tui.ts"
+  },
+  "scripts": {
+    "test": "node --test review.test.mjs",
+    "test:smoke": "python3 smoke.py",
+    "check": "node --check review.mjs && npm test && npm pack --dry-run",
+    "prepublishOnly": "npm run check"
+  },
+  "files": ["tui.ts", "review.mjs", "README.md", "LICENSE", "CHANGELOG.md"],
+  "engines": { "node": ">=22" },
+  "peerDependencies": { "@opencode/plugin": ">=2.0.22 <3" },
+  "peerDependenciesMeta": { "@opencode/plugin": { "optional": true } },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nxxxsooo/opencode-plannotator-tui.git"
+  },
+  "homepage": "https://github.com/nxxxsooo/opencode-plannotator-tui#readme",
+  "bugs": { "url": "https://github.com/nxxxsooo/opencode-plannotator-tui/issues" },
+  "keywords": ["opencode", "opencode-plugin", "plannotator", "tui", "annotation", "markdown", "review"],
+  "publishConfig": { "access": "public" }
+}

package/review.mjs

@@ -0,0 +1,228 @@
+import { spawn, execFile } from "node:child_process"
+import { createHash, randomUUID } from "node:crypto"
+import { mkdtemp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import { promisify } from "node:util"
+
+const execute = promisify(execFile)
+const documentExtensions = new Set([".md", ".mdx", ".markdown", ".txt"])
+const maxDocumentBytes = 2 * 1024 * 1024
+
+async function documentSource(input, client, sessionID, signal) {
+  let target = input.trim()
+  if ((target.startsWith('"') && target.endsWith('"')) || (target.startsWith("'") && target.endsWith("'"))) {
+    target = target.slice(1, -1)
+  }
+  if (!target || !documentExtensions.has(path.extname(target).toLowerCase())) {
+    throw new Error("请指定一个 Markdown 或纯文本文件（.md、.mdx、.markdown、.txt）。")
+  }
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(target)) throw new Error("请指定本地文件路径。")
+  if (target.startsWith("~/")) target = path.join(os.homedir(), target.slice(2))
+  const session = await client.session.get({ sessionID }, { signal })
+  const directory = session.location?.directory
+  if (!path.isAbsolute(target) && !directory) throw new Error("无法确定当前会话的工作目录。")
+  const filePath = path.isAbsolute(target) ? path.normalize(target) : path.resolve(directory, target)
+  try {
+    const info = await stat(filePath)
+    if (!info.isFile()) throw new Error("目标不是文件。")
+    if (info.size > maxDocumentBytes) throw new Error("文件超过 2 MiB，请先选取较小的文档。")
+    const bytes = await readFile(filePath, { signal })
+    if (bytes.length > maxDocumentBytes) throw new Error("文件超过 2 MiB。")
+    if (bytes.includes(0)) throw new Error("文件包含二进制内容。")
+    let text
+    try {
+      text = new TextDecoder("utf-8", { fatal: true }).decode(bytes)
+    } catch {
+      throw new Error("请使用 UTF-8 编码的文本文件。")
+    }
+    return {
+      text, filePath,
+      sourceHash: createHash("sha256").update(bytes).digest("hex"),
+      snapshot: path.join("source", path.basename(filePath)),
+    }
+  } catch (error) {
+    if (signal.aborted) throw error
+    throw new Error(`无法读取文档「${filePath}」：${error.code === "ENOENT" ? "文件不存在。" : error.message}`)
+  }
+}
+
+export function selectReply(messages) {
+  const newest = [...messages].sort((a, b) =>
+    b.time.created - a.time.created || b.id.localeCompare(a.id),
+  )
+  for (const message of newest) {
+    if (message.type !== "assistant" || message.time.completed === undefined || message.error) continue
+    if (["tool-calls", "error", "content-filter"].includes(message.finish)) continue
+    const text = message.content.filter(part => part.type === "text").map(part => part.text).join("\n\n")
+    if (text.trim()) return { id: message.id, text }
+  }
+}
+
+async function latestReply(client, sessionID, signal) {
+  const seen = new Set()
+  let cursor
+  do {
+    signal.throwIfAborted()
+    const page = await client.message.list({
+      sessionID, type: "assistant", limit: 50,
+      ...(cursor ? { cursor } : { order: "desc" }),
+    }, { signal })
+    const reply = selectReply(page.data)
+    if (reply) return reply
+    cursor = page.cursor?.next
+    if (cursor && seen.has(cursor)) throw new Error("读取会话历史时收到重复分页游标。")
+    seen.add(cursor)
+  } while (cursor)
+}
+
+async function archivedNotes(data) {
+  let count = 0
+  for (const name of await readdir(data, { recursive: true })) {
+    if (path.basename(name) !== "annotations.json") continue
+    const record = JSON.parse(await readFile(path.join(data, name), "utf8"))
+    count += record.archived?.length ?? 0
+  }
+  return count
+}
+
+async function interactive({ binary, file, cwd, env, signal }) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error("请在 OpenCode 完整终端界面中运行 /annotate。")
+  }
+  await new Promise((resolve, reject) => {
+    const child = spawn(binary, [file], { cwd, env, stdio: "inherit", signal })
+    child.once("error", reject)
+    child.once("close", (code, termination) => {
+      if (code === 0) resolve()
+      else reject(new Error(`plannotator-tui exited: ${termination ?? code}`))
+    })
+  })
+}
+
+export function createReviewCommand(context, options = {}) {
+  const binary = options.binary ?? context.options.binary ?? "plannotator-tui"
+  const runInteractive = options.interactive ?? interactive
+  let active
+  let disposed = false
+  const notice = (message, variant = "info") => context.ui.toast.show({
+    title: "Annotate", message, variant, duration: variant === "error" ? 15000 : 5000,
+  })
+
+  async function run(input = "") {
+    if (disposed) return
+    if (active) return notice("已有批注正在进行。")
+    // Capture before the first await: changing tabs must never redirect a review.
+    const route = context.ui.router.current()
+    if (route.type !== "session") return notice("请先打开一个会话。")
+    const sessionID = route.sessionID
+    const title = context.data.session.get(sessionID)?.title ?? sessionID
+    const controller = new AbortController()
+    active = controller
+    let directory
+    let keepDraft = false
+    try {
+      // The UI cache contains only a recent page; a long tool run can push the last
+      // completed reply out of it. Read the session-scoped history, newest first.
+      const target = input.trim()
+      const source = target
+        ? await documentSource(target, context.client, sessionID, controller.signal)
+        : await latestReply(context.client, sessionID, controller.signal)
+      if (controller.signal.aborted) return
+      if (!source) return notice("当前会话还没有已完成的助手回复。")
+
+      directory = await mkdtemp(path.join(options.tempRoot ?? os.tmpdir(), "opencode-annotate-"))
+      keepDraft = true
+      const snapshot = source.snapshot ?? "last-reply.md"
+      const file = path.join(directory, snapshot)
+      const data = path.join(directory, "data")
+      const promptID = `msg_${randomUUID().replaceAll("-", "")}`
+      await mkdir(data, { mode: 0o700 })
+      await mkdir(path.dirname(file), { recursive: true, mode: 0o700 })
+      await writeFile(file, source.text, { mode: 0o600 })
+      await writeFile(path.join(directory, "review.json"), JSON.stringify({
+        sessionID, messageID: source.id, filePath: source.filePath,
+        sourceHash: source.sourceHash, snapshot, promptID, title,
+      }, null, 2), { mode: 0o600 })
+
+      // Use a fresh store per invocation, and disable any inherited pane delivery.
+      // The OpenCode confirmation is the sole authority for sending feedback.
+      const env = Object.fromEntries(Object.entries(process.env).filter(([key]) =>
+        !key.startsWith("HERDR_") && !key.startsWith("PLANNOTATOR_TUI_"),
+      ))
+      Object.assign(env, {
+        PLANNOTATOR_DATA_DIR: data,
+        PLANNOTATOR_FEEDBACK_HISTORY: "0",
+        PLANNOTATOR_TUI_THEME: context.themeMode === "light" ? "light" : "dark",
+      })
+      context.ui.dialog.clear()
+      context.renderer.suspend()
+      try {
+        context.renderer.currentRenderBuffer.clear()
+        await runInteractive({ binary, file, cwd: directory, env, signal: controller.signal })
+      } finally {
+        context.renderer.currentRenderBuffer.clear()
+        context.renderer.resume()
+        context.renderer.requestRender()
+      }
+      if (controller.signal.aborted) return
+      const { stdout } = await execute(binary, ["--export", file], {
+        cwd: directory, env, signal: controller.signal, timeout: 15000, maxBuffer: 8 * 1024 * 1024,
+      })
+      const feedback = stdout.trim()
+      const archived = await archivedNotes(data)
+      const retainedArchive = archived ? `\n${archived} 条归档批注保留在 ${directory}。` : ""
+      // Upstream 0.9.4 emits this sentinel rather than empty stdout.
+      if (!feedback || feedback === "No annotations.") {
+        keepDraft = archived > 0
+        return notice(archived ? `没有待发送的批注。${retainedArchive}` : "没有批注，已返回会话。", archived ? "warning" : "info")
+      }
+      if (!feedback.startsWith("# Annotations on ")) throw new Error("无法识别 TUI 的批注导出格式。")
+      const subject = source.filePath
+        ? `以下是我对文档 ${JSON.stringify(source.filePath)} 的批注，请按反馈处理该文件。\n批注基于打开时的文档快照（SHA-256：${source.sourceHash}）；修改前请重新读取原文件并核对引用。`
+        : `以下是我对你回复 ${source.id} 的批注，请按反馈处理。`
+      const text = `${subject}\n\n${feedback}`
+      const feedbackPath = path.join(directory, "feedback.md")
+      await writeFile(feedbackPath, text, { mode: 0o600 })
+      const count = (feedback.match(/^## Annotation /gm) ?? []).length
+      const confirmed = await context.ui.dialog.confirm({
+        title: "发送批注？",
+        message: `${source.filePath ? `文档：${source.filePath}\n` : ""}将 ${count} 条批注发送到「${title}」，并让助手继续处理？`,
+        label: { confirm: "发送并继续", cancel: "取消" },
+      })
+      if (controller.signal.aborted) return
+      if (confirmed !== true) {
+        keepDraft = archived > 0
+        return notice(`已取消发送。${retainedArchive}`)
+      }
+      await context.client.session.prompt({
+        sessionID, id: promptID, text, delivery: "queue", resume: true,
+      })
+      keepDraft = archived > 0
+      notice(`已发送 ${count} 条批注。${retainedArchive}`, "success")
+    } catch (error) {
+      if (!disposed) {
+        const detail = error?.code === "ENOENT"
+          ? "找不到 plannotator-tui；请检查安装和 PATH。"
+          : error instanceof Error ? error.message : String(error)
+        const recovery = keepDraft && directory
+          ? `\n草稿保留在 ${directory}；若已导出，反馈文件为 feedback.md。`
+          : ""
+        notice(`${detail}${recovery}`, "error")
+      }
+    } finally {
+      if (directory && !keepDraft) {
+        await rm(directory, { recursive: true, force: true }).catch(() => {})
+      }
+      active = undefined
+    }
+  }
+
+  return {
+    run,
+    dispose() {
+      disposed = true
+      active?.abort()
+    },
+  }
+}

package/tui.ts

@@ -0,0 +1,32 @@
+import { Plugin } from "@opencode/plugin/tui"
+import { createReviewCommand } from "./review.mjs"
+
+export default Plugin.define({
+  id: "opencode-plannotator-tui",
+  setup(context) {
+    const review = createReviewCommand(context)
+    // 2.0.22's keymap.layer needs the mounted provider; newer hosts also allow setup().
+    const unmount = context.ui.slot({
+      append: "app",
+      render() {
+        context.keymap.layer(() => ({
+          mode: "global",
+          commands: [{
+            id: "opencode-plannotator-tui.annotate",
+            title: "Annotate reply or document (TUI)",
+            description: "批注回复或文档；可填写文件路径，按 q 返回后确认发送",
+            group: "Plannotator",
+            palette: true,
+            slash: { name: "annotate", aliases: ["annotate-last"], arguments: true },
+            run: review.run,
+          }],
+        }))
+        return null
+      },
+    })
+    return () => {
+      review.dispose()
+      unmount()
+    }
+  },
+})