docs: add AGENTS.md with project conventions

2026-07-15 16:37:36 -04:00
parent d4f839c491
commit 4358098c57
1 changed files with 76 additions and 0 deletions
@@ -0,0 +1,76 @@
+# AGENTS.md — Sis Project Conventions
+
+## Project Overview
+
+Sis is a shared household chore/task tracker with a Haskell backend and
+TypeScript/Mithril.js SPA frontend.
+
+## Build & Tooling
+
+- **Haskell container:** `./hs <cmd>` runs Haskell tools inside the
+  flipstone/haskell-tools Docker image. Use for `stack build`, `stack test`,
+  `hpack`, `fourmolu`, `hlint`.
+- **Build script:** `./scripts/build` — formats (fourmolu), lints (hlint),
+  builds with stack, copies binary to `build/`.
+- **Test script:** `./scripts/test` — fourmolu check, hlint, `stack test`.
+- **Run script:** `./scripts/run` — starts server in Docker via `stack exec`.
+- **hpack:** `package.yaml` is the source of truth for dependencies. After
+  editing it, run `./hs hpack` to regenerate `sis-server.cabal`. (If `hpack`
+  is unavailable, edit `sis-server.cabal` manually in parallel.)
+
+## Haskell Conventions
+
+- **Style:** fourmolu-formatted. The `./scripts/test` script checks this.
+  Run `./hs fourmolu --mode inplace app/ src/ test/` before committing.
+- **Lint:** hlint clean required. Fix any hints before committing.
+- **Warnings:** `-Wall -Werror` in `package.yaml`. All warnings are fatal.
+- **Module qualifiers:** Use qualified imports with descriptive aliases
+  (e.g., `import Data.Text qualified as T`).
+- **JSON:** Aeson instances live in the same module as the types they
+  serialize (`Sis.Types`).
+- **Architecture:** The backend uses [Orb](https://github.com/flipstone/orb)
+  for HTTP routing (`Sis.Server`), with WAI/Warp underneath. Route types
+  (like `HealthCheck`) implement `Orb.HasHandler`.
+
+## Frontend Conventions
+
+- **SPA framework:** [Mithril.js](https://mithril.js.org/) v2 with TypeScript.
+- **CSS:** [Neo Brutalism](https://unpkg.com/neobrutalismcss@latest) CDN.
+- **Build:** `npm run build` (or `cd frontend && npx tsc` for dev).
+- **API client:** Thin fetch wrapper in `frontend/src/api.ts`. Base path `/api`.
+- **Dev server:** `npm run serve` serves the built frontend on port 5000.
+
+## Project Structure
+
+```
+sis/
+├── app/Main.hs            # Server entry point, CLI options, Warp setup
+├── src/
+│   ├── Sis.hs             # Top-level re-exports
+│   ├── Sis/Server.hs      # Orb HTTP routes, WAI app, SPA serving
+│   ├── Sis/Types.hs       # Core domain types (Task, User, etc.)
+│   └── Sis/Database.hs    # SQLite connection management
+├── test/Spec.hs           # Hspec test suite
+├── frontend/
+│   ├── src/
+│   │   ├── index.ts       # Mithril mount point
+│   │   ├── api.ts         # Backend API client
+│   │   └── components/    # Mithril components
+│   └── public/style.css
+├── docs/
+│   ├── specs/             # Design specs
+│   └── plans/             # Implementation plans
+├── scripts/               # build, test, run
+├── package.yaml           # Haskell deps (hpack source of truth)
+├── sis-server.cabal       # Generated by hpack
+├── stack.yaml             # Stack resolver config
+├── docker-compose.yml     # Deployment stack
+├── Dockerfile             # Production image
+└── FEATURES.org           # Feature roadmap
+```
+
+## Commit Style
+
+- Conventional commits: `feat:`, `deps:`, `test:`, `chore:`, `docs:`.
+- Each commit should be a self-contained logical change.
+- Run `./scripts/test` before committing. Tests must pass.