d405f71673
- Add Makefile with dev/build/test/docker/ci commands - Rewrite README.md with architecture, quickstart, env vars (EN + RU) - Add Forgejo CI workflow (.forgejo/workflows/test.yml) - Update GitHub CI workflow for pnpm monorepo structure - Fix unused imports in bridge test file (typecheck) - Add test/ci scripts to root package.json - Docker compose build verified (bridge + frontend images) - Full local CI passes: typecheck → test (16/16) → build
213 lines
7.1 KiB
Markdown
213 lines
7.1 KiB
Markdown
# Hermes Kanban Mini App
|
||
|
||
Telegram Mini App and web dashboard for [Hermes Agent](https://github.com/NousResearch/hermes-agent) Kanban boards. View, create, and manage tasks from mobile or desktop.
|
||
|
||
> **[Русская версия](#hermes-kanban-mini-app--на-русском)**
|
||
|
||
## What it does
|
||
|
||
- **Board view**: Kanban columns — triage, todo, ready, running, blocked, done, archived
|
||
- **Task details**: body, events, runs, log tail, comments
|
||
- **Task actions**: create, assign, promote, block/unblock, archive, dispatch, comment
|
||
- **Telegram integration**: Mini App theme variables, `initData` auth, haptic feedback
|
||
- **Secure bridge**: execFile with `shell: false`, command allowlist, token auth
|
||
|
||
## Architecture
|
||
|
||
```
|
||
Telegram Mini App / Browser
|
||
│
|
||
│ HTTPS / Vite proxy in dev
|
||
▼
|
||
React + TypeScript + Vite frontend (port 5173 dev / 80 nginx)
|
||
│
|
||
│ /bridge/v1/* (X-Bridge-Token or dev mode)
|
||
▼
|
||
Express Bridge (port 3456)
|
||
│
|
||
│ hermes kanban ... --json (execFile, shell: false)
|
||
▼
|
||
Hermes Kanban board (SQLite)
|
||
```
|
||
|
||
**Monorepo structure** (pnpm workspace):
|
||
- `packages/contracts` — shared TypeScript types + Zod schemas
|
||
- `packages/bridge` — Express API server, CLI wrapper
|
||
- `frontend` — React + Vite SPA with Tailwind CSS
|
||
|
||
## Quick start
|
||
|
||
### Prerequisites
|
||
|
||
- Node.js ≥ 18
|
||
- pnpm 9.x (`corepack enable`)
|
||
- [Hermes Agent](https://github.com/NousResearch/hermes-agent) installed with Kanban enabled
|
||
|
||
### Local development
|
||
|
||
```bash
|
||
git clone https://github.com/Kisskin-Mister/hermes-kanban-miniapp.git
|
||
cd hermes-kanban-miniapp
|
||
cp .env.example .env # edit as needed
|
||
pnpm install
|
||
make dev # starts bridge + frontend
|
||
```
|
||
|
||
- Frontend: http://localhost:5173 (Vite dev server with hot reload)
|
||
- Bridge API: http://localhost:3456/bridge/v1/health
|
||
|
||
### Docker Compose
|
||
|
||
```bash
|
||
cp .env.example .env # edit HERMES_HOME, BRIDGE_TOKEN, etc.
|
||
make docker-build # or: docker compose build
|
||
make up # or: docker compose up -d
|
||
```
|
||
|
||
- Frontend: http://localhost:8080
|
||
- Bridge API: http://localhost:3456 (internal, proxied by nginx)
|
||
|
||
### Production
|
||
|
||
```bash
|
||
make build # build TypeScript
|
||
make docker-build # build images
|
||
make up # start containers
|
||
```
|
||
|
||
The `docker-compose.yml` mounts `~/.hermes` read-only into the bridge container. Configure `HERMES_HOME` in `.env`.
|
||
|
||
## Environment variables
|
||
|
||
### Bridge (`.env`)
|
||
|
||
| Variable | Default | Description |
|
||
|---|---|---|
|
||
| `BRIDGE_HOST` | `127.0.0.1` | Bridge bind address |
|
||
| `BRIDGE_PORT` | `8787` | Bridge port |
|
||
| `BRIDGE_TOKEN` | — | Auth token (`X-Bridge-Token` header) |
|
||
| `AUTH_MODE` | `token` | `token` (validate header) or `dev` (bypass auth) |
|
||
| `BRIDGE_ALLOWED_BOARDS` | `default` | Comma-separated board slugs or `*` |
|
||
| `COMMAND_TIMEOUT_SECONDS` | `30` | Per-command timeout |
|
||
| `LOG_TAIL_MAX_LINES` | `500` | Max log lines returned |
|
||
| `HERMES_BIN` | `hermes` | Path to hermes executable |
|
||
| `HERMES_HOME` | — | Hermes profile directory |
|
||
| `TELEGRAM_BOT_TOKEN` | — | For initData validation (optional) |
|
||
|
||
### Docker Compose
|
||
|
||
| Variable | Default | Description |
|
||
|---|---|---|
|
||
| `HERMES_HOME` | `/home/kisskin/.hermes` | Mounted into bridge container |
|
||
|
||
## Makefile commands
|
||
|
||
```
|
||
make install — pnpm install
|
||
make dev — run bridge + frontend in dev mode
|
||
make build — build all TypeScript packages
|
||
make typecheck — run TypeScript type checking
|
||
make test — run bridge tests
|
||
make ci — install + typecheck + test + build
|
||
make docker-build — build Docker images
|
||
make up — docker compose up -d
|
||
make down — docker compose down
|
||
make logs — follow service logs
|
||
make clean — remove build artifacts
|
||
```
|
||
|
||
## Telegram Mini App setup
|
||
|
||
1. Create a bot with [BotFather](https://t.me/BotFather)
|
||
2. Set the Mini App domain: `/setdomain` → your HTTPS domain
|
||
3. Configure `.env`:
|
||
```bash
|
||
AUTH_MODE=token
|
||
BRIDGE_TOKEN=<generate-a-strong-token>
|
||
TELEGRAM_BOT_TOKEN=<your-bot-token>
|
||
```
|
||
4. Deploy with HTTPS (Caddy, Nginx, Traefik, or Cloudflare Tunnel)
|
||
|
||
## CI
|
||
|
||
Forgejo CI workflow (`.forgejo/workflows/test.yml`) runs on push to `main`:
|
||
- Typecheck contracts, bridge, frontend
|
||
- Run bridge unit tests (vitest)
|
||
- Build frontend
|
||
|
||
## License
|
||
|
||
MIT — see [LICENSE](LICENSE).
|
||
|
||
---
|
||
|
||
# Hermes Kanban Mini App / На русском
|
||
|
||
Telegram Mini App и веб-панель для управления задачами [Hermes Agent](https://github.com/NousResearch/hermes-agent). Просматривайте, создавайте и управляйте задачами с мобильного или десктопа.
|
||
|
||
## Что это
|
||
|
||
- **Доска с колонками**: triage, todo, ready, running, blocked, done, archived
|
||
- **Детали задачи**: описание, события, запуски, логи, комментарии
|
||
- **Действия**: создание, назначение, продвижение, блокировка/разблокировка, архивация, диспетчеризация
|
||
- **Интеграция с Telegram**: темы Mini App, авторизация `initData`, тактильная обратная связь
|
||
|
||
## Быстрый старт
|
||
|
||
### Локальная разработка
|
||
|
||
```bash
|
||
git clone https://github.com/Kisskin-Mister/hermes-kanban-miniapp.git
|
||
cd hermes-kanban-miniapp
|
||
cp .env.example .env
|
||
pnpm install
|
||
make dev
|
||
```
|
||
|
||
- Фронтенд: http://localhost:5173
|
||
- API моста: http://localhost:3456/bridge/v1/health
|
||
|
||
### Docker Compose
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# Отредактируйте HERMES_HOME, BRIDGE_TOKEN и другие переменные
|
||
make docker-build
|
||
make up
|
||
```
|
||
|
||
- Фронтенд: http://localhost:8080
|
||
- Мост (внутренний): http://localhost:3456
|
||
|
||
### Предварительные требования
|
||
|
||
- Node.js ≥ 18
|
||
- pnpm 9.x (`corepack enable`)
|
||
- [Hermes Agent](https://github.com/NousResearch/hermes-agent) с включённым Kanban
|
||
|
||
## Переменные окружения
|
||
|
||
Смотрите таблицу выше или файл `.env.example`.
|
||
|
||
## Команды Makefile
|
||
|
||
| Команда | Описание |
|
||
|---|---|
|
||
| `make dev` | Запуск bridge + frontend в режиме разработки |
|
||
| `make build` | Сборка всех TypeScript пакетов |
|
||
| `make test` | Запуск тестов bridge |
|
||
| `make docker-build` | Сборка Docker образов |
|
||
| `make up` | Запуск сервисов через docker compose |
|
||
| `make down` | Остановка сервисов |
|
||
| `make ci` | Полный CI-пайплайн локально |
|
||
|
||
## Установка Telegram Mini App
|
||
|
||
1. Создайте бота через [BotFather](https://t.me/BotFather)
|
||
2. Установите домен Mini App: `/setdomain` → ваш HTTPS домен
|
||
3. Настройте `.env` с `AUTH_MODE=token`, `BRIDGE_TOKEN` и `TELEGRAM_BOT_TOKEN`
|
||
4. Разверните с HTTPS (Caddy, Nginx, Traefik, Cloudflare Tunnel)
|
||
|
||
## Лицензия
|
||
|
||
MIT — см. [LICENSE](LICENSE).
|