espresense§espresense-companion

Imported from gencau/test-practices-agent-configurations (dataset/repos/espresense§espresense-companion/AGENTS.md). Install upstream with npx skills add gencau/test-practices-agent-configurations --skill espresense§espresense-companion. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

• Backend: C# ASP.NET Core in src/ (controllers, services, models, utils).
• Frontend: SvelteKit app in src/ui/ (routes, lib, tests). Vite dev server proxies /api and /ws to backend.
• Static assets: src/wwwroot/ (served by backend in production).
• Tests: NUnit C# tests in tests/; frontend unit/e2e tests in src/ui/src and src/ui/tests.

Build, Test, and Development Commands

• Backend dev: dotnet watch --project src (serves API/WebSocket at http://localhost:5279).
• Backend build/test: dotnet build • dotnet test.
• Frontend setup/dev: pnpm -C src/ui install • pnpm -C src/ui start (Vite dev at http://localhost:5173).
• Frontend build/preview: pnpm -C src/ui build • pnpm -C src/ui preview.
• Lint/format UI: pnpm -C src/ui lint • pnpm -C src/ui format.
• Optional container: docker build -t espresense/companion . (uses repo Dockerfile).

Coding Style & Naming Conventions

• EditorConfig: C# uses spaces, 4-width; UI (*.svelte, *.ts, *.js) uses tabs, width 2.
• C#: PascalCase for types/methods, camelCase for locals/params; *Controller.cs, *Service.cs patterns.
• Svelte/TS: Components PascalCase (Map.svelte), stores/utilities in src/ui/src/lib.
• Formatting: UI uses Prettier + ESLint; keep files clean before PR.

Testing Guidelines

• Backend: NUnit (+ Moq). Place tests under tests/ with *Tests.cs naming. Example: TimeSpanExtensionsTests.cs.
• Frontend: Vitest unit tests (pnpm -C src/ui test:unit) and Playwright e2e (pnpm -C src/ui test).
• Expectations: Add/extend tests for new logic; keep existing tests green.

Commit & Pull Request Guidelines

• Commits: Imperative, concise subject (≤72 chars). Prefer Conventional Commits (e.g., feat:, fix:) when reasonable. Link issues (Closes #123).
• PRs: Include purpose, scope, testing notes, and screenshots/GIFs for UI changes. Reference related issues/PRs.
• Quality gate: run dotnet test, pnpm -C src/ui lint, and relevant UI tests before opening/review.

Security & Configuration Tips

• Do not commit secrets. Use src/config.example.yaml as a template; keep local config out of VCS.
• For local tweaks use appsettings.json; avoid hardcoding credentials. Review .gitignore before adding new files.