opencode-plannotator-tui 0.3.0 → 0.4.2

package/browser/worker.mjs

@@ -0,0 +1,105 @@
+import { HOST, safeUrl, validateReview } from "./protocol.mjs"
+
+const pageKey = async url => [...new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(url)))].map(v => v.toString(16).padStart(2, "0")).join("")
+let writes = Promise.resolve()
+const serial = fn => { const next = writes.then(fn); writes = next.catch(() => {}); return next }
+async function activate(tab) {
+  if (!tab?.id || !/^(https?|file):/.test(tab.url || "")) throw new Error("Open an ordinary webpage or authorized local HTML")
+  await chrome.scripting.executeScript({ target: { tabId: tab.id }, files: ["inspector.js", "capture.js"] })
+  await chrome.storage.session.set({ [`tab:${tab.id}`]: { page: { url: safeUrl(tab.url), title: tab.title || "Page" }, anchor: null } })
+}
+chrome.action.onClicked.addListener(tab => {
+  // open() must retain the browser's action user gesture, before asynchronous injection.
+  chrome.sidePanel.open({ tabId: tab.id }).catch(console.error)
+  activate(tab).catch(async error => { await chrome.storage.session.set({ [`tab:${tab.id}`]: { error: error.message } }) })
+})
+async function current() {
+  const [tab] = await chrome.tabs.query({ active: true, lastFocusedWindow: true })
+  if (!tab) throw new Error("No active page")
+  const state = (await chrome.storage.session.get(`tab:${tab.id}`))[`tab:${tab.id}`]
+  if (!state?.page) throw new Error(state?.error || "Click the extension icon on this page to grant access")
+  const hash = await pageKey(state.page.url)
+  const storage = await chrome.storage.local.get(null)
+  const notes = Object.entries(storage).filter(([key, value]) => key.startsWith(`note:${hash}:`) && !value.deleted).map(([, value]) => value).sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id))
+  let anchorStates = notes.map(() => "unavailable")
+  try { anchorStates = (await chrome.tabs.sendMessage(tab.id, { action: "locate", anchors: notes.map(note => note.anchor) })).states } catch { /* visibly unavailable while navigating */ }
+  return { tabID: tab.id, ...state, notes, anchorStates, hash }
+}
+async function handle(message, sender) {
+  if (message.action === "capture") {
+    if (!sender.tab || !sender.url || new URL(message.page.url).origin !== new URL(sender.url).origin) throw new Error("Invalid page source")
+    const key = `tab:${sender.tab.id}`
+    const previous = (await chrome.storage.session.get(key))[key] || {}
+    await chrome.storage.session.set({ [key]: { ...previous, page: { url: safeUrl(message.page.url), title: String(message.page.title).slice(0, 500) }, picking: !!message.picking,
+      ...(!message.modeOnly ? { anchor: message.anchor, error: message.error } : {}) } })
+    return {}
+  }
+  if (sender.url && !sender.url.startsWith(chrome.runtime.getURL(""))) throw new Error("Only the extension panel can manage feedback")
+  if (message.action === "current") return current()
+  if (message.action === "targets") return chrome.runtime.sendNativeMessage(HOST, { action: "targets" })
+  if (message.action === "connection") {
+    const result = await chrome.runtime.sendNativeMessage(HOST, { action: "targets" })
+    if (!result.ok) throw new Error(result.error)
+    const { paired } = await chrome.storage.local.get("paired")
+    const target = paired ? result.targets.find(target => target.id === paired.id) : result.targets.length === 1 ? result.targets[0] : null
+    return { targets: result.targets, target: target || null, stale: !!paired && !target }
+  }
+  if (message.action === "pair") {
+    const result = await chrome.runtime.sendNativeMessage(HOST, { action: "info", targetID: message.target.id })
+    if (!result.ok) throw new Error(result.error)
+    await chrome.storage.local.set({ paired: result.target }); return { target: result.target }
+  }
+  if (message.action === "pairing") return { target: (await chrome.storage.local.get("paired")).paired || null }
+  if (message.action === "unpair") { await chrome.storage.local.remove("paired"); return {} }
+  const state = await current()
+  if (message.url && message.url !== state.page.url) throw new Error("The active page changed; retry on the original page")
+  if (message.action === "pick") return chrome.tabs.sendMessage(state.tabID, { action: "pick" })
+  if (message.action === "save" || message.action === "delete") return serial(async () => {
+    const key = `note:${state.hash}:${message.note.id}`
+    const old = (await chrome.storage.local.get(key))[key]
+    if ((old?.revision || 0) !== message.baseRevision) throw new Error("This note changed in another tab; refresh and retry")
+    const note = { ...message.note, page: state.page, revision: (old?.revision || 0) + 1, deleted: message.action === "delete" }
+    validateReview({ version: 1, page: state.page, annotations: [note] })
+    if (!old && state.notes.length >= 200) throw new Error("This page has 200 notes; export and remove some first")
+    await chrome.storage.local.set({ [key]: note }); return { note }
+  })
+  if (message.action === "markers") return chrome.tabs.sendMessage(state.tabID, { action: "markers", notes: state.notes.map(note => ({ anchor: note.anchor })) })
+  if (message.action === "send") return serial(async () => {
+    const latest = await current()
+    if (latest.page.url !== state.page.url) throw new Error("The active page changed; return to the original page to send")
+    if (typeof message.targetID !== "string" || !message.targetID) throw new Error("Choose a destination session before sending")
+    let { paired } = await chrome.storage.local.get("paired")
+    if (paired && paired.id !== message.targetID) throw new Error("The destination changed in another panel; choose it again")
+    if (!paired) {
+      // A sole target is only preselected. The user's Send click authorizes this binding.
+      const result = await chrome.runtime.sendNativeMessage(HOST, { action: "info", targetID: message.targetID })
+      if (!result.ok) throw new Error(result.error)
+      paired = result.target
+      await chrome.storage.local.set({ paired })
+    }
+    const outboxKey = `outbox:${state.hash}`
+    let batch = (await chrome.storage.local.get(outboxKey))[outboxKey]
+    if (batch && batch.targetID !== paired.id) throw new Error("An unsent batch belongs to the previous pairing; restore that pairing or export your notes")
+    if (!batch) {
+      const pending = latest.notes.filter(note => note.sentRevision !== note.revision)
+      if (!pending.length) throw new Error("No new feedback to send")
+      const review = validateReview({ version: 1, page: state.page, annotations: pending })
+      batch = { action: "send", batchID: crypto.randomUUID(), targetID: paired.id, review }
+      await chrome.storage.local.set({ [outboxKey]: batch })
+    }
+    const response = await chrome.runtime.sendNativeMessage(HOST, batch)
+    if (!response.ok) throw new Error(response.error)
+    for (const sent of batch.review.annotations) {
+      const key = `note:${state.hash}:${sent.id}`
+      const note = (await chrome.storage.local.get(key))[key]
+      if (note && note.revision === sent.revision) await chrome.storage.local.set({ [key]: { ...note, sentRevision: sent.revision } })
+    }
+    await chrome.storage.local.remove(outboxKey)
+    return response
+  })
+  throw new Error("Unknown annotation action")
+}
+chrome.runtime.onMessage.addListener((message, sender, respond) => {
+  handle(message, sender).then(result => respond({ ok: true, ...result }), error => respond({ ok: false, error: error.message }))
+  return true
+})

package/package.json

@@ -1,14 +1,17 @@
 {
   "name": "opencode-plannotator-tui",
-  "version": "0.3.0",
-  "description": "Unofficial OpenCode adapter for Plannotator TUI: annotate replies and documents without leaving your terminal.",
+  "version": "0.4.2",
+  "description": "Unofficial OpenCode plugin: annotate replies, documents and webpages, then send the feedback to the originating session.",
   "license": "MIT",
   "type": "module",
   "exports": {
     "./tui": "./tui.ts"
   },
   "scripts": {
-    "test": "node --test review.test.mjs",
+    "test": "node --test review.test.mjs bridge/*.test.mjs",
+    "test:browser": "node tests/browser.mjs",
+    "install:bridge": "node scripts/install-bridge.mjs",
+    "install:plugin": "node scripts/install-plugin.mjs",
     "test:smoke": "python3 smoke.py",
     "check": "node --check review.mjs && npm test && npm pack --dry-run",
     "prepublishOnly": "npm run check"
@@ -16,6 +19,15 @@
   "files": [
     "tui.ts",
     "review.mjs",
+    "targets.mjs",
+    "web-review.mjs",
+    "browser",
+    "bridge/native-host.mjs",
+    "bridge/receiver.mjs",
+    "bridge/wire.mjs",
+    "scripts/install-bridge.mjs",
+    "scripts/install-plugin.mjs",
+    "scripts/migrate-page-context.mjs",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"

package/review.mjs

@@ -4,6 +4,8 @@ import { mkdtemp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/
 import os from "node:os"
 import path from "node:path"
 import { promisify } from "node:util"
+import { createWebReview } from "./web-review.mjs"
+import { wantsBrowser } from "./targets.mjs"
 
 const execute = promisify(execFile)
 const documentExtensions = new Set([".md", ".mdx", ".markdown", ".txt"])
@@ -111,6 +113,7 @@ async function interactive({ binary, file, cwd, env, signal }) {
 }
 
 export function createReviewCommand(context, options = {}) {
+  const web = createWebReview(context, options.web)
   const binary = options.binary ?? context.options.binary ?? "plannotator-tui"
   const runInteractive = options.interactive ?? interactive
   let active
@@ -135,6 +138,10 @@ export function createReviewCommand(context, options = {}) {
       // 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()
+      if (wantsBrowser(target)) {
+        await web.run(target, sessionID)
+        return
+      }
       const numeric = target !== "" && /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i.test(target)
       const position = numeric ? Number(target) : 1
       if (numeric && (!/^\d+$/.test(target) || !Number.isSafeInteger(position) || position < 1)) {
@@ -173,13 +180,12 @@ export function createReviewCommand(context, options = {}) {
         PLANNOTATOR_TUI_THEME: context.themeMode === "light" ? "light" : "dark",
       })
       context.ui.dialog.clear()
-      context.renderer.suspend()
+      // OpenCode 2.1.1+ suspends and resumes asynchronously; resume forces a full repaint.
+      await 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()
+        await context.renderer.resume()
         context.renderer.requestRender()
       }
       if (controller.signal.aborted) return
@@ -240,6 +246,7 @@ export function createReviewCommand(context, options = {}) {
     dispose() {
       disposed = true
       active?.abort()
+      return web.dispose()
     },
   }
 }

package/scripts/install-bridge.mjs

@@ -0,0 +1,27 @@
+import { readFile, mkdir, writeFile, chmod, copyFile } from "node:fs/promises"
+import { createHash } from "node:crypto"
+import { fileURLToPath } from "node:url"
+import os from "node:os"
+import path from "node:path"
+import { registryRoot } from "../bridge/receiver.mjs"
+const root = fileURLToPath(new URL("../", import.meta.url))
+export async function installBridge({ profileDirectory = path.join(os.homedir(), "Library/Application Support/Google/Chrome"), installRoot = path.join(os.homedir(), ".local/share/opencode-annotate/native"), node = process.execPath, targetsDirectory = registryRoot() } = {}) {
+  const manifest = JSON.parse(await readFile(path.join(root, "browser/manifest.json"), "utf8"))
+  const extensionID = [...createHash("sha256").update(Buffer.from(manifest.key, "base64")).digest().subarray(0, 16)].flatMap(byte => [String.fromCharCode(97 + (byte >> 4)), String.fromCharCode(97 + (byte & 15))]).join("")
+  await mkdir(installRoot, { recursive: true, mode: 0o700 })
+  const launcher = path.join(installRoot, "host"), config = path.join(installRoot, "config.json")
+  const quote = value => `'${value.replaceAll("'", "'\\''")}'`
+  await writeFile(config, JSON.stringify({ extensionID, targetsDirectory }), { mode: 0o600 })
+  await writeFile(launcher, `#!/bin/sh\nexec ${quote(node)} ${quote(path.join(root, "bridge/native-host.mjs"))} ${quote(config)} "$@"\n`, { mode: 0o700 })
+  await chmod(launcher, 0o700)
+  const directory = path.join(profileDirectory, "NativeMessagingHosts")
+  await mkdir(directory, { recursive: true })
+  const hostManifest = path.join(directory, "fun.mjshao.annotate.json")
+  try { await copyFile(hostManifest, `${hostManifest}.backup-${Date.now()}`) } catch (error) { if (error.code !== "ENOENT") throw error }
+  await writeFile(hostManifest, JSON.stringify({ name: "fun.mjshao.annotate", description: "Paired OpenCode annotation delivery", path: launcher, type: "stdio", allowed_origins: [`chrome-extension://${extensionID}/`] }, null, 2), { mode: 0o600 })
+  return { extensionID, extensionDirectory: path.join(root, "browser"), hostManifest, launcher }
+}
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  if (process.platform !== "darwin") throw new Error("Local installer currently supports macOS only")
+  console.log(JSON.stringify(await installBridge(), null, 2))
+}

package/scripts/install-plugin.mjs

@@ -0,0 +1,34 @@
+import { readFile, writeFile, mkdir, realpath, rename, stat } from "node:fs/promises"
+import { fileURLToPath } from "node:url"
+import { createHash } from "node:crypto"
+import path from "node:path"
+import os from "node:os"
+
+const root = fileURLToPath(new URL("../", import.meta.url)).replace(/\/$/, "")
+const source = entry => typeof entry === "string" ? entry : entry.package
+const oldEntry = entry => source(entry) === "opencode-plannotator-tui" || source(entry)?.startsWith("opencode-plannotator-tui@")
+const configPath = path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "opencode/cli.json")
+const filename = await realpath(configPath)
+const bytes = await readFile(filename, "utf8"), config = JSON.parse(bytes)
+let backup
+if (process.argv[2] === "--undo") {
+  if (!process.argv[3]) throw new Error("Supply the cli-before.json backup")
+  const previous = JSON.parse(await readFile(process.argv[3], "utf8"))
+  const old = previous.plugins.filter(oldEntry)
+  if (old.length !== 1 || config.plugins.filter(entry => source(entry) === root).length !== 1) throw new Error("Ambiguous plugin rollback; no changes made")
+  config.plugins = config.plugins.map(entry => source(entry) === root ? old[0] : entry)
+} else {
+  const candidates = config.plugins.filter(oldEntry)
+  if (config.plugins.some(entry => source(entry) === root)) { console.log("Local plugin is already configured."); process.exit(0) }
+  if (candidates.length !== 1) throw new Error("Expected exactly one existing Plannotator TUI entry; no changes made")
+  const backupDir = path.join(root, ".local/migration")
+  await mkdir(backupDir, { recursive: true, mode: 0o700 })
+  backup = path.join(backupDir, `cli-before-${Date.now()}.json`)
+  await writeFile(backup, bytes, { mode: 0o600, flag: "wx" })
+  config.plugins = config.plugins.map(entry => oldEntry(entry) ? typeof entry === "string" ? root : { ...entry, package: root } : entry)
+}
+if (await readFile(filename, "utf8") !== bytes) throw new Error("CLI configuration changed concurrently; retry")
+const output = `${JSON.stringify(config, null, 2)}\n`, temporary = `${filename}.annotate-${process.pid}`
+await writeFile(temporary, output, { mode: (await stat(filename)).mode & 0o777, flag: "wx" })
+await rename(temporary, filename)
+console.log(JSON.stringify({ configured: root, config: filename, backup, installedSha256: createHash("sha256").update(output).digest("hex"), next: "Reopen the OpenCode terminal client. Do not restart the shared service." }, null, 2))

package/scripts/migrate-page-context.mjs

@@ -0,0 +1,31 @@
+import { createHash } from "node:crypto"
+import { readFile, writeFile } from "node:fs/promises"
+import { fileURLToPath } from "node:url"
+import { safeUrl, validateReview } from "../browser/protocol.mjs"
+
+export function migratePageContext(storage) {
+  const result = {}
+  for (const [key, page] of Object.entries(storage)) {
+    if (!key.startsWith("page:")) continue
+    if (!page?.page?.url || !Array.isArray(page.notes)) throw new Error(`Unrecognized old draft: ${key}`)
+    const source = { url: safeUrl(page.page.url), title: page.page.title || "Page" }
+    const hash = createHash("sha256").update(source.url).digest("hex")
+    for (const old of page.notes) {
+      const note = { id: old.id, revision: 1, kind: old.kind, comment: old.body,
+        createdAt: old.createdAt, updatedAt: old.updatedAt || old.createdAt,
+        anchor: { ...old.target, element: old.target.label || old.target.role || old.target.type,
+          styles: old.target.styles || "", accessibility: old.target.accessibility || "", fullPath: old.target.selector }, page: source }
+      validateReview({ version: 1, page: source, annotations: [note] })
+      const destination = `note:${hash}:${note.id}`
+      if (result[destination]) throw new Error("Duplicate note during migration")
+      result[destination] = note
+    }
+  }
+  return result
+}
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  if (!process.argv[2] || !process.argv[3]) throw new Error("Usage: migrate-page-context.mjs input.json output.json")
+  const records = migratePageContext(JSON.parse(await readFile(process.argv[2], "utf8")))
+  await writeFile(process.argv[3], JSON.stringify(records, null, 2), { mode: 0o600, flag: "wx" })
+  console.log(`Prepared ${Object.keys(records).length} notes for import; source backup unchanged.`)
+}

package/targets.mjs

@@ -0,0 +1,32 @@
+import { stat } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import { fileURLToPath, pathToFileURL } from "node:url"
+
+const unquote = input => {
+  const value = input.trim()
+  return ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) ? value.slice(1, -1) : value
+}
+export const wantsBrowser = input => /^web(?: off)?$/.test(unquote(input)) || /\.html?$/i.test(unquote(input)) || /^[a-z][a-z0-9+.-]*:/i.test(unquote(input))
+
+export async function browserTarget(input, directory) {
+  let value = unquote(input)
+  if (value === "web") return { type: "browser" }
+  if (/^[a-z][a-z0-9+.-]*:/i.test(value)) {
+    const url = new URL(value)
+    if (["http:", "https:"].includes(url.protocol)) {
+      if (url.username || url.password) throw new Error("Remove credentials from the page URL.")
+      if (/^chrome(webstore)?\.google\.com$/.test(url.hostname) || /\.pdf$/i.test(url.pathname)) throw new Error("This page cannot be annotated.")
+      return { type: "browser", url: url.href }
+    }
+    if (url.protocol !== "file:") throw new Error("Use an http, https, or local HTML target.")
+    value = fileURLToPath(url)
+    if (!/\.html?$/i.test(value)) throw new Error("File URLs must point to an HTML document.")
+  }
+  if (!/\.html?$/i.test(value)) return null
+  if (value.startsWith("~/")) value = path.join(os.homedir(), value.slice(2))
+  if (!path.isAbsolute(value) && !directory) throw new Error("Can't determine the session working directory.")
+  const file = path.resolve(directory || ".", value)
+  if (!(await stat(file)).isFile()) throw new Error("The HTML target is not a file.")
+  return { type: "browser", url: pathToFileURL(file).href }
+}

package/tui.ts

@@ -2,7 +2,7 @@ import { Plugin } from "@opencode/plugin/tui"
 import { createReviewCommand } from "./review.mjs"
 
 export default Plugin.define({
-  id: "opencode-plannotator-tui",
+  id: "opencode-annotate",
   setup(context) {
     const review = createReviewCommand(context)
     // 2.0.22's keymap.layer needs the mounted provider; newer hosts also allow setup().
@@ -12,18 +12,18 @@ export default Plugin.define({
         context.keymap.layer(() => ({
           mode: "global",
           commands: [{
-            id: "opencode-plannotator-tui.annotate",
-            title: "Annotate reply or document (TUI)",
-            description: "Annotate a reply (1 = latest, 2 = previous) or a file; press q, then confirm to send",
-            group: "Plannotator",
+            id: "opencode-annotate.annotate",
+            title: "Annotate reply, document, or webpage",
+            description: "Text defaults to TUI; explicit HTML, URL or web pairs browser review",
+            group: "Annotate",
             palette: true,
             slash: { name: "annotate", arguments: true },
             run: review.run,
           }, {
-            id: "opencode-plannotator-tui.annotate-last",
+            id: "opencode-annotate.annotate-last",
             title: "Annotate last reply (TUI)",
             description: "Annotate the latest completed reply; press q, then confirm to send",
-            group: "Plannotator",
+            group: "Annotate",
             palette: true,
             // Keep slash submission with a trailing space local to the command.
             // Any supplied argument is deliberately ignored: this always means latest.

package/web-review.mjs

@@ -0,0 +1,36 @@
+import { execFile } from "node:child_process"
+import { promisify } from "node:util"
+import { browserTarget } from "./targets.mjs"
+import { createReceiver } from "./bridge/receiver.mjs"
+
+const execute = promisify(execFile)
+export function createWebReview(context, options = {}) {
+  const receivers = new Map()
+  let disposed = false
+  return {
+    async run(input, sessionID) {
+      if (input.trim() === "web off") {
+        await receivers.get(sessionID)?.close(); receivers.delete(sessionID)
+        context.ui.toast.show({ title: "Annotate web", message: "Browser pairing revoked for this session." })
+        return true
+      }
+      const session = await context.client.session.get({ sessionID })
+      const target = await browserTarget(input, session.location?.directory)
+      if (!target) return false
+      if (disposed) throw new Error("Annotation plugin is closed")
+      if (!receivers.has(sessionID)) {
+        const receiver = await createReceiver({ sessionID, title: session.title || sessionID, directory: session.location?.directory || "", client: context.client, ...options.receiver })
+        if (disposed) { await receiver.close(); return true }
+        receivers.set(sessionID, receiver)
+      }
+      if (target.url) {
+        if (options.open) await options.open(target.url)
+        else if (process.platform === "darwin") await execute("open", ["-a", "Google Chrome", target.url])
+        else throw new Error("Browser review currently requires macOS")
+      }
+      context.ui.toast.show({ title: "Annotate web", message: `Ready for browser pairing: ${session.title || sessionID}. Open the extension and select this session.`, duration: 10000 })
+      return true
+    },
+    async dispose() { disposed = true; await Promise.all([...receivers.values()].map(receiver => receiver.close())); receivers.clear() },
+  }
+}