runlify 0.0.794 → 0.0.797

package/docs/01-overview.md

@@ -0,0 +1,172 @@
+# Overview & Mental Model
+
+> **Load this file when:** you need to understand how Runlify works end-to-end,
+> or when you need to orient yourself in a Runlify-powered project for the first time.
+
+---
+
+## What Runlify is
+
+Runlify is a **metadata-driven full-stack code generator**. A consumer describes their
+system declaratively using a fluent builder API (`SystemMetaBuilder`). Runlify generates
+two complete sibling projects from that description plus all deployment infrastructure.
+
+```
+meta-project/                  ← you own this
+  src/meta/metadata.ts         ← SystemMetaBuilder DSL — the source of truth
+  src/meta/options.json        ← BootstrapEntityOptions — generation switches
+
+        runlify regen
+              │
+     ┌────────┴────────┐
+     ▼                 ▼
+<prefix>-back/     <prefix>-ui/
+NestJS/Prisma      react-admin
+GraphQL            TypeScript/React
+```
+
+The meta project is **not deployed**. It is a build tool. The two generated projects are
+what actually runs in production.
+
+---
+
+## Data flow
+
+```
+SystemMetaBuilder
+  .addCatalog(...)
+  .addDocument(...)
+  .addMethod(...)
+  .build()                     ← produces a System object
+
+System  ──serialize──▶  src/meta/metadata.json
+BootstrapEntityOptions  ──▶  src/meta/options.json
+
+runlify regen
+  │
+  ├─ reads metadata.json + options.json
+  ├─ prepareProjectWideGenerationArgs()   ← resolves links, normalises DBs
+  ├─ cleanFiles()                         ← wipes previous generated output
+  ├─ generateBack()  [typesOnly pass]     ← generates TS types first
+  ├─ genGraphSchemesByLocalGenerator()    ← generates .graphql schema files
+  ├─ generateBack()  [full pass]          ← full backend generation
+  ├─ generateFront()                      ← frontend generation (if enabled)
+  └─ generateEnvironment()               ← Dockerfile, CI, Helm charts
+```
+
+---
+
+## Two classes of files
+
+Every file in the generated projects is one of two classes.
+
+### Generated files — DO NOT EDIT
+
+Written by Runlify on **every** `regen`. First line is always:
+
+```
+// DO NOT EDIT! THIS IS GENERATED FILE
+```
+
+Editing these files is pointless — changes are lost on the next regen.
+
+Examples: `<Entity>Service.ts`, GraphQL resolvers, Prisma schema, `resources.tsx`,
+`routes.tsx`, `<Entity>List/index.tsx`.
+
+### Your files — safe to edit
+
+Created by Runlify **once** (on first regen) then never touched again.
+These are your extension points.
+
+**Backend:**
+| File | Purpose |
+|------|---------|
+| `Additional<Entity>Service.ts` | Add methods, override behaviour |
+| `hooks/beforeCreate.ts` | Run logic before DB insert |
+| `hooks/afterCreate.ts` | Run logic after DB insert |
+| `hooks/beforeUpdate.ts` | Run logic before DB update |
+| `hooks/afterUpdate.ts` | Run logic after DB update |
+| `hooks/beforeDelete.ts` | Run logic before DB delete |
+| `hooks/afterDelete.ts` | Run logic after DB delete |
+| `hooks/beforeUpsert.ts` | Run logic before upsert |
+| `hooks/additionalOperationsOnCreate.ts` | Side-effects on create |
+| `hooks/additionalOperationsOnUpdate.ts` | Side-effects on update |
+| `hooks/additionalOperationsOnDelete.ts` | Side-effects on delete |
+| `hooks/changeListFilter.ts` | Mutate list query filter at runtime |
+| `hooks/tenantIdRequiredHooks.ts` | Tenant isolation enforcement |
+| `rest/restRouter.ts` | Custom REST endpoints |
+| `init/roles/customPermissions.ts` | Hand-written data-space permissions — see [11-permissions.md](./11-permissions.md) |
+| `init/roles/customUiPermissions.ts` | Hand-written UI-space permissions — see [11-permissions.md](./11-permissions.md) |
+
+**Frontend:**
+| File | Purpose |
+|------|---------|
+| `Dashboard.tsx` | Home page content |
+| `additionalRoutes.tsx` | Custom pages/routes |
+| `getAdditionalMenu.ts` | Extra menu items |
+| `PermissionPage.tsx` | Shown instead of a page the user lacks permission for |
+| `NotFoundPage.tsx` | Shown for an action that doesn't exist on the entity (e.g. no edit form) |
+| `i18n/types.ts`, `i18n/<lang>/<lang>Validation.ts`, `i18n/<lang>/index.ts` | Validation messages and the per-language translation root — see [08-frontend-file-graph.md](./08-frontend-file-graph.md#i18n) |
+
+See [11-permissions.md](./11-permissions.md) for access control — a separate system from
+these "yours" files, spanning both projects.
+
+Full file trees: [07-backend-file-graph.md](./07-backend-file-graph.md) and
+[08-frontend-file-graph.md](./08-frontend-file-graph.md).
+
+---
+
+## What gets generated
+
+| Area | Technology | Docs |
+|------|-----------|------|
+| ORM / DB schema | Prisma (v6/v7) | [07-backend-file-graph.md](./07-backend-file-graph.md) |
+| API layer | GraphQL (Apollo) | [07-backend-file-graph.md](./07-backend-file-graph.md) |
+| Admin UI | react-admin | [08-frontend-file-graph.md](./08-frontend-file-graph.md) |
+| Config | JSON env files | [09-options.md](./09-options.md) |
+| CI/CD | GitLab CI `.yml` | [09-options.md](./09-options.md) |
+| Containers | Dockerfile | [09-options.md](./09-options.md) |
+| Kubernetes | Helm charts | [09-options.md](./09-options.md) |
+
+---
+
+## Output paths
+
+By default `regen` resolves sibling directories relative to the meta project:
+
+```
+../  ← parent of the meta project
+  <prefix>-back/    ← detachedBackProject
+  <prefix>-ui/      ← detachedUiProject
+  <meta-project>/
+```
+
+Both paths are overridable via `detachedBackProject` and `detachedUiProject` in
+`options.json`. See [09-options.md](./09-options.md).
+
+---
+
+## Anti-patterns
+
+### Editing generated files
+
+**Wrong:** opening `<Entity>Service.ts` and adding a method directly.
+
+**Why:** the file is overwritten completely on every `runlify regen`. Your changes vanish
+with no warning.
+
+**Correct:** put all custom logic in `Additional<Entity>Service.ts` or the appropriate
+`hooks/` file.
+
+---
+
+### Putting business logic in `metadata.ts`
+
+**Wrong:** computing values, calling APIs, or reading environment variables inside the
+`SystemMetaBuilder` chain.
+
+**Why:** `metadata.ts` is a build-time description. It must be pure and deterministic.
+Side effects here cause unpredictable generation output.
+
+**Correct:** keep `metadata.ts` as a plain declarative description of the domain.
+All runtime logic goes into the generated project.

package/docs/02-system-meta-builder.md

@@ -0,0 +1,405 @@
+# SystemMetaBuilder API
+
+> **Load this file when:** you need to know what methods are available on the root
+> `SystemMetaBuilder` instance — adding entities, config vars, roles, menus, pages,
+> databases, deploy environments, or custom methods.
+>
+> Related: [03-entity-types.md](./03-entity-types.md) · [04-fields.md](./04-fields.md) ·
+> [05-custom-methods.md](./05-custom-methods.md) · [09-options.md](./09-options.md)
+
+---
+
+## Constructor
+
+```ts
+new SystemMetaBuilder(prefix: string, defOpts?: BootstrapEntityOptions, defaultLanguage?: string)
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `prefix` | `string` | required | Project prefix, used as the base name for all generated artifacts |
+| `defOpts` | `BootstrapEntityOptions` | `defaultBootstrapEntityOptions` | Generation options passed to every entity added. See [09-options.md](./09-options.md) |
+| `defaultLanguage` | `string` | `'ru'` | Default language code for all titles and labels |
+
+The constructor automatically:
+- Seeds ~80 default config vars (DB, S3, JWT, Kafka, ES, ClickHouse, OIDC, Keycloak, recaptcha, Sentry, Loki)
+- Creates two deploy environments: `dev` and `prod`
+- Registers languages `en` and `ru`
+- Adds the built-in `files` catalog via `initDefaultCatalogs()`
+
+---
+
+## Identity
+
+### `setName(name: string): this`
+
+Sets the system name (defaults to `prefix`). Used in generated docs and specs.
+
+### `setPrefix(prefix: string): this`
+
+Sets the project prefix. Affects generated project names and k8s chart names.
+
+### `setNeedFor(needFor: string): this`
+
+Human-readable description of what this system is for. Used in generated documentation.
+
+---
+
+## Entities
+
+All `add*` entity methods throw if a name is already taken across **all** entity types.
+
+### `addCatalog(name, title?, options?): CatalogBuilder` {#addCatalog}
+
+Adds a reference data entity (lookup table).
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | Unique entity name, `camelCase` |
+| `title` | `{ singular?: string, plural?: string }` | Human-readable titles |
+| `options` | `BootstrapEntityOptions` | Overrides default generation options for this entity |
+
+Returns a `CatalogBuilder`. See [03-entity-types.md#catalog](./03-entity-types.md#catalog).
+
+### `addDocument(name, title?, options?): DocumentBuilder` {#addDocument}
+
+Adds a transactional document entity (e.g. orders, invoices).
+
+Same signature as `addCatalog`. Returns a `DocumentBuilder`.
+See [03-entity-types.md#document](./03-entity-types.md#document).
+
+### `addInfoRegistry(name, registrarDepended, title?, options?): InfoRegistryBuilder` {#addInfoRegistry}
+
+Adds an information register (accounting-style, stores state snapshots).
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `registrarDepended` | `boolean` | If `true`, auto-adds `registrarTypeId`, `registrarId`, `row` fields + unique constraint |
+
+See [03-entity-types.md#inforegistry](./03-entity-types.md#inforegistry).
+
+### `addSumRegistry(name, registrarDepended, title?, options?): SumRegistryBuilder` {#addSumRegistry}
+
+Adds a totals register (accounting-style, stores aggregated sums).
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `options` | `RegistryOptions` | `{ registrarIdType: 'int' \| 'string', sharded?: boolean }` |
+
+See [03-entity-types.md#sumregistry](./03-entity-types.md#sumregistry).
+
+### `addManyToManyRelation(name, title?, options?): CatalogBuilder`
+
+Creates a junction catalog for a many-to-many relationship. Identical to `addCatalog`
+internally — the name is semantic only, to signal intent.
+
+### `addReport(name, title?, options?): ReportBuilder` {#addReport}
+
+Adds a read-only report page. Automatically creates a page and a `read` permission.
+See [03-entity-types.md#report](./03-entity-types.md#report).
+
+---
+
+## Lookups
+
+```ts
+getCatalogByName(name: string): CatalogBuilder      // throws if not found
+getInfoRegistryByName(name: string): InfoRegistryBuilder
+getSavableEntities(): EntityBuilderWithOptions[]     // catalogs + documents + infoRegistries + sumRegistries
+getCatalogs(): EntityBuilderWithOptions[]
+getDocuments(): EntityBuilderWithOptions[]
+```
+
+---
+
+## Config Variables
+
+Config vars define the runtime configuration schema for the generated application.
+All config vars seeded in the constructor can be modified after construction.
+
+### `addConfigVar(name, type, required, def, needFor, scopes?, hidden?, editable?): ConfigVarBuilder` {#addConfigVar}
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | `string` | required | Dot-notation key, e.g. `'database.main.write.uri'` |
+| `type` | `FieldType` | required | `'string' \| 'int' \| 'bigint' \| 'float' \| 'bool' \| 'datetime' \| 'date'` |
+| `required` | `boolean` | required | Whether the var must be set in every environment |
+| `def` | `ConfigValue<T>` | required | Default value |
+| `needFor` | `string` | required | Human description of what this var configures |
+| `scopes` | `ConfigVarScope[]` | `['back','worker','telegramBot']` | Which services use this var |
+| `hidden` | `boolean` | `false` | Hide from UI |
+| `editable` | `boolean` | `true` | Allow editing in UI |
+
+Returns a `ConfigVarBuilder` which supports further chaining:
+- `.setRequired()` / `.setScopes(scopes)` / `.addScopes(scopes)` / `.delScopes(scopes)`
+- `.setHidden()` / `.setEditable()` / `.setDefValue(value)`
+- `.setSecure()` — shorthand for `.setHidden(true).setEditable(false)`. Use for secrets.
+
+`ConfigVarScope` values: `'ci' | 'back' | 'admin-app' | 'cutomer-app' | 'worker' | 'telegramBot'`
+
+### `delConfigVar(name: string): this`
+
+Removes a config var by name. Useful for removing default vars seeded in the constructor.
+
+### `getConfigVar(name: string): ConfigVarBuilder | undefined`
+
+Returns the builder for an existing config var, or `undefined`.
+
+### `getConfigVarRequired(name: string): ConfigVarBuilder`
+
+Returns the builder or throws if not found. Use to modify default vars:
+
+```ts
+system.getConfigVarRequired('database.main.write.uri').setDefValue('postgresql://...')
+```
+
+**Anti-pattern — legacy methods:**
+
+`setConfigVarDefaultValue(name, def)` and `setDefaultValueForConfigVar(name, def)` are
+deprecated. They log a warning and delegate to `getConfigVarRequired(name).setDefValue(def)`.
+
+**Correct:** always use `system.getConfigVarRequired(name).setDefValue(value)`.
+
+---
+
+## Databases
+
+`main` is always registered. Additional databases must be registered before entities
+reference them.
+
+### `addDatabase(name: string): this` {#addDatabase}
+
+Registers an additional named database. Automatically generates connection config vars
+for the new database (`database.<name>.write.uri`, etc.).
+
+**Anti-pattern — referencing an unregistered database:**
+
+```ts
+// WRONG: throws at build() time
+const orders = system.addCatalog('orders')
+orders.setDatabase('archive')  // 'archive' was never registered
+
+// CORRECT
+system.addDatabase('archive')
+const orders = system.addCatalog('orders')
+orders.setDatabase('archive')
+```
+
+### `getRegisteredDatabaseNames(): string[]`
+
+Returns `['main', ...others]` sorted alphabetically.
+
+---
+
+## Roles
+
+### `addRole(name: string, title?: string): RoleBuilder` {#addRole}
+
+Defines an access role. Roles are referenced by permissions on entities.
+Name must be unique across all entity names. See
+[11-permissions.md](./11-permissions.md) for how permission strings are named and enforced.
+
+---
+
+## Deploy Environments
+
+Two default environments (`dev`, `prod`) are seeded in the constructor.
+
+### `addDeployEnvironment(env: DeployEnvironment): this`
+
+Adds a new deploy environment. `DeployEnvironment` shape:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Environment name (`'staging'`, `'prod'`, etc.) |
+| `main` | `boolean` | Is this the primary/production environment |
+| `manualDeploy` | `boolean` | Requires manual trigger in CI |
+| `clusterName` | `string` | Kubernetes cluster name |
+| `workerClusterName` | `string` | Kubernetes cluster for workers |
+| `branchName` | `string` | Git branch that triggers this environment |
+| `metricsEnabled` | `boolean` | Enable metrics collection |
+| `host` | `string` | Base domain for this environment |
+| `runnerTag` | `string` | GitLab CI runner tag |
+| `gitlabEnvPrefix` | `string` | Prefix for GitLab environment variables |
+
+### `editDeployEnvironment(name: string, partial: Partial<DeployEnvironment>): this`
+
+Modifies an existing environment. Use to override the defaults:
+
+```ts
+system.editDeployEnvironment('dev', { host: 'mycompany.dev', branchName: 'develop' })
+system.editDeployEnvironment('prod', { host: 'mycompany.com', clusterName: 'prod01' })
+```
+
+### `delDeployEnvironment(name: string): this`
+
+Removes an environment.
+
+---
+
+## Pages & Menu
+
+### `addPage(name, link, label, title?): PageBuilder` {#addPage}
+
+Adds a standalone UI page (not tied to an entity). Used as a target for menu items.
+
+| Parameter | Description |
+|-----------|-------------|
+| `name` | Unique page identifier |
+| `link` | URL path (e.g. `'/dashboard'`) |
+| `label` | i18n key shown in breadcrumbs/menu |
+| `title` | Optional human title |
+
+### `addGroupMenuItem(label: string): GroupMenuItemBuilder`
+
+Adds a collapsible group in the sidebar menu. Returns a builder to add sub-items:
+- `.addInternalMenuItem(pageName)` — link to a page defined in the system
+- `.addExternalMenuItem(label, url)` — link to an absolute URL
+- `.addExternalEnvMenuItem(label, env)` — link resolved from a config var at runtime
+
+### `addInternalMenuItem(pageName: string): InternalMenuItemBuilder`
+
+Adds a top-level sidebar link to an existing page.
+
+### `addExternalMenuItem(label, url): ExternalMenuItemBuilder`
+
+Adds a top-level link to a hardcoded external URL.
+
+### `addExternalEnvMenuItem(label, env): ExternalEnvMenuItemBuilder`
+
+Adds a top-level link where the URL is read from the config var named `env` at runtime.
+Useful for linking to environment-specific external services.
+
+**Anti-pattern — menu items pointing to non-existent pages:**
+
+`addInternalMenuItem` validates that the page exists at `build()` time.
+Calling it with a name that hasn't been registered via `addPage` (or auto-created by an
+entity) throws. Always call `addPage` (or add the entity that owns the page) before
+adding menu items that reference it.
+
+---
+
+## Custom Methods & Models
+
+These produce additional GraphQL operations outside of entity CRUD.
+
+### `addMethod(name, methodType, title?): MethodBuilder` {#addMethod}
+
+Adds a custom GraphQL Query or Mutation at the system level.
+
+| Parameter | Type | Values |
+|-----------|------|--------|
+| `methodType` | `MethodType` | `MethodType.Query` \| `MethodType.Mutation` |
+
+Returns a `MethodBuilder`. See [05-custom-methods.md](./05-custom-methods.md).
+
+### `createGeneralModel(name, title?): BaseModelBuilder`
+
+Creates a model usable as both input and output.
+
+### `createInputModel(name, title?): BaseModelBuilder`
+
+Creates a model usable only as input (GraphQL `input` type).
+
+### `createOutputModel(name, title?): BaseModelBuilder`
+
+Creates a model usable only as output (GraphQL `type`).
+
+See [05-custom-methods.md](./05-custom-methods.md) for full `MethodBuilder` and model API.
+
+---
+
+## i18n
+
+```ts
+addLanguage(id: string, title?: string)  // adds a language (en/ru pre-seeded)
+deleteLanguage(id: string)               // removes a language
+setDefailtLanguage(id: string)           // sets default; must exist or throws
+```
+
+---
+
+## Glossary & Commands
+
+```ts
+addGlossaryTerm(term: string, definition: string)
+// Adds a domain term to the generated documentation. Throws on duplicate.
+
+addCommnad(projectCategory: ProjectCategory, name: string, command: string, needFor: string)
+// Registers a CLI command in the generated docs.
+// projectCategory: 'back' | 'ui' | 'app' | 'land'
+```
+
+---
+
+## Additional Service (standalone service without entity)
+
+### `addAdditionalService(name, title?): AdditionalServiceBuilder`
+
+Adds a standalone backend service with its own methods and models — not tied to any
+entity. Useful for orchestration logic, external integrations, or complex business
+operations that span multiple entities.
+
+---
+
+## Backend deployment config
+
+### `getBack(): DeploymentBuilder`
+
+Returns the `DeploymentBuilder` for the main backend service. Allows configuring
+replicas, CPU/memory requests and limits:
+
+```ts
+system.getBack().setReplicas(2).setRequests({ cpu: '100m', memory: '256Mi' })
+```
+
+---
+
+## Build
+
+### `build(): System`
+
+Validates and serialises the entire meta description into a plain `System` object.
+Throws on any validation error (duplicate names, unregistered databases, invalid
+constraints, etc.).
+
+### `validate(): System`
+
+Alias of `build()`. Can be used to check for errors without assigning the result.
+
+---
+
+## Anti-patterns
+
+### Using `setConfigVarDefaultValue` / `setDefaultValueForConfigVar`
+
+Both are **deprecated**. They print a warning on every call.
+
+**Wrong:**
+```ts
+system.setConfigVarDefaultValue('database.main.write.uri', 'postgresql://...')
+```
+
+**Correct:**
+```ts
+system.getConfigVarRequired('database.main.write.uri').setDefValue('postgresql://...')
+```
+
+### Duplicate names across different entity types
+
+All entity names share a single namespace. `addCatalog('users')` and then
+`addDocument('users')` will throw. Names must be unique across catalogs, documents,
+infoRegistries, sumRegistries, roles, and pages.
+
+### Calling `build()` multiple times expecting different results
+
+`build()` is deterministic. Calling it twice produces two separate plain objects with
+identical content. If you need to check validity without producing output, use
+`validate()` — it is the same operation.
+
+---
+
+> **Examples:** this file intentionally omits code examples. If you are working with
+> this documentation as an AI agent or developer, add real usage examples from the
+> consuming project here. A reference metadata file can typically be found at
+> `src/meta/metadata.ts` in the meta project.