@checkstack/backend 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # @checkstack/backend
 
+## 0.10.0
+
+### Minor Changes
+
+- 9016526: Add a `/rest/:pluginId/*` HTTP mount that serves every plugin's oRPC contract
+  through the REST/OpenAPI shape described by `/api/openapi.json`. Queries are
+  `GET` with query parameters, mutations are `POST` with the input as the raw
+  JSON body. The existing `/api/:pluginId/*` mount continues to serve oRPC's
+  native wire protocol unchanged, so existing clients are not affected.
+
+  The OpenAPI spec at `/api/openapi.json` now reflects the real mount: every
+  `paths` entry is prefixed with `/rest` instead of `/api`.
+
+  Also fixes a SPA-fallback bug: the backend's `/api-docs` route previously
+  returned 404 on production deployments because the static-file middleware
+  skipped any path starting with `/api`, capturing `/api-docs` along with real
+  API routes. The skip now requires a trailing slash (`/api/`, `/rest/`).
+
+  Required access rules are now visible in the API Docs UI. The OpenAPI spec
+  generator was reading a non-existent `accessRules` field on procedure
+  metadata; the real field is `access: AccessRule[]`. Each procedure's access
+  rules are now flattened to fully-qualified IDs (e.g. `catalog.system.read`)
+  and emitted under `x-orpc-meta.accessRules`, which the existing
+  `Required Access Rules` section in the docs UI already knew how to render.
+
+  The API Docs schema renderer now handles record types (zod `z.record`),
+  `$ref`s into `components.schemas`, `oneOf`/`anyOf`/`allOf`, nullable union
+  types (`type: ["string", "null"]`), and `format` qualifiers. Previously
+  record outputs like `{ statuses: object }` masked the actual value type;
+  they now render as `{ [key]: <ResolvedType> { ... } }` with the inner
+  schema expanded, capped at 12 levels with cycle detection.
+
+  **REST method conventions.** `proc()` now defaults to `GET` for queries and
+  `POST` for mutations on the `/rest` mount, using bracket-notation query
+  params (`?filter[status]=active&ids[0]=a`) for GET inputs. Existing
+  procedures were updated to follow REST semantics:
+
+  - `update*` mutations → `PATCH`
+  - `delete*` / `remove*` mutations → `DELETE`
+  - `getBulk*` queries and any query taking a large array input → `POST`
+    (because `@orpc/openapi@1.13.x` has no GET→POST URL-length fallback)
+
+  GET endpoints require an `object` input — bare scalars like
+  `.input(z.string())` are not valid on GET. `getSystemConfigurations` was
+  refactored from `.input(z.string())` to `.input(z.object({ systemId: ... }))`
+  to fit the GET shape; the only call-site update was the in-process router
+  unpacking `input.systemId` instead of passing `input` directly.
+
+  The API Docs UI now renders query parameters (path/query/header/cookie) in a
+  dedicated table for GET endpoints, and the fetch example shows them in the
+  URL with `<required>` / `<optional>` placeholders.
+
+### Patch Changes
+
+- Updated dependencies [9016526]
+  - @checkstack/common@0.10.0
+  - @checkstack/auth-common@0.7.0
+  - @checkstack/api-docs-common@0.1.13
+  - @checkstack/backend-api@0.15.2
+  - @checkstack/pluginmanager-common@0.2.2
+  - @checkstack/signal-backend@0.2.5
+  - @checkstack/signal-common@0.2.3
+  - @checkstack/cache-api@0.3.1
+  - @checkstack/queue-api@0.3.1
+
 ## 0.9.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "license": "Elastic-2.0",
   "checkstack": {
     "type": "backend"
@@ -14,16 +14,16 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/api-docs-common": "0.1.11",
-    "@checkstack/auth-common": "0.6.5",
-    "@checkstack/backend-api": "0.15.0",
-    "@checkstack/common": "0.8.0",
+    "@checkstack/api-docs-common": "0.1.12",
+    "@checkstack/auth-common": "0.6.6",
+    "@checkstack/backend-api": "0.15.1",
+    "@checkstack/common": "0.9.0",
     "@checkstack/drizzle-helper": "0.0.5",
-    "@checkstack/cache-api": "0.2.4",
-    "@checkstack/queue-api": "0.2.18",
-    "@checkstack/signal-backend": "0.2.3",
-    "@checkstack/signal-common": "0.2.1",
-    "@checkstack/pluginmanager-common": "0.2.0",
+    "@checkstack/cache-api": "0.3.0",
+    "@checkstack/queue-api": "0.3.0",
+    "@checkstack/signal-backend": "0.2.4",
+    "@checkstack/signal-common": "0.2.2",
+    "@checkstack/pluginmanager-common": "0.2.1",
     "@hono/zod-validator": "^0.7.6",
     "@orpc/client": "^1.13.14",
     "@orpc/contract": "^1.13.14",
@@ -45,8 +45,8 @@
     "@types/bun": "latest",
     "@types/semver": "^7.5.0",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.3.0",
-    "@checkstack/test-utils-backend": "0.1.24",
+    "@checkstack/scripts": "0.3.1",
+    "@checkstack/test-utils-backend": "0.1.25",
     "drizzle-kit": "^0.31.10"
   }
 }

package/src/index.ts

@@ -335,8 +335,13 @@ if (frontendDistPath && fs.existsSync(frontendDistPath)) {
   // Serve root-level static files (e.g., /favicon.svg) from the dist directory
   // before the SPA fallback, so they don't get caught by the index.html handler
   app.get("*", async (c, next) => {
-    // Skip API and WebSocket routes - let them pass through to actual handlers
-    if (c.req.path.startsWith("/api")) {
+    // Skip API and WebSocket routes - let them pass through to actual handlers.
+    // The trailing slash matters: `/api-docs` is a frontend route and must hit
+    // the SPA fallback below, while `/api/...` and `/rest/...` go to backend
+    // handlers (oRPC RPC + OpenAPI REST mounts).
+    const apiPath =
+      c.req.path.startsWith("/api/") || c.req.path.startsWith("/rest/");
+    if (apiPath) {
       return next();
     }
 

package/src/openapi-router.ts

@@ -10,6 +10,7 @@ import { ZodToJsonSchemaConverter } from "@orpc/zod/zod4";
 import type { AnyContractRouter } from "@orpc/contract";
 import type { PluginManager } from "./plugin-manager";
 import type { AuthService } from "@checkstack/backend-api";
+import type { AccessRule } from "@checkstack/common";
 
 /**
  * Check if a user has a specific access rule.
@@ -25,40 +26,57 @@ function hasAccess(
   );
 }
 
+/**
+ * Shape of the metadata we surface in the OpenAPI spec as `x-orpc-meta`.
+ * `accessRules` are the fully-qualified access rule IDs (e.g.
+ * `"catalog.system.read"`), flattened from each procedure's `access`
+ * AccessRule[] so doc consumers don't need to know the AccessRule shape.
+ */
+interface ExposedProcedureMeta {
+  userType?: string;
+  accessRules?: string[];
+}
+
 /**
  * Extract procedure metadata from a contract using oRPC internal structure.
+ * Returns the raw `meta` block stored on the contract procedure builder.
  */
-function extractProcedureMetadata(
+function extractRawProcedureMeta(
   contract: unknown
-): { userType?: string; accessRules?: string[] } | undefined {
+): { userType?: string; access?: AccessRule[] } | undefined {
   const orpcData = (contract as Record<string, unknown>)?.["~orpc"] as
-    | { meta?: { userType?: string; accessRules?: string[] } }
+    | { meta?: { userType?: string; access?: AccessRule[] } }
     | undefined;
   return orpcData?.meta;
 }
 
 /**
- * Build a lookup map of operationId -> metadata from all contracts.
- * operationId format: "pluginId.procedureName"
+ * Build a lookup map of operationId -> exposed metadata from all contracts.
+ * operationId format: "pluginId.procedureName".
+ *
+ * The procedure metadata stores `access` as AccessRule[]; we flatten it to
+ * `accessRules: string[]` of qualified IDs (`{pluginId}.{ruleId}`) so the
+ * OpenAPI consumer (API docs UI, third-party clients) gets a plain list.
  */
 function buildMetadataLookup(
   contracts: Map<string, AnyContractRouter>
-): Map<string, { userType?: string; accessRules?: string[] }> {
-  const lookup = new Map<
-    string,
-    { userType?: string; accessRules?: string[] }
-  >();
+): Map<string, ExposedProcedureMeta> {
+  const lookup = new Map<string, ExposedProcedureMeta>();
 
   for (const [pluginId, contract] of contracts) {
-    // Contract is an object with procedure names as keys
     for (const [procedureName, procedure] of Object.entries(
       contract as Record<string, unknown>
     )) {
-      const meta = extractProcedureMetadata(procedure);
-      if (meta) {
-        const operationId = `${pluginId}.${procedureName}`;
-        lookup.set(operationId, meta);
-      }
+      const raw = extractRawProcedureMeta(procedure);
+      if (!raw) continue;
+
+      const accessRules = raw.access?.map((rule) => `${pluginId}.${rule.id}`);
+
+      const operationId = `${pluginId}.${procedureName}`;
+      lookup.set(operationId, {
+        userType: raw.userType,
+        ...(accessRules && accessRules.length > 0 ? { accessRules } : {}),
+      });
     }
   }
 
@@ -107,13 +125,14 @@ export async function generateOpenApiSpec({
     >;
   };
 
-  // Post-process: Add x-orpc-meta to each operation and prefix paths with /api
+  // Post-process: Add x-orpc-meta to each operation and prefix paths with /rest.
+  // The REST handler is mounted at /rest/:pluginId/* (see api-router.ts);
+  // /api/:pluginId/* serves oRPC's native wire protocol, not REST.
   if (spec.paths) {
     const prefixedPaths: typeof spec.paths = {};
 
     for (const [path, methods] of Object.entries(spec.paths)) {
-      // Prefix path with /api
-      const prefixedPath = `/api${path.startsWith("/") ? path : `/${path}`}`;
+      const prefixedPath = `/rest${path.startsWith("/") ? path : `/${path}`}`;
       prefixedPaths[prefixedPath] = methods;
 
       // Add metadata to each operation

package/src/plugin-manager/api-router.ts

@@ -1,6 +1,7 @@
 import type { Hono, Context } from "hono";
 import type { SafeDatabase } from "@checkstack/backend-api";
 import { RPCHandler } from "@orpc/server/fetch";
+import { OpenAPIHandler } from "@orpc/openapi/fetch";
 import {
   coreServices,
   AuthService,
@@ -23,9 +24,182 @@ import type { PluginMetadata } from "@checkstack/common";
 import { rootLogger } from "../logger";
 import { extractErrorMessage } from "@checkstack/common";
 
+interface RouteHandlerDeps {
+  registry: ServiceRegistry;
+  pluginRpcRouters: Map<string, unknown>;
+  pluginMetadataRegistry: Map<string, PluginMetadata>;
+}
+
+interface ResolvedRequestContext {
+  context: RpcContext;
+  logger: Logger;
+}
+
+type ContextResult =
+  | { ok: true; resolved: ResolvedRequestContext }
+  | { ok: false; response: Response };
+
+function createServiceGetter(registry: ServiceRegistry) {
+  return async function getService<T>(ref: {
+    id: string;
+    T: T;
+  }): Promise<T | undefined> {
+    try {
+      return await registry.get(ref, { pluginId: "core" });
+    } catch {
+      return undefined;
+    }
+  };
+}
+
+/**
+ * Resolve auth + core services and build the per-request RpcContext.
+ * Shared between the oRPC `/api/*` handler and the REST `/rest/*` handler.
+ */
+async function resolveRequestContext({
+  c,
+  pluginId,
+  deps,
+}: {
+  c: Context;
+  pluginId: string;
+  deps: RouteHandlerDeps;
+}): Promise<ContextResult> {
+  const getService = createServiceGetter(deps.registry);
+  const pathname = new URL(c.req.raw.url).pathname;
+
+  const logger = await getService(coreServices.logger);
+  const auth = await getService(coreServices.auth);
+  const db = await getService(coreServices.database);
+  const fetch = await getService(coreServices.fetch);
+  const healthCheckRegistry = await getService(
+    coreServices.healthCheckRegistry,
+  );
+  const collectorRegistry = await getService(coreServices.collectorRegistry);
+  const queuePluginRegistry = await getService(
+    coreServices.queuePluginRegistry,
+  );
+  const queueManager = await getService(coreServices.queueManager);
+  const cachePluginRegistry = await getService(
+    coreServices.cachePluginRegistry,
+  );
+  const cacheManager = await getService(coreServices.cacheManager);
+  const eventBus = await getService(coreServices.eventBus);
+
+  if (
+    !auth ||
+    !logger ||
+    !db ||
+    !fetch ||
+    !healthCheckRegistry ||
+    !collectorRegistry ||
+    !queuePluginRegistry ||
+    !queueManager ||
+    !cachePluginRegistry ||
+    !cacheManager ||
+    !eventBus
+  ) {
+    const missing = [
+      !auth && "auth",
+      !logger && "logger",
+      !db && "db",
+      !fetch && "fetch",
+      !healthCheckRegistry && "healthCheckRegistry",
+      !collectorRegistry && "collectorRegistry",
+      !queuePluginRegistry && "queuePluginRegistry",
+      !queueManager && "queueManager",
+      !cachePluginRegistry && "cachePluginRegistry",
+      !cacheManager && "cacheManager",
+      !eventBus && "eventBus",
+    ]
+      .filter(Boolean)
+      .join(", ");
+    (logger ?? rootLogger).error(
+      `${pathname}: core services not initialized — missing: ${missing}`,
+    );
+    return {
+      ok: false,
+      response: c.json({ error: "Core services not initialized" }, 500),
+    };
+  }
+
+  const user = await (auth as AuthService).authenticate(c.req.raw);
+
+  const emitHook: EmitHookFn = async <T>(hook: Hook<T>, payload: T) => {
+    await (eventBus as EventBus).emit(hook, payload);
+  };
+
+  const pluginMetadata: PluginMetadata | undefined =
+    deps.pluginMetadataRegistry.get(pluginId);
+
+  if (!pluginMetadata) {
+    (logger as Logger).error(
+      `${pathname}: no plugin metadata registered for pluginId='${pluginId}'. ` +
+        `Regular plugins populate this during register(); core routers must call ` +
+        `pluginManager.registerCorePluginMetadata().`,
+    );
+    return {
+      ok: false,
+      response: c.json({ error: "Plugin metadata not found in registry" }, 500),
+    };
+  }
+
+  const context: RpcContext = {
+    pluginMetadata,
+    auth: auth as AuthService,
+    logger: logger as Logger,
+    db: db as SafeDatabase<Record<string, unknown>>,
+    fetch: fetch as Fetch,
+    healthCheckRegistry: healthCheckRegistry as HealthCheckRegistry,
+    collectorRegistry: collectorRegistry as CollectorRegistry,
+    queuePluginRegistry: queuePluginRegistry as QueuePluginRegistry,
+    queueManager: queueManager as QueueManager,
+    cachePluginRegistry: cachePluginRegistry as CachePluginRegistry,
+    cacheManager: cacheManager as CacheManager,
+    user,
+    emitHook,
+  };
+
+  return { ok: true, resolved: { context, logger: logger as Logger } };
+}
+
+function buildRpcRouter(
+  pluginRpcRouters: Map<string, unknown>,
+): Record<string, unknown> {
+  const rootRpcRouter: Record<string, unknown> = {};
+  for (const [pluginId, router] of pluginRpcRouters.entries()) {
+    rootRpcRouter[pluginId] = router;
+  }
+  return rootRpcRouter;
+}
+
+function logHandlerError({
+  error,
+  pathname,
+  logger,
+  protocolLabel,
+}: {
+  error: unknown;
+  pathname: string;
+  logger: Logger | undefined;
+  protocolLabel: string;
+}) {
+  const target = (logger ?? rootLogger) as Logger;
+  target.error(
+    `${protocolLabel} ${pathname} failed: ${extractErrorMessage(error)}`,
+  );
+  const stack =
+    error !== null && typeof error === "object" && "stack" in error
+      ? (error as { stack: string }).stack
+      : undefined;
+  if (stack) {
+    target.error(`Stack trace: ${stack}`);
+  }
+}
+
 /**
  * Creates the API route handler for Hono.
- * Extracted from PluginManager for better organization.
+ * Serves oRPC's native RPC wire protocol at /api/:pluginId/*.
  */
 export function createApiRouteHandler({
   registry,
@@ -38,54 +212,36 @@ export function createApiRouteHandler({
   pluginHttpHandlers: Map<string, (req: Request) => Promise<Response>>;
   pluginMetadataRegistry: Map<string, PluginMetadata>;
 }) {
-  // Helper to get service from registry
-  async function getService<T>(ref: {
-    id: string;
-    T: T;
-  }): Promise<T | undefined> {
-    try {
-      return await registry.get(ref, { pluginId: "core" });
-    } catch {
-      return undefined;
-    }
-  }
+  const deps: RouteHandlerDeps = {
+    registry,
+    pluginRpcRouters,
+    pluginMetadataRegistry,
+  };
 
   return async function handleApiRequest(c: Context) {
-    // Extract pluginId from Hono path parameter (/api/:pluginId/*)
     const pluginId = c.req.param("pluginId") || "";
     const pathname = new URL(c.req.raw.url).pathname;
 
-    // Build RPC handler lazily at request time
-    // This ensures all plugins registered during init are included
-    const rootRpcRouter: Record<string, unknown> = {};
-    for (const [pluginId, router] of pluginRpcRouters.entries()) {
-      rootRpcRouter[pluginId] = router;
-    }
-
-    // Resolve logger first for use in interceptor
-    const logger = await getService(coreServices.logger);
+    const result = await resolveRequestContext({ c, pluginId, deps });
+    if (!result.ok) return result.response;
+    const { context, logger } = result.resolved;
 
     const rpcHandler = new RPCHandler(
-      rootRpcRouter as ConstructorParameters<typeof RPCHandler>[0],
+      buildRpcRouter(pluginRpcRouters) as ConstructorParameters<
+        typeof RPCHandler
+      >[0],
       {
         interceptors: [
           async ({ next, ...rest }) => {
             try {
               return await next(rest);
             } catch (error) {
-              const target = (logger ?? rootLogger) as Logger;
-              target.error(
-                `RPC ${pathname} failed: ${extractErrorMessage(error)}`,
-              );
-              const stack =
-                error !== null &&
-                typeof error === "object" &&
-                "stack" in error
-                  ? (error as { stack: string }).stack
-                  : undefined;
-              if (stack) {
-                target.error(`Stack trace: ${stack}`);
-              }
+              logHandlerError({
+                error,
+                pathname,
+                logger,
+                protocolLabel: "RPC",
+              });
               throw error;
             }
           },
@@ -93,93 +249,6 @@ export function createApiRouteHandler({
       },
     );
 
-    // Resolve core services for RPC context
-    const auth = await getService(coreServices.auth);
-    const db = await getService(coreServices.database);
-    const fetch = await getService(coreServices.fetch);
-    const healthCheckRegistry = await getService(
-      coreServices.healthCheckRegistry,
-    );
-    const collectorRegistry = await getService(coreServices.collectorRegistry);
-    const queuePluginRegistry = await getService(
-      coreServices.queuePluginRegistry,
-    );
-    const queueManager = await getService(coreServices.queueManager);
-    const cachePluginRegistry = await getService(
-      coreServices.cachePluginRegistry,
-    );
-    const cacheManager = await getService(coreServices.cacheManager);
-    const eventBus = await getService(coreServices.eventBus);
-
-    if (
-      !auth ||
-      !logger ||
-      !db ||
-      !fetch ||
-      !healthCheckRegistry ||
-      !collectorRegistry ||
-      !queuePluginRegistry ||
-      !queueManager ||
-      !cachePluginRegistry ||
-      !cacheManager ||
-      !eventBus
-    ) {
-      const missing = [
-        !auth && "auth",
-        !logger && "logger",
-        !db && "db",
-        !fetch && "fetch",
-        !healthCheckRegistry && "healthCheckRegistry",
-        !collectorRegistry && "collectorRegistry",
-        !queuePluginRegistry && "queuePluginRegistry",
-        !queueManager && "queueManager",
-        !cachePluginRegistry && "cachePluginRegistry",
-        !cacheManager && "cacheManager",
-        !eventBus && "eventBus",
-      ].filter(Boolean).join(", ");
-      (logger ?? rootLogger).error(
-        `${pathname}: core services not initialized — missing: ${missing}`,
-      );
-      return c.json({ error: "Core services not initialized" }, 500);
-    }
-
-    const user = await (auth as AuthService).authenticate(c.req.raw);
-
-    // Create emitHook function using eventBus
-    const emitHook: EmitHookFn = async <T>(hook: Hook<T>, payload: T) => {
-      await (eventBus as EventBus).emit(hook, payload);
-    };
-
-    // Lookup plugin metadata from registry
-    const pluginMetadata: PluginMetadata | undefined =
-      pluginMetadataRegistry.get(pluginId);
-
-    if (!pluginMetadata) {
-      (logger as Logger).error(
-        `${pathname}: no plugin metadata registered for pluginId='${pluginId}'. ` +
-          `Regular plugins populate this during register(); core routers must call ` +
-          `pluginManager.registerCorePluginMetadata().`,
-      );
-      return c.json({ error: "Plugin metadata not found in registry" }, 500);
-    }
-
-    const context: RpcContext = {
-      pluginMetadata,
-      auth: auth as AuthService,
-      logger: logger as Logger,
-      db: db as SafeDatabase<Record<string, unknown>>,
-      fetch: fetch as Fetch,
-      healthCheckRegistry: healthCheckRegistry as HealthCheckRegistry,
-      collectorRegistry: collectorRegistry as CollectorRegistry,
-      queuePluginRegistry: queuePluginRegistry as QueuePluginRegistry,
-      queueManager: queueManager as QueueManager,
-      cachePluginRegistry: cachePluginRegistry as CachePluginRegistry,
-      cacheManager: cacheManager as CacheManager,
-      user,
-      emitHook,
-    };
-
-    // 1. Try oRPC first
     const { matched, response } = await rpcHandler.handle(c.req.raw, {
       prefix: "/api",
       context,
@@ -191,8 +260,7 @@ export function createApiRouteHandler({
 
     logger.debug(`RPC mismatch for: ${c.req.method} ${pathname}`);
 
-    // 2. Try native handlers
-    // Sort by path length (descending) to ensure more specific paths are tried first
+    // Fall through to native plugin HTTP handlers (sorted longest-prefix first)
     const sortedHandlers = [...pluginHttpHandlers.entries()].toSorted(
       function (a, b) {
         return b[0].length - a[0].length;
@@ -209,6 +277,71 @@ export function createApiRouteHandler({
   };
 }
 
+/**
+ * Creates the REST route handler for Hono.
+ * Serves the REST/OpenAPI shape of the same oRPC contract at /rest/:pluginId/*.
+ * Standard JSON bodies / query params work here — matches /api/openapi.json.
+ */
+export function createRestRouteHandler({
+  registry,
+  pluginRpcRouters,
+  pluginMetadataRegistry,
+}: {
+  registry: ServiceRegistry;
+  pluginRpcRouters: Map<string, unknown>;
+  pluginMetadataRegistry: Map<string, PluginMetadata>;
+}) {
+  const deps: RouteHandlerDeps = {
+    registry,
+    pluginRpcRouters,
+    pluginMetadataRegistry,
+  };
+
+  return async function handleRestRequest(c: Context) {
+    const pluginId = c.req.param("pluginId") || "";
+    const pathname = new URL(c.req.raw.url).pathname;
+
+    const result = await resolveRequestContext({ c, pluginId, deps });
+    if (!result.ok) return result.response;
+    const { context, logger } = result.resolved;
+
+    const restHandler = new OpenAPIHandler(
+      buildRpcRouter(pluginRpcRouters) as ConstructorParameters<
+        typeof OpenAPIHandler
+      >[0],
+      {
+        interceptors: [
+          async ({ next, ...rest }) => {
+            try {
+              return await next(rest);
+            } catch (error) {
+              logHandlerError({
+                error,
+                pathname,
+                logger,
+                protocolLabel: "REST",
+              });
+              throw error;
+            }
+          },
+        ],
+      },
+    );
+
+    const { matched, response } = await restHandler.handle(c.req.raw, {
+      prefix: "/rest",
+      context,
+    });
+
+    if (matched) {
+      return c.newResponse(response.body, response);
+    }
+
+    logger.debug(`REST mismatch for: ${c.req.method} ${pathname}`);
+    return c.json({ error: "Not Found" }, 404);
+  };
+}
+
 /**
  * Registers the /api/:pluginId/* route with Hono.
  */
@@ -218,3 +351,13 @@ export function registerApiRoute(
 ) {
   rootRouter.all("/api/:pluginId/*", handler);
 }
+
+/**
+ * Registers the /rest/:pluginId/* route with Hono.
+ */
+export function registerRestRoute(
+  rootRouter: Hono,
+  handler: ReturnType<typeof createRestRouteHandler>,
+) {
+  rootRouter.all("/rest/:pluginId/*", handler);
+}

package/src/plugin-manager/plugin-loader.ts

@@ -29,7 +29,12 @@ import {
 } from "../utils/plugin-discovery";
 import type { InitCallback, PendingInit } from "./types";
 import { sortPlugins } from "./dependency-sorter";
-import { createApiRouteHandler, registerApiRoute } from "./api-router";
+import {
+  createApiRouteHandler,
+  createRestRouteHandler,
+  registerApiRoute,
+  registerRestRoute,
+} from "./api-router";
 import type { ExtensionPointManager } from "./extension-points";
 import { Router } from "@orpc/server";
 import { AnyContractRouter } from "@orpc/contract";
@@ -302,7 +307,10 @@ export async function loadPlugins({
   const sortedIds = sortPlugins({ pendingInits, providedBy, logger });
   rootLogger.debug(`✅ Initialization Order: ${sortedIds.join(" -> ")}`);
 
-  // Register /api/* route BEFORE plugin initialization
+  // Register /api/* (oRPC wire format) and /rest/* (REST/OpenAPI shape) routes
+  // BEFORE plugin initialization. Both routes share the same plugin RPC routers
+  // and per-request context; they differ only in how the handler decodes the
+  // request and matches it to a procedure.
   const apiHandler = createApiRouteHandler({
     registry: deps.registry,
     pluginRpcRouters: deps.pluginRpcRouters,
@@ -311,6 +319,13 @@ export async function loadPlugins({
   });
   registerApiRoute(rootRouter, apiHandler);
 
+  const restHandler = createRestRouteHandler({
+    registry: deps.registry,
+    pluginRpcRouters: deps.pluginRpcRouters,
+    pluginMetadataRegistry: deps.pluginMetadataRegistry,
+  });
+  registerRestRoute(rootRouter, restHandler);
+
   // Routes are now registered on the root router. Signal readiness so the
   // server can stop blocking incoming requests in `waitForInit()`. We open
   // the gate here (BEFORE Phase 2 / Phase 3) so that: