# Developer notes

## Layout

| Path | What it is |
|---|---|
| `xteve.go` | `main`: flags, version, start-up |
| `src/` | the application (one Go package `src`) |
| `src/internal/` | authentication, image cache, M3U parser |
| `html/` | web interface: HTML pages, CSS, images, the compiled `js/app.js`, and `embed.go` which embeds the lot |
| `ts/` | TypeScript sources for the web interface |
| `docker/` | container entrypoint |
| `tasks/` | improvement plan and checklist |

## Build the binary

Go 1.27.1 is pinned in `go.mod`; the go command downloads it automatically.

```bash
go build ./...
go vet ./...
go test ./...
```

The web interface is embedded with `go:embed` from `html/`, so a bare clone builds a complete binary.

## Web interface

The UI is plain TypeScript compiled as global scripts (no modules yet) into a single bundle, `html/js/app.js`, which is committed. CI rebuilds it and fails if the committed file is stale.

```bash
npm ci          # installs the pinned TypeScript compiler and jsdom
npm run build   # ts/*.ts -> html/js/app.js
npm run check   # type-check only
npm test        # jsdom tests under tests/ (Node's built-in runner)
```

File order in the bundle is fixed in `ts/tsconfig.json`: `network`, `menu`, `content`, `popup`, `xmltv`, `settings`, `logs`, `base`, `configuration`, `authentication`. Classes must be defined before the top-level statements in later files that instantiate them. All pages load the same bundle.

The tests load the built bundle into a jsdom window (`tests/harness.js`) with a fixture server payload (`tests/fixture.js`), so they exercise the real rendering code. Run `npm run build` before `npm test`.

English strings are inlined in the TypeScript. There is no language layer.

## Run from source

```bash
go run . -config /path/to/config -port 34400
```

Add `-dev` to serve the web interface from the local `html/` directory instead of the embedded copy, so CSS and HTML edits show up on reload. JavaScript still needs `npm run build`.

## Versioning and release

The version lives in two places that must agree: `var Version` in `xteve.go` and the first `#### ` heading in `changelog-beta.md` (without the `-beta` suffix). CI fails on drift.

Drone (`.drone.yml`) runs vet, tests, the bundle check, hadolint and compose validation on every push. Pushes to `master` publish `registry.coadcorp.com/nathan/xteve:latest` and `:<sha>`; other branches publish `:<branch>` and `:<sha>`.

## Endpoints useful for operations

* `GET /healthz` returns `{"status":"ok","version":...,"scanInProgress":...}` with no authentication. The Docker healthcheck uses it.

## Container image

`Dockerfile` builds the binary in a `golang:1.27.1-alpine` stage, copies static `ffmpeg`/`ffprobe` from a pinned `mwader/static-ffmpeg` tag (bump the tag in the Dockerfile; there is no other place to change) and runs on `alpine`. The runtime stage installs `su-exec` and does not set `USER`: `docker/entrypoint.sh` starts as root, applies `PUID`/`PGID` to the `xteve` user by editing `/etc/passwd` and `/etc/group`, fixes ownership of the config directory, and execs `su-exec xteve:xteve xteve`. With `--user` it skips all of that. `ARG XTEVE_UID`/`XTEVE_GID` remain the build-time defaults so Drone's build args still work. Check the script with `sh -n` and `shellcheck -s sh` after editing.