feat: enhance multi-project support with new route plugins for templates and runtime config

Author: hotlong

CHANGELOG.md

@@ -8,6 +8,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Fixed
+- `apps/server`: `GET /api/v1/cloud/templates` now returns the full template registry (`blank`, `crm`, `todo`) on Vercel / play.objectstack.ai. Root cause: the dispatcher resolved templates through a `template-seeder` service registered by `MultiProjectPlugin`, and on Vercel cold starts that service registration could be missed by the request handler — the dispatcher then silently returned `{ templates: [], total: 0 }`. Added a `createTemplatesRoutePlugin` that registers `/cloud/templates` directly on `http.server` from a static, module-scope `listTemplates()` snapshot, registered before `DispatcherPlugin`. Local single-project mode is unchanged.
+- `packages/runtime/http-dispatcher.ts`: `/cloud/templates` fallback now logs the resolution error via `console.error` instead of swallowing it silently, so the underlying cause is visible in production logs.
+- `apps/server/objectstack.config.ts`: `multiProjectPluginProxy.init` now wraps the inner init in try/catch and logs failures, preventing one-off init errors from silently leaving the kernel without `template-seeder` / `kernel-manager`.
 - `apps/server`: Multi-project / cloud mode now also serves `GET /api/v1/studio/runtime-config` (returns `{ singleProject: false }`) via a new `createStudioRuntimeConfigPlugin`. Eliminates the 404 the Studio SPA logged on first load when `OBJECTSTACK_MULTI_PROJECT=true` (the default for root `pnpm dev`). Single-project mode is unchanged.
 
 ### Added

apps/server/objectstack.config.ts

@@ -46,7 +46,9 @@ import {
     AppPlugin,
 } from '@objectstack/runtime';
 import { createControlPlanePlugins } from './server/control-plane-preset.js';
-import { createSingleProjectPlugin, createStudioRuntimeConfigPlugin } from './server/single-project-plugin.js';
+import { createSingleProjectPlugin } from './server/single-project-plugin.js';
+import { createStudioRuntimeConfigPlugin, createTemplatesRoutePlugin } from './server/multi-project-plugins.js';
+import { listTemplates } from './server/templates/registry.js';
 import { templateRegistry } from './server/templates/registry.js';
 
 type IDataDriver = Contracts.IDataDriver;
@@ -208,18 +210,30 @@ const multiProjectPluginProxy: any = {
     version: '0.0.0',
     _impl: null as any,
     async init(ctx: any) {
-        const { driver: controlDriver } = await controlDriverPromise;
-        const { MultiProjectPlugin: MPlugin } = await import('@objectstack/runtime');
-        this._impl = new MPlugin({
-            controlDriver,
-            basePlugins,
-            appBundles,
-            templates: templateRegistry,
-            maxSize: Number(process.env.OBJECTSTACK_KERNEL_CACHE_SIZE ?? 32),
-            ttlMs: Number(process.env.OBJECTSTACK_KERNEL_TTL_MS ?? 15 * 60 * 1000),
-            cacheTTLMs: Number(process.env.OBJECTSTACK_ENV_CACHE_TTL_MS ?? 5 * 60 * 1000),
-        });
-        if (this._impl.init) await this._impl.init(ctx);
+        try {
+            const { driver: controlDriver } = await controlDriverPromise;
+            const { MultiProjectPlugin: MPlugin } = await import('@objectstack/runtime');
+            this._impl = new MPlugin({
+                controlDriver,
+                basePlugins,
+                appBundles,
+                templates: templateRegistry,
+                maxSize: Number(process.env.OBJECTSTACK_KERNEL_CACHE_SIZE ?? 32),
+                ttlMs: Number(process.env.OBJECTSTACK_KERNEL_TTL_MS ?? 15 * 60 * 1000),
+                cacheTTLMs: Number(process.env.OBJECTSTACK_ENV_CACHE_TTL_MS ?? 5 * 60 * 1000),
+            });
+            if (this._impl.init) await this._impl.init(ctx);
+        } catch (err: any) {
+            // Surface init failures explicitly. Without this, a Turso connection
+            // error or service-registration crash silently leaves the kernel
+            // running with no `template-seeder`, surfacing as `/cloud/templates`
+            // returning `{ templates: [], total: 0 }` on Vercel/play.objectstack.ai.
+            // eslint-disable-next-line no-console
+            console.error('[multiProjectPluginProxy] init failed:', err?.stack ?? err?.message ?? err);
+            // Do NOT rethrow: a partial init (e.g. driver registered but
+            // service registration failed) is still better than crashing the
+            // entire control plane. The logged error is the only diagnostic.
+        }
     },
     async start(ctx: any) {
         if (this._impl?.start) await this._impl.start(ctx);
@@ -248,6 +262,11 @@ const config = isLocalMode
             }),
             multiProjectPluginProxy,
             createStudioRuntimeConfigPlugin(),
+            // Static /cloud/templates handler — registered on http.server
+            // before DispatcherPlugin so it wins. The dispatcher's seeder-
+            // based path is kept as a fallback for environments that bypass
+            // this layer (e.g. tests using the dispatcher directly).
+            createTemplatesRoutePlugin(listTemplates()),
         ],
         api: {
             enableProjectScoping: true,

apps/server/server/multi-project-plugins.ts

@@ -0,0 +1,92 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Multi-Project / Cloud auxiliary route plugins.
+ *
+ * Counterpart to `single-project-plugin.ts`. These plugins are registered
+ * only when the server runs in multi-project mode (`OBJECTSTACK_MULTI_PROJECT=true`,
+ * e.g. the Vercel deployment behind play.objectstack.ai). They expose two
+ * Studio-facing endpoints:
+ *
+ *   - `GET /api/v1/studio/runtime-config` → `{ singleProject: false }`
+ *     so the SPA initRuntimeConfig() handshake doesn't 404 and falls
+ *     through to the org/project picker.
+ *
+ *   - `GET /api/v1/cloud/templates` → static list from the template
+ *     registry. Bypasses the dispatcher's `template-seeder` service
+ *     indirection, which silently returned `{templates:[],total:0}` on
+ *     Vercel cold starts when MultiProjectPlugin's service registration
+ *     races the request.
+ *
+ * Both plugins register their routes on `http.server` *before*
+ * DispatcherPlugin, so they win the route match.
+ */
+
+import type { IHttpServer } from '@objectstack/spec/contracts';
+
+type AnyContext = any;
+
+/**
+ * Returns `{ singleProject: false }` so the SPA's `initRuntimeConfig()`
+ * handshake succeeds in multi-project mode without 404 noise.
+ */
+export function createStudioRuntimeConfigPlugin(options: { apiPrefix?: string } = {}): any {
+    const prefix = options.apiPrefix ?? '/api/v1';
+    return {
+        name: 'com.objectstack.studio.runtime-config',
+        version: '1.0.0',
+        init: async (_ctx: AnyContext) => {},
+        start: async (ctx: AnyContext) => {
+            let server: IHttpServer | undefined;
+            try {
+                server = ctx.getService('http.server') as IHttpServer | undefined;
+            } catch {
+                return;
+            }
+            if (!server) return;
+            server.get(`${prefix}/studio/runtime-config`, async (_req: any, res: any) => {
+                res.json({ singleProject: false });
+            });
+        },
+        stop: async (_ctx: AnyContext) => {},
+    };
+}
+
+/**
+ * Direct `/cloud/templates` route. Serves a snapshot of the template
+ * registry captured at config-load time, so SPA always receives the
+ * full list even before per-project kernels finish provisioning.
+ */
+export function createTemplatesRoutePlugin(
+    templates: Array<{ id: string; label: string; description: string; category?: string }>,
+    options: { apiPrefix?: string } = {},
+): any {
+    const prefix = options.apiPrefix ?? '/api/v1';
+    const payload = templates.map(({ id, label, description, category }) => ({
+        id,
+        label,
+        description,
+        category,
+    }));
+    return {
+        name: 'com.objectstack.studio.templates-route',
+        version: '1.0.0',
+        init: async (_ctx: AnyContext) => {},
+        start: async (ctx: AnyContext) => {
+            let server: IHttpServer | undefined;
+            try {
+                server = ctx.getService('http.server') as IHttpServer | undefined;
+            } catch {
+                return;
+            }
+            if (!server) return;
+            server.get(`${prefix}/cloud/templates`, async (_req: any, res: any) => {
+                res.json({
+                    success: true,
+                    data: { templates: payload, total: payload.length },
+                });
+            });
+        },
+        stop: async (_ctx: AnyContext) => {},
+    };
+}

apps/server/server/single-project-plugin.ts

@@ -10,6 +10,8 @@
  * and `useProjects.ts`. Routes are registered on the shared
  * `http.server` service *before* DispatcherPlugin, so they win the
  * match against the control-plane `/cloud/projects*` handlers.
+ *
+ * Multi-project / cloud-mode counterparts live in `multi-project-plugins.ts`.
  */
 
 import type { IHttpServer } from '@objectstack/spec/contracts';
@@ -141,34 +143,6 @@ export function createSingleProjectPlugin(options: SingleProjectPluginOptions =
     };
 }
 
-/**
- * Multi-project / cloud variant: only registers `/studio/runtime-config`,
- * returning `{ singleProject: false }` so the SPA falls through to the
- * org/project picker. Avoids a 404 in the Network panel without affecting
- * any actual control-plane behaviour.
- */
-export function createStudioRuntimeConfigPlugin(options: { apiPrefix?: string } = {}): any {
-    const prefix = options.apiPrefix ?? '/api/v1';
-    return {
-        name: 'com.objectstack.studio.runtime-config',
-        version: '1.0.0',
-        init: async (_ctx: AnyContext) => {},
-        start: async (ctx: AnyContext) => {
-            let server: IHttpServer | undefined;
-            try {
-                server = ctx.getService('http.server') as IHttpServer | undefined;
-            } catch {
-                return;
-            }
-            if (!server) return;
-            server.get(`${prefix}/studio/runtime-config`, async (_req: any, res: any) => {
-                res.json({ singleProject: false });
-            });
-        },
-        stop: async (_ctx: AnyContext) => {},
-    };
-}
-
 function buildLocalProjectRow(orgId: string, projectId: string, userId: string): Record<string, unknown> {
     const now = new Date().toISOString();
     return {

packages/runtime/src/http-dispatcher.ts

@@ -1488,7 +1488,14 @@ export class HttpDispatcher {
                     const seeder: any = await this.resolveService('template-seeder');
                     const templates = seeder?.listTemplates?.() ?? [];
                     return { handled: true, response: this.success({ templates, total: templates.length }) };
-                } catch {
+                } catch (err: any) {
+                    // Don't silently mask — log the real reason. Empty templates
+                    // here usually means MultiProjectPlugin failed to register
+                    // `template-seeder` (e.g. control-driver init error).
+                    try {
+                        // eslint-disable-next-line no-console
+                        console.error('[HttpDispatcher] /cloud/templates: failed to resolve template-seeder:', err?.message ?? err);
+                    } catch { /* noop */ }
                     return { handled: true, response: this.success({ templates: [], total: 0 }) };
                 }
             }