# AGENTS.md

Instructions for AI agents and new contributors working in this repository.
Read this before changing code. The README describes what the program does
for its users; this file describes why it is built the way it is and which
properties must survive your change.

## What this is

`gsg` is a self-hosted web frontend for bare git repositories. It serves
pages dynamically, reads its per-repository configuration out of each repo's
own git config, and is designed so that adding a page, a data source, or a
JSON endpoint is a local change rather than a change to the core.

The target deployment is one binary next to a gitolite-managed repository
root, behind a reverse proxy, on a personal server.

### Goals, in priority order

1. **Extensibility without core churn.** Adding a feature should mean adding
   one file and calling it from one template. If a change requires editing
   `internal/core`, that is a signal the design is wrong, not that the core
   needs another special case.
2. **Coherent theming.** Every page shares one layout, one stylesheet, one
   set of partials. Views do not carry their own styling.
3. **Correctness over speed of delivery.** This serves attacker-influenced
   input to a public network. A plausible-looking fix that is not understood
   is worse than an open bug.
4. **Small dependency surface.** Currently: the Go standard library,
   `github.com/yuin/goldmark` (which has no dependencies of its own), and the
   `git` binary. Do not add a dependency without a clear reason that cannot be
   met by the stdlib.

### Non-goals

- **Not a forge.** No accounts, no issues, no pull requests, no write paths.
  Every route is `GET` and nothing mutates a repository.
- **Not a static site generator.** An earlier version generated files ahead
  of time. That was removed because it made diffs and arbitrary-branch
  browsing impractical. Do not reintroduce build-time page enumeration.
- **Not a general git host.** Cloning is served by something else
  (git-daemon, ssh, gitolite). This is read-only presentation.

## Architecture

The layering is strict. Violating it is the most common way to make this
codebase worse.

```
main.go              flags, repo discovery, embedded assets
internal/gitx/       the ONLY package that knows git exists
internal/core/       Ctx, module registry, routes, server, cache, funcmap
internal/access/     repo visibility + share-grant policy (imports no core)
internal/authn/      login/logout endpoints
internal/httpx/      shared admin/share HTTP security helpers
internal/modules/    the extension point: one module per concern
internal/notices/    operator notices: YAML store + admin UI (imports no core)
internal/api/        JSON DTOs -- the serialization allowlist
internal/site/       the route table and route-specific request parsers
templates/           layouts/ + views/
static/              one stylesheet
```

**`internal/gitx`** wraps the `git` binary. Nothing above it may invoke git,
parse git output, or know what a packfile is. Everything it returns is a
plain Go value. This boundary exists so the implementation can be swapped for
go-git or git2go by rewriting one package.

**`internal/core`** knows about HTTP, templates, caching and the module
registry. It must not know git semantics. If you find yourself importing
`gitx` into `core` for anything beyond the `Handle`/`Repo` plumbing that is
already there, stop and reconsider.

**`internal/access`** owns the rule for whether an identity may view or
share a repo. It deliberately imports nothing from `core`, so the 404 gate,
the index module, share minting and share redemption all call the same
policy. Do not grow a second visibility check elsewhere.

**`internal/modules`** is where features go. A module is:

```go
type Module func(c *Ctx, args ...string) (any, error)
```

It registers itself in `init()` and is reached from templates through a
single funcmap entry, `mod`. Three properties follow and must be preserved:

- **Lazy.** A template calling `mod "authors"` is what *causes* authors to be
  computed. A view that does not ask does not pay. This is why removing a
  block from a template is a complete removal of its cost.
- **Memoized twice.** Per request in `Ctx.cache`, and process-wide in the
  SHA-keyed `core.LRU`.
- **Declared by use.** There is no module manifest to keep in sync with the
  templates. Do not add one.

**`internal/site/routes.go`** is the file you edit most. A route is a
`net/http` pattern plus a renderer.

## Invariants

These are not style preferences. Each one is either load-bearing for security
or was a real bug that got fixed. Do not break them; if a change seems to
require breaking one, say so explicitly rather than working around it.

### 1. User ref input never reaches `git rev-parse`

`rev-parse` accepts an expression language: `:/regex` searches history,
`@{...}` reads the reflog, and git subcommands treat a leading `-` as an
option. `gitx.Resolve` accepts only a hex SHA that already exists, or an
exact match against the repository's own ref list. Everything else is
rejected with a 404.

Any new route that takes a ref-like path segment must resolve it through
`Resolve` in `Server.buildCtx`, never pass it onward as a raw string.

Regression cases that must keep returning 404 with no side effect:
`--upload-pack=touch /tmp/pwned`, `:/secret`, `HEAD@{0}`, `-n`.

### 2. Modules read `c.Commit`, not `c.Ref`

`c.Ref` is the ref as the user spelled it. `c.Commit` is that ref resolved to
a SHA once, at the top of the request. A ref can move between resolution and
render; a module reading `c.Ref` would then produce content that does not
match the ETag the server already computed. Use `c.Commit` and fall back to
`c.Ref` only when `c.Commit` is empty (an empty repository).

### 3. Anything that changes a module's output belongs in the cache key

`Ctx.CacheKey` covers repo, commit, path, module name, args, **and
`Ctx.Vars`**. Vars were missing originally and caused a real bug:
`/compare/a..b` and `/compare/a...b` resolve to the same *head* commit, so the
second request was served the first one's diff. If you add a new input to a
module, add it to the key.

The cache needs no invalidation logic because it is keyed on immutable SHAs.
Do not add TTLs or manual eviction on the assumption that entries go stale —
if an entry can go stale, the key is wrong.

`Ctx.contentIdentity()` also folds in inputs that change *without* the commit
moving: `RepoInfo.GPGKeyring` and `Site.Revision()`. Site revision is the
site-level analogue of the keyring; operator notices use it so a banner edit
invalidates both the module cache and every ETag. Anything else with that
shape belongs there too.

`Ctx.Immutable` marks responses served with the year-long immutable cache
(see `Server.serve`). Commit-independent chrome must not be rendered into
them, because the browser is told never to revalidate; the notices partial
skips those pages for exactly this reason.

### 4. JSON endpoints use DTOs, never module values

`internal/api` defines explicit structs with json tags. Go marshals every
exported field by default, so serializing a module's return type means the
day someone adds a field to `gitx.Commit`, it is public. The allowlist lives
in one readable file on purpose.

Specific product decision: **commit messages are not exposed over the JSON
API.** `api.Commit` has no `Subject` and no `Body`. Do not add them.

### 5. `/raw/` never serves `text/html`

A repository can contain an `.html` file with a `<script>` tag. Serving it as
`text/html` on this origin turns any push into stored XSS against the whole
site — which is why GitHub puts raw content on a separate hostname. Raw
responses are `text/plain` (or `application/octet-stream` plus
`Content-Disposition: attachment` for binaries) with
`X-Content-Type-Options: nosniff` and
`Content-Security-Policy: default-src 'none'; sandbox`.

The one deliberate exception is a validated raster image (PNG, JPEG, GIF,
WebP, BMP, ICO, AVIF): `modules/image.go` requires the extension and the
magic bytes to agree before `/raw/` may declare `image/*`, so an `.png`
holding HTML is not relabelled. SVG is never in that list — it is an XML
document that can carry a script, so it stays `text/plain`. A raster image
is safe to serve inline because it cannot execute and `nosniff` stops the
declared type from being re-sniffed; the blob page needs those bytes on the
same origin for its `<img>` preview, and the same URL is the download link.
If raw content is ever moved to its own hostname, keep these headers anyway.

### 6. goldmark runs without `WithUnsafe`

Anyone who can push can write a README, so raw HTML in markdown is untrusted
input. goldmark drops it. This also matches Hugo's default, which matters
because the extension set is deliberately aligned with Hugo's (GFM,
Typographer, auto heading IDs) so a README renders identically to the same
file on the author's blog. Keep them aligned.

### 7. `exec` argv cannot contain NUL

Separator bytes in git format strings must be written as git's own hex
escapes — `%00` for `for-each-ref`, `%x00`/`%x1e` for `git log` — so that git
emits the byte. Passing a literal `\x00` in an argument fails with
`fork/exec: invalid argument`. See the constant block at the top of
`gitx/git.go`; use `sepF`/`sepR` when splitting output and `escF`/`escLogF`/
`escLogR` when building a format.

### 8. Every git invocation is bounded

`Repo.WithContext` binds a request deadline and an output cap. Serving means
every git call is attacker-influenced work: without a deadline one `git log`
on a large repository pins a core, and without a cap one diff of a huge blob
eats the heap. The environment is scrubbed (`GIT_CONFIG_NOSYSTEM=1`, no
`HOME`, no terminal prompt) so repository or user config cannot alter
behaviour. New `gitx` methods must go through `Repo.run`.

### 9. Graph geometry is coupled to CSS

`modules/graph.go` has `rowH = 30`, and `static/style.css` has
`table.graph td { height: 30px }`. They must match or the rails detach from
their rows. This is the one fragile seam in the design; if you change either,
change both.

Colour is *not* coupled: the module emits `var(--lane-N)` and the stylesheet
owns the palette. Keep it that way — do not hardcode a colour in Go.

### 10. Empty repositories are a normal state

A freshly created bare repo has an unborn HEAD. `Repo.Empty()` is checked at
`Open`, and `Log`/`Tree` return nothing rather than failing. Templates must
not index into a possibly-empty slice — use `{{ with mod "log" "1" }}{{ with
index . 0 }}`, not `{{ index (mod "log" "1") 0 }}`, or the render aborts.

## How to make common changes

### Add a module

One new file in `internal/modules`. Nothing else moves.

```go
func init() { core.Register("authors", authorsMod) }

func authorsMod(c *core.Ctx, args ...string) (any, error) { ... }
```

Then call it from any template: `{{ with mod "authors" }}…{{ end }}`. Use
`modOr` when absence is normal rather than an error (a missing README, for
example) so the section simply disappears.

`internal/modules/example_authors.go` exists as a live demonstration of
exactly this. Do not delete it.

### Add a page

A module for the data, a view in `templates/views/`, one entry in
`internal/site/routes.go`. Views define `main` and are parsed into separate
template trees, because `html/template` has a single namespace for defined
blocks and two views both defining `main` would collide. That is why
`LoadTemplates` parses each view with the layouts rather than globbing
everything together. If the route needs a new path grammar, declare a
`Route.Request` parser in `internal/site`; core still resolves every ref it
returns. Pagination is declared with `Route.PageSize`.

### Add a JSON endpoint

A DTO in `internal/api`, an `Endpoint` function that calls modules and fills
it, one route with `core.JSON{Build: …}`. Pages and endpoints are the same
mechanism deliberately — both take a `*Ctx`, both call the same memoized
modules.

### Add a per-repository config key

A field on `core.RepoInfo` and a line in `LoadRepoInfo`. Follow the existing
fallback pattern: the `gsg.*` key first, then the cgit/gitweb equivalent, so
an existing cgit tree keeps working unmodified.

A config key that nothing reads is a bug. `gsg.section` sat unused for a
while; if you add a key, wire it into a template or an endpoint in the same
change.

### Add an operator notice source

Notices (global and per-repo banners) live in `internal/notices`: a
file-backed store watched for changes, plus the admin listener. The
`notices` module merges the global list with the current repo's, and
`templates/layouts/notices.html` renders them — but only when
`Ctx.Immutable` is false. `main.go` wires the store to `Site.RevFn` so a
change invalidates caches. `internal/notices` deliberately does not import
`internal/core`; keep it that way so the module and the admin handler can
both reach it without a cycle. The admin listener is the one deliberate
write path, and it writes a config file, never a repository.

## Building and checking

```sh
gofmt -l .          # must print nothing
go vet ./...        # must be clean
go build -o gsg .
```

There is no test suite yet. Until there is, verify changes against a fixture
tree with at least: a bare repo with several commits, a diverged branch, a
merge commit, a tag, a repository with no commits, and a non-bare repo. The
divergence matters — without it, `a..b` and `a...b` produce the same output
and a compare bug is invisible.

```sh
./gsg -root /srv/git -addr 127.0.0.1:8080 -templates ./templates
```

`-templates` re-parses on every request, which is how to iterate on the theme
without restarting.

Routes worth exercising after any change: `/`, `/{repo}/`, `/{repo}/graph/`,
`/{repo}/tree/{ref}/{path}`, `/{repo}/blob/…`, `/{repo}/raw/…`,
`/{repo}/compare/a...b`, `/{repo}/commit/{sha}`, plus the two JSON endpoints
and the empty repository.

If you add a test suite, start with the invariants above — they are the
things worth asserting, and several of them are single-request checks.

## Conventions

- Comments explain **why**, not what. The code says what it does; the comment
  should say what would go wrong otherwise. Several comments in this codebase
  record a specific bug — preserve those rather than tidying them away.
- Errors that are the client's fault carry a status:
  `core.Errorf(http.StatusNotFound, …)`. Anything else becomes a 500 and is
  logged at error level. A valid commit with a bad path is a 404, not a 500.
- User-facing copy is plain and directive. Empty states say what to do ("No
  repositories yet. Create a bare repo under the configured root."), not just
  that something is absent.
- The UI type is monospace throughout because every value on these pages is
  an identifier, hash, path or count. The sans face appears only inside
  rendered README prose. All colour lives in `:root` custom properties; do
  not introduce a literal hex value elsewhere in the stylesheet.
- `gsg` is a placeholder name with no expansion. If it is renamed, the module
  path, the config section, and the footer string all move.

## Known gaps

Accurate as of now; update this list when you close one.

- No test suite.
- No syntax highlighting in the blob view — it returns numbered plain lines.
  Chroma would drop into the `blob` module.
- No pagination on `log` (caps at 200) or `graph` (caps at 150).
- The graph loads all refs into memory before layout. Fine to a few thousand
  commits; beyond that it needs windowing.
- The LRU is bounded by entry count, not bytes, so a large diff and a ref
  list occupy one slot each. The `Store` interface is the only thing a
  size-aware replacement must satisfy.
- Repository discovery is one level deep and happens once at startup; a repo
  created afterwards needs a restart.
- README relative-link rewriting assumes every link is a file. A link to a
  directory lands on the blob view and 404s. Fixing it properly means a tree
  lookup per link.
- Module errors surface at render time, not load time. A CI pass that renders
  every view against a fixture repository would catch them earlier.
- Path queries in the structured JSON/YAML search store the deepest path
  found for a line. Flow style (`{"a": 1, "b": 2}`) puts several values on
  one row and keeps only the last path; a container query still reaches the
  others through the prefix match, but a sibling's exact path does not.