AGENTS.md

1# Agent instructions
2 
3When working in this repository, run the following commands to verify your changes.
4 
5```bash
6# Test whole repo
7mix test
8 
9# Test individual test you worked on
10mix test test/sequin/runtime/slot_producer/slot_producer_test.exs:1234
11 
12# Test individual file you worked on:
13mix test test/sequin/runtime/slot_producer/slot_producer_test.exs
14 
15# Re-run tests on intermittent failure
16mix test --failed
17
18mix format --check-formatted
19MIX_ENV=prod mix compile --warnings-as-errors
20 
21# CLI checks
22cd cli
23go test ./cli
24if unformatted=$(gofmt -s -l .); [ -n "$unformatted" ]; then
25  echo "Go files need formatting: $unformatted" && exit 1
26fi
27go vet ./...
28go build -o /dev/null ./...
29cd ..
30 
31# Spelling and docs
32make spellcheck
33make check-links
34 
35# Frontend assets
36cd assets
37npm run format:check
38npm run tsc
39cd ..
40```
41 
42These commands should pass before committing. Warnings or noise in test is not acceptable.
43 
44## `mix test`
45 
46- For fast feedback, run `mix test --exclude unboxed`. This skips synchronous tests. Then run `mix test` at the end to validate your work.
47- New tests that you create MUST NOT generate extra logs, even if the tests pass.
48 
49## Testing
50 
51### No `Process.sleep`
52 
53Process.sleep is not allowed in test. You can use temporarily to get things working. But then find a way to use signal passing or telemetry handlers to get rid of it.
54 
55## Using jj workspaces for isolated work
56 
57When working on a feature or fix, you can create an isolated workspace using jj:
58 
59```bash
60# Create a new workspace (from the main repo)
61jj workspace add ../sequin-feature-name
62 
63# The new workspace needs deps and _build symlinked from the main repo
64cd ../sequin-feature-name
65ln -s ../sequin/deps .
66ln -s ../sequin/_build .
67 
68# Now you can run tests and make changes in this isolated workspace
69mix test test/path/to/test.exs
70```
71 
72## Tidewave
73 
74Always use Tidewave's tools for evaluating code, querying the database, etc.
75 
76Use `get_docs` to access documentation and the `get_source_location` tool to
77find module/function definitions.