@mandujs/core 0.9.39 → 0.9.40

package/README.ko.md

@@ -133,6 +133,33 @@ if (!result.passed) {
 | `COMPONENT_NOT_FOUND` | 컴포넌트 파일 없음 | ❌ |
 | `SLOT_NOT_FOUND` | slot 파일 없음 | ✅ |
 
+## Contract 모듈
+
+Zod 기반 계약(Contract) 정의 및 타입 안전 클라이언트 생성.
+
+```typescript
+import { Mandu } from "@mandujs/core";
+import { z } from "zod";
+
+const userContract = Mandu.contract({
+  request: {
+    GET: { query: z.object({ id: z.string() }) },
+    POST: { body: z.object({ name: z.string() }) },
+  },
+  response: {
+    200: z.object({ data: z.any() }),
+    400: z.object({ error: z.string() }),
+  },
+});
+
+// 클라이언트에 노출할 스키마만 선택
+const clientContract = Mandu.clientContract(userContract, {
+  request: { POST: { body: true } },
+  response: [200],
+  includeErrors: true,
+});
+```
+
 ## Runtime 모듈
 
 서버 시작 및 라우팅.

package/README.md

@@ -160,7 +160,7 @@ listPresets().forEach(p => console.log(p.name, p.description));
 
 | Preset | Layers | Use Case |
 |--------|--------|----------|
-| `mandu` | app, pages, widgets, features, entities, api, application, domain, infra, core, shared | Fullstack (default) |
+| `mandu` | client/*, shared/(contracts, types, utils/*, schema, env), server/* | Fullstack (default) |
 | `fsd` | app, pages, widgets, features, entities, shared | Frontend |
 | `clean` | api, application, domain, infra, shared | Backend |
 | `hexagonal` | adapters, ports, application, domain | DDD |
@@ -295,10 +295,26 @@ const handlers = Mandu.handler(userContract, {
   POST: (ctx) => ({ data: createUser(ctx.body) })
 });
 
-// Type-safe client
-const client = Mandu.client(userContract, { baseUrl: "/api/users" });
-const result = await client.GET({ query: { id: "123" } });
-```
+  // Type-safe client
+  const client = Mandu.client(userContract, { baseUrl: "/api/users" });
+  const result = await client.GET({ query: { id: "123" } });
+  ```
+
+  ### Client-safe Contract
+
+  Limit schemas exposed to client-side usage (forms/UI validation):
+
+  ```typescript
+  const clientContract = Mandu.clientContract(userContract, {
+    request: {
+      POST: { body: true },
+    },
+    response: [201],
+    includeErrors: true,
+  });
+
+  const client = Mandu.client(clientContract, { baseUrl: "/api/users" });
+  ```
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.9.39",
+  "version": "0.9.40",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/config/index.ts

@@ -0,0 +1 @@
+export * from "./mandu";

package/src/config/mandu.ts

@@ -0,0 +1,60 @@
+import path from "path";
+import fs from "fs/promises";
+
+export type GuardRuleSeverity = "error" | "warn" | "off";
+
+export interface ManduConfig {
+  guard?: {
+    rules?: Record<string, GuardRuleSeverity>;
+    contractRequired?: GuardRuleSeverity;
+  };
+}
+
+const CONFIG_FILES = [
+  "mandu.config.ts",
+  "mandu.config.js",
+  "mandu.config.json",
+  path.join(".mandu", "guard.json"),
+];
+
+function coerceConfig(raw: unknown, source: string): ManduConfig {
+  if (!raw || typeof raw !== "object") return {};
+
+  // .mandu/guard.json can be guard-only
+  if (source.endsWith("guard.json") && !("guard" in (raw as Record<string, unknown>))) {
+    return { guard: raw as ManduConfig["guard"] };
+  }
+
+  return raw as ManduConfig;
+}
+
+export async function loadManduConfig(rootDir: string): Promise<ManduConfig> {
+  for (const fileName of CONFIG_FILES) {
+    const filePath = path.join(rootDir, fileName);
+    try {
+      await fs.access(filePath);
+    } catch {
+      continue;
+    }
+
+    if (fileName.endsWith(".json")) {
+      try {
+        const content = await Bun.file(filePath).text();
+        const parsed = JSON.parse(content);
+        return coerceConfig(parsed, fileName);
+      } catch {
+        return {};
+      }
+    }
+
+    try {
+      const module = await import(filePath);
+      const raw = module?.default ?? module;
+      return coerceConfig(raw, fileName);
+    } catch {
+      return {};
+    }
+  }
+
+  return {};
+}

package/src/contract/client-safe.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { Mandu, createClientContract } from "../index";
+
+describe("Client-safe contract", () => {
+  const contract = Mandu.contract({
+    request: {
+      GET: {
+        query: z.object({ id: z.string() }),
+      },
+      POST: {
+        body: z.object({ name: z.string() }),
+      },
+    },
+    response: {
+      200: z.object({ ok: z.boolean() }),
+      201: z.object({ id: z.string() }),
+      400: z.object({ error: z.string() }),
+    },
+  });
+
+  it("should pick only selected schemas", () => {
+    const clientContract = createClientContract(contract, {
+      request: {
+        POST: { body: true },
+      },
+      response: [201],
+      includeErrors: true,
+    });
+
+    expect(clientContract.request.GET).toBeUndefined();
+    expect(clientContract.request.POST?.body).toBeDefined();
+    expect(clientContract.response[200]).toBeUndefined();
+    expect(clientContract.response[201]).toBeDefined();
+    expect(clientContract.response[400]).toBeDefined();
+  });
+
+  it("should return original contract when no options are provided", () => {
+    const clientContract = createClientContract(contract);
+    expect(clientContract).toBe(contract);
+  });
+});

package/src/contract/client-safe.ts

@@ -0,0 +1,114 @@
+/**
+ * Mandu Client-safe Contract Utilities
+ * Reduce contract exposure for client usage (forms, UI validation)
+ */
+
+import type {
+  ContractSchema,
+  ContractMethod,
+  MethodRequestSchema,
+  ClientSafeOptions,
+  ContractRequestSchema,
+  ContractResponseSchema,
+} from "./schema";
+
+const ERROR_STATUS_CODES = [400, 401, 403, 404, 500] as const;
+
+function normalizeResponseSelection(
+  selection: ClientSafeOptions["response"]
+): number[] {
+  if (!selection) return [];
+  if (Array.isArray(selection)) return selection;
+
+  const result: number[] = [];
+  for (const [code, enabled] of Object.entries(selection)) {
+    if (enabled) {
+      const num = Number(code);
+      if (!Number.isNaN(num)) {
+        result.push(num);
+      }
+    }
+  }
+  return result;
+}
+
+function pickRequestSchema(
+  methodSchema: MethodRequestSchema,
+  selection: NonNullable<ClientSafeOptions["request"]>[ContractMethod]
+): MethodRequestSchema | undefined {
+  if (!selection) return undefined;
+
+  const picked: MethodRequestSchema = {};
+
+  if (selection.query && methodSchema.query) {
+    picked.query = methodSchema.query;
+  }
+  if (selection.body && methodSchema.body) {
+    picked.body = methodSchema.body;
+  }
+  if (selection.params && methodSchema.params) {
+    picked.params = methodSchema.params;
+  }
+  if (selection.headers && methodSchema.headers) {
+    picked.headers = methodSchema.headers;
+  }
+
+  return Object.keys(picked).length > 0 ? picked : undefined;
+}
+
+/**
+ * Create a client-safe contract by selecting exposed schemas.
+ * If options are omitted and contract.clientSafe is not defined,
+ * the original contract is returned (with a warning).
+ */
+export function createClientContract<T extends ContractSchema>(
+  contract: T,
+  options?: ClientSafeOptions
+): ContractSchema {
+  const resolved = options ?? contract.clientSafe;
+
+  if (!resolved) {
+    console.warn(
+      "[Mandu] clientContract: no clientSafe options provided. Returning original contract."
+    );
+    return contract;
+  }
+
+  const requestSelection = resolved.request ?? {};
+  const responseSelection = normalizeResponseSelection(resolved.response);
+  const safeRequest: ContractRequestSchema = {};
+  const safeResponse: ContractResponseSchema = {};
+
+  for (const method of Object.keys(requestSelection) as ContractMethod[]) {
+    const methodSchema = contract.request[method] as MethodRequestSchema | undefined;
+    if (!methodSchema) continue;
+
+    const picked = pickRequestSchema(methodSchema, requestSelection[method]);
+    if (picked) {
+      safeRequest[method] = picked;
+    }
+  }
+
+  const allowedResponses = new Set(responseSelection);
+
+  if (resolved.includeErrors) {
+    for (const code of ERROR_STATUS_CODES) {
+      if (contract.response[code]) {
+        allowedResponses.add(code);
+      }
+    }
+  }
+
+  for (const code of allowedResponses) {
+    const schema = contract.response[code];
+    if (schema) {
+      safeResponse[code] = schema;
+    }
+  }
+
+  return {
+    ...contract,
+    request: safeRequest,
+    response: safeResponse,
+  };
+}

package/src/contract/client.ts

@@ -8,11 +8,12 @@
  */
 
 import type { z } from "zod";
-import type {
-  ContractSchema,
-  ContractMethod,
-  MethodRequestSchema,
-} from "./schema";
+import type {
+  ContractSchema,
+  ContractMethod,
+  MethodRequestSchema,
+} from "./schema";
+import type { InferResponseSchema } from "./types";
 
 /**
  * Client options for making requests
@@ -72,12 +73,12 @@ type InferRequestOptions<T extends MethodRequestSchema | undefined> =
 /**
  * Infer success response from contract
  */
-type InferSuccessResponse<TResponse extends ContractSchema["response"]> =
-  TResponse[200] extends z.ZodTypeAny
-    ? z.infer<TResponse[200]>
-    : TResponse[201] extends z.ZodTypeAny
-      ? z.infer<TResponse[201]>
-      : unknown;
+type InferSuccessResponse<TResponse extends ContractSchema["response"]> =
+  InferResponseSchema<TResponse[200]> extends never
+    ? InferResponseSchema<TResponse[201]> extends never
+      ? unknown
+      : InferResponseSchema<TResponse[201]>
+    : InferResponseSchema<TResponse[200]>;
 
 /**
  * Contract client method

package/src/contract/handler.ts

@@ -5,12 +5,13 @@
  * Elysia 패턴 채택: Contract → Handler 타입 자동 추론
  */
 
-import type { z } from "zod";
-import type {
-  ContractSchema,
-  ContractMethod,
-  MethodRequestSchema,
-} from "./schema";
+import type { z } from "zod";
+import type {
+  ContractSchema,
+  ContractMethod,
+  MethodRequestSchema,
+} from "./schema";
+import type { InferResponseSchema } from "./types";
 
 /**
  * Typed request context for a handler
@@ -61,11 +62,9 @@ export type HandlerFn<TContext, TResponse> = (
 /**
  * Infer response type union from contract response schema
  */
-type InferResponseUnion<TResponse extends ContractSchema["response"]> = {
-  [K in keyof TResponse]: TResponse[K] extends z.ZodTypeAny
-    ? z.infer<TResponse[K]>
-    : never;
-}[keyof TResponse];
+type InferResponseUnion<TResponse extends ContractSchema["response"]> = {
+  [K in keyof TResponse]: InferResponseSchema<TResponse[K]>;
+}[keyof TResponse];
 
 /**
  * Handler definition for all methods in a contract

package/src/contract/index.ts

@@ -10,15 +10,18 @@
 
 export * from "./schema";
 export * from "./types";
-export * from "./validator";
-export * from "./handler";
-export * from "./client";
-export * from "./normalize";
-
-import type { ContractDefinition, ContractInstance, ContractSchema } from "./schema";
-import type { ContractHandlers, RouteDefinition } from "./handler";
-import { defineHandler, defineRoute } from "./handler";
-import { createClient, contractFetch, type ClientOptions } from "./client";
+export * from "./validator";
+export * from "./handler";
+export * from "./client";
+export * from "./normalize";
+export * from "./registry";
+export * from "./client-safe";
+
+import type { ContractDefinition, ContractInstance, ContractSchema } from "./schema";
+import type { ContractHandlers, RouteDefinition } from "./handler";
+import { defineHandler, defineRoute } from "./handler";
+import { createClient, contractFetch, type ClientOptions } from "./client";
+import { createClientContract } from "./client-safe";
 
 /**
  * Create a Mandu API Contract
@@ -120,7 +123,7 @@ export function createContract<T extends ContractDefinition>(definition: T): T &
  * Contract-specific Mandu functions
  * Note: Use `ManduContract` to avoid conflict with other Mandu exports
  */
-export const ManduContract = {
+export const ManduContract = {
   /**
    * Create a typed Contract
    * Contract 스키마 정의 및 타입 추론
@@ -162,9 +165,9 @@ export const ManduContract = {
    */
   route: defineRoute,
 
-  /**
-   * Create a type-safe API client from contract
-   * Contract 기반 타입 안전 클라이언트 생성
+  /**
+   * Create a type-safe API client from contract
+   * Contract 기반 타입 안전 클라이언트 생성
    *
    * @example
    * ```typescript
@@ -177,7 +180,13 @@ export const ManduContract = {
    * const newUser = await client.POST({ body: { name: "Alice" } });
    * ```
    */
-  client: createClient,
+  client: createClient,
+
+  /**
+   * Create a client-safe contract
+   * Client에서 노출할 스키마만 선택
+   */
+  clientContract: createClientContract,
 
   /**
    * Single type-safe fetch call
@@ -190,8 +199,8 @@ export const ManduContract = {
    * });
    * ```
    */
-  fetch: contractFetch,
-} as const;
+  fetch: contractFetch,
+} as const;
 
 /**
  * Alias for backward compatibility within contract module

package/src/contract/registry.test.ts

@@ -0,0 +1,206 @@
+import { describe, it, expect } from "vitest";
+import { diffContractRegistry, type ContractRegistry } from "./registry";
+
+describe("Contract registry diff", () => {
+  it("should mark added optional fields as minor", () => {
+    const prev: ContractRegistry = {
+      version: 1,
+      generatedAt: "",
+      contracts: [
+        {
+          id: "users",
+          routeId: "users",
+          file: "spec/contracts/users.contract.ts",
+          methods: ["POST"],
+          request: {
+            POST: { query: false, body: true, params: false, headers: false },
+          },
+          response: [201],
+          hash: null,
+          schemas: {
+            request: {
+              POST: {
+                body: {
+                  type: "object",
+                  keys: ["name"],
+                  required: ["name"],
+                },
+              },
+            },
+            response: {
+              201: {
+                type: "object",
+                keys: ["id"],
+                required: ["id"],
+              },
+            },
+          },
+        },
+      ],
+    };
+
+    const next: ContractRegistry = {
+      version: 1,
+      generatedAt: "",
+      contracts: [
+        {
+          id: "users",
+          routeId: "users",
+          file: "spec/contracts/users.contract.ts",
+          methods: ["POST"],
+          request: {
+            POST: { query: false, body: true, params: false, headers: false },
+          },
+          response: [201],
+          hash: null,
+          schemas: {
+            request: {
+              POST: {
+                body: {
+                  type: "object",
+                  keys: ["age", "name"],
+                  required: ["name"],
+                },
+              },
+            },
+            response: {
+              201: {
+                type: "object",
+                keys: ["id"],
+                required: ["id"],
+              },
+            },
+          },
+        },
+      ],
+    };
+
+    const diff = diffContractRegistry(prev, next);
+    expect(diff.summary.major).toBe(0);
+    expect(diff.summary.minor).toBeGreaterThan(0);
+  });
+
+  it("should mark required field addition as major", () => {
+    const prev: ContractRegistry = {
+      version: 1,
+      generatedAt: "",
+      contracts: [
+        {
+          id: "users",
+          routeId: "users",
+          file: "spec/contracts/users.contract.ts",
+          methods: ["POST"],
+          request: {
+            POST: { query: false, body: true, params: false, headers: false },
+          },
+          response: [201],
+          hash: null,
+          schemas: {
+            request: {
+              POST: {
+                body: {
+                  type: "object",
+                  keys: ["name", "age"],
+                  required: ["name"],
+                },
+              },
+            },
+          },
+        },
+      ],
+    };
+
+    const next: ContractRegistry = {
+      version: 1,
+      generatedAt: "",
+      contracts: [
+        {
+          id: "users",
+          routeId: "users",
+          file: "spec/contracts/users.contract.ts",
+          methods: ["POST"],
+          request: {
+            POST: { query: false, body: true, params: false, headers: false },
+          },
+          response: [201],
+          hash: null,
+          schemas: {
+            request: {
+              POST: {
+                body: {
+                  type: "object",
+                  keys: ["name", "age"],
+                  required: ["name", "age"],
+                },
+              },
+            },
+          },
+        },
+      ],
+    };
+
+    const diff = diffContractRegistry(prev, next);
+    expect(diff.summary.major).toBeGreaterThan(0);
+  });
+
+  it("should mark enum value removal as major", () => {
+    const prev: ContractRegistry = {
+      version: 1,
+      generatedAt: "",
+      contracts: [
+        {
+          id: "users",
+          routeId: "users",
+          file: "spec/contracts/users.contract.ts",
+          methods: ["GET"],
+          request: {
+            GET: { query: true, body: false, params: false, headers: false },
+          },
+          response: [200],
+          hash: null,
+          schemas: {
+            request: {
+              GET: {
+                query: {
+                  type: "enum",
+                  values: ["active", "inactive"],
+                },
+              },
+            },
+          },
+        },
+      ],
+    };
+
+    const next: ContractRegistry = {
+      version: 1,
+      generatedAt: "",
+      contracts: [
+        {
+          id: "users",
+          routeId: "users",
+          file: "spec/contracts/users.contract.ts",
+          methods: ["GET"],
+          request: {
+            GET: { query: true, body: false, params: false, headers: false },
+          },
+          response: [200],
+          hash: null,
+          schemas: {
+            request: {
+              GET: {
+                query: {
+                  type: "enum",
+                  values: ["active"],
+                },
+              },
+            },
+          },
+        },
+      ],
+    };
+
+    const diff = diffContractRegistry(prev, next);
+    expect(diff.summary.major).toBeGreaterThan(0);
+  });
+});