# compare.sr.ht

A git compare/diff viewer for a self-hosted [SourceHut] instance. It compares
two refs (branches, tags, or commits) of any git.sr.ht repository — `base...head`
or `base..head` — and renders the diff with [`@pierre/diffs`] (Shiki-based
syntax-highlighted diffs) and a [`@pierre/trees`] file tree, plus a
single-commit view. Runs at `https://compare.srht.bigb.es`.

[SourceHut]: https://sourcehut.org
[`@pierre/diffs`]: https://www.npmjs.com/package/@pierre/diffs
[`@pierre/trees`]: https://www.npmjs.com/package/@pierre/trees

## Architecture

The service integrates into SourceHut purely through configuration — no upstream
sources are modified (see the sourcehut-custom-service integration model). It is
**stateless**: it owns no database and no object storage. Repository data is read
directly from the bare repos on disk (`{[git.sr.ht] repos}/~{owner}/{name}`) by
shelling out to `git`, exactly as git.sr.ht itself does. Every request is
authorized against the git.sr.ht GraphQL API using core-go's internal-auth
client, acting as the cookie's logged-in user (or anonymously, which the API
scopes to public/unlisted repos). Identity comes from decrypting the shared
`sr.ht.unified-login.v1` cookie with the instance's network key. Pages are
server-rendered Go templates that reproduce the SourceHut chrome; the diff/tree
UI is one vendored esbuild bundle driven by a JSON blob embedded in the page.

## Layout

- `core/` — pure domain: owner/repo/ref validation, the compare-spec grammar,
  sentinel errors. No external dependencies.
- `gitx/` — git shell-out (refs, diff, log, commit) with output limits. *(phase 1)*
- `authz/` — cookie→identity and the GraphQL authorizer with a short TTL cache. *(phase 1)*
- `web/` — chi router, handlers, chrome, Go templates, embedded static assets. *(phase 2)*
- `frontend/` + `scss/` — build-time TypeScript diff bundle and the SCSS entry. *(phase 2)*
- `cmd/comparesrht/` — the daemon entry point and startup validation. *(phase 3)*
- `contrib/` — nginx server block and systemd unit.

The core-go dependency is pinned to a private fork
(`git.srht.bigb.es/~bigbes/core-go`) via a `replace` directive in `go.mod`; the
fork carries one production S3 patch on top of upstream.

## Build requirements

- **Go** 1.26+ (module `go.bigb.es/sourcehut-compare`).
- **sassc** and **minify** — CSS pipeline (`make css`), building against the
  shared sourcehut scss partials installed at `/usr/share/sourcehut/scss`.
- **Node.js** (build time only) — the frontend diff bundle (`make bundle`,
  esbuild). The vendored `web/static/bundle.js` is committed, so Node is not
  needed at runtime.

```sh
make build   # compile the service
make test    # go test ./...
make css     # build the hashed stylesheet
make bundle  # build the vendored frontend bundle
```

## Configuration

See `config.example.ini`. On a real instance, append the `[compare.sr.ht]`
section to the shared `/etc/sr.ht/config.ini`; the service reads the instance's
existing shared keys (`[sr.ht]`, `[webhooks]`, `[meta.sr.ht]`, `[git.sr.ht]`) in
place.

## Deployment

*Filled in during phase 3.* In outline: install the binary and static assets
(`make install`), add the `[compare.sr.ht]` config section, install
`contrib/compare.sr.ht.conf` (nginx) and `contrib/compare-srht.service`
(systemd), point DNS `compare.srht.bigb.es` at the instance, and ensure this
host is within the git.sr.ht API's `internal-ipnet`.