board-viewer/.tasks/board-viewer-gitea-reader.md

board-viewer-gitea-reader

Goal

Модуль, который через Gitea API читает .tasks/STATUS.md + per-task <slug>.md файлы из всех релевантных репо (OpeItcLoc03/agenda + per-project репо из ~/.config/projects-mcp/auth.toml::gitea_owners) и нормализует в типизированную структуру для рендера.

Это первая импл-таска. Остальные импл-таски (board-viewer-html-render, board-viewer-cron-deploy) зависят от типов, которые этот модуль публикует.

TDD-mode: обязательно по follow tdd-criteria триггеру в .wiki/CLAUDE.md. Сначала тесты на нормализацию пар фикстур (STATUS.md + per-task.md) → потом реализация. Не модифицировать assert'ы во время реализации без [test-modify: ...] маркера в commit subject.

Key files

• src/parser.ts — STATUS.md → StatusBlock[] (pure)
• src/gitea.ts — Gitea HTTP client (DI'd fetch, getFile / getLatestCommitIso / rawUrl)
• src/reader.ts — readBoard(client, repos) → TaskRecord[]; orchestrates parser+client
• src/config.ts — loads ~/.config/projects-mcp/auth.toml → { baseUrl, token, repos }
• tests/fixtures/ — status-single-block.md, status-multi.md, real STATUS.md from books / claude-skills / projects-meta-mcp
• tests/parser.test.ts (9), tests/gitea.test.ts (7), tests/reader.test.ts (5), tests/config.test.ts (4) — 25 tests total

Acceptance criteria

• Output contract: массив объектов с полями:

  {
    slug: string,
    project: string,        // repo name (e.g. "board-viewer", "books")
    project_owner: string,  // gitea owner (e.g. "OpeItcLoc03")
    status: "open" | "in_progress" | "paused" | "blocked" | "done",
    status_emoji: "⚪" | "🔴" | "🟡" | "🔵" | "🟢",
    title: string,          // from STATUS.md block H2 after slug
    where_stopped: string | null,
    next_action: string | null,
    blocker: string | null,
    branch: string | null,
    last_commit_iso: string | null,  // from Gitea API, latest commit touching the task file
    raw_url: string,        // Gitea raw URL to per-task <slug>.md for drawer lazy-fetch
  }
  

• Inputs: список репо из конфига (env var или TOML).
• Auth: Gitea token из ~/.config/projects-mcp/auth.toml::gitea_token (admin scope, читает любой репо).
• Robustness: репо без .tasks/ → пропустить молча (не ошибка). .tasks/STATUS.md без emoji-блоков → пустой массив для этого проекта.
• Tests: фикстуры из ≥3 реальных репо (board-viewer, books, .workshop), assertions покрывают: нормальный case, status без per-task.md (только STATUS.md block), per-task без записи в STATUS.md (legacy), blocked-таски с Blocker: строкой.
• Single language: один из TS / Python. Выбор — за имплементером (TS легче переиспользует с HTML-рендером в одном процессе; Python проще читать конфиг).

Decisions log

• 2026-05-22: task создан промоушеном; контракт фиксирован — это публичный API для html-render.
• 2026-05-22: emoji-словарь выравнен под реальные .tasks/STATUS.md (using-tasks skill): ⚪ open / 🔴 in_progress / 🟡 paused / 🔵 blocked / 🟢 done. Раньше дизайн-док и acceptance путали 🔴/🔵 — исправлено.
• 2026-05-22: язык — TypeScript / Node (vitest, ESM, Node 22). Repo discovery — whitelist board_viewer_repos в auth.toml. Без кэша Gitea API на MVP.

Open questions

• TS (Node 22, vitest, ESM) — выбор подтверждён юзером 2026-05-22.
• Whitelist board_viewer_repos в auth.toml — выбран как явный и контролируемый.
• Без кэширования на MVP — Gitea на том же VDS, latency negligible.

Completed steps

• парсер STATUS.md (src/parser.ts) с маппингом ⚪🔴🟡🔵🟢 → open/in_progress/paused/blocked/done
• Gitea HTTP client (src/gitea.ts): getFile / getLatestCommitIso / rawUrl, DI fetch
• reader orchestrator (src/reader.ts): объединяет parser+client → TaskRecord[]
• TOML config loader (src/config.ts) с whitelist board_viewer_repos
• 25 тестов: 9 парсера (включая 3 real-repo фикстуры), 7 gitea, 5 reader, 4 config
• typecheck clean

Notes

NB: исходный буфер упоминал mcp__projects-meta__tasks_aggregate как возможный источник — это ложная развилка, MCP недоступен HTTP-сервису. Только прямой Gitea API. См. .wiki/concepts/board-viewer.md секцию «Implementation note».