shoc-backend/AGENTS.md

AGENTS.md

Cursor Cloud specific instructions

This repo is the .NET 8 backend for SHOC (Sea Haven Industries), a facility maintenance / work-order & vendor-dispatch platform. It pairs with the React SPA in the shoc-frontend-new repo. Architecture details live in BACKEND_ARCHITECTURE.md; required config is documented in .env.example.

Services & how they run (dev)

• SQL Server 2022 (installed on the VM, Developer edition). There is no systemd in this environment, so it is not started as a service. Start it manually: sudo -u mssql MSSQL_SA_PASSWORD='SeaHaven!Passw0rd1' /opt/mssql/bin/sqlservr (run it in a tmux/background session). It listens on localhost:1433. Note: sqlservr needs the OpenLDAP 2.5 libs (liblber-2.5.so.0 / libldap-2.5.so.0) which are shimmed into /usr/lib/x86_64-linux-gnu because the base OS ships 2.6.
• Web API (Api.SeaHavenIndustries): from the repo root run cd Api.SeaHavenIndustries && dotnet run with these env vars exported first:
  • ConnectionStrings__DefaultConnection='Server=localhost,1433;Database=SeahavenIndustries;User Id=sa;Password=SeaHaven!Passw0rd1;TrustServerCertificate=True;MultipleActiveResultSets=true'
  • JWT__Secret='local-dev-jwt-secret-key-change-me-please-1234567890' (any long string)
  • ASPNETCORE_ENVIRONMENT=Development and ASPNETCORE_URLS='http://localhost:5141' Swagger UI is served at http://localhost:5141/ (root). The React dev server proxies /api to :5141.
• SendGrid, AWS (DynamoDB/S3), Google Maps keys are optional; email failures are swallowed so the app runs without them.

The SA password above is a local-dev-only credential for this VM's SQL Server, not a real secret.

Database: migrations & seeding

• Apply schema with EF Core (the dotnet-ef global tool is installed): dotnet-ef database update --project Data.SeaHavenIndustries --startup-project Api.SeaHavenIndustries (export ConnectionStrings__DefaultConnection first). The DefaultConnection placeholder in appsettings*.json is intentional — always supply the real value via env var / user-secrets.
• The role/admin seeding block in Api.SeaHavenIndustries/Program.cs is commented out, so no users exist after a fresh migrate and there is no anonymous registration endpoint. A dev admin is seeded on this VM (role Admin). Read credentials from Cursor Cloud secrets TEST_LOGIN_USERNAME and TEST_LOGIN_PASSWORD — do not commit plaintext credentials. If the user is missing (e.g. a fresh DB), create it with a throwaway console app that references Data.SeaHavenIndustries and uses ASP.NET Identity UserManager/RoleManager (mirror the commented block in Program.cs), using those same secret values.

Lint / test / build

• Build: dotnet build SeaHavenIndustries.sln (warnings only; 0 errors expected).
• Smoke tests (no SQL required):
  dotnet test Api.SeaHavenIndustries.Tests/Api.SeaHavenIndustries.Tests.csproj and
  dotnet test SeaHaven.Services.Tests/SeaHaven.Services.Tests.csproj
  (xUnit + EF Core InMemory). Expect ~12 + ~18 passing on current dev.
• Broader suite: dotnet test SeaHavenIndustries.Tests/SeaHavenIndustries.Tests.csproj. Some SQL Server LocalDB-gated tests only skip cleanly on Windows LocalDB; on Linux they may fail open with PlatformNotSupportedException instead of skipping — treat that as a test-hygiene issue on the branch under review, not a missing VM dependency.

Known pre-existing app bugs (NOT environment problems)

These are real defects in the committed code; do not mistake them for setup issues:

• EF model/migration drift. The Locations entity expects columns Address1, Address2, Zip, PhoneNumber, Email but the latest migration created Address, ZipCode, Phone, ContactEmail. Any query that touches Locations (location CRUD, and any list/detail that joins it, e.g. Follow-up list/GetById) throws Invalid column name 'Address1'. The Events table has no migration at all (Invalid object name 'Events'), so Calendar read/list fails.
• Writes that avoid the drifted tables work end-to-end. Verified: login, Employee create/list/delete, and Follow-up Create all persist to SQL Server.