opencode-bark-notify 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rohit
+
+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

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# opencode-bark-notify
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Bark push notifications for [OpenCode](https://opencode.ai) sessions: one push when a task finishes, fails, or needs approval, with the session title, a deep link back to it, and no duplicates.
+
+## Requirements
+
+- [Bark](https://github.com/Finb/Bark) on your iPhone or iPad
+- Your Bark device key from the app
+- OpenCode V2
+
+## Install
+
+```sh
+opencode plugin add opencode-bark-notify
+```
+
+Then configure it in `opencode.json(c)`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "opencode-bark-notify",
+      "options": {
+        "barkKey": "YOUR_DEVICE_KEY",
+        "uiUrl": "https://opencode.example.com",
+      },
+    },
+  ],
+}
+```
+
+## Options
+
+| Option    | Required | Default                                    | Description                                                              |
+| --------- | -------- | ------------------------------------------ | ------------------------------------------------------------------------ |
+| `barkKey` | yes      | —                                          | Bark device key. Without it the plugin logs a warning and sends nothing. |
+| `barkUrl` | no       | `https://api.day.app`                      | Base URL of a Bark server. Trailing slashes are stripped.                |
+| `group`   | no       | `opencode`                                 | Bark notification group.                                                 |
+| `uiUrl`   | no       | —                                          | Base URL of the OpenCode web UI, used to build per-session deep links.   |
+| `icon`    | no       | `https://opencode.ai/favicon-96x96-v3.png` | Icon URL shown by Bark. Set to `""` to send no icon.                     |
+| `sound`   | no       | `tiptoes`                                  | Bark/iOS sound name. Set to `""` to send no sound.                       |
+
+Leave `uiUrl` unset to omit the tap action entirely.
+
+## Events
+
+| Event                         | Title         | Subtitle      | Body                          |
+| ----------------------------- | ------------- | ------------- | ----------------------------- |
+| `session.execution.succeeded` | session title | Task finished | `A session is ready.`         |
+| `session.execution.failed`    | session title | Task failed   | `A session execution failed.` |
+| `permission.asked`            | session title | Question      | `action: resource`            |
+
+The title falls back to `OpenCode` when the session has no title or the lookup fails.
+
+Requests go to `POST {barkUrl}/push` with an 8 second timeout.
+
+## Duplicate prevention
+
+OpenCode loads plugins once per project location while the event stream is server-wide, so a naive subscriber sends one push per open project. This plugin avoids that by:
+
+- keeping only events whose session belongs to the plugin instance's own directory;
+- skipping sessions with a `parentID` for completion events, so subagents do not each produce a push (`permission.asked` is exempt);
+- relying on a single explicit config entry, never auto-discovery as well.
+
+## Deep links
+
+Tapping a notification opens the session in the OpenCode web UI:
+
+```text
+https://opencode.example.com/server/<serverKey>/session/<sessionID>
+```
+
+`serverKey` is the base64url encoding of the `uiUrl` origin. Pairing the same OpenCode server through a different URL yields a different key, so the deep link only resolves when your client is paired to the same origin as `uiUrl`.
+
+## Logging
+
+Each send logs one line:
+
+```text
+[opencode-bark] sending ses_abc123 from /home/me/projects/app
+```
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,116 @@
+import { Plugin } from "@opencode/plugin"
+
+type Options = {
+  barkKey?: string
+  barkUrl?: string
+  group?: string
+  uiUrl?: string
+  icon?: string
+  sound?: string
+}
+
+const encodeKey = (value: string) => {
+  const bytes = new TextEncoder().encode(value)
+  const binary = Array.from(bytes, (byte) => String.fromCharCode(byte)).join("")
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
+}
+
+export default Plugin.define({
+  id: "bark-notify",
+  async setup(ctx) {
+    const options = ctx.options as Options
+    const barkKey = options.barkKey
+    const barkUrl = (options.barkUrl || "https://api.day.app").replace(/\/+$/, "")
+    const group = options.group || "opencode"
+    const uiUrl = options.uiUrl
+    const icon = options.icon ?? "https://opencode.ai/favicon-96x96-v3.png"
+    const sound = options.sound ?? "tiptoes"
+
+    let uiOrigin: string | undefined
+    let serverKey: string | undefined
+    if (uiUrl) {
+      try {
+        uiOrigin = new URL(uiUrl).origin
+        serverKey = encodeKey(uiOrigin)
+      } catch {
+        console.warn(`[opencode-bark] invalid uiUrl: ${uiUrl}`)
+      }
+    }
+
+    const sessionUrl = (sessionID: string) => {
+      if (!uiOrigin || !serverKey) return uiUrl
+      return `${uiOrigin}/server/${serverKey}/session/${sessionID}`
+    }
+
+    const send = async (title: string, subtitle: string, body: string, sessionID: string) => {
+      if (!barkKey) {
+        console.warn("[opencode-bark] barkKey is not configured; skipping notification")
+        return
+      }
+
+      const payload: Record<string, string> = {
+        device_key: barkKey,
+        title,
+        subtitle,
+        body,
+        group,
+      }
+      if (icon) payload.icon = icon
+      if (sound) payload.sound = sound
+      const url = sessionUrl(sessionID)
+      if (url) payload.url = url
+      console.log(`[opencode-bark] sending ${sessionID} from ${ctx.location.directory}`)
+
+      const response = await fetch(`${barkUrl}/push`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json; charset=utf-8" },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(8000),
+      })
+      if (!response.ok) console.warn(`[opencode-bark] Bark returned HTTP ${response.status}`)
+    }
+
+    const sessionFor = async (sessionID: string) => {
+      try {
+        return await ctx.session.get({ sessionID })
+      } catch {
+        return undefined
+      }
+    }
+
+    const controller = new AbortController()
+    void (async () => {
+      try {
+        for await (const event of ctx.event.subscribe({
+          types: ["session.execution.succeeded", "session.execution.failed", "permission.asked"],
+          signal: controller.signal,
+        })) {
+          try {
+            if (event.location && event.location.directory !== ctx.location.directory) continue
+
+            const session = await sessionFor(event.data.sessionID)
+            if (!session) continue
+            if (session.location.directory !== ctx.location.directory) continue
+            if (session.parentID && event.type !== "permission.asked") continue
+            const title = session.title || "OpenCode"
+
+            if (event.type === "session.execution.succeeded") {
+              await send(title, "Task finished", "A session is ready.", event.data.sessionID)
+            } else if (event.type === "session.execution.failed") {
+              await send(title, "Task failed", "A session execution failed.", event.data.sessionID)
+            } else if (event.type === "permission.asked") {
+              const body = [event.data.action, ...event.data.resources].filter(Boolean).join(": ")
+              await send(title, "Question", body || "Permission requested", event.data.sessionID)
+            }
+          } catch (error) {
+            console.warn("[opencode-bark] notification failed", error)
+          }
+        }
+      } catch (error) {
+        if (!controller.signal.aborted) console.warn("[opencode-bark] event subscription failed", error)
+      }
+    })()
+
+    return () => controller.abort()
+  },
+})

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "opencode-bark-notify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Bark push notifications for OpenCode sessions, with session deep links and duplicate-free delivery.",
+  "homepage": "https://github.com/rohitagre/opencode-bark-notify#readme",
+  "bugs": {
+    "url": "https://github.com/rohitagre/opencode-bark-notify/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rohitagre/opencode-bark-notify.git"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "README.md"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "bark",
+    "notifications",
+    "push",
+    "ios"
+  ],
+  "author": "Rohit Agre",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@opencode/plugin": "latest"
+  }
+}