@goodnesshq/opencode-notification 0.1.0

package/.opencode/notify-init.mjs

@@ -0,0 +1,374 @@
+#!/usr/bin/env node
+import { readFile, writeFile, mkdir, copyFile, stat } from "node:fs/promises";
+import { join, basename, dirname } from "node:path";
+import { homedir } from "node:os";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+
+const REPO_CONFIG_PATH = ".opencode/oc-notify.json";
+const GLOBAL_CONFIG_PATH = join(
+  homedir(),
+  ".config",
+  "opencode",
+  "oc-notify.json",
+);
+const SCRIPT_PATH = fileURLToPath(import.meta.url);
+const SCRIPT_DIR = dirname(SCRIPT_PATH);
+const SCHEMA_SOURCE_PATH = join(SCRIPT_DIR, "oc-notify.schema.json");
+
+const DEFAULTS = {
+  enabled: true,
+  title: "",
+  tier: "standard",
+  detailLevel: "full",
+  responseComplete: {
+    enabled: true,
+    trigger: "message.updated",
+  },
+  channels: {
+    mac: {
+      enabled: true,
+      method: "auto",
+    },
+    ntfy: {
+      enabled: true,
+      server: "https://ntfy.sh",
+      topic: "oc-goodness-attn-1407537",
+    },
+  },
+  overrides: {
+    includeGroups: [],
+    excludeGroups: [],
+  },
+};
+
+const GROUPS_BASIC = [
+  "action_required",
+  "failures",
+  "change_summary",
+  "session_lifecycle",
+  "responses",
+  "vcs_worktree",
+  "todos",
+];
+
+const GROUPS_ADVANCED = [
+  "files",
+  "pty",
+  "commands_tools",
+  "message_lifecycle",
+  "message_parts",
+  "system",
+  "lsp",
+  "tui",
+];
+
+async function commandExists(command) {
+  try {
+    const { execSync } = await import("node:child_process");
+    execSync(`command -v ${command}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function yesNo(value, fallback) {
+  if (!value) return fallback;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "y" || normalized === "yes") return true;
+  if (normalized === "n" || normalized === "no") return false;
+  return fallback;
+}
+
+function parseList(input, allowed) {
+  if (!input) return [];
+  const items = input
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+  if (!allowed) return items;
+  return items.filter((item) => allowed.includes(item));
+}
+
+async function readJson(path) {
+  try {
+    const content = await readFile(path, "utf8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+async function writeJson(path, data) {
+  const content = JSON.stringify(data, null, 2) + "\n";
+  await writeFile(path, content, "utf8");
+}
+
+async function fileExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function ensureOpencodeDir(cwd) {
+  await mkdir(join(cwd, ".opencode"), { recursive: true });
+}
+
+async function copySchema(cwd) {
+  try {
+    await copyFile(
+      SCHEMA_SOURCE_PATH,
+      join(cwd, ".opencode", "oc-notify.schema.json"),
+    );
+  } catch {}
+}
+
+
+async function sendTestNotification(config, repoName) {
+  const title = config.title || `${repoName}@test`;
+  const subtitle = "OpenCode Notify";
+  const message = "Test notification";
+  const useTerminalNotifier =
+    config.channels.mac.enabled && (await commandExists("terminal-notifier"));
+
+  if (config.channels.mac.enabled) {
+    try {
+      const { execFileSync } = await import("node:child_process");
+      if (useTerminalNotifier && config.channels.mac.method !== "applescript") {
+        execFileSync("terminal-notifier", [
+          "-title",
+          title,
+          "-message",
+          message,
+          "-subtitle",
+          subtitle,
+        ]);
+      } else {
+        const script = [
+          "on run argv",
+          "set theMessage to item 1 of argv",
+          "set theTitle to item 2 of argv",
+          "set theSubtitle to item 3 of argv",
+          'if theSubtitle is "" then',
+          "  display notification theMessage with title theTitle",
+          "else",
+          "  display notification theMessage with title theTitle subtitle theSubtitle",
+          "end if",
+          "end run",
+        ].join("\n");
+        execFileSync("osascript", ["-e", script, message, title, subtitle]);
+      }
+    } catch {
+      console.log("Test macOS notification failed.");
+    }
+  }
+
+  if (config.channels.ntfy.enabled) {
+    try {
+      const { execFileSync } = await import("node:child_process");
+      const server = config.channels.ntfy.server.replace(/\/$/, "");
+      const url = `${server}/${config.channels.ntfy.topic}`;
+      execFileSync("curl", [
+        "-sS",
+        "-H",
+        `Title: ${title}`,
+        "-H",
+        "Priority: 3",
+        "-H",
+        "Tags: opencode,info",
+        "-d",
+        message,
+        url,
+      ]);
+    } catch {
+      console.log("Test ntfy notification failed.");
+    }
+  }
+}
+
+async function main() {
+  const cwd = process.cwd();
+  const repoName = basename(cwd);
+  const args = process.argv.slice(2);
+
+  if (args.includes("--install")) {
+    await ensureOpencodeDir(cwd);
+    await copyFile(SCRIPT_PATH, join(cwd, ".opencode", "notify-init.mjs"));
+    await copySchema(cwd);
+    console.log("Installed .opencode/notify-init.mjs and schema in this repo.");
+    return;
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+  console.log("OpenCode Notify — per-repo setup\n");
+
+  const enableInput = await rl.question(
+    "Enable notifications for this repo? (Y/n) [Y] ",
+  );
+  const enabled = yesNo(enableInput, true);
+  if (!enabled) {
+    await rl.close();
+    return;
+  }
+
+  const titleInput = await rl.question(
+    `Notification title (blank = "${repoName}@<branch>"): `,
+  );
+  const title = titleInput.trim();
+
+  console.log(
+    "\nSelect a tier:\n  1) Minimal\n  2) Standard\n  3) Verbose\n  4) Custom",
+  );
+  const tierInput = await rl.question("> [2] ");
+  const tier =
+    tierInput.trim() === "1"
+      ? "minimal"
+      : tierInput.trim() === "3"
+        ? "verbose"
+        : tierInput.trim() === "4"
+          ? "custom"
+          : "standard";
+
+  console.log(
+    "\nResponse-complete trigger:\n  1) session.idle (coarse, low noise)\n  2) message.updated (precise)\n  3) message.part.updated (very precise, more noise)",
+  );
+  const triggerInput = await rl.question("> [2] ");
+  const trigger =
+    triggerInput.trim() === "1"
+      ? "session.idle"
+      : triggerInput.trim() === "3"
+        ? "message.part.updated"
+        : "message.updated";
+
+  const macInput = await rl.question(
+    "\nEnable macOS Notification Center? (Y/n) [Y] ",
+  );
+  const macEnabled = yesNo(macInput, true);
+
+  const ntfyInput = await rl.question("Enable ntfy notifications? (Y/n) [Y] ");
+  const ntfyEnabled = yesNo(ntfyInput, true);
+
+  let globalConfig = await readJson(GLOBAL_CONFIG_PATH);
+  if (!globalConfig) globalConfig = {};
+  if (!globalConfig.ntfy) globalConfig.ntfy = {};
+
+  if (ntfyEnabled) {
+    const serverInput = await rl.question(
+      `ntfy server (blank = ${globalConfig.ntfy.server || DEFAULTS.channels.ntfy.server}): `,
+    );
+    const topicInput = await rl.question(
+      `ntfy topic (blank = ${globalConfig.ntfy.topic || DEFAULTS.channels.ntfy.topic}): `,
+    );
+    if (serverInput.trim()) globalConfig.ntfy.server = serverInput.trim();
+    if (topicInput.trim()) globalConfig.ntfy.topic = topicInput.trim();
+  }
+
+  const detailInput = await rl.question(
+    "Detail level (1=full, 2=title-only) [1] ",
+  );
+  const detailLevel = detailInput.trim() === "2" ? "title-only" : "full";
+
+  const adjustGroups = yesNo(
+    await rl.question("\nAdjust event groups? (y/N) [N] "),
+    false,
+  );
+  let includeGroups = [];
+  let excludeGroups = [];
+  if (adjustGroups) {
+    const advanced = yesNo(
+      await rl.question("Show advanced groups? (y/N) [N] "),
+      false,
+    );
+    const allowed = advanced
+      ? GROUPS_BASIC.concat(GROUPS_ADVANCED)
+      : GROUPS_BASIC;
+    console.log(`Available groups: ${allowed.join(", ")}`);
+    const includeInput = await rl.question(
+      "Include groups (comma-separated, blank to skip): ",
+    );
+    const excludeInput = await rl.question(
+      "Exclude groups (comma-separated, blank to skip): ",
+    );
+    includeGroups = parseList(includeInput, allowed);
+    excludeGroups = parseList(excludeInput, allowed);
+  }
+
+  const installTN = yesNo(
+    await rl.question("\nUse terminal-notifier if available? (Y/n) [Y] "),
+    true,
+  );
+
+  if (installTN) {
+    const hasTN = await commandExists("terminal-notifier");
+    const hasBrew = await commandExists("brew");
+    if (!hasTN && hasBrew) {
+      const installNow = yesNo(
+        await rl.question(
+          "terminal-notifier not found. Install with Homebrew now? (y/N) [N] ",
+        ),
+        false,
+      );
+      if (installNow) {
+        try {
+          const { execSync } = await import("node:child_process");
+          execSync("brew install terminal-notifier", { stdio: "inherit" });
+        } catch {
+          console.log("Homebrew install failed. Falling back to AppleScript.");
+        }
+      }
+    }
+  }
+
+  const config = {
+    version: 1,
+    enabled: true,
+    title,
+    tier,
+    detailLevel,
+    responseComplete: {
+      enabled: true,
+      trigger,
+    },
+    channels: {
+      mac: {
+        enabled: macEnabled,
+        method: installTN ? "auto" : "applescript",
+      },
+      ntfy: {
+        enabled: ntfyEnabled,
+        server: globalConfig.ntfy?.server || DEFAULTS.channels.ntfy.server,
+        topic: globalConfig.ntfy?.topic || DEFAULTS.channels.ntfy.topic,
+      },
+    },
+    overrides: {
+      includeGroups,
+      excludeGroups,
+    },
+  };
+
+  const writeInput = await rl.question(
+    "\nWrite config to .opencode/oc-notify.json? (Y/n) [Y] ",
+  );
+  const shouldWrite = yesNo(writeInput, true);
+  if (shouldWrite) {
+    await ensureOpencodeDir(cwd);
+    await writeJson(join(cwd, REPO_CONFIG_PATH), config);
+    await copySchema(cwd);
+  }
+
+  const testInput = await rl.question(
+    "Send a test notification now? (Y/n) [Y] ",
+  );
+  const sendTest = yesNo(testInput, true);
+  if (sendTest) {
+    await sendTestNotification(config, repoName);
+  }
+
+  await rl.close();
+}
+
+await main();

package/.opencode/oc-notify.schema.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "OpenCode Notifications Repo Config",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "enabled": {
+      "type": "boolean"
+    },
+    "title": {
+      "type": "string"
+    },
+    "tier": {
+      "type": "string",
+      "enum": ["minimal", "standard", "verbose", "custom"]
+    },
+    "detailLevel": {
+      "type": "string",
+      "enum": ["full", "title-only"]
+    },
+    "responseComplete": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "trigger": {
+          "type": "string",
+          "enum": ["session.idle", "message.updated", "message.part.updated"]
+        }
+      }
+    },
+    "channels": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "mac": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            },
+            "method": {
+              "type": "string",
+              "enum": ["auto", "applescript", "terminal-notifier"]
+            }
+          }
+        },
+        "ntfy": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            },
+            "server": {
+              "type": "string"
+            },
+            "topic": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "overrides": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "includeGroups": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "excludeGroups": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "dedupe": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "ttlSeconds": {
+          "type": "number",
+          "minimum": 0
+        }
+      }
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt
+
+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,129 @@
+# OpenCode Notifications
+
+This repo implements a per-repo notification plugin for OpenCode. It uses a repo-local config file (`.opencode/oc-notify.json`) and sends notifications to macOS Notification Center and ntfy.
+
+## Quick Start
+
+1) Install the CLI (global) or use `npx`:
+
+```bash
+npm install -g @goodnesshq/opencode-notification
+```
+
+2) Install the repo installer (once per repo):
+
+```bash
+ocn install
+```
+
+3) Add the plugin to your global OpenCode config (use an absolute path; `~` is not expanded).
+
+`~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "<path-from-ocn-plugin-path>"
+  ]
+}
+```
+
+4) Run the repo installer:
+
+```bash
+node .opencode/notify-init.mjs
+```
+
+This writes `.opencode/oc-notify.json` with your repo-specific settings.
+
+### Update guidance
+
+- One-off: `npx @goodnesshq/opencode-notification@latest install`
+- Global: `npm update -g @goodnesshq/opencode-notification`
+
+## Troubleshooting
+
+**OpenCode fails to start after enabling the plugin**
+
+- Ensure every entry in `plugin` points to an existing file.
+- Remove stale plugin paths from other repos.
+- Use absolute paths (no `~`).
+
+## Config Schema
+
+The config is defined in `.opencode/oc-notify.schema.json` and supports:
+
+- `enabled`: master switch
+- `title`: override or template (supports `{repo}` and `{branch}`)
+- `tier`: `minimal` | `standard` | `verbose` | `custom`
+- `detailLevel`: `full` | `title-only`
+- `responseComplete`: trigger for completion notifications
+- `channels`: `mac` and `ntfy` settings
+- `overrides`: include/exclude groups
+- `dedupe`: in-memory TTL settings
+
+## Tier Defaults
+
+- **minimal**: `action_required`, `failures`
+- **standard**: minimal + `change_summary`, `session_lifecycle`
+- **verbose**: standard + `files`, `todos`, `vcs_worktree`, `pty`, `responses`
+
+## Example Configs
+
+### Minimal
+```json
+{
+  "enabled": true,
+  "tier": "minimal",
+  "responseComplete": {
+    "enabled": true,
+    "trigger": "session.idle"
+  },
+  "channels": {
+    "mac": { "enabled": true, "method": "auto" },
+    "ntfy": { "enabled": true, "server": "https://ntfy.sh", "topic": "oc-goodness-attn-1407537" }
+  }
+}
+```
+
+### Standard
+```json
+{
+  "enabled": true,
+  "tier": "standard",
+  "detailLevel": "full",
+  "responseComplete": {
+    "enabled": true,
+    "trigger": "message.updated"
+  }
+}
+```
+
+### Verbose
+```json
+{
+  "enabled": true,
+  "tier": "verbose",
+  "responseComplete": {
+    "enabled": true,
+    "trigger": "message.part.updated"
+  },
+  "overrides": {
+    "includeGroups": ["commands_tools"],
+    "excludeGroups": []
+  }
+}
+```
+
+### Custom
+```json
+{
+  "enabled": true,
+  "tier": "custom",
+  "overrides": {
+    "includeGroups": ["action_required", "failures", "change_summary"],
+    "excludeGroups": ["session_lifecycle"]
+  }
+}
+```

package/bin/ocn.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import { copyFile, mkdir, stat } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
+const ASSET_NOTIFY_INIT = join(PACKAGE_ROOT, ".opencode", "notify-init.mjs");
+const ASSET_SCHEMA = join(PACKAGE_ROOT, ".opencode", "oc-notify.schema.json");
+const PLUGIN_PATH = join(PACKAGE_ROOT, "plugins", "opencode-notifications.mjs");
+
+function usage() {
+  console.log("Usage: ocn <command>\n\nCommands:\n  install       Copy installer assets into the current repo\n  plugin-path   Print absolute path to the plugin entry file\n");
+}
+
+async function ensureDir(path) {
+  await mkdir(path, { recursive: true });
+}
+
+async function fileExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function install() {
+  const cwd = process.cwd();
+  const repoName = basename(cwd);
+  const opencodeDir = join(cwd, ".opencode");
+  await ensureDir(opencodeDir);
+
+  if (!(await fileExists(ASSET_NOTIFY_INIT)) || !(await fileExists(ASSET_SCHEMA))) {
+    console.error("ocn: installer assets missing from package");
+    process.exit(1);
+  }
+
+  await copyFile(ASSET_NOTIFY_INIT, join(opencodeDir, "notify-init.mjs"));
+  await copyFile(ASSET_SCHEMA, join(opencodeDir, "oc-notify.schema.json"));
+
+  console.log(`Installed OpenCode Notifications installer in ${repoName}.`);
+  console.log("Next steps:");
+  console.log("  1) Run: node .opencode/notify-init.mjs");
+  console.log("  2) Add the plugin path to ~/.config/opencode/opencode.json");
+  console.log("     ocn plugin-path");
+  console.log("\nUpdate guidance:");
+  console.log("  - One-off: npx @goodnesshq/opencode-notification@latest install");
+  console.log("  - Global: npm update -g @goodnesshq/opencode-notification");
+}
+
+async function pluginPath() {
+  if (!(await fileExists(PLUGIN_PATH))) {
+    console.error("ocn: plugin entry file missing from package");
+    process.exit(1);
+  }
+  console.log(PLUGIN_PATH);
+}
+
+async function main() {
+  const [command] = process.argv.slice(2);
+  if (!command || command === "-h" || command === "--help") {
+    usage();
+    return;
+  }
+
+  if (command === "install") {
+    await install();
+    return;
+  }
+
+  if (command === "plugin-path") {
+    await pluginPath();
+    return;
+  }
+
+  usage();
+  process.exit(1);
+}
+
+await main();