opencode-prompt-expand 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0
+
+- Initial OpenCode Desktop GUI plugin.
+- Expand, regenerate, undo, restore, and version navigation commands.
+- Composer pill for mounted sessions.
+- Best-effort bottom button and DOM fallback for Home / new-session drafts.
+- Settings page for mode, model, and project context.
+- Project context from package.json, rule files, and git status.
+- OpenAI/Claude-family prompt variants.
+- Unit tests and a stubbed GUI smoke test.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,339 @@
-# Temporary Holding Version
+# opencode-prompt-expand
 
-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.
+![opencode-prompt-expand featured image](assets/featured.png)
+
+Expand a rough draft in the **OpenCode Desktop** composer into a structured prompt, in place.
+
+The plugin is a small OpenCode Desktop extension: it reads the current draft, asks your own connected model to expand it, writes the result back into the composer, and leaves the send action to you. It never sends a message, never writes session history, and never proxies model credentials.
+
+**Status:** `v0.1.0` experimental. The OpenCode Desktop GUI plugin API is still marked experimental upstream; pin the OpenCode version you test against.
+
+[中文说明](README.zh-CN.md)
+
+**Who it is for:** OpenCode Desktop users who write natural-language prompts and want a more structured first draft without leaving the composer. It is not a TUI plugin and it does not send messages for you.
+
+## What it does
+
+- Turns vague requests into prompts with scope, constraints, output format, and acceptance criteria.
+- Writes the result back into the composer so you can edit it before sending.
+- Keeps up to five generated versions in memory for the current window.
+- Adds toast actions for **Undo** and **Regenerate**.
+- Can read a small, whitelisted set of project facts to make the expansion more specific.
+- Supports a concise mode (~800 characters) and a full-expansion mode.
+
+It does not:
+
+- send the prompt
+- modify session history
+- read `.env`, keys, or source files
+- call the plugin author's servers
+
+## Requirements
+
+- OpenCode Desktop **2.2.5** (the version this release was built and tested against)
+- Node.js **^20.19.0 or >=22.12.0** and npm, if you build from source
+- A provider/model connected in OpenCode. The plugin uses your own provider account (BYOK).
+
+The TUI is not supported. The GUI composer API used here is only available in OpenCode Desktop.
+
+## Install from GitHub
+
+```bash
+git clone https://github.com/ConnorYyy/opencode-prompt-expand.git
+cd opencode-prompt-expand
+npm ci
+```
+
+`npm ci` runs the `prepare` script, which builds `dist/`. You can also run `npm run build` explicitly.
+
+The build produces:
+
+```text
+dist/index.js              server part
+dist/rpc.js                RPC contract
+dist/gui-experimental.cjs  Desktop GUI bundle
+```
+
+Add the plugin to the **global** OpenCode config. Desktop reads GUI plugins only from the global file:
+
+- macOS / Linux: `~/.config/opencode/opencode.jsonc`
+- Windows: `C:\Users\<you>\.config\opencode\opencode.jsonc`
+
+```jsonc
+{
+  "shell": "powershell",
+  "plugins": [
+    {
+      "package": "/absolute/path/to/opencode-prompt-expand",
+      "options": {
+        "mode": "concise",
+        "model": "auto",
+        "projectContext": true,
+        "timeoutMs": 30000
+      }
+    }
+  ]
+}
+```
+
+On Windows, use forward slashes or escaped backslashes in the path, for example:
+
+```jsonc
+"package": "D:/path/to/opencode-prompt-expand"
+```
+
+Then reload the Desktop window or restart OpenCode Desktop. The GUI bundle is loaded at window start; reloading only the server is not enough after a first install.
+
+Confirm the install:
+
+- **Settings > Extensions > Plugins** shows `prompt-expand` as enabled.
+- The command palette has **Expand prompt**.
+- A mounted session shows the `⚡ Expand Prompt` pill above the composer.
+- Home / new-session drafts show the bottom `⚡ Expand Prompt` button (see below).
+
+### Install from npm
+
+Once the package is published, install it with the OpenCode CLI:
+
+```bash
+opencode plugin add opencode-prompt-expand
+```
+
+Pin a specific version when needed:
+
+```bash
+opencode plugin add opencode-prompt-expand@0.1.0
+```
+
+Then verify it is configured:
+
+```bash
+opencode plugin list
+```
+
+The package name is `opencode-prompt-expand`. It has not been published to npm in this release yet; until it is, use the local-directory install above.
+
+## Usage
+
+1. Write a draft in the composer, for example:
+   `帮我做一个数据看板，包含筛选和导出`
+2. Click `⚡ Expand Prompt`, run **Expand prompt** from the command palette, or type `/expand <text>`.
+3. Wait for the model. The draft is replaced in place.
+4. Review or edit the result, then press Enter yourself.
+
+### Entry points
+
+| Entry | How |
+|---|---|
+| Pill | Click `⚡ Expand Prompt` above a session composer |
+| Draft button | On Home / new-session drafts, use the bottom `⚡ Expand Prompt` button |
+| Command palette | Search `Expand prompt` |
+| Slash command | `/expand <text>` |
+| Regenerate | Toast action, or command palette **Regenerate prompt** |
+| Restore original | Toast **Undo**, or command palette **Restore original prompt** |
+| Previous / next version | Command palette **Previous expanded version** / **Next expanded version** |
+| Toggle mode | Command palette **Toggle expansion mode** |
+
+There are **no default keyboard shortcuts**. Commands are registered in **Settings > Shortcuts**; assign your own:
+
+```text
+prompt-expand.expand
+prompt-expand.regenerate
+prompt-expand.restore
+prompt-expand.previous
+prompt-expand.next
+prompt-expand.mode
+prompt-expand.settings
+```
+
+### Versions
+
+- Up to 5 generated versions per draft, in memory for the current window.
+- Editing the draft resets the version stack; the next expansion starts from the edited text.
+- Toast actions are guarded: if you switched sessions or edited the text, Undo will not overwrite your changes.
+- The failure toast includes the server `code` and `message` when available, so timeout, model, and validation failures are distinguishable.
+
+## Home and new-session drafts
+
+The official `ctx.screen.current()?.composer` API is `undefined` on Home and on a draft session; `Sessions.current()` is also `undefined` there. The session `ComposerPill` therefore cannot render before the first message creates a mounted session.
+
+For those pages the plugin adds a bottom `⚡ Expand Prompt` button. Because no official draft composer API exists, it uses a **best-effort DOM adapter**:
+
+- it finds the bottom-most visible `textarea`, text input, or contenteditable;
+- it reads and writes that element directly;
+- it only runs when there is no mounted session;
+- it is hidden on Settings and other plugin pages.
+
+Impact and limits:
+
+- It is not an official OpenCode API and may break if the Desktop composer changes.
+- It may fail on a complex rich-text composer or if the editor changes during the model call.
+- `@` mentions and attachments are not supported on drafts.
+- The draft has no composer model, so the model comes from the server default or your configured model.
+- Disable it with `draftFallback: false` if you only want to expand in mounted sessions.
+- After the first message creates a session, the normal composer pill is used.
+
+## Settings
+
+Open **Settings > Prompt Expand**, or run **Prompt Expand settings** from the command palette (command `prompt-expand.settings`).
+
+| Setting | Description |
+|---|---|
+| Mode | `concise` (~800 chars) or `full` |
+| Model | `auto`, `composer`, `provider/model`, or empty |
+| Project context | Read `package.json`, rule files, and git status |
+
+Settings persist through `Store.global`. An unset field, or a model field of `auto`, follows the `options` from `opencode.jsonc`; an explicit setting overrides it. This matters on Home/draft pages, where no composer model is available.
+
+## Configuration
+
+Options are passed through the plugin entry:
+
+| Key | Default | Description |
+|---|---|---|
+| `model` | `"auto"` | `auto`, `composer`, or `"provider/model"` |
+| `mode` | `"concise"` | `concise` / `full` |
+| `maxRounds` | `5` | Total generations per draft, including v1 |
+| `timeoutMs` | `30000` | Abort and leave the composer untouched after this long |
+| `maxGrowth` | `5` | Reject output larger than `original × maxGrowth` **and** > 2000 chars |
+| `minChars` | `10` | Below this, skip |
+| `maxPromptChars` | `6000` | Above this, skip |
+| `skipPatterns` | built-in | Array of regex strings; replaces the built-in list |
+| `skipOnMentions` | `true` | Skip drafts containing `@path` |
+| `projectContext` | `true` | Read project facts |
+| `projectContextBudget` | `2048` | Character budget for injected context |
+| `draftFallback` | `true` | Enable the DOM fallback on Home / new-session drafts |
+| `prompts` | built-in | Map of glob → prompt; `*gpt*` and `*claude*` included |
+
+### Model selection
+
+- `composer` uses the model currently selected in the composer.
+- `auto` prefers the composer model, then the session model, then the server default, then a cheap chat model.
+- Explicit `provider/model` is used as-is.
+
+If `auto` falls back to a free model and that model has hit its usage limit, set the model to `composer` or an explicit paid model.
+
+The composer model is mapped from `{ providerID, modelID }` to the generation API's `{ providerID, id }`.
+
+### Project context
+
+Only these sources are read:
+
+- `package.json` (name, description, dependency names)
+- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.windsurfrules`, `CONVENTIONS.md`, `.github/copilot-instructions.md`
+- current branch and changed file names (filtered to exclude `node_modules/`)
+
+The directory is resolved from the mounted session first, then the directory supplied by the Desktop window, then the plugin instance location. The result is cached for 5 minutes per directory and limited to `projectContextBudget` characters.
+
+## Privacy and side effects
+
+- The draft is sent only to the provider you connected in OpenCode.
+- The plugin does not persist drafts, keys, or credentials.
+- It does not send messages, write session history, or occupy the session context window.
+- Project context never reads `.env`, `.pem`, `credentials*`, or source files.
+- The plugin has no telemetry and no author-operated proxy.
+
+## Development
+
+```bash
+npm ci
+npm run typecheck
+npm test
+npm run build
+npm run smoke:gui
+npm run verify       # typecheck + tests + build + GUI smoke
+```
+
+`src/index.ts` is the server part, `src/gui.tsx` is the Desktop GUI bundle, and `src/rpc.ts` is the shared contract.
+
+`scripts/smoke-gui.cjs` loads the built GUI bundle with stubbed host modules and exercises expand, regenerate, undo, settings, pill, and the draft fallback slot.
+
+### Project layout
+
+```text
+src/
+├── index.ts              server and RPC registration
+├── rpc.ts                RPC contract
+├── gui.tsx               Desktop GUI entry
+├── gui/
+│   ├── commands.ts       command palette / slash commands
+│   ├── controller.ts     expand, regenerate, undo, versions
+│   ├── draft.ts          DOM fallback for Home / drafts
+│   ├── failure.ts        RPC error detail
+│   ├── pill.ts           composer pill
+│   ├── settings.tsx      settings page
+│   └── state.ts          per-session version stack
+├── optimizer.ts          bypass, cleaning, validation
+├── prompts.ts            default and model-family prompts
+├── model.ts              model selection
+├── project-context.ts    whitelist and budget
+└── config.ts             option resolution
+```
+
+### CI
+
+The repository includes a GitHub Actions workflow that runs `npm ci` and `npm run verify` on Windows and Ubuntu with Node 20.19 and 22.12.
+
+## Limitations
+
+- The Desktop GUI plugin API is experimental. Pin `@opencode/plugin` to the OpenCode version you run.
+- The Home/draft DOM fallback is best-effort and not an official composer API.
+- `composer.setText()` replaces text and keeps attachments, but it cannot rewrite `@` mention parts. Drafts containing `@path` are skipped.
+- There is no TUI implementation.
+- A slow model can exceed `timeoutMs`; raise it if your provider is slow.
+
+## FAQ
+
+### Is this a TUI plugin?
+
+No. It uses the OpenCode Desktop GUI composer API. The terminal TUI is not supported.
+
+### Does it send the prompt automatically?
+
+No. The plugin only reads the composer, writes the expanded text back, and leaves Enter to you. It does not create session messages or write conversation history.
+
+### Which model does it use?
+
+By default, `auto` prefers the composer model, then the session model, then the server default, then a cheap chat model. You can also set `composer` or an explicit `provider/model` in settings.
+
+### Why are there no default keyboard shortcuts?
+
+Shortcuts are user-specific and can conflict with host bindings. The commands are registered in **Settings > Shortcuts**; assign the ones you want.
+
+### Why does the new-session page use a bottom button instead of a composer pill?
+
+OpenCode does not expose an official composer API on Home or draft sessions. The bottom button is a best-effort DOM fallback and is marked experimental. Once the first message creates a mounted session, the normal composer pill is used.
+
+### Does it support `@` file mentions?
+
+Drafts containing `@path` references are skipped because rewriting the text can desynchronize mention attachments. Plain email addresses are not treated as mentions.
+
+### Does it store my prompts?
+
+No. Drafts are not persisted by the plugin. The version stack is in memory for the current window only.
+
+### What happens when expansion fails?
+
+The original composer text is left unchanged. The toast includes the server `code` and `message` when available, such as timeout, model, or validation failure.
+
+### Is it free?
+
+The plugin is MIT-licensed. You pay your own model provider for generation; there is no author-operated proxy or telemetry.
+
+### How is it different from a generic prompt optimizer?
+
+It works inside the OpenCode Desktop composer, writes back in place, keeps a small version stack, and can use the model you already selected. It does not require copying prompts into another chat window.
+
+## Sponsor
+
+If this plugin saves you time, you can support maintenance and testing through Buy Me a Coffee:
+
+[buymeacoffee.com/connory](https://buymeacoffee.com/connory)
+
+[![Buy Me a Coffee QR code](assets/bmc-qr.png)](https://buymeacoffee.com/connory)
+
+Scan the QR code or use the link. Support is optional; the plugin remains MIT-licensed.
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,177 @@
+# opencode-prompt-expand
+
+[English README](README.md)
+
+![opencode-prompt-expand](assets/featured.png)
+
+在 **OpenCode Desktop** 的 composer 里，把粗糙草稿扩展成结构化提示词，并原地写回。
+
+**状态：** `v0.1.0` 实验版。OpenCode Desktop 的 GUI 插件 API 仍是 experimental，请锁定你测试的 OpenCode 版本。
+
+## 适合谁
+
+- 使用 OpenCode Desktop 的个人开发者
+- 习惯用自然语言描述需求，但不想每次手写结构化提示词
+- 希望结果留在 composer 里，自己检查、修改后再按 Enter
+
+不适用于终端 TUI。插件不会自动发送消息，也不会写入会话历史。
+
+## 功能
+
+- 把模糊需求补成：目标、范围、约束、产出、验收方式
+- 原地写回 composer，可继续编辑
+- toast 提供「撤销」和「重生成」
+- 最多保留 5 个版本，仅在当前窗口内存中
+- 简洁模式（约 800 字符）和充分展开模式
+- 可读取白名单内的项目信息：`package.json`、规则文件、git 状态
+- 支持 `*gpt*` / `*claude*` 家族指令
+
+## 要求
+
+- OpenCode Desktop **2.2.5**（当前验证版本）
+- Node.js **^20.19.0 或 >=22.12.0**（仅从源码构建时需要）
+- 已在 OpenCode 中连接 provider/model
+
+## 安装
+
+### 从 GitHub 构建
+
+```bash
+git clone https://github.com/ConnorYyy/opencode-prompt-expand.git
+cd opencode-prompt-expand
+npm ci
+```
+
+`npm ci` 会通过 `prepare` 自动构建 `dist/`。
+
+把插件加入**全局** OpenCode 配置：
+
+- macOS / Linux：`~/.config/opencode/opencode.jsonc`
+- Windows：`C:\Users\<you>\.config\opencode\opencode.jsonc`
+
+```jsonc
+{
+  "shell": "powershell",
+  "plugins": [
+    {
+      "package": "/absolute/path/to/opencode-prompt-expand",
+      "options": {
+        "mode": "concise",
+        "model": "auto",
+        "projectContext": true,
+        "timeoutMs": 30000
+      }
+    }
+  ]
+}
+```
+
+Windows 路径示例：
+
+```jsonc
+"package": "D:/path/to/opencode-prompt-expand"
+```
+
+重载 Desktop 窗口，或重启 OpenCode Desktop。  
+检查 **Settings > Extensions > Plugins** 中是否出现 `prompt-expand`。
+
+### npm
+
+npm 包名是 `opencode-prompt-expand`，当前尚未发布。发布后可使用：
+
+```bash
+opencode plugin add opencode-prompt-expand
+opencode plugin list
+```
+
+## 使用
+
+1. 在 composer 写草稿，例如：`帮我做一个数据看板，包含筛选和导出`
+2. 点击 `⚡ Expand Prompt`，或在命令面板搜索 **Expand prompt**，或输入 `/expand <text>`
+3. 等待模型返回，结果会写回 composer
+4. 自己检查/修改，然后按 Enter 发送
+
+入口：
+
+| 入口 | 方式 |
+|---|---|
+| session composer | 点击 `⚡ Expand Prompt` pill |
+| Home / 新建会话草稿 | 点击底部 `⚡ Expand Prompt` 按钮 |
+| 命令面板 | 搜索 `Expand prompt` |
+| 斜杠 | `/expand <text>` |
+| 重生成 / 撤销 | toast 按钮，或命令面板 |
+| 版本切换 | 命令面板 Previous / Next expanded version |
+
+没有默认快捷键。可在 **Settings > Shortcuts** 绑定：
+
+```text
+prompt-expand.expand
+prompt-expand.regenerate
+prompt-expand.restore
+prompt-expand.previous
+prompt-expand.next
+prompt-expand.mode
+prompt-expand.settings
+```
+
+## 设置
+
+打开 **Settings > Prompt Expand**，或运行 **Prompt Expand settings**。
+
+| 设置 | 说明 |
+|---|---|
+| Mode | 简洁 / 充分展开 |
+| Model | `auto`、`composer`、`provider/model` 或留空 |
+| Project context | 是否读取项目信息 |
+
+设置通过 `Store.global` 保存。未设置或 Model 为 `auto` 时，回退到 `opencode.jsonc` 的 options；显式设置会覆盖。
+
+## 常见问题
+
+**会发送消息吗？**  
+不会。插件只读写 composer，发送由你按 Enter 完成。
+
+**支持 TUI 吗？**  
+不支持，只支持 OpenCode Desktop。
+
+**为什么新建会话页没有 composer pill？**  
+Home / draft 没有官方 composer API。插件在底部提供 `⚡ Expand Prompt` 按钮，通过 DOM 适配器读写草稿，属于 best-effort。创建 session 后会使用正常 pill。
+
+**支持 `@` 文件引用吗？**  
+含 `@path` 的草稿会跳过，避免附件与文本不同步。普通邮箱地址不会被误判。
+
+**失败会改输入框吗？**  
+不会。失败时原文不变，toast 会尽量显示服务端 code/message。
+
+**会保存我的提示词吗？**  
+不会。版本栈只在当前窗口内存中。
+
+## 隐私
+
+- 草稿只发送给你在 OpenCode 中连接的 provider
+- 不经过插件作者的代理
+- 不读取 `.env`、`.pem`、`credentials*` 或源码文件
+- 项目感知只读取白名单文件，并限制字符预算
+- 无 telemetry
+
+## 限制
+
+- GUI 插件 API 仍是 experimental
+- Home / draft 的 DOM 回退不是官方 API
+- `setText()` 不能重写 `@` mention 附件
+- 没有 TUI 实现
+- 慢模型可能超过 `timeoutMs`
+
+## 赞助
+
+如果这个插件帮你节省了时间，可以通过 Buy Me a Coffee 支持维护和测试：
+
+[buymeacoffee.com/connory](https://buymeacoffee.com/connory)
+
+[![Buy Me a Coffee QR code](assets/bmc-qr.png)](https://buymeacoffee.com/connory)
+
+赞助是可选的，插件保持 MIT License。
+
+## License
+
+MIT