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:

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:

{
  "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:

{
  "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.

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:

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ń.

4.3 KiB Raw Blame History