Merge branch 'next' of github.com:devforth/adminforth into next

Author: yaroslav8765

AGENTS.md

@@ -1,5 +1,212 @@
-Follow SOLID principles
-Use DRY and avoid duplication
-Keep the code KISS unless complexity is required
-Avoid unnecessary abstractions.
-Cover edge cases and clear error handling
+
+# AGENTS.md
+
+## General engineering rules
+
+Write code as if the system contracts are already defined and trusted.
+
+Do not add defensive checks “just in case” when the contract, type, schema, backend response, or controlled internal API already guarantees the shape of the data.
+
+Prefer simplicity, clarity, and consistency over paranoia.
+
+Follow these principles strictly:
+
+- DRY
+- SOLID
+- YAGNI
+- Keep code minimal
+- Trust typed contracts
+- Avoid duplicate validation
+- Avoid speculative fallback logic
+- Avoid inline regex literals when reused or non-trivial
+
+---
+
+## Trust the contract
+
+If backend and frontend are part of the same system, and the backend explicitly guarantees a response shape, do **not** re-validate every field on the frontend.
+
+Bad:
+- backend returns a strict object
+- frontend then checks every field for `undefined`, wrong type, empty string, wrong enum, etc.
+- frontend adds fallback branches for impossible states
+
+Good:
+- backend owns validation
+- shared types or schemas define the contract
+- frontend consumes the contract directly
+- frontend only handles real UI states, not imaginary protocol corruption
+
+Do not treat trusted internal responses as untrusted external input.
+
+Only add extra runtime validation when:
+- data comes from a truly external/untrusted source
+- the contract is unknown or unstable
+- there is an explicit requirement for hardening
+- security boundaries require validation
+- corrupted legacy data is known to exist in production
+
+If none of the above is true, do not add redundant guards.
+
+---
+
+## No duplicate validation
+
+Validation must live in one clear place.
+
+Prefer this order:
+1. Boundary validation
+2. Domain validation
+3. UI rendering without re-checking the same invariants
+
+Examples:
+- Validate request payload on the backend boundary
+- Validate forms at form/input level
+- Validate DB input before persistence if needed
+- Do not re-check the same rule again deeper in the stack unless there is a real new boundary
+
+If a field is already guaranteed by type/schema/backend, do not validate it again in consumers.
+
+---
+
+## Frontend rules
+
+When rendering data from a trusted backend:
+- do not check every property manually
+- do not write `if (!obj || !obj.a || !obj.b || !obj.c)` chains for guaranteed objects
+- do not silently swallow impossible states
+- do not invent fallback values for required fields unless product requirements explicitly ask for fallback UI
+
+Prefer:
+- strong TypeScript types
+- narrow, explicit UI states
+- a small number of meaningful guards at actual boundaries
+
+Allowed:
+- loading state
+- not-found state
+- permission-denied state
+- explicitly documented optional fields
+
+Not allowed:
+- repetitive property-by-property paranoia checks for required response fields
+
+---
+
+## Backend rules
+
+Backend should enforce the contract once, clearly and centrally.
+
+- Validate incoming external input at the boundary
+- Normalize data once
+- Return stable, typed responses
+- Do not scatter the same checks across controllers, services, and callers
+- Do not add branches for impossible states without evidence
+
+When a response format is defined, keep it strict and predictable so consumers do not need defensive coding.
+
+---
+
+## Regex rules
+
+Do not inline non-trivial regexes directly inside business logic.
+
+Bad:
+- inline regex literals scattered through the codebase
+- repeating the same regex multiple times
+- unreadable regex embedded inside conditions
+
+Good:
+- define regex once as a named constant
+- place reusable regexes in a dedicated constants/module file
+- give regexes semantic names
+- compile once when appropriate
+
+Example:
+- `const EMAIL_RE = /.../`
+- `const SLUG_RE = /.../`
+- `const STRIP_HTML_RE = /.../g`
+
+If regex is used more than once or is not instantly obvious, extract it.
+
+---
+
+## No speculative coding
+
+Do not add code for hypothetical scenarios unless they are documented requirements or known production realities.
+
+Avoid:
+- “in case backend changes”
+- “in case this field comes null someday”
+- “in case this enum gets other values”
+- “in case this internal method returns something unexpected”
+
+If such a risk is real, document it and solve it at the right boundary, not everywhere.
+
+---
+
+## Error handling
+
+Error handling must be intentional, not reflexive.
+
+Handle:
+- real network failures
+- documented optionality
+- known domain errors
+- permission/auth errors
+- user-caused invalid input
+- external system failures
+
+Do not handle:
+- impossible states already excluded by the contract
+- contradictions to compile-time types without evidence
+- redundant field-level checks for trusted internal data
+
+For impossible states, prefer failing loudly in development rather than hiding the issue with fallback logic.
+
+---
+
+## Code review rules for agents
+
+Before writing extra guards, ask:
+
+1. Is this input external and untrusted?
+2. Is this invariant already guaranteed by types/schema/backend?
+3. Am I repeating validation that already exists elsewhere?
+4. Is this a real production case or just imagination?
+5. Would this code make the system clearer, or only noisier?
+
+If the invariant is already guaranteed, do not add the guard.
+
+---
+
+## Preferred style
+
+Prefer:
+- shared types
+- schema-driven boundaries
+- single-source-of-truth validation
+- concise functions
+- explicit contracts
+- named helpers/constants
+- reusable compiled regex constants
+
+Avoid:
+- defensive clutter
+- repeated null/undefined chains for required fields
+- duplicated business rules
+- inline complicated regex
+- fallback-on-fallback logic
+- broad “safety” code without a concrete reason
+
+---
+
+## Decision rule
+
+When choosing between:
+- trusting a well-defined internal contract
+- or adding more defensive checks
+
+choose trusting the contract, unless there is a clear boundary, documented risk, or real evidence that extra validation is needed.
+
+Less code, fewer duplicate checks, clearer ownership.

adminforth/index.ts

@@ -5,6 +5,7 @@ import MysqlConnector from './dataConnectors/mysql.js';
 import SQLiteConnector from './dataConnectors/sqlite.js';
 import CodeInjector from './modules/codeInjector.js';
 import ExpressServer from './servers/express.js';
+import OpenApiRegistry from './servers/openapi.js';
 // import FastifyServer from './servers/fastify.js';
 import { ADMINFORTH_VERSION, listify, suggestIfTypo, RateLimiter, RAMLock, getClientIp, isProbablyUUIDColumn, convertPeriodToSeconds, hookResponseError } from './modules/utils.js';
 import { 
@@ -116,6 +117,7 @@ class AdminForth implements IAdminForth {
   // fastify: FastifyServer;
   auth: AdminForthAuth;
   codeInjector: CodeInjector;
+  openApi: OpenApiRegistry;
   connectors: {
     [dataSourceId: string]: IAdminForthDataSourceConnectorBase,
   };
@@ -169,6 +171,10 @@ class AdminForth implements IAdminForth {
     afLogger.trace('🔧 Creating AdminForthRestAPI...');
     this.restApi = new AdminForthRestAPI(this);
     afLogger.trace('🔧 AdminForthRestAPI created');
+
+    afLogger.trace('🔧 Creating OpenApiRegistry...');
+    this.openApi = new OpenApiRegistry(this);
+    afLogger.trace('🔧 OpenApiRegistry created');
 
     afLogger.trace('🔧 Creating SocketBroker...');
     this.websocket = new SocketBroker(this);