diff --git a/dashboards/tracker-web/ROADMAP.md b/dashboards/tracker-web/ROADMAP.md new file mode 100644 index 00000000..2f8f86c2 --- /dev/null +++ b/dashboards/tracker-web/ROADMAP.md @@ -0,0 +1,461 @@ +# Tracker Dashboard โ€” Product Roadmap + +> **Living document.** Coding agents, developers, PMs, and public contributors can submit items +> via the [public roadmap](/roadmap) or the [Agent API](#-agent--automation-api). +> Last updated: 2026-05-25. + +--- + +## Legend + +| Symbol | Meaning | +| ------ | ----------------------- | +| โœ… | Shipped / complete | +| ๐Ÿ”„ | In progress | +| ๐Ÿ”ฒ | Planned โ€” not started | +| ๐Ÿค– | Agent-targeted feature | +| ๐ŸŒ | Public-facing feature | +| ๐Ÿข | Internal / team feature | +| โš ๏ธ | Known bug / gap | + +--- + +## Phase 0 โ€” Foundation (Current State) โœ… + +Everything checked here is already shipped and running. + +### Core Item Management โœ… + +- [x] Create / read / update / delete tracker items +- [x] Item types: `bug` ยท `feature` ยท `task` +- [x] Statuses: `open` โ†’ `in_progress` โ†’ `done` โ†’ `closed` ยท `wont_fix` +- [x] Priority levels: `critical` ยท `high` ยท `medium` ยท `low` +- [x] Visibility toggle: `internal` vs `public` +- [x] Labels (free-text array) +- [x] Assignee field +- [x] Reporter / `reportedBy` tracking +- [x] Target release field +- [x] Source tracking: `internal` ยท `user_submitted` ยท `auto_detected` +- [x] Vote count per item +- [x] Comment count per item + +### Views โœ… + +- [x] Dashboard overview with stats (by type / status / priority) +- [x] Items list with search, filter, paginate +- [x] Kanban board (4-column status board) +- [x] Item detail page with inline edits + +### Public Roadmap โœ… + +- [x] Public `/roadmap` page โ€” no auth required +- [x] Board / list view toggle +- [x] Submit idea form (name + email + type + description) +- [x] Email-based voting (stored in localStorage) +- [x] Stats bar (total ยท votes ยท in-progress ยท completed) +- [x] Search and filter by type + +### Authentication โœ… + +- [x] Email + password login via platform-service +- [x] MFA (multi-factor authentication) +- [x] Google OAuth +- [x] JWT token refresh +- [x] Product switcher (multi-product support via `x-product-id` header) + +### Infrastructure โœ… + +- [x] Dockerised (standalone Next.js build) +- [x] Caddy reverse proxy with HTTPS +- [x] PostHog analytics integration +- [x] Vitest unit tests +- [x] Playwright E2E scaffolding +- [x] ESLint + Prettier + Husky git hooks + +--- + +## Phase 1 โ€” Production Hardening ๐Ÿ”„ + +> **Goal:** Make everything that's built actually reliable in production. +> **Target:** Sprint ending 2026-06-14 + +### 1.1 โ€” Infrastructure Health โš ๏ธ + +- [ ] **Fix platform-service health check** โ€” currently reporting `unhealthy`; diagnose valkey (Redis) โ†’ platform-service dependency chain +- [ ] **Fix valkey container health** โ€” Redis-compatible cache is unhealthy; all session/queue-dependent services degrade +- [ ] **Fix tracker-web health endpoint** โ€” `/health` should verify DB + platform-service connectivity, not just return 200 +- [ ] **Add swap space on VM** โ€” currently 0 B swap; 8 GB minimum to survive build spikes +- [ ] **Kill/limit concurrent CI builds** โ€” Gitea runners spinning up `next build` + `tsc` simultaneously saturate 4-core VM +- [ ] **Add container restart policies** โ€” ensure `restart: unless-stopped` on all services + +### 1.2 โ€” Rate Limiting & Spam Protection ๐ŸŒ + +- [ ] **Rate-limit public `/roadmap/submit`** โ€” no throttling today; bots can flood it +- [ ] **Add hCaptcha / Turnstile to public submission form** โ€” prevent bot submissions +- [ ] **Rate-limit public vote endpoint** โ€” deduplicate votes server-side (not just localStorage) +- [ ] **Validate and sanitize all public inputs** โ€” server-side XSS/injection guards + +### 1.3 โ€” Test Coverage + +- [ ] **Vitest unit tests โ‰ฅ 80% on `src/lib/`** โ€” tracker-client, auth-context, utils +- [ ] **Playwright E2E: login โ†’ create item โ†’ close item** happy path +- [ ] **Playwright E2E: public roadmap submit + vote** flow +- [ ] **Playwright E2E: Kanban status drag (when drag implemented)** +- [ ] **API contract tests** โ€” ensure proxy routes match platform-service schema + +### 1.4 โ€” Error Handling & Observability + +- [ ] **Global error boundary with user-friendly fallback UI** โ€” no raw stack traces to users +- [ ] **Structured server-side logging** โ€” use `@bytelyst/logger` on all API routes +- [ ] **Loki log aggregation** โ€” forward Next.js server logs to Loki (already deployed) +- [ ] **Prometheus metrics on tracker-web** โ€” request count, latency, error rate +- [ ] **Alerting** โ€” alert on health-check failures, error rate spikes (Grafana โ†’ webhook) +- [ ] **Sentry (or equivalent) for client-side errors** โ€” catch unhandled React errors + +### 1.5 โ€” Security + +- [ ] **Security headers audit** โ€” CSP, HSTS, X-Frame-Options, Referrer-Policy on all routes +- [ ] **CSRF protection on all mutating API routes** +- [ ] **API key rotation mechanism** โ€” for agent API keys (see Phase 3) +- [ ] **Audit log** โ€” record who changed what on every item mutation +- [ ] **PII scrubbing in logs** โ€” emails, names must not appear in raw log lines + +--- + +## Phase 2 โ€” Rich Item Details (Linear / Jira parity) ๐Ÿ”ฒ + +> **Goal:** Items rich enough for developers and PMs to fully spec work without leaving the tool. +> **Target:** Sprint ending 2026-07-12 + +### 2.1 โ€” Rich Text & Markdown + +- [ ] **Markdown description editor** โ€” live preview, syntax highlighting, toolbar +- [ ] **Acceptance criteria block** โ€” structured checklist inside item; each criterion is checkable + ``` + Acceptance Criteria + โ˜ User can submit form without login + โ˜ Email confirmation sent within 60s + โ˜ Duplicate email check prevents double-vote + ``` +- [ ] **Steps to reproduce block** (bug type only) โ€” numbered list with copy-as-markdown button +- [ ] **Expected vs Actual behaviour fields** (bug type only) +- [ ] **Code block support in descriptions and comments** โ€” syntax-highlighted fenced blocks +- [ ] **Mention support `@username`** in comments โ†’ notify mentioned user + +### 2.2 โ€” Attachments & Media + +- [ ] **File upload to items** โ€” screenshots, logs, designs (max 25 MB; stored in blob service) +- [ ] **Image paste from clipboard** โ€” paste screenshot directly into description editor +- [ ] **Video embed support** โ€” paste Loom / YouTube URL โ†’ embed player inline +- [ ] **Attachment list on item detail** โ€” show all files with download + delete + +### 2.3 โ€” Relationships & Linking + +- [ ] **Linked items** โ€” `blocks` / `is blocked by` / `relates to` / `duplicate of` +- [ ] **Sub-tasks** โ€” child items under a parent; progress roll-up on parent +- [ ] **Milestones** โ€” group items under a named release milestone with a target date +- [ ] **PR / Commit links** โ€” attach GitHub/Gitea PR URL; show PR title + status badge live +- [ ] **Branch name suggestion** โ€” auto-suggest `feat/tracker-{id}-{slug}` on item detail +- [ ] **External issue links** โ€” link to GitHub issues, Jira, Linear, Notion pages + +### 2.4 โ€” Metadata & Fields + +- [ ] **Effort estimate** โ€” story points (Fibonacci) or T-shirt sizes (XS/S/M/L/XL) +- [ ] **Time tracking** โ€” log hours against an item; total vs estimate +- [ ] **Due date / SLA** โ€” date picker; highlight overdue items in red +- [ ] **Environment** โ€” `production` ยท `staging` ยท `dev` ยท `all` +- [ ] **Affected version** โ€” free-text; links to release notes +- [ ] **Fixed in version** โ€” auto-populated when item closes and a release is cut +- [ ] **Stakeholders / Watchers** โ€” subscribe to item updates without being assignee +- [ ] **Custom fields** โ€” per-product key-value pairs (product teams define their own) +- [ ] **Colour-coded labels** โ€” labels get hex colour; shown as chips + +### 2.5 โ€” Activity & History + +- [ ] **Full activity log on every item** โ€” every field change recorded with actor + timestamp + ``` + 09:14 saravana โ†’ changed status: open โ†’ in_progress + 09:22 codex-agent โ†’ linked PR #142 + 10:05 saravana โ†’ changed priority: medium โ†’ high + ``` +- [ ] **Comment reactions** โ€” emoji reactions on comments (๐Ÿ‘ โœ… ๐Ÿ”ฅ etc.) +- [ ] **Comment edit + delete** โ€” authors can edit/delete their own comments +- [ ] **@mention notifications** โ€” in-app + email when mentioned in comment +- [ ] **Item history diff view** โ€” show before/after for description edits + +### 2.6 โ€” Views & Filters + +- [ ] **Kanban drag-and-drop** โ€” drag cards between status columns (replace button-only transitions) +- [ ] **Saved filter views** โ€” name and save a filter set; pin to sidebar +- [ ] **Bulk actions** โ€” select multiple items โ†’ bulk status change / assign / label / delete +- [ ] **Group by** โ€” group list view by assignee, label, milestone, priority +- [ ] **Timeline / Gantt view** โ€” items with due dates shown on a calendar timeline +- [ ] **My items view** โ€” quick filter: assigned to me / reported by me / watching +- [ ] **Export** โ€” CSV and JSON export of filtered item lists + +--- + +## Phase 3 โ€” Agent & Automation API ๐Ÿค– + +> **Goal:** First-class API for coding agents (Claude Code, Codex, Copilot, custom agents) to +> consume, update, and create tracker items programmatically โ€” closing the loop between +> AI-assisted development and project management. +> **Target:** Sprint ending 2026-07-26 + +### 3.1 โ€” Agent Authentication + +- [ ] **API key management UI** โ€” generate / revoke / rotate API keys per agent identity +- [ ] **Agent identity model** โ€” each key has a `name`, `role` (`agent` / `ci` / `webhook`), `productId` scope, and optional IP allowlist +- [ ] **Scoped permissions** โ€” read-only keys, write keys, admin keys +- [ ] **Key usage log** โ€” last-used timestamp, request count per key +- [ ] **Rate limiting per API key** โ€” configurable RPM per key + +### 3.2 โ€” Agent Item Operations + +- [ ] **`GET /api/agent/items`** โ€” pull items assigned to agent, by label, by status; supports `since` timestamp for polling + ```http + GET /api/agent/items?status=open&label=agent-ready&assignee=codex-agent + Authorization: Bearer + ``` +- [ ] **`POST /api/agent/items`** โ€” agents create items (bug reports from CI, auto-detected regressions) + ```json + { + "type": "bug", + "title": "TypeError in UserCard on null avatar", + "description": "Reproduced in e2e run #4821. Stack trace: ...", + "source": "auto_detected", + "labels": ["ci-failure", "agent-reported"], + "metadata": { "testRun": "4821", "commitSha": "abc123" } + } + ``` +- [ ] **`PATCH /api/agent/items/:id/claim`** โ€” agent claims an item (sets `assignee`, status โ†’ `in_progress`, records claim timestamp); prevents two agents racing on same item +- [ ] **`PATCH /api/agent/items/:id/status`** โ€” update status with a reason and optional evidence +- [ ] **`POST /api/agent/items/:id/comments`** โ€” post implementation notes, test results, error logs +- [ ] **`PATCH /api/agent/items/:id/pr`** โ€” link a PR to an item + ```json + { + "prUrl": "https://github.com/org/repo/pull/142", + "prNumber": 142, + "prTitle": "fix: null-check avatar in UserCard", + "prStatus": "open", + "branch": "fix/tracker-789-null-avatar", + "commitSha": "abc123def456" + } + ``` +- [ ] **`POST /api/agent/items/:id/checklist`** โ€” update acceptance-criteria checklist items (check/uncheck) +- [ ] **`GET /api/agent/items/:id/context`** โ€” fetch full item context formatted for LLM prompt injection (title + description + acceptance criteria + comments + linked PRs as markdown) + +### 3.3 โ€” Webhook Integration (Inbound) + +- [ ] **GitHub webhook receiver** โ€” `POST /api/webhooks/github` + - PR opened โ†’ link to item if branch matches `tracker-{id}` pattern; status โ†’ `in_progress` + - PR merged โ†’ status โ†’ `done`; post merge comment on item + - PR closed without merge โ†’ comment on item; status stays + - CI check failed โ†’ post failure summary as comment on linked item +- [ ] **Gitea webhook receiver** โ€” `POST /api/webhooks/gitea` (same events as GitHub) +- [ ] **Webhook signature verification** โ€” HMAC-SHA256 on all inbound webhooks +- [ ] **Webhook delivery log** โ€” show last 100 inbound webhook events per product; replayable + +### 3.4 โ€” Webhook Integration (Outbound) + +- [ ] **Outbound webhook configuration UI** โ€” register URLs to receive tracker events +- [ ] **Events fired:** `item.created` ยท `item.updated` ยท `item.status_changed` ยท `comment.added` ยท `pr.linked` ยท `item.closed` +- [ ] **Retry with exponential backoff** โ€” retry failed deliveries up to 5ร— over 24 h +- [ ] **Delivery log** โ€” show status of every outbound delivery (200 โœ… / 5xx โŒ / timeout) +- [ ] **Slack integration** โ€” built-in Slack webhook sender; configurable per product + +### 3.5 โ€” Agent SDK / CLI + +- [ ] **`@bytelyst/tracker-client` npm package** โ€” typed client for Node.js agents + ```ts + import { TrackerClient } from '@bytelyst/tracker-client'; + const tracker = new TrackerClient({ apiKey: process.env.TRACKER_KEY, productId: 'chronomind' }); + const items = await tracker.items.list({ status: 'open', label: 'agent-ready' }); + await tracker.items.claim(items[0].id); + ``` +- [ ] **Claude Code hook template** โ€” ready-made `PostToolUse` hook that files a tracker item when tests fail +- [ ] **CI integration guide** โ€” docs + example GitHub Actions step to post build failures as tracker bugs + +### 3.6 โ€” AI-Assisted Triage + +- [ ] **Auto-classify incoming submissions** โ€” LLM call on new public submissions to suggest type + priority + labels +- [ ] **Duplicate detection** โ€” embedding similarity check on new items vs existing open items; surface "possible duplicate of #42" banner +- [ ] **Auto-assign** โ€” configurable rules: items with label `frontend` โ†’ assign to frontend agent; `ci-failure` โ†’ assign to CI agent +- [ ] **Sentiment analysis on public submissions** โ€” flag angry/urgent submissions for faster triage +- [ ] **Auto-generate acceptance criteria** โ€” for feature requests, LLM suggests a checklist based on description + +--- + +## Phase 4 โ€” Multi-Source Intake ๐ŸŒ๐Ÿข + +> **Goal:** Every stakeholder โ€” public users, company team, developers, and agents โ€” has a +> frictionless native path to submit and track items. +> **Target:** Sprint ending 2026-08-09 + +### 4.1 โ€” Public Submission Enhancements ๐ŸŒ + +- [ ] **Public user account (optional)** โ€” create lightweight account to track your own submissions without full platform login +- [ ] **Submission status page** โ€” public URL `/submissions/{token}` shows status of your submitted idea without login +- [ ] **Email notifications to submitters** โ€” "Your idea is now In Progress" / "shipped in v2.3" +- [ ] **Public changelog** โ€” `/changelog` page auto-generated from items closed with `public` visibility + release notes field +- [ ] **Upvote limit per email** โ€” max N votes per product per email to prevent ballot stuffing + +### 4.2 โ€” Internal Team Intake ๐Ÿข + +- [ ] **Quick-capture widget** โ€” floating button on any internal bytelyst dashboard โ†’ pre-fills product + reporter; one-click submit +- [ ] **Browser extension** โ€” capture bugs from any web page with screenshot + URL auto-filled +- [ ] **Email-to-tracker** โ€” send email to `tracker+{product}@bytelyst.com` โ†’ creates item; threading = comments +- [ ] **Slack `/tracker` slash command** โ€” submit item from Slack; subscribe to updates in channel +- [ ] **Microsoft Teams bot** โ€” same as Slack integration (for teams using Teams) + +### 4.3 โ€” Developer Intake ๐Ÿข + +- [ ] **GitHub issue sync (bidirectional)** โ€” link a GitHub repo; issues sync to tracker; tracker status updates push back as GitHub labels +- [ ] **Gitea issue sync** โ€” same as GitHub, targeting the local Gitea instance +- [ ] **`tracker` CLI** โ€” `npx @bytelyst/tracker create --type bug --title "..."` from terminal +- [ ] **VS Code extension** โ€” view assigned items, update status, file bugs without leaving editor +- [ ] **Test failure โ†’ auto-item** โ€” CI step that files a `bug` item on test failures with full test output attached + +### 4.4 โ€” PM / Stakeholder Views ๐Ÿข + +- [ ] **Roadmap presentation mode** โ€” clean full-screen roadmap grouped by milestone; shareable link +- [ ] **Sprint planning board** โ€” drag items into sprints; velocity charts +- [ ] **Release notes generator** โ€” from `done` items in a milestone โ†’ draft release notes markdown +- [ ] **Weekly digest email** โ€” per-product summary: items opened, closed, blocked; sent to watchers + +--- + +## Phase 5 โ€” Analytics & Intelligence ๐Ÿ”ฒ + +> **Target:** Sprint ending 2026-08-30 + +### 5.1 โ€” Item Analytics + +- [ ] **Cycle time tracking** โ€” time from `open` โ†’ `in_progress` โ†’ `done` per item; p50/p95 dashboard +- [ ] **Throughput chart** โ€” items closed per week/sprint over time +- [ ] **Bug burn-down** โ€” open bug count over time; goal line for zero-bug releases +- [ ] **Feature request popularity** โ€” vote leaderboard; trending this week vs all time +- [ ] **Agent productivity** โ€” items closed by agent vs human; PR merge rate per agent + +### 5.2 โ€” SLA & Alerting + +- [ ] **SLA breach alerts** โ€” `critical` bugs open > 24 h โ†’ alert assignee + PM +- [ ] **Stale item detector** โ€” items with no activity for N days โ†’ auto-ping assignee +- [ ] **Blocked item escalation** โ€” items blocked > 3 days โ†’ escalate to team lead + +### 5.3 โ€” Reporting + +- [ ] **CSV / PDF export of any view** +- [ ] **Scheduled email reports** โ€” configure frequency + recipients per product +- [ ] **Embeddable status widget** โ€” `