@venizia/ignis-docs 0.0.8-1 → 0.0.8-3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venizia/ignis-docs",
-  "version": "0.0.8-1",
+  "version": "0.0.8-3",
   "description": "Interactive documentation site and MCP (Model Context Protocol) server for the Ignis Framework. Includes a VitePress-powered documentation site with guides, API references, and best practices. Ships an MCP server (CLI: ignis-docs-mcp) with 11 tools for AI assistants to search docs, browse source code, verify dependencies, and access real-time framework knowledge. Built with Mastra MCP SDK and Fuse.js fuzzy search.",
   "keywords": [
     "ai",
@@ -115,28 +115,28 @@
     "prepublishOnly": "bun run mcp:rebuild"
   },
   "dependencies": {
-    "@mastra/core": "^1.18.0",
-    "@mastra/mcp": "^1.3.2",
-    "cytoscape": "^3.33.1",
+    "@mastra/core": "^1.36.0",
+    "@mastra/mcp": "^1.8.0",
+    "cytoscape": "^3.33.4",
     "cytoscape-cose-bilkent": "^4.1.0",
     "dayjs": "^1.11.20",
     "debug": "^4.4.3",
     "fast-glob": "^3.3.3",
-    "fuse.js": "^7.1.0",
+    "fuse.js": "^7.3.0",
     "gray-matter": "^4.0.3",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@braintree/sanitize-url": "^7.1.2",
-    "@types/bun": "^1.3.11",
-    "@venizia/dev-configs": "^0.0.7-1",
-    "eslint": "^10.1.0",
-    "prettier": "^3.8.1",
-    "tsc-alias": "^1.8.16",
-    "tsx": "^4.20.6",
-    "typescript": "^6.0.2",
+    "@types/bun": "^1.3.14",
+    "@venizia/dev-configs": "^0.0.7-3",
+    "eslint": "^10.4.0",
+    "prettier": "^3.8.3",
+    "tsc-alias": "^1.8.17",
+    "tsx": "^4.22.3",
+    "typescript": "^6.0.3",
     "vitepress": "^1.6.4",
     "vitepress-plugin-mermaid": "^2.0.17",
-    "vue": "^3.5.31"
+    "vue": "^3.5.34"
   }
 }

package/wiki/best-practices/error-handling.md

@@ -60,7 +60,7 @@ Use the correct status code for each error type:
 | 503 | `RS_5.ServiceUnavailable` | Service temporarily down |
 
 :::tip Automatic Database Error Handling
-Database constraint violations (unique, foreign key, not null, check) are automatically converted to HTTP 400 by the global error middleware. You don't need to catch these errors manually.
+Database errors in SQLSTATE class `22` (data exception) and `23` (integrity constraint — unique, foreign key, not null, check, exclusion) are automatically converted to HTTP 400 by the global error middleware. You don't need to catch these manually. Other classes (e.g. syntax / undefined column) stay 500, and production responses are sanitized — see [Repository Layer Errors](#repository-layer-errors).
 :::
 
 ## 3. Error Handling Patterns
@@ -148,7 +148,9 @@ export class UserController extends BaseRestController {
 
 ### Repository Layer Errors
 
-Database constraint violations (unique, foreign key, not null, check) are **automatically handled** by the global error middleware. They return HTTP 400 with a human-readable message:
+Database errors in SQLSTATE class `22` (data exception) and `23` (integrity constraint — unique, foreign key, not null, check, exclusion) are **automatically handled** by the global error middleware and return HTTP 400. Codes outside those classes (e.g. class `42` undefined column — an application/SQL bug) correctly stay 500.
+
+**Non-production** returns the full driver context for debugging:
 
 ```json
 {
@@ -158,6 +160,14 @@ Database constraint violations (unique, foreign key, not null, check) are **auto
 }
 ```
 
+:::warning Production sanitizes database internals
+In production the message is the **base message only** — `Detail:` (which echoes row values like emails), `Table:`, and `Constraint:` are stripped, and `details.stack`/`details.cause` are omitted. Unexpected (non-client) database errors and connection failures return a generic `"Internal Server Error"`, so SQL, schema names, and connection host/port never leak. Use `requestId` + server logs to diagnose.
+
+```json
+{ "message": "Unique constraint violation", "statusCode": 400, "requestId": "abc123" }
+```
+:::
+
 You don't need to wrap repository calls in try-catch for constraint errors. If you need custom error messages, you can still handle them explicitly:
 
 ```typescript
@@ -240,7 +250,9 @@ All errors should follow a consistent format:
 interface ErrorResponse {
   statusCode: number;
   message: string;
+  messageCode?: string; // stable, localizable code (validation: from params.code or the raw Zod code)
   requestId: string;
+  extra?: Record<string, unknown>; // structured context attached via getError(...)
   details?: {
     cause?: Array<{
       path: string;
@@ -271,16 +283,19 @@ interface ErrorResponse {
 }
 
 // 422 Validation Error
+// `message`/`messageCode` come from the first failing issue — its `params.code` if the schema set
+// one, otherwise the raw Zod code (e.g. `invalid_type`, `too_small`). The full list stays in `details.cause`.
 {
   "statusCode": 422,
-  "message": "Validation failed",
+  "message": "Invalid email format",
+  "messageCode": "user.email.invalid",
   "requestId": "abc123",
   "details": {
     "cause": [
       {
         "path": "email",
         "message": "Invalid email format",
-        "code": "invalid_string"
+        "code": "custom"
       }
     ]
   }