user
131 lines
4.7 KiB
Markdown
131 lines
4.7 KiB
Markdown
# API aplikacji kart
|
|
|
|
Wspólna aplikacja Fastify wystawia stan dowolnej karty, nawigację UML,
|
|
checkpointy oraz Neovim wybrany przez MCP. Domyślny adres lokalnej instancji
|
|
to `http://127.0.0.1:8080`. Kontrakt nie zależy od serii ani konkretnej karty;
|
|
dane i recepty pochodzą z jej `card_source.json`.
|
|
|
|
API nie zarządza cyklem życia kontenera i nie podpina pane tmuxa. Za operacje
|
|
`start/reset/refresh/attach/detach` odpowiada `stemctl session`. API korzysta z
|
|
kontenera wskazanego przez bieżący wybór MCP i steruje zawartością jego sesji:
|
|
Neovimem, Termdebugiem/GDB i checkpointami maszyny.
|
|
|
|
## Tożsamość i stan
|
|
|
|
| Metoda i endpoint | Znaczenie |
|
|
| --- | --- |
|
|
| `GET /api/identity` | `id`, UUID, wersja i SHA-256 źródłowego JSON-a karty. |
|
|
| `GET /api/card-revision` | Rewizja plików używana do automatycznego odświeżania strony. |
|
|
| `GET /api/state` | Złożony stan nawigacji, widoku, checkpointu i dostępności Neovima. |
|
|
| `GET /api/control/state` | Lekki stan synchronizacji strony z klientem sterującym. |
|
|
|
|
Serwer jest przeznaczony do pracy lokalnej. Nie ma warstwy uwierzytelnienia,
|
|
dlatego nie należy wystawiać go bezpośrednio poza zaufany host.
|
|
|
|
## Nawigacja UML
|
|
|
|
Hierarchia nawigacji jest stała:
|
|
|
|
```text
|
|
task → block → phase → step → snapshot
|
|
```
|
|
|
|
| Metoda i endpoint | Znaczenie |
|
|
| --- | --- |
|
|
| `GET /api/keyboard` | Skróty i obsługiwane poziomy nawigacji. |
|
|
| `GET /api/navigation/catalog` | Wszystkie prawidłowe pozycje i ich indeksy. |
|
|
| `GET /api/navigation/current` | Bieżąca pozycja oraz status checkpointu. |
|
|
| `PUT /api/navigation/current` | Ustawia dokładną pozycję i poziom fokusu. |
|
|
| `POST /api/navigation/move` | Przesuwa kursor o `delta` na wybranym poziomie. |
|
|
|
|
Przykład ustawienia kroku — identyfikatory są danymi konkretnej karty:
|
|
|
|
```json
|
|
{
|
|
"task_id": "<task-id>",
|
|
"block_id": "<block-id>",
|
|
"phase_id": "<phase-id>",
|
|
"step_id": "<step-id>",
|
|
"snapshot_ref": "<snapshot-ref>",
|
|
"focus_level": "step",
|
|
"sync_requested": true,
|
|
"actor": "stemctl"
|
|
}
|
|
```
|
|
|
|
## Checkpointy
|
|
|
|
| Metoda i endpoint | Znaczenie |
|
|
| --- | --- |
|
|
| `GET /api/checkpoint/status` | Aktywna operacja, ostatni wynik i generacja. |
|
|
| `POST /api/checkpoint/activate` | Odtwarza stan GDB przypisany do snapshotu. |
|
|
|
|
Wywołanie orkiestratora przypina zarówno kontener, jak i rewizję karty:
|
|
|
|
```json
|
|
{
|
|
"snapshot_ref": "<snapshot-ref>",
|
|
"generation": 1784280000000,
|
|
"expected_binding": {
|
|
"container_id": "<container-id>",
|
|
"instance": "<instance-id>",
|
|
"profile": "hazard3-sim",
|
|
"target": "hazard3-baremetal"
|
|
},
|
|
"expected_identity": {
|
|
"id": "<card-id>",
|
|
"uuid": "<card-uuid>",
|
|
"version": "<card-version>",
|
|
"source_sha256": "<sha256>"
|
|
}
|
|
}
|
|
```
|
|
|
|
Replay kończy się powodzeniem wyłącznie ze statusem `ready`. Zmiana kontenera,
|
|
socketu MCP albo źródłowego JSON-a podczas operacji powoduje odrzucenie
|
|
wyniku; pozycja strony i `SYNC ON` nie są wtedy publikowane.
|
|
|
|
## Widok i Neovim
|
|
|
|
| Metoda i endpoint | Znaczenie |
|
|
| --- | --- |
|
|
| `GET/PUT /api/viewer/state` | Skala, scroll oraz `visible/sync/control/expanded/fit`. |
|
|
| `GET /api/nvim/state` | Bieżący bufor, okno, kursor i tryb Neovima. |
|
|
| `PUT /api/nvim/cursor` | Ustawia `row`, `column` i opcjonalnie `window`. |
|
|
| `POST /api/nvim/input` | Przekazuje do 256 znaków przez `nvim_input`. |
|
|
| `WS /api/nvim-ui` | Strumień zewnętrznego UI Neovima do panelu WWW. |
|
|
|
|
Wyłączenie `viewer.nvim.sync` automatycznie wyłącza również
|
|
`viewer.nvim.control`. Samo ponowne włączenie synchronizacji nie uzbraja
|
|
sterowania klawiaturą bez jawnego `control: true`.
|
|
|
|
### Podział odpowiedzialności widoków
|
|
|
|
Interaktywny diagram UML pokazuje przepływ i służy do wyboru kroku. Nie
|
|
renderuje pod SVG osobnych paneli kodu, terminala, rejestrów, pamięci ani ramki
|
|
stosu. Te dane prezentuje `Nvim view`, ustawiany przez snapshot wybranego
|
|
kroku. Snapshoty pozostają w JSON/API, mimo że nie są powielane wizualnie pod
|
|
diagramem.
|
|
|
|
## Postęp zajęć i raport
|
|
|
|
| Metoda i endpoint | Znaczenie |
|
|
| --- | --- |
|
|
| `GET /api/progress` | Katalog, statusy i podsumowanie wykonania. |
|
|
| `PUT /api/progress/:itemId` | Ustawia `pending` albo `approved`, notatkę i aktora. |
|
|
| `GET /api/report/teams.md` | Generuje bieżący raport Markdown do Teams. |
|
|
|
|
## Planowane strategie i adnotacje
|
|
|
|
Strategie debugowania będą przypinane do pełnego klucza
|
|
`task/block/phase/step/snapshot`. Adnotacja pozostanie osobnym rekordem:
|
|
|
|
```text
|
|
strategy: id, label, commands, expected_observations
|
|
annotation: id, strategy_id, target, geometry, style, text, visible
|
|
```
|
|
|
|
Planowane operacje `show/hide/toggle` zmienią wyłącznie `visible`.
|
|
`add/remove` będą osobnymi, audytowalnymi operacjami. Dzięki temu ukrycie
|
|
warstwy objaśnień nie usuwa przygotowanych oznaczeń.
|