@mandujs/core 0.4.3 → 0.5.1

package/package.json

@@ -1,41 +1,41 @@
-{
-  "name": "@mandujs/core",
-  "version": "0.4.3",
-  "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
-  "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
-  "exports": {
-    ".": "./src/index.ts",
-    "./client": "./src/client/index.ts",
-    "./*": "./src/*"
-  },
-  "files": [
-    "src/**/*"
-  ],
-  "keywords": [
-    "mandu",
-    "framework",
-    "agent",
-    "ai",
-    "code-generation"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/konamgil/mandu.git",
-    "directory": "packages/core"
-  },
-  "author": "konamgil",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "bun": ">=1.0.0"
-  },
-  "peerDependencies": {
-    "react": ">=18.0.0",
-    "react-dom": ">=18.0.0",
-    "zod": ">=3.0.0"
-  }
-}
+{
+  "name": "@mandujs/core",
+  "version": "0.5.1",
+  "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/client/index.ts",
+    "./*": "./src/*"
+  },
+  "files": [
+    "src/**/*"
+  ],
+  "keywords": [
+    "mandu",
+    "framework",
+    "agent",
+    "ai",
+    "code-generation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/konamgil/mandu.git",
+    "directory": "packages/core"
+  },
+  "author": "konamgil",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
+    "zod": ">=3.0.0"
+  }
+}

package/src/contract/index.ts

@@ -0,0 +1,63 @@
+/**
+ * Mandu Contract Module
+ * Contract-first API 정의 시스템
+ */
+
+export * from "./schema";
+export * from "./types";
+export * from "./validator";
+
+import type { ContractDefinition, ContractInstance } from "./schema";
+
+/**
+ * Create a Mandu API Contract
+ *
+ * Contract-first 방식으로 API 스키마를 정의합니다.
+ * 정의된 스키마는 다음에 활용됩니다:
+ * - TypeScript 타입 추론 (Slot에서 자동 완성)
+ * - 런타임 요청/응답 검증
+ * - OpenAPI 문서 자동 생성
+ * - Guard의 Contract-Slot 일관성 검사
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod";
+ * import { Mandu } from "@mandujs/core";
+ *
+ * const UserSchema = z.object({
+ *   id: z.string().uuid(),
+ *   email: z.string().email(),
+ *   name: z.string().min(2),
+ * });
+ *
+ * export default Mandu.contract({
+ *   description: "사용자 관리 API",
+ *   tags: ["users"],
+ *
+ *   request: {
+ *     GET: {
+ *       query: z.object({
+ *         page: z.coerce.number().default(1),
+ *         limit: z.coerce.number().default(10),
+ *       }),
+ *     },
+ *     POST: {
+ *       body: UserSchema.omit({ id: true }),
+ *     },
+ *   },
+ *
+ *   response: {
+ *     200: z.object({ data: z.array(UserSchema) }),
+ *     201: z.object({ data: UserSchema }),
+ *     400: z.object({ error: z.string() }),
+ *     404: z.object({ error: z.string() }),
+ *   },
+ * });
+ * ```
+ */
+export function createContract<T extends ContractDefinition>(definition: T): T & ContractInstance {
+  return {
+    ...definition,
+    _validated: false,
+  };
+}

package/src/contract/schema.ts

@@ -0,0 +1,110 @@
+/**
+ * Mandu Contract Schema Types
+ * API 계약 정의를 위한 타입 시스템
+ */
+
+import type { z } from "zod";
+
+/** HTTP Methods supported in contracts */
+export type ContractMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+/** Request schema for a specific HTTP method */
+export interface MethodRequestSchema {
+  /** Query parameters schema */
+  query?: z.ZodTypeAny;
+  /** Request body schema */
+  body?: z.ZodTypeAny;
+  /** Path parameters schema (for nested routes) */
+  params?: z.ZodTypeAny;
+  /** Request headers schema */
+  headers?: z.ZodTypeAny;
+}
+
+/** Nested route schema (e.g., ":id" for /users/:id) */
+export interface NestedRouteSchema extends MethodRequestSchema {
+  GET?: MethodRequestSchema;
+  POST?: MethodRequestSchema;
+  PUT?: MethodRequestSchema;
+  PATCH?: MethodRequestSchema;
+  DELETE?: MethodRequestSchema;
+}
+
+/** Request schemas by method */
+export interface ContractRequestSchema {
+  GET?: MethodRequestSchema;
+  POST?: MethodRequestSchema;
+  PUT?: MethodRequestSchema;
+  PATCH?: MethodRequestSchema;
+  DELETE?: MethodRequestSchema;
+  /** Nested routes (e.g., ":id" for /users/:id) */
+  [key: string]: MethodRequestSchema | NestedRouteSchema | undefined;
+}
+
+/** Response schemas by status code */
+export interface ContractResponseSchema {
+  200?: z.ZodTypeAny;
+  201?: z.ZodTypeAny;
+  204?: z.ZodTypeAny;
+  400?: z.ZodTypeAny;
+  401?: z.ZodTypeAny;
+  403?: z.ZodTypeAny;
+  404?: z.ZodTypeAny;
+  500?: z.ZodTypeAny;
+  [statusCode: number]: z.ZodTypeAny | undefined;
+}
+
+/** Full contract schema definition */
+export interface ContractSchema {
+  /** API description */
+  description?: string;
+  /** Tags for grouping (e.g., OpenAPI tags) */
+  tags?: string[];
+  /** Request schemas by method */
+  request: ContractRequestSchema;
+  /** Response schemas by status code */
+  response: ContractResponseSchema;
+}
+
+/** Contract definition input (what user provides) */
+export interface ContractDefinition {
+  description?: string;
+  tags?: string[];
+  request: ContractRequestSchema;
+  response: ContractResponseSchema;
+}
+
+/** Contract instance with metadata */
+export interface ContractInstance extends ContractSchema {
+  /** Unique identifier (derived from route id) */
+  _id?: string;
+  /** Whether this contract is validated */
+  _validated?: boolean;
+}
+
+/** Validation error detail */
+export interface ContractValidationIssue {
+  /** Field path (e.g., "body.email") */
+  path: (string | number)[];
+  /** Error message */
+  message: string;
+  /** Zod error code */
+  code: string;
+}
+
+/** Validation error by type */
+export interface ContractValidationError {
+  /** Error type (query, body, params, headers, response) */
+  type: "query" | "body" | "params" | "headers" | "response";
+  /** Validation issues */
+  issues: ContractValidationIssue[];
+}
+
+/** Validation result */
+export interface ContractValidationResult {
+  /** Whether validation succeeded */
+  success: boolean;
+  /** Validation errors if failed */
+  errors?: ContractValidationError[];
+  /** Parsed/transformed data if successful */
+  data?: unknown;
+}

package/src/contract/types.ts

@@ -0,0 +1,134 @@
+/**
+ * Mandu Contract Type Inference
+ * Contract 스키마에서 TypeScript 타입 추론
+ */
+
+import type { z } from "zod";
+import type {
+  ContractSchema,
+  ContractRequestSchema,
+  ContractResponseSchema,
+  MethodRequestSchema,
+} from "./schema";
+
+/**
+ * Extract inferred type from Zod schema
+ */
+type InferZod<T> = T extends z.ZodTypeAny ? z.infer<T> : never;
+
+/**
+ * Infer request schema types for a single method
+ */
+type InferMethodRequest<T extends MethodRequestSchema | undefined> = T extends MethodRequestSchema
+  ? {
+      query: T["query"] extends z.ZodTypeAny ? z.infer<T["query"]> : undefined;
+      body: T["body"] extends z.ZodTypeAny ? z.infer<T["body"]> : undefined;
+      params: T["params"] extends z.ZodTypeAny ? z.infer<T["params"]> : undefined;
+      headers: T["headers"] extends z.ZodTypeAny ? z.infer<T["headers"]> : undefined;
+    }
+  : undefined;
+
+/**
+ * Infer all request schemas
+ */
+type InferContractRequest<T extends ContractRequestSchema> = {
+  [K in keyof T]: InferMethodRequest<T[K] extends MethodRequestSchema ? T[K] : undefined>;
+};
+
+/**
+ * Infer all response schemas
+ */
+type InferContractResponse<T extends ContractResponseSchema> = {
+  [K in keyof T]: T[K] extends z.ZodTypeAny ? z.infer<T[K]> : never;
+};
+
+/**
+ * Infer full contract types
+ *
+ * @example
+ * ```typescript
+ * const contract = Mandu.contract({
+ *   request: {
+ *     GET: { query: z.object({ page: z.number() }) },
+ *     POST: { body: z.object({ name: z.string() }) },
+ *   },
+ *   response: {
+ *     200: z.object({ data: z.array(z.string()) }),
+ *   },
+ * });
+ *
+ * type Contract = InferContract<typeof contract>;
+ * // {
+ * //   request: {
+ * //     GET: { query: { page: number }, body: undefined, params: undefined, headers: undefined },
+ * //     POST: { query: undefined, body: { name: string }, params: undefined, headers: undefined },
+ * //   },
+ * //   response: {
+ * //     200: { data: string[] },
+ * //   },
+ * // }
+ * ```
+ */
+export type InferContract<T extends ContractSchema> = {
+  request: InferContractRequest<T["request"]>;
+  response: InferContractResponse<T["response"]>;
+  description: T["description"];
+  tags: T["tags"];
+};
+
+/**
+ * Extract query type for a specific method
+ */
+export type InferQuery<
+  T extends ContractSchema,
+  M extends keyof T["request"]
+> = T["request"][M] extends MethodRequestSchema
+  ? T["request"][M]["query"] extends z.ZodTypeAny
+    ? z.infer<T["request"][M]["query"]>
+    : undefined
+  : undefined;
+
+/**
+ * Extract body type for a specific method
+ */
+export type InferBody<
+  T extends ContractSchema,
+  M extends keyof T["request"]
+> = T["request"][M] extends MethodRequestSchema
+  ? T["request"][M]["body"] extends z.ZodTypeAny
+    ? z.infer<T["request"][M]["body"]>
+    : undefined
+  : undefined;
+
+/**
+ * Extract params type for a specific method
+ */
+export type InferParams<
+  T extends ContractSchema,
+  M extends keyof T["request"]
+> = T["request"][M] extends MethodRequestSchema
+  ? T["request"][M]["params"] extends z.ZodTypeAny
+    ? z.infer<T["request"][M]["params"]>
+    : undefined
+  : undefined;
+
+/**
+ * Extract response type for a specific status code
+ */
+export type InferResponse<
+  T extends ContractSchema,
+  S extends keyof T["response"]
+> = T["response"][S] extends z.ZodTypeAny ? z.infer<T["response"][S]> : never;
+
+/**
+ * Helper type to get all defined methods in a contract
+ */
+export type ContractMethods<T extends ContractSchema> = Extract<
+  keyof T["request"],
+  "GET" | "POST" | "PUT" | "PATCH" | "DELETE"
+>;
+
+/**
+ * Helper type to get all defined status codes in a contract
+ */
+export type ContractStatusCodes<T extends ContractSchema> = keyof T["response"];

package/src/contract/validator.ts

@@ -0,0 +1,257 @@
+/**
+ * Mandu Contract Validator
+ * 런타임 요청/응답 검증
+ */
+
+import type { z } from "zod";
+import type {
+  ContractSchema,
+  ContractValidationResult,
+  ContractValidationError,
+  ContractValidationIssue,
+  MethodRequestSchema,
+} from "./schema";
+
+/**
+ * Parse query string from URL
+ */
+function parseQueryString(url: string): Record<string, string | string[]> {
+  const result: Record<string, string | string[]> = {};
+  try {
+    const urlObj = new URL(url);
+    urlObj.searchParams.forEach((value, key) => {
+      const existing = result[key];
+      if (existing !== undefined) {
+        if (Array.isArray(existing)) {
+          existing.push(value);
+        } else {
+          result[key] = [existing, value];
+        }
+      } else {
+        result[key] = value;
+      }
+    });
+  } catch {
+    // Invalid URL, return empty object
+  }
+  return result;
+}
+
+/**
+ * Convert Zod error to validation issues
+ */
+function zodErrorToIssues(error: z.ZodError): ContractValidationIssue[] {
+  return error.errors.map((issue) => ({
+    path: issue.path,
+    message: issue.message,
+    code: issue.code,
+  }));
+}
+
+/**
+ * Contract Validator
+ * Validates requests and responses against contract schemas
+ */
+export class ContractValidator {
+  constructor(private contract: ContractSchema) {}
+
+  /**
+   * Validate incoming request against contract
+   * @param req - The incoming request
+   * @param method - HTTP method
+   * @param pathParams - Path parameters extracted by router
+   */
+  async validateRequest(
+    req: Request,
+    method: string,
+    pathParams: Record<string, string> = {}
+  ): Promise<ContractValidationResult> {
+    const methodSchema = this.contract.request[method] as MethodRequestSchema | undefined;
+    if (!methodSchema) {
+      // No schema defined for this method, pass through
+      return { success: true };
+    }
+
+    const errors: ContractValidationError[] = [];
+
+    // Validate query parameters
+    if (methodSchema.query) {
+      const query = parseQueryString(req.url);
+      const result = methodSchema.query.safeParse(query);
+      if (!result.success) {
+        errors.push({
+          type: "query",
+          issues: zodErrorToIssues(result.error),
+        });
+      }
+    }
+
+    // Validate path parameters
+    if (methodSchema.params) {
+      const result = methodSchema.params.safeParse(pathParams);
+      if (!result.success) {
+        errors.push({
+          type: "params",
+          issues: zodErrorToIssues(result.error),
+        });
+      }
+    }
+
+    // Validate headers
+    if (methodSchema.headers) {
+      const headers: Record<string, string> = {};
+      req.headers.forEach((value, key) => {
+        headers[key.toLowerCase()] = value;
+      });
+      const result = methodSchema.headers.safeParse(headers);
+      if (!result.success) {
+        errors.push({
+          type: "headers",
+          issues: zodErrorToIssues(result.error),
+        });
+      }
+    }
+
+    // Validate body (for methods that have body)
+    if (methodSchema.body) {
+      try {
+        const contentType = req.headers.get("content-type") || "";
+        let body: unknown;
+
+        if (contentType.includes("application/json")) {
+          body = await req.clone().json();
+        } else if (contentType.includes("application/x-www-form-urlencoded")) {
+          const formData = await req.clone().formData();
+          body = Object.fromEntries(formData.entries());
+        } else if (contentType.includes("multipart/form-data")) {
+          const formData = await req.clone().formData();
+          body = Object.fromEntries(formData.entries());
+        } else {
+          // Try JSON as default
+          try {
+            body = await req.clone().json();
+          } catch {
+            body = await req.clone().text();
+          }
+        }
+
+        const result = methodSchema.body.safeParse(body);
+        if (!result.success) {
+          errors.push({
+            type: "body",
+            issues: zodErrorToIssues(result.error),
+          });
+        }
+      } catch (error) {
+        errors.push({
+          type: "body",
+          issues: [
+            {
+              path: [],
+              message: `Failed to parse request body: ${error instanceof Error ? error.message : "Unknown error"}`,
+              code: "invalid_type",
+            },
+          ],
+        });
+      }
+    }
+
+    if (errors.length > 0) {
+      return { success: false, errors };
+    }
+
+    return { success: true };
+  }
+
+  /**
+   * Validate response against contract (development mode)
+   * @param responseBody - The response body (already parsed)
+   * @param statusCode - HTTP status code
+   */
+  validateResponse(responseBody: unknown, statusCode: number): ContractValidationResult {
+    const responseSchema = this.contract.response[statusCode];
+    if (!responseSchema) {
+      // No schema defined for this status code, pass through
+      return { success: true };
+    }
+
+    const result = responseSchema.safeParse(responseBody);
+    if (!result.success) {
+      return {
+        success: false,
+        errors: [
+          {
+            type: "response",
+            issues: zodErrorToIssues(result.error),
+          },
+        ],
+      };
+    }
+
+    return { success: true, data: result.data };
+  }
+
+  /**
+   * Get all defined methods in this contract
+   */
+  getMethods(): string[] {
+    return Object.keys(this.contract.request).filter((key) =>
+      ["GET", "POST", "PUT", "PATCH", "DELETE"].includes(key)
+    );
+  }
+
+  /**
+   * Get all defined status codes in this contract
+   */
+  getStatusCodes(): number[] {
+    return Object.keys(this.contract.response)
+      .map((k) => parseInt(k, 10))
+      .filter((n) => !isNaN(n));
+  }
+
+  /**
+   * Check if method has request schema
+   */
+  hasMethodSchema(method: string): boolean {
+    return !!this.contract.request[method];
+  }
+
+  /**
+   * Check if status code has response schema
+   */
+  hasResponseSchema(statusCode: number): boolean {
+    return !!this.contract.response[statusCode];
+  }
+
+  /**
+   * Get the underlying contract schema
+   */
+  getSchema(): ContractSchema {
+    return this.contract;
+  }
+}
+
+/**
+ * Format validation errors for HTTP response
+ */
+export function formatValidationErrors(errors: ContractValidationError[]): {
+  error: string;
+  details: Array<{
+    type: string;
+    issues: Array<{
+      path: string;
+      message: string;
+    }>;
+  }>;
+} {
+  return {
+    error: "Validation Error",
+    details: errors.map((e) => ({
+      type: e.type,
+      issues: e.issues.map((issue) => ({
+        path: issue.path.join(".") || "(root)",
+        message: issue.message,
+      })),
+    })),
+  };
+}

package/src/filling/filling.ts

@@ -5,6 +5,7 @@
 
 import { ManduContext, NEXT_SYMBOL, ValidationError } from "./context";
 import { ErrorClassifier, formatErrorResponse, ErrorCode } from "../error";
+import { createContract, type ContractDefinition, type ContractInstance } from "../contract";
 
 /** Handler function type */
 export type Handler = (ctx: ManduContext) => Response | Promise<Response>;
@@ -318,6 +319,55 @@ export const Mandu = {
     return new ManduFilling<TLoaderData>();
   },
 
+  /**
+   * Create an API contract (schema-first definition)
+   *
+   * Contract-first 방식으로 API 스키마를 정의합니다.
+   * 정의된 스키마는 다음에 활용됩니다:
+   * - TypeScript 타입 추론 (Slot에서 자동 완성)
+   * - 런타임 요청/응답 검증
+   * - OpenAPI 문서 자동 생성
+   * - Guard의 Contract-Slot 일관성 검사
+   *
+   * @example
+   * ```typescript
+   * import { z } from "zod";
+   * import { Mandu } from "@mandujs/core";
+   *
+   * const UserSchema = z.object({
+   *   id: z.string().uuid(),
+   *   email: z.string().email(),
+   *   name: z.string().min(2),
+   * });
+   *
+   * export default Mandu.contract({
+   *   description: "사용자 관리 API",
+   *   tags: ["users"],
+   *
+   *   request: {
+   *     GET: {
+   *       query: z.object({
+   *         page: z.coerce.number().default(1),
+   *         limit: z.coerce.number().default(10),
+   *       }),
+   *     },
+   *     POST: {
+   *       body: UserSchema.omit({ id: true }),
+   *     },
+   *   },
+   *
+   *   response: {
+   *     200: z.object({ data: z.array(UserSchema) }),
+   *     201: z.object({ data: UserSchema }),
+   *     400: z.object({ error: z.string() }),
+   *   },
+   * });
+   * ```
+   */
+  contract<T extends ContractDefinition>(definition: T): T & ContractInstance {
+    return createContract(definition);
+  },
+
   /**
    * Create context manually (for testing)
    */