@valentinkolb/cloud 0.3.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentinkolb/cloud",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Modular Hono+SolidJS framework for building per-app docker services behind a dynamic gateway. Powers cloud.stuve-ulm.de.",
   "license": "MIT",
   "repository": {
@@ -36,8 +36,6 @@
   },
   "dependencies": {
     "@fontsource-variable/jetbrains-mono": "^5.2.8",
-    "@scalar/hono-api-reference": "^0.10.9",
-    "@scalar/openapi-to-markdown": "^0.5.6",
     "@tabler/icons-webfont": "^3.36.1",
     "@tailwindcss/typography": "^0.5.19",
     "@valentinkolb/ssr": "0.9.0",

package/src/_internal/define-app.ts

@@ -8,6 +8,7 @@ import { createConfig as createSsrConfig } from "@valentinkolb/ssr";
 import { createSSRHandler, routes } from "@valentinkolb/ssr/hono";
 import { Hono } from "hono";
 import { serveStatic } from "hono/bun";
+import { generateSpecs } from "hono-openapi";
 import type { SsrConfig } from "@valentinkolb/ssr";
 import type {
   AppMeta,
@@ -107,6 +108,23 @@ export type AppOptions<S extends AppSettingsMap = {}> = {
    * prefix-trie from these strings.
    */
   routes: readonly string[];
+  /**
+   * Gateway-relative URL at which this app's OpenAPI 3.x JSON spec is
+   * served, e.g. `"/api/notebooks/openapi.json"`. Opt-in: only set this
+   * for apps whose api router is documented with `middleware.openapi()`
+   * (i.e. `describeRoute()`) and worth surfacing in the api-docs aggregator.
+   *
+   * Pair this with `app.start({ openapi: <api router> })` — `defineApp`
+   * generates the spec from that router at boot, mounts it on the
+   * framework server (before the user's fetch, so it bypasses any
+   * auth/rate-limit middleware), and advertises the URL via the registry
+   * so `app-api-docs` picks it up automatically.
+   *
+   * The path must be reachable through the gateway — usually that means
+   * the standard form `"/api/<id>/openapi.json"` (covered by the
+   * `/api/<id>` entry in `routes`).
+   */
+  openapi?: string;
   /**
    * Project root used by the SSR plugin to discover island/client files.
    * Defaults to `process.cwd()`. Override only if you run the entrypoint
@@ -134,6 +152,18 @@ export type StartOptions = {
    * might register.
    */
   fetch: (req: Request) => Response | Promise<Response>;
+  /**
+   * Hono router to scan for OpenAPI route metadata. When set together with
+   * `defineApp({ openapi: "..." })`, the framework generates an OpenAPI
+   * spec from this router and mounts it at the configured URL on the
+   * framework server (before the user's fetch, so the spec stays public).
+   *
+   * Pass the BARE api router — the one with `describeRoute()` annotations.
+   * `generateSpecs` walks the route tree without executing middleware, so
+   * the inner auth/rate-limit `.use(...)` calls don't matter for spec
+   * generation; they only run if the router is hit by an actual request.
+   */
+  openapi?: Hono<any>;
   lifecycle?: AppLifecycle;
   capabilities?: AppCapabilities;
   port?: number;
@@ -258,6 +288,7 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
     nav: opts.nav,
     legalLinks: opts.legalLinks ? [...opts.legalLinks] : undefined,
     widgets: opts.widgets ? opts.widgets.map((w) => ({ ...w })) : undefined,
+    openapi: opts.openapi,
   };
 
   // ── 3. start() — builds and boots the Hono server ────────────────────
@@ -266,6 +297,11 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
     const baseUrl = opts.baseUrl;
     const log = logger("app");
 
+    // OpenAPI advertised in the registry only when there's a router to
+    // derive the spec from. The mount block lower down uses the same
+    // flag so the registry never points at a URL that 404s.
+    const advertiseOpenapi = !!(opts.openapi && startOpts.openapi);
+
     // Registry entry
     const entry: AppRegistryEntry = {
       id: meta.id,
@@ -294,6 +330,7 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
         : undefined,
       legalLinks: meta.legalLinks ? meta.legalLinks.map((l) => ({ ...l })) : undefined,
       widgets: meta.widgets ? meta.widgets.map((w) => ({ ...w })) : undefined,
+      openapi: advertiseOpenapi ? opts.openapi : undefined,
     };
 
     // Heartbeat
@@ -306,11 +343,13 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
     // watcher is a module-level singleton, only one runs per process.
     await ensureRuntimeWatcher();
 
-    // Build Hono server. Framework owns three mounts (registered first so
+    // Build Hono server. Framework owns these mounts (registered first so
     // they take precedence over any catch-all in the user's fetch):
     //   /_ssr/*                 island chunks (SSR adapter)
     //   /public/*               serveStatic + terminal 404
     //   /api/_internal/search   only when capabilities.search is declared
+    //   <opts.openapi>          OpenAPI JSON spec, when both opts.openapi
+    //                            and startOpts.openapi are set
     const ssrMountPath = config.basePath ? `${config.basePath}/_ssr` : "/_ssr";
 
     const server = new Hono()
@@ -336,6 +375,32 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
       });
     }
 
+    // OpenAPI spec mount. Registered on the framework server (before the
+    // user-fetch catch-all below) so it bypasses any auth / rate-limit
+    // middleware on the api router — the spec must stay reachable without
+    // a session for `app-api-docs` to render it.
+    //
+    // The `servers` override is load-bearing: hono-openapi walks the
+    // BARE api router and emits paths relative to its own root (e.g.
+    // `/{id}`, `/{id}/notes`), without the `/api/<id>` prefix it ends
+    // up under in the user's outer router. We derive that prefix from
+    // `opts.openapi` (everything before the trailing `/openapi.json`)
+    // so combined Scalar URLs resolve to the real public paths.
+    if (advertiseOpenapi) {
+      const apiPrefix = opts.openapi!.replace(/\/openapi\.json$/, "") || "/";
+      const spec = await generateSpecs(startOpts.openapi!, {
+        documentation: {
+          info: {
+            title: meta.name,
+            version: "0.0.1",
+            description: meta.description,
+          },
+          servers: [{ url: apiPrefix }],
+        },
+      });
+      server.get(opts.openapi!, (c) => c.json(spec));
+    }
+
     // User's fetch handles everything else. The framework doesn't inject any
     // context vars here — the user's router is expected to register the
     // middlewares it needs (middleware.runtime, middleware.settings, …).

package/src/_internal/runtime-context.ts

@@ -33,6 +33,7 @@ export const buildRuntimeFromRegistry = (entries: AppRegistryEntry[]): CloudRunt
       searchHelp: e.search?.help,
       searchTagHelp: e.search?.tagHelp,
       legalLinks: e.legalLinks ? e.legalLinks.map((l) => ({ ...l })) : undefined,
+      openapi: e.openapi,
     }),
   ),
 });

package/src/api/index.ts

@@ -8,13 +8,13 @@
  * Apps that need a typed client to these routes import from
  * `@valentinkolb/cloud/clients/core`. The client and the routes share their
  * type via `CoreApiType` below.
+ *
+ * The OpenAPI spec for these routes is generated by `defineApp` (driven by
+ * core's `openapi: "/api/openapi.json"` opt-in) — this file no longer mounts
+ * any docs UI; the api-docs aggregator at `/app/api-docs` is the only consumer.
  */
 import { Hono } from "hono";
-import { Scalar } from "@scalar/hono-api-reference";
-import { generateSpecs } from "hono-openapi";
 import { prettyJSON } from "hono/pretty-json";
-import { createMarkdownFromOpenApi } from "@scalar/openapi-to-markdown";
-import { openApiMeta } from "../server";
 import authRoutes from "./auth";
 import meRoutes from "./me";
 import adminLifecycleRoutes from "./admin-lifecycle";
@@ -41,26 +41,11 @@ const buildCoreApi = () => {
 export type CoreApiType = ReturnType<typeof buildCoreApi>;
 
 /**
- * Build the core router and accompanying OpenAPI assets. The core-app calls
- * this and mounts the returned router under `/api`.
+ * Build the core router. The core-app calls this and mounts the returned
+ * router under `/api`.
  */
-export const createCoreApiRouter = async () => {
+export const createCoreApiRouter = () => {
   const api = buildCoreApi();
-
-  const spec = await generateSpecs(api, openApiMeta);
-  const llmsTxt = await createMarkdownFromOpenApi(JSON.stringify(spec));
-
-  api.get("/openapi.json", (c) => c.json(spec));
-  api.get(
-    "/docs",
-    Scalar({
-      theme: "saturn",
-      url: "/api/openapi.json",
-      hideClientButton: true,
-    }),
-  );
-
   api.all("/*", (c) => c.json({ message: "API route not found" }, 404));
-
-  return { api, llmsTxt };
+  return { api };
 };

package/src/contracts/app.ts

@@ -43,6 +43,8 @@ export type AppMeta = {
    * silently skip rendering for the current user.
    */
   widgets?: WidgetEndpoint[];
+  /** Gateway-relative URL where this app's OpenAPI JSON is served, or undefined. */
+  openapi?: string;
 };
 
 export type WidgetEndpoint = {

package/src/contracts/registry.ts

@@ -47,4 +47,6 @@ export type AppRegistryEntry = {
   search?: AppRegistrySearch;
   legalLinks?: AppRegistryLegalLink[];
   widgets?: AppRegistryWidget[];
+  /** Gateway-relative URL where this app serves its OpenAPI JSON spec. */
+  openapi?: string;
 };