mates-fullstack 1.0.0-beta.1

package/dist/middleware.d.ts

@@ -0,0 +1,30 @@
+/**
+ * mates-fullstack — middleware.ts
+ */
+import type { Context } from "./ctx.js";
+export type RequestHook = (c: Context) => Response | void | Promise<Response | void>;
+export type ResponseHook = (c: Context) => void | Promise<void>;
+export type BeforeRPCHook = (data: Record<string, unknown>, c: Context) => Record<string, unknown> | Promise<Record<string, unknown>>;
+export interface AfterRPCInfo {
+    moduleId: string;
+    fnName: string;
+    duration: number;
+}
+export type AfterRPCHook = (result: unknown, c: Context, info: AfterRPCInfo) => unknown | Promise<unknown>;
+export declare function onRequest(hook: RequestHook): void;
+export declare function onResponse(hook: ResponseHook): void;
+export declare function onBeforeRPC(hook: BeforeRPCHook): void;
+export declare function onAfterRPC(hook: AfterRPCHook): void;
+export declare function runRequestHooks(c: Context): Promise<RequestHookResult>;
+export declare function runResponseHooks(c: Context): Promise<void>;
+export declare function runBeforeRPCHooks(data: Record<string, unknown>, c: Context): Promise<Record<string, unknown>>;
+export declare function runAfterRPCHooks(result: unknown, c: Context, info: AfterRPCInfo): Promise<unknown>;
+export interface RequestHookResult {
+    response: Response | null;
+}
+export declare function clearMiddleware(): void;
+export declare function middlewareStats(): {
+    request: number;
+    response: number;
+};
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAGxC,MAAM,MAAM,WAAW,GAAG,CACxB,CAAC,EAAE,OAAO,KACP,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;AAEhD,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEhE,MAAM,MAAM,aAAa,GAAG,CAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,CAAC,EAAE,OAAO,KACP,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEhE,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,YAAY,GAAG,CACzB,MAAM,EAAE,OAAO,EACf,CAAC,EAAE,OAAO,EACV,IAAI,EAAE,YAAY,KACf,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAOhC,wBAAgB,SAAS,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAEjD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAEnD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAErD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAEnD;AAED,wBAAsB,eAAe,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAM5E;AAED,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAQhE;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,CAAC,EAAE,OAAO,GACT,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAMlC;AAED,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,OAAO,EACf,CAAC,EAAE,OAAO,EACV,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC3B;AAED,wBAAgB,eAAe,IAAI,IAAI,CAKtC;AAED,wBAAgB,eAAe,IAAI;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAEvE"}

package/dist/middleware.js

@@ -0,0 +1,67 @@
+/**
+ * mates-fullstack — middleware.ts
+ */
+import { devError } from "./log.js";
+let _requestHooks = [];
+let _responseHooks = [];
+let _beforeRPCHooks = [];
+let _afterRPCHooks = [];
+export function onRequest(hook) {
+    _requestHooks.push(hook);
+}
+export function onResponse(hook) {
+    _responseHooks.push(hook);
+}
+export function onBeforeRPC(hook) {
+    _beforeRPCHooks.push(hook);
+}
+export function onAfterRPC(hook) {
+    _afterRPCHooks.push(hook);
+}
+export async function runRequestHooks(c) {
+    for (const hook of _requestHooks) {
+        const result = await hook(c);
+        if (result instanceof Response)
+            return { response: result };
+    }
+    return { response: null };
+}
+export async function runResponseHooks(c) {
+    for (const hook of _responseHooks) {
+        try {
+            await hook(c);
+        }
+        catch (err) {
+            devError(`onResponse hook error: ${err?.message ?? err}`);
+        }
+    }
+}
+export async function runBeforeRPCHooks(data, c) {
+    let current = data;
+    for (const hook of _beforeRPCHooks) {
+        current = await hook(current, c);
+    }
+    return current;
+}
+export async function runAfterRPCHooks(result, c, info) {
+    let current = result;
+    for (const hook of _afterRPCHooks) {
+        try {
+            current = await hook(current, c, info);
+        }
+        catch (err) {
+            devError(`onAfterRPC hook error: ${err?.message ?? err}`);
+        }
+    }
+    return current;
+}
+export function clearMiddleware() {
+    _requestHooks = [];
+    _responseHooks = [];
+    _beforeRPCHooks = [];
+    _afterRPCHooks = [];
+}
+export function middlewareStats() {
+    return { request: _requestHooks.length, response: _responseHooks.length };
+}
+//# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAyBpC,IAAI,aAAa,GAAkB,EAAE,CAAC;AACtC,IAAI,cAAc,GAAmB,EAAE,CAAC;AACxC,IAAI,eAAe,GAAoB,EAAE,CAAC;AAC1C,IAAI,cAAc,GAAmB,EAAE,CAAC;AAExC,MAAM,UAAU,SAAS,CAAC,IAAiB;IACzC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAkB;IAC3C,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAmB;IAC7C,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAkB;IAC3C,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,CAAU;IAC9C,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC;QAC7B,IAAI,MAAM,YAAY,QAAQ;YAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC9D,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAC5B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,CAAU;IAC/C,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC;QAChB,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,QAAQ,CAAC,0BAA0B,GAAG,EAAE,OAAO,IAAI,GAAG,EAAE,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,IAA6B,EAC7B,CAAU;IAEV,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,KAAK,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC;QACnC,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,MAAe,EACf,CAAU,EACV,IAAkB;IAElB,IAAI,OAAO,GAAG,MAAM,CAAC;IACrB,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;QACzC,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,QAAQ,CAAC,0BAA0B,GAAG,EAAE,OAAO,IAAI,GAAG,EAAE,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAMD,MAAM,UAAU,eAAe;IAC7B,aAAa,GAAG,EAAE,CAAC;IACnB,cAAc,GAAG,EAAE,CAAC;IACpB,eAAe,GAAG,EAAE,CAAC;IACrB,cAAc,GAAG,EAAE,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,OAAO,EAAE,OAAO,EAAE,aAAa,CAAC,MAAM,EAAE,QAAQ,EAAE,cAAc,CAAC,MAAM,EAAE,CAAC;AAC5E,CAAC"}

package/dist/project-resolver.d.ts

@@ -0,0 +1,102 @@
+/**
+ * mates-fullstack — project-resolver.ts
+ *
+ * Convention-based project path resolution. No mates.config.ts needed.
+ *
+ * The framework infers all paths from the project folder structure:
+ *
+ *   my-app/
+ *   ├── client/
+ *   │   ├── components/
+ *   │   ├── styles/
+ *   │   ├── App.ts        ← root SPA component with Router()
+ *   │   └── client.ts     ← browser hydration entry point
+ *   ├── server/
+ *   │   ├── api/          ← RPC functions
+ *   │   ├── socket/       ← WebSocket handlers
+ *   │   ├── helpers/      ← server-only utilities (never scanned)
+ *   │   └── main.ts       ← per-request middleware hook
+ *   ├── shared/
+ *   │   └── types/        ← shared TypeScript types
+ *   └── public/           ← static assets
+ *
+ * All paths are absolute. Missing directories are null — the framework
+ * gracefully disables the corresponding feature rather than crashing.
+ */
+export interface ResolvedPaths {
+    /** Absolute path to the project root (directory containing package.json). */
+    projectRoot: string;
+    /**
+     * client/App.ts (or .js) — the root SPA component.
+     * The server imports this and renders it directly for every SSR request.
+     * pathAtom is set to the request pathname before rendering so the
+     * app's Router() renders the correct page.
+     * null if not found (SSR disabled).
+     */
+    appFile: string | null;
+    /** client/client.ts (or .js) — browser entry point. null if not found. */
+    clientEntry: string | null;
+    /** public/ — static assets served as-is. null if not found. */
+    publicDir: string | null;
+    /** server/api/ — RPC function registry. null if not found. */
+    apiDir: string | null;
+    /** server/socket/ — WebSocket handlers. null if not found. */
+    socketDir: string | null;
+    /**
+     * server/helpers/ — server-only utilities.
+     * Never scanned for routes. Never entered the browser bundle.
+     * null if not found (no warning — it's optional).
+     */
+    helpersDir: string | null;
+    /** server/main.ts (or .js) — per-request hook. null if not present. */
+    mainFile: string | null;
+    /** shared/ — types and constants shared by both sides. null if not found. */
+    sharedDir: string | null;
+    /** shared/types/ — TypeScript types. null if not found. */
+    sharedTypesDir: string | null;
+    /** dist/ — output directory for production builds and SSG. */
+    outDir: string;
+    /** HTTP port. process.env.PORT → 3000 fallback. */
+    port: number;
+}
+/**
+ * Resolve all project paths from the project root.
+ *
+ * @param projectRoot - Absolute path to the project root.
+ *   Usually the result of findProjectRoot(process.cwd()).
+ */
+export declare function resolveProjectPaths(projectRoot: string): ResolvedPaths;
+export declare function resolveProductionRuntimePaths(sourcePaths: ResolvedPaths): ResolvedPaths;
+/**
+ * Walk up from `startDir` until a directory containing `package.json` is found.
+ * Returns the absolute path to that directory.
+ *
+ * @throws Error if no package.json is found before the filesystem root.
+ */
+export declare function findProjectRoot(startDir: string): string;
+/**
+ * Log warnings for missing directories that affect core features.
+ * Called once at startup after resolving paths.
+ */
+export declare function warnMissingPaths(paths: ResolvedPaths, log: (msg: string) => void): void;
+/**
+ * Returns a human-readable summary of resolved paths for startup logging.
+ */
+export declare function formatPaths(paths: ResolvedPaths): string;
+/**
+ * Resolve the path to the mates package in the project's node_modules.
+ *
+ * Tries multiple resolution strategies:
+ * 1. projectRoot/node_modules/mates/dist/index.esm.js
+ * 2. Standard Node.js module resolution from projectRoot
+ * 3. Standard Node.js module resolution from __dirname (mates-fullstack itself)
+ *
+ * @throws Error if mates cannot be found.
+ */
+export declare function findMatesPath(projectRoot: string): string;
+/**
+ * Returns true if `suspectedChild` is inside `parent`.
+ * Used to prevent path traversal attacks in static file serving.
+ */
+export declare function isPathInside(parent: string, suspectedChild: string): boolean;
+//# sourceMappingURL=project-resolver.d.ts.map

package/dist/project-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-resolver.d.ts","sourceRoot":"","sources":["../src/project-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAQH,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAEvB,0EAA0E;IAC1E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B,+DAA+D;IAC/D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB,8DAA8D;IAC9D,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAEtB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;;;OAIG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B,uEAAuE;IACvE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAExB,6EAA6E;IAC7E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB,2DAA2D;IAC3D,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9B,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IAEf,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;CACd;AAID;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CA+DtE;AAED,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,aAAa,GACzB,aAAa,CAqBf;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAoBxD;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,aAAa,EACpB,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GACzB,IAAI,CAqBN;AAID;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAexD;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAgDzD;AAcD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAI5E"}

package/dist/project-resolver.js

@@ -0,0 +1,271 @@
+/**
+ * mates-fullstack — project-resolver.ts
+ *
+ * Convention-based project path resolution. No mates.config.ts needed.
+ *
+ * The framework infers all paths from the project folder structure:
+ *
+ *   my-app/
+ *   ├── client/
+ *   │   ├── components/
+ *   │   ├── styles/
+ *   │   ├── App.ts        ← root SPA component with Router()
+ *   │   └── client.ts     ← browser hydration entry point
+ *   ├── server/
+ *   │   ├── api/          ← RPC functions
+ *   │   ├── socket/       ← WebSocket handlers
+ *   │   ├── helpers/      ← server-only utilities (never scanned)
+ *   │   └── main.ts       ← per-request middleware hook
+ *   ├── shared/
+ *   │   └── types/        ← shared TypeScript types
+ *   └── public/           ← static assets
+ *
+ * All paths are absolute. Missing directories are null — the framework
+ * gracefully disables the corresponding feature rather than crashing.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { devWarn } from "./log.js";
+// ─── Resolver ─────────────────────────────────────────────────────────────────
+/**
+ * Resolve all project paths from the project root.
+ *
+ * @param projectRoot - Absolute path to the project root.
+ *   Usually the result of findProjectRoot(process.cwd()).
+ */
+export function resolveProjectPaths(projectRoot) {
+    const abs = (...parts) => path.resolve(projectRoot, ...parts);
+    // ── client/ ──────────────────────────────────────────────────────────────────────
+    const appFile = _existsFile(abs("client", "App.ts"))
+        ? abs("client", "App.ts")
+        : _existsFile(abs("client", "App.js"))
+            ? abs("client", "App.js")
+            : null;
+    const clientEntry = _existsFile(abs("client", "client.ts"))
+        ? abs("client", "client.ts")
+        : _existsFile(abs("client", "client.js"))
+            ? abs("client", "client.js")
+            : null;
+    // ── server/ ───────────────────────────────────────────────────────────────
+    const apiDir = _existsDir(abs("server", "api")) ? abs("server", "api") : null;
+    const socketDir = _existsDir(abs("server", "socket"))
+        ? abs("server", "socket")
+        : null;
+    const helpersDir = _existsDir(abs("server", "helpers"))
+        ? abs("server", "helpers")
+        : null;
+    const mainFile = _existsFile(abs("server", "main.ts"))
+        ? abs("server", "main.ts")
+        : _existsFile(abs("server", "main.js"))
+            ? abs("server", "main.js")
+            : null;
+    // ── shared/ ───────────────────────────────────────────────────────────────
+    const sharedDir = _existsDir(abs("shared")) ? abs("shared") : null;
+    const sharedTypesDir = _existsDir(abs("shared", "types"))
+        ? abs("shared", "types")
+        : null;
+    // ── public/ ───────────────────────────────────────────────────────────────
+    const publicDir = _existsDir(abs("public")) ? abs("public") : null;
+    // ── dist/ (always resolved, may not exist yet) ────────────────────────────
+    const outDir = abs("dist");
+    // ── Port ──────────────────────────────────────────────────────────────────
+    const port = _resolvePort();
+    return {
+        projectRoot,
+        appFile,
+        clientEntry,
+        publicDir,
+        apiDir,
+        socketDir,
+        helpersDir,
+        mainFile,
+        sharedDir,
+        sharedTypesDir,
+        outDir,
+        port,
+    };
+}
+export function resolveProductionRuntimePaths(sourcePaths) {
+    const serverDir = path.join(sourcePaths.outDir, "server");
+    const publicDir = path.join(sourcePaths.outDir, "public");
+    const appFile = path.join(serverDir, "App.js");
+    const mainFile = path.join(serverDir, "main.js");
+    const apiDir = path.join(serverDir, "api");
+    const socketDir = path.join(serverDir, "socket");
+    const sharedDir = path.join(serverDir, "shared");
+    const sharedTypesDir = path.join(sharedDir, "types");
+    return {
+        ...sourcePaths,
+        appFile: _existsFile(appFile) ? appFile : null,
+        publicDir: _existsDir(publicDir) ? publicDir : null,
+        apiDir: _existsDir(apiDir) ? apiDir : null,
+        socketDir: _existsDir(socketDir) ? socketDir : null,
+        helpersDir: null,
+        mainFile: _existsFile(mainFile) ? mainFile : null,
+        sharedDir: _existsDir(sharedDir) ? sharedDir : null,
+        sharedTypesDir: _existsDir(sharedTypesDir) ? sharedTypesDir : null,
+    };
+}
+/**
+ * Walk up from `startDir` until a directory containing `package.json` is found.
+ * Returns the absolute path to that directory.
+ *
+ * @throws Error if no package.json is found before the filesystem root.
+ */
+export function findProjectRoot(startDir) {
+    let current = path.resolve(startDir);
+    while (true) {
+        if (_existsFile(path.join(current, "package.json"))) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        // Reached filesystem root without finding package.json
+        if (parent === current) {
+            throw new Error(`mates-fullstack: could not find package.json in "${startDir}" or any parent directory.\n` +
+                `Make sure you are running from inside your project.`);
+        }
+        current = parent;
+    }
+}
+// ─── Startup warnings ─────────────────────────────────────────────────────────
+/**
+ * Log warnings for missing directories that affect core features.
+ * Called once at startup after resolving paths.
+ */
+export function warnMissingPaths(paths, log) {
+    if (!paths.appFile) {
+        log("warn: client/App.ts not found — SSR is disabled. " +
+            "Create client/App.ts with your root Router() component.");
+    }
+    if (!paths.clientEntry) {
+        log("warn: client/client.ts not found — no browser entry point. " +
+            "Create client/client.ts that calls renderX(App, ...).");
+    }
+    if (!paths.apiDir) {
+        log("warn: server/api/ not found — RPC functions are disabled. " +
+            "Create server/api/ to define server functions.");
+    }
+}
+// ─── Path utilities ───────────────────────────────────────────────────────────
+/**
+ * Returns a human-readable summary of resolved paths for startup logging.
+ */
+export function formatPaths(paths) {
+    const lines = [
+        `  project root : ${paths.projectRoot}`,
+        `  port         : ${paths.port}`,
+        `  app          : ${paths.appFile ?? "(SSR disabled)"}`,
+        `  client entry : ${paths.clientEntry ?? "(not found)"}`,
+        `  api (RPC)    : ${paths.apiDir ?? "(disabled)"}`,
+        `  socket       : ${paths.socketDir ?? "(none)"}`,
+        `  helpers      : ${paths.helpersDir ?? "(none)"}`,
+        `  main.ts      : ${paths.mainFile ?? "(none)"}`,
+        `  shared       : ${paths.sharedDir ?? "(none)"}`,
+        `  public       : ${paths.publicDir ?? "(none)"}`,
+        `  out          : ${paths.outDir}`,
+    ];
+    return lines.join("\n");
+}
+/**
+ * Resolve the path to the mates package in the project's node_modules.
+ *
+ * Tries multiple resolution strategies:
+ * 1. projectRoot/node_modules/mates/dist/index.esm.js
+ * 2. Standard Node.js module resolution from projectRoot
+ * 3. Standard Node.js module resolution from __dirname (mates-fullstack itself)
+ *
+ * @throws Error if mates cannot be found.
+ */
+export function findMatesPath(projectRoot) {
+    // Find mates package.json, then use the ESM entry (module field) if available.
+    // Using the same file that user ESM code resolves to is critical for module identity —
+    // two different file paths = two different module instances = hooks break.
+    const pkgJsonPath = _findPackageJson("mates", projectRoot);
+    if (pkgJsonPath) {
+        const pkgDir = path.dirname(pkgJsonPath);
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+            // Prefer ESM entry: exports["."]["import"] > module > main
+            const esmEntry = pkg.exports?.["."]?.["import"] ?? pkg.module ?? pkg.main;
+            if (esmEntry) {
+                const resolved = path.resolve(pkgDir, esmEntry);
+                if (_existsFile(resolved)) {
+                    // Resolve symlinks — critical for module identity in ESM cache
+                    try {
+                        return fs.realpathSync(resolved);
+                    }
+                    catch {
+                        return resolved;
+                    }
+                }
+            }
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    // Fallback: look for ESM dist directly
+    const direct = path.join(projectRoot, "node_modules", "mates", "dist", "index.esm.js");
+    if (_existsFile(direct))
+        return direct;
+    // Fallback: resolve CJS from mates-fullstack's location
+    try {
+        return require.resolve("mates");
+    }
+    catch {
+        /* fall through */
+    }
+    throw new Error(`mates-fullstack: could not find the "mates" package.\n` +
+        `Make sure mates is installed: npm install mates`);
+}
+function _findPackageJson(pkgName, fromDir) {
+    const candidates = [
+        path.join(fromDir, "node_modules", pkgName, "package.json"),
+        path.join(fromDir, "..", "node_modules", pkgName, "package.json"),
+        path.join(fromDir, "..", "..", "node_modules", pkgName, "package.json"),
+    ];
+    for (const c of candidates) {
+        if (_existsFile(path.resolve(c)))
+            return path.resolve(c);
+    }
+    return null;
+}
+/**
+ * Returns true if `suspectedChild` is inside `parent`.
+ * Used to prevent path traversal attacks in static file serving.
+ */
+export function isPathInside(parent, suspectedChild) {
+    const rel = path.relative(parent, suspectedChild);
+    // If the relative path starts with ".." or is absolute, it's outside
+    return !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+function _existsDir(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function _existsFile(p) {
+    try {
+        return fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function _resolvePort() {
+    const envPort = process.env.PORT;
+    if (envPort) {
+        const parsed = parseInt(envPort, 10);
+        if (!isNaN(parsed) && parsed > 0 && parsed < 65536) {
+            return parsed;
+        }
+        // Invalid PORT env var — warn and fall through to default
+        devWarn(`invalid PORT="${envPort}" — using default 3000`);
+    }
+    return 3000;
+}
+//# sourceMappingURL=project-resolver.js.map

package/dist/project-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-resolver.js","sourceRoot":"","sources":["../src/project-resolver.ts"],"names":[],"mappings":"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"}

package/dist/rate-limit.d.ts

@@ -0,0 +1,37 @@
+import type { Context } from "./ctx.js";
+export interface RateLimitOptions {
+    /** Maximum requests allowed per window. */
+    max: number;
+    /** Window size. Number = seconds. String = "30s", "1m", "15m", "1h", "1d". Default: "1m". */
+    window?: number | string;
+    /**
+     * Derive a rate-limit key from the context.
+     * Default: client IP from X-Forwarded-For / X-Real-IP headers.
+     */
+    key?: (c: Context) => string;
+    /** Error message when limit is exceeded. Default: "Too many requests". */
+    message?: string;
+    /** HTTP status code when limit is exceeded. Default: 429. */
+    statusCode?: number;
+    /**
+     * Only apply rate limiting to requests whose path starts with this prefix.
+     * When omitted, all requests are rate-limited.
+     *
+     * @example pathPrefix: "/auth" — only limit OAuth and login routes
+     */
+    pathPrefix?: string;
+}
+/**
+ * Register a sliding-window rate limiter for all (or prefixed) requests.
+ *
+ * Call once at module level in server/main.ts.
+ *
+ * @example
+ * // Limit all requests to 100 per minute per IP
+ * rateLimit({ max: 100, window: "1m" });
+ *
+ * // Tighter limit on auth routes
+ * rateLimit({ max: 10, window: "15m", pathPrefix: "/auth" });
+ */
+export declare function rateLimit(options: RateLimitOptions): void;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,6FAA6F;IAC7F,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,CAAC;IAC7B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAOD;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAmDzD"}

package/dist/rate-limit.js

@@ -0,0 +1,109 @@
+import { onRequest } from "./middleware.js";
+/**
+ * Register a sliding-window rate limiter for all (or prefixed) requests.
+ *
+ * Call once at module level in server/main.ts.
+ *
+ * @example
+ * // Limit all requests to 100 per minute per IP
+ * rateLimit({ max: 100, window: "1m" });
+ *
+ * // Tighter limit on auth routes
+ * rateLimit({ max: 10, window: "15m", pathPrefix: "/auth" });
+ */
+export function rateLimit(options) {
+    const windowMs = parseWindow(options.window ?? "1m") * 1000;
+    const max = options.max;
+    const message = options.message ?? "Too many requests";
+    const statusCode = options.statusCode ?? 429;
+    const pathPrefix = options.pathPrefix;
+    const getKey = options.key ?? defaultKey;
+    const store = new Map();
+    onRequest((c) => {
+        if (pathPrefix) {
+            const pathname = new URL(c.req.raw.url).pathname;
+            if (!pathname.startsWith(pathPrefix))
+                return;
+        }
+        const key = getKey(c);
+        const now = Date.now();
+        let record = store.get(key);
+        if (!record || now > record.resetAt) {
+            record = { count: 0, resetAt: now + windowMs };
+            store.set(key, record);
+        }
+        record.count++;
+        // Evict expired entries when the store grows large
+        if (store.size > 10000) {
+            for (const [k, v] of store) {
+                if (now > v.resetAt)
+                    store.delete(k);
+            }
+        }
+        const remaining = Math.max(0, max - record.count);
+        const resetSecs = Math.ceil(record.resetAt / 1000);
+        const retryAfter = Math.ceil((record.resetAt - now) / 1000);
+        if (record.count > max) {
+            return new Response(JSON.stringify({ error: message }), {
+                status: statusCode,
+                headers: {
+                    "content-type": "application/json",
+                    "retry-after": String(retryAfter),
+                    "x-ratelimit-limit": String(max),
+                    "x-ratelimit-remaining": "0",
+                    "x-ratelimit-reset": String(resetSecs),
+                },
+            });
+        }
+    });
+}
+function defaultKey(c) {
+    // Only trust forwarding headers when trustProxy is enabled.
+    // Otherwise, attackers can spoof their rate-limit identity.
+    if (c.trustProxy) {
+        const forwarded = c.reqHeaders["x-forwarded-for"];
+        if (forwarded)
+            return forwarded.split(",")[0].trim();
+        const realIp = c.reqHeaders["x-real-ip"];
+        if (realIp)
+            return realIp.trim();
+        const cfIp = c.reqHeaders["cf-connecting-ip"];
+        if (cfIp)
+            return cfIp.trim();
+    }
+    // Fallback: socket remote address
+    try {
+        // Access the raw Node.js IncomingMessage's socket address
+        const raw = c.req?.raw;
+        if (raw && typeof raw === "object") {
+            if (typeof raw.socket?.remoteAddress === "string") {
+                return raw.socket.remoteAddress;
+            }
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return "unknown";
+}
+function parseWindow(value) {
+    if (typeof value === "number")
+        return Math.floor(value);
+    const str = value.trim();
+    if (/^\d+$/.test(str))
+        return Number(str);
+    const match = str.match(/^(\d+(?:\.\d+)?)\s*(s|m|h|d)$/i);
+    if (!match) {
+        throw new Error(`[mates-fullstack] rateLimit: invalid window "${value}". Use a number (seconds) or a string like "30s", "15m", "1h".`);
+    }
+    const amount = Number(match[1]);
+    const unit = match[2].toLowerCase();
+    const multipliers = {
+        s: 1,
+        m: 60,
+        h: 3600,
+        d: 86400,
+    };
+    return Math.floor(amount * multipliers[unit]);
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"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"}