Pipeline/docs/forgejo-issue-batches.md

# Forgejo Issue Integration Batches

Planning artifact for adding Forgejo issue visibility and issue-closing workflows to Pipeline.

This document is written so each section can be copied into a git issue and assigned to an implementation agent. Batches are intentionally small and split by backend-only or frontend-only work. Do not combine backend and frontend work in one implementation issue unless the issue explicitly says it is a coordination step.

## Ground Rules For Agents

- Keep backend issues backend-only: models, migrations, services, API routes, schemas, tests, docs.
- Keep frontend issues frontend-only: generated clients, pages, components, UI tests, styling.
- Do not hand-edit generated frontend API files except in the explicit Orval regeneration issue.
- Do not expose Forgejo tokens in API responses, activity messages, logs, or frontend state.
- Treat Forgejo tokens as high-risk secrets because `write:issue` can mutate external projects.
- Treat Forgejo base URLs as outbound network targets. Validate scheme and normalization deliberately to avoid accidental SSRF footguns.
- Prefer existing Pipeline patterns:
  - Backend routers: `backend/app/api/*.py`
  - Backend schemas: `backend/app/schemas/*.py`
  - Backend models: `backend/app/models/*.py`
  - Backend tests: `backend/tests/test_*`
  - Frontend pages: `frontend/src/app/**/page.tsx`
  - Frontend generated hooks: `frontend/src/api/generated/**`
  - Frontend tables: `frontend/src/components/tables/DataTable.tsx`
  - Frontend shell/sidebar: `frontend/src/components/templates/DashboardPageLayout.tsx`, `frontend/src/components/organisms/DashboardSidebar.tsx`
- Add focused tests for each batch. Avoid relying on future batches.
- If a batch needs an API from an earlier batch, assume that earlier batch is already merged.

## Assumptions

- Git project integration means Forgejo or Gitea-compatible git projects.
- Pipeline stores Forgejo tokens server-side only.
- Humans should be able to view tracked issues in Pipeline.
- Agents should be able to view issues through agent-scoped APIs.
- Only board lead agents can close issues in the first implementation pass.
- Closing an issue should update Forgejo and then update Pipeline's local tracking cache.
- Generated frontend API clients come from Orval after backend OpenAPI routes exist.

## Reference Notes

- Forgejo API usage supports `Authorization: token ...` and paginated API responses.
- Forgejo access tokens should use `read:issue` for read-only issue access and `write:issue` for issue closing or mutation.
- Forgejo exposes an OpenAPI document at `/swagger.v1.json` on a Forgejo host.
- Forgejo's issue edit operation is `PATCH /api/v1/repos/{owner}/{repo}/issues/{index}`. Closing an issue should send a body with `state: "closed"`.
- Forgejo issue list endpoints are paginated with `page` and `limit`; hosts can cap page sizes. The default and max values are available from `/api/v1/settings/api`.
- Forgejo issue APIs may include pull requests depending on endpoint/query options. MVP issue sync should exclude pull requests.

Sources:

- https://forgejo.codeberg.page/docs/v7.0/user/api-usage/
- https://forgejo.org/docs/v11.0/user/token-scope/
- https://docs.rs/forgejo-api/latest/forgejo_api/

## Current Pipeline Fit

Pipeline already has useful architecture for this work:

- FastAPI routers mounted under `/api/v1` in `backend/app/main.py`.
- SQLModel models and Alembic migrations.
- Organization, board, and agent access dependencies in `backend/app/api/deps.py`.
- Agent-scoped API routes in `backend/app/api/agent.py`.
- Activity events in `backend/app/models/activity_events.py` and `backend/app/services/activity_log.py`.
- Dashboard metrics aggregation in `backend/app/api/metrics.py`.
- Frontend generated React Query hooks via `frontend/orval.config.ts`.
- Existing dashboard, table, settings, and admin page patterns.

## Recommended Backend Order

1. Add Forgejo database models.
2. Add admin connection CRUD API.
3. Add admin tracked repository CRUD API.
4. Add Forgejo API client service.
5. Add backend connection validation API.
6. Add cached issue database model.
7. Add issue sync service and manual sync API.
8. Add human issue list/read APIs.
9. Add board-to-repository link database model.
10. Add board repository linking APIs.
11. Add agent issue read APIs.
12. Add close issue service.
13. Add human and agent close issue APIs.
14. Add issue tracking metrics.
15. Optional: add Forgejo webhook ingest.

## Recommended Frontend Order

1. Regenerate API client after backend routes are merged.
2. Add Git Projects navigation and shell page.
3. Add admin Forgejo connection UI.
4. Add admin tracked repository UI.
5. Add manual repository sync UI.
6. Add connection validation UI.
7. Add issue list view.
8. Add board repository linking UI.
9. Add board-level linked issues panel.
10. Add close issue action.
11. Add dashboard issue tracking widgets.
12. Final UI polish and theme review.

---

## Backend Issue 1: Add Forgejo Database Models

Labels: `backend`, `database`, `forgejo`

### Goal

Add the database foundation for Forgejo connections and tracked repositories.

### Scope

- Add SQLModel models for Forgejo connections and tracked repositories.
- Add an Alembic migration.
- Add model imports where Pipeline expects metadata discovery.
- Do not add API routes in this issue.

### Suggested Implementation References

- Existing models: `backend/app/models/gateways.py`, `backend/app/models/boards.py`
- Existing migrations: `backend/migrations/versions/*`
- Model registry import patterns: `backend/app/models/__init__.py`

### Suggested Model Shape

- `ForgejoConnection`
  - `id`
  - `organization_id`
  - `name`
  - `base_url`
  - `token`
  - `token_last_eight`
  - `active`
  - `created_at`
  - `updated_at`
- `ForgejoRepository`
  - `id`
  - `organization_id`
  - `connection_id`
  - `owner`
  - `repo`
  - `display_name`
  - `default_branch`
  - `active`
  - `last_sync_at`
  - `last_sync_error`
  - `created_at`
  - `updated_at`

### Acceptance Criteria

- Migration creates `forgejo_connections` and `forgejo_repositories`.
- Foreign keys and indexes support organization-scoped lookup.
- Token is nullable only if intentionally supported by validation later.
- Store a token hint such as the last eight characters so admins can identify which token is configured without exposing it.
- Prefer encrypted token storage if Pipeline already has a secret-encryption utility available; otherwise document that this batch follows the existing gateway-token storage pattern and leave encryption as a separate security hardening issue.
- No API routes are added.
- A focused model/migration test or metadata test passes.

### Out Of Scope

- CRUD endpoints.
- Forgejo HTTP calls.
- Issue syncing.
- Frontend UI.

---

## Backend Issue 2: Add Admin Forgejo Connection CRUD API

Labels: `backend`, `api`, `forgejo`, `admin`

### Goal

Allow organization admins to manage Forgejo connections.

### Scope

- Add Forgejo connection schemas.
- Add admin-only list/create/read/update/delete endpoints for connections.
- Redact tokens from all read responses.
- Keep repository management out of this issue.

### Suggested Implementation References

- Admin dependency: `backend/app/api/deps.py` `require_org_admin`
- Gateway CRUD style: `backend/app/api/gateways.py`, `backend/app/schemas/gateways.py`
- Router wiring: `backend/app/main.py`
- Response wrapper: `backend/app/schemas/common.py` `OkResponse`

### Suggested Endpoints

- `GET /api/v1/forgejo/connections`
- `POST /api/v1/forgejo/connections`
- `GET /api/v1/forgejo/connections/{connection_id}`
- `PATCH /api/v1/forgejo/connections/{connection_id}`
- `DELETE /api/v1/forgejo/connections/{connection_id}`

### Acceptance Criteria

- Only organization admins can create/update/delete connections.
- Connection list/read responses never include the token.
- Updating token with an empty string leaves existing token unchanged or clears it only if the schema explicitly supports clearing.
- Read responses include only safe token metadata such as `has_token` and `token_last_eight`.
- `base_url` is normalized to a root Forgejo host URL, not a full API endpoint path.
- `base_url` accepts only `http` or `https`.
- Cross-organization access returns 404 or 403 consistently with existing Pipeline APIs.
- Tests cover create, list redaction, update, delete, and non-admin rejection.

### Out Of Scope

- Repository CRUD.
- Calling Forgejo.
- Frontend UI.

---

## Backend Issue 3: Add Admin Tracked Repository CRUD API

Labels: `backend`, `api`, `forgejo`, `admin`

### Goal

Allow organization admins to register Forgejo repositories that Pipeline should track.

### Scope

- Add repository schemas.
- Add admin-only list/create/read/update/delete endpoints for tracked repositories.
- Validate the selected connection belongs to the caller's organization.
- Do not sync issues in this issue.

### Suggested Implementation References

- Gateway list/create patterns: `backend/app/api/gateways.py`
- Board list patterns: `backend/app/api/boards.py`
- Pagination helper: `backend/app/db/pagination.py`

### Suggested Endpoints

- `GET /api/v1/forgejo/repositories`
- `POST /api/v1/forgejo/repositories`
- `GET /api/v1/forgejo/repositories/{repository_id}`
- `PATCH /api/v1/forgejo/repositories/{repository_id}`
- `DELETE /api/v1/forgejo/repositories/{repository_id}`

### Acceptance Criteria

- Admins can manage tracked repositories.
- Repository read includes connection id and safe connection display metadata.
- Duplicate active repository records for the same organization/connection/owner/repo are rejected.
- Repository `owner` and `repo` are normalized by trimming whitespace.
- Store raw display values and normalized lookup values if needed to enforce duplicate checks without losing original casing.
- Tests cover CRUD, duplicate rejection, and cross-organization connection rejection.

### Out Of Scope

- Issue cache.
- Issue sync.
- Board links.
- Frontend UI.

---

## Backend Issue 4: Add Forgejo API Client Service

Labels: `backend`, `forgejo`, `api-client`

### Goal

Create a small internal service for Forgejo REST calls.

### Scope

- Add a service wrapper around Forgejo issue APIs.
- Use `httpx.AsyncClient`.
- Support configured base URL and token auth.
- Normalize Forgejo API errors into Pipeline service exceptions.
- Support issue list and close issue operations.

### Suggested Implementation References

- HTTP client style: `backend/app/services/souls_directory.py`
- Logging policy: `backend/app/core/logging.py`
- Backend dependencies: `backend/pyproject.toml`

### Suggested Service API

- `list_issues(owner, repo, state, page, limit)`
- `close_issue(owner, repo, issue_number)`
- `get_repository(owner, repo)`

### Acceptance Criteria

- Client sends `Authorization: token <token>`.
- Client sets a short connect/read timeout.
- Client sends a Pipeline-specific user agent.
- Client can list issues for `owner/repo` with state, page, and limit.
- Client excludes pull requests from issue sync when Forgejo returns issue and pull-request data together.
- Client can close one issue by owner, repo, and issue number using `PATCH /api/v1/repos/{owner}/{repo}/issues/{index}` and `{"state": "closed"}`.
- Client can fetch repository metadata to validate owner/repo and token access.
- Client handles non-2xx responses with clear error messages.
- Tests mock HTTP responses and do not require a real Forgejo server.

### Out Of Scope

- Database models.
- API routes.
- Frontend UI.

---

## Backend Issue 5: Add Backend Connection Validation API

Labels: `backend`, `api`, `forgejo`, `validation`

### Goal

Let admins validate that a Forgejo connection and tracked repository are reachable before relying on sync.

### Scope

- Add a lightweight validation endpoint for a connection.
- Add a lightweight validation endpoint for a tracked repository.
- Use the Forgejo API client from Backend Issue 4.
- Do not persist issues in this issue.

### Suggested Implementation References

- Backend gateway admin patterns: `backend/app/api/gateways.py`
- Gateway runtime compatibility checks: `backend/app/services/openclaw/admin_service.py`
- Forgejo API client from Backend Issue 4.

### Suggested Endpoints

- `POST /api/v1/forgejo/connections/{connection_id}/validate`
- `POST /api/v1/forgejo/repositories/{repository_id}/validate`

### Acceptance Criteria

- Connection validation confirms the configured base URL and token can make an authenticated API request.
- Repository validation confirms owner/repo exists and token can read issue data.
- Errors are safe for display and never include token values.
- Tests cover success, bad token, missing repo, and remote timeout.

### Out Of Scope

- Issue sync.
- Frontend UI.

---

## Backend Issue 6: Add Cached Issue Database Model

Labels: `backend`, `database`, `forgejo`, `issues`

### Goal

Add a local cache table for Forgejo issues.

### Scope

- Add `ForgejoIssue` model.
- Add migration for cached issue fields.
- Add read schema for cached issue records.
- Do not add sync logic in this issue.

### Suggested Implementation References

- Task model timestamp/status style: `backend/app/models/tasks.py`
- Activity event model simplicity: `backend/app/models/activity_events.py`
- Schema style: `backend/app/schemas/tasks.py`

### Suggested Model Shape

- `id`
- `organization_id`
- `repository_id`
- `forgejo_issue_number`
- `title`
- `body_preview`
- `state`
- `is_pull_request`
- `labels`
- `assignees`
- `author`
- `html_url`
- `forgejo_created_at`
- `forgejo_updated_at`
- `forgejo_closed_at`
- `last_synced_at`
- `created_at`
- `updated_at`

### Acceptance Criteria

- Migration creates `forgejo_issues`.
- Unique constraint or unique index prevents duplicate issue numbers per tracked repository.
- JSON fields use existing SQLModel JSON column patterns.
- Model can represent pull-request rows if they are accidentally received, but MVP sync should mark and ignore them in issue views.
- Read schema excludes secrets and includes enough display fields for frontend tables.
- Tests cover model construction and uniqueness behavior if practical.

### Out Of Scope

- Forgejo HTTP calls.
- Sync endpoint.
- Frontend UI.

---

## Backend Issue 7: Add Issue Sync Service And Manual Sync API

Labels: `backend`, `forgejo`, `sync`, `issues`

### Goal

Fetch issues from Forgejo and upsert them into Pipeline's local issue cache.

### Scope

- Add a sync service that uses the Forgejo API client.
- Add admin-only manual sync endpoint for one tracked repository.
- Upsert issues into `forgejo_issues`.
- Update repository sync metadata.

### Suggested Implementation References

- Service tests with mocked calls: `backend/tests/test_board_webhooks_api.py`
- Activity recording: `backend/app/services/activity_log.py`
- CRUD helpers: `backend/app/db/crud.py`

### Suggested Endpoint

- `POST /api/v1/forgejo/repositories/{repository_id}/sync`

### Acceptance Criteria

- Sync paginates through Forgejo issues using `page` and `limit`.
- Sync stores open and closed issues.
- Sync excludes pull requests from MVP issue counts and issue views.
- Sync returns created, updated, open, closed, and total counts.
- Sync updates `last_sync_at` on success.
- Sync updates `last_sync_error` on failure without leaking token values.
- Tests cover pagination, idempotent upsert, and Forgejo failure.

### Out Of Scope

- Human issue list API.
- Agent issue API.
- Frontend UI.

---

## Backend Issue 8: Add Human Issue List And Read APIs

Labels: `backend`, `api`, `forgejo`, `issues`

### Goal

Allow authenticated Pipeline users to view cached Forgejo issues through Pipeline APIs.

### Scope

- Add list/read endpoints for cached Forgejo issues.
- Enforce organization access.
- Support useful filters.
- Return paginated responses.

### Suggested Implementation References

- User/org access dependencies: `backend/app/api/deps.py`
- Activity list filtering style: `backend/app/api/activity.py`
- Task list filtering style: `backend/app/api/tasks.py`
- Pagination response: `backend/app/schemas/pagination.py`

### Suggested Endpoints

- `GET /api/v1/forgejo/issues`
- `GET /api/v1/forgejo/issues/{issue_id}`

### Acceptance Criteria

- Users can list issues by repository id, state, label text, assignee text, and search text.
- Users can read one cached issue by id.
- Users cannot read issues from another organization.
- Pull requests are excluded from issue list responses in MVP.
- Responses never include connection tokens.
- Tests cover allowed access, forbidden cross-org access, filters, and pagination.

### Out Of Scope

- Board-scoped repository links.
- Issue closing.
- Agent routes.
- Frontend UI.

---

## Backend Issue 9: Add Board-To-Repository Link Database Model

Labels: `backend`, `database`, `forgejo`, `boards`

### Goal

Add the data model for linking tracked Forgejo repositories to Pipeline boards.

### Scope

- Add mapping model between boards and tracked repositories.
- Add migration.
- Add basic schema if needed.
- Do not add API routes in this issue.

### Suggested Implementation References

- Task dependency model: `backend/app/models/task_dependencies.py`
- Organization board access model: `backend/app/models/organization_board_access.py`
- Migration examples: `backend/migrations/versions/*`

### Suggested Model Shape

- `id`
- `board_id`
- `repository_id`
- `organization_id`
- `created_at`

### Acceptance Criteria

- Migration creates board/repository link table.
- Unique constraint prevents duplicate board/repository links.
- Foreign keys reference boards and Forgejo repositories.
- Indexes support lookup by board and repository.

### Out Of Scope

- Board link API.
- Frontend UI.

---

## Backend Issue 10: Add Board Repository Linking APIs

Labels: `backend`, `api`, `forgejo`, `boards`

### Goal

Let Pipeline boards declare which tracked Forgejo repositories belong to that board.

### Scope

- Add board-scoped endpoints to attach, detach, and list linked repositories.
- Enforce board write access for attach/detach.
- Enforce board read access for list.
- Ensure repository belongs to same organization as board.

### Suggested Implementation References

- Board access dependencies: `backend/app/api/deps.py`
- Board webhooks nested route style: `backend/app/api/board_webhooks.py`
- Board memory nested route style: `backend/app/api/board_memory.py`

### Suggested Endpoints

- `GET /api/v1/boards/{board_id}/forgejo/repositories`
- `POST /api/v1/boards/{board_id}/forgejo/repositories`
- `DELETE /api/v1/boards/{board_id}/forgejo/repositories/{repository_id}`

### Acceptance Criteria

- Board writers can attach a tracked repository to a board.
- Board writers can detach a tracked repository from a board.
- Board readers can list linked repositories.
- Duplicate links are rejected or treated idempotently.
- Tests cover access checks, duplicate behavior, and cross-organization rejection.

### Out Of Scope

- Agent issue routes.
- Issue closing.
- Frontend UI.

---

## Backend Issue 11: Add Agent Issue Read APIs

Labels: `backend`, `agent-api`, `forgejo`, `issues`

### Goal

Allow agents to discover and inspect Forgejo issues for their accessible boards.

### Scope

- Add agent-scoped issue list/read routes.
- Restrict results to repositories linked to the target board.
- Add OpenAPI LLM routing hints consistent with existing agent routes.

### Suggested Implementation References

- Existing agent route hints: `backend/app/api/agent.py` `_agent_board_openapi_hints`
- Agent board access guard: `backend/app/api/agent.py` `_guard_board_access`
- Agent task list route: `backend/app/api/agent.py` `list_tasks`

### Suggested Endpoints

- `GET /api/v1/agent/boards/{board_id}/git/issues`
- `GET /api/v1/agent/boards/{board_id}/git/issues/{issue_id}`

### Acceptance Criteria

- Board-scoped agents only see issues for their assigned board.
- Main agents are constrained by organization/gateway scope.
- Agents only see issues for repositories linked to the board.
- Pull requests are excluded from agent issue responses in MVP.
- Routes include LLM guidance metadata.
- Tests cover board-scoped access and forbidden cross-board access.

### Out Of Scope

- Closing issues.
- Frontend UI.

---

## Backend Issue 12: Add Close Issue Service

Labels: `backend`, `forgejo`, `service`, `issues`

### Goal

Create reusable backend service logic for closing a Forgejo issue and updating local cache.

### Scope

- Add service function that closes the remote Forgejo issue.
- Update cached issue only after Forgejo succeeds.
- Return normalized result payload or model.
- Record no HTTP routes in this issue.

### Suggested Implementation References

- Forgejo client service from Backend Issue 4.
- Sync upsert helpers from Backend Issue 7.
- Activity logging style: `backend/app/services/activity_log.py`

### Suggested Service API

- `close_cached_issue(session, issue, actor_agent_id=None, actor_user_id=None)`

### Acceptance Criteria

- Service does not close local cache if Forgejo call fails.
- Service uses Forgejo's issue edit endpoint: `PATCH /api/v1/repos/{owner}/{repo}/issues/{index}` with `state: "closed"`.
- Service treats already closed local issues consistently.
- Service updates state, closed timestamp, and last synced timestamp.
- Unit tests cover success, remote failure, and already-closed behavior.

### Out Of Scope

- Human API route.
- Agent API route.
- Frontend UI.

---

## Backend Issue 13: Add Human And Agent Close Issue APIs

Labels: `backend`, `api`, `agent-api`, `forgejo`, `audit`

### Goal

Expose issue close mutations to authorized humans and board lead agents.

### Scope

- Add human close endpoint.
- Add agent close endpoint.
- Use the close issue service from Backend Issue 12.
- Record activity events.
- Enforce authorization.

### Suggested Implementation References

- User board write dependency: `backend/app/api/deps.py` `get_board_for_user_write`
- Agent lead check: `backend/app/api/agent.py` `_require_board_lead`
- Activity events: `backend/app/services/activity_log.py`
- Task delete lead-only route: `backend/app/api/agent.py`

### Suggested Endpoints

- `POST /api/v1/forgejo/issues/{issue_id}/close`
- `POST /api/v1/agent/boards/{board_id}/git/issues/{issue_id}/close`

### Acceptance Criteria

- Human board writers/admins can close linked issues.
- Board lead agents can close linked issues.
- Non-lead worker agents cannot close issues.
- Issue must be linked to the target board before a board-scoped human or agent can close it.
- Forgejo failure does not mark the local issue closed.
- Successful close records an activity event with board id, actor, repository, and issue number.
- Tests cover success, forbidden worker agent, Forgejo failure, and cache update.

### Out Of Scope

- Reopening issues.
- Creating issues.
- Frontend UI.

---

## Backend Issue 14: Add Issue Tracking Metrics

Labels: `backend`, `metrics`, `forgejo`

### Goal

Expose aggregate tracking data for Forgejo issues in Pipeline metrics.

### Scope

- Add issue counters to metrics service or add a focused issue metrics endpoint.
- Support organization, board, and repository scopes.
- Include last sync health.

### Suggested Implementation References

- Existing metrics endpoint: `backend/app/api/metrics.py`
- Existing metrics schemas: `backend/app/schemas/metrics.py`
- Existing metrics tests: `backend/tests/test_metrics_kpis.py`

### Suggested Metrics

- Open issues.
- Closed issues.
- Issues closed in selected range.
- Stale open issues.
- Last successful sync timestamp.
- Repository sync error count.

### Acceptance Criteria

- Metrics can be filtered by board and repository where applicable.
- Empty scope returns zeroes.
- Pull requests are excluded from issue metrics in MVP.
- Tests cover mixed open/closed data and stale issue calculation.
- Existing dashboard metrics tests continue to pass.

### Out Of Scope

- Frontend dashboard widgets.
- Webhook ingest.

---

## Backend Issue 15: Optional Forgejo Webhook Ingest For Issue Updates

Labels: `backend`, `forgejo`, `webhooks`, `optional`

### Goal

Allow Forgejo webhooks to update cached issues without waiting for manual sync.

### Scope

- Add webhook receiver for issue opened, edited, closed, and reopened events.
- Validate a shared secret.
- Update cached issue records.
- Record activity events.

### Suggested Implementation References

- Existing board webhook security patterns: `backend/app/api/board_webhooks.py`
- Webhook tests: `backend/tests/test_security_fixes.py`, `backend/tests/test_board_webhooks_api.py`

### Suggested Endpoint

- `POST /api/v1/forgejo/webhooks/{repository_id}`

### Acceptance Criteria

- Webhook rejects invalid signatures.
- Webhook updates cached issue state and metadata.
- Webhook ignores pull-request events in MVP unless a later issue explicitly adds PR tracking.
- Webhook records activity for close/reopen events.
- Manual sync still works and remains the repair path.

### Out Of Scope

- First-pass MVP.
- Frontend UI.

---

## Frontend Issue 1: Regenerate API Client After Forgejo Backend Routes

Labels: `frontend`, `api-client`, `forgejo`

### Goal

Regenerate Orval clients after backend Forgejo routes are available.

### Scope

- Run Orval against the backend OpenAPI schema.
- Commit generated model and hook files.
- Ensure TypeScript still passes.

### Suggested Implementation References

- Orval config: `frontend/orval.config.ts`
- Existing generated APIs: `frontend/src/api/generated/**`
- API mutator: `frontend/src/api/mutator.ts`

### Acceptance Criteria

- Generated client includes Forgejo connection, repository, issue, sync, metrics, and close endpoints available at that point.
- `npm run lint` passes.
- `npx tsc --noEmit` passes.

### Out Of Scope

- Handwritten UI.
- Backend changes.

---

## Frontend Issue 2: Add Git Projects Navigation And Shell Page

Labels: `frontend`, `navigation`, `forgejo`

### Goal

Add a landing page for Git Projects inside Pipeline.

### Scope

- Add sidebar navigation item.
- Add route for Git Projects.
- Use `DashboardPageLayout`.
- Show loading, empty, and error states.

### Suggested Implementation References

- Sidebar: `frontend/src/components/organisms/DashboardSidebar.tsx`
- Page layout: `frontend/src/components/templates/DashboardPageLayout.tsx`
- Boards page pattern: `frontend/src/app/boards/page.tsx`

### Suggested Files

- `frontend/src/app/git-projects/page.tsx`

### Acceptance Criteria

- Signed-in users can navigate to Git Projects.
- Page lists tracked repositories or shows an empty state.
- Uses generated API hooks.
- No mutations in this batch.
- `npm run lint` and `npx tsc --noEmit` pass.

### Out Of Scope

- Connection forms.
- Issue list table.
- Close action.

---

## Frontend Issue 3: Add Admin Forgejo Connection UI

Labels: `frontend`, `admin`, `forgejo`

### Goal

Let admins configure Forgejo connections.

### Scope

- Add connection list table.
- Add connection create/edit form.
- Add delete confirmation.
- Keep repository management out of this issue.

### Suggested Implementation References

- Gateway admin page: `frontend/src/app/gateways/page.tsx`
- Gateway form pattern: `frontend/src/components/gateways/GatewayForm.tsx`
- Confirm dialog: `frontend/src/components/ui/confirm-action-dialog.tsx`

### Suggested Files

- `frontend/src/app/git-projects/connections/page.tsx`
- `frontend/src/app/git-projects/connections/new/page.tsx`
- `frontend/src/app/git-projects/connections/[connectionId]/edit/page.tsx`
- `frontend/src/components/git/ForgejoConnectionsTable.tsx`
- `frontend/src/components/git/ForgejoConnectionForm.tsx`

### Acceptance Criteria

- Admins can add and edit Forgejo base URL and token.
- Token is write-only and never displayed after save.
- Safe token metadata such as `token_last_eight` may be shown if returned by the API.
- Non-admin users do not see admin actions.
- Empty/loading/error states are present.
- `npm run lint` and `npx tsc --noEmit` pass.

### Out Of Scope

- Repository management.
- Issue list.
- Close issue action.

---

## Frontend Issue 4: Add Admin Tracked Repository UI

Labels: `frontend`, `admin`, `forgejo`, `repositories`

### Goal

Let admins register Forgejo repositories for Pipeline tracking.

### Scope

- Add tracked repository table.
- Add create/edit form.
- Select connection from existing Forgejo connections.
- Add delete confirmation.

### Suggested Implementation References

- Tables: `frontend/src/components/tables/DataTable.tsx`
- Boards table pattern: `frontend/src/components/boards/BoardsTable.tsx`
- Searchable select: `frontend/src/components/ui/searchable-select.tsx`

### Suggested Files

- `frontend/src/app/git-projects/repositories/page.tsx`
- `frontend/src/app/git-projects/repositories/new/page.tsx`
- `frontend/src/app/git-projects/repositories/[repositoryId]/edit/page.tsx`
- `frontend/src/components/git/ForgejoRepositoriesTable.tsx`
- `frontend/src/components/git/ForgejoRepositoryForm.tsx`

### Acceptance Criteria

- Admins can add tracked repositories by connection, owner, and repo.
- Admins can edit display fields and active state.
- Repository table shows last sync status if available.
- Non-admin users do not see admin actions.
- `npm run lint` and `npx tsc --noEmit` pass.

### Out Of Scope

- Manual sync button.
- Issue list.
- Board linking UI.

---

## Frontend Issue 5: Add Manual Repository Sync UI

Labels: `frontend`, `admin`, `forgejo`, `sync`

### Goal

Let admins trigger manual issue sync for tracked repositories.

### Scope

- Add sync action to repository table or repository detail.
- Show sync in-progress, success, and error states.
- Refetch repository and issue data after sync.

### Suggested Implementation References

- Optimistic/invalidation helper: `frontend/src/lib/list-delete.ts`
- Existing mutation patterns: `frontend/src/app/gateways/page.tsx`
- Button component: `frontend/src/components/ui/button.tsx`

### Suggested Files

- `frontend/src/components/git/ForgejoRepositoriesTable.tsx`
- `frontend/src/app/git-projects/repositories/page.tsx`

### Acceptance Criteria

- Admin can trigger sync from repository row.
- UI prevents duplicate clicks while sync is pending.
- Success shows created/updated/open/closed counts.
- Failure shows backend error message.
- `npm run lint` and `npx tsc --noEmit` pass.

### Out Of Scope

- Backend sync implementation.
- Issue list table.

---

## Frontend Issue 6: Add Connection Validation UI

Labels: `frontend`, `admin`, `forgejo`, `validation`

### Goal

Let admins validate Forgejo connections and tracked repositories from the UI.

### Scope

- Add "Validate" actions for connections and repositories.
- Show success/failure status inline.
- Keep validation separate from manual sync.

### Suggested Implementation References

- Gateway connection check UX: `frontend/src/components/gateways/GatewayForm.tsx`
- Mutation/error patterns: `frontend/src/app/gateways/page.tsx`
- Badge component: `frontend/src/components/ui/badge.tsx`

### Suggested Files

- `frontend/src/components/git/ForgejoConnectionsTable.tsx`
- `frontend/src/components/git/ForgejoRepositoriesTable.tsx`

### Acceptance Criteria

- Admin can validate a connection.
- Admin can validate a repository.
- Validation errors show safe backend messages.
- Pending state prevents duplicate validation clicks.
- `npm run lint` and `npx tsc --noEmit` pass.

### Out Of Scope

- Manual sync.
- Backend validation implementation.

---

## Frontend Issue 7: Add Issue List View

Labels: `frontend`, `issues`, `forgejo`

### Goal

Show cached Forgejo issues across tracked repositories.

### Scope

- Add issue list table.
- Add filters for repository, state, and search text.
- Link each issue to its Forgejo URL.

### Suggested Implementation References

- Activity page filtering/list pattern: `frontend/src/app/activity/page.tsx`
- Data table: `frontend/src/components/tables/DataTable.tsx`
- Cell formatters: `frontend/src/components/tables/cell-formatters.tsx`

### Suggested Files

- `frontend/src/app/git-projects/issues/page.tsx`
- `frontend/src/components/git/ForgejoIssuesTable.tsx`
- `frontend/src/components/git/ForgejoIssueFilters.tsx`

### Acceptance Criteria

- Table columns include repository, number, title, state, labels, assignee, and updated time.
- Users can filter by repo and state.
- Users can search by title/body text when backend supports it.
- Forgejo issue links open in a new tab.
- Pull requests are not shown in MVP issue lists.
- Empty/loading/error states are present.
- `npm run lint` and `npx tsc --noEmit` pass.

### Out Of Scope

- Close action.
- Board detail integration.

---

## Frontend Issue 8: Add Board Repository Linking UI

Labels: `frontend`, `boards`, `forgejo`, `admin`

### Goal

Let authorized users link tracked Forgejo repositories to a Pipeline board.

### Scope

- Add board repository link management UI.
- Allow attach/detach using backend board repository link APIs.
- Keep issue rendering out of this issue.

### Suggested Implementation References

- Board edit/detail page: `frontend/src/app/boards/[boardId]/page.tsx`
- Searchable select: `frontend/src/components/ui/searchable-select.tsx`
- Confirm dialog: `frontend/src/components/ui/confirm-action-dialog.tsx`

### Suggested Files

- `frontend/src/components/git/BoardForgejoRepositoryLinks.tsx`
- `frontend/src/app/boards/[boardId]/page.tsx`

### Acceptance Criteria

- Board users with write access can attach repositories.
- Board users with write access can detach repositories.
- Board readers can see linked repositories without edit actions.
- Empty/loading/error states are present.
- `npm run lint` and `npx tsc --noEmit` pass.

### Out Of Scope

- Issue panel.
- Close issue action.

---

## Frontend Issue 9: Add Board-Level Linked Issues Panel

Labels: `frontend`, `boards`, `forgejo`, `issues`

### Goal

Show Forgejo issues that belong to repositories linked to a board.

### Scope

- Add a panel or tab on board detail.
- Show linked repository issues.
- Include state filter.

### Suggested Implementation References

- Board page: `frontend/src/app/boards/[boardId]/page.tsx`
- Existing board panels/components in `frontend/src/components`
- Table empty state: `frontend/src/components/ui/table-state.tsx`

### Suggested Files

- `frontend/src/components/git/BoardForgejoIssuesPanel.tsx`
- `frontend/src/components/git/ForgejoIssuesTable.tsx`

### Acceptance Criteria

- Board page shows linked repository issues.
- Empty state explains that no repositories are linked.
- Panel refetches on normal board refresh cadence.
- No close action in this batch.
- `npm run lint` and `npx tsc --noEmit` pass.

### Out Of Scope

- Repository linking management.
- Close action.

---

## Frontend Issue 10: Add Close Issue Action

Labels: `frontend`, `issues`, `forgejo`, `mutation`

### Goal

Allow authorized users to close Forgejo issues from Pipeline.

### Scope

- Add close button/action where issue rows are shown.
- Add confirmation dialog.
- Invalidate/refetch issue queries after success.
- Show API errors clearly.

### Suggested Implementation References

- Confirm dialog: `frontend/src/components/ui/confirm-action-dialog.tsx`
- Existing delete mutation pattern: `frontend/src/app/boards/page.tsx`
- Generated mutation hooks from Frontend Issue 1.

### Suggested Files

- `frontend/src/components/git/ForgejoIssuesTable.tsx`
- `frontend/src/components/git/CloseForgejoIssueDialog.tsx`
- `frontend/src/app/git-projects/issues/page.tsx`
- `frontend/src/components/git/BoardForgejoIssuesPanel.tsx`

### Acceptance Criteria

- Open issues show a close action when the API/user role allows it.
- Pull requests do not show a close action in MVP issue surfaces.
- Confirmation dialog names repository and issue number.
- Successful close updates UI state.
- Failed close shows the backend error.
- Closed issues do not show an active close action.
- `npm run lint` and `npx tsc --noEmit` pass.

### Out Of Scope

- Agent UI.
- Reopen action.

---

## Frontend Issue 11: Add Dashboard Issue Tracking Widgets

Labels: `frontend`, `dashboard`, `metrics`, `forgejo`

### Goal

Add high-level Forgejo issue tracking to Pipeline dashboard.

### Scope

- Display issue metrics from backend.
- Link widgets to Git Projects issue list.
- Keep dashboard layout consistent with existing cards.

### Suggested Implementation References

- Dashboard page: `frontend/src/app/dashboard/page.tsx`
- Existing generated metrics hook: `frontend/src/api/generated/metrics/metrics.ts`
- Number/date formatting: `frontend/src/lib/formatters.ts`

### Suggested Files

- `frontend/src/components/git/ForgejoIssueMetricCards.tsx`
- `frontend/src/app/dashboard/page.tsx`

### Acceptance Criteria

- Dashboard shows open issues, recently closed issues, stale open issues, and last sync health.
- Widgets link to relevant filtered issue list views.
- Empty metrics render cleanly.
- `npm run lint` and `npx tsc --noEmit` pass.

### Out Of Scope

- Backend metrics changes.
- Connection management UI.

---

## Frontend Issue 12: Final UI Polish And Theme Review

Labels: `frontend`, `design`, `polish`, `forgejo`

### Goal

Review the completed Forgejo/Git Projects UI end-to-end and make it fit Pipeline's modern dark-default theme.

### Scope

- Review Git Projects pages, repository admin pages, issue lists, board panels, close dialogs, and dashboard widgets.
- Align spacing, colors, empty states, loading states, table density, focus states, and responsive behavior.
- Ensure dark mode is the default and light mode remains readable.
- Ensure UI copy says `Pipeline` and `Git Projects` consistently.

### Suggested Implementation References

- Global theme tokens: `frontend/src/app/globals.css`
- Theme provider/toggle: `frontend/src/components/providers/ThemeProvider.tsx`, `frontend/src/components/organisms/ThemeToggle.tsx`
- Dashboard shell: `frontend/src/components/templates/DashboardShell.tsx`
- Design style guidance in repo docs: `docs/style-guide.md`

### Acceptance Criteria

- Git Projects UI feels consistent with Pipeline's dashboard and admin surfaces.
- No hard-coded light-only table surfaces remain in new Git Projects UI.
- Text does not overflow on mobile or narrow desktop widths.
- Empty, loading, error, success, and destructive states are visually polished.
- Close issue dialog is clear and not alarming beyond the action's real risk.
- Verified in both dark and light modes.
- `npm run lint` and `npx tsc --noEmit` pass.

### Out Of Scope

- New backend behavior.
- New product features.
- Broad redesign outside Git Projects and touched dashboard widgets.