@jskit-ai/kernel 0.1.4

package/client/moduleBootstrap.test.js

@@ -0,0 +1,403 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createSurfaceRuntime } from "../shared/surface/runtime.js";
+import { bootClientModules } from "./moduleBootstrap.js";
+
+function createRouterStub() {
+  const routes = [];
+  return {
+    routes,
+    addRoute(route) {
+      routes.push(route);
+    }
+  };
+}
+
+function createSurfaceRuntimeFixture() {
+  return createSurfaceRuntime({
+    allMode: "all",
+    surfaces: {
+      app: { id: "app", pagesRoot: "app", enabled: true },
+      admin: { id: "admin", pagesRoot: "admin", enabled: true }
+    },
+    defaultSurfaceId: "app"
+  });
+}
+
+test("bootClientModules registers global routes regardless of surface mode", async () => {
+  const router = createRouterStub();
+  const surfaceRuntime = createSurfaceRuntimeFixture();
+
+  const result = await bootClientModules({
+    clientModules: [
+      {
+        packageId: "@example/auth",
+        descriptorUiRoutes: [
+          {
+            id: "auth.login",
+            path: "/auth/login",
+            scope: "global",
+            autoRegister: false
+          }
+        ],
+        module: {
+          clientRoutes: [
+            {
+              id: "auth.login",
+              name: "auth-login",
+              path: "/auth/login",
+              scope: "global",
+              component: {}
+            }
+          ]
+        }
+      }
+    ],
+    router,
+    surfaceRuntime,
+    surfaceMode: "admin",
+    logger: { info() {}, warn() {}, error() {} }
+  });
+
+  assert.equal(result.routeResults.length, 1);
+  assert.equal(result.routeResults[0].declaredCount, 1);
+  assert.equal(result.routeResults[0].registeredCount, 1);
+  assert.equal(router.routes.length, 1);
+  assert.equal(router.routes[0].path, "/auth/login");
+});
+
+test("bootClientModules filters surface routes by mode", async () => {
+  const router = createRouterStub();
+  const surfaceRuntime = createSurfaceRuntimeFixture();
+
+  const result = await bootClientModules({
+    clientModules: [
+      {
+        packageId: "@example/admin",
+        module: {
+          clientRoutes: [
+            {
+              id: "admin.dashboard",
+              name: "admin-dashboard",
+              path: "/admin/dashboard",
+              scope: "surface",
+              component: {}
+            },
+            {
+              id: "app.dashboard",
+              name: "app-dashboard",
+              path: "/app/dashboard",
+              scope: "surface",
+              component: {}
+            }
+          ]
+        }
+      }
+    ],
+    router,
+    surfaceRuntime,
+    surfaceMode: "admin",
+    logger: { info() {}, warn() {}, error() {} }
+  });
+
+  assert.equal(result.routeResults.length, 1);
+  assert.equal(result.routeResults[0].declaredCount, 2);
+  assert.equal(result.routeResults[0].registeredCount, 1);
+  assert.equal(router.routes.length, 1);
+  assert.equal(router.routes[0].path, "/admin/dashboard");
+});
+
+test("bootClientModules registers descriptor and clientRoutes with providers only", async () => {
+  const router = createRouterStub();
+  const surfaceRuntime = createSurfaceRuntimeFixture();
+  const events = [];
+  const loginComponent = {};
+  class ExampleClientProvider {
+    static id = "example.client";
+    register(app) {
+      events.push("register");
+      app.instance("example.value", 42);
+    }
+    boot() {
+      events.push("boot");
+    }
+  }
+
+  const result = await bootClientModules({
+    clientModules: [
+      {
+        packageId: "@example/alpha",
+        module: {
+          clientProviders: [ExampleClientProvider],
+          ExampleClientProvider
+        }
+      },
+      {
+        packageId: "@example/zeta",
+        descriptorUiRoutes: [
+          {
+            id: "auth.default-login-2",
+            name: "auth-default-login-2",
+            path: "/auth/default-login-2",
+            scope: "global",
+            componentKey: "auth-login",
+            autoRegister: true
+          },
+          {
+            id: "auth.skipped",
+            path: "/auth/skipped",
+            scope: "global",
+            componentKey: "auth-login",
+            autoRegister: false
+          },
+          {
+            id: "auth.login",
+            path: "/auth/login",
+            scope: "global",
+            autoRegister: false
+          },
+          {
+            id: "auth.callback",
+            path: "/auth/callback",
+            scope: "global",
+            autoRegister: false
+          }
+        ],
+        module: {
+          routeComponents: {
+            "auth-login": loginComponent
+          },
+          clientRoutes: [
+            {
+              id: "auth.login",
+              name: "auth-login",
+              path: "/auth/login",
+              scope: "global",
+              component: loginComponent
+            }
+          ]
+        }
+      }
+    ],
+    router,
+    surfaceRuntime,
+    surfaceMode: "all",
+    logger: { info() {}, warn() {}, error() {} }
+  });
+
+  assert.deepEqual(events, ["register", "boot"]);
+  assert.equal(result.providerCount, 1);
+  assert.equal(result.routeCount, 2);
+  assert.equal(router.routes.length, 2);
+  assert.equal(router.routes[0].path, "/auth/default-login-2");
+  assert.equal(router.routes[0].component, loginComponent);
+  assert.equal(router.routes[1].path, "/auth/login");
+  assert.equal(router.routes[1].component, loginComponent);
+  assert.equal(result.runtimeApp.make("example.value"), 42);
+});
+
+test("bootClientModules does not auto-discover providers from module exports", async () => {
+  const router = createRouterStub();
+  const surfaceRuntime = createSurfaceRuntimeFixture();
+  const events = [];
+
+  class ExampleClientProvider {
+    static id = "example.client";
+    register() {
+      events.push("register");
+    }
+    boot() {
+      events.push("boot");
+    }
+  }
+
+  const result = await bootClientModules({
+    clientModules: [
+      {
+        packageId: "@example/no-provider-declaration",
+        module: {
+          ExampleClientProvider
+        }
+      }
+    ],
+    router,
+    surfaceRuntime,
+    surfaceMode: "all",
+    logger: { info() {}, warn() {}, error() {} }
+  });
+
+  assert.equal(result.providerCount, 0);
+  assert.deepEqual(events, []);
+});
+
+test("bootClientModules rejects clientRoutes without components", async () => {
+  const router = createRouterStub();
+  const surfaceRuntime = createSurfaceRuntimeFixture();
+
+  await assert.rejects(
+    bootClientModules({
+      clientModules: [
+        {
+          packageId: "@example/missing",
+          module: {
+            clientRoutes: [
+              {
+                id: "auth.login",
+                path: "/auth/login",
+                scope: "global",
+                component: null
+              }
+            ]
+          }
+        }
+      ],
+      router,
+      surfaceRuntime,
+      surfaceMode: "all",
+      logger: { info() {}, warn() {}, error() {} }
+    }),
+    /Client route "auth.login" from @example\/missing requires component\./
+  );
+});
+
+test("bootClientModules rejects non-declared global clientRoutes", async () => {
+  const router = createRouterStub();
+  const surfaceRuntime = createSurfaceRuntimeFixture();
+  const loginComponent = {};
+
+  await assert.rejects(
+    bootClientModules({
+      clientModules: [
+        {
+          packageId: "@example/strict",
+          descriptorUiRoutes: [
+            {
+              id: "auth.default-login-2",
+              path: "/auth/default-login-2",
+              scope: "global",
+              componentKey: "auth-login",
+              autoRegister: true
+            }
+          ],
+          module: {
+            routeComponents: {
+              "auth-login": loginComponent
+            },
+            clientRoutes: [
+              {
+                id: "auth.callback",
+                name: "auth-callback",
+                path: "/auth/callback",
+                scope: "global",
+                component: loginComponent
+              }
+            ]
+          }
+        }
+      ],
+      router,
+      surfaceRuntime,
+      surfaceMode: "all",
+      logger: { info() {}, warn() {}, error() {} }
+    }),
+    /must be declared in metadata\.ui\.routes/
+  );
+});
+
+test("bootClientModules allows non-declared surface clientRoutes", async () => {
+  const router = createRouterStub();
+  const surfaceRuntime = createSurfaceRuntimeFixture();
+  const dashboardComponent = {};
+
+  const result = await bootClientModules({
+    clientModules: [
+      {
+        packageId: "@example/surface-programmatic",
+        descriptorUiRoutes: [],
+        module: {
+          clientRoutes: [
+            {
+              id: "admin.projects",
+              name: "admin-projects",
+              path: "/admin/projects",
+              scope: "surface",
+              component: dashboardComponent
+            }
+          ]
+        }
+      }
+    ],
+    router,
+    surfaceRuntime,
+    surfaceMode: "admin",
+    logger: { info() {}, warn() {}, error() {} }
+  });
+
+  assert.equal(result.routeCount, 1);
+  assert.equal(router.routes.length, 1);
+  assert.equal(router.routes[0].path, "/admin/projects");
+});
+
+test("bootClientModules loads client providers declared in descriptorClientProviders", async () => {
+  const router = createRouterStub();
+  const surfaceRuntime = createSurfaceRuntimeFixture();
+  const events = [];
+
+  await bootClientModules({
+    clientModules: [
+      {
+        packageId: "@example/descriptor-providers",
+        descriptorClientProviders: [
+          {
+            entrypoint: "src/client/providers/ExampleProvider.js",
+            export: "ExampleProvider"
+          }
+        ],
+        module: {
+          ExampleProvider: class {
+            static id = "example.descriptor.provider";
+            register() {
+              events.push("register");
+            }
+            boot() {
+              events.push("boot");
+            }
+          }
+        }
+      }
+    ],
+    router,
+    surfaceRuntime,
+    surfaceMode: "all",
+    logger: { info() {}, warn() {}, error() {} }
+  });
+
+  assert.deepEqual(events, ["register", "boot"]);
+});
+
+test("bootClientModules throws when descriptorClientProviders export is missing", async () => {
+  const router = createRouterStub();
+  const surfaceRuntime = createSurfaceRuntimeFixture();
+
+  await assert.rejects(
+    bootClientModules({
+      clientModules: [
+        {
+          packageId: "@example/missing-provider-export",
+          descriptorClientProviders: [
+            {
+              entrypoint: "src/client/providers/MissingProvider.js",
+              export: "MissingProvider"
+            }
+          ],
+          module: {}
+        }
+      ],
+      router,
+      surfaceRuntime,
+      surfaceMode: "all",
+      logger: { info() {}, warn() {}, error() {} }
+    }),
+    /descriptor provider export "MissingProvider" is missing or invalid/
+  );
+});

package/client/shellBootstrap.js

@@ -0,0 +1,233 @@
+import { buildSurfaceAwareRoutes, createFallbackNotFoundRoute, createShellBeforeEachGuard } from "./shellRouting.js";
+import { isRecord } from "../shared/support/normalize.js";
+import { setClientAppConfig } from "./appConfig.js";
+import { createStructuredLogger, summarizeRouterRoutes } from "./logging.js";
+
+function resolveClientBootstrapDebugEnabled({
+  env = {},
+  debugEnabled = undefined,
+  debugEnvKey = "VITE_JSKIT_CLIENT_DEBUG"
+} = {}) {
+  if (typeof debugEnabled === "boolean") {
+    return debugEnabled;
+  }
+  if (!isRecord(env)) {
+    return false;
+  }
+  return String(env[debugEnvKey] || "").trim() === "1";
+}
+
+function createClientBootstrapLogger({
+  env = {},
+  logger = console,
+  debugEnabled = undefined,
+  debugEnvKey = "VITE_JSKIT_CLIENT_DEBUG"
+} = {}) {
+  const baseLogger = createStructuredLogger(logger);
+  const isDebugEnabled = resolveClientBootstrapDebugEnabled({
+    env,
+    debugEnabled,
+    debugEnvKey
+  });
+  return Object.freeze({
+    info: baseLogger.info,
+    warn: baseLogger.warn,
+    error: baseLogger.error,
+    debug: isDebugEnabled ? baseLogger.info : () => {},
+    isDebugEnabled
+  });
+}
+
+function installAppPlugins(app, appPlugins = []) {
+  const plugins = Array.isArray(appPlugins) ? appPlugins : [];
+  for (const pluginEntry of plugins) {
+    if (!pluginEntry) {
+      continue;
+    }
+    if (Array.isArray(pluginEntry)) {
+      const [plugin, ...pluginArgs] = pluginEntry;
+      if (!plugin) {
+        continue;
+      }
+      app.use(plugin, ...pluginArgs);
+      continue;
+    }
+    app.use(pluginEntry);
+  }
+}
+
+function createSurfaceShellRouter({
+  createRouter,
+  history,
+  routes = [],
+  surfaceRuntime,
+  surfaceMode,
+  fallbackRoute = null,
+  notFoundComponent = null,
+  guard = false
+} = {}) {
+  if (typeof createRouter !== "function") {
+    throw new TypeError("createSurfaceShellRouter requires createRouter().");
+  }
+
+  const effectiveFallbackRoute = fallbackRoute || (notFoundComponent ? createFallbackNotFoundRoute(notFoundComponent) : null);
+  const activeRoutes = buildSurfaceAwareRoutes({
+    routes,
+    surfaceRuntime,
+    surfaceMode,
+    fallbackRoute: effectiveFallbackRoute
+  });
+  const router = createRouter({
+    history,
+    routes: activeRoutes
+  });
+
+  if (guard !== false) {
+    if (!router || typeof router.beforeEach !== "function") {
+      throw new TypeError("createSurfaceShellRouter requires router.beforeEach() when guard is enabled.");
+    }
+    const beforeEachGuard =
+      typeof guard === "function"
+        ? guard
+        : createShellBeforeEachGuard({
+            surfaceRuntime,
+            ...(isRecord(guard) ? guard : {})
+          });
+    router.beforeEach(beforeEachGuard);
+  }
+
+  return Object.freeze({
+    router,
+    activeRoutes: Object.freeze([...activeRoutes]),
+    fallbackRoute: effectiveFallbackRoute
+  });
+}
+
+async function bootstrapClientShellApp({
+  createApp,
+  rootComponent,
+  appConfig = {},
+  appPlugins = [],
+  router,
+  bootClientModules,
+  surfaceRuntime,
+  surfaceMode,
+  env = {},
+  fallbackRoute = null,
+  logger = console,
+  createBootstrapLogger = null,
+  debugEnabled = undefined,
+  debugEnvKey = "VITE_JSKIT_CLIENT_DEBUG",
+  debugMessage = "Client modules bootstrapped before router install.",
+  onAfterModulesBootstrapped = null,
+  mountSelector = "#app"
+} = {}) {
+  if (typeof createApp !== "function") {
+    throw new TypeError("bootstrapClientShellApp requires createApp().");
+  }
+  if (!router || typeof router.addRoute !== "function") {
+    throw new TypeError("bootstrapClientShellApp requires router.addRoute().");
+  }
+  if (typeof bootClientModules !== "function") {
+    throw new TypeError("bootstrapClientShellApp requires bootClientModules().");
+  }
+
+  const app = createApp(rootComponent);
+  if (!app || typeof app.use !== "function" || typeof app.mount !== "function") {
+    throw new TypeError("bootstrapClientShellApp requires createApp() to return a Vue app with use() and mount().");
+  }
+
+  installAppPlugins(app, appPlugins);
+  setClientAppConfig(appConfig);
+
+  const resolvedLogger =
+    typeof createBootstrapLogger === "function"
+      ? createBootstrapLogger({
+          env,
+          logger,
+          debugEnabled,
+          debugEnvKey
+        })
+      : createClientBootstrapLogger({
+          env,
+          logger,
+          debugEnabled,
+          debugEnvKey
+        });
+  const bootstrapLogger = createStructuredLogger(resolvedLogger);
+
+  const clientBootstrap = await bootClientModules({
+    app,
+    router,
+    surfaceRuntime,
+    surfaceMode,
+    env,
+    logger: bootstrapLogger
+  });
+
+  const isDebugEnabled =
+    typeof resolvedLogger?.isDebugEnabled === "boolean"
+      ? resolvedLogger.isDebugEnabled
+      : resolveClientBootstrapDebugEnabled({
+          env,
+          debugEnabled,
+          debugEnvKey
+        });
+  if (isDebugEnabled) {
+    bootstrapLogger.info(
+      {
+        bootstrap: {
+          modules: clientBootstrap?.modules || [],
+          providerCount: Number(clientBootstrap?.providerCount || 0),
+          routeCount: Number(clientBootstrap?.routeCount || 0)
+        },
+        routerRoutesBeforeInstall: summarizeRouterRoutes(router),
+        currentPath: typeof window !== "undefined" ? String(window.location?.pathname || "") : ""
+      },
+      String(debugMessage || "").trim() || "Client modules bootstrapped before router install."
+    );
+  }
+
+  if (fallbackRoute?.name && typeof router.addRoute === "function") {
+    if (typeof router.hasRoute === "function" && router.hasRoute(fallbackRoute.name) && typeof router.removeRoute === "function") {
+      router.removeRoute(fallbackRoute.name);
+    }
+    router.addRoute(fallbackRoute);
+  }
+
+  if (typeof onAfterModulesBootstrapped === "function") {
+    await onAfterModulesBootstrapped(
+      Object.freeze({
+        app,
+        router,
+        clientBootstrap,
+        surfaceRuntime,
+        surfaceMode,
+        env: isRecord(env) ? { ...env } : {},
+        logger: bootstrapLogger,
+        debugEnabled: isDebugEnabled
+      })
+    );
+  }
+
+  app.use(router);
+  if (typeof router.isReady === "function") {
+    await router.isReady();
+  }
+  app.mount(mountSelector);
+
+  return Object.freeze({
+    app,
+    router,
+    clientBootstrap,
+    logger: bootstrapLogger,
+    debugEnabled: isDebugEnabled
+  });
+}
+
+export {
+  resolveClientBootstrapDebugEnabled,
+  createClientBootstrapLogger,
+  createSurfaceShellRouter,
+  bootstrapClientShellApp
+};