skrueckenandCursor
846bb31dc9
Expose tm mcp tools against the local daemon, document agent setup, and ignore workspace .tm_token files. Co-authored-by: Cursor <cursoragent@cursor.com>
190 lines
7.2 KiB
Markdown
190 lines
7.2 KiB
Markdown
# task-master
|
||
|
||
Offline-first Terminal-Taskmanager (`tm`) — Kanban-Board, Markdown-Tickets, Checklisten, Zeiterfassung und Reports. Gebaut mit [Bubble Tea](https://github.com/charmbracelet/bubbletea). Dazu der optionale Web-Server `tm_server` mit Svelte-UI und SQLite.
|
||
|
||
|
||
|
||
> Demo wird aus [`demo.tape`](demo.tape) erzeugt (`make demo`). Ohne GIF lokal: siehe [Demo aufnehmen](#demo-aufnehmen).
|
||
|
||
## Features
|
||
|
||
**TUI (`tm`)**
|
||
|
||
- Projekte & Tickets lokal als JSON hinter einem Hintergrund-Daemon (Unix-Socket)
|
||
- Mehrere TUI-Instanzen teilen denselben State; `tm stop` beendet den Daemon
|
||
- Board-Filter: All / Backlog / In Progress / Done
|
||
- Tickets in `$EDITOR` bearbeiten (Markdown + Checklisten)
|
||
- Timer, manuelle Zeitbuchungen, Zeiteinträge inkl. Start/Ende editieren
|
||
- Report mit Group-by (Ticket / Tag)
|
||
- Undo / Redo über eine Command-History (im Daemon)
|
||
- Vim-Style Keybindings
|
||
- YouTrack Pull/Push (manuell; Remote-URL, Token, Project-Key pro Projekt)
|
||
- Sync gegen `tm_server` (Backend `taskmaster`, Projekt-Tokens)
|
||
- MCP-Token pro Projekt erzeugen (`g` in der Projektliste) für späteren KI-Zugriff
|
||
|
||
**Web (`tm_server`)**
|
||
|
||
- Eingebettetes Svelte-UI, SQLite, Auth und Rechte pro Projekt
|
||
- Projektgruppen, Sidebar-Navigation, Hash-Routes
|
||
- Drag & Drop auf dem Board (OPEN / WIP / DONE)
|
||
- Lesbare Ticket-Keys aus Projektcode + Sequenz (z. B. `WEB-12`)
|
||
- Visual- und Markdown-Editor für Ticket-Beschreibungen
|
||
- Datei-Anhänge; Tabellen (XLSX/ODS/…) im Browser editierbar
|
||
- Report mit Datums- und Ticket-Filtern sowie Eintragsliste
|
||
- Sync-Backend pro Projekt, Projekt-Tokens für die TUI, Ticket-Revisionen
|
||
- Members, Settings (Tokens), Users (Admin)
|
||
|
||
## Install
|
||
|
||
Voraussetzung: Go (siehe `go.mod`). Für `tm_server` zusätzlich Node.js (Frontend-Build).
|
||
|
||
```bash
|
||
git clone git@git.aloxdrim.de:skruecken/task-master.git
|
||
cd task-master
|
||
make install # → $(go env GOPATH)/bin/tm
|
||
# oder nur bauen:
|
||
make build # → ./bin/tm
|
||
make build-server # Frontend + → ./bin/tm_server
|
||
make build-all # beides
|
||
```
|
||
|
||
## Nutzung
|
||
|
||
```bash
|
||
tm # TUI starten (startet Daemon bei Bedarf)
|
||
tm sync pull # Issues von YouTrack / tm_server holen
|
||
tm sync push # lokale Änderungen pushen
|
||
tm sync pull -p inbox # anderes Projekt
|
||
tm status # Daemon-Status + Socket-Pfad
|
||
tm stop # Hintergrund-Daemon beenden
|
||
tm daemon # Daemon im Vordergrund (Debug)
|
||
tm version # Build-Version (Git-Hash)
|
||
tm help
|
||
```
|
||
|
||
### Lokaler JSON-Daemon
|
||
|
||
`tm` speichert weiterhin JSON unter dem DataDir, schreibt aber nur noch über einen lokalen Daemon-Prozess (eine Instanz pro DataDir). Socket/PID liegen unter `$XDG_RUNTIME_DIR/task-master-<hash>/` (Fallback: Temp-Dir). Die TUI und `tm sync` verbinden sich als vertrauenswürdige Clients (`X-TM-Client: tui|cli`).
|
||
|
||
### MCP (`tm mcp`)
|
||
|
||
1. In der TUI-Projektliste `g` → Token erzeugen (Klartext einmal in der Statuszeile); `G` widerruft.
|
||
2. Im Repo-Root (oder darüber) `.tm_token` anlegen — **nicht committen**:
|
||
|
||
```
|
||
project=inbox
|
||
token=tm_mcp_…
|
||
```
|
||
|
||
3. Cursor / MCP-Client:
|
||
|
||
```json
|
||
{ "command": "tm", "args": ["mcp"] }
|
||
```
|
||
|
||
Ohne gültiges `.tm_token` macht der MCP-Server keine Daemon-Aufrufe. Mit Token sind Lesen und Schreiben nur für dieses eine TM-Projekt erlaubt.
|
||
|
||
### Web-Server (`tm_server`)
|
||
|
||
```bash
|
||
# Dev/Test gegen lokales tm_server (kein YouTrack): seedet Projekte + verdrahtet TUI
|
||
make run-server-dev # :8080, Data unter ./.dev-home, Login admin/admin
|
||
make run-dev # TUI: Projekte „Test“ + „Website Relaunch“ schon mit Token connected
|
||
|
||
# Produktion / manuell:
|
||
export TM_ADMIN_USER=admin
|
||
export TM_ADMIN_PASSWORD='change-me'
|
||
export TASK_MASTER_SECRET='long-random-secret' # verschlüsselt Remote-Tokens
|
||
./bin/tm_server -listen :8080
|
||
|
||
# JSON-Daten der TUI einmalig importieren:
|
||
./bin/tm_server import-json -owner admin
|
||
```
|
||
|
||
UI: http://localhost:8080 — Dashboard, Board, Report, Attachments, Members, Settings (Tokens), Users (Admin), Ticket-Zeit & History.
|
||
|
||
Das Test-Environment (`run-server-dev`) spricht nur mit diesem Backend; YouTrack ist dort nicht verdrahtet.
|
||
Beim Seed (`TM_SEED_DEMO=1`) werden Demo-Projekte angelegt und für **Test** sowie **Website Relaunch** Write-Tokens unter `.dev-home` als lokale TUI-Projekte (`backend=taskmaster`) hinterlegt — danach `make run-dev` und Sync (`Y` → Pull). Login: `admin`/`admin` (Member: `alice`/`alice`).
|
||
|
||
Dev-Frontend (Vite, API-Proxy): `cd web && npm run dev` parallel zu `tm_server`. Frontend neu bauen ohne Go-Rebuild: `make web-build`.
|
||
|
||
Sandbox ohne echte Config/Daten:
|
||
|
||
```bash
|
||
make run-dev # nutzt ./.dev-home
|
||
# oder:
|
||
TASK_MASTER_HOME=/tmp/tm-sandbox tm
|
||
```
|
||
|
||
Daten landen standardmäßig unter `~/.local/share/task-master`, Config unter `~/.config/task-master`.
|
||
|
||
| Variable | Wirkung |
|
||
|------------------------|---------------------------------------------------|
|
||
| `TASK_MASTER_HOME` | Basis für Config + Daten (Dev/Demo) |
|
||
| `TASK_MASTER_DATA_DIR` | Nur Datenverzeichnis überschreiben |
|
||
| `TASK_MASTER_SECRET` | Verschlüsselt Remote-Tokens in SQLite |
|
||
| `TM_ADMIN_USER` / `TM_ADMIN_PASSWORD` | Bootstrap des ersten Admins |
|
||
| `TM_SEED_DEMO=1` | Demo-Projekte + TUI-Verdrahtung (Test / Website Relaunch) |
|
||
| `TM_SEED_BASE_URL` | Basis-URL in den geseedeten TUI-`meta.json` |
|
||
|
||
Server-Flags: `-listen`, `-db`, `-secure` (siehe `tm_server help`).
|
||
|
||
## Keybindings (Auszug)
|
||
|
||
| Taste | Aktion |
|
||
|---------|------------------------|
|
||
| `j`/`k` | Navigieren |
|
||
| `n` | Neues Ticket/Projekt |
|
||
| `e` | Ticket bzw. Projekt editieren (in Projektliste: YouTrack / Sync-Backend) |
|
||
| `s` | Status ändern |
|
||
| `l` | Board-Filter |
|
||
| `/` | Suche |
|
||
| `p`/`P` | Projekt / Ticket verschieben |
|
||
| `Y` | Sync-Menü: Pull / Push |
|
||
| `t`/`T` | Timer / Zeit buchen |
|
||
| `m` | Zeiteinträge |
|
||
| `r` | Report |
|
||
| `x`/`X` | Löschen / Force-Delete |
|
||
| `u`/`U` | Undo / Redo |
|
||
| `q` | Beenden |
|
||
|
||
Checklisten im Preview: `J`/`K` + `Space`.
|
||
|
||
### YouTrack / Sync
|
||
|
||
1. `p` → Projekt wählen → `e`
|
||
2. Backend wählen: YouTrack (Remote-URL, Permanent Token, Project-Key) oder task-master (Server-URL + Projekt-Token)
|
||
3. Lokal arbeiten (Anlegen/Edit/Status bleiben lokal)
|
||
4. `Y` → **Pull** oder **Push**
|
||
CLI: `tm sync pull` / `tm sync push`
|
||
|
||
Zeit: lokale Einträge ohne `externalId` werden remote als Work-Items gepusht; remote Work Items landen lokal beim Pull.
|
||
|
||
Status-Mapping Richtung YouTrack: OPEN→`Open`, WIP→`In Progress`, DONE→`Fixed` (Workflow-Namen können projektspezifisch abweichen).
|
||
|
||
## Entwicklung
|
||
|
||
```bash
|
||
make test
|
||
make build
|
||
make build-server # braucht Node (npm ci + Vite-Build)
|
||
make version
|
||
```
|
||
|
||
CI (Gitea): Tests, `tm` + `tm_server`-Build, Demo-GIF als Artifact.
|
||
|
||
## Demo aufnehmen
|
||
|
||
Die Walkthrough-Aufnahme steckt in [`demo.tape`](demo.tape) ([VHS](https://github.com/charmbracelet/vhs)):
|
||
|
||
```bash
|
||
# einmalig: vhs + ttyd/ffmpeg (siehe VHS-Docs)
|
||
make demo # schreibt demo.gif (+ demo.mp4)
|
||
```
|
||
|
||
Die Pipeline erzeugt das GIF ebenfalls und lädt es als Artifact hoch.
|
||
|
||
## Lizenz
|
||
|
||
Privat / eigener Use — siehe Repository-Einstellungen auf Gitea.
|