Soft Serve fork guide

This fork adds an optional public web UI. Keep changes focused on that UI and its direct dependencies. Do not modify unrelated upstream Soft Serve code unless the task requires it.

Layout

• pkg/web/server.go creates the HTTP router.
• pkg/web/goget.go owns only GET /{repo}?go-get=1.
• pkg/web/git.go and pkg/web/git_lfs.go own Git and LFS transport.
• pkg/web/pages/ is the UI package. It must not import pkg/web.
  • controller.go: UI route registration, homepage data, embedded assets.
  • access.go: public anonymous repository access checks.
  • repository.go, content.go, raw.go, urls.go: safe Git input, content, raw-file, and URL helpers.
  • browser.go: overview, tree, file, and raw handlers.
  • history.go: commits, commit detail, and refs handlers.
  • render.go: security headers and safe Markdown/source rendering.
  • status.go: server-side client for current worker build statuses.
  • templates/: Go HTML templates and inline SVG icons.
  • assets/site.css and assets/site.js: embedded UI assets.
• pkg/config/config.go and pkg/config/file.go define and render http.web_ui settings.
• pkg/ui/common/RepoURL defines clone URL behavior.
• git/ contains the Git abstraction. Add UI-specific limits there only when they cannot live in pkg/web/pages.

Router and access rules

Router order is mandatory: health, Go import metadata, Git/LFS, enabled UI routes, then 404. Do not add a catch-all page route before Git or Go-import routes.

All page handlers must use backend.FromContext and proto.Repository. A repository page is readable only when it exists, is public, and anonymous access is at least read-only. Return 404 for inaccessible repositories. Hidden repositories are excluded from the homepage but may be browsed directly when public.

Use existing helpers for refs, hashes, POSIX tree paths, bounded blobs, raw metadata, and URLs. Never pass a request value as a Git revision expression. Do not read bare repository paths or query the database directly from pages.

UI rules

• Keep the UI embedded, semantic, keyboard-accessible, and mostly server-rendered.
• The only client script is site.js, for explicit copy-to-clipboard actions. It is same-origin and CSP allows only script-src 'self'.
• Use the existing inline SVG icon templates. Do not add external icon fonts, a frontend package manager, or remote page assets.
• Use the dark Gruvbox theme in site.css.
• Repository cards are complete links; do not add separate “Open project” buttons.
• Keep actions in existing navigation or file-header groups. Do not add decorative duplicate headings or orange eyebrow labels.
• Render Markdown files in the tree browser through RenderRepositoryMarkdown, like repository READMEs.
• Show only HTTP clone copying. Do not restore SSH clone UI.
• Raw download copy links must be absolute when http.public_url is configured. Use AbsoluteRawURL; do not concatenate untrusted paths.
• Hide build UI when the worker has no current status or cannot be reached. Render Build: only for queued, running, passed, or failed states.

Build status integration

http.web_ui.build_status_url configures a private worker endpoint. The page server sends POST /build-statuses; browsers must never call the worker. The worker status is in-memory and may be absent after restart. The actual local worker repository is ../soft-builder; Compose deployment files are managed elsewhere.

Validation

Prefer golangci-lint run for validation. Focused UI checks are go test ./pkg/web/pages ./pkg/web.