Imports:
  - Types:
      - CellGraph
    From: goga_tool_viewer/models
  - Types:
      - load_json_file
      - load_json_stdin
    Usages:
      - loading
    From: goga_tool_viewer/parser
  - Types:
      - index_page
    Usages:
      - serving
    From: goga_tool_viewer/frontend
  - Types:
      - find_free_port
    Usages:
      - finding
    From: goga_tool_viewer/server/port_finder
  - Usages:
      - codemanifest
      - usage_file
    From: goga_tool_viewer/loader

Usages:
  conventions: .goga/usages/conventions.md
  stdlib_http: |
    Использовать http.server из стандартной библиотеки Python.
    Custom handler наследуется от http.server.BaseHTTPRequestHandler.
    MIME-типы: text/html для HTML, application/json для JSON,
    text/css для CSS, application/javascript для JS,
    image/png для PNG, image/svg+xml для SVG.

Annotations: |
  Использовать `conventions` для правил написания кода и тестов.

  HTTP-сервер для обслуживания SPA, статических файлов и API графа.

  Используй `stdlib_http` для реализации сервера.
  Используй `load_json_file` и `load_json_stdin` для загрузки JSON-данных. См. `loading`.
  Используй `index_page` для генерации SPA-страницы. См. `serving`.
  Используй `find_free_port` для поиска свободного порта. См. `finding`.

---

"GraphServer(graph: CellGraph, port: int, static_dir: Path | None = None)":
  location: server.py
  annotations: |
    HTTP-сервер, обслуживающий SPA и API.
    Роуты: / — SPA-страница, /static/* — статические файлы (CSS, JS, изображения),
    /api/graph — JSON с данными графа,
    /api/codemanifest?cell=<path> — содержимое CODEMANIFEST,
    /api/usage?path=<path> — содержимое usage .md файла.

    `graph`: граф проекта для отдачи через API
    `port`: номер порта для запуска
    `static_dir`: директория со статическими файлами. По умолчанию — frontend/static

    Используй `stdlib_http` для реализации.
    Используй `index_page` для генерации SPA-страницы. См. `serving`.
    Используй `codemanifest` для загрузки CODEMANIFEST.
    Используй `usage_file` для загрузки usage .md файлов.
  properties:
    "port -> int": |
      Номер TCP-порта сервера.
  methods:
    "start() -> void:null": |
      Запускает HTTP-сервер. Блокирующий вызов.
    "stop() -> void:null": |
      Останавливает HTTP-сервер и закрывает сокет.
    "url() -> address:str": |
      Возвращает полный URL сервера.
    "get_codemanifest(cell_path: str) -> content:str": |
      Возвращает содержимое CODEMANIFEST для указанного cell.
      Если cell или CODEMANIFEST не найден — возвращает 404.
      Передаёт project_root из графа в load_codemanifest.

      `cell_path`: путь к cell из параметра запроса
      `content`: yaml-содержимое CODEMANIFEST

      Используй `codemanifest` для чтения файла.

"run_server(json_path: str | None) -> void:null":
  location: server.py
  annotations: |
    Точка входа сервера: загружает JSON, находит порт, запускает `GraphServer`.
    Если `json_path` is None — читает из stdin.
    При KeyboardInterrupt (Ctrl+C) завершается штатно с освобождением ресурсов.

    `json_path`: путь к JSON-файлу или None для чтения из stdin

    Используй `find_free_port` для поиска порта. См. `finding`.
    Используй `load_json_file` и `load_json_stdin` для загрузки JSON. См. `loading`.

---

Author: Goga
CreatedAt: 09/05/26
Description: |
  HTTP-сервер для обслуживания SPA, статических файлов и API данных графа cells.
