hermes-kanban-miniapp/README.md

# Hermes Kanban Mini App

A community-ready Telegram Mini App and browser dashboard for viewing and operating Hermes Agent Kanban boards from mobile or desktop.

Status: local MVP. The repository is prepared for a future public GitHub push, but no remote is created by this task.

## What it does

- Shows Hermes Kanban columns: triage, todo, ready, running, blocked, done, archived.
- Opens task details with body, events, runs and log tail.
- Creates tasks with assignee, priority, workspace kind, goal mode and runtime options.
- Adds comments and runs common actions: assign, promote, block, unblock, archive, dispatch.
- Supports Telegram Mini App theme variables and server-side Telegram `initData` validation.

## Architecture

```text
Telegram Mini App / Browser
        |
        | HTTPS in production, Vite proxy in dev
        v
React + TypeScript frontend
        |
        | /api/* with optional X-Telegram-Init-Data
        v
FastAPI backend
        |
        | fixed subprocess argv, shell=False
        v
hermes kanban CLI
        |
        v
Hermes Kanban board
```

Screenshot placeholder: run the frontend locally and replace this section with screenshots before publishing the GitHub repository.

## Prerequisites

- Hermes Agent installed with Kanban enabled.
- Python 3.11+.
- Node.js 20+ (tested with Node 24).
- Telegram bot from BotFather for Mini App production mode.
- HTTPS public URL for Telegram Mini App production usage.

## Local development

```bash
git clone <your-future-repo-url> hermes-kanban-miniapp
cd hermes-kanban-miniapp
cp .env.example .env
```

Backend:

```bash
python3 -m venv .venv
. .venv/bin/activate
pip install -e backend[dev]
uvicorn app.main:app --app-dir backend --reload --host 127.0.0.1 --port 8000
```

Frontend:

```bash
cd frontend
npm install
npm run dev
```

Open http://localhost:5173. In `KANBAN_UI_AUTH_MODE=dev` or `none`, the browser works without Telegram.

## Environment variables

See `.env.example`.

Important settings:

- `HERMES_BIN`: Hermes executable, default `hermes`.
- `HERMES_HOME`: Hermes home directory for the target profile.
- `HERMES_KANBAN_BOARD`: default board slug.
- `KANBAN_UI_AUTH_MODE`: `telegram`, `dev` or `none`.
- `TELEGRAM_BOT_TOKEN`: bot token used only by backend for `initData` validation.
- `TELEGRAM_ALLOWED_USER_IDS`: optional comma-separated Telegram user id allowlist.
- `KANBAN_UI_ALLOWED_ORIGINS`: CORS allowlist.
- `KANBAN_UI_FRONTEND_DIST_DIR`: optional built frontend directory for single-container serving.
- `VITE_API_BASE_URL`: frontend API base URL for production builds.

## Telegram Mini App setup

1. Open BotFather in Telegram.
2. Create or choose a bot.
3. Use `/setdomain` and set the HTTPS domain that serves this app.
4. Use `/setmenubutton` or create a Web App button and point it at your HTTPS frontend URL.
5. On the backend, set:
   - `KANBAN_UI_AUTH_MODE=telegram`
   - `TELEGRAM_BOT_TOKEN=<your bot token>`
   - optionally `TELEGRAM_ALLOWED_USER_IDS=123,456`
6. Never put the bot token into frontend env vars or committed files.

## Production deployment notes

Telegram Mini Apps require HTTPS. Put the frontend and backend behind a reverse proxy such as Caddy, Nginx, Traefik or Cloudflare Tunnel. Configure CORS so the backend only accepts your frontend origin.

Systemd example:

```ini
[Unit]
Description=Hermes Kanban Mini App API
After=network.target

[Service]
WorkingDirectory=/opt/hermes-kanban-miniapp
EnvironmentFile=/opt/hermes-kanban-miniapp/.env
ExecStart=/opt/hermes-kanban-miniapp/.venv/bin/uvicorn app.main:app --app-dir backend --host 127.0.0.1 --port 8000
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

Build frontend for static hosting:

```bash
cd frontend
npm ci
npm run build
```

The included Dockerfile builds the frontend and serves it from the FastAPI container on port `8000`.
For same-origin Docker deployment, leave `VITE_API_BASE_URL` empty at build time and expose only the backend container.

## Security model

- Backend accepts only fixed API actions mapped to fixed Hermes Kanban CLI subcommands.
- Subprocess calls use argv lists and `shell=False`.
- Telegram `initData` is validated according to Telegram WebApp signing rules in `telegram` auth mode.
- Optional Telegram user allowlist rejects unknown users.
- CORS is restrictive and configured by env.
- `.env` is ignored by git; `.env.example` contains placeholders only.

## Known limitations

- The adapter prefers Hermes CLI JSON output. If a local Hermes version lacks JSON for a command, parsing is conservative and may return raw text for some endpoints.
- No drag-and-drop yet; actions are button-based.
- No SSE yet; running boards auto-refresh every 2.5 seconds, otherwise every 5 seconds.
- No GitHub remote is created until the owner/name are confirmed and auth is configured.

## Tests

Backend:

```bash
. .venv/bin/activate
pytest backend/tests -q
```

Frontend:

```bash
cd frontend
npm test
npm run build
```