Merge pull request #565 from devforth/next

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/basePlugin.ts

@@ -47,7 +47,7 @@ export default class AdminForthPlugin implements IAdminForthPlugin {
 
     const seed = `af_pl_${this.constructor.name}_${resourceConfig.resourceId}_${uniqueness}`;
     this.pluginInstanceId = md5hash(seed);
-    afLogger.trace(`🪲 AdminForthPlugin.modifyResourceConfig, ${seed}, 'id', ${this.pluginInstanceId}`);
+    afLogger.trace({seed, pluginInstanceId: this.pluginInstanceId}, `🪲 AdminForthPlugin.modifyResourceConfig`);
     this.adminforth = adminforth;
   }
 

adminforth/commands/createApp/templates/api.ts.hbs

@@ -1,23 +1,32 @@
-import { Express, Request, Response } from "express";
-import { IAdminForth } from "adminforth";
+import { Express, Response } from "express";
+import { IAdminForth, IAdminUserExpressRequest } from "adminforth";
+import * as z from "zod";
+
 export function initApi(app: Express, admin: IAdminForth) {
   app.get(`${admin.config.baseUrl}/api/hello/`,
 
-    // you can use data API to work with your database https://adminforth.dev/docs/tutorial/Customization/dataApi/
-    async (req: Request, res: Response) => {
-      // req.adminUser to get info about the admin users
-      const allUsers = await admin.resource("adminuser").list([]);
-      res.json({
-        message: "List of admin users from AdminForth API",
-        users: allUsers,
-      });
-    },
+    admin.express.withSchema(
+      {
+        description: "Returns example data from a custom Express API together with the current authenticated AdminForth user.",
+        response: z.object({
+          message: z.string(),
+          users: z.array(z.record(z.string(), z.unknown())),
+          adminUser: z.record(z.string(), z.unknown()),
+        }),
+      },
 
-    // you can use admin.express.authorize to get info about the current user
-    admin.express.authorize(
-      async (req: Request, res: Response) => {
-        res.json({ message: "Current adminuser from AdminForth API", adminUser: req.adminUser });
-      }
+      // you can use data API to work with your database https://adminforth.dev/docs/tutorial/Customization/dataApi/
+      // and admin.express.authorize to inject req.adminUser
+      admin.express.authorize(
+        async (req: IAdminUserExpressRequest, res: Response) => {
+          const allUsers = await admin.resource("adminuser").list([]);
+          res.json({
+            message: "Hello from AdminForth API!",
+            users: allUsers,
+            adminUser: req.adminUser,
+          });
+        }
+      )
     )
   );
 }

adminforth/commands/createApp/templates/package.json.hbs

@@ -35,7 +35,8 @@
   "dependencies": {
     "@dotenvx/dotenvx": "^1.34.0",
     "adminforth": "{{adminforthVersion}}",
-    "express": "latest-4"
+    "express": "latest-4",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "typescript": "5.4.5",

adminforth/documentation/blog/2025-04-10-how-to-translate-dynamic-strings/index.md

@@ -45,7 +45,17 @@ export default {
 You might have this page and return it in your API for nuxt:
 
 ```ts
+import * as z from "zod";
+
 app.get(`${admin.config.baseUrl}/api/get_page`,
+  admin.express.withSchema(
+    {
+      description: 'Returns translated SEO metadata for the page specified by the pageUrl query parameter.',
+      response: z.object({
+        meta_title: z.string(),
+        meta_desc: z.string(),
+      }),
+    },
     async (req:any, res: Response): Promise<void> => {
       const pageUrl = req.query.pageUrl;
       if (!pageUrl) {
@@ -62,18 +72,29 @@ app.get(`${admin.config.baseUrl}/api/get_page`,
         meta_desc: page.meta_desc,
       });
     }
-  ) 
+  )
 );
 ```
 
+Install and import Zod before using this pattern: `pnpm add zod` or `npm install zod`, then `import * as z from 'zod';`. `admin.express.withSchema(...)` will convert the Zod schema to OpenAPI for you.
+
 Now you want to translate page meta title and meta description. You can do this by using `i18n` plugin for AdminForth.
 
 ```ts
 import { AdminForth } from "adminforth";
+import * as z from "zod";
 
 export const SEO_PAGE_CATEGORY = "seo_page_config";
 
 app.get(`${admin.config.baseUrl}/api/get_page`,\
+ admin.express.withSchema(
+  {
+    description: 'Returns translated SEO metadata for the page specified by the pageUrl query parameter.',
+    response: z.object({
+      meta_title: z.string(),
+      meta_desc: z.string(),
+    }),
+  },
 //diff-add
  admin.express.translatable(
     async (req:any, res: Response): Promise<void> => {
@@ -107,6 +128,7 @@ app.get(`${admin.config.baseUrl}/api/get_page`,\
         meta_desc,
       });
     }
+  )
 //diff-add
   ) 
 );

adminforth/documentation/blog/tags.yml

@@ -67,3 +67,13 @@ ansible:
   label: Ansible
   permalink: /ansible
   description: Ansible is an open-source automation tool used for configuration management, application deployment, and task automation.
+
+context7:
+  label: Context7
+  permalink: /context7
+  description: Context7 provides MCP-powered library and API documentation access for coding assistants.
+
+MCP:
+  label: MCP
+  permalink: /mcp
+  description: Model Context Protocol is a standard way for tools and assistants to connect to external capabilities and data sources.