@venizia/ignis-docs 0.0.8-2 → 0.0.8

package/{wiki → content}/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"
       }
     ]
   }

package/{wiki → content}/guides/get-started/5-minute-quickstart.md

@@ -177,18 +177,18 @@ Update `package.json` to add build scripts:
     "server:prod": "NODE_ENV=production bun run dist/index.js"
   },
   "dependencies": {
-    "hono": "^4.12.1",
+    "hono": "^4.12.25",
     "@hono/zod-openapi": "latest",
     "@scalar/hono-api-reference": "latest",
     "@venizia/ignis": "latest",
     "@venizia/ignis-helpers": "latest"
   },
   "devDependencies": {
-    "typescript": "^5.5.3",
+    "typescript": "^6.0.3",
     "@types/bun": "latest",
     "@venizia/dev-configs": "latest",
-    "eslint": "^9.36.0",
-    "prettier": "^3.6.2",
+    "eslint": "^10.5.0",
+    "prettier": "^3.8.4",
     "tsc-alias": "^1.8.10"
   }
 }

package/{wiki → content}/references/base/middlewares.md

@@ -43,14 +43,14 @@ IGNIS provides a collection of built-in middlewares for common application needs
 
 The error handler middleware catches all unhandled errors in your application and formats them into consistent JSON responses.
 
-**File:** `packages/core/src/base/middlewares/app-error.middleware.ts`
+**File:** `packages/core/src/base/middlewares/app-error/app-error.middleware.ts`
 
 #### Features
 
 - **Automatic Error Formatting**: Converts all errors to structured JSON responses
-- **ZodError Support**: Special handling for Zod validation errors with detailed field-level messages
-- **Database Error Handling**: Automatically returns 400 for database constraint violations (unique, foreign key, not null, etc.)
-- **Environment-Aware**: Hides stack traces and error causes in production
+- **ZodError Support**: Validation errors surface a schema-driven `messageCode` and `message` (from `params.code`, else the raw Zod code), with the full per-field list under `details.cause`
+- **Database Error Handling**: Returns 400 for SQLSTATE class `22` (data exception) and `23` (integrity) errors, with a fallback message; other classes (e.g. `42` programming errors) stay 500
+- **Production-Safe**: Hides stack traces, error causes, DB driver internals (`detail`/`table`/`constraint`), and raw system messages in production
 - **Request Tracking**: Includes `requestId` for debugging and tracing
 - **Status Code Detection**: Automatically extracts `statusCode` from errors
 
@@ -87,9 +87,13 @@ app.onError(appErrorHandler({
 ```
 
 **Validation Error (ZodError):**
+
+Top-level `message`/`messageCode` come from the first failing issue — its `params.code` if the schema set one (see below), otherwise its raw Zod code. The full per-field list stays under `details.cause`. If `error.rootKey` is configured, the whole body is wrapped under that key.
+
 ```json
 {
-  "message": "ValidationError",
+  "message": "Invalid email address",
+  "messageCode": "invalid_type",
   "statusCode": 422,
   "requestId": "abc123",
   "details": {
@@ -100,45 +104,50 @@ app.onError(appErrorHandler({
       {
         "path": "email",
         "message": "Invalid email address",
-        "code": "invalid_string",
-        "expected": "string",
-        "received": "undefined"
+        "code": "invalid_type",
+        "expected": "string"
       }
     ]
   }
 }
 ```
 
+To emit a stable, domain-specific `messageCode`, attach `params.code` to a custom check:
+
+```typescript
+z.string().refine(isEmail, { message: 'Invalid email address', params: { code: 'user.email.invalid' } });
+// → "messageCode": "user.email.invalid"
+```
+
 **Database Constraint Error:**
 
-Database constraint violations (unique, foreign key, not null, check) are automatically detected and returned as 400 Bad Request with a human-readable message:
+Database errors in SQLSTATE class `22` (data exception) and `23` (integrity constraint) are detected by **class** and returned as 400 Bad Request. A known code uses its specific message; any other in-class code uses `DATABASE_CLIENT_ERROR_FALLBACK_MESSAGE` (`"Invalid database request"`).
 
 ```json
+// non-production — full driver context for debugging
 {
   "message": "Unique constraint violation\nDetail: Key (email)=(test@example.com) already exists.\nTable: User\nConstraint: UQ_User_email",
   "statusCode": 400,
   "requestId": "abc123",
-  "details": {
-    "url": "http://localhost:3000/api/users",
-    "path": "/api/users",
-    "stack": "...",  // development only
-    "cause": { ... }  // development only
-  }
+  "details": { "url": "...", "path": "/api/users", "stack": "...", "cause": { } }
 }
 ```
 
-**Supported PostgreSQL Error Codes:**
-
-| Code | Error Type |
-|------|------------|
-| 23505 | Unique constraint violation |
-| 23503 | Foreign key constraint violation |
-| 23502 | Not null constraint violation |
-| 23514 | Check constraint violation |
-| 23P01 | Exclusion constraint violation |
-| 22P02 | Invalid text representation |
-| 22003 | Numeric value out of range |
-| 22001 | String data too long |
+:::warning Production sanitizes database internals
+In **production** the message is the base message only — `Detail:`/`Table:`/`Constraint:` are stripped (they echo row values and schema names), and `details.stack`/`details.cause` are omitted. Codes outside class 22/23 (e.g. `42703` undefined column) and connection failures return a generic `"Internal Server Error"`, so SQL, schema names, and connection host/port never leak.
+:::
+
+**Database client error classes** — codes in SQLSTATE class `22` (data exception), `23` (integrity constraint), and `44` (WITH CHECK OPTION) map to HTTP 400. Common codes get a specific message; any other in-class code uses the fallback (`"Invalid database request"`).
+
+| Class | Codes with a specific message |
+|-------|-------------------------------|
+| `23` Integrity | `23505` unique · `23503` foreign key · `23502` not null · `23514` check · `23P01` exclusion · `23000` integrity · `23001` restrict |
+| `22` Data exception | `22001` string too long · `22003` numeric range · `22004` null not allowed · `22007` datetime format · `22008` datetime overflow · `22009` tz displacement · `22011` substring · `22012` division by zero · `22023` invalid parameter · `22025` invalid escape · `22026` length mismatch · `22030` duplicate JSON key · `22032` invalid JSON · `22P01` floating-point · `22P02` invalid text · `22P03` invalid binary · `22P05` untranslatable char |
+| `44` View check | `44000` WITH CHECK OPTION violation |
+
+:::tip Transient conflicts return 409, not 400/500
+Class `40` (`40001` serialization failure, `40P01` deadlock) is **transient/retryable** and returns **409 Conflict** with `messageCode: "database.conflict"` and a safe "please retry" message — the client can safely retry the same request. Programming/infra classes (`42` syntax, `53` resources, `0A`, `25`, `28`) remain 500.
+:::
 
 #### API Reference
 

package/dist/mcp-server/common/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../mcp-server/common/paths.ts"],"names":[],"mappings":"AAOA,qBAAa,KAAK;IAChB,MAAM,CAAC,QAAQ,CAAC,IAAI,SAAgC;IAEpD,MAAM,CAAC,QAAQ,CAAC,MAAM,SAAkC;IACxD,MAAM,CAAC,QAAQ,CAAC,WAAW,SAAyC;IACpE,MAAM,CAAC,QAAQ,CAAC,aAAa,SAA2C;IACxE,MAAM,CAAC,QAAQ,CAAC,cAAc,SAA0C;IAExE,MAAM,CAAC,QAAQ,CAAC,UAAU,SAAsC;IAChE,MAAM,CAAC,QAAQ,CAAC,IAAI,SAAsC;IAC1D,MAAM,CAAC,QAAQ,CAAC,SAAS,SAA2C;IAEpE,MAAM,CAAC,QAAQ,CAAC,UAAU,SAAsC;IAChE,MAAM,CAAC,QAAQ,CAAC,UAAU,SAA4C;IACtE,MAAM,CAAC,QAAQ,CAAC,OAAO,SAAyC;IAChE,MAAM,CAAC,QAAQ,CAAC,cAAc,SAA6C;CAC5E"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../mcp-server/common/paths.ts"],"names":[],"mappings":"AAOA,qBAAa,KAAK;IAChB,MAAM,CAAC,QAAQ,CAAC,IAAI,SAAmC;IAEvD,MAAM,CAAC,QAAQ,CAAC,MAAM,SAAkC;IACxD,MAAM,CAAC,QAAQ,CAAC,WAAW,SAAyC;IACpE,MAAM,CAAC,QAAQ,CAAC,aAAa,SAA2C;IACxE,MAAM,CAAC,QAAQ,CAAC,cAAc,SAA0C;IAExE,MAAM,CAAC,QAAQ,CAAC,UAAU,SAAsC;IAChE,MAAM,CAAC,QAAQ,CAAC,IAAI,SAAsC;IAC1D,MAAM,CAAC,QAAQ,CAAC,SAAS,SAA2C;IAEpE,MAAM,CAAC,QAAQ,CAAC,UAAU,SAAsC;IAChE,MAAM,CAAC,QAAQ,CAAC,UAAU,SAA4C;IACtE,MAAM,CAAC,QAAQ,CAAC,OAAO,SAAyC;IAChE,MAAM,CAAC,QAAQ,CAAC,cAAc,SAA6C;CAC5E"}

package/dist/mcp-server/common/paths.js

@@ -7,10 +7,10 @@ exports.Paths = void 0;
 const node_path_1 = __importDefault(require("node:path"));
 const MCP_ROOT = __dirname;
 // When compiled, __dirname is mcp-server/dist/common
-// Go up 3 levels to reach package root: common -> dist -> mcp-server -> docs
+// Go up 3 levels to reach package root: common -> dist -> mcp-server -> wiki (package root)
 const DOCS_ROOT = node_path_1.default.resolve(MCP_ROOT, '..', '..', '..');
 class Paths {
-    static { this.WIKI = node_path_1.default.join(DOCS_ROOT, 'wiki'); }
+    static { this.WIKI = node_path_1.default.join(DOCS_ROOT, 'content'); }
     static { this.GUIDES = node_path_1.default.join(this.WIKI, 'guides'); }
     static { this.GET_STARTED = node_path_1.default.join(this.GUIDES, 'get-started'); }
     static { this.CORE_CONCEPTS = node_path_1.default.join(this.GUIDES, 'core-concepts'); }

package/dist/mcp-server/common/paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../mcp-server/common/paths.ts"],"names":[],"mappings":";;;;;;AAAA,0DAA6B;AAE7B,MAAM,QAAQ,GAAG,SAAS,CAAC;AAC3B,qDAAqD;AACrD,6EAA6E;AAC7E,MAAM,SAAS,GAAG,mBAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AAE3D,MAAa,KAAK;aACA,SAAI,GAAG,mBAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;aAEpC,WAAM,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;aACxC,gBAAW,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;aACpD,kBAAa,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;aACxD,mBAAc,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;aAExD,eAAU,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;aAChD,SAAI,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;aAC1C,cAAS,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;aAEpD,eAAU,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;aAChD,eAAU,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;aACtD,YAAO,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;aAChD,mBAAc,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;;AAf7E,sBAgBC"}
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../mcp-server/common/paths.ts"],"names":[],"mappings":";;;;;;AAAA,0DAA6B;AAE7B,MAAM,QAAQ,GAAG,SAAS,CAAC;AAC3B,qDAAqD;AACrD,4FAA4F;AAC5F,MAAM,SAAS,GAAG,mBAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AAE3D,MAAa,KAAK;aACA,SAAI,GAAG,mBAAI,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;aAEvC,WAAM,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;aACxC,gBAAW,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;aACpD,kBAAa,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;aACxD,mBAAc,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;aAExD,eAAU,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;aAChD,SAAI,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;aAC1C,cAAS,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;aAEpD,eAAU,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;aAChD,eAAU,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;aACtD,YAAO,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;aAChD,mBAAc,GAAG,mBAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;;AAf7E,sBAgBC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venizia/ignis-docs",
-  "version": "0.0.8-2",
+  "version": "0.0.8",
   "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",
@@ -47,7 +47,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/VENIZIA-AI/ignis.git",
-    "directory": "packages/docs"
+    "directory": "docs/wiki"
   },
   "bugs": {
     "url": "https://github.com/VENIZIA-AI/ignis/issues"
@@ -88,8 +88,8 @@
     "README.md",
     "LICENSE.md",
     "dist/mcp-server",
-    "wiki",
-    "!wiki/changelogs",
+    "content",
+    "!content/changelogs",
     "!**/*.tsbuildinfo"
   ],
   "publishConfig": {
@@ -129,7 +129,7 @@
   "devDependencies": {
     "@braintree/sanitize-url": "^7.1.2",
     "@types/bun": "^1.3.14",
-    "@venizia/dev-configs": "^0.0.7-2",
+    "@venizia/dev-configs": "^0.0.7",
     "eslint": "^10.4.0",
     "prettier": "^3.8.3",
     "tsc-alias": "^1.8.17",