implemented agents, readme, and changelog md files for ai-assisted

development.
2026-05-11 19:22:11 +02:00
parent 6d5122bc11
commit db0f402ab2
4 changed files with 1232 additions and 71 deletions
@@ -0,0 +1,188 @@
 # AGENTS.md — ForgeBucket AI Agent Guide
 This file is for AI coding agents (Claude Code, GitHub Copilot, etc.) working in this repository. Read it before making changes.
 ---
 ## Mission
 ForgeBucket is a **unified operating system for software delivery** — not a Git repository viewer with CI attached. The guiding philosophy:
 > Repositories are runtime systems. The dashboard is a command center. GitOps is first-class.
 Every feature decision should answer: does this reduce cognitive load? Does this improve operational awareness? Does this improve developer flow?
 The full product vision lives in [`ai_agent_master_prompt_for_building_modern_git_platform.md`](ai_agent_master_prompt_for_building_modern_git_platform.md).
 ---
 ## Architecture Map
 ```
 cmd/forgebucket/          — binary entry point (main.go)
 internal/
  api/
    router.go             — Chi router, all route definitions (~26 routes)
    middleware/           — auth, CSRF, RBAC, logging
    handlers/             — one file per domain (repo, pr, issue, auth, user, ssh...)
  domain/
    git/                  — sanitized git binary wrapper (exec.Command only, no shell)
    federation/           — ActivityPub / ForgeFed (DATA LAYER ONLY — no handlers yet)
    ci/                   — CI orchestrator (EMPTY — Phase 2 stub)
  models/                 — XORM structs + 7 migration files
  config/                 — ENV-driven config, fails fast on missing secrets
 web/                      — //go:embed target for the built React SPA
 frontend/
  src/
    pages/                — 20 route-level page components
    components/           — shared UI (AppShell, Sidebar, Header, DiffViewer, etc.)
    ui/
      tokens.ts           — SINGLE SOURCE OF TRUTH for all design tokens
    hooks/                — custom React hooks
    api/                  — typed API client (fetch wrappers)
 ```
 **Middleware chain — this order is fixed, do not reorder:**
 ```
 Logger → RealIP → Recoverer → CORS → CSRF → SessionAuth → RBAC → Handler
 ```
 ---
 ## Current Phase Status
 Understand the phases before adding code — don't build Phase 3 infrastructure when Phase 2 is incomplete.
 | Phase | Scope | Status |
 |-------|-------|--------|
 | 1 | Auth, Git HTTP, repos, PRs, issues, RBAC, webhooks model, LFS, design system, 20-page SPA | **Complete** |
 | 2 | CI/CD orchestrator, runner manager, pipeline DAG visualization, artifact registry | **Active — `internal/domain/ci/` is the stub** |
 | 3 | GitOps controller, environments, drift detection, federation handlers, observability, audit log | Planned |
 | 4 | Command palette, AI diagnostics, signed artifacts, package registry | Planned |
 Do not implement Phase 3+ features without explicit discussion. The `domain/federation/` and `domain/ci/` directories are intentional stubs.
 ---
 ## Go Conventions
 ### Git commands — critical rule
 Always use `exec.Command("git", arg1, arg2, ...)` with **discrete arguments**. Never build a shell string from user input.
 ```go
 // CORRECT
 cmd := exec.Command("git", "clone", "--bare", repoURL, destPath)
 // WRONG — never do this
 cmd := exec.Command("sh", "-c", "git clone "+userInput)
 ```
 This rule is non-negotiable. It prevents command injection.
 ### Router / handlers
 - Chi router. Route definitions in `internal/api/router.go`.
 - One handler file per domain area. Keep handlers thin — business logic belongs in domain packages.
 - All POST/PUT/DELETE routes require `X-CSRF-Token` header matching the session cookie. The middleware enforces this, but don't remove it from routes.
 ### Database
 - XORM for all DB access. Structs in `internal/models/`.
 - Migrations are numbered files in `internal/models/migrations/`. Always add a new migration file; never edit existing ones.
 - No raw SQL strings built from user input.
 ### Secrets and config
 - All secrets come from environment variables via `internal/config/`.
 - Never hardcode secrets, tokens, or credentials anywhere.
 - `SESSION_SECRET` ≥ 32 chars. `CSRF_SECRET` = exactly 32 chars.
 ### Error handling
 - Return errors up the call stack. Don't swallow them silently.
 - HTTP handlers use consistent JSON error responses — follow the pattern in existing handlers.
 ---
 ## TypeScript / React Conventions
 ### Design tokens — critical rule
 All spacing, color, and sizing values must come from `frontend/src/ui/tokens.ts`. Do not introduce new hardcoded pixel values or color hex codes.
 ```tsx
 // CORRECT — use token classes via Tailwind
 <div className="p-sm gap-xs">
 // WRONG — arbitrary values
 <div style={{ padding: "12px" }}>
 ```
 ### Grid system
 - Base unit: 8px. All spacing is multiples of 4px (`xs`) or 8px (`sm`).
 - Touch targets: 44px minimum height/width on all interactive elements (buttons, links, icon buttons).
 ### Dark mode
 - Use Tailwind v4 `@variant dark` — not hardcoded dark: classes unless inside a component that explicitly handles both.
 - Colors must work in both light and dark modes. Test both.
 ### Component patterns
 - `AppShell` wraps all authenticated pages. Don't bypass it.
 - `Sidebar` has three states: expanded (320px), collapsed (56px), mobile bottom bar. Respect all three.
 - Mobile-first: design for 375px, enhance for 1440px. Use the `BottomTabBar` for mobile nav — don't add new nav patterns.
 - Loading states: use `Skeleton` components for perceived performance, not spinners.
 - Mobile code review: use the `MobileComment` bottom-sheet pattern — not modals.
 ### API calls
 - Use the typed API client in `frontend/src/api/` — don't write raw `fetch` calls in components.
 - Always include `X-CSRF-Token` header on mutating requests.
 ---
 ## What NOT to Do
 - **No shell string injection** — see Go conventions above
 - **No hardcoded secrets** — everything via env
 - **No skipping CSRF** — all mutating routes require it
 - **No arbitrary design values** — tokens.ts is the law
 - **No Phase 3+ features without discussion** — don't wire up GitOps, federation handlers, or the command palette until Phase 2 is complete
 - **No new color tokens** — if the design requires a new color, discuss it; don't invent one
 - **No modal-heavy UX** — this platform uses progressive disclosure; avoid deep modal chains
 - **No YAML-centric UI** — pipeline and environment config should feel operational, not config-file editing
 ---
 ## Testing
 ```bash
 make test     # Go tests (go test ./...) + Vitest (frontend unit tests)
 make lint     # go vet + ESLint
 ```
 - Go: test files live alongside source files (`*_test.go`)
 - Frontend: Vitest for unit tests, component tests alongside components
 - All UI changes must be manually verified at 1440px desktop and 375px mobile
 ---
 ## Key Files Reference
 | File | Purpose |
 |------|---------|
 | `internal/api/router.go` | All route definitions — start here for backend |
 | `internal/models/` | XORM models + migrations — all DB schemas |
 | `internal/config/config.go` | Env-driven config, required vars |
 | `internal/domain/git/` | Git binary wrapper — safe exec patterns |
 | `frontend/src/ui/tokens.ts` | Design token source of truth |
 | `frontend/src/components/AppShell.tsx` | Root layout wrapper |
 | `frontend/src/components/Sidebar.tsx` | 3-state navigation sidebar |
 | `frontend/src/pages/` | All 20 route-level pages |
 | `frontend/src/api/` | Typed API client |
 | `.env.example` | All required environment variables |
 | `CLAUDE.md` | Developer guide (rules overlap with this file — CLAUDE.md takes precedence on conflicts) |
 ---
 ## Running Locally
 ```bash
 cp .env.example .env     # fill SESSION_SECRET and CSRF_SECRET
 make docker-up           # PostgreSQL via Docker Compose
 make migrate             # run XORM migrations
 make dev                 # Go :8080 + Vite :5173
 ```
@@ -0,0 +1,102 @@
 # Changelog
 All notable changes to ForgeBucket are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ---
 ## [Unreleased]
 ### Planned — Phase 2 (CI/CD)
 - CI orchestrator with DAG pipeline execution
 - Runner manager (Docker, Kubernetes, Firecracker backends)
 - Pipeline DAG visualization (visual dependency graph with live execution state)
 - Build artifact storage and retention policies
 - Forgejo Actions gRPC integration
 - Flaky test detection
 - Pipeline log viewer (collapsible, filterable, syntax-highlighted)
 - Matrix builds and reusable workflow templates
 - Concurrency controls and pipeline cancellation
 ### Planned — Phase 3 (GitOps + Observability + Federation)
 - GitOps controller with reconciliation loops
 - Environment management and topology visualization
 - Drift detection and sync status
 - Deployment promotion workflows (dev → staging → production)
 - Rollback visualization and one-click rollbacks
 - Canary and blue/green deployment support
 - Unified operational timeline (commits + deployments + incidents + CI failures merged)
 - ActivityPub / ForgeFed federation handlers (inbox, outbox, cross-instance PRs)
 - Audit log (all administrative and git-over-HTTP actions)
 - Secret scanning and dependency vulnerability scanning
 ---
 ## [0.1.0] — 2026-05-11
 Initial development milestone. Core Git hosting, collaboration, and frontend SPA are functional.
 ### Added — Authentication & Security
 - User registration and login with secure session cookies
 - CSRF protection on all mutating routes via `X-CSRF-Token` header
 - Middleware chain: Logger → RealIP → Recoverer → CORS → CSRF → SessionAuth → RBAC → Handler
 - SSH key management per user
 - OIDC / OAuth2 optional integration (configurable via env)
 - Scoped access tokens with optional expiration dates
 - Repository deploy keys (read-only or read-write HTTP tokens)
 - ENV-driven config with fail-fast validation on missing secrets
 ### Added — Git Hosting
 - Smart HTTP transport (git clone, push, pull over HTTP)
 - AGit protocol support (`refs/for/` push for instant PR creation without branch switching)
 - Branch management (list, create, delete, default branch configuration)
 - Commit log and diff viewing
 - Git LFS per-repository (configurable file size limits, locking)
 - Branch protection rules (force-push blocking, required reviews)
 - Repository visibility (public / private)
 ### Added — Collaboration
 - Pull requests (open / merged / closed states) with author tracking
 - Issues (open / closed)
 - Reviewer assignment (default reviewer per repo, per-PR reviewer assignment)
 - Merge strategy selection per repository (merge commit / squash / rebase)
 - Branching model configuration (feature / bugfix / release / hotfix prefixes)
 - PR default description templates (per-repo)
 - Excluded files from diffs (glob pattern configuration)
 - Webhook system with event filtering (push, pull_request, issue)
 - Repository member RBAC (read / write / admin roles)
 ### Added — Frontend SPA
 - React 18 + TypeScript + Vite, embedded into Go binary via `//go:embed`
 - 20 route-level pages: Login, Register, Dashboard, Repos, CreateRepo, ImportRepo, Repo, RepoSettings, Blob, Commits, Branches, RepoIssues, RepoPRs, CreatePR, PRDetail, Starred, PRs (cross-repo), Pipelines (placeholder), Explore, Profile, Settings
 - AppShell layout wrapper for all authenticated pages
 - Triple-state sidebar: expanded (320px) / collapsed (56px) / mobile bottom bar
 - Mobile-first responsive design (375px → 1440px)
 - DiffViewer: side-by-side and unified views with syntax highlighting
 - MobileComment: bottom-sheet overlay for inline code review on mobile
 - TreeBrowser: repository file tree navigation
 - PipelineWaterfall: placeholder pipeline visualization component
 - Skeleton loading states for perceived performance
 ### Added — Design System
 - Custom semantic token palette in `frontend/src/ui/tokens.ts`
 - Full dark/light mode support via Tailwind CSS v4 `@variant dark`
 - Brand colors: `#0052CC` (light) / `#3B82F6` (dark)
 - 8px grid system (xs: 4px, sm: 8px, md: 16px, lg: 24px, xl: 32px, xxl: 48px)
 - 44px minimum touch targets on all interactive elements (WCAG 2.5.5)
 - Consistent border radius scale (subtle 3–8px, full 9999px)
 - System font stack (Segoe UI, Roboto, sans-serif)
 ### Added — Infrastructure
 - PostgreSQL + XORM with 7 migration files covering: users, repositories, issues, SSH keys, access tokens, deploy keys, workflows, and LFS settings
 - ActivityPub actor data model (FederationActor with inbox/outbox URLs and RSA key pairs) — data layer only
 - Docker Compose setup for local PostgreSQL
 - Makefile targets: dev, build, migrate, test, lint, docker-up
 - WebSockets foundation for live logs and notifications
 ---
 [Unreleased]: https://github.com/forgeo/forgebucket/compare/v0.1.0...HEAD
 [0.1.0]: https://github.com/forgeo/forgebucket/releases/tag/v0.1.0
@@ -1,101 +1,231 @@
-# ForgeBucket 🛡️🪣
+# ForgeBucket
-**Sovereign Federation meets Enterprise Design.**
+> A unified operating system for software delivery — not just a Git host.
-ForgeBucket is a production-ready, federated git collaboration platform. It combines the high-performance, lightweight Go engine of **Forgejo** with the sophisticated, high-density UI/UX of **Bitbucket**, optimized for a "Responsive-First, Access Anywhere" experience.
+ForgeBucket is a self-hosted, federated developer operations platform. Where other Git platforms show you a list of files, ForgeBucket surfaces deployments, pipeline health, environment drift, and operational context directly alongside your code. Repositories are runtime systems. The dashboard is a command center.
 **Status:** Early development. Core Git hosting, collaboration, and auth are functional. CI/CD and GitOps integrations are next.
 ---
-## 🚀 The Vision
+## What Makes It Different
-ForgeBucket aims to provide developers with a world-class code review and project management experience without sacrificing data sovereignty. It bridges the gap between community-driven open-source software and enterprise-grade usability.
+| Principle | What it means |
-
+|-----------|---------------|
- **Engine:** Built on the Forgejo/Gitea ecosystem.
+| **Repositories are runtime systems** | Repo pages show deployments, environments, health, and risk — not just a file tree |
- **Interface:** Powered by Atlassian Design System (ADS) principles.
+| **Operational awareness by default** | Failing pipelines, stale PRs, security alerts, and environment drift surface without digging |
- **Connectivity:** Full ActivityPub (ForgeFed) integration for a decentralized git world.
+| **GitOps is first-class** | Git is the source of truth for deployment state, rollbacks, and environment promotion |
 | **Keyboard-first UX** | Global command palette, minimal navigation depth, low cognitive load |
 | **Federated by design** | ActivityPub (ForgeFed) for cross-instance pull requests and collaboration |
 | **Sovereign** | Fully self-hostable — your code, your infrastructure, your keys |
 ---
-## 🛠️ Tech Stack
+## Feature Status
-### Backend & Core
+### Core Platform
 | Feature | Status |
 |---------|--------|
 | User auth (registration, login, sessions) | Done |
 | CSRF + session security | Done |
 | SSH key management | Done |
 | OIDC / OAuth2 (optional) | Done |
 | Access tokens (scoped, expiring) | Done |
 | Deploy keys | Done |
- **Language:** Go (Golang) 1.21+
+### Git Hosting
- **Database:** PostgreSQL with XORM
+| Feature | Status |
- **Git Engine:** Native System Git Binary execution
+|---------|--------|
- **CI/CD:** Forgejo Actions (gRPC protocol)
+| Smart HTTP transport (clone/push/pull) | Done |
 | AGit protocol (`refs/for/` PR creation) | Done |
 | Branch management | Done |
 | Commit + diff viewing | Done |
 | Git LFS (per-repo, configurable size limits) | Done |
 | Branch protection rules | Done |
-### Frontend & UX
+### Collaboration
 | Feature | Status |
 |---------|--------|
 | Pull requests (open/merged/closed) | Done |
 | Issues | Done |
 | Code review (inline comments, mobile bottom-sheet) | Done |
 | Side-by-side + unified diff viewer | Done |
 | Reviewer assignment | Done |
 | Merge strategies (merge/squash/rebase) | Done |
 | Webhooks | Done (model + routes) |
 | Repository RBAC (read/write/admin) | Done |
- **Framework:** React 18+ (Embedded in Go binary)
+### CI/CD
- **Styling:** Tailwind CSS + Atlassian Design Tokens
+| Feature | Status |
- **Components:** Custom implementation of Atlaskit primitives
+|---------|--------|
- **Real-time:** WebSockets for live logs and notifications
+| Pipeline DAG visualization | In progress |
 | CI orchestrator | Planned (Phase 2) |
 | Runner manager | Planned (Phase 2) |
 | Artifact registry | Planned (Phase 2) |
 | Forgejo Actions integration (gRPC) | Planned (Phase 2) |
 | Flaky test detection | Planned (Phase 2) |
 ### GitOps + Environments
 | Feature | Status |
 |---------|--------|
 | GitOps controller | Planned (Phase 3) |
 | Environment management | Planned (Phase 3) |
 | Drift detection | Planned (Phase 3) |
 | Deployment promotion workflows | Planned (Phase 3) |
 | Rollback visualization | Planned (Phase 3) |
 | Canary / blue-green support | Planned (Phase 3) |
 ### Observability + Security
 | Feature | Status |
 |---------|--------|
 | Unified operational timeline | Planned (Phase 3) |
 | Secret scanning | Planned (Phase 3) |
 | Dependency scanning | Planned (Phase 3) |
 | Signed artifacts (Sigstore/Cosign) | Planned (Phase 4) |
 | Audit log | Planned (Phase 3) |
 ### Federation
 | Feature | Status |
 |---------|--------|
 | ActivityPub actor model | Done (data layer) |
 | Federation handlers / inbox / outbox | Planned (Phase 3) |
 | Cross-instance pull requests | Planned (Phase 3) |
 ---
-## ✨ Key Features
+## Quick Start
 - **Responsive Navigation:** A triple-state sidebar (Expanded, Collapsed, Mobile Bottom-Bar) that adheres to an 8px grid system.
 - **Advanced Diff Viewer:** Side-by-side and unified views with "Bottom Sheet" comment overlays for mobile code reviews.
 - **Federated Pull Requests:** Interaction across different ForgeBucket/Forgejo instances via ActivityPub.
 - **AGit "Quick Edit":** Web-based file editing with automatic `refs/for/` branch creation for instant PRs.
 - **Skeleton Loading:** Optimized "Perceived Performance" using pulsate loading states for metadata.
 ---
 ## 🔒 Security & Compliance
 - **OWASP Top 10 Compliance:** Strict protection against XSS, CSRF, and SQLi.
 - **Command Sanitization:** Hardened wrapper for all Git binary executions.
 - **Identity:** OIDC and OAuth2 support with Row-Level Security (RLS) mentalities.
 - **Auditability:** Full logging of all administrative and git-over-HTTP actions.
 ---
 ## 🏁 Getting Started
 ### Prerequisites
 - Go 1.21 or higher
 - Node.js 18+ (for frontend development)
 - PostgreSQL 14+
 - System Git 2.20+
 ### Installation
 1. **Clone the repository:**
 ```bash
-   git clone [https://github.com/your-repo/forgebucket.git](https://github.com/your-repo/forgebucket.git)
+# 1. Clone and configure
-   cd forgebucket
+git clone https://github.com/forgeo/forgebucket.git
 cd forgebucket
 cp .env.example .env          # fill in SESSION_SECRET and CSRF_SECRET
 # 2. Start PostgreSQL
 make docker-up
 # 3. Run DB migrations
 make migrate
 # 4. Start both servers (Go :8080 + Vite :5173)
 make dev
 ```
-2. **Setup Frontend:**
+The Go API runs at `http://localhost:8080`. The Vite dev server runs at `http://localhost:5173` and proxies API requests.
-```Bash
+---
-cd frontend
+
-npm install
+## Architecture
-npm run build
+
 ```
 ForgeBucket
 ├── API Gateway          (Chi router, internal/api/)
 ├── Auth Service         (sessions, CSRF, OIDC — internal/api/handlers/)
 ├── Repository Service   (git HTTP, branches, LFS — internal/domain/git/)
 ├── Pull Request Service (PRs, reviews, merge — internal/api/handlers/)
 ├── Issue Service        (issues, labels — internal/api/handlers/)
 ├── Federation Layer     (ActivityPub actors — internal/domain/federation/)  ← stub
 ├── CI Orchestrator      (pipeline scheduling — internal/domain/ci/)         ← stub
 ├── Secret Manager       (env-based, scoped tokens — internal/config/)
 ├── Database             (PostgreSQL + XORM — internal/models/)
 └── Web Frontend         (React 18 + TypeScript, embedded via //go:embed — web/)
 ```
-3. **Build the Binary:**
+**Middleware chain (every request):**
-
+```
-```Bash
+Logger → RealIP → Recoverer → CORS → CSRF → SessionAuth → RBAC → Handler
 cd ..
 go build -o forgebucket main.go
 ```
-4. **Run:**
+---
-```Bash
+## Tech Stack
 ./forgebucket web
 ```
-## 🤝 Contributing
+| Layer | Technology |
 |-------|------------|
 | Language | Go 1.21+ |
 | Router | Chi |
 | ORM / Migrations | XORM + PostgreSQL |
 | Frontend framework | React 18 + TypeScript |
 | Build tool | Vite |
 | Styling | Tailwind CSS v4 |
 | Code editing | CodeMirror |
 | Real-time | WebSockets |
 | Container | Docker Compose (dev) |
 | Federation | ActivityPub / ForgeFed |
-We follow the "Responsive-First" contribution model. Please ensure all UI changes are tested on both Desktop (1440px) and Mobile (375px) breakpoints.
+---
-## 📄 License
+## Design System
-This project is licensed under the MIT License - see the LICENSE file for details. Portions of the code are derived from Forgejo (GPLv3).
+ForgeBucket has its own design language — intentionally distinct from GitHub and GitLab.
 **Philosophy:** information-dense but calm. Inspired by Linear, Datadog, and VS Code — not enterprise CRUD forms.
 - **Colors:** Semantic token palette with full dark/light mode. Brand blue `#0052CC` (light) / `#3B82F6` (dark). Source of truth: `frontend/src/ui/tokens.ts`
 - **Grid:** 8px base unit. All spacing is multiples of 4px (xs) or 8px (sm). No arbitrary pixel values.
 - **Touch targets:** 44px minimum on all interactive elements (WCAG 2.5.5)
 - **Navigation:** Triple-state sidebar (expanded 320px / collapsed 56px / mobile bottom bar). Keyboard-first.
 - **Breakpoints:** Desktop 1440px, mobile 375px. Mobile code review uses bottom-sheet overlays, not modals.
 - **Typography:** System font stack (Segoe UI, Roboto, sans-serif)
 ---
 ## Environment Variables
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `DATABASE_URL` | Yes | PostgreSQL connection string |
 | `SESSION_SECRET` | Yes | Session signing key, ≥ 32 chars (`openssl rand -hex 32`) |
 | `CSRF_SECRET` | Yes | CSRF key, exactly 32 chars (`openssl rand -hex 16`) |
 | `PORT` | No | HTTP port, default `8080` |
 | `REPO_ROOT` | Yes | Absolute path for bare git repository storage |
 | `INSTANCE_URL` | Yes | Public URL of this instance (no trailing slash) |
 | `INSTANCE_NAME` | No | Display name, default `ForgeBucket` |
 | `OIDC_ISSUER` | No | OIDC provider URL |
 | `OIDC_CLIENT_ID` | No | OIDC client ID |
 | `OIDC_CLIENT_SECRET` | No | OIDC client secret |
 | `DEBUG` | No | Disables Secure cookies, enables verbose logging |
 ---
 ## Common Commands
 | Command | What it does |
 |---------|-------------|
 | `make dev` | Start Go API + Vite dev server concurrently |
 | `make build` | Build frontend, embed into Go binary |
 | `make migrate` | Sync XORM schemas to PostgreSQL |
 | `make test` | Run Go tests + Vitest |
 | `make lint` | `go vet` + ESLint |
 | `make docker-up` | Start PostgreSQL via Docker Compose |
 ---
 ## Roadmap
 | Phase | Focus | Status |
 |-------|-------|--------|
 | Phase 1 | Core Git hosting, auth, PRs, issues, RBAC, design system | Done |
 | Phase 2 | CI/CD orchestrator, runner manager, pipeline visualization, artifact registry | In progress |
 | Phase 3 | GitOps controller, environments, observability, federation handlers, audit log | Planned |
 | Phase 4 | Command palette, AI diagnostics, signed artifacts, package registry | Planned |
 ---
 ## Contributing
 See [AGENTS.md](AGENTS.md) for AI-assisted development conventions, architecture boundaries, and what not to build without discussion.
 All UI contributions must be tested at both 1440px desktop and 375px mobile. Spacing must use tokens from `frontend/src/ui/tokens.ts` — no arbitrary pixel values.
 ---
 ## Module Path
 `github.com/forgeo/forgebucket`
 ---
 ## License
 MIT License. See LICENSE for details.
@@ -0,0 +1,741 @@
 # MASTER IMPLEMENTATION PROMPT
 ## Building a Modern Git Platform with CI/CD + GitOps + Operational UX
 You are an elite senior staff engineer, platform architect, DevOps architect, distributed systems engineer, and product UX engineer.
 You are tasked with designing and implementing a next-generation self-hosted Git platform.
 This platform exists in the category of:
 - GitHub
 - GitLab
 - Forgejo
 - Gitea
 - Bitbucket
 BUT:
 You must NOT merely clone existing platforms.
 The goal is to create:
 > a modern developer operations platform
 that deeply integrates:
 - Git hosting
 - pull requests
 - CI/CD
 - GitOps
 - deployments
 - environments
 - observability
 - security
 - operational awareness
 - developer productivity
 The platform should feel:
 - fast
 - operational
 - developer-first
 - low cognitive load
 - modern
 - reliable
 - modular
 - keyboard-first
 - context-aware
 The product philosophy is:
 > repositories are operational systems
 NOT:
 > collections of files.
 ==================================================
 HIGH LEVEL PRODUCT GOALS
 ==================================================
 The platform should optimize for:
 - immediate situational awareness
 - workflow continuity
 - deployment visibility
 - operational clarity
 - reliability
 - developer flow
 - observability
 - intelligent automation
 - security by default
 - excellent UX
 Users should always be able to answer:
 - what changed?
 - what failed?
 - what deployed?
 - what is unhealthy?
 - what needs my attention?
 - what environments are affected?
 - what should I review next?
 - what caused this incident?
 without navigating deeply.
 ==================================================
 CORE PRODUCT PRINCIPLES
 ==================================================
 1. UX FIRST
 Most Git platforms prioritize functionality over usability.
 This platform must prioritize:
 - readability
 - discoverability
 - contextual awareness
 - progressive disclosure
 - speed
 - low noise
 - operational understanding
 Avoid:
 - tab overload
 - enterprise clutter
 - giant forms
 - notification spam
 - YAML-centric UX
 - log-centric UX
 The system should feel:
 - intentional
 - calm
 - efficient
 - operationally intelligent
 --------------------------------------------------
 2. OPERATIONAL AWARENESS
 The platform must continuously surface:
 - failing pipelines
 - deployment health
 - environment drift
 - flaky tests
 - security issues
 - review bottlenecks
 - dependency risks
 - deployment risks
 This information should appear naturally throughout the UI.
 --------------------------------------------------
 3. REPOSITORIES ARE RUNTIME SYSTEMS
 The repository page should not simply display files.
 It should display:
 - deployments
 - environments
 - active PRs
 - operational health
 - timelines
 - incidents
 - ownership
 - risk
 - observability
 The file tree is secondary.
 --------------------------------------------------
 4. GITOPS IS FIRST CLASS
 Git should become:
 - source of truth
 - deployment history
 - environment state definition
 - rollback system
 - audit log
 The system must support:
 - reconciliation
 - drift detection
 - declarative environments
 - promotion workflows
 - rollback visualization
 - environment topology
 --------------------------------------------------
 5. RELIABILITY IS A PRIMARY FEATURE
 The platform should optimize for:
 - deterministic execution
 - idempotency
 - isolation
 - resilience
 - queue durability
 - observability
 - safe rollbacks
 - fault tolerance
 ==================================================
 ARCHITECTURE REQUIREMENTS
 ==================================================
 Design the platform using modular services.
 Suggested architecture:
 ```txt
 Platform
 ├── API Gateway
 ├── Auth Service
 ├── Repository Service
 ├── Pull Request Service
 ├── Issue Service
 ├── Event Bus
 ├── CI Orchestrator
 ├── Runner Manager
 ├── Artifact Registry
 ├── Package Registry
 ├── Deployment Engine
 ├── GitOps Controller
 ├── Environment Service
 ├── Secret Manager
 ├── Notification Service
 ├── Search Service
 ├── Observability Layer
 ├── Metrics Service
 ├── Audit Service
 └── Web Frontend
 ```
 ==================================================
 EVENT DRIVEN ARCHITECTURE
 ==================================================
 The platform should be event-driven.
 Everything emits events.
 Examples:
 ```txt
 repo.created
 push.created
 pr.opened
 review.requested
 pipeline.started
 pipeline.failed
 artifact.published
 deployment.started
 deployment.failed
 environment.drift_detected
 incident.created
 ```
 Requirements:
 - durable events
 - replay support
 - auditability
 - timeline reconstruction
 - reactive UI updates
 Recommended technologies:
 - NATS
 - Kafka
 - RabbitMQ
 Prefer NATS initially for simplicity.
 ==================================================
 CI/CD SYSTEM REQUIREMENTS
 ==================================================
 The CI/CD system must support:
 - DAG pipelines
 - matrix builds
 - reusable workflows
 - workflow templates
 - conditional execution
 - parallel execution
 - artifacts
 - caches
 - retries
 - concurrency controls
 - cancellation
 - pipeline graphs
 - environment promotion
 - rollback support
 - preview environments
 - flaky test detection
 - deployment visualization
 The orchestrator should:
 - schedule
 - coordinate
 - monitor
 NOT directly execute jobs.
 ==================================================
 RUNNER SYSTEM REQUIREMENTS
 ==================================================
 Runners should:
 - be ephemeral
 - isolated
 - disposable
 - reproducible
 - stateless
 Support execution backends:
 1. Docker containers
 2. Kubernetes jobs
 3. Firecracker microVMs
 4. Bare metal runners
 Security is critical.
 Forked PRs must never automatically receive secrets.
 ==================================================
 SECRET MANAGEMENT
 ==================================================
 Implement scoped secret management.
 Secret hierarchy:
 ```txt
 Global
 → Organization
 → Repository
 → Environment
 → Runtime ephemeral injection
 ```
 Support:
 - Vault
 - OIDC federation
 - cloud secret providers
 - encrypted secret storage
 Secrets must:
 - never leak to logs
 - be masked automatically
 - support audit trails
 - support rotation
 ==================================================
 ARTIFACT + PACKAGE MANAGEMENT
 ==================================================
 Implement:
 - build artifact storage
 - OCI registry
 - package registries
 - retention policies
 - artifact provenance
 - signing support
 - SBOM support
 Support:
 - container images
 - npm
 - cargo
 - pip
 - maven
 - generic artifacts
 ==================================================
 GITOPS REQUIREMENTS
 ==================================================
 GitOps must be deeply integrated.
 Support:
 - reconciliation loops
 - drift detection
 - sync visualization
 - environment topology
 - deployment promotion
 - rollback flows
 - canary releases
 - blue/green deployments
 - environment history
 The UI should make GitOps understandable.
 Avoid overwhelming Kubernetes-centric UX.
 ==================================================
 DATABASE + STORAGE DESIGN
 ==================================================
 Separate:
 - application code
 - repository storage
 - artifacts
 - caches
 - logs
 - uploads
 Repository storage should NOT exist in the app repository.
 Recommended:
 ```txt
 /data/repos
 /data/artifacts
 /data/cache
 /data/uploads
 ```
 Repository storage is runtime instance data.
 Treat it like:
 - database files
 - object storage
 - runtime state
 ==================================================
 DASHBOARD REQUIREMENTS
 ==================================================
 The dashboard should behave like:
 > an operational command center
 NOT:
 > a repository list.
 Include:
 1. Attention Required
 - failing pipelines
 - stale PRs
 - security alerts
 - deployment failures
 - environment drift
 2. Active Workspaces
 - active repos
 - active branches
 - assigned reviews
 - recent deployments
 3. Team Activity
 - merges
 - releases
 - deployments
 - incidents
 4. CI/CD Overview
 - pipeline health
 - queue health
 - flaky tests
 - deployment status
 5. Review Dashboard
 - pending reviews
 - high risk PRs
 - stale reviews
 6. Security Overview
 - dependency vulnerabilities
 - secret leaks
 - suspicious pushes
 ==================================================
 REPOSITORY PAGE REQUIREMENTS
 ==================================================
 The repository page must feel operational.
 Top area should include:
 ```txt
 Repo Name
 Production: Healthy
 CI: Passing
 Deployments: 3 active
 Risk: Medium
 ```
 The page should include:
 - active PRs
 - deployments
 - environments
 - repository health
 - security alerts
 - ownership
 - recent activity
 - operational timeline
 - preview environments
 - CI/CD overview
 - deployment history
 The README should not dominate the page.
 ==================================================
 UNIFIED OPERATIONAL TIMELINE
 ==================================================
 Implement a unified timeline merging:
 - commits
 - deployments
 - incidents
 - rollbacks
 - CI failures
 - security events
 - alerts
 - releases
 This is one of the most important features.
 Users should easily answer:
 > what changed before things broke?
 ==================================================
 PIPELINE UX REQUIREMENTS
 ==================================================
 Pipelines should be visual DAGs.
 Support:
 - dependency visualization
 - execution timing
 - bottleneck detection
 - retry controls
 - artifact visibility
 - live execution state
 - grouped logs
 - semantic errors
 Logs should support:
 - filtering
 - collapsing
 - syntax highlighting
 - structured parsing
 - AI summarization
 ==================================================
 DEPLOYMENT UX REQUIREMENTS
 ==================================================
 Deployments must feel first-class.
 Each environment should expose:
 ```txt
 Production
 Healthy
 v1.4.2
 3 pods
 0.1% errors
 Last deploy 14m ago
 ```
 Support:
 - rollback
 - traffic shifting
 - canary visibility
 - deployment timelines
 - release notes
 - environment logs
 - health checks
 ==================================================
 COMMAND PALETTE REQUIREMENTS
 ==================================================
 Implement a global command palette.
 Inspired by:
 - VS Code
 - Raycast
 - Linear
 Examples:
 ```txt
 /retry failed jobs
 /deploy staging
 /open logs
 /review next
 /show flaky tests
 /open production incidents
 ```
 Keyboard-first navigation is critical.
 ==================================================
 AI-ASSISTED FEATURES
 ==================================================
 Implement optional AI-assisted operational tooling.
 Examples:
 - failure diagnosis
 - flaky test detection
 - architecture summaries
 - impact analysis
 - deployment risk scoring
 - review summaries
 - onboarding explanations
 Example:
 ```txt
 Likely failure cause:
 Database migration introduced lock contention.
 ```
 ==================================================
 OBSERVABILITY REQUIREMENTS
 ==================================================
 Integrate:
 - metrics
 - traces
 - logs
 - deployment state
 - incident state
 - service topology
 Do not isolate observability into external systems.
 Expose operational health directly in repository pages.
 ==================================================
 RELIABILITY REQUIREMENTS
 ==================================================
 Implement:
 - durable queues
 - retries
 - dead-letter queues
 - resumable pipelines
 - distributed scheduling
 - concurrency controls
 - checkpointing
 - idempotent operations
 The platform should survive:
 - runner crashes
 - orchestrator crashes
 - network partitions
 - deployment interruptions
 ==================================================
 SECURITY REQUIREMENTS
 ==================================================
 Implement:
 - signed artifacts
 - provenance verification
 - branch protections
 - permission scopes
 - audit logging
 - secret scanning
 - dependency scanning
 - runner isolation
 - sandboxing
 Support:
 - Sigstore
 - Cosign
 - SLSA concepts
 ==================================================
 UI/UX DESIGN LANGUAGE
 ==================================================
 The UI should feel:
 - modern
 - minimal
 - operational
 - clean
 - responsive
 - keyboard-first
 - information dense but calm
 Visual inspirations:
 - Linear
 - Datadog
 - Grafana
 - Raycast
 - Arc Browser
 - VS Code
 - modern observability dashboards
 Avoid:
 - clutter
 - giant tables
 - excessive modal workflows
 - deeply nested navigation
 ==================================================
 IMPLEMENTATION EXPECTATIONS
 ==================================================
 You should:
 - think deeply about architecture
 - optimize for maintainability
 - optimize for extensibility
 - prioritize UX heavily
 - prioritize reliability heavily
 - explain tradeoffs
 - avoid overengineering early
 - support future scalability
 You should continuously ask:
 - does this reduce cognitive load?
 - does this improve operational awareness?
 - does this improve developer flow?
 - does this improve reliability?
 - does this make debugging easier?
 ==================================================
 DELIVERABLES
 ==================================================
 When implementing features:
 Provide:
 - architecture reasoning
 - schema design
 - API design
 - event definitions
 - service boundaries
 - UI mockups
 - workflow diagrams
 - UX rationale
 - security implications
 - scaling considerations
 - operational implications
 Always optimize for:
 - clarity
 - reliability
 - developer experience
 - operational intelligence
 - future extensibility
 The platform should ultimately feel like:
 > a unified operating system for software delivery
 rather than:
 > a Git repository viewer with CI attached.