opencode-prompt-expand 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.1
+
+- Fix the npm package README so the English README is primary.
+- Move the Chinese README to `docs/README.zh-CN.md`.
+- Update the npm install instructions after the first publish.
+
+## 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.1` experimental. The package is published on npm. The OpenCode Desktop GUI plugin API is still marked experimental upstream; pin the OpenCode version you test against.
+
+[中文说明](docs/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
+
+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.1
+```
+
+Then verify it is configured:
+
+```bash
+opencode plugin list
+```
+
+Package page: https://www.npmjs.com/package/opencode-prompt-expand
+
+## 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/assets/featured.html

@@ -0,0 +1,260 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=1080, initial-scale=1" />
+<title>opencode-prompt-expand featured image</title>
+<style>
+  * { box-sizing: border-box; }
+  html, body { margin: 0; width: 1080px; height: 1080px; overflow: hidden; }
+  body {
+    font-family: "Segoe UI", "Inter", Arial, sans-serif;
+    background: #080d19;
+    color: #f5f7ff;
+    -webkit-font-smoothing: antialiased;
+  }
+  .canvas {
+    position: relative;
+    width: 1080px;
+    height: 1080px;
+    padding: 64px 72px 54px;
+    overflow: hidden;
+    background:
+      radial-gradient(circle at 78% 18%, rgba(70, 130, 255, 0.20), transparent 34%),
+      radial-gradient(circle at 18% 78%, rgba(40, 220, 190, 0.13), transparent 32%),
+      linear-gradient(145deg, #0a1020 0%, #0b1224 52%, #070b14 100%);
+  }
+  .canvas::before {
+    content: "";
+    position: absolute;
+    inset: 0;
+    background-image:
+      linear-gradient(rgba(140, 170, 230, 0.045) 1px, transparent 1px),
+      linear-gradient(90deg, rgba(140, 170, 230, 0.045) 1px, transparent 1px);
+    background-size: 54px 54px;
+    mask-image: linear-gradient(to bottom, rgba(0,0,0,0.7), transparent 78%);
+  }
+  .glow {
+    position: absolute;
+    border-radius: 999px;
+    filter: blur(80px);
+    opacity: 0.5;
+    pointer-events: none;
+  }
+  .g1 { width: 420px; height: 420px; right: -120px; top: 40px; background: #245bff; }
+  .g2 { width: 360px; height: 360px; left: -140px; bottom: 20px; background: #16c7a7; opacity: 0.3; }
+  .top {
+    position: relative;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    z-index: 2;
+  }
+  .badge {
+    display: inline-flex;
+    align-items: center;
+    gap: 12px;
+    padding: 12px 18px;
+    border: 1px solid rgba(120, 160, 230, 0.28);
+    background: rgba(16, 28, 52, 0.72);
+    border-radius: 999px;
+    font-size: 17px;
+    letter-spacing: 2.4px;
+    font-weight: 650;
+    color: #b9c9e9;
+  }
+  .dot {
+    width: 10px;
+    height: 10px;
+    border-radius: 50%;
+    background: #3ee0be;
+    box-shadow: 0 0 18px rgba(62, 224, 190, 0.9);
+  }
+  .version {
+    font-family: Consolas, "Cascadia Code", monospace;
+    font-size: 18px;
+    color: #7e91b8;
+  }
+  h1 {
+    position: relative;
+    z-index: 2;
+    margin: 54px 0 0;
+    font-size: 86px;
+    line-height: 0.98;
+    letter-spacing: -3.8px;
+    font-weight: 760;
+  }
+  h1 span {
+    color: #67e5ca;
+    text-shadow: 0 0 46px rgba(53, 220, 185, 0.24);
+  }
+  .tagline {
+    position: relative;
+    z-index: 2;
+    margin: 24px 0 0;
+    max-width: 820px;
+    font-size: 29px;
+    line-height: 1.35;
+    color: #a9b9d8;
+    letter-spacing: -0.3px;
+  }
+  .flow {
+    position: relative;
+    z-index: 2;
+    display: grid;
+    grid-template-columns: 1fr 104px 1.18fr;
+    gap: 12px;
+    align-items: center;
+    margin-top: 48px;
+  }
+  .card {
+    min-height: 300px;
+    border-radius: 26px;
+    padding: 26px 26px 22px;
+    border: 1px solid rgba(130, 165, 230, 0.22);
+    background: linear-gradient(180deg, rgba(24, 38, 68, 0.86), rgba(12, 20, 38, 0.88));
+    box-shadow: 0 22px 60px rgba(0, 0, 0, 0.32), inset 0 1px 0 rgba(255,255,255,0.05);
+  }
+  .card.result {
+    border-color: rgba(75, 225, 193, 0.35);
+    background: linear-gradient(180deg, rgba(18, 53, 62, 0.62), rgba(10, 26, 35, 0.9));
+  }
+  .label {
+    font-family: Consolas, "Cascadia Code", monospace;
+    font-size: 14px;
+    letter-spacing: 2.6px;
+    color: #8094bb;
+    margin-bottom: 20px;
+  }
+  .result .label { color: #64d9c0; }
+  .quote {
+    font-size: 31px;
+    line-height: 1.32;
+    color: #e7edff;
+    letter-spacing: -0.5px;
+    margin: 8px 0 18px;
+  }
+  .muted {
+    font-size: 17px;
+    color: #7386aa;
+    line-height: 1.4;
+  }
+  .rline {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    margin: 13px 0;
+  }
+  .check {
+    width: 24px;
+    height: 24px;
+    border-radius: 8px;
+    display: grid;
+    place-items: center;
+    background: rgba(58, 221, 187, 0.14);
+    border: 1px solid rgba(58, 221, 187, 0.35);
+    color: #64e5cb;
+    font-size: 15px;
+    font-weight: 800;
+    flex: none;
+  }
+  .bar {
+    height: 10px;
+    border-radius: 99px;
+    background: linear-gradient(90deg, rgba(109, 145, 210, 0.75), rgba(109, 145, 210, 0.28));
+  }
+  .w90 { width: 90%; }
+  .w74 { width: 74%; }
+  .w82 { width: 82%; }
+  .w60 { width: 60%; }
+  .w68 { width: 68%; }
+  .arrow {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 10px;
+  }
+  .bolt {
+    width: 68px;
+    height: 68px;
+    border-radius: 22px;
+    display: grid;
+    place-items: center;
+    font-size: 36px;
+    background: linear-gradient(145deg, #47e3c5, #347dff);
+    color: #07111f;
+    box-shadow: 0 0 45px rgba(60, 220, 195, 0.28);
+  }
+  .arrow-line {
+    width: 2px;
+    height: 58px;
+    background: linear-gradient(to bottom, rgba(80, 225, 200, 0.7), rgba(80, 225, 200, 0));
+  }
+  .footer {
+    position: absolute;
+    z-index: 2;
+    left: 72px;
+    right: 72px;
+    bottom: 50px;
+    display: flex;
+    gap: 14px;
+    align-items: center;
+    font-family: Consolas, "Cascadia Code", monospace;
+    font-size: 16px;
+    color: #6d82a8;
+    letter-spacing: 0.4px;
+  }
+  .footer span {
+    padding: 7px 12px;
+    border-radius: 8px;
+    background: rgba(20, 34, 60, 0.62);
+    border: 1px solid rgba(120, 155, 220, 0.14);
+  }
+  .footer .accent { color: #67e5ca; }
+</style>
+</head>
+<body>
+  <div class="canvas">
+    <div class="glow g1"></div>
+    <div class="glow g2"></div>
+
+    <div class="top">
+      <div class="badge"><span class="dot"></span> OPENCODE DESKTOP PLUGIN</div>
+      <div class="version">v0.1.0</div>
+    </div>
+
+    <h1>opencode-<br /><span>prompt-expand</span></h1>
+    <p class="tagline">Turn rough drafts into structured prompts — in place, in your composer.</p>
+
+    <div class="flow">
+      <div class="card draft">
+        <div class="label">DRAFT</div>
+        <div class="quote">“修一下登录的 bug”</div>
+        <div class="bar w82" style="margin-bottom:12px"></div>
+        <div class="bar w60" style="margin-bottom:22px"></div>
+        <div class="muted">vague · missing scope<br />no acceptance criteria</div>
+      </div>
+
+      <div class="arrow">
+        <div class="bolt">⚡</div>
+        <div class="arrow-line"></div>
+      </div>
+
+      <div class="card result">
+        <div class="label">EXPANDED</div>
+        <div class="rline"><span class="check">✓</span><div class="bar w90"></div></div>
+        <div class="rline"><span class="check">✓</span><div class="bar w74"></div></div>
+        <div class="rline"><span class="check">✓</span><div class="bar w82"></div></div>
+        <div class="rline"><span class="check">✓</span><div class="bar w68"></div></div>
+        <div class="muted" style="margin-top:18px">goal · scope · constraints<br />output · acceptance</div>
+      </div>
+    </div>
+
+    <div class="footer">
+      <span>MIT licensed</span>
+      <span>BYOK</span>
+      <span class="accent">never auto-sends</span>
+    </div>
+  </div>
+</body>
+</html>