@mandujs/core 0.30.0 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",
@@ -13,6 +13,9 @@
     "./auth/reset": "./src/auth/reset.ts",
     "./auth/verification": "./src/auth/verification.ts",
     "./client": "./src/client/index.ts",
+    "./client/rpc": "./src/client/rpc.ts",
+    "./contract": "./src/contract/index.ts",
+    "./contract/rpc": "./src/contract/rpc.ts",
     "./content": "./src/content/index.ts",
     "./content/prebuild": "./src/content/prebuild.ts",
     "./content/collection": "./src/content/collection.ts",
@@ -33,6 +36,7 @@
     "./testing": "./src/testing/index.ts",
     "./plugins": "./src/plugins/index.ts",
     "./error": "./src/error/index.ts",
+    "./i18n": "./src/i18n/index.ts",
     "./id": "./src/id/index.ts",
     "./observability": "./src/observability/index.ts",
     "./perf": "./src/perf/index.ts",
@@ -40,6 +44,8 @@
     "./routes": "./src/routes/index.ts",
     "./scheduler": "./src/scheduler/index.ts",
     "./storage/s3": "./src/storage/s3/index.ts",
+    "./guard/define-rule": "./src/guard/define-rule.ts",
+    "./guard/rule-presets": "./src/guard/rule-presets.ts",
     "./bundler/prerender": "./src/bundler/prerender.ts",
     "./bundler/safe-build": "./src/bundler/safe-build.ts",
     "./bundler/hmr-types": "./src/bundler/hmr-types.ts",

package/src/client/index.ts

@@ -112,7 +112,17 @@ export { Link, NavLink, type LinkProps, type NavLinkProps } from "./Link";
 export { Form, type FormProps, type FormState } from "./Form";
 
 // RPC Client
-export { createClient, RpcError, type RpcMethods, type RpcRequestOptions, type RpcClientOptions } from "./rpc";
+export {
+  createClient,
+  RpcError,
+  type RpcMethods,
+  type RpcRequestOptions,
+  type RpcClientOptions,
+  // Phase 18.κ — typed RPC proxy
+  createRpcClient,
+  RpcCallError,
+  type CreateRpcClientOptions,
+} from "./rpc";
 
 // useFetch Composable
 export { useFetch, type UseFetchOptions, type UseFetchReturn } from "./use-fetch";

package/src/client/rpc.ts

@@ -1,140 +1,293 @@
-/**
- * Mandu RPC Client
- * Contract 정의에서 타입 안전한 API 클라이언트 생성
- */
-
-// ========== Types ==========
-
-/** RPC 클라이언트 에러 */
-export class RpcError extends Error {
-  constructor(
-    public readonly status: number,
-    public readonly body: unknown
-  ) {
-    super(`API Error ${status}`);
-    this.name = "RpcError";
-  }
-}
-
-export interface RpcRequestOptions {
-  query?: Record<string, unknown>;
-  body?: unknown;
-  params?: Record<string, string>;
-  headers?: Record<string, string>;
-  signal?: AbortSignal;
-}
-
-export interface RpcClientOptions {
-  /** API base URL (기본: 현재 origin) */
-  baseUrl?: string;
-  /** 공통 헤더 */
-  headers?: Record<string, string>;
-  /** 커스텀 fetch (테스트용) */
-  fetch?: typeof globalThis.fetch;
-}
-
-// ========== Implementation ==========
-
-/**
- * Contract 기반 타입 안전 RPC 클라이언트 생성
- *
- * @example
- * ```typescript
- * import { createClient } from "@mandujs/core/client";
- * import type todoContract from "../spec/contracts/api-todos.contract";
- *
- * const api = createClient<typeof todoContract>("/api/todos");
- *
- * // 타입 추론 동작
- * const { todos } = await api.get({ query: { page: 2 } });
- * const { id } = await api.post({ body: { title: "New" } });
- * ```
- */
-export function createClient<TContract = unknown>(
-  path: string,
-  options?: RpcClientOptions
-): RpcMethods {
-  const baseFetch = options?.fetch ?? globalThis.fetch;
-  const baseUrl = options?.baseUrl ?? "";
-  const baseHeaders = options?.headers ?? {};
-
-  function makeRequest(method: string) {
-    return async (input?: RpcRequestOptions): Promise<unknown> => {
-      const url = new URL(`${baseUrl}${path}`, typeof window !== "undefined" ? window.location.origin : "http://localhost");
-
-      // URL 파라미터 치환
-      if (input?.params) {
-        let resolvedPath = url.pathname;
-        for (const [key, value] of Object.entries(input.params)) {
-          resolvedPath = resolvedPath.replace(`:${key}`, encodeURIComponent(value));
-        }
-        // 미해결 파라미터 검출
-        if (resolvedPath.includes(":")) {
-          throw new RpcError(0, `Unresolved path params in "${resolvedPath}". Check your params object.`);
-        }
-        url.pathname = resolvedPath;
-      }
-
-      // Query 파라미터
-      if (input?.query) {
-        for (const [key, value] of Object.entries(input.query)) {
-          if (value !== undefined && value !== null) {
-            url.searchParams.set(key, String(value));
-          }
-        }
-      }
-
-      const headers: Record<string, string> = {
-        ...baseHeaders,
-        ...input?.headers,
-        "Accept": "application/json",
-      };
-
-      const fetchOptions: RequestInit = {
-        method: method.toUpperCase(),
-        headers,
-        signal: input?.signal,
-      };
-
-      // Body (GET/HEAD 제외)
-      if (input?.body && method !== "GET" && method !== "HEAD") {
-        fetchOptions.body = JSON.stringify(input.body);
-        headers["Content-Type"] = "application/json";
-      }
-
-      const response = await baseFetch(url.toString(), fetchOptions);
-
-      if (!response.ok) {
-        let body: unknown;
-        try {
-          body = await response.json();
-        } catch {
-          body = await response.text().catch(() => null);
-        }
-        throw new RpcError(response.status, body);
-      }
-
-      const contentType = response.headers.get("content-type") ?? "";
-      if (contentType.includes("application/json")) {
-        return response.json();
-      }
-      return response.text();
-    };
-  }
-
-  return {
-    get: makeRequest("GET"),
-    post: makeRequest("POST"),
-    put: makeRequest("PUT"),
-    patch: makeRequest("PATCH"),
-    delete: makeRequest("DELETE"),
-  };
-}
-
-export interface RpcMethods {
-  get: (input?: RpcRequestOptions) => Promise<unknown>;
-  post: (input?: RpcRequestOptions) => Promise<unknown>;
-  put: (input?: RpcRequestOptions) => Promise<unknown>;
-  patch: (input?: RpcRequestOptions) => Promise<unknown>;
-  delete: (input?: RpcRequestOptions) => Promise<unknown>;
-}
+/**
+ * Mandu RPC Client
+ * Contract 정의에서 타입 안전한 API 클라이언트 생성
+ */
+
+// ========== Types ==========
+
+/** RPC 클라이언트 에러 */
+export class RpcError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly body: unknown
+  ) {
+    super(`API Error ${status}`);
+    this.name = "RpcError";
+  }
+}
+
+export interface RpcRequestOptions {
+  query?: Record<string, unknown>;
+  body?: unknown;
+  params?: Record<string, string>;
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+}
+
+export interface RpcClientOptions {
+  /** API base URL (기본: 현재 origin) */
+  baseUrl?: string;
+  /** 공통 헤더 */
+  headers?: Record<string, string>;
+  /** 커스텀 fetch (테스트용) */
+  fetch?: typeof globalThis.fetch;
+}
+
+// ========== Implementation ==========
+
+/**
+ * Contract 기반 타입 안전 RPC 클라이언트 생성
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from "@mandujs/core/client";
+ * import type todoContract from "../spec/contracts/api-todos.contract";
+ *
+ * const api = createClient<typeof todoContract>("/api/todos");
+ *
+ * // 타입 추론 동작
+ * const { todos } = await api.get({ query: { page: 2 } });
+ * const { id } = await api.post({ body: { title: "New" } });
+ * ```
+ */
+export function createClient<TContract = unknown>(
+  path: string,
+  options?: RpcClientOptions
+): RpcMethods {
+  const baseFetch = options?.fetch ?? globalThis.fetch;
+  const baseUrl = options?.baseUrl ?? "";
+  const baseHeaders = options?.headers ?? {};
+
+  function makeRequest(method: string) {
+    return async (input?: RpcRequestOptions): Promise<unknown> => {
+      const url = new URL(`${baseUrl}${path}`, typeof window !== "undefined" ? window.location.origin : "http://localhost");
+
+      // URL 파라미터 치환
+      if (input?.params) {
+        let resolvedPath = url.pathname;
+        for (const [key, value] of Object.entries(input.params)) {
+          resolvedPath = resolvedPath.replace(`:${key}`, encodeURIComponent(value));
+        }
+        // 미해결 파라미터 검출
+        if (resolvedPath.includes(":")) {
+          throw new RpcError(0, `Unresolved path params in "${resolvedPath}". Check your params object.`);
+        }
+        url.pathname = resolvedPath;
+      }
+
+      // Query 파라미터
+      if (input?.query) {
+        for (const [key, value] of Object.entries(input.query)) {
+          if (value !== undefined && value !== null) {
+            url.searchParams.set(key, String(value));
+          }
+        }
+      }
+
+      const headers: Record<string, string> = {
+        ...baseHeaders,
+        ...input?.headers,
+        "Accept": "application/json",
+      };
+
+      const fetchOptions: RequestInit = {
+        method: method.toUpperCase(),
+        headers,
+        signal: input?.signal,
+      };
+
+      // Body (GET/HEAD 제외)
+      if (input?.body && method !== "GET" && method !== "HEAD") {
+        fetchOptions.body = JSON.stringify(input.body);
+        headers["Content-Type"] = "application/json";
+      }
+
+      const response = await baseFetch(url.toString(), fetchOptions);
+
+      if (!response.ok) {
+        let body: unknown;
+        try {
+          body = await response.json();
+        } catch {
+          body = await response.text().catch(() => null);
+        }
+        throw new RpcError(response.status, body);
+      }
+
+      const contentType = response.headers.get("content-type") ?? "";
+      if (contentType.includes("application/json")) {
+        return response.json();
+      }
+      return response.text();
+    };
+  }
+
+  return {
+    get: makeRequest("GET"),
+    post: makeRequest("POST"),
+    put: makeRequest("PUT"),
+    patch: makeRequest("PATCH"),
+    delete: makeRequest("DELETE"),
+  };
+}
+
+export interface RpcMethods {
+  get: (input?: RpcRequestOptions) => Promise<unknown>;
+  post: (input?: RpcRequestOptions) => Promise<unknown>;
+  put: (input?: RpcRequestOptions) => Promise<unknown>;
+  patch: (input?: RpcRequestOptions) => Promise<unknown>;
+  delete: (input?: RpcRequestOptions) => Promise<unknown>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Phase 18.κ — Typed RPC Client (tRPC-like)
+// ═══════════════════════════════════════════════════════════════════════════
+//
+// `createRpcClient<typeof postsRpc>()` returns a Proxy whose properties
+// are the RPC procedure names (`list`, `get`, …). Each access produces
+// an async function whose input type is the procedure's Zod input
+// type and whose return type is the procedure's Zod output type.
+//
+// Wire protocol:
+//   POST <baseUrl>/<method>
+//   body: { "input": <value> }
+//   response: { "ok": true, "data": <value> }
+//            | { "ok": false, "error": { code, message, issues? } }
+//
+// Errors throw {@link RpcCallError} with the structured fields
+// preserved so UI code can surface field-level validation issues.
+
+import type { RpcClient, RpcDefinition, RpcProcedureRecord, RpcWireEnvelope, RpcWireError } from "../contract/rpc";
+
+/** Options passed to {@link createRpcClient}. */
+export interface CreateRpcClientOptions {
+  /**
+   * Absolute or site-relative base URL for the RPC endpoint —
+   * typically `/api/rpc/<name>`. The method name is appended.
+   */
+  baseUrl: string;
+  /** Extra headers sent with every call. */
+  headers?: Record<string, string>;
+  /** Custom fetch (e.g. test double or node-fetch polyfill). */
+  fetch?: typeof globalThis.fetch;
+  /**
+   * Optional per-call AbortSignal factory. Useful when the proxy is
+   * shared across React components that want independent cancellation.
+   */
+  signal?: AbortSignal;
+}
+
+/**
+ * Typed error thrown by {@link createRpcClient} calls on non-OK
+ * envelopes. Carries the wire-level {@link RpcWireError} + HTTP
+ * status so callers can distinguish validation vs. handler errors
+ * without string-matching on `message`.
+ */
+export class RpcCallError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly error: RpcWireError
+  ) {
+    super(`[Mandu RPC] ${error.code}: ${error.message}`);
+    this.name = "RpcCallError";
+  }
+
+  /** Machine-readable code (forwarded from the server). */
+  get code(): string {
+    return this.error.code;
+  }
+
+  /** Field-level issues, if any. */
+  get issues(): RpcWireError["issues"] {
+    return this.error.issues;
+  }
+}
+
+/**
+ * Create a typed RPC client from an `RpcDefinition` type import.
+ *
+ * The implementation uses a `Proxy` so no codegen step is required —
+ * TypeScript infers call signatures from the imported `typeof` at
+ * compile time, and at runtime every property access produces a
+ * fetch wrapper.
+ *
+ * @example
+ * ```ts
+ * import { createRpcClient } from "@mandujs/core/client";
+ * import type { postsRpc } from "../server/rpc/posts";
+ *
+ * const api = createRpcClient<typeof postsRpc>({ baseUrl: "/api/rpc/posts" });
+ * const posts = await api.list({ limit: 20 });   // fully typed
+ * const post  = await api.get({ id: "abc" });    // fully typed
+ * ```
+ *
+ * Type-check failures at the call site are real compile errors:
+ * `api.list({ limit: "not-a-number" })` is a TS2322.
+ */
+export function createRpcClient<TDef extends RpcDefinition<RpcProcedureRecord>>(
+  options: CreateRpcClientOptions
+): RpcClient<TDef> {
+  const baseFetch = options.fetch ?? globalThis.fetch;
+  const baseUrl = options.baseUrl.replace(/\/$/, "");
+  const baseHeaders = options.headers ?? {};
+
+  const call = async (method: string, input: unknown): Promise<unknown> => {
+    const url = `${baseUrl}/${method}`;
+    const payload = input === undefined ? { input: undefined } : { input };
+    const response = await baseFetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        ...baseHeaders,
+      },
+      body: JSON.stringify(payload),
+      signal: options.signal,
+    });
+
+    // Prefer JSON parse (every legitimate RPC response is JSON), but
+    // tolerate non-JSON failure paths (e.g. upstream proxy error).
+    let envelope: RpcWireEnvelope | null = null;
+    const text = await response.text();
+    try {
+      envelope = text.length > 0 ? (JSON.parse(text) as RpcWireEnvelope) : null;
+    } catch {
+      envelope = null;
+    }
+
+    if (envelope && envelope.ok === true) {
+      return envelope.data;
+    }
+
+    // Non-OK path — throw a structured error. Prefer server-emitted
+    // envelope; fall back to a synthesized one for transport errors.
+    let error: RpcWireError;
+    if (envelope && envelope.ok === false) {
+      error = envelope.error;
+    } else {
+      error = {
+        code: response.ok ? "BAD_RESPONSE" : `HTTP_${response.status}`,
+        message:
+          text.length > 0
+            ? text.slice(0, 500)
+            : `RPC call to ${url} failed with HTTP ${response.status}`,
+      };
+    }
+    throw new RpcCallError(response.status, error);
+  };
+
+  // A Proxy on a plain object: every property access returns a
+  // pre-curried call fn. Symbol keys (`Symbol.toStringTag`, etc.) fall
+  // through so `console.log(api)` does not throw.
+  const target = Object.create(null) as Record<string, unknown>;
+  return new Proxy(target, {
+    get(_t, prop) {
+      if (typeof prop !== "string") return undefined;
+      // Allow common non-method inspection hooks to no-op.
+      if (prop === "then") return undefined; // not thenable
+      if (prop === "toJSON") return undefined;
+      return (input?: unknown) => call(prop, input);
+    },
+  }) as RpcClient<TDef>;
+}
+

package/src/config/mandu.ts

@@ -3,6 +3,10 @@ import { readJsonFile } from "../utils/bun";
 import type { ManduAdapter } from "../runtime/adapter";
 import type { ManduPlugin, ManduHooks } from "../plugins/hooks";
 import type { Middleware } from "../middleware/define";
+import type { RpcDefinition, RpcProcedureRecord } from "../contract/rpc";
+import type { CronDef } from "../scheduler";
+import type { GuardRule as CustomGuardRule } from "../guard/define-rule";
+import type { I18nStrategy, LocaleCode } from "../i18n/types";
 
 export type GuardRuleSeverity = "error" | "warn" | "warning" | "off";
 
@@ -146,7 +150,20 @@ export interface ManduConfig {
     srcDir?: string;
     exclude?: string[];
     realtime?: boolean;
-    rules?: Record<string, GuardRuleSeverity>;
+    /**
+     * Built-in rule severity overrides (map) OR consumer-defined
+     * custom rules (array). The Guard runner dispatches on shape:
+     *
+     *   - `Record<string, GuardRuleSeverity>` → override severity of
+     *     Mandu's built-in rules by id.
+     *   - `GuardRule[]` (Phase 18.ν) → register consumer-defined rules
+     *     alongside the built-in presets. See `@mandujs/core/guard/define-rule`.
+     *
+     * Passing both at once is not supported; pick one shape per config.
+     * Mixed input falls back to "custom rules only" and the built-in
+     * rule severity overrides become unreachable.
+     */
+    rules?: Record<string, GuardRuleSeverity> | CustomGuardRule[];
     contractRequired?: GuardRuleSeverity;
     /**
      * Issue #207 — hard-fail on direct `__generated__/` imports at the
@@ -373,6 +390,95 @@ export interface ManduConfig {
    * @see `docs/architect/middleware-composition.md`
    */
   middleware?: Middleware[];
+  /**
+   * Phase 18.κ — tRPC-like typed RPC endpoints.
+   *
+   * Keys become URL segments: `endpoints.posts` is served from
+   * `/api/rpc/posts/<method>`. Each value is a `defineRpc()` result —
+   * a tagged object carrying Zod input/output schemas and handler
+   * functions. The runtime dispatcher (`runtime/server.ts`) registers
+   * every declared endpoint at `startServer()` time and validates
+   * both request inputs and handler outputs against the schemas.
+   *
+   * Wire protocol: `POST /api/rpc/<name>/<method>` with JSON body
+   * `{ "input": <value> }`; returns `{ ok: true, data }` or
+   * `{ ok: false, error: { code, message, issues? } }`.
+   *
+   * Client: `createRpcClient<typeof postsRpc>({ baseUrl: "/api/rpc/posts" })`.
+   *
+   * @see `docs/architect/typed-rpc.md`
+   * @see `@mandujs/core/contract/rpc` for `defineRpc`.
+   * @see `@mandujs/core/client/rpc` for `createRpcClient`.
+   */
+  rpc?: {
+    endpoints?: Record<string, RpcDefinition<RpcProcedureRecord>>;
+  };
+  /**
+   * Phase 18.λ — declarative cron job scheduler.
+   *
+   * `scheduler.jobs` is an array of {@link CronDef} objects (from
+   * `@mandujs/core/scheduler`). At `startServer()` boot time the runtime
+   * filters the set by `runOn === "bun"` (or `runOn` omitted) and registers
+   * each surviving job with `Bun.cron`. At build time, when
+   * `--target=workers` is set, the CLI filters by `runOn === "workers"` (or
+   * omitted) and emits the schedule strings into the generated
+   * `wrangler.toml` `[triggers] crons = [...]` block.
+   *
+   * Schedule strings are validated synchronously at `defineCron` time, so
+   * malformed crontabs fail boot instead of silently never firing.
+   *
+   * `scheduler.disabled` is an escape hatch for environments where cron
+   * should not fire (e.g., a read-only replica). Default: `false`.
+   *
+   * @see `docs/architect/cron-scheduler.md`
+   * @see `@mandujs/core/scheduler` for `defineCron`.
+   */
+  scheduler?: {
+    jobs?: CronDef[];
+    disabled?: boolean;
+  };
+  /**
+   * Phase 18.μ — first-class internationalization.
+   *
+   * Declaring this block opts the project into the framework's built-in
+   * locale resolution + route synthesis. The CLI (`mandu build` /
+   * `mandu dev`) materializes per-locale route variants when
+   * `strategy === "path-prefix"` so a single `app/docs/page.tsx`
+   * serves `/en/docs`, `/ko/docs`, etc. without file duplication.
+   *
+   * At runtime, the server dispatcher attaches `ctx.locale`
+   * ({@link ResolvedLocale}) + `ctx.t` (typed translator, when a
+   * message registry is wired) to every loader and stamps
+   * `Vary: Accept-Language` on responses so CDNs cache correctly.
+   *
+   * Coexists with the legacy `app/[lang]/...` manual pattern — users
+   * migrate only when ready. See `docs/architect/i18n.md`.
+   *
+   * @example
+   * ```ts
+   * export default {
+   *   i18n: {
+   *     locales: ['en', 'ko'],
+   *     defaultLocale: 'en',
+   *     strategy: 'path-prefix',
+   *   },
+   * } satisfies ManduConfig;
+   * ```
+   */
+  i18n?: {
+    /** Non-empty list of supported locale codes. */
+    locales: LocaleCode[];
+    /** Fallback when no signal matches. MUST be in `locales`. */
+    defaultLocale: LocaleCode;
+    /** Optional fallback chain between request locale and defaultLocale. */
+    fallback?: LocaleCode;
+    /** Locale detection strategy. See {@link I18nStrategy}. */
+    strategy: I18nStrategy;
+    /** Cookie name (default: "mandu_locale"). */
+    cookieName?: string;
+    /** Domain → locale map; required when strategy === "domain". */
+    domains?: Record<string, LocaleCode>;
+  };
 }
 
 export const CONFIG_FILES = [