v0.1.0 d9218d6

AGENTS.md RawHistoryFolder

Repository rules

  • Use Go 1.27 only; normal builds and tests use CGO_ENABLED=0.
  • Keep a lightweight hexagonal architecture: core imports only stdlib and ports.
  • Owner goroutines own window state; no mutex on window state.
  • Use zerowrap logging with a component field on every entry.
  • Run tests with -race.
  • Use signed conventional commits: type(scope): description.

Mocks (hard rule)

Test doubles are always generated by Mockery v3 (testify template). Never handwrite them.

  • No handwritten fakes, stubs or spies. This covers any test type standing in for a project interface, and function fields swapped by tests (x.ioctl = func...). make check runs fakes-check, which rejects fake/stub/spy/dummy/mock type names in tests.
  • Every seam is an interface. When a test needs to replace a dependency, add an interface and generate its mock:
    • Cross-layer dependencies go in internal/ports. Mocks: internal/mocks/ports, package portsmocks, type MockX.
    • Adapter-internal seams (e.g. a kernel ioctl) stay unexported in the adapter. Mocks: <name>_mock_test.go in the same package.
  • Add a .mockery.yml entry for each new interface, run make mocks and commit the generated files. make mocks-check (CI) fails if they are stale or missing.
  • Use mocks through .EXPECT(). Record calls with RunAndReturn when a test inspects arguments.
  • Channel ports (sealed message interfaces in ports/messages.go) are tested by sending messages, not with mocks.
  • Not doubles, so allowed:
    • real protocol clients in wayland tests (wlturbo proxies);
    • real in-memory implementations of std interfaces (e.g. a locked bytes.Buffer as io.Writer);
    • production constructor parameters such as NewRenderer func(w, h) (ports.Renderer, error), where tests return a generated mock;
    • channels passed to app.run to inject input or observe scenes (channel ports).

Checks before merge

make check, make race, make mocks-check and staticcheck ./... must pass.

source
1# Repository rules
2
3- Use Go 1.27 only; normal builds and tests use CGO_ENABLED=0.
4- Keep a lightweight hexagonal architecture: core imports only stdlib and ports.
5- Owner goroutines own window state; no mutex on window state.
6- Use zerowrap logging with a `component` field on every entry.
7- Run tests with `-race`.
8- Use signed conventional commits: `type(scope): description`.
9
10## Mocks (hard rule)
11
12Test doubles are always generated by Mockery v3 (`testify` template). Never handwrite them.
13
14- **No handwritten fakes, stubs or spies.** This covers any test type standing in for a project interface, and function fields swapped by tests (`x.ioctl = func...`). `make check` runs `fakes-check`, which rejects `fake`/`stub`/`spy`/`dummy`/`mock` type names in tests.
15- **Every seam is an interface.** When a test needs to replace a dependency, add an interface and generate its mock:
16  - Cross-layer dependencies go in `internal/ports`. Mocks: `internal/mocks/ports`, package `portsmocks`, type `MockX`.
17  - Adapter-internal seams (e.g. a kernel ioctl) stay unexported in the adapter. Mocks: `<name>_mock_test.go` in the same package.
18- **Add a `.mockery.yml` entry** for each new interface, run `make mocks` and commit the generated files. `make mocks-check` (CI) fails if they are stale or missing.
19- Use mocks through `.EXPECT()`. Record calls with `RunAndReturn` when a test inspects arguments.
20- Channel ports (sealed message interfaces in `ports/messages.go`) are tested by sending messages, not with mocks.
21- Not doubles, so allowed:
22  - real protocol clients in wayland tests (`wlturbo` proxies);
23  - real in-memory implementations of std interfaces (e.g. a locked `bytes.Buffer` as `io.Writer`);
24  - production constructor parameters such as `NewRenderer func(w, h) (ports.Renderer, error)`, where tests return a generated mock;
25  - channels passed to `app.run` to inject input or observe scenes (channel ports).
26
27## Checks before merge
28
29`make check`, `make race`, `make mocks-check` and `staticcheck ./...` must pass.

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 25

Tags 10

↑↓ moveenter openesc close