# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Build/Run

```bash
npm run dev          # compile (esbuild → dist/index.js) + run CLI
npm run build        # lint + compile
npm run lint         # eslint --fix on src/**/*.ts
npm start            # run dist/index.js directly
```

Build bundles everything into a single `dist/index.js` (esbuild, platform: node, target: es2016). `scripts/copyTsTemplates.js` then copies static templates from `src/templates/` into `dist/templates/` — the runtime reads templates from `__dirname/templates/`.

No test suite. Validate changes by running `npm run dev` and inspecting `output/`.

**Working on this project vs. using it:** this repo is the *generator itself*. Running `vex` reads schema files, runs the generator pipeline, and writes `output/` — a standalone Express app. The output has its own `package.json` and dependencies. Changes to generator source (`src/`) need `npm run compile` before `vex` picks them up.

## Docs

Project documentation lives in `docs/`. Key references:

| Document | Content |
|----------|---------|
| `docs/vexJsonSchema.md` | Full JSON Schema reference — `x-documentConfig`, `x-foreignKey`, `x-format`, `x-vexData` |
| `docs/apiUsage.md` | API client guide — pagination, search, response format |
| `docs/appGenerated/auth.md` | Auth system — JWT rolling keys, OAuth2 providers |
| `docs/features/rbac.md` | Role-based access control — role files, permission model |
| `docs/features/dataIsolation.md` | Row-level ownership — declarative per-entity query scoping |
| `docs/features/filterOperators.md` | Filter query operators — `$and`, `$or`, `$like`, `$in`, comparison |
| `docs/features/joinWhitelist.md` | Join whitelist — restricting relation joins at the API level |
| `docs/ForeignKey.md` | Foreign-key joining via API `join` parameter |
| `docs/roadMap/` | Future plans and version milestones |

## Architecture

VeryExpress is a **code generator** — it reads JSON Schema files and produces a complete Express.js REST API.

```
jsonSchema/*.json  →  preprocess (validate/normalize)  →  generators  →  output/
```

| Directory | Role |
|-----------|------|
| `src/cli.ts` | CLI entry (`vex` command), minimal config parsing, delegates to `generate()` |
| `src/index.ts` | Orchestrator — creates dirs, copies static templates, preprocesses schemas, runs all generators in order |
| `src/generators/` | Async `compile()` functions that generate code files into `output/` |
| `src/templates/` | Static base files copied verbatim (renamed `.ts` → `.gen.ts`) into the generated app |
| `src/preprocess/` | Schema validation, normalization, FK metadata wiring before generation |
| `src/types/types.ts` | Core interfaces: `compilerOptions`, `jsonSchema`, `jsonSchemaPropsItem`, `documentConfig` |
| `src/utils/` | File I/O, logging, JSON-schema helpers, template formatter, config defaults |

### Generation pipeline (in `src/index.ts → generate()`)

1. Validate config, set up directories
2. Copy static templates into `output/src/system/`
3. Preprocess schemas — normalize `required` arrays, validate FK configs, sync role enums
4. For each JSON schema file in parallel: generate TypeScript interface, DB model (Mongoose or TypeORM), and controller
5. Generate join whitelist registry, SQL migrations (if `dbType === "sql"`)
6. Generate routes, server entrypoint, and project settings files (package.json, tsoa.json, env config)

### Generator pattern

Every generator exports an async `compile(options)` that:
1. Extracts/validates data from options
2. Calls a `*Template()` function that returns a string
3. Writes with `utils.common.writeFile()` — it compares normalized content (stripping header comments) and skips if unchanged

### Template system

Two kinds of templates:

- **Static templates** in `src/templates/` — copied as-is to `output/`, with `.ts` → `.gen.ts` renaming (except `index.ts`). Generated files are considered write-once (hand-editable between runs).
- **Template functions** in `*.template.ts` beside their generator — use `{{placeholder}}` syntax replaced via `.replace()`.

`FUNC{{ <code> }}` syntax embeds runnable JS in generated output. The formatter in `src/utils/template.ts` strips the wrapping `'FUNC{{...}}'` quotes so the inner code runs as JavaScript in the generated file.

### Path aliases

`tsconfig.json` maps `~/*` → `src/*`. Imports can use `~/generators/...`, `~/utils/...`, `~/types/...`.

### DB targets

Controlled by `vex.config.json` → `dbType`:
- `"mongo"` — Mongoose models (`src/generators/db/mongooseModel.generator.ts`)
- `"sql"` — TypeORM entities + Knex SQL migrations (`src/generators/db/typeormEntity.generator.ts`, `src/generators/db/sqlMigration.generator.ts`)

### TSOA integration (current branch)

Generates `tsoa.json` in output root so `tsoa` CLI produces routes + OpenAPI spec. Controller decorators use `@Route`, `@Security`, `@Tags`, etc. The authentication middleware at `src/templates/_middlewares/tsoaAuthentication.ts` handles `BearerAuth` and `AuthIndex` security schemes.

### Preprocessing

Three preprocessors run before generation, in `src/preprocess/`:

| File | Role |
|------|------|
| `jsonschemaFormat.ts` | Validate schema structure (`x-documentConfig`, FK config, `x-format` type constraints). Normalize per-prop `required: true` into root `required: string[]`. For SQL target, convert `ObjectId` → `Primary` on `_id`, warn on nested index/FK/vexData. |
| `jsonSchemaForeignKeys.ts` | Wire reverse-relation metadata (`one-to-many` derived from other side's `many-to-one`). Auto-populate `restApi.joinWhitelist` if not set. |
| `roleDefinitions.ts` | For RBAC schemas, ensure per-role JSON files exist with default CRUD permissions for each resource document. |

### Interface generation

Uses `json-schema-to-typescript` to emit TypeScript interfaces from each JSON schema. Then injects FK relation types (`{DocName}Relations`, `{DocName}ApiRelations`, `{DocName}WithRelations`, `{DocName}WithApiRelations`) and generates enums for fields with `enum` arrays.

### Repository adapter pattern

Controllers never touch ORM/ODM directly. They call `VexDb.getRepository(Entity)` which returns a `VexRepository<T>` (an interface in `src/templates/_types/vex/`). Two adapters implement it:

| Adapter | DB target | Notes |
|---------|-----------|-------|
| `TypeOrmRepositoryAdapter` | SQL | Maps `$and`/`$or`/`$like`/`$gt` etc. → TypeORM `FindOptions`. Applies data isolation ownership filter if configured. |
| `MongooseRepositoryAdapter` | Mongo | Thin wrapper. Many features (join, select, pagination, count) are TODO — Mongoose support is less mature. |

The `VexRepository<T>` interface defines: `find`, `count`, `findOne`, `findOneWhere`, `create`, `replace`, `update`, `delete`, `deleteWhere`.

### Data isolation

Entities can declare `dataIsolation: { field: "ownerId" }` in `x-documentConfig.restApi`. This generates:

1. A `DataIsolationRegistry.gen.ts` mapping entity → ownership field
2. The `DataIsolationContext` middleware (AsyncLocalStorage) injected into the request pipeline
3. The TypeORM adapter reads the current user ID from context and injects `{ [field]: userId }` into every query — transparent row-level ownership

The RBAC middleware generator (`src/generators/middlewares/RBACmiddleware.generator.ts`) produces `RoleBaseAccessControl.gen.ts` which enforces per-document CRUD permissions based on role JSON files.

### Routing & auth generation

The route generator (`src/generators/routes/`) produces three kinds of routes:

- **API routes** — generated by tsoa from controller decorators (`@Route`, `@Get`, `@Post`, etc.)
- **Auth routes** — `AuthController.gen.ts` (tsoa-based: login, register, token refresh) and `AuthRouter.gen.ts` (express OAuth passport redirect flows)
- **Swagger UI** — `SwaggerRouter.gen.ts` serving OpenAPI spec + Swagger UI

### Migration system

`src/migration.ts` runs pending migrations before generation. Each migration in `src/migrations/<version>.ts` exports `run(jsonSchemaDir: string): void`. Versions are compared semver-wise against `lastGeneratedVersion` in `.vex/meta.json`. To add a migration, import it in `src/migration.ts` and push to the `migrations` array.

### Project settings generation

`src/generators/projectSettings/` produces non-code files: `package.json`, `.env`, tsoa config, build scripts (for the *generated* app, not this repo).

### Meta tracking

`.vex/meta.json` in the generated project root tracks `lastGeneratedVersion` and per-file `allowOverwrite` flags. On version major/minor change, `sysDir` is wiped for clean regeneration. The migration system (`src/migration.ts`) runs pending version-bumped migrations before generation.

## JSON Schema extensions (custom `x-*` properties)

- `x-documentConfig` — REST methods, document name (must match filename)
- `x-foreignKey` — relationships, only `one-to-one` and `many-to-one` on owning side; `one-to-many` auto-derived
- `x-vexData: "role"` — marks field for RBAC
- `x-format: "ObjectId"` — MongoDB ObjectId, auto-converted to `"Primary"` for SQL target
- Full reference: `docs/vexJsonSchema.md`

## Key conventions

- Generated files: `{DocName}{Type}.gen.ts` — never hand-edit (regenerated on next `vex` run)
- Controller class: PascalCase (e.g. `UserController`)
- REST endpoint: lowercase documentName (e.g. `/user`)
- `required` fields: preprocessor normalizes `required: true` on individual props into root-level `required: string[]`, but source schemas use the array form
- `interface.fkProps` on each schema holds reverse-relation metadata populated during preprocessing

## Style

Caveman speak — drop articles, filler, pleasantries. Short, direct, technical. Code itself remains idiomatic TypeScript.