git init
This commit is contained in:
MaKarin
216
AGENTS.md
Normal file
216
AGENTS.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# KIS-TOiR — Agent Operating Rules
|
||||
|
||||
Read this file at the start of every session before reading any other file.
|
||||
|
||||
---
|
||||
|
||||
## What this repository is
|
||||
|
||||
KIS-TOiR is a fullstack CRUD application (NestJS backend + React Admin frontend)
|
||||
for equipment maintenance management (Техническое обслуживание и ремонт).
|
||||
|
||||
Generation is driven by a single authoritative source file:
|
||||
|
||||
- `domain/toir.api.dsl` — the complete API contract: enums, DTOs, endpoints, HTTP methods, pagination
|
||||
|
||||
---
|
||||
|
||||
## Source-of-truth hierarchy
|
||||
|
||||
### Tier 1 — authoritative (hand-authored; never overwritten by generation)
|
||||
|
||||
| File | Authoritative for |
|
||||
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `domain/*.api.dsl` | Enums, DTO shapes per operation, nullability, HTTP verb+path per endpoint, endpoint names, pagination contracts. Single source of truth. Drives: NestJS modules + React Admin resources + Prisma schema. |
|
||||
| `prompts/*.md` | Auth rules, runtime rules, framework scaffold rules, Prisma rules, validation rules, generation policy, naming conventions. |
|
||||
| `AGENTS.md` (this file) | Agent workflow, mutation boundaries, verification contract. |
|
||||
|
||||
### Tier 2 — deterministic derivative (generated by script; never edited manually)
|
||||
|
||||
| File | Generated from | Command |
|
||||
| ------------------ | ------------------ | ------------------------------ |
|
||||
| `api-summary.json` | `domain/*.api.dsl` | `npm run generate:api-summary` |
|
||||
|
||||
### Tier 3 — LLM-generated artifacts (never edit manually after generation)
|
||||
|
||||
| Zone | Generated from |
|
||||
| -------------------------------- | ------------------------------------------------------ |
|
||||
| `server/src/modules/<entity>/` | `domain/*.api.dsl` + `prompts/backend-rules.md` |
|
||||
| `client/src/resources/<entity>/` | `domain/*.api.dsl` + `prompts/frontend-rules.md` |
|
||||
| `server/src/app.module.ts` | Module registrations derived from api.dsl api blocks |
|
||||
| `client/src/App.tsx` | Resource registrations derived from api.dsl api blocks |
|
||||
| `server/prisma/schema.prisma` | `domain/*.api.dsl` + `prompts/prisma-rules.md` |
|
||||
| `server/src/auth/` | `prompts/auth-rules.md` |
|
||||
| `client/src/auth/` | `prompts/auth-rules.md` |
|
||||
| `client/src/dataProvider.ts` | `prompts/auth-rules.md` |
|
||||
| `toir-realm.json` | `prompts/auth-rules.md` |
|
||||
| `docker-compose.yml` | `prompts/runtime-rules.md` |
|
||||
| `server/.env.example` | `prompts/runtime-rules.md` |
|
||||
| `client/.env.example` | `prompts/runtime-rules.md` |
|
||||
|
||||
### Tier 4 — handwritten / framework-managed support files
|
||||
|
||||
- Framework scaffold: `server/nest-cli.json`, `server/tsconfig*.json`, `client/vite.config.*`, etc.
|
||||
|
||||
---
|
||||
|
||||
## Forbidden mutations during any generation run
|
||||
|
||||
**NEVER write to `*.dsl` files.**
|
||||
They are read-only inputs. To change the API contract or domain model, edit `domain/*.api.dsl`
|
||||
as a separate explicit task.
|
||||
|
||||
**NEVER manually edit files under `server/src/modules/` or `client/src/resources/`.**
|
||||
To change generated code: update `domain/*.api.dsl` and regenerate.
|
||||
|
||||
**NEVER edit `server/prisma/schema.prisma` directly.**
|
||||
It is LLM-generated from `domain/*.api.dsl` following `prompts/prisma-rules.md`.
|
||||
|
||||
---
|
||||
|
||||
## Generation workflow (required sequence)
|
||||
|
||||
1. Read `AGENTS.md` and `prompts/general-prompt.md`.
|
||||
2. Read the active `api API.<EntityName>` block + its DTOs + its enums from `domain/toir.api.dsl` (entity-scoped — do not inject the full DSL as a blob).
|
||||
3. Load the companion rule files required for the active stage:
|
||||
- `prompts/prisma-rules.md`
|
||||
- `prompts/backend-rules.md`
|
||||
- `prompts/frontend-rules.md`
|
||||
- `prompts/auth-rules.md`
|
||||
- `prompts/runtime-rules.md`
|
||||
- `prompts/validation-rules.md`
|
||||
4. Verify or repair framework scaffolds before domain generation:
|
||||
- official Nest CLI for backend workspace creation/repair
|
||||
- official Vite React TypeScript CLI for frontend workspace creation/repair
|
||||
- official Prisma CLI when Prisma initialization or repair is required
|
||||
5. Generate `server/prisma/schema.prisma` per `prompts/prisma-rules.md`.
|
||||
6. Generate backend modules and registrations per `prompts/backend-rules.md`.
|
||||
7. Generate frontend resources and registrations per `prompts/frontend-rules.md`.
|
||||
8. Generate auth/runtime/realm artifacts per `prompts/auth-rules.md` and `prompts/runtime-rules.md`.
|
||||
9. Refresh `api-summary.json` only when validation/tooling requires the auxiliary freshness artifact: `npm run generate:api-summary`.
|
||||
10. Run: `node tools/validate-generation.mjs --artifacts-only`
|
||||
11. Run: `npm run eval:generation`
|
||||
12. Fix all failures before considering the task complete.
|
||||
|
||||
**Context budget rule:** Before generating any DTO or component, quote the field
|
||||
definitions from the DSL api block verbatim, then generate from those quotes. This
|
||||
prevents training-data contamination. See `prompts/general-prompt.md`.
|
||||
|
||||
---
|
||||
|
||||
## Type mappings
|
||||
|
||||
| DSL type | Prisma type | TS DTO type | React Admin component |
|
||||
| --------- | ----------------------------- | ----------- | ----------------------------- |
|
||||
| `uuid` | `String @id @default(uuid())` | `string` | `TextInput` / `TextField` |
|
||||
| `string` | `String` | `string` | `TextInput` / `TextField` |
|
||||
| `text` | `String` | `string` | `TextInput` / `TextField` |
|
||||
| `integer` | `Int` | `number` | `NumberInput` / `NumberField` |
|
||||
| `number` | `Float` | `number` | `NumberInput` / `NumberField` |
|
||||
| `decimal` | `Decimal` | `string` | `NumberInput` / `NumberField` |
|
||||
| `date` | `DateTime` | `string` | `DateInput` / `DateField` |
|
||||
| `boolean` | `Boolean` | `boolean` | (appropriate boolean input) |
|
||||
| enum name | enum name | `string` | `SelectInput` / `SelectField` |
|
||||
|
||||
---
|
||||
|
||||
## Naming conventions
|
||||
|
||||
Resource name (plural, kebab-case):
|
||||
|
||||
- `Equipment` → `equipment` (irregular — stays as-is)
|
||||
- `EquipmentType` → `equipment-types`
|
||||
- `RepairOrder` → `repair-orders`
|
||||
- General: PascalCase → kebab-case → append `s` (or `es` if ends in `s`; irregular cases explicit)
|
||||
|
||||
Default sort field (when not declared in api.dsl):
|
||||
Priority: `inventoryNumber` > `number` > `code` > `name` > primary key
|
||||
|
||||
---
|
||||
|
||||
## Verification gate (two-stage)
|
||||
|
||||
### Stage 1 — Structural gate
|
||||
|
||||
```
|
||||
node tools/validate-generation.mjs --artifacts-only
|
||||
```
|
||||
|
||||
Checks: file existence, api-summary freshness, auth seam contracts, natural-key handling, realm structure, runtime contract, api.dsl coverage (backend + frontend files per entity), DTO field name coverage, **DTO class-validator decorator coverage**, **@UseGuards presence on controllers**, **frontend component type correctness**.
|
||||
|
||||
Full structural verification (requires installed `node_modules`):
|
||||
|
||||
```
|
||||
node tools/validate-generation.mjs
|
||||
```
|
||||
|
||||
### Stage 2 — Eval harness (Rule 6)
|
||||
|
||||
```
|
||||
npm run eval:generation
|
||||
```
|
||||
|
||||
Fixture-based semantic checks from `tools/eval/fixtures/`. Checks: correct HTTP method decorators, Content-Range header, enum filter patterns, FK reference wiring, component type correctness, class-validator decorator patterns.
|
||||
|
||||
See `tools/eval/README.md` for fixture authoring and eval-driven development workflow.
|
||||
|
||||
**Generation is incomplete unless both stages pass.**
|
||||
|
||||
## Pre-commit hook
|
||||
|
||||
Install with `npm run install-hooks`. The hook runs **both** the structural gate and
|
||||
the eval harness before every commit. Commits are blocked when either fails.
|
||||
|
||||
---
|
||||
|
||||
## Auth and runtime defaults
|
||||
|
||||
Full auth contract: `prompts/auth-rules.md`
|
||||
|
||||
Working defaults (do not regress to localhost):
|
||||
|
||||
- Keycloak base: `https://sso.greact.ru`
|
||||
- Realm/client: `toir` / `toir-frontend` / `toir-backend`
|
||||
- Production frontend: `https://toir-frontend.greact.ru`
|
||||
- CORS: `http://localhost:5173,https://toir-frontend.greact.ru`
|
||||
|
||||
---
|
||||
|
||||
## OpenRouter configuration
|
||||
|
||||
```
|
||||
OPENAI_API_KEY=<openrouter-key>
|
||||
OPENAI_BASE_URL=https://openrouter.ai/api/v1
|
||||
OPENAI_MODEL=<model-id>
|
||||
```
|
||||
|
||||
These variables are used by `tools/api-format-to-openapi/convert.mjs --mode llm`.
|
||||
|
||||
---
|
||||
|
||||
## Reading order for generation tasks
|
||||
|
||||
**Critical zone (load first, never drop):**
|
||||
|
||||
1. `AGENTS.md` (this file) — project governance, mutation boundaries, tier hierarchy
|
||||
2. `prompts/general-prompt.md` — master orchestration prompt: mission, stage ownership, delegation model, completion criteria
|
||||
3. `domain/toir.api.dsl §API.<EntityName>` — active api block only, plus its referenced DTOs and enums
|
||||
|
||||
**Companion zone (load when the matching stage is active):**
|
||||
|
||||
4. `prompts/prisma-rules.md` — Prisma schema generation details
|
||||
5. `prompts/backend-rules.md` — NestJS generation details
|
||||
6. `prompts/frontend-rules.md` — React Admin generation details
|
||||
7. `prompts/auth-rules.md` — auth seam and realm requirements
|
||||
8. `prompts/runtime-rules.md` — scaffold, env, and bootstrap requirements
|
||||
9. `prompts/validation-rules.md` — success gate requirements
|
||||
|
||||
**Auxiliary zone (never authoritative):**
|
||||
|
||||
10. `api-summary.json` — optional inventory/freshness artifact for validators and supporting tooling; do not use it instead of the DSL
|
||||
|
||||
**Reference only (do not load proactively):**
|
||||
|
||||
- `domain/dsl-spec.md` — DSL syntax reference; load only if DSL is ambiguous
|
||||
- `docs/generation-playbook.md` — step-by-step workflow reference
|
||||
- `docs/future-work.md` — deferred items (Rules 7 and 8)
|
||||
Reference in New Issue
Block a user