hermes-kanban-miniapp/README.md

# 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).