66 lines
2.6 KiB
Markdown
66 lines
2.6 KiB
Markdown
# AGENTS.md
|
|
|
|
Exercise repo: illustrating the transition from DB-backed domain classes
|
|
(`DbBase` inheritance) to plain domain objects + DTOs + mappers.
|
|
Diagrams: `before-after-dto.mmd`, `after-dto.mmd` (source sketch:
|
|
`before-after-dto-sketch.png`).
|
|
|
|
## Rendering diagrams (mermaid → svg)
|
|
|
|
Mermaid diagrams can be rendered to SVG with the `mmdc` CLI (mermaid-cli,
|
|
installed via npm): `mmdc -i <input>` writes `<input>.svg` next to the
|
|
source, i.e. `<name>.mmd` becomes `<name>.mmd.svg`.
|
|
|
|
```sh
|
|
mmdc -i before-after-dto.mmd # -> before-after-dto.mmd.svg
|
|
mmdc -i after-dto.mmd # -> after-dto.mmd.svg
|
|
```
|
|
|
|
## Running dotnet
|
|
|
|
dotnet SDK 10 is installed **via mise** (see `mise.toml`). It is NOT on PATH in
|
|
agent/sandbox shells, and SDK 10 additionally fails without
|
|
`DOTNET_CLI_HOME` in some shells. Always use the wrappers:
|
|
|
|
```sh
|
|
scripts/dotnet.sh build db-subclass-to-dto.sln
|
|
scripts/dotnet.sh test db-subclass-to-dto.sln
|
|
scripts/run-tests.sh # full test suite, from repo root
|
|
```
|
|
|
|
The wrappers cd to the repo root (the test runner must run from the parent
|
|
directory of the test project), export `DOTNET_CLI_HOME`, and invoke
|
|
`mise exec -- dotnet ...`. Do not call bare `dotnet`.
|
|
|
|
If the first-time-use setup fails with `The file ...
|
|
'.dotnet-cli/.dotnet' already exists` or `Operation not permitted` (some
|
|
agent/sandbox shells block `$HOME/.dotnet-cli`), point the wrapper at a
|
|
repo-local home: `DOTNET_CLI_HOME="$PWD/.dotnet-cli" scripts/dotnet.sh ...`
|
|
(add `.dotnet-cli/` to `.gitignore`).
|
|
|
|
## Yaks (task management with yx)
|
|
|
|
Tasks are managed with the `yx` CLI; yaks live in git (event store), snapshot
|
|
in `.yaks/` (gitignored). Work one yak at a time:
|
|
|
|
```sh
|
|
yx list # all yaks and states
|
|
yx show "<yak name>" # full yak context (the task instructions)
|
|
yx start "<yak name>" # set state to wip
|
|
yx done "<yak name>" # set state to done (only after acceptance
|
|
# criteria pass and changes are committed)
|
|
```
|
|
|
|
- The yak context in `yx show` is the authoritative task description; follow
|
|
its acceptance criteria before `yx done`.
|
|
- Children block their parent: do prerequisites (nested under a yak) first.
|
|
- Add new tasks: `yx add "<name>"` (nest with `--under "<parent>"`).
|
|
- If yx complains `.yaks is not gitignored`, keep `.yaks` in `.gitignore`.
|
|
|
|
## Conventions
|
|
|
|
- Target framework: net10.0 (SDK pinned by mise).
|
|
- Tests: xUnit, one `tests/BeforeAfter.Tests/` project.
|
|
- No EF Core / SQLite / AutoMapper — the DB layer is a small hand-rolled fake
|
|
(pure managed code, cross-platform).
|
|
- Commit per yak with a message referencing the yak. |