Mount plugin routes via the router (todo §2); match method+path under /<id>, resolve :params, permission gate, RouteResult→response

src/app.test.ts

@@ -1,12 +1,13 @@
 import assert from "node:assert/strict";
-import { cpSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import type { AddressInfo } from "node:net";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
-import { after, before, test } from "node:test";
+import { after, before, test, type TestContext } from "node:test";
 import { fileURLToPath } from "node:url";
 import * as ejs from "ejs";
 import { createApp } from "./app.ts";
+import type { Plugin } from "./plugin.ts";
 import { contentTypeFor, resolveStaticPath } from "./static.ts";
 
 const viewsDir = join(dirname(fileURLToPath(import.meta.url)), "..", "views");
@@ -97,6 +98,61 @@ test("renders the 403 error page as HTML", async () => {
   assert.match(html, /styles\.css/);
 });
 
+// A test plugin exercising each RouteResult shape, a path param, and the permission gate.
+const demoPlugin: Plugin = {
+  apiVersion: "1.0.0",
+  id: "demo",
+  routes: [
+    { handler: (ctx) => ({ html: `<p>Hi ${ctx.params.name}</p>` }), method: "GET", path: "/hello/:name" },
+    { handler: () => ({ json: { ok: true } }), method: "GET", path: "/data" },
+    { handler: () => ({ redirect: "/demo/hello/world" }), method: "POST", path: "/go" },
+    { handler: () => ({ html: "secret" }), method: "GET", path: "/secret", permission: "demo:read" },
+    { handler: () => ({ data: { who: "Plainpages" }, view: "page" }), method: "GET", path: "/page" },
+  ],
+};
+
+async function startApp(t: TestContext, plugins: Plugin[], pluginsDir?: string): Promise<string> {
+  const app = createApp(pluginsDir ? { plugins, pluginsDir } : { plugins });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  return `http://localhost:${(app.address() as AddressInfo).port}`;
+}
+
+test("mounts plugin routes: params, html/json/redirect/view results, and the permission gate", async (t) => {
+  const dir = mkdtempSync(join(tmpdir(), "pp-plugins-"));
+  mkdirSync(join(dir, "demo", "views"), { recursive: true });
+  writeFileSync(join(dir, "demo", "views", "page.ejs"), "<h1>Hello <%= who %></h1>");
+  t.after(() => rmSync(dir, { force: true, recursive: true }));
+  const url = await startApp(t, [demoPlugin], dir);
+
+  // Path param + html
+  const hi = await fetch(url + "/demo/hello/world");
+  assert.equal(hi.status, 200);
+  assert.match(await hi.text(), /Hi world/);
+
+  // json
+  const data = await fetch(url + "/demo/data");
+  assert.match(data.headers.get("content-type") ?? "", /application\/json/);
+  assert.deepEqual(await data.json(), { ok: true });
+
+  // redirect (POST → 303 Location)
+  const go = await fetch(url + "/demo/go", { method: "POST", redirect: "manual" });
+  assert.equal(go.status, 303);
+  assert.equal(go.headers.get("location"), "/demo/hello/world");
+
+  // view rendered from the plugin's own views/
+  assert.match(await (await fetch(url + "/demo/page")).text(), /Hello Plainpages/);
+
+  // gated route with no session → 403
+  assert.equal((await fetch(url + "/demo/secret")).status, 403);
+
+  // known path + wrong method → 405 with Allow; unknown path → 404
+  const wrong = await fetch(url + "/demo/data", { method: "DELETE" });
+  assert.equal(wrong.status, 405);
+  assert.match(wrong.headers.get("allow") ?? "", /GET/);
+  assert.equal((await fetch(url + "/demo/nope")).status, 404);
+});
+
 test("rejects unsafe static request paths (encoded traversal, NUL) with 403", async () => {
   assert.equal((await fetch(base + "/public/..%2f..%2fapp.ts")).status, 403);
   assert.equal((await fetch(base + "/public/%00")).status, 403);

src/app.ts

@@ -4,6 +4,9 @@ import { fileURLToPath } from "node:url";
 import * as ejs from "ejs";
 import { buildContext } from "./context.ts";
 import { buildDashboardModel } from "./dashboard.ts";
+import { PLUGINS_DIR } from "./discovery.ts";
+import type { Plugin, RouteResult } from "./plugin.ts";
+import { allowedMethods, isAuthorized, matchRoute } from "./router.ts";
 import { serveStatic } from "./static.ts";
 
 const rootDir = join(dirname(fileURLToPath(import.meta.url)), "..");
@@ -12,18 +15,27 @@ export interface AppOptions {
   // Cache compiled templates; caller decides (server passes config.cacheTemplates).
   // Off by default so edits show live; the app itself never inspects the environment.
   cache?: boolean;
+  plugins?: Plugin[]; // discovered manifests to mount (router); empty until §2 discovery runs
+  pluginsDir?: string; // where plugin views/static live; defaults to the scanned plugins/
   publicDir?: string;
   viewsDir?: string;
 }
 
 export function createApp(options: AppOptions = {}): Server {
   const cache = options.cache ?? false;
+  const plugins = options.plugins ?? [];
+  const pluginsDir = options.pluginsDir ?? PLUGINS_DIR;
   const publicDir = options.publicDir ?? join(rootDir, "public");
   const viewsDir = options.viewsDir ?? join(rootDir, "views");
 
   const render = (view: string, data: Record<string, unknown>): Promise<string> =>
     ejs.renderFile(join(viewsDir, `${view}.ejs`), data, { cache });
 
+  // A `view` RouteResult resolves against the plugin's own views/ (the richer per-plugin
+  // resolver — core-partial includes, subfolders — is the next §2 item).
+  const renderPluginView = (plugin: Plugin) => (view: string, data: Record<string, unknown>): Promise<string> =>
+    ejs.renderFile(join(pluginsDir, plugin.id, "views", `${view}.ejs`), data, { cache });
+
   const sendHtml = (res: ServerResponse, status: number, html: string): void => {
     res.writeHead(status, { "content-type": "text/html; charset=utf-8" });
     res.end(html);
@@ -31,27 +43,40 @@ export function createApp(options: AppOptions = {}): Server {
 
   return createServer(async (req, res) => {
     try {
-      if (req.method !== "GET" && req.method !== "HEAD") {
-        res.writeHead(405, { "content-type": "text/plain; charset=utf-8" }).end("Method Not Allowed");
-        return;
-      }
-
-      // The request shape handlers receive (§2/§4 router passes it on); routing
-      // reuses its parsed URL instead of building a throwaway.
+      const method = req.method ?? "GET";
       const { url } = buildContext(req, res);
       const pathname = url.pathname;
 
-      if (pathname.startsWith("/public/")) {
-        await serveStatic(publicDir, pathname.slice("/public/".length), res, req.method === "HEAD");
+      if (pathname.startsWith("/public/") && (method === "GET" || method === "HEAD")) {
+        await serveStatic(publicDir, pathname.slice("/public/".length), res, method === "HEAD");
         return;
       }
 
-      if (pathname === "/") {
-        // Mock data + no roles until the plugin host (§2) and auth (§4) land.
+      // Plugin routes (any method): gate on the route's permission, then run the handler.
+      const match = matchRoute(plugins, method, pathname);
+      if (match) {
+        const ctx = buildContext(req, res, { params: match.params });
+        if (!isAuthorized(match.route, ctx.roles)) {
+          sendHtml(res, 403, await render("403", { title: "Forbidden" }));
+          return;
+        }
+        const result = await match.route.handler(ctx);
+        await sendResult(res, result ?? null, renderPluginView(match.plugin));
+        return;
+      }
+
+      if (pathname === "/" && (method === "GET" || method === "HEAD")) {
+        // Mock data + no roles until auth (§4) lands.
         sendHtml(res, 200, await render("index", { model: buildDashboardModel(url) }));
         return;
       }
 
+      // Known path, wrong method → 405 with Allow; otherwise nothing here → 404.
+      const allow = allowedMethods(plugins, pathname);
+      if (allow.length) {
+        res.writeHead(405, { allow: allow.join(", "), "content-type": "text/plain; charset=utf-8" }).end("Method Not Allowed");
+        return;
+      }
       sendHtml(res, 404, await render("404", { title: "Not found" }));
     } catch (err) {
       console.error(err);
@@ -67,3 +92,23 @@ export function createApp(options: AppOptions = {}): Server {
     }
   });
 }
+
+type ViewRenderer = (view: string, data: Record<string, unknown>) => Promise<string>;
+
+// Turn a handler's RouteResult into the HTTP response. `null` = the handler took over `ctx.res`
+// itself (the void escape hatch). Author `headers` override the content-type default.
+async function sendResult(res: ServerResponse, result: RouteResult | null, renderView: ViewRenderer): Promise<void> {
+  if (result == null || res.writableEnded) return;
+  if ("redirect" in result) {
+    res.writeHead(result.status ?? 303, { location: result.redirect }).end();
+    return;
+  }
+  if ("json" in result) {
+    res.writeHead(result.status ?? 200, { "content-type": "application/json; charset=utf-8", ...result.headers });
+    res.end(JSON.stringify(result.json));
+    return;
+  }
+  const body = "html" in result ? result.html : await renderView(result.view, result.data ?? {});
+  res.writeHead(result.status ?? 200, { "content-type": "text/html; charset=utf-8", ...result.headers });
+  res.end(body); // Node suppresses the body for HEAD automatically
+}

src/plugin.ts

@@ -183,8 +183,9 @@ function collectNavIds(nodes: NavNode[] | undefined, push: (id: string) => void)
   }
 }
 
-// A route's full path = the plugin's mount path `/<id>` + the route path.
-function fullPath(id: string, path: string): string {
+// A route's full path = the plugin's mount path `/<id>` + the route path. The single source of
+// truth for both conflict detection (here) and the §2 router, so they can't disagree.
+export function fullPath(id: string, path: string): string {
   return `/${id}${path.startsWith("/") ? path : `/${path}`}`;
 }
 

src/router.test.ts

@@ -0,0 +1,65 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import type { Plugin, Route } from "./plugin.ts";
+import { allowedMethods, isAuthorized, matchRoute } from "./router.ts";
+
+const noop: Route["handler"] = () => ({ html: "x" });
+
+// Minimal discovered Plugin — only id + routes matter to the router.
+function plugin(id: string, routes: Route[]): Plugin {
+  return { apiVersion: "1.0.0", id, routes };
+}
+
+test("matchRoute matches method + full path under /<id>, resolves params, HEAD falls back to GET", () => {
+  const plugins = [
+    plugin("scheduling", [
+      { handler: noop, method: "GET", path: "/shifts" },
+      { handler: noop, method: "GET", path: "/shifts/:id" },
+      { handler: noop, method: "POST", path: "/shifts" },
+    ]),
+  ];
+  assert.equal(matchRoute(plugins, "GET", "/scheduling/shifts")?.route.method, "GET");
+  assert.deepEqual(matchRoute(plugins, "GET", "/scheduling/shifts/42")?.params, { id: "42" });
+  assert.equal(matchRoute(plugins, "POST", "/scheduling/shifts")?.route.method, "POST");
+  // HEAD is answered by the GET route; PUT (no route) and an unknown path miss.
+  assert.equal(matchRoute(plugins, "HEAD", "/scheduling/shifts")?.route.method, "GET");
+  assert.equal(matchRoute(plugins, "PUT", "/scheduling/shifts"), null);
+  assert.equal(matchRoute(plugins, "GET", "/scheduling/missing"), null);
+});
+
+test("matchRoute decodes percent-encoded params and rejects malformed encoding", () => {
+  const plugins = [plugin("users", [{ handler: noop, method: "GET", path: "/:id" }])];
+  assert.deepEqual(matchRoute(plugins, "GET", "/users/john%40doe")?.params, { id: "john@doe" });
+  assert.equal(matchRoute(plugins, "GET", "/users/%ZZ"), null);
+});
+
+test("matchRoute prefers the most specific (fewest-param) pattern over a param catch-all", () => {
+  const plugins = [
+    plugin("users", [
+      { handler: noop, method: "GET", path: "/:id" }, // declared first, still loses to the literal
+      { handler: noop, method: "GET", path: "/new" },
+    ]),
+  ];
+  assert.equal(matchRoute(plugins, "GET", "/users/new")?.route.path, "/new");
+  assert.equal(matchRoute(plugins, "GET", "/users/123")?.route.path, "/:id");
+});
+
+test("allowedMethods lists methods at a path (GET implies HEAD); empty when the path is unknown", () => {
+  const plugins = [
+    plugin("x", [
+      { handler: noop, method: "GET", path: "/a" },
+      { handler: noop, method: "POST", path: "/a" },
+    ]),
+  ];
+  assert.deepEqual(allowedMethods(plugins, "/x/a"), ["GET", "HEAD", "POST"]);
+  assert.deepEqual(allowedMethods(plugins, "/x/missing"), []);
+});
+
+test("isAuthorized: open routes pass; gated routes require the role token", () => {
+  const open: Route = { handler: noop, method: "GET", path: "/" };
+  const gated: Route = { handler: noop, method: "GET", path: "/", permission: "x:read" };
+  assert.equal(isAuthorized(open, []), true);
+  assert.equal(isAuthorized(gated, []), false);
+  assert.equal(isAuthorized(gated, ["x:read"]), true);
+  assert.equal(isAuthorized(gated, ["other"]), false);
+});

src/router.ts

@@ -0,0 +1,83 @@
+// Router (todo §2): the pure core that maps an incoming method + pathname to a discovered
+// plugin route. I/O-free — app.ts is the imperative shell that builds the context, runs the
+// gate, calls the handler, and turns its RouteResult into an HTTP response. A route is mounted
+// at `/<id>` + its path (fullPath, shared with conflict detection); `:name` segments become
+// path params. Specificity: a literal segment beats a `:param`, so /users/new wins over
+// /users/:id regardless of declaration order.
+
+import { fullPath, type Plugin, type Route } from "./plugin.ts";
+
+export interface RouteMatch {
+  params: Record<string, string>;
+  plugin: Plugin;
+  route: Route;
+}
+
+function segments(path: string): string[] {
+  return path.split("/").filter(Boolean);
+}
+
+function paramCount(path: string): number {
+  return segments(path).filter((s) => s.startsWith(":")).length;
+}
+
+// Match a concrete pathname's segments against a route pattern's; return the params or null.
+function matchSegments(pattern: string[], path: string[]): Record<string, string> | null {
+  if (pattern.length !== path.length) return null;
+  const params: Record<string, string> = {};
+  for (let i = 0; i < pattern.length; i++) {
+    const pat = pattern[i] as string;
+    const seg = path[i] as string;
+    if (pat.startsWith(":")) {
+      try {
+        params[pat.slice(1)] = decodeURIComponent(seg);
+      } catch {
+        return null; // malformed %-encoding → no match
+      }
+    } else if (pat !== seg) {
+      return null;
+    }
+  }
+  return params;
+}
+
+// Every plugin route whose path pattern matches `pathname`, regardless of method, with params.
+function matchPath(plugins: Plugin[], pathname: string): RouteMatch[] {
+  const path = segments(pathname);
+  const out: RouteMatch[] = [];
+  for (const plugin of plugins) {
+    for (const route of plugin.routes ?? []) {
+      const params = matchSegments(segments(fullPath(plugin.id, route.path)), path);
+      if (params) out.push({ params, plugin, route });
+    }
+  }
+  return out;
+}
+
+// The single route for `method` + `pathname`, or null. A GET route also answers HEAD. Among
+// matches the most specific (fewest `:param` segments) wins; ties keep discovery order (plugins
+// sorted by id, routes as declared) — sort is stable.
+export function matchRoute(plugins: Plugin[], method: string, pathname: string): RouteMatch | null {
+  const wanted = method.toUpperCase();
+  const candidates = matchPath(plugins, pathname).filter(
+    (m) => m.route.method === wanted || (wanted === "HEAD" && m.route.method === "GET"),
+  );
+  candidates.sort((a, b) => paramCount(a.route.path) - paramCount(b.route.path));
+  return candidates[0] ?? null;
+}
+
+// Methods allowed at `pathname` (for a 405 `Allow` header); empty when no route matches the path.
+export function allowedMethods(plugins: Plugin[], pathname: string): string[] {
+  const methods = new Set<string>();
+  for (const m of matchPath(plugins, pathname)) {
+    methods.add(m.route.method);
+    if (m.route.method === "GET") methods.add("HEAD");
+  }
+  return [...methods].sort();
+}
+
+// Coarse permission gate: a route with no `permission` is open; otherwise the user's roles (from
+// the session JWT, §4) must include the token. The same rule composeNav uses for the menu.
+export function isAuthorized(route: Route, roles: string[]): boolean {
+  return route.permission == null || roles.includes(route.permission);
+}

src/server.ts

@@ -4,10 +4,10 @@ import { discoverPlugins } from "./discovery.ts";
 
 const config = loadConfig(); // validates the env (incl. enforced secrets) — fails loud at boot
 
-const plugins = await discoverPlugins(); // scans plugins/, validates — fails loud on a bad plugin (router wiring is next §2)
+const plugins = await discoverPlugins(); // scans plugins/, validates — fails loud on a bad plugin
 console.log(`Discovered ${plugins.length} plugin(s)${plugins.length ? `: ${plugins.map((p) => p.id).join(", ")}` : ""}`);
 
-const server = createApp({ cache: config.cacheTemplates }).listen(config.port, () => {
+const server = createApp({ cache: config.cacheTemplates, plugins }).listen(config.port, () => {
   console.log(`Listening on http://localhost:${config.port}`);
 });