@spfn/core 0.3.0-beta.13 → 0.3.0-beta.15

package/README.md

@@ -122,8 +122,9 @@ the route map the RPC proxy needs — and nothing else.
 5. **Mount the RPC proxy** in Next.js as the `app/api/rpc/[routeName]/route.ts`
    catch-all. The browser only ever sends `GET` (no body) or `POST` (body or formData)
    to `/api/rpc/{routeName}`; the proxy looks up `routeMap[routeName]`, substitutes
-   `:params`, and forwards with the real method. Package route maps (`authRouteMap`,
-   `eventRouteMap`) merge into the same map.
+   `:params`, and forwards with the real method. The generated map already carries the
+   routes of the packages the app router mounts with `.packages()`; `eventRouteMap` is
+   merged by hand, being a constant rather than a mounted router.
 6. **Call it** through `createApi<AppRouter>()`. The client is a `Proxy` over the
    `AppRouter` type — typed in and out, with no runtime cost for the types. Errors
    arrive as `ApiError`, or as the original error class when that class is registered in
@@ -791,9 +792,10 @@ way so the endpoint never reveals that someone else's record exists.
 
 Other SPFN packages build on `@spfn/core`:
 
-- [`@spfn/auth`](../auth/README.md) — sessions, social login and RBAC. Exports
-  `authRouteMap` and registers proxy interceptors automatically; merge its route map into
-  `createRpcProxy`.
+- [`@spfn/auth`](../auth/README.md) — sessions, social login and RBAC. Mount `authRouter`
+  with `.packages()` and its routes are in the app's generated map; the package registers
+  proxy interceptors automatically. (`authRouteMap` is still exported, and merging it is
+  now a no-op.)
 - [`@spfn/mcp`](../mcp/README.md) — exposes your operations as MCP tools, so an agent can
   run them instead of you building an admin dashboard.
 - `@spfn/i18n`, `@spfn/storage`, `@spfn/notification`, `@spfn/cms`, `@spfn/monitor`,

package/dist/codegen/index.d.ts

@@ -302,6 +302,15 @@ interface GenerationStats {
  * 404s. Walking the loaded router registers exactly what `registerRoutes`
  * registers, whatever the source looks like.
  *
+ * The map carries the routes of every package router the app mounts with
+ * `.packages()`, not only the app's own. A package ships a client that addresses
+ * its routes by name — `authApi.login`, `monitorApi.getStats` — and the app's
+ * `createRpcProxy` resolves a name in the single map it was constructed with, so
+ * a package route in nobody's map is a call that resolves nowhere. The app
+ * therefore merges nothing by hand: `{ ...routeMap, ...authRouteMap }` is a
+ * no-op today and `{ ...routeMap }` is the whole of it. (`eventRouteMap` is the
+ * exception that stays — it is a hand-written constant, not a mounted router.)
+ *
  * @example
  * ```typescript
  * // .spfnrc.ts

package/dist/codegen/index.js

@@ -688,46 +688,99 @@ function loadRouter(cwd, absoluteRouterPath) {
   );
 }
 var HTTP_METHODS = { GET: true, POST: true, PUT: true, PATCH: true, DELETE: true };
-function addRoute(name, routeDef, trail, found) {
+function duplicateNameError(origin, name, existing, where) {
+  if (origin === "app") {
+    return new RouteMapGeneratorError(
+      `Two routes are both named "${name}" (${existing.trail} and ${where}). The RPC client addresses a route by its name alone, and a nested route registers under its own key, so a name must be unique across the whole router.`
+    );
+  }
+  return new RouteMapGeneratorError(
+    `Two package routers both register a route named "${name}" (${existing.trail} and ${where}). Both are written into this app's route map, which holds one entry per name, so one of the two packages would have its client call the other package's path. Nothing of this app's can be renamed to fix it: drop one of the two mounts, or raise the name with the package that took it second.`
+  );
+}
+function addRoute(name, routeDef, trail, into, origin) {
   const where = trail.join(".");
   if (!routeDef.method || !routeDef.path) {
     genLogger.warn(
       `Route "${where}" has no method or path and is left out of the map. The RPC client resolves a name to a method and a path, so both are required. A route reaches this state by being registered before .handler() was called \u2014 the server skips it too.`
     );
-    return;
+    return void 0;
   }
   if (!Object.hasOwn(HTTP_METHODS, routeDef.method)) {
     throw new RouteMapGeneratorError(
       `Route "${where}" declares the method "${routeDef.method}", which is not an HttpMethod (${Object.keys(HTTP_METHODS).join(", ")}). The generated map is typed HttpMethod, so naming it would write a file that does not compile.`
     );
   }
-  const existing = found.get(name);
+  const existing = into.get(name);
   if (existing) {
-    throw new RouteMapGeneratorError(
-      `Two routes are both named "${name}" (${existing.trail} and ${where}). The RPC client addresses a route by its name alone, and a nested route registers under its own key, so a name must be unique across the whole router.`
-    );
+    if (origin === "package" && existing.def === routeDef) {
+      return void 0;
+    }
+    throw duplicateNameError(origin, name, existing, where);
   }
-  found.set(name, { method: routeDef.method, path: routeDef.path, trail: where });
+  const collected = {
+    method: routeDef.method,
+    path: routeDef.path,
+    trail: where,
+    def: routeDef
+  };
+  into.set(name, collected);
+  return collected;
 }
-function collectPackageNames(router, trail, names) {
-  if (router._publishesRouteMap === false) {
+function pathPrefix(path) {
+  const [, first] = path.split("/");
+  return first ? `/${first}` : path;
+}
+function collectPackageRoutes(router, trail, mount, collection) {
+  if (router._publishesRouteMap === false || collection.visited.has(router)) {
     return;
   }
+  collection.visited.set(router, trail.join("."));
   for (const [name, entry] of Object.entries(router.routes)) {
     if (isRouter(entry)) {
-      collectPackageNames(entry, [...trail, name], names);
-    } else if (isRouteDef(entry) && !names.has(name)) {
-      names.set(name, [...trail, name].join("."));
+      collectPackageRoutes(entry, [...trail, name], mount, collection);
+      continue;
+    }
+    if (!isRouteDef(entry)) {
+      genLogger.warn(
+        `Package router entry "${[...trail, name].join(".")}" is neither a route nor a router (got ${typeof entry}) and is left out of the map. \`registerRoutes\` skips it too.`
+      );
+      continue;
+    }
+    const collected = addRoute(name, entry, [...trail, name], collection.packages, "package");
+    if (collected) {
+      mount.count += 1;
+      mount.prefixes.add(pathPrefix(collected.path));
+      continue;
+    }
+    const already = collection.packages.get(name);
+    if (already?.def === entry) {
+      mount.sharedWith ??= already.trail;
     }
   }
-  for (const [index, packageRouter] of (router._packageRouters ?? []).entries()) {
-    collectPackageNames(packageRouter, [...trail, `packages[${index}]`], names);
+  for (const [index, nested] of (router._packageRouters ?? []).entries()) {
+    collectPackageRoutes(nested, [...trail, `packages[${index}]`], mount, collection);
   }
 }
-function collectRoutes(router, trail, found, packageNames) {
+function mountPackageRouter(router, label, collection) {
+  const mount = { label, count: 0, prefixes: /* @__PURE__ */ new Set() };
+  const alreadyAt = collection.visited.get(router);
+  if (router._publishesRouteMap === false) {
+    mount.skipped = "publishes no route map";
+  } else if (alreadyAt) {
+    mount.skipped = `already reached through ${alreadyAt}`;
+  }
+  collectPackageRoutes(router, [label], mount, collection);
+  if (mount.count === 0 && !mount.skipped && mount.sharedWith) {
+    mount.skipped = `every route it holds was already collected through ${mount.sharedWith}`;
+  }
+  collection.mounts.push(mount);
+  return mount;
+}
+function collectRoutes(router, trail, collection) {
   for (const [name, entry] of Object.entries(router.routes)) {
     if (isRouter(entry)) {
-      collectRoutes(entry, [...trail, name], found, packageNames);
+      collectRoutes(entry, [...trail, name], collection);
       continue;
     }
     if (!isRouteDef(entry)) {
@@ -736,29 +789,33 @@ function collectRoutes(router, trail, found, packageNames) {
       );
       continue;
     }
-    addRoute(name, entry, [...trail, name], found);
+    addRoute(name, entry, [...trail, name], collection.app, "app");
   }
   for (const [index, packageRouter] of (router._packageRouters ?? []).entries()) {
-    collectPackageNames(packageRouter, [...trail, `packages[${index}]`], packageNames);
+    mountPackageRouter(packageRouter, `${trail.join(".")}.packages[${index}]`, collection);
   }
 }
-function assertNoPackageCollision(found, packageNames) {
-  for (const [name, where] of packageNames) {
-    const route = found.get(name);
-    if (!route) {
+function assertNoPackageCollision(collection) {
+  for (const [name, route] of collection.packages) {
+    const appRoute = collection.app.get(name);
+    if (!appRoute) {
       continue;
     }
     throw new RouteMapGeneratorError(
-      `The app route "${name}" (${route.trail}) is also registered by a package router (${where}). The app merges the two maps as { ...routeMap, ...packageRouteMap }, so the package entry wins the name at runtime while the generated types still describe the app's route \u2014 every call would go to the package's path. Rename the app route.`
+      `The app route "${name}" (${appRoute.trail}) is also registered by a package router (${route.trail}). Both go into this app's generated route map, which holds one entry per name, so one of the two paths becomes unreachable while the typed client still describes the app's route. Rename the app route.`
     );
   }
 }
 function collectRouteMap(router) {
-  const found = /* @__PURE__ */ new Map();
-  const packageNames = /* @__PURE__ */ new Map();
-  collectRoutes(router, ["router"], found, packageNames);
-  assertNoPackageCollision(found, packageNames);
-  return found;
+  const collection = {
+    app: /* @__PURE__ */ new Map(),
+    packages: /* @__PURE__ */ new Map(),
+    mounts: [],
+    visited: /* @__PURE__ */ new Map()
+  };
+  collectRoutes(router, ["router"], collection);
+  assertNoPackageCollision(collection);
+  return collection;
 }
 function toObjectKey(name) {
   if (name === "__proto__") {
@@ -773,7 +830,29 @@ function toStringLiteral(value) {
   }
   return JSON.stringify(value).replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
 }
-function generateRouteMapContent(routes, nodeEnv) {
+function describeMount(mount) {
+  if (mount.count === 0) {
+    return `${mount.label} \u2014 no routes${mount.skipped ? ` (${mount.skipped})` : ""}`;
+  }
+  const routes = `${mount.count} route${mount.count === 1 ? "" : "s"}`;
+  return `${mount.label} \u2014 ${routes} under ${[...mount.prefixes].join(", ")}`;
+}
+function packageHeaderLines(collection) {
+  if (collection.packages.size === 0) {
+    return [];
+  }
+  return [
+    " *",
+    " * The entries under the .packages() line below are not this app's. They belong",
+    " * to the package routers it mounts, copied in as they were when this file was",
+    " * generated:",
+    ...collection.mounts.map((mount) => ` *   ${describeMount(mount)}`),
+    " *",
+    " * A package upgrade reaches them only through a regeneration: `spfn build`",
+    " * regenerates before it compiles, a bare `next build` uses what is committed here."
+  ];
+}
+function generateRouteMapContent(collection, nodeEnv) {
   const lines = [
     "/**",
     " * Route Map (Auto-generated)",
@@ -783,6 +862,7 @@ function generateRouteMapContent(routes, nodeEnv) {
     ` * Generated with NODE_ENV=${nodeEnv}. A route registered only under one environment is`,
     " * named here only when the generator ran under it, so this line changing is that",
     " * difference rather than an edit.",
+    ...packageHeaderLines(collection),
     " */",
     "",
     "import type { HttpMethod } from '@spfn/core/route';",
@@ -795,8 +875,14 @@ function generateRouteMapContent(routes, nodeEnv) {
     "",
     "export const routeMap: Record<string, RouteInfo> = {"
   ];
-  for (const [name, route] of routes) {
-    lines.push(`    ${toObjectKey(name)}: { method: '${route.method}', path: ${toStringLiteral(route.path)} },`);
+  for (const [name, route] of collection.app) {
+    lines.push(entryLine(name, route));
+  }
+  if (collection.packages.size > 0) {
+    lines.push("    // From the package routers this app mounts with .packages(), not its own:");
+    for (const [name, route] of collection.packages) {
+      lines.push(entryLine(name, route));
+    }
   }
   lines.push("};");
   lines.push("");
@@ -806,6 +892,9 @@ function generateRouteMapContent(routes, nodeEnv) {
   lines.push("");
   return lines.join("\n");
 }
+function entryLine(name, route) {
+  return `    ${toObjectKey(name)}: { method: '${route.method}', path: ${toStringLiteral(route.path)} },`;
+}
 function createRouteMapGenerator(config) {
   const {
     routerPath,
@@ -853,17 +942,23 @@ Usage:
         exportName,
         subject: "route map"
       });
-      const routes = collectRouteMap(router);
+      const collection = collectRouteMap(router);
+      const total = collection.app.size + collection.packages.size;
       if (debug) {
-        genLogger.info(`Found ${routes.size} routes`, { names: [...routes.keys()] });
+        genLogger.info(`Found ${total} routes`, {
+          app: [...collection.app.keys()],
+          packages: [...collection.packages.keys()]
+        });
       }
       const outputDir = dirname(absoluteOutputPath);
       if (!existsSync(outputDir)) {
         mkdirSync(outputDir, { recursive: true });
       }
       const nodeEnv = process.env.NODE_ENV ?? "unset";
-      writeFileSync(absoluteOutputPath, generateRouteMapContent(routes, nodeEnv), "utf-8");
-      genLogger.info(`Generated route map: ${relative(cwd, absoluteOutputPath)} (${routes.size} routes)`);
+      writeFileSync(absoluteOutputPath, generateRouteMapContent(collection, nodeEnv), "utf-8");
+      genLogger.info(
+        `Generated route map: ${relative(cwd, absoluteOutputPath)} (${collection.app.size} app routes, ${collection.packages.size} from mounted packages)`
+      );
     }
   };
 }