@mandujs/core 0.29.1 → 0.31.0

package/src/config/validate.ts

@@ -6,6 +6,7 @@ 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";
 
 /**
  * DNA-003: Strict mode schema helper
@@ -105,6 +106,13 @@ const BuildConfigSchema = z
      * module exports `generateStaticParams` is prerendered).
      */
     prerender: z.boolean().default(true),
+    /**
+     * Phase 18.η — opt into post-build bundle analyzer artefacts
+     * (`.mandu/analyze/report.html` + `report.json`). Default `false`.
+     * CLI `--analyze` overrides this at runtime; config is the "always on
+     * for this project" switch.
+     */
+    analyze: z.boolean().default(false),
   })
   .strict();
 
@@ -229,10 +237,28 @@ const TestConfigSchema = z
  * default so the runtime can distinguish "not set" (use mode default)
  * from "explicit false" (force off even in dev).
  */
+/**
+ * Phase 18.θ — tracing sub-block. All fields optional; omitting the
+ * whole block keeps tracing disabled and incurs zero runtime overhead.
+ * `endpoint` and `headers` are only meaningful when `exporter === "otlp"`
+ * but we don't make that a cross-field refine — runtime falls back to
+ * console with a warning when `"otlp"` is requested without an endpoint.
+ */
+const TracingConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    exporter: z.enum(["console", "otlp"]).optional(),
+    endpoint: z.string().url().optional(),
+    headers: z.record(z.string()).optional(),
+    serviceName: z.string().min(1).optional(),
+  })
+  .strict();
+
 const ObservabilityConfigSchema = z
   .object({
     heapEndpoint: z.boolean().optional(),
     metricsEndpoint: z.boolean().optional(),
+    tracing: TracingConfigSchema.optional(),
   })
   .strict();
 
@@ -293,6 +319,64 @@ const MiddlewareSchema = z.custom<Middleware>(
   }
 );
 
+/**
+ * Phase 18.ζ — ISR / cache config (strict).
+ *
+ * All fields optional. Omitting the block leaves caching disabled unless
+ * individual routes opt in via `filling.loader(fn, { revalidate })` or
+ * loader-level `_cache` metadata. Setting `defaultMaxAge` makes every
+ * non-dynamic route auto-cache with that fresh TTL.
+ */
+const CacheConfigSchema = z
+  .object({
+    defaultMaxAge: z.number().int().nonnegative().optional(),
+    defaultSwr: z.number().int().nonnegative().optional(),
+    maxEntries: z.number().int().positive().optional(),
+    store: z.enum(["memory"]).optional(),
+  })
+  .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();
+
 export const ManduConfigSchema = z
   .object({
     adapter: AdapterConfigSchema.optional(),
@@ -322,6 +406,8 @@ export const ManduConfigSchema = z
     seo: SeoConfigSchema.default({}),
     test: TestConfigSchema.default({}),
     observability: ObservabilityConfigSchema.default({}),
+    /** Phase 18.ζ — ISR / tag-based cache invalidation. Optional. */
+    cache: CacheConfigSchema.optional(),
     plugins: z.array(ManduPluginSchema).optional(),
     hooks: ManduHooksSchema.optional(),
     /**
@@ -331,6 +417,12 @@ 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(),
   })
   .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);
+}