oc-tweaks 0.1.0

package/README.md

@@ -0,0 +1,333 @@
+# oc-tweaks
+
+[![npm version](https://img.shields.io/npm/v/oc-tweaks?color=a1b858&label=)](https://www.npmjs.com/package/oc-tweaks)
+
+A collection of runtime enhancement plugins for [OpenCode](https://opencode.ai/).
+
+## Introduction
+
+`oc-tweaks` provides a set of plugins to enhance your OpenCode experience. These plugins are activated at runtime and can modify OpenCode's behavior, such as sending notifications, improving multi-language support, and enforcing best practices for sub-agent usage.
+
+The currently available plugins are:
+- **`notify`**: Sends desktop notifications when a task is completed or an error occurs.
+- **`compaction`**: Injects a language preference prompt during session compaction to ensure summaries are in your preferred language.
+- **`backgroundSubagent`**: Adds a system prompt to encourage using background sub-agents for better responsiveness.
+- **`leaderboard`**: Reports token usage to [claudecount.com](https://claudecount.com) for community leaderboards.
+
+## Installation
+
+Install the package from npm:
+```bash
+bun add oc-tweaks
+# or
+npm install oc-tweaks
+```
+
+Then, add it to your OpenCode configuration file (`~/.config/opencode/opencode.json`). Note the key is `plugin` (singular).
+
+```json
+{
+  "plugin": ["oc-tweaks"]
+}
+```
+
+## Quick Start
+
+To generate a default configuration file, run the following command:
+
+```bash
+bunx oc-tweaks init
+```
+
+This will create `~/.config/opencode/oc-tweaks.json` with all plugins configured. You can edit this file to enable or disable plugins and customize their behavior.
+
+## Configuration
+
+All configurations are optional. By default, most plugins are enabled after running the `init` command.
+
+### `notify`
+
+This plugin sends desktop notifications upon task completion (session idle) or error.
+
+- **Windows**: Uses a custom, non-intrusive WPF window that works across virtual desktops.
+- **macOS**: Uses `osascript`.
+- **Linux**: Uses `notify-send`.
+- **Fallback**: Can use the built-in TUI toast if available.
+
+**Configuration Options:**
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | boolean | `true` | Enable or disable the plugin. |
+| `notifyOnIdle` | boolean | `true` | Notify when a session becomes idle (task completion). |
+| `notifyOnError` | boolean | `true` | Notify on session errors. |
+| `command` | string | `null` | A custom command to run for notifications. `$TITLE` and `$MESSAGE` are available as placeholders. |
+| `style` | object | `{...}` | Custom styles for the Windows WPF notification window. See below. |
+
+#### `notify.style` (Windows WPF)
+
+Customize the appearance of the WPF notification window.
+
+| Property | Default | Description |
+|---|---|---|
+| `backgroundColor` | `"#101018"` | Background color of the notification window. |
+| `backgroundOpacity` | `0.95` | Background opacity (0 to 1). |
+| `textColor` | `"#AAAAAA"` | Main text color. |
+| `borderRadius` | `14` | Corner radius in pixels. |
+| `colorBarWidth` | `5` | Width of the left accent bar in pixels. |
+| `width` | `420` | Window width in pixels. |
+| `height` | `105` | Window height in pixels. |
+| `titleFontSize` | `14` | Font size for the title in points. |
+| `contentFontSize` | `11` | Font size for the content in points. |
+| `iconFontSize` | `13` | Font size for the icon (✅/❌) in points. |
+| `duration` | `10000` | Time in milliseconds before the notification auto-closes. |
+| `position` | `"center"` | Window position: `"center"`, `"top-right"`, or `"bottom-right"`. |
+| `shadow` | `true` | Enable or disable the drop shadow effect. |
+| `idleColor` | `"#4ADE80"` | Accent color for idle (success) notifications. |
+| `errorColor` | `"#EF4444"` | Accent color for error notifications. |
+
+### `compaction`
+
+This plugin ensures that when OpenCode compacts a session's context, the resulting summary is generated in your preferred language (e.g., Chinese) instead of defaulting to English.
+
+**Configuration Options:**
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | boolean | `true` | Enable or disable the plugin. |
+
+### `backgroundSubagent`
+
+This plugin injects a policy into the system prompt, reminding the AI agent to use `run_in_background=true` by default when dispatching sub-agents. It helps maintain a responsive main conversation. If a foreground task is dispatched, a friendly reminder is shown.
+
+**Configuration Options:**
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | boolean | `true` | Enable or disable the plugin. |
+
+### `leaderboard`
+
+This plugin reports token usage statistics to the community-driven [claudecount.com](https://claudecount.com) leaderboard. It is disabled by default.
+
+**Configuration Options:**
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | boolean | `false` | Enable or disable the plugin. |
+| `configPath` | string | `null` | Optional path to a custom `leaderboard.json` file. If not set, it searches standard locations (`~/.claude/leaderboard.json`, `~/.config/claude/leaderboard.json`). |
+
+### `logging`
+
+Configure logging for `oc-tweaks`.
+
+**Configuration Options:**
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | boolean | `false` | Enable writing logs to a file. |
+| `maxLines` | number | `100` | Maximum number of lines to keep in the log file. Older lines are truncated. |
+
+Logs are written to `~/.config/opencode/plugins/oc-tweaks.log`.
+
+## Full Configuration Example
+
+Here is an example of a `~/.config/opencode/oc-tweaks.json` file with all options shown.
+
+```json
+{
+  "notify": {
+    "enabled": true,
+    "notifyOnIdle": true,
+    "notifyOnError": true,
+    // Example of a custom command to send notification to another machine via SSH
+    // "command": "ssh my-desktop 'notify-send \"$TITLE\" \"$MESSAGE\"'",
+    "style": {
+      "backgroundColor": "#101018",
+      "duration": 8000
+    }
+  },
+  "compaction": {
+    "enabled": true
+  },
+  "backgroundSubagent": {
+    "enabled": true
+  },
+  "leaderboard": {
+    "enabled": false
+    // "configPath": "/path/to/my/leaderboard.json"
+  },
+  "logging": {
+    "enabled": false,
+    "maxLines": 200
+  }
+}
+```
+
+---
+
+# oc-tweaks (中文)
+
+[![npm version](https://img.shields.io/npm/v/oc-tweaks?color=a1b858&label=)](https://www.npmjs.com/package/oc-tweaks)
+
+一套用于 [OpenCode](https://opencode.ai/) 的运行时增强插件。
+
+## 简介
+
+`oc-tweaks` 提供了一系列插件来增强你的 OpenCode 使用体验。这些插件在运行时激活，可以调整 OpenCode 的行为，例如发送桌面通知、改善多语言支持以及强制执行子代理使用的最佳实践。
+
+目前可用的插件包括：
+- **`notify`**: 在任务完成或发生错误时发送桌面通知。
+- **`compaction`**: 在会话上下文压缩期间注入语言偏好提示，以确保摘要使用你的首选语言。
+- **`backgroundSubagent`**: 添加系统提示，鼓励使用后台子代理以获得更好的响应性。
+- **`leaderboard`**: 向 [claudecount.com](https://claudecount.com) 报告 token 用量，用于社区排行榜。
+
+## 安装
+
+通过 npm 安装该软件包：
+```bash
+bun add oc-tweaks
+# 或
+npm install oc-tweaks
+```
+
+然后，将其添加到你的 OpenCode 配置文件 (`~/.config/opencode/opencode.json`) 中。请注意，键是 `plugin` (单数)。
+
+```json
+{
+  "plugin": ["oc-tweaks"]
+}
+```
+
+## 快速开始
+
+要生成默认配置文件，请运行以下命令：
+
+```bash
+bunx oc-tweaks init
+```
+
+这将在 `~/.config/opencode/oc-tweaks.json` 创建一个包含所有插件配置的文件。你可以编辑此文件来启用或禁用插件并自定义其行为。
+
+## 配置说明
+
+所有配置都是可选的。默认情况下，运行 `init` 命令后，大多数插件都是启用的。
+
+### `notify`
+
+此插件在任务完成（会话空闲）或出错时发送桌面通知。
+
+- **Windows**: 使用一个自定义的、无侵入性的 WPF 窗口，该窗口可跨虚拟桌面工作。
+- **macOS**: 使用 `osascript`。
+- **Linux**: 使用 `notify-send`。
+- **备选方案**: 如果可用，可以使用内置的 TUI toast。
+
+**配置选项:**
+
+| 属性 | 类型 | 默认值 | 描述 |
+|---|---|---|---|
+| `enabled` | boolean | `true` | 启用或禁用此插件。 |
+| `notifyOnIdle` | boolean | `true` | 当会话变为空闲时（任务完成）通知。 |
+| `notifyOnError` | boolean | `true` | 在会话出错时通知。 |
+| `command` | string | `null` | 用于发送通知的自定义命令。`$TITLE` 和 `$MESSAGE` 可作为占位符。 |
+| `style` | object | `{...}` | 用于 Windows WPF 通知窗口的自定义样式。详见下文。 |
+
+#### `notify.style` (Windows WPF)
+
+自定义 WPF 通知窗口的外观。
+
+| 属性 | 默认值 | 描述 |
+|---|---|---|
+| `backgroundColor` | `"#101018"` | 通知窗口的背景颜色。 |
+| `backgroundOpacity` | `0.95` | 背景不透明度 (0 到 1)。 |
+| `textColor` | `"#AAAAAA"` | 主要文本颜色。 |
+| `borderRadius` | `14` | 圆角半径 (像素)。 |
+| `colorBarWidth` | `5` | 左侧强调色条的宽度 (像素)。 |
+| `width` | `420` | 窗口宽度 (像素)。 |
+| `height` | `105` | 窗口高度 (像素)。 |
+| `titleFontSize` | `14` | 标题的字体大小 (pt)。 |
+| `contentFontSize` | `11` | 内容的字体大小 (pt)。 |
+| `iconFontSize` | `13` | 图标 (✅/❌) 的字体大小 (pt)。 |
+| `duration` | `10000` | 通知自动关闭前的延迟时间 (毫秒)。 |
+| `position` | `"center"` | 窗口位置: `"center"`, `"top-right"`, 或 `"bottom-right"`。 |
+| `shadow` | `true` | 启用或禁用下拉阴影效果。 |
+| `idleColor` | `"#4ADE80"` | 空闲 (成功) 通知的强调色。 |
+| `errorColor` | `"#EF4444"` | 错误通知的强调色。 |
+
+### `compaction`
+
+此插件确保当 OpenCode 压缩会话上下文时，生成的摘要使用你的首选语言（例如中文），而不是默认为英文。
+
+**配置选项:**
+
+| 属性 | 类型 | 默认值 | 描述 |
+|---|---|---|---|
+| `enabled` | boolean | `true` | 启用或禁用此插件。 |
+
+### `backgroundSubagent`
+
+此插件向系统提示中注入一项策略，提醒 AI 代理在派发子代理时默认使用 `run_in_background=true`。这有助于保持主对话的响应性。如果派发了前台任务，则会显示一个友好的提醒。
+
+**配置选项:**
+
+| 属性 | 类型 | 默认值 | 描述 |
+|---|---|---|---|
+| `enabled` | boolean | `true` | 启用或禁用此插件。 |
+
+### `leaderboard`
+
+此插件向社区驱动的 [claudecount.com](https://claudecount.com) 排行榜报告 token 使用情况统计。默认禁用。
+
+**配置选项:**
+
+| 属性 | 类型 | 默认值 | 描述 |
+|---|---|---|---|
+| `enabled` | boolean | `false` | 启用或禁用此插件。 |
+| `configPath` | string | `null` | 可选的自定义 `leaderboard.json` 文件路径。如果未设置，则会搜索标准位置 (`~/.claude/leaderboard.json`, `~/.config/claude/leaderboard.json`)。 |
+
+### `logging`
+
+为 `oc-tweaks` 配置日志记录。
+
+**配置选项:**
+
+| 属性 | 类型 | 默认值 | 描述 |
+|---|---|---|---|
+| `enabled` | boolean | `false` | 启用将日志写入文件。 |
+| `maxLines` | number | `100` | 日志文件中保留的最大行数。旧行将被截断。 |
+
+日志文件路径为 `~/.config/opencode/plugins/oc-tweaks.log`。
+
+## 完整配置示例
+
+这是一个 `~/.config/opencode/oc-tweaks.json` 文件的完整示例，展示了所有选项。
+
+```json
+{
+  "notify": {
+    "enabled": true,
+    "notifyOnIdle": true,
+    "notifyOnError": true,
+    // 自定义命令示例：通过 SSH 向另一台机器发送通知
+    // "command": "ssh my-desktop 'notify-send \"$TITLE\" \"$MESSAGE\"'",
+    "style": {
+      "backgroundColor": "#101018",
+      "duration": 8000
+    }
+  },
+  "compaction": {
+    "enabled": true
+  },
+  "backgroundSubagent": {
+    "enabled": true
+  },
+  "leaderboard": {
+    "enabled": false
+    // "configPath": "/path/to/my/leaderboard.json"
+  },
+  "logging": {
+    "enabled": false,
+    "maxLines": 200
+  }
+}
+```

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "oc-tweaks",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.2.15"
+  },
+  "bin": {
+    "oc-tweaks": "./src/cli/init.ts"
+  },
+  "scripts": {
+    "test": "bun test",
+    "smoke": "bun scripts/smoke-test.ts"
+  },
+  "files": [
+    "src/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/__tests__/background-subagent.test.ts

@@ -0,0 +1,106 @@
+// @ts-nocheck
+
+import { describe, test, expect, afterEach } from "bun:test"
+
+const originalBunFile = Bun.file
+const originalHome = Bun.env?.HOME
+
+function mockBunFile(mockData: Record<string, any>) {
+  ;(globalThis as any).Bun.file = (path: string) => ({
+    exists: async () => path in mockData,
+    json: async () => {
+      if (!(path in mockData)) throw new Error("ENOENT")
+      const data = mockData[path]
+      if (data instanceof Error) throw data
+      return data
+    },
+    text: async () => JSON.stringify(mockData[path] ?? ""),
+  })
+}
+
+afterEach(() => {
+  ;(globalThis as any).Bun.file = originalBunFile
+  if (originalHome === undefined) {
+    delete (Bun.env as any).HOME
+  } else {
+    ;(Bun.env as any).HOME = originalHome
+  }
+})
+
+describe("backgroundSubagentPlugin", () => {
+  test("injects English system prompt", async () => {
+    const home = "/tmp/oc-background-system"
+    ;(Bun.env as any).HOME = home
+    const path = `${home}/.config/opencode/oc-tweaks.json`
+    mockBunFile({
+      [path]: { backgroundSubagent: { enabled: true } },
+    })
+
+    const { backgroundSubagentPlugin } = await import("../plugins/background-subagent")
+    const hooks = await backgroundSubagentPlugin()
+
+    const output = { system: [] as string[] }
+    await hooks["experimental.chat.system.transform"]({}, output)
+
+    expect(output.system.length).toBe(1)
+    expect(output.system[0]).toContain("Sub-Agent Dispatch Policy")
+    expect(output.system[0]).not.toMatch(/[\u4e00-\u9fff]/)
+  })
+
+  test("does not append warning for non-task tools", async () => {
+    const home = "/tmp/oc-background-non-task"
+    ;(Bun.env as any).HOME = home
+    const path = `${home}/.config/opencode/oc-tweaks.json`
+    mockBunFile({
+      [path]: { backgroundSubagent: { enabled: true } },
+    })
+
+    const { backgroundSubagentPlugin } = await import("../plugins/background-subagent")
+    const hooks = await backgroundSubagentPlugin()
+
+    const beforeOutput = { args: { run_in_background: false } }
+    await hooks["tool.execute.before"]({ callID: "c1", tool: "other" }, beforeOutput)
+
+    const afterOutput = { output: "ok" }
+    await hooks["tool.execute.after"]({ callID: "c1" }, afterOutput)
+
+    expect(afterOutput.output).toBe("ok")
+  })
+
+  test("tracks foreground task calls and appends violation warning", async () => {
+    const home = "/tmp/oc-background-violation"
+    ;(Bun.env as any).HOME = home
+    const path = `${home}/.config/opencode/oc-tweaks.json`
+    mockBunFile({
+      [path]: { backgroundSubagent: { enabled: true } },
+    })
+
+    const { backgroundSubagentPlugin } = await import("../plugins/background-subagent")
+    const hooks = await backgroundSubagentPlugin()
+
+    const beforeOutput = { args: { run_in_background: false } }
+    await hooks["tool.execute.before"]({ callID: "c2", tool: "task" }, beforeOutput)
+
+    const afterOutput = { output: "result" }
+    await hooks["tool.execute.after"]({ callID: "c2" }, afterOutput)
+
+    expect(afterOutput.output).toContain("[Reminder]")
+    expect(afterOutput.output).not.toMatch(/[\u4e00-\u9fff]/)
+  })
+
+  test("returns empty hooks when disabled", async () => {
+    const home = "/tmp/oc-background-disabled"
+    ;(Bun.env as any).HOME = home
+    const path = `${home}/.config/opencode/oc-tweaks.json`
+    mockBunFile({
+      [path]: {
+        backgroundSubagent: { enabled: false },
+      },
+    })
+
+    const { backgroundSubagentPlugin } = await import("../plugins/background-subagent")
+    const hooks = await backgroundSubagentPlugin()
+
+    expect(hooks).toEqual({})
+  })
+})

package/src/__tests__/cli-init.test.ts

@@ -0,0 +1,70 @@
+// @ts-nocheck
+
+import { describe, test, expect, afterEach } from "bun:test"
+
+const originalBunFile = Bun.file
+const originalBunWrite = Bun.write
+const originalHome = Bun.env?.HOME
+
+afterEach(() => {
+  ;(globalThis as any).Bun.file = originalBunFile
+  ;(globalThis as any).Bun.write = originalBunWrite
+  if (originalHome === undefined) {
+    delete (Bun.env as any).HOME
+  } else {
+    ;(Bun.env as any).HOME = originalHome
+  }
+})
+
+describe("CLI init", () => {
+  test("creates config file when it does not exist", async () => {
+    const written: Record<string, string> = {}
+    ;(globalThis as any).Bun.write = async (path: string, content: string) => {
+      written[path] = content
+      return 0
+    }
+    ;(globalThis as any).Bun.file = (path: string) => ({
+      exists: async () => path in written,
+      json: async () => JSON.parse(written[path] ?? "{}"),
+    })
+    ;(Bun.env as any).HOME = "/tmp/oc-init-create"
+
+    const { initConfig } = await import("../cli/init")
+    const result = await initConfig()
+
+    expect(result.created).toBe(true)
+    expect(result.path).toContain("oc-tweaks.json")
+
+    const configPath = "/tmp/oc-init-create/.config/opencode/oc-tweaks.json"
+    const content = JSON.parse(written[configPath] ?? "{}")
+    expect(content.notify?.enabled).toBe(true)
+    expect(content.leaderboard?.enabled).toBe(false)
+    expect(content.logging?.maxLines).toBe(200)
+  })
+
+  test("does not overwrite when config already exists", async () => {
+    const existingContent = JSON.stringify({ notify: { enabled: false } })
+    const written: Record<string, string> = {}
+    const configPath = "/tmp/oc-init-exists/.config/opencode/oc-tweaks.json"
+    written[configPath] = existingContent
+
+    let writeCount = 0
+    ;(globalThis as any).Bun.write = async (path: string, content: string) => {
+      writeCount++
+      written[path] = content
+      return 0
+    }
+    ;(globalThis as any).Bun.file = (path: string) => ({
+      exists: async () => path in written,
+      json: async () => JSON.parse(written[path] ?? "{}"),
+    })
+    ;(Bun.env as any).HOME = "/tmp/oc-init-exists"
+
+    const { initConfig } = await import("../cli/init")
+    const result = await initConfig()
+
+    expect(result.created).toBe(false)
+    expect(writeCount).toBe(0)
+    expect(written[configPath]).toBe(existingContent) // unchanged
+  })
+})

package/src/__tests__/compaction.test.ts

@@ -0,0 +1,113 @@
+// @ts-nocheck
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+
+import { compactionPlugin } from "../plugins/compaction"
+
+const originalBunFile = Bun.file
+const originalHome = Bun.env?.HOME
+
+function mockBunFile(mockData: Record<string, any>) {
+  ;(globalThis as any).Bun.file = (path: string) => ({
+    exists: async () => path in mockData,
+    json: async () => {
+      if (!(path in mockData)) throw new Error("ENOENT")
+      const data = mockData[path]
+      if (data instanceof Error) throw data
+      return data
+    },
+    text: async () => JSON.stringify(mockData[path] ?? ""),
+  })
+}
+
+function restoreBunFile() {
+  ;(globalThis as any).Bun.file = originalBunFile
+}
+
+function setHome(home: string | undefined) {
+  if (home === undefined) {
+    delete (Bun.env as any).HOME
+  } else {
+    ;(Bun.env as any).HOME = home
+  }
+}
+
+beforeEach(() => {
+  setHome(originalHome)
+})
+
+afterEach(() => {
+  restoreBunFile()
+  setHome(originalHome)
+})
+
+describe("compactionPlugin", () => {
+  test("pushes language preference prompt into context", async () => {
+    const home = "/tmp/oc-home-compaction"
+    const path = `${home}/.config/opencode/oc-tweaks.json`
+
+    setHome(home)
+    mockBunFile({
+      [path]: { compaction: { enabled: true } },
+    })
+
+    const plugin = await compactionPlugin()
+    const hook = plugin["experimental.session.compacting"]
+    const output = { context: [] as string[] }
+
+    await hook({ sessionID: "s-1" }, output)
+
+    expect(output.context.length).toBe(1)
+    const prompt = output.context[0]
+    expect(prompt).toContain("Language Preference")
+    expect(prompt).toContain("preferred language")
+  })
+
+  test("prompt includes preferred language phrasing", async () => {
+    const home = "/tmp/oc-home-compaction-phrase"
+    const path = `${home}/.config/opencode/oc-tweaks.json`
+
+    setHome(home)
+    mockBunFile({
+      [path]: {
+        compaction: { enabled: true },
+      },
+    })
+
+    const plugin = await compactionPlugin()
+    const hook = plugin["experimental.session.compacting"]
+    const output = { context: [] as string[] }
+
+    await hook({ sessionID: "s-2" }, output)
+
+    const prompt = output.context[0]
+    expect(prompt.toLowerCase()).toContain("preferred language")
+  })
+
+  test("returns empty hooks when compaction is disabled", async () => {
+    const home = "/tmp/oc-home-compaction-disabled"
+    const path = `${home}/.config/opencode/oc-tweaks.json`
+
+    setHome(home)
+    mockBunFile({
+      [path]: {
+        compaction: { enabled: false },
+      },
+    })
+
+    const plugin = await compactionPlugin()
+
+    expect(plugin).toEqual({})
+  })
+
+  test("returns empty hooks when config file is missing", async () => {
+    const home = "/tmp/oc-home-compaction-missing"
+
+    setHome(home)
+    mockBunFile({})
+
+    const plugin = await compactionPlugin()
+
+    expect(plugin).toEqual({})
+  })
+})