74 lines
3.1 KiB
Markdown
74 lines
3.1 KiB
Markdown
# AGENTS.md
|
|
|
|
This document defines the laws, principles, and rule sets that govern this codebase. Any agent or developer making changes has to adhere to these rules.
|
|
|
|
**Before starting off** — Read the README.md file to understand the project's goals and objectives.
|
|
|
|
---
|
|
|
|
## Agent Rules (Override Everything)
|
|
|
|
1. **No testing by yourself** — All testing is done by the team.
|
|
2. **No assumptions about code or domain logic** — Always confirm and be sure before making changes.
|
|
3. **No running scripts** — Do not run build, dev, test, or migrate scripts unless explicitly approved.
|
|
4. **No touching migration files** — Do not mess with the `migrations` sql dir, as those are generated manually via drizzle orm
|
|
|
|
More rules are only to be added by the human, in case such a suggestion becomes viable.
|
|
|
|
---
|
|
|
|
## 1. Stack
|
|
|
|
- **Monorepo**: Turborepo + pnpm
|
|
- **Language**: TypeScript everywhere, Node >= 24
|
|
- **Apps**: `@apps/main` (SvelteKit), `@apps/front` (Hono), `@apps/orchestrator` (Hono)
|
|
- **Packages**: `@pkg/logic`, `@pkg/db`, `@pkg/logger`, `@pkg/result`, `@pkg/keystore`, `@pkg/settings`
|
|
- **DB**: PostgreSQL via Drizzle ORM; Redis (Valkey) via `@pkg/keystore`
|
|
|
|
---
|
|
|
|
## 2. Logic Package Conventions
|
|
|
|
All domain logic lives in `@pkg/logic` under `packages/logic/domains/<domain>/` with four files: `data.ts`, `repository.ts`, `controller.ts`, `errors.ts`. Mirror this exactly when adding a domain.
|
|
|
|
**Path aliases** (logic package only):
|
|
- `@/*` → `./*` · `@domains/*` → `./domains/*` · `@core/*` → `./core/*`
|
|
|
|
**FlowExecCtx** (`fctx`) — passed into every domain operation for tracing:
|
|
```ts
|
|
type FlowExecCtx = { flowId: string; userId?: string; sessionId?: string; };
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Error Handling
|
|
|
|
- Use `neverthrow` (`ResultAsync`, `okAsync`, `errAsync`) for all fallible async logic.
|
|
- `@pkg/result`'s `Result` type is **legacy** — do not reach for it primarily.
|
|
- Use `ERROR_CODES` from `@pkg/result` for all error codes.
|
|
- Use `getError()` from `@pkg/logger` when converting thrown errors into `Err` objects at boundaries.
|
|
- Use domain-specific error constructors from `errors.ts` — never ad-hoc error objects.
|
|
- Always check `result.isOk()` / `result.isErr()` before accessing `result.value`.
|
|
|
|
---
|
|
|
|
## 4. Main App Conventions (`apps/main`)
|
|
|
|
- Feature code lives in `src/lib/domains/<domain>/` — view model, components, remote functions.
|
|
- **VM pattern**: `*.vm.svelte.ts` classes own all reactive state and async flows for a screen. Pages are thin — they just mount the VM.
|
|
- **Remote functions**: `*.remote.ts` per domain. Naming: `*SQ` for queries, `*SC` for commands.
|
|
- Auth context and `fctx` are built inside remote functions from `event.locals` via `$lib/core/server.utils`.
|
|
|
|
---
|
|
|
|
## 5. Observability Convention
|
|
|
|
When adding any new operation in a repository or controller, wrap it with `traceResultAsync` from `@pkg/logic/core/observability.ts`. Keep span names descriptive and consistent (e.g. `"user.getUserInfo"`). Do not add ad-hoc spans.
|
|
|
|
---
|
|
|
|
## 6. Validation
|
|
|
|
- **Valibot** for all schemas. Types via `v.InferOutput<typeof Schema>`.
|
|
- Domain data types defined in `data.ts`. Remote function inputs validated via Valibot schemas passed to `query()` / `command()`.
|