@mandujs/core 0.30.0 → 0.32.0

package/src/config/validate.ts

@@ -6,6 +6,8 @@ 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 { CronDef } from "../scheduler";
+import { isGuardRuleLike, type GuardRule as CustomGuardRule } from "../guard/define-rule";
 
 /**
  * DNA-003: Strict mode schema helper
@@ -71,8 +73,30 @@ const ServerConfigSchema = z
   })
   .strict();
 
+/**
+ * Phase 18.ν — consumer-defined Guard rule (structural check).
+ *
+ * Rule objects carry closures (`check`) that Zod cannot introspect, so
+ * we validate structurally: must be a non-null object with a non-empty
+ * `id` string and a `check` function. Deeper validation (severity enum,
+ * description type) happens at `defineGuardRule()` time for the clearest
+ * DX error; the Guard runner catches any in-band violations.
+ */
+const CustomGuardRuleSchema = z.custom<CustomGuardRule>(
+  (v) => isGuardRuleLike(v),
+  {
+    message:
+      "Each custom guard rule must be an object with a non-empty `id` string and a `check` function. Use `defineGuardRule({...})` from `@mandujs/core/guard/define-rule` to construct.",
+  }
+);
+
 /**
  * Guard 설정 스키마 (strict)
+ *
+ * `guard.rules` is a discriminated union of two shapes:
+ *   - `Record<string, GuardRuleSeverity>` → built-in rule severity overrides.
+ *   - `GuardRule[]` (Phase 18.ν) → consumer-defined custom rules.
+ * The runner dispatches on `Array.isArray()`.
  */
 const GuardConfigSchema = z
   .object({
@@ -80,7 +104,12 @@ const GuardConfigSchema = z
     srcDir: z.string().default("src"),
     exclude: z.array(z.string()).default([]),
     realtime: z.boolean().default(true),
-    rules: z.record(z.enum(["error", "warn", "warning", "off"])).optional(),
+    rules: z
+      .union([
+        z.record(z.enum(["error", "warn", "warning", "off"])),
+        z.array(CustomGuardRuleSchema),
+      ])
+      .optional(),
     /**
      * Issue #207 — bundler-level hard-fail on direct `__generated__/`
      * imports. Default `true`. Set `false` to opt out of the
@@ -335,6 +364,110 @@ const CacheConfigSchema = z
   })
   .strict();
 
+/**
+ * Phase 18.λ — declarative cron scheduler (strict).
+ *
+ * Each `jobs[i]` entry is structurally validated: `name` must be a non-empty
+ * string, `schedule` a string (deeper cron validation runs at `defineCron`
+ * time), and `handler` (or `run` alias) a function. Zod cannot introspect
+ * closures, so the handler field is a structural check.
+ *
+ * `disabled` short-circuits registration in environments where cron
+ * shouldn't fire (e.g., a read-only replica reading the same config file
+ * its primary uses).
+ */
+const CronDefSchema = z.custom<CronDef>(
+  (v) => {
+    if (typeof v !== "object" || v === null) return false;
+    const obj = v as Record<string, unknown>;
+    if (typeof obj.name !== "string" || obj.name.length === 0) return false;
+    if (typeof obj.schedule !== "string" || obj.schedule.length === 0) return false;
+    if (typeof obj.handler !== "function" && typeof obj.run !== "function") return false;
+    if (obj.timezone !== undefined && typeof obj.timezone !== "string") return false;
+    if (obj.runOn !== undefined) {
+      if (!Array.isArray(obj.runOn)) return false;
+      for (const r of obj.runOn) {
+        if (r !== "bun" && r !== "workers") return false;
+      }
+    }
+    return true;
+  },
+  {
+    message:
+      "Each cron job must be an object with `name` (string), `schedule` (string), and `handler` (function). Optional: `timezone` (string), `runOn` (array of 'bun'|'workers'), `skipInDev` (boolean), `timeoutMs` (number).",
+  }
+);
+
+const SchedulerConfigSchema = z
+  .object({
+    jobs: z.array(CronDefSchema).optional(),
+    disabled: z.boolean().optional(),
+  })
+  .strict();
+
+/**
+ * Phase 18.μ — i18n config schema (strict).
+ *
+ * Strictly validates shape + cross-field invariants that `defineI18n()`
+ * enforces at runtime (defaultLocale ∈ locales, fallback ∈ locales,
+ * domain map required when strategy === "domain"). Doing this at
+ * config load gives users a clean `mandu validate` error instead of
+ * a runtime boot failure.
+ */
+const I18nConfigSchema = z
+  .object({
+    locales: z.array(z.string().min(1)).min(1),
+    defaultLocale: z.string().min(1),
+    fallback: z.string().min(1).optional(),
+    strategy: z.enum(["path-prefix", "domain", "header", "cookie"]),
+    cookieName: z.string().min(1).optional(),
+    domains: z.record(z.string().min(1)).optional(),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    const locales = new Set(value.locales);
+    if (locales.size !== value.locales.length) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["locales"],
+        message: "locales must not contain duplicates",
+      });
+    }
+    if (!locales.has(value.defaultLocale)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["defaultLocale"],
+        message: `defaultLocale "${value.defaultLocale}" must be one of locales`,
+      });
+    }
+    if (value.fallback !== undefined && !locales.has(value.fallback)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["fallback"],
+        message: `fallback "${value.fallback}" must be one of locales`,
+      });
+    }
+    if (value.strategy === "domain") {
+      if (!value.domains || Object.keys(value.domains).length === 0) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["domains"],
+          message: "strategy 'domain' requires a non-empty domains map",
+        });
+      } else {
+        for (const [host, locale] of Object.entries(value.domains)) {
+          if (!locales.has(locale)) {
+            ctx.addIssue({
+              code: z.ZodIssueCode.custom,
+              path: ["domains", host],
+              message: `domains["${host}"] = "${locale}" is not in locales`,
+            });
+          }
+        }
+      }
+    }
+  });
+
 export const ManduConfigSchema = z
   .object({
     adapter: AdapterConfigSchema.optional(),
@@ -375,6 +508,17 @@ export const ManduConfigSchema = z
      * passthrough at runtime).
      */
     middleware: z.array(MiddlewareSchema).optional(),
+    /**
+     * Phase 18.λ — declarative cron scheduler. See {@link SchedulerConfigSchema}.
+     * Omit the block to disable scheduling entirely (zero-overhead
+     * passthrough).
+     */
+    scheduler: SchedulerConfigSchema.optional(),
+    /**
+     * Phase 18.μ — first-class i18n config. See {@link I18nConfigSchema}.
+     * Optional; omission leaves i18n disabled with zero runtime overhead.
+     */
+    i18n: I18nConfigSchema.optional(),
   })
   .strict();
 

package/src/contract/index.ts

@@ -19,6 +19,24 @@ export * from "./client-safe";
 export * from "./protection";
 export * from "./route-helpers";
 
+// Phase 18.κ — tRPC-like typed RPC (see `./rpc.ts`).
+export {
+  defineRpc,
+  registerRpc,
+  getRpc,
+  clearRpcRegistry,
+  listRpcEndpoints,
+  matchRpcPath,
+  dispatchRpc,
+  type RpcContext,
+  type RpcProcedure,
+  type RpcProcedureRecord,
+  type RpcDefinition,
+  type RpcClient,
+  type RpcWireEnvelope,
+  type RpcWireError,
+} from "./rpc";
+
 import type { ContractDefinition, ContractInstance, ContractSchema } from "./schema";
 import type { ContractHandlers, RouteDefinition } from "./handler";
 import { defineHandler, defineRoute } from "./handler";

package/src/contract/rpc.ts

@@ -0,0 +1,443 @@
+/**
+ * Mandu Typed RPC — Server Side
+ *
+ * tRPC-like end-to-end typed RPC built on Mandu's existing contract +
+ * client layer. No external tRPC dependency. Zod contracts on the
+ * server flow through to auto-typed client proxies.
+ *
+ * Phase 18.κ — see `docs/architect/typed-rpc.md` for the comparison
+ * against tRPC / SvelteKit form actions / Next.js server actions plus
+ * the migration recipe.
+ *
+ * @module
+ */
+
+import type { z } from "zod";
+
+// ========== Types ==========
+
+/**
+ * Per-procedure call context.
+ *
+ * `input` is the Zod-parsed, validated request body (or `undefined`
+ * when the procedure declares no `input` schema). `request` is the
+ * raw Fetch `Request` so procedures can read cookies / headers. `ctx`
+ * is a free-form object threaded from the dispatcher — Phase 18.κ
+ * ships an empty object by default; session / DB / user wiring is
+ * layered on via `ManduConfig.rpc.context` in a future patch.
+ */
+export interface RpcContext<TInput = unknown, TCtx = Record<string, unknown>> {
+  /** Validated input (parsed by the procedure's `input` Zod schema). */
+  input: TInput;
+  /** Raw Fetch Request — cookies / headers / auth state. */
+  request: Request;
+  /** Per-request context (session, db, user, …). */
+  ctx: TCtx;
+}
+
+/**
+ * A single RPC procedure definition.
+ *
+ * Each procedure pairs an `input` schema (optional — allow
+ * parameter-less RPCs), an `output` schema (required — the contract
+ * guarantee), and a `handler` function. `handler` receives the
+ * validated input + the raw Request + a shared context object and
+ * returns the output shape; the dispatcher validates the return
+ * value against `output` before shipping.
+ */
+export interface RpcProcedure<
+  TInputSchema extends z.ZodTypeAny | undefined = z.ZodTypeAny | undefined,
+  TOutputSchema extends z.ZodTypeAny = z.ZodTypeAny,
+  TCtx extends Record<string, unknown> = Record<string, unknown>,
+> {
+  /** Zod schema for procedure input. `undefined` for no-arg procedures. */
+  input?: TInputSchema;
+  /** Zod schema for the return value (response body). */
+  output: TOutputSchema;
+  /** Procedure body. Receives validated input + request + shared ctx. */
+  handler: (
+    args: RpcContext<
+      TInputSchema extends z.ZodTypeAny ? z.infer<TInputSchema> : undefined,
+      TCtx
+    >
+  ) => Promise<z.infer<TOutputSchema>> | z.infer<TOutputSchema>;
+}
+
+/** Record of procedures — the raw user input to {@link defineRpc}. */
+export type RpcProcedureRecord = Record<
+  string,
+  RpcProcedure<z.ZodTypeAny | undefined, z.ZodTypeAny>
+>;
+
+/**
+ * Tagged RPC definition — the return value of {@link defineRpc}.
+ *
+ * The `__rpc` brand lets the client proxy and the route dispatcher
+ * distinguish RPC definitions from plain contract objects without
+ * reaching for `instanceof`.
+ */
+export interface RpcDefinition<TProcedures extends RpcProcedureRecord = RpcProcedureRecord> {
+  /** The raw procedure record (used by both server dispatch and client proxy). */
+  procedures: TProcedures;
+  /** Brand — distinguishes RPC defs from contract objects. */
+  readonly __rpc: true;
+}
+
+/**
+ * Client-facing type derived from a {@link RpcDefinition}.
+ *
+ * Maps each procedure key to a function whose argument is the Zod
+ * input type (or `undefined`/no-arg for procedures without input)
+ * and whose return is `Promise<Output>`. Used by
+ * `createRpcClient<typeof postsRpc>()`.
+ */
+export type RpcClient<TDef extends RpcDefinition<RpcProcedureRecord>> = {
+  [K in keyof TDef["procedures"]]: TDef["procedures"][K]["input"] extends z.ZodTypeAny
+    ? (input: z.infer<TDef["procedures"][K]["input"]>) => Promise<z.infer<TDef["procedures"][K]["output"]>>
+    : (input?: undefined) => Promise<z.infer<TDef["procedures"][K]["output"]>>;
+};
+
+// ========== Core API ==========
+
+/**
+ * Define a tRPC-style typed RPC module.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { defineRpc } from "@mandujs/core/contract/rpc";
+ *
+ * export const postsRpc = defineRpc({
+ *   list: {
+ *     input: z.object({ limit: z.number().optional() }).optional(),
+ *     output: z.array(z.object({ id: z.string(), title: z.string() })),
+ *     handler: async ({ input }) => db.posts.findMany({ limit: input?.limit ?? 10 }),
+ *   },
+ *   get: {
+ *     input: z.object({ id: z.string() }),
+ *     output: z.object({ id: z.string(), title: z.string(), body: z.string() }),
+ *     handler: async ({ input }) => db.posts.findUnique({ where: { id: input.id } }),
+ *   },
+ * });
+ * ```
+ *
+ * Wire to a server by passing to {@link registerRpc} (or via
+ * `ManduConfig.rpc.endpoints`). Requests resolve to
+ * `POST /api/rpc/<name>/<method>` where `<name>` is the endpoint key.
+ */
+export function defineRpc<TProcedures extends RpcProcedureRecord>(
+  procedures: TProcedures
+): RpcDefinition<TProcedures> {
+  // Validate each procedure shape at define-time so a missing `output`
+  // or `handler` fails fast with a readable message instead of a
+  // runtime NPE inside the dispatcher.
+  for (const [key, proc] of Object.entries(procedures)) {
+    if (!proc || typeof proc !== "object") {
+      throw new Error(
+        `[Mandu RPC] Procedure "${key}" is not an object. Each procedure must be { input?, output, handler }.`
+      );
+    }
+    if (typeof proc.handler !== "function") {
+      throw new Error(
+        `[Mandu RPC] Procedure "${key}" is missing a handler function.`
+      );
+    }
+    if (!proc.output || typeof (proc.output as z.ZodTypeAny).safeParse !== "function") {
+      throw new Error(
+        `[Mandu RPC] Procedure "${key}" is missing an output Zod schema.`
+      );
+    }
+    if (proc.input !== undefined && typeof (proc.input as z.ZodTypeAny).safeParse !== "function") {
+      throw new Error(
+        `[Mandu RPC] Procedure "${key}" has an invalid input schema (not a Zod type).`
+      );
+    }
+  }
+
+  return {
+    procedures,
+    __rpc: true,
+  };
+}
+
+// ========== Registry ==========
+
+/**
+ * Global RPC endpoint registry.
+ *
+ * Keyed by endpoint name (the `<name>` in `/api/rpc/<name>/<method>`).
+ * Populated by {@link registerRpc} (typically at boot via
+ * `ManduConfig.rpc.endpoints`) and consumed by the dispatcher in
+ * `runtime/server.ts`.
+ */
+const rpcRegistry = new Map<string, RpcDefinition<RpcProcedureRecord>>();
+
+/**
+ * Register an RPC endpoint under `name`.
+ *
+ * Same name twice overwrites (HMR-friendly). Pass `null` / `undefined`
+ * to clear a registration. Typically called automatically from
+ * `startServer` when `ManduConfig.rpc.endpoints` is set, but public
+ * so user code can register additional endpoints at runtime.
+ */
+export function registerRpc(
+  name: string,
+  definition: RpcDefinition<RpcProcedureRecord>
+): void {
+  if (!definition?.__rpc) {
+    throw new Error(
+      `[Mandu RPC] registerRpc("${name}", …) expected a defineRpc() result, got ${typeof definition}.`
+    );
+  }
+  rpcRegistry.set(name, definition);
+}
+
+/** Look up an RPC endpoint by name. Returns `undefined` on miss. */
+export function getRpc(name: string): RpcDefinition<RpcProcedureRecord> | undefined {
+  return rpcRegistry.get(name);
+}
+
+/** Clear all RPC registrations (test helper). */
+export function clearRpcRegistry(): void {
+  rpcRegistry.clear();
+}
+
+/** Enumerate registered endpoint names. */
+export function listRpcEndpoints(): string[] {
+  return Array.from(rpcRegistry.keys());
+}
+
+// ========== Dispatch ==========
+
+/**
+ * Shape of the JSON envelope that flows over the wire.
+ *
+ * Mirrors {@link RpcWireError} for the failure case — the client
+ * proxy inspects `ok` and unwraps `data` or throws {@link RpcCallError}.
+ */
+export type RpcWireEnvelope<T = unknown> =
+  | { ok: true; data: T }
+  | { ok: false; error: RpcWireError };
+
+export interface RpcWireError {
+  /** Machine-readable code: `INPUT_INVALID` | `OUTPUT_INVALID` | `NOT_FOUND` | `HANDLER_ERROR` | `METHOD_NOT_ALLOWED` | `BAD_JSON`. */
+  code: string;
+  /** Human-readable message (generic in prod, full in dev). */
+  message: string;
+  /** Optional field-level issues for `INPUT_INVALID` / `OUTPUT_INVALID`. */
+  issues?: Array<{ path: (string | number)[]; message: string; code?: string }>;
+}
+
+/**
+ * Match `/api/rpc/<name>/<method>` — the canonical RPC URL shape.
+ * Returns `null` for any path that is not an RPC call, so the
+ * dispatcher can fall through to the normal route matcher.
+ *
+ * `<name>` and `<method>` are restricted to `[A-Za-z0-9_-]+` to
+ * prevent path-traversal style abuse of the lookup key.
+ */
+export function matchRpcPath(
+  pathname: string
+): { endpoint: string; method: string } | null {
+  if (!pathname.startsWith("/api/rpc/")) return null;
+  const rest = pathname.slice("/api/rpc/".length);
+  // Only two non-empty segments; reject nested paths.
+  const parts = rest.split("/");
+  if (parts.length !== 2) return null;
+  const [endpoint, method] = parts;
+  if (!endpoint || !method) return null;
+  if (!/^[A-Za-z0-9_-]+$/.test(endpoint)) return null;
+  if (!/^[A-Za-z0-9_-]+$/.test(method)) return null;
+  return { endpoint, method };
+}
+
+/**
+ * Serialize a Zod error to the wire-level `issues` array.
+ */
+function zodIssues(err: z.ZodError): RpcWireError["issues"] {
+  return err.errors.map((iss) => ({
+    path: iss.path,
+    message: iss.message,
+    code: iss.code,
+  }));
+}
+
+function jsonResponse(envelope: RpcWireEnvelope, status: number): Response {
+  return new Response(JSON.stringify(envelope), {
+    status,
+    headers: { "Content-Type": "application/json; charset=utf-8" },
+  });
+}
+
+/**
+ * Dispatch an RPC call.
+ *
+ * Handles (in order): method gate (POST only), endpoint lookup,
+ * procedure lookup, input parse + validate, handler invocation,
+ * output validate, response shaping. Every failure path returns a
+ * structured {@link RpcWireEnvelope} — callers do not throw.
+ *
+ * `isDev` toggles whether handler errors include the raw message +
+ * stack. In prod (`isDev === false`) we return a generic
+ * `"Internal RPC error"` to avoid leaking stack frames.
+ */
+export async function dispatchRpc(
+  req: Request,
+  endpoint: string,
+  method: string,
+  options: { isDev?: boolean; ctx?: Record<string, unknown> } = {}
+): Promise<Response> {
+  const isDev = options.isDev ?? false;
+  const sharedCtx = options.ctx ?? {};
+
+  if (req.method !== "POST") {
+    return jsonResponse(
+      {
+        ok: false,
+        error: {
+          code: "METHOD_NOT_ALLOWED",
+          message: `RPC endpoints accept POST only (got ${req.method}).`,
+        },
+      },
+      405
+    );
+  }
+
+  const definition = rpcRegistry.get(endpoint);
+  if (!definition) {
+    return jsonResponse(
+      {
+        ok: false,
+        error: {
+          code: "NOT_FOUND",
+          message: `Unknown RPC endpoint "${endpoint}".`,
+        },
+      },
+      404
+    );
+  }
+
+  const procedure = definition.procedures[method];
+  if (!procedure) {
+    return jsonResponse(
+      {
+        ok: false,
+        error: {
+          code: "NOT_FOUND",
+          message: `RPC endpoint "${endpoint}" has no procedure "${method}".`,
+        },
+      },
+      404
+    );
+  }
+
+  // ---- Parse body ----
+  let rawBody: unknown = undefined;
+  const contentLength = req.headers.get("content-length");
+  const hasBody = contentLength !== "0" && req.headers.get("content-type")?.includes("application/json");
+  if (hasBody) {
+    try {
+      const text = await req.text();
+      if (text.length > 0) {
+        rawBody = JSON.parse(text);
+      }
+    } catch (err) {
+      return jsonResponse(
+        {
+          ok: false,
+          error: {
+            code: "BAD_JSON",
+            message: `Request body is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+          },
+        },
+        400
+      );
+    }
+  }
+
+  // Wire envelope: { input: <value> } — matches createRpcClient output.
+  const rawInput = rawBody && typeof rawBody === "object" && rawBody !== null && "input" in rawBody
+    ? (rawBody as { input: unknown }).input
+    : rawBody;
+
+  // ---- Validate input ----
+  let parsedInput: unknown = undefined;
+  if (procedure.input) {
+    const result = procedure.input.safeParse(rawInput);
+    if (!result.success) {
+      return jsonResponse(
+        {
+          ok: false,
+          error: {
+            code: "INPUT_INVALID",
+            message: "Input failed schema validation.",
+            issues: zodIssues(result.error),
+          },
+        },
+        400
+      );
+    }
+    parsedInput = result.data;
+  }
+
+  // ---- Invoke handler ----
+  let handlerResult: unknown;
+  try {
+    handlerResult = await procedure.handler({
+      input: parsedInput as never,
+      request: req,
+      ctx: sharedCtx,
+    });
+  } catch (err) {
+    const message =
+      isDev && err instanceof Error
+        ? err.message
+        : "Internal RPC error";
+    if (isDev) {
+      // Dev mode: surface the stack on the server console so the
+      // user can debug without peering at network tab payloads.
+      console.error(
+        `[Mandu RPC] handler error in ${endpoint}.${method}:`,
+        err
+      );
+    }
+    return jsonResponse(
+      {
+        ok: false,
+        error: {
+          code: "HANDLER_ERROR",
+          message,
+        },
+      },
+      500
+    );
+  }
+
+  // ---- Validate output ----
+  const outResult = procedure.output.safeParse(handlerResult);
+  if (!outResult.success) {
+    // Output-schema mismatch is a programmer bug (server returned
+    // wrong shape). Log loud in dev; return a generic 500 in prod.
+    if (isDev) {
+      console.error(
+        `[Mandu RPC] output validation failed in ${endpoint}.${method}:`,
+        outResult.error.errors
+      );
+    }
+    return jsonResponse(
+      {
+        ok: false,
+        error: {
+          code: "OUTPUT_INVALID",
+          message: isDev
+            ? "Handler returned a value that does not match the output schema."
+            : "Internal RPC error",
+          issues: isDev ? zodIssues(outResult.error) : undefined,
+        },
+      },
+      500
+    );
+  }
+
+  return jsonResponse({ ok: true, data: outResult.data }, 200);
+}