opencode-docker-panel 0.4.8

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this plugin, by version and date. The version is the one in `package.json` at
+that commit.
+
+## 0.4.8 - 2026-10-04
+
+- The package now ships precompiled ESM: `npm run build` transpiles the sources with the same
+  Solid options OpenTUI's own transform uses, and `exports["./tui"]` points at `dist/tui.js`
+- `react` dropped: the panel never imported it, and the host rewrites `@opentui/solid` and
+  `solid-js` to its own runtime when a package under `node_modules` ships JavaScript
+- Peer dependencies stay optional, so npm never writes a second Solid or OpenTUI copy next to
+  the plugin
+- `check-build` verifies the built entry imports, claims `sidebar.content`, and releases it on
+  cleanup
+
+## 0.4.1 — 2026-10-04
+
+- `react` added to peer dependencies, so the panel loads from npm
+
+## 0.4.0 — 2026-10-04
+
+- Sidebar draws running containers only, at most five, with the header opening the full list
+- `Pin` and `Unpin` per container, stored by the host and surviving a TUI restart
+- `Up stack` starts a compose project from the agent directory, only when the file provably declares
+  the clicked container's project
+- An unstarted stack in the agent directory gets its own line under the rows
+- Packaged for npm: `files` allowlist, peer dependencies, repository metadata, npm install docs
+- Readme trimmed to what a user needs, with the working install path first
+
+## 0.3.0 — 2026-09-30
+
+- `Start`, `Restart`, `Stop` and `Down compose project` per container, with `Down` confirming first
+- Log view in the same dialog, `docker logs --timestamps --tail 200`, streams merged by timestamp
+- Terminal recording added to the readme
+- CI running typecheck and parser checks on both Linux and Windows
+
+## 0.2.0 — 2026-09-29
+
+- Loads as a CLI-only plugin, no `@opencode/plugin` import at runtime
+- A poll that reports no containers clears the panel instead of keeping stale rows
+
+## 0.1.0 — 2026-09-29
+
+- First version: Docker containers in the `sidebar.content` slot, polled from `docker ps`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victor Ochenin
+
+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

@@ -0,0 +1,194 @@
+# opencode-docker-panel
+
+[![CI](https://github.com/victor-ochenin/opencodeDockerPlugin/actions/workflows/ci.yml/badge.svg)](https://github.com/victor-ochenin/opencodeDockerPlugin/actions/workflows/ci.yml)
+
+A Docker container panel for the OpenCode 2 TUI sidebar.
+
+The panel appends itself to the `sidebar.content` slot, polls `docker ps --all --format "{{json .}}"`, and lets you act on a container from the row itself. Clicking a row opens a dialog with the actions docker accepts for that container's current state; `Down` is the only one that asks for confirmation.
+
+Русская версия этого файла: [README.ru.md](README.ru.md)
+
+![The Docker panel in the session sidebar, with an unstarted compose stack from the agent directory](docs/demo2.gif)
+
+## Contents
+
+- [What it does](#what-it-does)
+- [Compose stacks](#compose-stacks)
+- [Logs](#logs)
+- [What it shows](#what-it-shows)
+- [Requirements](#requirements)
+- [Install](#install)
+  - [Option A: let an LLM do it](#option-a-let-an-llm-do-it)
+  - [Option B: manual setup](#option-b-manual-setup)
+  - [From a local checkout](#from-a-local-checkout)
+  - [Verification](#verification)
+- [Options](#options)
+- [Known limits](#known-limits)
+- [Changelog](#changelog)
+- [License](#license)
+
+## What it does
+
+```text
+Docker (2)
+• api           0.0.0.0:8080->8080/tcp · shop
+1 more, click for all
+Up stack · storefront is not running here
+```
+
+| Container state | Actions offered |
+|---|---|
+| `running`, `restarting`, `paused` | `Restart`, `Stop`, and `Down` when the container belongs to a compose project |
+| `created`, `exited`, `dead` | `Start`, `Up stack` when the agent directory holds a matching compose file, and `Down` when the container belongs to a compose project |
+| anything else | none |
+
+| Action | Command |
+|---|---|
+| Start | `docker start -- <name>` |
+| Up stack | `docker compose -f <file> -p <project> up -d` |
+| Restart | `docker restart -- <name>` |
+| Stop | `docker stop -- <name>` |
+| Down | `docker compose -p <project> down` |
+
+`--` is not optional: a container name may start with a dash, and without the separator docker reads it as a flag. Every option shows its exact command in the dialog footer, so the destructive one is never a surprise.
+
+## Compose stacks
+
+`Up stack` starts a whole compose project instead of one container, using the compose file that sits in the agent directory. That file is executable content: it carries `build`, `command` and `entrypoint`, which is why the dialog shows the exact command before you run it, and why `up` needs no confirmation while `down` does.
+
+The button appears only when the file provably belongs to the project of the container you clicked. The project name is read the way compose v2 reads it: a top-level `name:` if there is one, otherwise the name of the directory holding the file. It must equal the `com.docker.compose.project` label on the container, and the container must not be running already. Anything else and the button is simply absent, because a wrong stack is worse than no button.
+
+A stack that has no containers at all is the normal state of something never started, and it gets its own way in. When the agent directory holds a compose file and no container on the machine carries that project label, the panel adds a line under the rows:
+
+```text
+Up stack · storefront is not running here
+```
+
+Clicking it asks once, showing the exact command before anything runs, because a compose file is executable content and this stack has no container to name it. The line disappears as soon as one container of that project shows up, because from then on the per-container `Up stack` is the way in. Nothing is offered for a Dockerfile on its own: there is no image name to run, so the panel would be guessing.
+
+The project is passed twice, as `-f <file>` and `-p <project>`. The name inside a compose file can be templated or overridden by the environment, and `-p` makes sure the stack you start is the one the panel was already showing rather than a second copy of it.
+
+Candidate file names are tried in compose's own order: `compose.yaml`, `compose.yml`, `docker-compose.yaml`, `docker-compose.yml`. The first file that exists wins even when it declares another project, because that is the file compose itself would use, so falling through to the next candidate would offer a stack the CLI ignores.
+
+`Down` runs `docker compose down` against the compose project the container carries in its labels, which stops every container of that project and removes their networks. Volumes are kept, and the confirmation dialog says so. A container with no compose project never gets the option, and `buildArgs` refuses it as well.
+
+The result of every action arrives as a toast, and the panel refreshes immediately instead of waiting for the next poll. While a command runs the header shows `working` and further clicks are ignored, so a double click cannot launch two commands.
+
+## Logs
+
+`Logs` in the same menu replaces the dialog contents with a log view for that container, so the log and the actions share one window. It closes with `esc` or by clicking the footer line.
+
+The view is `docker logs --timestamps --tail 200 -- <name>`, refreshed every two seconds while it is open. Docker interleaves the container's two streams, so the two buffers are parsed separately and merged back by timestamp; without that the log reads all of stdout first. ANSI sequences and lone `CR` are stripped, because the terminal would otherwise run them as control codes. A fixed window of fifteen lines is scrolled with the mouse wheel.
+
+## What it shows
+
+The dot is coloured by container state: green for `running`, yellow for `paused` and `restarting`, red for `dead`, muted for everything else. The panel draws running containers and nothing else, at most five rows in the order docker reports them, so the list does not jump between polls. Stopped containers never get a row of their own: the header opens a dialog with every container, and picking one there opens the same actions as a click on its row. A `N more, click for all` line appears under the rows when something is still hidden. With rows to show, the header collapses and expands them instead.
+
+`Pin` in a container's menu keeps that container visible whatever its state, and it spends the five row budget when it happens to run, so pinning everything shows everything. A pin is stored by the host, so it survives a TUI restart and applies to every session; `Unpin` in the same menu drops it. Pinned rows are marked `pinned` next to their ports and project.
+
+| State | Panel output |
+|---|---|
+| Docker up with containers | `Docker (N)` plus one row per container |
+| Docker up, nothing created | `no containers` |
+| Docker Desktop not running | `docker desktop not running` |
+| Docker not installed | `docker not installed` |
+| `docker ps` timed out | last known rows with a `stale` marker |
+| No permission on the Docker socket | `no permission to talk to docker` |
+
+A missing or stopped Docker is a normal state, not a plugin failure, so it is reported as a muted line rather than an error. Any failed poll, whether a timeout or a dead daemon, keeps the last known rows with a `stale` marker instead of blanking the panel; a successful poll that reports no containers clears the list.
+
+## Requirements
+
+- OpenCode 2 runtime with plugin slots (`opencode2`)
+- `docker` on `PATH`: Docker Desktop on Windows, Docker Engine on Linux and macOS
+
+The panel's own strings are English only; the documentation is bilingual.
+
+## Install
+
+### Option A: let an LLM do it
+
+Paste this into any agent (Claude Code, OpenCode, Cursor, and so on):
+
+```text
+Install the opencode-docker-panel Docker sidebar plugin by following
+https://github.com/victor-ochenin/opencodeDockerPlugin#installation
+```
+
+### Option B: manual setup
+
+Add the plugin to `~/.config/opencode/cli.json`. Create the file if it does not exist and keep whatever is already in it.
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/v2/cli.json",
+  "plugins": [{ "package": "opencode-docker-panel", "options": { "intervalMs": 3000 } }]
+}
+```
+
+Two things trip people up here, so they are worth stating plainly:
+
+- **It goes in `cli.json`, not `opencode.json`.** This is a terminal-only plugin: it draws in the sidebar, and `cli.json` is the file the terminal client reads.
+- **There is no login step and no provider to configure.** It talks to the local `docker` CLI and nothing else.
+
+Restart the TUI afterwards. The host installs the package on the next start; nothing to copy and nothing to build.
+
+Pin a version when you want a known state: `{ "package": "opencode-docker-panel@0.4.1" }`.
+
+### From a local checkout
+
+To run the plugin straight from a clone instead, copy the files into the OpenCode config directory. On Windows that is `%USERPROFILE%\.config\opencode\plugins\docker-panel\`.
+
+```powershell
+$src = "path\to\opencodeDockerPlugin"
+$dst = "$HOME\.config\opencode\plugins\docker-panel"
+New-Item -ItemType Directory -Force -Path $dst | Out-Null
+Copy-Item "$src\*.ts","$src\*.tsx","$src\package.json" -Destination $dst -Force
+```
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/v2/cli.json",
+  "plugins": [{ "package": "./plugins/docker-panel", "options": { "intervalMs": 3000 } }]
+}
+```
+
+The package ships TypeScript sources and OpenCode resolves them at runtime, so there is no build step. `solid-js`, the OpenTUI packages and the OpenCode SDK are peer dependencies rather than hard dependencies, so a second copy of the SDK cannot shadow the one the host is running.
+
+### Verification
+
+There is no CLI check for this one: the plugin draws in the terminal UI, so `opencode run` will never show it. Verify in the TUI.
+
+1. `docker ps` returns at least one container. If it fails, the panel has nothing to draw and says so.
+2. Restart the TUI and open a session.
+3. The sidebar gets a `Docker` header with a container count. Running containers appear as rows, at most five of them, with a `N more, click for all` line under them when something is still hidden.
+4. Collapse the list with a click on `Docker`, then click it again to open the full list. Pick a container to get its actions menu.
+
+If the header never appears, the plugin did not load: check that the entry is in `cli.json` under `plugins`, and check `~/.local/share/opencode/log/opencode.log` for a load error.
+
+## Options
+
+| Option | Default | Notes |
+|---|---|---|
+| `intervalMs` | `3000` | Poll interval, clamped to 1000..60000 |
+
+## Known limits
+
+- The sidebar draws containers that are `running` and nothing else. A `paused` or `restarting` container gets no row even though docker still counts it as alive; pin it to see it.
+- OpenCode 2 is in beta, so slot names and theme tokens may change.
+- A repaint workaround resets the collapsed state and closes an open log view when the container list really changes.
+- The poll spawns `docker ps` on an interval. On a host with hundreds of containers, raise `intervalMs` to 5000 or higher.
+- At most five running containers get a row, and the five is a constant rather than an option: a host with thirty containers shows five and leaves the rest to the dialog. Pinning is the only way to promote a sixth.
+- The sidebar itself cannot scroll, so the containers past the five live in the dialog rather than in the panel.
+- No exec, no volume or image actions, no restart history. `Down` is offered per container but acts on the whole compose project. The log view is a fixed window over the last 200 lines with no history beyond that.
+- `Up stack` only ever starts a stack whose compose file sits in the agent directory. A project that was created somewhere else can still be torn down with `Down`, but it can only be started with `Start` on a single container.
+- `Up stack` may stay hidden when the compose file declares its project in a form the panel cannot read, such as an indented `name:` or a quoted value. That is a refusal rather than a wrong stack.
+- Actions are mouse-only; the plugin registers no keymap layer.
+
+## Changelog
+
+Versions and dates are in [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT

package/README.ru.md

@@ -0,0 +1,194 @@
+# opencode-docker-panel
+
+[![CI](https://github.com/victor-ochenin/opencodeDockerPlugin/actions/workflows/ci.yml/badge.svg)](https://github.com/victor-ochenin/opencodeDockerPlugin/actions/workflows/ci.yml)
+
+Панель контейнеров Docker для бокового сайдбара OpenCode 2.
+
+Плагин добавляет себя в слот `sidebar.content`, опрашивает `docker ps --all --format "{{json .}}"` и позволяет действовать с контейнером прямо из строки. Клик по строке открывает диалог с командами, которые docker принимает в текущем состоянии контейнера, и только `Down` спрашивает подтверждение.
+
+English version of this file: [README.md](README.md)
+
+![Панель Docker в сайдбаре сессии с незапущенным compose-стеком из каталога агента](docs/demo2.gif)
+
+## Содержание
+
+- [Что показывает панель](#что-показывает-панель)
+- [Действия](#действия)
+- [Compose-стек](#compose-стек)
+- [Логи](#логи)
+- [Требования](#требования)
+- [Установка](#установка)
+  - [Вариант A: пусть сделает LLM](#вариант-a-пусть-сделает-llm)
+  - [Вариант B: вручную](#вариант-b-вручную)
+  - [Из локального клона](#из-локального-клона)
+  - [Проверка](#проверка)
+- [Опции](#опции)
+- [Ограничения](#ограничения)
+- [Изменения](#изменения)
+- [Лицензия](#лицензия)
+
+## Что показывает панель
+
+```text
+Docker (2)
+• api           0.0.0.0:8080->8080/tcp · shop
+1 more, click for all
+Up stack · storefront is not running here
+```
+
+Цвет точки зависит от состояния: зелёный для `running`, жёлтый для `paused` и `restarting`, красный для `dead`, приглушённый для остальных. Панель рисует только запущенные контейнеры, не больше пяти строк в том порядке, в котором их отдаёт docker, поэтому список не прыгает между опросами. Остановленным контейнерам строки не достаётся: вход в них — заголовок, он открывает диалог со всеми контейнерами, а выбор контейнера там открывает те же действия, что и клик по его строке. Строка `N more, click for all` стоит под строками, если что-то ещё скрыто. Когда строки есть, заголовок сворачивает и разворачивает их.
+
+Пункт `Pin` в меню контейнера оставляет контейнер видимым независимо от состояния, и на запущенном он занимает место в бюджете из пяти строк, поэтому закрепив всё, видно всё. Закрепление хранит хост, поэтому оно переживает перезапуск TUI и действует во всех сессиях; пункт `Unpin` в том же меню снимает его. Закреплённые строки помечены `pinned` рядом с портами и проектом.
+
+| Состояние панели | Что видно |
+|---|---|
+| Docker работает, есть контейнеры | `Docker (N)` и по строке на контейнер |
+| Docker работает, контейнеров нет | `no containers` |
+| Docker Desktop не запущен | `docker desktop not running` |
+| Docker не установлен | `docker not installed` |
+| `docker ps` не ответил вовремя | последние известные строки с пометкой `stale` |
+| Нет прав на сокет Docker | `no permission to talk to docker` |
+
+Остановленный или отсутствующий Docker — это нормальное состояние, а не поломка плагина, поэтому оно показывается приглушённой строкой, а не ошибкой. Любой неудачный опрос, будь то таймаут или мёртвый демон, сохраняет последние известные строки с пометкой `stale`; успешный опрос без контейнеров очищает список.
+
+## Действия
+
+| Состояние контейнера | Какие действия предлагаются |
+|---|---|
+| `running`, `restarting`, `paused` | `Restart`, `Stop` и `Down`, если контейнер принадлежит compose-проекту |
+| `created`, `exited`, `dead` | `Start`, `Up stack`, если в каталоге агента лежит подходящий compose-файл, и `Down`, если контейнер принадлежит compose-проекту |
+| любое другое | ничего |
+
+| Действие | Команда |
+|---|---|
+| Start | `docker start -- <имя>` |
+| Up stack | `docker compose -f <файл> -p <проект> up -d` |
+| Restart | `docker restart -- <имя>` |
+| Stop | `docker stop -- <имя>` |
+| Down | `docker compose -p <проект> down` |
+
+Разделитель `--` обязателен: имя контейнера может начинаться с дефиса, и без разделителя docker примет его за флаг. Точная команда показана в подписи каждого пункта, поэтому разрушительная не выглядит сюрпризом.
+
+`Down` выполняет `docker compose down` для compose-проекта из лейблов контейнера: останавливает все контейнеры проекта и удаляет их сети. Тома остаются, о чём и говорит диалог подтверждения. Контейнеру без compose-проекта пункт не предлагается, и `buildArgs` его тоже отклоняет.
+
+Результат каждого действия приходит тостом, а панель обновляется сразу, не дожидаясь следующего опроса. Пока команда выполняется, в заголовке горит `working` и повторные клики игнорируются, так что двойной клик не запустит две команды.
+
+## Compose-стек
+
+`Up stack` поднимает весь compose-проект, а не один контейнер, и берёт compose-файл из каталога агента. Такой файл — исполняемое содержимое: в нём бывают `build`, `command` и `entrypoint`, поэтому диалог сначала показывает точную команду и подтверждения, в отличие от `down`, не требует.
+
+Пункт появляется только когда файл доказуемно принадлежит проекту контейнера, по которому кликнули. Имя проекта читается так же, как это делает compose v2: явное `name:` верхнего уровня, если оно есть, иначе имя каталога, где лежит файл. Оно должно совпасть с лейблом `com.docker.compose.project` контейнера, а сам контейнер не должен быть уже запущен. Во всех остальных случаях пункта просто нет, потому что не тот стек хуже, чем отсутствие кнопки.
+
+Проект передаётся дважды, как `-f <файл>` и `-p <проект>`. Имя внутри файла может быть шаблонным или перебитым окружением, а `-p` гарантирует, что поднимется тот самый проект, который панель уже показывает, а не его вторая копия.
+
+Стек, у которого нет ни одного контейнера, — обычное состояние того, что никогда не запускали, и для него сделана отдельная входная точка. Когда в каталоге агента лежит compose-файл и на машине нет ни одного контейнера с таким лейблом проекта, под строками появляется строка:
+
+```text
+Up stack · storefront is not running here
+```
+
+Клик по ней один раз спрашивает, показывая точную команду до запуска: compose-файл это исполняемое содержимое, а у стека нет контейнера, которым можно назвать действие. Как только появится хоть один контейнер этого проекта, строка исчезает: дальше входом служит `Up stack` у самого контейнера. Один Dockerfile без compose-файла ничего не предлагает: запускать нечего без имени образа, и панель догадывалась бы.
+
+Кандидаты проверяются в том же порядке, что и у compose: `compose.yaml`, `compose.yml`, `docker-compose.yaml`, `docker-compose.yml`. Первый существующий файл побеждает, даже если объявляет другой проект, потому что именно его использовал бы сам compose: если продолжить поиск, кнопка предложила бы стек, который CLI игнорирует.
+
+## Логи
+
+Пункт `Logs` в том же меню перезаписывает содержимое окна логами контейнера, то есть логи и действия делят одно окно. Закрывается через `esc` или кликом по нижней строке.
+
+Просмотр — это `docker logs --timestamps --tail 200 -- <имя>`, обновление раз в две секунды, пока окно открыто. Docker пишет потоки контейнера вперемешку, поэтому буферы разбираются отдельно и снова сливаются по времени: без этого лог читался бы сначала целиком из stdout. ANSI-последовательности и одиночные `CR` вырезаются, иначе терминал выполнил бы их как управляющие коды. Окно фиксированной высоты в пятнадцать строк прокручивается колесом мыши.
+
+## Требования
+
+- Рантайм OpenCode 2 со слотами плагинов (`opencode2`)
+- `docker` в `PATH`: Docker Desktop на Windows, Docker Engine на Linux и macOS
+
+Строки панели только английские, документация двуязычная.
+
+## Установка
+
+### Вариант A: пусть сделает LLM
+
+Вставь это в любого агента (Claude Code, OpenCode, Cursor и так далее):
+
+```text
+Установи плагин панели Docker opencode-docker-panel по инструкции
+https://github.com/victor-ochenin/opencodeDockerPlugin#installation
+```
+
+### Вариант B: вручную
+
+Добавь плагин в `~/.config/opencode/cli.json`. Если файла нет, создай его, и всё, что в нём уже есть, сохрани.
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/v2/cli.json",
+  "plugins": [{ "package": "opencode-docker-panel", "options": { "intervalMs": 3000 } }]
+}
+```
+
+Два места, на которых обычно спотыкаются, поэтому скажу прямо:
+
+- **Запись идёт в `cli.json`, а не в `opencode.json`.** Плагин только терминальный: он рисуется в сайдбаре, а `cli.json` читает терминальный клиент.
+- **Логиниться не нужно, провайдера настраивать не нужно.** Плагин говорит только с локальным `docker` и больше ни с чем.
+
+После этого перезапусти TUI: хост сам поставит пакет при следующем старте, копировать и собирать ничего не нужно.
+
+Если нужна зафиксированная версия, укажи её явно: `{ "package": "opencode-docker-panel@0.4.1" }`.
+
+### Из локального клона
+
+Чтобы запускать плагин прямо из клона, скопируй файлы в конфиг-каталог OpenCode. На Windows это `%USERPROFILE%\.config\opencode\plugins\docker-panel\`.
+
+```powershell
+$src = "path\to\opencodeDockerPlugin"
+$dst = "$HOME\.config\opencode\plugins\docker-panel"
+New-Item -ItemType Directory -Force -Path $dst | Out-Null
+Copy-Item "$src\*.ts","$src\*.tsx","$src\package.json" -Destination $dst -Force
+```
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/v2/cli.json",
+  "plugins": [{ "package": "./plugins/docker-panel", "options": { "intervalMs": 3000 } }]
+}
+```
+
+Пакет уходит исходниками на TypeScript, их резолвит сам OpenCode, поэтому собирать нечего. `solid-js`, пакеты OpenTUI и SDK OpenCode объявлены пирами, а не жёсткими зависимостями, поэтому вторая копия SDK не перекроет ту, которой работает хост.
+
+### Проверка
+
+CLI-проверки у этого плагина нет: он рисуется в терминальном интерфейсе, поэтому `opencode run` его не покажет никогда. Проверяй в TUI.
+
+1. `docker ps` возвращает хотя бы один контейнер. Если команда падает, панели нечего рисовать, и она так и скажет.
+2. Перезапусти TUI и открой сессию.
+3. В сайдбаре появится заголовок `Docker` со счётчиком контейнеров. Запущенные контейнеры станут строками, не больше пяти, а под ними — строка `N more, click for all`, если что-то ещё скрыто.
+4. Кликни по `Docker`, чтобы свернуть список, и ещё раз, чтобы открыть полный. Выбери контейнер — откроется меню его действий.
+
+Если заголовок так и не появился, плагин не загрузился: проверь, что запись лежит в `cli.json` в секции `plugins`, и посмотри `~/.local/share/opencode/log/opencode.log` на предмет ошибки загрузки.
+
+## Опции
+
+| Опция | По умолчанию | Примечания |
+|---|---|---|
+| `intervalMs` | `3000` | Интервал опроса, ограничивается диапазоном 1000..60000 |
+
+## Ограничения
+
+- Сайдбар рисует только контейнеры в состоянии `running`. `paused` и `restarting` строки не получают, хотя docker считает их живыми, — чтобы увидеть такой контейнер, закрепи его.
+- OpenCode 2 находится в бета-фазе, поэтому имена слотов и токены темы могут измениться.
+- Обходное решение с перерисовкой сбрасывает свёрнутое состояние и закрывает открытое окно логов, когда список контейнеров действительно меняется.
+- Опрос порождает `docker ps` с интервалом. На машине с сотнями контейнеров подними `intervalMs` до 5000 или выше.
+- Строк не больше пяти, и пять — константа, а не опция: на машине с тридцатью контейнерами панель покажет пять, а остальные останутся в диалоге. Единственный способ вывести шестой — закрепить его.
+- Сам сайдбар не прокручивается, поэтому контейнеры за пределами пяти живут в диалоге, а не в панели.
+- Нет exec, работы с томами и образами, истории перезапусков. `Down` предлагается у контейнера, но действует на весь compose-проект. Окно логов — фиксированное окно поверх последних 200 строк, истории глубже нет.
+- `Up stack` поднимает только стек, чей compose-файл лежит в каталоге агента. Проект, созданный в другом месте, всё равно можно снести через `Down`, но поднять его можно только `Start` на одном контейнере.
+- `Up stack` может остаться скрытым, когда compose-файл объявляет проект в форме, которую панель прочитать не может: например, `name:` с отступом или в кавычках. Это отказ, а не неверный запуск.
+- Действия только мышью; слой клавиш плагин не регистрирует.
+
+## Изменения
+
+Версии и даты в [CHANGELOG.md](CHANGELOG.md).
+
+## Лицензия
+
+MIT

package/dist/commands.js

@@ -0,0 +1,77 @@
+import { execFile } from "node:child_process";
+const COMMAND = "docker";
+const TIMEOUT_MS = 60000;
+const MAX_BUFFER = 1024 * 1024;
+export const ACTION_LABEL = {
+  start: "Start",
+  up: "Up stack",
+  restart: "Restart",
+  stop: "Stop",
+  down: "Down compose project"
+};
+
+/** The name is passed after `--` because a container name may start with a dash and docker would read it as a flag. */
+export function buildArgs(action, container, target) {
+  if (action === "up") {
+    if (!target) throw new Error(`container ${container.name} has no resolved compose target`);
+    // Both flags are explicit: the project name in the file can be templated or overridden by the
+    // environment, and this way `up` acts on the very project the panel is already showing.
+    return ["compose", "-f", target.file, "-p", target.project, "up", "-d"];
+  }
+  if (action === "down") {
+    const project = container.composeProject;
+    if (!project) throw new Error(`container ${container.name} has no compose project`);
+    return ["compose", "-p", project, "down"];
+  }
+  return [action, "--", container.name];
+}
+
+/** Only offers what docker accepts for the current state, with the destructive action last. */
+export function availableActions(container, target) {
+  const down = container.composeProject ? ["down"] : [];
+  const up = container.composeProject && target ? ["up"] : [];
+  switch (container.state) {
+    case "running":
+    case "restarting":
+    case "paused":
+      return ["restart", "stop", ...down];
+    case "created":
+    case "exited":
+    case "dead":
+      return ["start", ...up, ...down];
+    default:
+      return [];
+  }
+}
+function firstLine(text) {
+  const line = text.split(/\r?\n/).map(item => item.trim()).find(item => item.length > 0);
+  if (!line) return "";
+  return line.length > 80 ? `${line.slice(0, 77)}...` : line;
+}
+/**
+ * Runs an already-built argument list. `up` has no container behind it, so the boundary takes the
+ * argv rather than a container the caller would have to invent to satisfy the type.
+ */
+export function runDockerArgs(args) {
+  return new Promise(resolve => {
+    execFile(COMMAND, [...args], {
+      timeout: TIMEOUT_MS,
+      windowsHide: true,
+      maxBuffer: MAX_BUFFER
+    }, (error, stdout, stderr) => {
+      if (!error) {
+        resolve({
+          ok: true,
+          message: firstLine(String(stdout)) || "done"
+        });
+        return;
+      }
+      const killed = error.killed === true;
+      const reason = firstLine(String(stderr)) || (killed ? "timed out" : error.message);
+      resolve({
+        ok: false,
+        message: reason || "command failed"
+      });
+    });
+  });
+}

package/dist/compose.js

@@ -0,0 +1,48 @@
+import { readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+/** compose v2's own search order, so the resolver sees the same file the CLI would pick. */
+const CANDIDATES = ["compose.yaml", "compose.yml", "docker-compose.yaml", "docker-compose.yml"];
+/** An unindented `name:` is top-level by construction, which is why a regex beats a YAML parser here. */
+function declaredProject(body) {
+  // A UTF-8 BOM makes `^` miss the first line, which would hand back the directory name as if it
+  // were the project's. PowerShell and several editors write one, so strip it before matching.
+  const match = body.replace(/^\uFEFF/, "").match(/^name:[ \t]*(\S.*?)[ \t]*$/m);
+  return match?.[1]?.replace(/^["']|["']$/g, "") ?? "";
+}
+
+/**
+ * Finds the agent directory's compose file and reports the project it declares, if any. The file is
+ * read on every call because the call comes from opening a menu, not from the poll loop.
+ */
+export function findComposeFile(agentDir) {
+  if (!agentDir) return null;
+  for (const candidate of CANDIDATES) {
+    const file = join(agentDir, candidate);
+    let body;
+    try {
+      body = readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    // The first file that exists wins even when its project differs, because that is the file
+    // compose itself would use. Falling through would act on a stack the CLI ignores.
+    return {
+      dir: agentDir,
+      file,
+      project: declaredProject(body) || basename(dirname(file))
+    };
+  }
+  return null;
+}
+
+/**
+ * The compose target for a container that is already part of the project, or null when the agent
+ * directory's file belongs to somebody else. `up` runs build and command lines from that file, so
+ * an uncertain match has to hide the button rather than point it at the wrong stack.
+ */
+export function resolveComposeTarget(agentDir, project) {
+  const target = findComposeFile(agentDir);
+  if (!target || !project || target.project !== project) return null;
+  return target;
+}