@hxnnxs/opencode-voice 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## 0.1.0 - 2026-06-12
+
+### Added
+
+- Initial OpenCode TUI voice input plugin.
+- Local `whisper.cpp` transcription flow with model selection and verified downloads.
+- Helper CLI for install guidance and local diagnostics.
+- Managed engine status/import/remove commands for local `whisper-cli`.
+- Managed engine auto-install from the opencode-voice GitHub Release registry.
+- GitHub Actions workflow for building and publishing `whisper-cli` engine assets.
+- Model verification markers so existing model files must pass SHA256 before activation.
+- GitHub Actions release check workflow.
+- npm packaging metadata and release checks.

package/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contributing
+
+Thanks for helping improve `opencode-voice`.
+
+## Development
+
+- Use Node.js 20 or newer.
+- Run `npm run check` before opening a change.
+- Run `npm pack --dry-run` before release-oriented changes.
+- Keep generated audio, downloaded models, and local logs out of git.
+
+This package has no build step. Runtime code is shipped directly from `index.js`, `lib/`, and `bin/`.
+
+## Release Checklist
+
+- Update `CHANGELOG.md` for user-visible changes.
+- Confirm `package.json` version and npm package contents.
+- Run `npm run check`.
+- Run `npm pack --dry-run` and inspect the file list.
+- Create the GitHub release from the matching tag.
+
+Do not publish prerelease artifacts as `latest` unless that is intentional.

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/PUBLISHING.md

@@ -0,0 +1,36 @@
+# Publishing
+
+## npm name
+
+The package publishes as `@hxnnxs/opencode-voice`.
+
+The unscoped npm name `opencode-voice` is already published by another author, so do not publish this project under the unscoped name.
+
+Before publishing:
+
+1. Confirm `package.json#name` is `@hxnnxs/opencode-voice`.
+2. Keep the OpenCode plugin id as `opencode-voice` unless you want users to see a different plugin id.
+3. Confirm published install examples in all `README*.md` files use `@hxnnxs/opencode-voice`.
+4. Create the GitHub repository `ihxnnxs/opencode-voice` and push `main`.
+5. Run the **Engine Release** GitHub Actions workflow first. It must publish:
+
+```txt
+https://github.com/ihxnnxs/opencode-voice/releases/download/v0.1.0/registry.json
+```
+
+6. Confirm the registry contains assets for the target release platforms.
+7. Run:
+
+```bash
+npm run check
+npm pack --dry-run --json
+npm publish --dry-run
+```
+
+## Release checklist
+
+- Confirm `bin/opencode-voice.js` is executable in `npm pack --dry-run --json` (`mode: 493`).
+- Confirm `opencode-voice engine install whisper.cpp` downloads and probes the managed engine from the release registry.
+- Confirm `opencode-voice doctor` reports a working managed engine probe.
+- Confirm model downloads write `.sha256` verification markers.
+- Tag the release after the GitHub Actions release check passes.

package/README.es.md

@@ -0,0 +1,174 @@
+<p align="center">
+  <a href="https://github.com/ihxnnxs/opencode-voice">
+    <picture>
+      <source srcset="assets/opencode-voice-dark.svg" media="(prefers-color-scheme: dark)">
+      <source srcset="assets/opencode-voice-light.svg" media="(prefers-color-scheme: light)">
+      <img src="assets/opencode-voice-light.svg" alt="opencode voice logo">
+    </picture>
+  </a>
+</p>
+<p align="center">Speech-to-text local para OpenCode TUI.</p>
+<p align="center">
+  <img alt="status" src="https://img.shields.io/badge/status-mvp-orange?style=flat-square" />
+  <img alt="license" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" />
+  <img alt="opencode" src="https://img.shields.io/badge/opencode-%3E%3D1.17.4-black?style=flat-square" />
+  <img alt="stt" src="https://img.shields.io/badge/STT-local_whisper.cpp-purple?style=flat-square" />
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> |
+  <a href="README.ru.md">Русский</a> |
+  <a href="README.zh.md">简体中文</a> |
+  <a href="README.es.md">Español</a>
+</p>
+
+---
+
+### Instalación
+
+Una sola orden mediante OpenCode:
+
+```bash
+opencode plugin @hxnnxs/opencode-voice
+```
+
+Reinicia OpenCode después de instalar. En el primer inicio, el plugin descarga el managed `whisper.cpp` engine y el modelo elegido. El usuario no instala `whisper-cli` manualmente.
+
+Instalador CLI opcional. Ejecuta el mismo comando de instalación de OpenCode y predescarga el managed engine:
+
+```bash
+npx @hxnnxs/opencode-voice install
+```
+
+No clones el repositorio salvo que quieras desarrollar el plugin.
+
+> [!TIP]
+> El primer inicio abre un selector de modelo. Elige un modelo Whisper, espera la descarga y usa `ctrl+r` para dictar en el prompt.
+
+### Requisitos
+
+El plugin gestiona el STT engine y los modelos:
+
+- descarga `whisper.cpp` desde el GitHub Release registry de opencode-voice
+- lo guarda en `~/.cache/opencode-voice/engines/whisper.cpp/<platform>-<arch>/`
+- descarga el modelo Whisper elegido durante el primer setup
+
+Instalar `whisper-cli` manualmente es opcional. Si ya existe un binary local, `opencode-voice` puede importarlo o usarlo.
+
+Comprueba tu máquina:
+
+```bash
+npx @hxnnxs/opencode-voice doctor
+```
+
+Instala el managed engine sin abrir OpenCode:
+
+```bash
+npx @hxnnxs/opencode-voice engine install whisper.cpp
+```
+
+### Uso
+
+Comandos:
+
+- `/voice` - alterna la grabación e inserta la transcripción
+- `/voice-submit` - alterna la grabación, inserta la transcripción y envía
+- `/voice-stop` - cancela la grabación o transcripción activa
+- `/voice-settings` - abre ajustes de modelo, hotkeys, micrófono y diagnóstico
+
+Hotkey por defecto:
+
+```txt
+ctrl+r -> iniciar grabación
+ctrl+r -> detener, transcribir e insertar texto
+```
+
+Hold-to-talk está desactivado por defecto porque los terminal release events cambian entre terminales. Puedes configurar un hotkey hold en `/voice-settings`.
+
+### Modelos
+
+Disponibles ahora mediante `whisper.cpp`:
+
+| Modelo               | Tamaño | Notas                         |
+| -------------------- | ------ | ----------------------------- |
+| Whisper Small        | 465 MB | por defecto, multilingue      |
+| Whisper Medium Q4_1  | 469 MB | mejor precisión               |
+| Whisper Turbo        | 1.5 GB | grande, más rápido que large completo |
+| Whisper Large Q5_0   | 1.0 GB | preciso, más lento            |
+
+Las descargas de modelos soportan resume, retry, progreso y verificación SHA256.
+
+Modelos sidecar planeados:
+
+- Parakeet V3
+- GigaAM v3
+- Moonshine V2 Small
+
+### Estado Por Plataforma
+
+| Plataforma | Estado |
+| ---------- | ------ |
+| Linux      | instalación engine/model en una orden; la grabación usa `arecord`, `ffmpeg` o `sox` |
+| macOS      | instalación engine/model en una orden; la grabación usa `ffmpeg` AVFoundation hasta el native recorder sidecar |
+| Windows    | ruta de descarga de engine lista; la grabación necesita el native recorder sidecar |
+
+### Arquitectura
+
+El paquete sigue la forma pública de plugin TUI que usan los plugins de la comunidad de OpenCode.
+
+- npm package exporta `./tui`
+- el desarrollo local puede apuntar `tui.json` a una ruta absoluta
+- la instalación publicada usa `opencode plugin @hxnnxs/opencode-voice`
+- runtime settings viven en OpenCode TUI plugin storage
+
+Archivos:
+
+- `index.js` - entrada TUI, comandos, dialogs, keymap layer
+- `lib/models.js` - registry de modelos, cache paths, default settings
+- `lib/download.js` - descarga resumible y verificación SHA256
+- `lib/engine.js` - selección de recorder y transcripción con `whisper-cli`
+- `lib/engines.js` - descarga, estado, importación y eliminación de managed native engine
+- `bin/opencode-voice.js` - install wrapper y diagnostics CLI
+
+La entrada por voz necesita native audio y STT binaries. El plugin JS gestiona OpenCode UI, settings, engine/model downloads y prompt insertion. Un native sidecar futuro debe reemplazar shell recorders y añadir fast VAD más Handy-style models.
+
+### Roadmap
+
+- publicar managed `whisper-cli` release assets antes del npm release
+- Rust recorder sidecar con `cpal` y VAD
+- soporte para Parakeet, GigaAM, SenseVoice, Canary y Moonshine
+- Windows recorder support
+- streaming-style transcription más rápida
+
+### Desarrollo
+
+Ejecuta las comprobaciones:
+
+```bash
+npm run check
+npm pack --dry-run
+```
+
+Este MVP no tiene build step.
+
+Instalación de desarrollo desde un checkout:
+
+```bash
+git clone https://github.com/ihxnnxs/opencode-voice.git opencode-voice
+cd opencode-voice
+opencode plugin "$(pwd)"
+```
+
+### Estado Del Proyecto
+
+Este es un OpenCode plugin independiente. No está construido por el equipo de OpenCode y no está afiliado con OpenCode.
+
+### Créditos
+
+- OpenCode wordmark SVG adaptado del [OpenCode repository](https://github.com/anomalyco/opencode). La marca `voice` se añadió para este plugin.
+- La transcripción local usa [`whisper.cpp`](https://github.com/ggml-org/whisper.cpp).
+- La metadata de descarga de modelos sigue el UX local-first investigado en [Handy](https://github.com/cjpais/Handy).
+
+---
+
+**OpenCode** [Website](https://opencode.ai) | [Docs](https://opencode.ai/docs) | [Discord](https://opencode.ai/discord)

package/README.md

@@ -0,0 +1,174 @@
+<p align="center">
+  <a href="https://github.com/ihxnnxs/opencode-voice">
+    <picture>
+      <source srcset="assets/opencode-voice-dark.svg" media="(prefers-color-scheme: dark)">
+      <source srcset="assets/opencode-voice-light.svg" media="(prefers-color-scheme: light)">
+      <img src="assets/opencode-voice-light.svg" alt="opencode voice logo">
+    </picture>
+  </a>
+</p>
+<p align="center">Local speech-to-text for the OpenCode TUI.</p>
+<p align="center">
+  <img alt="status" src="https://img.shields.io/badge/status-mvp-orange?style=flat-square" />
+  <img alt="license" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" />
+  <img alt="opencode" src="https://img.shields.io/badge/opencode-%3E%3D1.17.4-black?style=flat-square" />
+  <img alt="stt" src="https://img.shields.io/badge/STT-local_whisper.cpp-purple?style=flat-square" />
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> |
+  <a href="README.ru.md">Русский</a> |
+  <a href="README.zh.md">简体中文</a> |
+  <a href="README.es.md">Español</a>
+</p>
+
+---
+
+### Installation
+
+One command through OpenCode:
+
+```bash
+opencode plugin @hxnnxs/opencode-voice
+```
+
+Restart OpenCode after installing. First launch downloads the managed `whisper.cpp` engine and then the selected model. The user does not install `whisper-cli` manually.
+
+Optional CLI installer. It runs the same OpenCode plugin install command and pre-downloads the managed engine:
+
+```bash
+npx @hxnnxs/opencode-voice install
+```
+
+Do not clone the repo unless you want to develop the plugin.
+
+> [!TIP]
+> First launch opens a model picker. Choose a Whisper model, let it download, then use `ctrl+r` to dictate into the prompt.
+
+### Requirements
+
+The plugin manages the STT engine and models:
+
+- downloads `whisper.cpp` from the opencode-voice GitHub Release registry
+- stores it in `~/.cache/opencode-voice/engines/whisper.cpp/<platform>-<arch>/`
+- downloads the selected Whisper model on first setup
+
+Manual `whisper-cli` install is optional. If a local binary already exists, `opencode-voice` can still import or use it.
+
+Check your machine:
+
+```bash
+npx @hxnnxs/opencode-voice doctor
+```
+
+Install the managed engine without opening OpenCode:
+
+```bash
+npx @hxnnxs/opencode-voice engine install whisper.cpp
+```
+
+### Usage
+
+Commands:
+
+- `/voice` - toggle recording and append transcription
+- `/voice-submit` - toggle recording, append transcription, and submit
+- `/voice-stop` - cancel active recording or transcription
+- `/voice-settings` - open model, hotkey, microphone, and diagnostics settings
+
+Default hotkey:
+
+```txt
+ctrl+r -> start recording
+ctrl+r -> stop, transcribe, and append
+```
+
+Hold-to-talk is disabled by default because terminal release events vary by terminal. You can still configure a hold hotkey in `/voice-settings`.
+
+### Models
+
+Available now through `whisper.cpp`:
+
+| Model                | Size   | Notes                         |
+| -------------------- | ------ | ----------------------------- |
+| Whisper Small        | 465 MB | default, multilingual         |
+| Whisper Medium Q4_1  | 469 MB | better accuracy               |
+| Whisper Turbo        | 1.5 GB | large, faster than full large |
+| Whisper Large Q5_0   | 1.0 GB | accurate, slower              |
+
+Model downloads support resume, retry, progress, and SHA256 verification.
+
+Planned sidecar models:
+
+- Parakeet V3
+- GigaAM v3
+- Moonshine V2 Small
+
+### Platform Status
+
+| Platform | Status |
+| -------- | ------ |
+| Linux    | one-command engine/model install; recording uses `arecord`, `ffmpeg`, or `sox` |
+| macOS    | one-command engine/model install; recording uses `ffmpeg` AVFoundation until the native recorder sidecar ships |
+| Windows  | engine download path ready; recording needs the native recorder sidecar |
+
+### Architecture
+
+The package follows the public OpenCode TUI plugin shape used by community plugins.
+
+- npm package exports `./tui`
+- local development can point `tui.json` at an absolute path
+- published install uses `opencode plugin @hxnnxs/opencode-voice`
+- runtime settings live in OpenCode TUI plugin storage
+
+Files:
+
+- `index.js` - TUI plugin entrypoint, commands, dialogs, keymap layer
+- `lib/models.js` - model registry, cache paths, default settings
+- `lib/download.js` - resumable model download and SHA256 verification
+- `lib/engine.js` - recorder selection and `whisper-cli` transcription
+- `lib/engines.js` - managed native engine download, status, import, and removal
+- `bin/opencode-voice.js` - install wrapper and diagnostics CLI
+
+Voice input needs native audio and STT binaries. The JS plugin manages OpenCode UI, settings, engine/model downloads, and prompt insertion. A future native sidecar should replace shell recorders and add fast VAD plus Handy-style models.
+
+### Roadmap
+
+- publish managed `whisper-cli` release assets before npm release
+- Rust recorder sidecar with `cpal` and VAD
+- Parakeet, GigaAM, SenseVoice, Canary, and Moonshine model support
+- Windows recorder support
+- faster streaming-style transcription
+
+### Development
+
+Run checks:
+
+```bash
+npm run check
+npm pack --dry-run
+```
+
+This MVP has no build step.
+
+Development install from a checkout:
+
+```bash
+git clone https://github.com/ihxnnxs/opencode-voice.git opencode-voice
+cd opencode-voice
+opencode plugin "$(pwd)"
+```
+
+### Project Status
+
+This is an independent OpenCode plugin. It is not built by the OpenCode team and is not affiliated with OpenCode.
+
+### Credits
+
+- OpenCode wordmark SVG adapted from the public [OpenCode repository](https://github.com/anomalyco/opencode). The `voice` mark was added for this plugin.
+- Local transcription uses [`whisper.cpp`](https://github.com/ggml-org/whisper.cpp).
+- Model download metadata follows the local-first UX researched from [Handy](https://github.com/cjpais/Handy).
+
+---
+
+**OpenCode** [Website](https://opencode.ai) | [Docs](https://opencode.ai/docs) | [Discord](https://opencode.ai/discord)

package/README.ru.md

@@ -0,0 +1,174 @@
+<p align="center">
+  <a href="https://github.com/ihxnnxs/opencode-voice">
+    <picture>
+      <source srcset="assets/opencode-voice-dark.svg" media="(prefers-color-scheme: dark)">
+      <source srcset="assets/opencode-voice-light.svg" media="(prefers-color-scheme: light)">
+      <img src="assets/opencode-voice-light.svg" alt="opencode voice logo">
+    </picture>
+  </a>
+</p>
+<p align="center">Локальный speech-to-text для OpenCode TUI.</p>
+<p align="center">
+  <img alt="status" src="https://img.shields.io/badge/status-mvp-orange?style=flat-square" />
+  <img alt="license" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" />
+  <img alt="opencode" src="https://img.shields.io/badge/opencode-%3E%3D1.17.4-black?style=flat-square" />
+  <img alt="stt" src="https://img.shields.io/badge/STT-local_whisper.cpp-purple?style=flat-square" />
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> |
+  <a href="README.ru.md">Русский</a> |
+  <a href="README.zh.md">简体中文</a> |
+  <a href="README.es.md">Español</a>
+</p>
+
+---
+
+### Установка
+
+Одна команда через OpenCode:
+
+```bash
+opencode plugin @hxnnxs/opencode-voice
+```
+
+Перезапустите OpenCode после установки. При первом запуске плагин сам скачает managed `whisper.cpp` engine и выбранную модель. Пользователь не ставит `whisper-cli` руками.
+
+Опциональный CLI-установщик. Он запускает ту же установку через OpenCode и заранее скачивает managed engine:
+
+```bash
+npx @hxnnxs/opencode-voice install
+```
+
+Не клонируйте репозиторий, если не собираетесь разрабатывать плагин.
+
+> [!TIP]
+> При первом запуске откроется выбор модели. Выберите Whisper-модель, дождитесь загрузки и используйте `ctrl+r`, чтобы диктовать в prompt.
+
+### Требования
+
+Плагин сам управляет STT engine и моделями:
+
+- скачивает `whisper.cpp` из GitHub Release registry проекта
+- кладет его в `~/.cache/opencode-voice/engines/whisper.cpp/<platform>-<arch>/`
+- скачивает выбранную Whisper-модель при первом setup
+
+Ручная установка `whisper-cli` не нужна. Если локальный binary уже есть, `opencode-voice` всё ещё может импортировать или использовать его.
+
+Проверить машину:
+
+```bash
+npx @hxnnxs/opencode-voice doctor
+```
+
+Установить managed engine без открытия OpenCode:
+
+```bash
+npx @hxnnxs/opencode-voice engine install whisper.cpp
+```
+
+### Использование
+
+Команды:
+
+- `/voice` - переключить запись и вставить транскрипцию
+- `/voice-submit` - переключить запись, вставить транскрипцию и отправить
+- `/voice-stop` - отменить активную запись или транскрибацию
+- `/voice-settings` - открыть настройки модели, хоткеев, микрофона и диагностики
+
+Хоткей по умолчанию:
+
+```txt
+ctrl+r -> начать запись
+ctrl+r -> остановить, распознать и вставить текст
+```
+
+Hold-to-talk отключен по умолчанию, потому что terminal release events зависят от терминала. Его можно включить в `/voice-settings`.
+
+### Модели
+
+Доступно сейчас через `whisper.cpp`:
+
+| Модель              | Размер | Примечание                    |
+| ------------------- | ------ | ----------------------------- |
+| Whisper Small       | 465 MB | дефолт, multilingual          |
+| Whisper Medium Q4_1 | 469 MB | выше точность                 |
+| Whisper Turbo       | 1.5 GB | крупная, быстрее full large   |
+| Whisper Large Q5_0  | 1.0 GB | точная, медленнее             |
+
+Загрузка моделей поддерживает resume, retry, progress и SHA256 verification.
+
+Запланированные sidecar-модели:
+
+- Parakeet V3
+- GigaAM v3
+- Moonshine V2 Small
+
+### Статус платформ
+
+| Платформа | Статус |
+| --------- | ------ |
+| Linux     | one-command engine/model install; запись использует `arecord`, `ffmpeg` или `sox` |
+| macOS     | one-command engine/model install; запись использует `ffmpeg` AVFoundation до native recorder sidecar |
+| Windows   | путь скачивания engine готов; recording ждёт native recorder sidecar |
+
+### Архитектура
+
+Пакет повторяет публичную форму OpenCode TUI-плагинов, которую используют community-плагины.
+
+- npm package экспортирует `./tui`
+- локальная разработка может указать абсолютный путь в `tui.json`
+- published install использует `opencode plugin @hxnnxs/opencode-voice`
+- runtime settings хранятся в OpenCode TUI plugin storage
+
+Файлы:
+
+- `index.js` - TUI entrypoint, команды, dialogs, keymap layer
+- `lib/models.js` - registry моделей, cache paths, default settings
+- `lib/download.js` - resumable download и SHA256 verification
+- `lib/engine.js` - выбор recorder и transcription через `whisper-cli`
+- `lib/engines.js` - managed native engine download, status, import и removal
+- `bin/opencode-voice.js` - install wrapper и diagnostics CLI
+
+Voice input требует native audio и STT binaries. JS-плагин управляет OpenCode UI, settings, engine/model downloads и prompt insertion. Будущий native sidecar должен заменить shell recorders и добавить fast VAD плюс Handy-style models.
+
+### Roadmap
+
+- опубликовать managed `whisper-cli` release assets перед npm release
+- Rust recorder sidecar с `cpal` и VAD
+- поддержка Parakeet, GigaAM, SenseVoice, Canary и Moonshine
+- Windows recorder support
+- более быстрая streaming-style transcription
+
+### Разработка
+
+Запустить проверки:
+
+```bash
+npm run check
+npm pack --dry-run
+```
+
+У этого MVP нет build step.
+
+Установка из checkout для разработки:
+
+```bash
+git clone https://github.com/ihxnnxs/opencode-voice.git opencode-voice
+cd opencode-voice
+opencode plugin "$(pwd)"
+```
+
+### Статус проекта
+
+Это независимый OpenCode plugin. Его не разрабатывает команда OpenCode, и он не связан с OpenCode официально.
+
+### Кредиты
+
+- OpenCode wordmark SVG адаптирован из публичного [OpenCode repository](https://github.com/anomalyco/opencode). Метка `voice` добавлена для этого плагина.
+- Локальная транскрибация использует [`whisper.cpp`](https://github.com/ggml-org/whisper.cpp).
+- Metadata загрузки моделей следует local-first UX, изученному в [Handy](https://github.com/cjpais/Handy).
+
+---
+
+**OpenCode** [Website](https://opencode.ai) | [Docs](https://opencode.ai/docs) | [Discord](https://opencode.ai/discord)