1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
|
# Neko — Agent Guidelines
## Project Overview
Neko is a self-hosted, single-user RSS reader. Go backend, SQLite storage, vanilla JavaScript frontend (v3). The legacy Backbone.js frontend (v1) lives in `web/static/` — don't touch it unless asked.
## TDD Workflow
Write tests before or alongside code. Every change should have a corresponding test.
- **Go tests**: `go test -cover ./...`
- **Frontend tests**: `cd frontend-vanilla && npm test -- --run`
- **Both at once**: `make test`
- **Lint + tests**: `make check`
Run `make test` before every commit. If tests fail, fix them before committing.
## Check-in Rules
1. Run `make test` — all tests must pass.
2. If you changed anything under `frontend-vanilla/src/`, run `make all` to rebuild production assets in `web/dist/v3/`. These built assets must be committed alongside your source changes.
3. Run `make all` for any UI change. The build output is checked into the repo.
4. Write a clear, concise commit message.
5. Never commit broken tests.
## Code Layout
```
api/ REST API handlers
cmd/neko/ Main entry point
config/ Configuration
internal/ Crawler, exporter, importer, utilities
models/ Database layer (item, feed)
web/ Web server, static assets, embedded dist
frontend-vanilla/ v3 frontend source (TypeScript, CSS, Vite)
```
## Testing Conventions
- Go test files live next to the code they test (`*_test.go`).
- Frontend tests use Vitest and live next to source files (`*.test.ts`).
- Use table-driven tests in Go where appropriate.
- Mock `fetch` in frontend tests — don't hit real endpoints.
## Style Notes
- Keep it simple. This is intentionally minimal software.
- No frameworks in the frontend — vanilla JS/TS only.
- Prefer small, focused changes over large refactors.
|
