db-subclass-to-dto/AGENTS.md

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.

mmdc -i before-after-dto.mmd   # -> before-after-dto.svg
mmdc -i after-dto.mmd          # -> after-dto.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:

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:

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.