opencode-summary 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 frostehhh
+
+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,158 @@
-# Temporary Holding Version
+# opencode-summary
 
-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.
+[![CI](https://github.com/frostehhh/opencode-summary/actions/workflows/ci.yml/badge.svg)](https://github.com/frostehhh/opencode-summary/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/opencode-summary.svg)](https://www.npmjs.com/package/opencode-summary)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+TUI plugin for [opencode](https://opencode.ai) V2. `/summary` opens a modal that generates and shows a summary of the
+current session using `session.generate` (the session's current model; the conversation history is not changed). The
+summary is stored in session metadata (`metadata["opencode-summary"]`), and a footer indicator shows how many turns ago
+it was made.
+
+## Install
+
+### From npm (recommended)
+
+```sh
+opencode plugin add opencode-summary
+```
+
+Or add it to your TUI config (`cli.json`) yourself, since it is a TUI-only plugin:
+
+```json
+{ "plugins": ["opencode-summary"] }
+```
+
+Pin a version with `opencode-summary@0.1.0`. Without a version, opencode checks for updates; run
+`opencode plugin update opencode-summary` to update.
+
+### From GitHub
+
+```sh
+opencode plugin add github:frostehhh/opencode-summary#v0.1.0
+```
+
+Replace `v0.1.0` with the [release](https://github.com/frostehhh/opencode-summary/releases) you want. Omit the `#tag`
+to follow the default branch.
+
+Restart opencode after installing.
+
+### Local development
+
+Clone the repo and symlink it into the global plugin directory, where the TUI discovers it:
+
+```sh
+git clone https://github.com/frostehhh/opencode-summary
+ln -s "$PWD/opencode-summary" ~/.config/opencode/plugins/opencode-summary
+```
+
+Edits hot-reload in a running TUI.
+
+## Usage
+
+Run `/summary` (or "Open summary modal" in the command palette) inside a session.
+
+| Key | Action |
+|---|---|
+| `g` | generate a summary |
+| `v` | toggle prompt view |
+| `c` | copy the summary (summary view) |
+| `e` | edit the prompt (prompt view) |
+| `r` | reset the prompt (prompt view) |
+| `j`/`k`, `↑`/`↓` | scroll |
+| `esc` | close |
+
+Bind a global key in `cli.json` with `keybinds`: `{"summary.open": "<key>"}`.
+
+### Commands
+
+Palette group "Summary". Only the first has a slash command.
+
+| Command | Id | Does |
+|---|---|---|
+| Open summary modal | `summary.open` (`/summary`) | opens the modal |
+| Generate summary | `summary.generate` | generates without the modal |
+| Copy summary | `summary.copy` | copies the stored summary |
+| Delete summary | `summary.delete` | removes the stored summary, after confirm |
+| View summary prompt | `summary.prompt.view` | modal in prompt view |
+| Edit summary prompt | `summary.prompt.edit` | `$VISUAL`/`$EDITOR`, else modal editor |
+| Reset summary prompt | `summary.prompt.reset` | deletes the override, after confirm |
+| Toggle summary footer indicator | `summary.indicator.toggle` | hides or shows `summary N turns ago` (the spinner stays) |
+
+The indicator setting is persisted, so it survives restarts.
+
+## Prompt
+
+The default prompt is in [`src/prompt.ts`](src/prompt.ts). Your own prompt is stored at:
+
+```
+$XDG_CONFIG_HOME/opencode/opencode-summary/summary.md   # default: ~/.config/opencode/opencode-summary/summary.md
+```
+
+This lives outside the plugin, so it survives plugin updates. A fixed line forbidding tool calls is always prepended
+and cannot be edited. `e` opens `$VISUAL`/`$EDITOR` on the file; if neither is set, a multi-line editor opens in the
+modal (`ctrl+s` save, `esc` cancel). `r` deletes the override.
+
+## Development
+
+```sh
+bun install
+bun test
+bun run build   # compiles src/tui.tsx -> dist/tui.js
+```
+
+opencode does not compile `.tsx` files inside `node_modules`, so the package ships the compiled `dist/tui.js`
+(`exports["./tui"]`). `dist/` is committed so `github:` installs work, and CI fails if it is out of date: run
+`bun run build` (Bun 1.3.11, the version CI pins, so output is identical) and commit `dist/` together with your `src/` change. For local development, the symlink points at the
+repo, so use `dist/tui.js` via `bun run build`, or point your plugin config at `src/tui.tsx` directly.
+
+`src/lib.ts` is pure and must not import opencode packages; `test/lib.test.ts` covers it. `src/tui.tsx` is checked
+manually with the checklist below.
+
+### Manual checklist
+
+- [ ] `/summary` in slash completion and palette; on home shows "Open a session first"
+- [ ] `g` shows the summary and "Generated …"; it persists after a TUI restart; `c` copies the markdown
+- [ ] Footer: `summary up to date` after `g`, then `summary N turns ago` as messages are sent
+- [ ] `g` then `esc`: footer spinner, then toast "Summary ready"; `g` mid-run shows "Already generating"
+- [ ] Revert and fork behave as described in the design docs
+- [ ] `e`/`r` only in prompt view, `c` only in summary view
+- [ ] Prompt edit with `$EDITOR` set and unset; saved file appears at the override path above; `r` removes it
+- [ ] Palette "Summary" lists all eight commands; only "Open summary modal" has `/summary`
+- [ ] Toggle footer indicator hides/shows the label and persists after restart
+
+## Contributing
+
+Commits and PR titles follow [Conventional Commits](https://www.conventionalcommits.org/), enforced by
+[commitlint](https://commitlint.js.org/) (a `commit-msg` hook locally, and CI on pull requests).
+
+```
+<type>(<optional scope>): <description>
+
+feat: add a new capability              -> minor bump
+fix: correct a bug                      -> patch bump
+feat!: change behavior incompatibly     -> breaking (minor while < 1.0)
+docs | refactor | test | chore | ci | build | perf | style
+```
+
+## Releasing
+
+Versions follow [SemVer](https://semver.org/) and are derived from commit messages by
+[release-please](https://github.com/googleapis/release-please). While the version is `0.x`, `feat` bumps the minor
+version and `fix` bumps the patch.
+
+1. Merge changes to `main` using conventional commits.
+2. release-please opens or updates a "chore(main): release x.y.z" PR with the version bump and `CHANGELOG.md`.
+3. Merge that PR: it creates the `vX.Y.Z` tag and a GitHub Release.
+
+Repository setting required once: **Settings → Actions → General → "Allow GitHub Actions to create and approve pull
+requests"**.
+
+## Design docs
+
+The design, plan and research for this plugin live in the
+[`ai-tools`](https://github.com/frostehhh/ai-tools/tree/main/openspec/changes/create-opencode-summary-plugin) repo.
+
+## License
+
+[MIT](LICENSE)