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.

Working Set (for now): the split projects — src/Domain, src/Db, src/Web — focus changes there; leave other projects untouched unless a yak explicitly says otherwise.

Rendering diagrams (mermaid → svg)

Mermaid diagrams are rendered to SVG with mermaid-cli (mmdc), pinned as a devDependency in package.json. Install it once per clone:

npm install        # installs @mermaid-js/mermaid-cli into node_modules/

Then render with npx mmdc, which resolves the local install — the same command on Linux, macOS and Windows (PowerShell/cmd):

npx mmdc -p puppeteer.config.json -i <diagram>.mmd   # -> <diagram>.mmd.svg

-p puppeteer.config.json passes the headless-Chrome flags (--no-sandbox et al.) — without it mmdc fails to launch the browser in agent/sandbox shells. On desktop shells it is not needed: plain npx mmdc -i <input> works. On first run puppeteer downloads its own Chrome. node_modules/ is gitignored.

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, mirroring the src split: tests/Domain.Tests, tests/Db.Tests, tests/Web.Tests, with the shared test-data builders in tests/TestData.
• 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.