@jskit-ai/kernel 0.1.4

package/client/shellBootstrap.test.js

@@ -0,0 +1,185 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createSurfaceRuntime } from "../shared/surface/runtime.js";
+import {
+  bootstrapClientShellApp,
+  createClientBootstrapLogger,
+  createSurfaceShellRouter
+} from "./shellBootstrap.js";
+import { getClientAppConfig } from "./appConfig.js";
+
+function createSurfaceRuntimeFixture() {
+  return createSurfaceRuntime({
+    allMode: "all",
+    surfaces: {
+      app: { id: "app", pagesRoot: "app", enabled: true },
+      admin: { id: "admin", pagesRoot: "admin", enabled: true }
+    },
+    defaultSurfaceId: "app"
+  });
+}
+
+test("createSurfaceShellRouter builds active routes and installs a guard", () => {
+  const surfaceRuntime = createSurfaceRuntimeFixture();
+  const guards = [];
+  const routerState = {
+    options: null
+  };
+
+  const { router, activeRoutes, fallbackRoute } = createSurfaceShellRouter({
+    createRouter(options) {
+      routerState.options = options;
+      return {
+        beforeEach(guard) {
+          guards.push(guard);
+        }
+      };
+    },
+    history: { kind: "memory" },
+    routes: [
+      {
+        path: "/app/home",
+        name: "app-home",
+        component: {}
+      },
+      {
+        path: "/admin/home",
+        name: "admin-home",
+        component: {}
+      }
+    ],
+    surfaceRuntime,
+    surfaceMode: "app",
+    notFoundComponent: {},
+    guard: {
+      surfaceDefinitions: {
+        app: { id: "app", pagesRoot: "app", requiresAuth: false },
+        admin: { id: "admin", pagesRoot: "admin", requiresAuth: false }
+      },
+      defaultSurfaceId: "app",
+      webRootAllowed: "yes"
+    }
+  });
+
+  assert.ok(router);
+  assert.equal(guards.length, 1);
+  assert.equal(routerState.options.routes.length, activeRoutes.length);
+  assert.equal(activeRoutes.some((route) => route.path === "/app/home"), true);
+  assert.equal(activeRoutes.some((route) => route.path === "/admin/home"), false);
+  assert.equal(activeRoutes.some((route) => route.path === "/:pathMatch(.*)*"), true);
+  assert.equal(fallbackRoute.path, "/:pathMatch(.*)*");
+});
+
+test("createClientBootstrapLogger enables debug from env flag", () => {
+  const logger = createClientBootstrapLogger({
+    env: { VITE_JSKIT_CLIENT_DEBUG: "1" }
+  });
+
+  assert.equal(typeof logger.info, "function");
+  assert.equal(typeof logger.debug, "function");
+  assert.equal(logger.isDebugEnabled, true);
+});
+
+test("bootstrapClientShellApp boots modules, reinstalls fallback route, and mounts app", async () => {
+  const calls = [];
+  const logs = [];
+  const surfaceRuntime = createSurfaceRuntimeFixture();
+  const plugin = { name: "vuetify-like-plugin" };
+  const fallbackRoute = {
+    name: "not-found",
+    path: "/:pathMatch(.*)*",
+    component: {}
+  };
+
+  const app = {
+    used: [],
+    mountedAt: "",
+    use(entry) {
+      this.used.push(entry);
+      return this;
+    },
+    mount(selector) {
+      this.mountedAt = selector;
+      calls.push(`mount:${selector}`);
+    }
+  };
+
+  const router = {
+    routes: [fallbackRoute],
+    addRoute(route) {
+      calls.push(`add:${route.name || route.path}`);
+      this.routes.push(route);
+    },
+    hasRoute(name) {
+      return this.routes.some((route) => String(route?.name || "") === String(name || ""));
+    },
+    removeRoute(name) {
+      calls.push(`remove:${name}`);
+      this.routes = this.routes.filter((route) => String(route?.name || "") !== String(name || ""));
+    },
+    getRoutes() {
+      return [...this.routes];
+    },
+    async isReady() {
+      calls.push("isReady");
+    }
+  };
+
+  const result = await bootstrapClientShellApp({
+    createApp(rootComponent) {
+      calls.push(`createApp:${String(rootComponent || "")}`);
+      return app;
+    },
+    rootComponent: "RootComponent",
+    appConfig: {
+      crud: {
+        contacts: {
+          namespace: "crm",
+          visibility: "workspace"
+        }
+      }
+    },
+    appPlugins: [plugin],
+    router,
+    bootClientModules: async (context) => {
+      calls.push("bootClientModules");
+      assert.equal(context.app, app);
+      assert.equal(context.router, router);
+      assert.equal(typeof context.logger.debug, "function");
+      return {
+        modules: ["@example/main"],
+        providerCount: 1,
+        routeCount: 3
+      };
+    },
+    surfaceRuntime,
+    surfaceMode: "app",
+    env: { VITE_JSKIT_CLIENT_DEBUG: "1" },
+    fallbackRoute,
+    logger: {
+      info(payload, message) {
+        logs.push({ payload, message });
+      },
+      warn() {},
+      error() {}
+    },
+    onAfterModulesBootstrapped(context) {
+      calls.push(`after:${context.clientBootstrap.routeCount}`);
+    }
+  });
+
+  assert.equal(result.debugEnabled, true);
+  assert.deepEqual(getClientAppConfig().crud?.contacts, {
+    namespace: "crm",
+    visibility: "workspace"
+  });
+  assert.equal(app.used[0], plugin);
+  assert.equal(app.used[1], router);
+  assert.equal(app.mountedAt, "#app");
+  assert.equal(logs.length, 1);
+  assert.equal(calls.includes("bootClientModules"), true);
+  assert.equal(calls.includes("remove:not-found"), true);
+  assert.equal(calls.includes("add:not-found"), true);
+  assert.equal(calls.includes("isReady"), true);
+  assert.equal(calls.includes("after:3"), true);
+});

package/client/shellRouting.js

@@ -0,0 +1,321 @@
+import { deriveSurfaceRouteBaseFromPagesRoot } from "../shared/surface/index.js";
+import { filterRoutesBySurface } from "../shared/surface/runtime.js";
+import { isExternalLinkTarget } from "../shared/support/linkPath.js";
+import { AUTH_POLICY_AUTHENTICATED, AUTH_POLICY_PUBLIC } from "../shared/support/policies.js";
+
+const DEFAULT_GUARD_EVALUATOR_KEY = "__JSKIT_WEB_SHELL_GUARD_EVALUATOR__";
+const WEB_ROOT_ALLOW_YES = "yes";
+const WEB_ROOT_ALLOW_NO = "no";
+
+function createFallbackNotFoundRoute(component) {
+  if (!component) {
+    throw new Error("createFallbackNotFoundRoute requires a component.");
+  }
+
+  return Object.freeze({
+    path: "/:pathMatch(.*)*",
+    name: "not-found",
+    component,
+    meta: {
+      jskit: {
+        scope: "global"
+      }
+    }
+  });
+}
+
+function buildSurfaceAwareRoutes({
+  routes = [],
+  surfaceRuntime,
+  surfaceMode,
+  fallbackRoute,
+  notFoundComponent
+} = {}) {
+  const effectiveFallback =
+    fallbackRoute ||
+    (notFoundComponent ? createFallbackNotFoundRoute(notFoundComponent) : null);
+
+  if (!effectiveFallback) {
+    throw new TypeError("buildSurfaceAwareRoutes requires fallbackRoute or notFoundComponent.");
+  }
+  return filterRoutesBySurface([...routes, effectiveFallback], {
+    surfaceRuntime,
+    surfaceMode
+  });
+}
+
+function normalizeGuardPolicy(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase();
+}
+
+function resolveRouteGuardFromMeta(meta) {
+  if (!meta || typeof meta !== "object" || Array.isArray(meta)) {
+    return null;
+  }
+
+  if (meta.guard && typeof meta.guard === "object" && !Array.isArray(meta.guard)) {
+    return meta.guard;
+  }
+
+  if (meta.jskit && typeof meta.jskit === "object" && !Array.isArray(meta.jskit)) {
+    const jskitGuard = meta.jskit.guard;
+    if (jskitGuard && typeof jskitGuard === "object" && !Array.isArray(jskitGuard)) {
+      return jskitGuard;
+    }
+  }
+
+  return null;
+}
+
+function resolveRouteGuard(to) {
+  const matched = Array.isArray(to?.matched) ? to.matched : [];
+  for (let index = matched.length - 1; index >= 0; index -= 1) {
+    const routeRecord = matched[index] && typeof matched[index] === "object" ? matched[index] : null;
+    if (!routeRecord) {
+      continue;
+    }
+
+    if (routeRecord.guard && typeof routeRecord.guard === "object" && !Array.isArray(routeRecord.guard)) {
+      return routeRecord.guard;
+    }
+
+    const metaGuard = resolveRouteGuardFromMeta(routeRecord.meta);
+    if (metaGuard) {
+      return metaGuard;
+    }
+  }
+
+  return null;
+}
+
+function resolveSearchFromFullPath(fullPath) {
+  const rawFullPath = String(fullPath || "").trim();
+  const queryStart = rawFullPath.indexOf("?");
+  if (queryStart < 0) {
+    return "";
+  }
+
+  const hashStart = rawFullPath.indexOf("#", queryStart);
+  return hashStart < 0 ? rawFullPath.slice(queryStart) : rawFullPath.slice(queryStart, hashStart);
+}
+
+function resolveSurfaceDefinition(surfaceDefinitions, surfaceId) {
+  const normalizedSurfaceId = String(surfaceId || "")
+    .trim()
+    .toLowerCase();
+  if (!normalizedSurfaceId) {
+    return null;
+  }
+  const definition = surfaceDefinitions[normalizedSurfaceId];
+  if (!definition || typeof definition !== "object") {
+    return null;
+  }
+  return definition;
+}
+
+function normalizeWebRootAllowed(value) {
+  const normalizedValue = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (normalizedValue === WEB_ROOT_ALLOW_YES || normalizedValue === WEB_ROOT_ALLOW_NO) {
+    return normalizedValue;
+  }
+  return WEB_ROOT_ALLOW_YES;
+}
+
+function resolveDefaultSurfaceRootPath({ surfaceDefinitions, defaultSurfaceId }) {
+  const defaultSurface = resolveSurfaceDefinition(surfaceDefinitions, defaultSurfaceId);
+  return String(
+    defaultSurface?.routeBase || deriveSurfaceRouteBaseFromPagesRoot(defaultSurface?.pagesRoot || "")
+  ).trim() || "/";
+}
+
+function resolveSurfaceRequiresAuth({ pathname, surfaceRuntime, surfaceDefinitions }) {
+  const normalizedPathname = String(pathname || "/").trim() || "/";
+  const surfaceId = surfaceRuntime.resolveSurfaceFromPathname(normalizedPathname);
+  const surfaceDefinition = resolveSurfaceDefinition(surfaceDefinitions, surfaceId);
+  return Boolean(surfaceDefinition?.requiresAuth);
+}
+
+function resolveEffectiveRouteGuard({
+  to,
+  surfaceRuntime,
+  surfaceDefinitions,
+  authenticatedPolicy = AUTH_POLICY_AUTHENTICATED,
+  publicPolicy = AUTH_POLICY_PUBLIC
+}) {
+  const routeGuard = resolveRouteGuard(to);
+  const routePolicy = normalizeGuardPolicy(routeGuard?.policy);
+  if (routePolicy) {
+    return {
+      policy: routePolicy
+    };
+  }
+
+  if (
+    resolveSurfaceRequiresAuth({
+      pathname: to?.path || "/",
+      surfaceRuntime,
+      surfaceDefinitions
+    })
+  ) {
+    return {
+      policy: authenticatedPolicy
+    };
+  }
+
+  return {
+    policy: publicPolicy
+  };
+}
+
+function resolveGuardEvaluator(guardEvaluatorKey) {
+  if (typeof globalThis !== "object" || !globalThis) {
+    return null;
+  }
+
+  const evaluator = globalThis[guardEvaluatorKey];
+  if (typeof evaluator !== "function") {
+    return null;
+  }
+  return evaluator;
+}
+
+function normalizeGuardOutcome(outcome) {
+  if (outcome === false) {
+    return {
+      allow: false,
+      redirectTo: "",
+      reason: ""
+    };
+  }
+
+  if (outcome == null || outcome === true || typeof outcome !== "object" || Array.isArray(outcome)) {
+    return {
+      allow: true,
+      redirectTo: "",
+      reason: ""
+    };
+  }
+
+  return {
+    allow: outcome.allow !== false,
+    redirectTo: String(outcome.redirectTo || "").trim(),
+    reason: String(outcome.reason || "").trim()
+  };
+}
+
+function evaluateShellGuard({ guard, to, guardEvaluatorKey }) {
+  const evaluator = resolveGuardEvaluator(guardEvaluatorKey);
+  if (!evaluator) {
+    return {
+      allow: true,
+      redirectTo: "",
+      reason: ""
+    };
+  }
+
+  const pathname = String(to?.path || "/").trim() || "/";
+  const search = resolveSearchFromFullPath(to?.fullPath || "");
+
+  try {
+    return normalizeGuardOutcome(
+      evaluator({
+        guard,
+        phase: "route",
+        context: {
+          to,
+          location: {
+            pathname,
+            search
+          }
+        }
+      })
+    );
+  } catch {
+    return {
+      allow: false,
+      redirectTo: "",
+      reason: "guard-evaluator-error"
+    };
+  }
+}
+
+function createShellBeforeEachGuard({
+  surfaceRuntime,
+  surfaceDefinitions,
+  defaultSurfaceId,
+  webRootAllowed = WEB_ROOT_ALLOW_YES,
+  guardEvaluatorKey = DEFAULT_GUARD_EVALUATOR_KEY,
+  authenticatedPolicy = AUTH_POLICY_AUTHENTICATED,
+  publicPolicy = AUTH_POLICY_PUBLIC
+} = {}) {
+  if (!surfaceRuntime || typeof surfaceRuntime.resolveSurfaceFromPathname !== "function") {
+    throw new TypeError("createShellBeforeEachGuard requires surfaceRuntime.resolveSurfaceFromPathname().");
+  }
+  if (!surfaceDefinitions || typeof surfaceDefinitions !== "object" || Array.isArray(surfaceDefinitions)) {
+    throw new TypeError("createShellBeforeEachGuard requires a surfaceDefinitions object.");
+  }
+
+  return (to) => {
+    const normalizedWebRootAllowed = normalizeWebRootAllowed(webRootAllowed);
+    const defaultSurfaceRootPath = resolveDefaultSurfaceRootPath({
+      surfaceDefinitions,
+      defaultSurfaceId
+    });
+    if (
+      normalizedWebRootAllowed === WEB_ROOT_ALLOW_NO &&
+      String(to?.path || "/").trim() === "/" &&
+      defaultSurfaceRootPath !== "/"
+    ) {
+      const search = resolveSearchFromFullPath(to?.fullPath || "");
+      const hash = String(to?.hash || "").trim();
+      return `${defaultSurfaceRootPath}${search}${hash}`;
+    }
+
+    const guard = resolveEffectiveRouteGuard({
+      to,
+      surfaceRuntime,
+      surfaceDefinitions,
+      authenticatedPolicy,
+      publicPolicy
+    });
+    if (guard.policy !== authenticatedPolicy) {
+      return true;
+    }
+
+    const outcome = evaluateShellGuard({
+      guard,
+      to,
+      guardEvaluatorKey
+    });
+    if (outcome.allow) {
+      return true;
+    }
+
+    if (outcome.redirectTo) {
+      if (isExternalLinkTarget(outcome.redirectTo)) {
+        if (typeof window === "object" && window?.location && typeof window.location.assign === "function") {
+          window.location.assign(outcome.redirectTo);
+        }
+        return false;
+      }
+      return outcome.redirectTo;
+    }
+
+    return false;
+  };
+}
+
+export {
+  AUTH_POLICY_AUTHENTICATED,
+  AUTH_POLICY_PUBLIC,
+  WEB_ROOT_ALLOW_YES,
+  WEB_ROOT_ALLOW_NO,
+  DEFAULT_GUARD_EVALUATOR_KEY,
+  createFallbackNotFoundRoute,
+  buildSurfaceAwareRoutes,
+  createShellBeforeEachGuard
+};

package/client/shellRouting.test.js

@@ -0,0 +1,113 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createSurfaceRuntime } from "../shared/surface/runtime.js";
+import { buildSurfaceAwareRoutes } from "./shellRouting.js";
+
+test("buildSurfaceAwareRoutes keeps declared route paths and filters by surface mode", () => {
+  const surfaceRuntime = createSurfaceRuntime({
+    defaultSurfaceId: "app",
+    surfaces: {
+      app: { id: "app", pagesRoot: "app", enabled: true, requiresWorkspace: false },
+      coffie: { id: "coffie", pagesRoot: "coffie", enabled: true, requiresWorkspace: true },
+      console: { id: "console", pagesRoot: "console", enabled: true, requiresWorkspace: false }
+    }
+  });
+
+  const routes = buildSurfaceAwareRoutes({
+    routes: [
+      {
+        path: "/app/home",
+        name: "app-home",
+        component: {}
+      },
+      {
+        path: "/coffie",
+        name: "coffie-home",
+        component: {}
+      },
+      {
+        path: "/coffie/members",
+        name: "coffie-members",
+        component: {}
+      },
+      {
+        path: "/coffie/workspaces",
+        name: "coffie-workspaces",
+        component: {}
+      },
+      {
+        path: "/console/settings",
+        name: "console-settings",
+        component: {}
+      },
+      {
+        path: "/auth/login",
+        name: "auth-login",
+        scope: "global",
+        component: {}
+      },
+      {
+        path: "/",
+        name: "root-global",
+        component: {},
+        meta: {
+          jskit: {
+            scope: "global"
+          }
+        }
+      }
+    ],
+    surfaceRuntime,
+    surfaceMode: "all",
+    notFoundComponent: {}
+  });
+
+  const routePaths = routes.map((route) => route.path);
+  assert.equal(routePaths.includes("/coffie"), true);
+  assert.equal(routePaths.includes("/coffie/members"), true);
+  assert.equal(routePaths.includes("/coffie/workspaces"), true);
+  assert.equal(routePaths.includes("/app/home"), true);
+  assert.equal(routePaths.includes("/console/settings"), true);
+  assert.equal(routePaths.includes("/auth/login"), true);
+  assert.equal(routePaths.includes("/"), true);
+});
+
+test("buildSurfaceAwareRoutes preserves parent path when nested descendants are global", () => {
+  const surfaceRuntime = createSurfaceRuntime({
+    defaultSurfaceId: "app",
+    surfaces: {
+      app: { id: "app", pagesRoot: "w/[workspaceSlug]", enabled: true, requiresWorkspace: true },
+      admin: { id: "admin", pagesRoot: "w/[workspaceSlug]/admin", enabled: true, requiresWorkspace: true }
+    }
+  });
+
+  const routes = buildSurfaceAwareRoutes({
+    routes: [
+      {
+        path: "/account",
+        children: [
+          {
+            path: "settings",
+            children: [
+              {
+                path: "",
+                component: {},
+                meta: {
+                  jskit: {
+                    scope: "global"
+                  }
+                }
+              }
+            ]
+          }
+        ]
+      }
+    ],
+    surfaceRuntime,
+    surfaceMode: "all",
+    notFoundComponent: {}
+  });
+
+  const routePaths = routes.map((route) => route.path);
+  assert.equal(routePaths.includes("/account"), true);
+});