@jskit-ai/kernel 0.1.4

package/shared/surface/paths.js

@@ -0,0 +1,273 @@
+import { escapeRegExp } from "./escapeRegExp.js";
+
+function normalizePathname(pathname) {
+  const rawValue = String(pathname || "/").trim();
+  if (!rawValue) {
+    return "/";
+  }
+
+  const withoutQuery = rawValue.split("?")[0].split("#")[0];
+  const withLeadingSlash = withoutQuery.startsWith("/") ? withoutQuery : `/${withoutQuery}`;
+  const squashed = withLeadingSlash.replace(/\/{2,}/g, "/");
+  if (squashed === "/") {
+    return "/";
+  }
+
+  return squashed.replace(/\/+$/, "") || "/";
+}
+
+function matchesPathPrefix(pathname, prefix) {
+  const normalizedPathname = normalizePathname(pathname);
+  const normalizedPrefix = normalizePathname(prefix);
+  return normalizedPathname === normalizedPrefix || normalizedPathname.startsWith(`${normalizedPrefix}/`);
+}
+
+function compileSurfaceRouteMatcher(routeBase) {
+  const normalizedRouteBase = normalizePathname(routeBase);
+  const segments = normalizedRouteBase.split("/").filter(Boolean);
+  if (segments.length < 1) {
+    return Object.freeze({
+      routeBase: "/",
+      segmentCount: 0,
+      staticSegmentCount: 0,
+      test(pathname) {
+        return normalizePathname(pathname).startsWith("/");
+      }
+    });
+  }
+
+  const patternSegments = segments.map((segment) =>
+    segment.startsWith(":") && segment.length > 1 ? "[^/]+" : escapeRegExp(segment)
+  );
+  const pattern = new RegExp(`^/${patternSegments.join("/")}(?:$|/)`);
+  const staticSegmentCount = segments.filter(
+    (segment) => !(segment.startsWith(":") && segment.length > 1)
+  ).length;
+
+  return Object.freeze({
+    routeBase: normalizedRouteBase,
+    segmentCount: segments.length,
+    staticSegmentCount,
+    test(pathname) {
+      return pattern.test(normalizePathname(pathname));
+    }
+  });
+}
+
+function compareSurfaceRouteSpecificity(left, right) {
+  const staticDiff = right.staticSegmentCount - left.staticSegmentCount;
+  if (staticDiff !== 0) {
+    return staticDiff;
+  }
+
+  const segmentDiff = right.segmentCount - left.segmentCount;
+  if (segmentDiff !== 0) {
+    return segmentDiff;
+  }
+
+  const lengthDiff = String(right.routeBase || "").length - String(left.routeBase || "").length;
+  if (lengthDiff !== 0) {
+    return lengthDiff;
+  }
+
+  return String(left.id || "").localeCompare(String(right.id || ""));
+}
+
+function createSurfacePathHelpers(options = {}) {
+  const normalizeSurfaceId = options?.normalizeSurfaceId;
+  const resolveSurfaceRouteBaseFromRegistry = options?.resolveSurfaceRouteBase;
+  const listSurfaceDefinitions = options?.listSurfaceDefinitions;
+
+  if (typeof normalizeSurfaceId !== "function") {
+    throw new Error("createSurfacePathHelpers requires normalizeSurfaceId.");
+  }
+  if (typeof resolveSurfaceRouteBaseFromRegistry !== "function") {
+    throw new Error("createSurfacePathHelpers requires resolveSurfaceRouteBase.");
+  }
+  if (typeof listSurfaceDefinitions !== "function") {
+    throw new Error("createSurfacePathHelpers requires listSurfaceDefinitions.");
+  }
+
+  const defaultSurfaceId = normalizeSurfaceId(options?.defaultSurfaceId);
+  if (!defaultSurfaceId) {
+    throw new Error("createSurfacePathHelpers requires defaultSurfaceId.");
+  }
+
+  const apiBasePath = normalizePathname(options?.apiBasePath || "/api");
+  const routeConfig = options?.routes && typeof options.routes === "object" && !Array.isArray(options.routes) ? options.routes : {};
+
+  function normalizeSurface(surface) {
+    return normalizeSurfaceId(surface);
+  }
+
+  function resolveSurfaceRouteBase(surface) {
+    return normalizePathname(resolveSurfaceRouteBaseFromRegistry(surface));
+  }
+
+  function surfaceDefinitions() {
+    return listSurfaceDefinitions().filter(
+      (surface) => surface && typeof surface === "object" && !Array.isArray(surface)
+    );
+  }
+
+  function routedSurfaceDefinitions() {
+    return surfaceDefinitions()
+      .map((definition) => {
+        const surfaceId = normalizeSurface(definition?.id);
+        if (!surfaceId) {
+          return null;
+        }
+
+        const routeBase = resolveSurfaceRouteBase(surfaceId);
+        const matcher = compileSurfaceRouteMatcher(routeBase);
+        return {
+          id: surfaceId,
+          routeBase,
+          segmentCount: matcher.segmentCount,
+          staticSegmentCount: matcher.staticSegmentCount,
+          matcher
+        };
+      })
+      .filter(Boolean)
+      .sort(compareSurfaceRouteSpecificity);
+  }
+
+  function resolveApiNamespace(pathname) {
+    const normalizedPathname = normalizePathname(pathname);
+    if (!matchesPathPrefix(normalizedPathname, apiBasePath)) {
+      return "";
+    }
+
+    if (normalizedPathname === apiBasePath) {
+      return apiBasePath;
+    }
+
+    const remainder = normalizedPathname.slice(apiBasePath.length);
+    if (!remainder || remainder === "/") {
+      return apiBasePath;
+    }
+
+    const versionMatch = remainder.match(/^\/v[0-9]+(?:$|\/)/);
+    if (!versionMatch) {
+      return apiBasePath;
+    }
+
+    const versionPath = String(versionMatch[0]).replace(/\/$/, "");
+    return normalizePathname(`${apiBasePath}${versionPath}`);
+  }
+
+  function resolveSurfaceFromApiPathname(pathname) {
+    const apiNamespace = resolveApiNamespace(pathname);
+    if (!apiNamespace) {
+      return "";
+    }
+
+    const normalizedPathname = normalizePathname(pathname);
+    const remainder = normalizedPathname.slice(apiNamespace.length) || "/";
+    const apiRelativePath = normalizePathname(remainder.startsWith("/") ? remainder : `/${remainder}`);
+
+    for (const surface of routedSurfaceDefinitions()) {
+      if (surface.matcher.test(apiRelativePath)) {
+        return surface.id;
+      }
+    }
+
+    return defaultSurfaceId;
+  }
+
+  function resolveSurfaceFromPathname(pathname) {
+    const normalizedPathname = normalizePathname(pathname);
+    const apiSurface = resolveSurfaceFromApiPathname(normalizedPathname);
+    if (apiSurface) {
+      return apiSurface;
+    }
+
+    for (const surface of routedSurfaceDefinitions()) {
+      if (surface.matcher.test(normalizedPathname)) {
+        return surface.id;
+      }
+    }
+
+    return defaultSurfaceId;
+  }
+
+  function withSurfaceRouteBase(surface, path) {
+    const normalizedPath = normalizePathname(path);
+    const routeBase = resolveSurfaceRouteBase(surface);
+    if (normalizedPath === "/") {
+      return routeBase || "/";
+    }
+
+    if (routeBase === "/") {
+      return normalizedPath;
+    }
+    return normalizePathname(`${routeBase}${normalizedPath}`);
+  }
+
+  function normalizeOptionalRoutePath(path) {
+    const normalizedPath = String(path || "").trim();
+    if (!normalizedPath) {
+      return "";
+    }
+
+    return normalizePathname(normalizedPath);
+  }
+
+  function createSurfacePaths(surface) {
+    const normalizedSurface = normalizeSurface(surface);
+    const routeBase = resolveSurfaceRouteBase(normalizedSurface);
+
+    const rootPath = routeBase || "/";
+    const namedPaths = {};
+    for (const [routeName, routePath] of Object.entries(routeConfig)) {
+      const normalizedRouteName = String(routeName || "").trim();
+      if (!normalizedRouteName) {
+        continue;
+      }
+      const normalizedRoutePath = normalizeOptionalRoutePath(routePath);
+      if (!normalizedRoutePath) {
+        continue;
+      }
+      namedPaths[normalizedRouteName] = withSurfaceRouteBase(normalizedSurface, normalizedRoutePath);
+    }
+
+    const frozenNamedPaths = Object.freeze({
+      ...namedPaths
+    });
+
+    return {
+      surface: normalizedSurface,
+      routeBase,
+      rootPath,
+      namedPaths: frozenNamedPaths,
+      isNamedPath(routeName, pathname) {
+        const normalizedRouteName = String(routeName || "").trim();
+        if (!normalizedRouteName || !Object.hasOwn(frozenNamedPaths, normalizedRouteName)) {
+          return false;
+        }
+        return normalizePathname(pathname) === frozenNamedPaths[normalizedRouteName];
+      }
+    };
+  }
+
+  function resolveSurfacePaths(pathname) {
+    const browserPathname =
+      typeof window !== "undefined" && window?.location?.pathname ? String(window.location.pathname) : "";
+    const effectivePathname = browserPathname || pathname;
+    return createSurfacePaths(resolveSurfaceFromPathname(effectivePathname));
+  }
+
+  return Object.freeze({
+    normalizePathname,
+    matchesPathPrefix,
+    compileSurfaceRouteMatcher,
+    resolveSurfaceFromApiPathname,
+    resolveSurfaceFromPathname,
+    resolveSurfaceRouteBase,
+    withSurfaceRouteBase,
+    createSurfacePaths,
+    resolveSurfacePaths
+  });
+}
+
+export { createSurfacePathHelpers, normalizePathname, matchesPathPrefix };

package/shared/surface/registry.js

@@ -0,0 +1,135 @@
+function normalizeSurfaceId(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase();
+}
+
+function normalizeSurfacePagesRoot(pagesRootLike) {
+  const rawPagesRoot = String(pagesRootLike || "").trim();
+  if (!rawPagesRoot || rawPagesRoot === "/") {
+    return "";
+  }
+
+  return rawPagesRoot
+    .replace(/\\/g, "/")
+    .replace(/\/{2,}/g, "/")
+    .replace(/^\/+|\/+$/g, "");
+}
+
+function normalizeRouteSegment(segmentLike) {
+  const segment = String(segmentLike || "").trim();
+  if (!segment) {
+    return "";
+  }
+
+  const dynamicMatch = segment.match(/^\[([^\]]+)\]$/);
+  if (dynamicMatch) {
+    const paramName = String(dynamicMatch[1] || "").trim();
+    if (!paramName) {
+      return "";
+    }
+    return `:${paramName}`;
+  }
+
+  return segment;
+}
+
+function deriveSurfaceRouteBaseFromPagesRoot(pagesRootLike) {
+  const normalizedPagesRoot = normalizeSurfacePagesRoot(pagesRootLike);
+  if (!normalizedPagesRoot) {
+    return "/";
+  }
+
+  const segments = normalizedPagesRoot
+    .split("/")
+    .map((segment) => normalizeRouteSegment(segment))
+    .filter(Boolean);
+
+  if (segments.length < 1) {
+    return "/";
+  }
+  return `/${segments.join("/")}`;
+}
+
+function createSurfaceRegistry(options = {}) {
+  const rawSurfaces = options?.surfaces;
+  if (!rawSurfaces || typeof rawSurfaces !== "object") {
+    throw new Error("createSurfaceRegistry requires a surfaces object.");
+  }
+
+  const normalizedEntries = Object.entries(rawSurfaces)
+    .map(([key, value]) => {
+      const sourceDefinition = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+      const normalizedId = normalizeSurfaceId(sourceDefinition.id || key);
+      if (!normalizedId) {
+        return null;
+      }
+
+      const pagesRoot = normalizeSurfacePagesRoot(sourceDefinition.pagesRoot);
+      if (
+        !Object.prototype.hasOwnProperty.call(sourceDefinition, "pagesRoot") &&
+        pagesRoot === ""
+      ) {
+        throw new Error(`Surface "${normalizedId}" requires pagesRoot (use "" for root).`);
+      }
+
+      return [
+        normalizedId,
+        Object.freeze({
+          ...sourceDefinition,
+          id: normalizedId,
+          pagesRoot,
+          routeBase: deriveSurfaceRouteBaseFromPagesRoot(pagesRoot)
+        })
+      ];
+    })
+    .filter(Boolean);
+
+  if (normalizedEntries.length < 1) {
+    throw new Error("createSurfaceRegistry requires at least one surface definition.");
+  }
+
+  const SURFACE_REGISTRY = Object.freeze(Object.fromEntries(normalizedEntries));
+  const fallbackSurfaceId = normalizedEntries[0][0];
+  const requestedDefaultSurfaceId = normalizeSurfaceId(options?.defaultSurfaceId);
+  const DEFAULT_SURFACE_ID = SURFACE_REGISTRY[requestedDefaultSurfaceId]
+    ? requestedDefaultSurfaceId
+    : fallbackSurfaceId;
+
+  function normalizeRegisteredSurfaceId(value) {
+    const normalized = normalizeSurfaceId(value);
+    if (SURFACE_REGISTRY[normalized]) {
+      return normalized;
+    }
+
+    return DEFAULT_SURFACE_ID;
+  }
+
+  function resolveSurfacePagesRoot(surfaceId) {
+    return SURFACE_REGISTRY[normalizeRegisteredSurfaceId(surfaceId)]?.pagesRoot || "";
+  }
+
+  function resolveSurfaceRouteBase(surfaceId) {
+    return SURFACE_REGISTRY[normalizeRegisteredSurfaceId(surfaceId)]?.routeBase || "/";
+  }
+
+  function listSurfaceDefinitions() {
+    return Object.values(SURFACE_REGISTRY);
+  }
+
+  return Object.freeze({
+    SURFACE_REGISTRY,
+    DEFAULT_SURFACE_ID,
+    normalizeSurfaceId: normalizeRegisteredSurfaceId,
+    resolveSurfacePagesRoot,
+    resolveSurfaceRouteBase,
+    listSurfaceDefinitions
+  });
+}
+
+export {
+  createSurfaceRegistry,
+  normalizeSurfaceId,
+  normalizeSurfacePagesRoot,
+  deriveSurfaceRouteBaseFromPagesRoot
+};

package/shared/surface/registry.test.js

@@ -0,0 +1,44 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  createSurfaceRegistry,
+  deriveSurfaceRouteBaseFromPagesRoot,
+  normalizeSurfaceId,
+  normalizeSurfacePagesRoot
+} from "./registry.js";
+
+test("normalizeSurfaceId lowercases and trims", () => {
+  assert.equal(normalizeSurfaceId(" Admin "), "admin");
+  assert.equal(normalizeSurfaceId(""), "");
+  assert.equal(normalizeSurfaceId(null), "");
+});
+
+test("normalizeSurfacePagesRoot normalizes slash style and root pages root", () => {
+  assert.equal(normalizeSurfacePagesRoot(" admin "), "admin");
+  assert.equal(normalizeSurfacePagesRoot("/admin///"), "admin");
+  assert.equal(normalizeSurfacePagesRoot("/"), "");
+  assert.equal(normalizeSurfacePagesRoot(""), "");
+});
+
+test("deriveSurfaceRouteBaseFromPagesRoot converts dynamic segments", () => {
+  assert.equal(deriveSurfaceRouteBaseFromPagesRoot(""), "/");
+  assert.equal(deriveSurfaceRouteBaseFromPagesRoot("console"), "/console");
+  assert.equal(deriveSurfaceRouteBaseFromPagesRoot("w/[workspaceSlug]"), "/w/:workspaceSlug");
+  assert.equal(deriveSurfaceRouteBaseFromPagesRoot("w/[workspaceSlug]/admin"), "/w/:workspaceSlug/admin");
+});
+
+test("createSurfaceRegistry keeps registered normalization with fallback", () => {
+  const registry = createSurfaceRegistry({
+    surfaces: {
+      app: { id: "app", pagesRoot: "" },
+      admin: { id: "admin", pagesRoot: "admin" }
+    },
+    defaultSurfaceId: "app"
+  });
+
+  assert.equal(registry.normalizeSurfaceId("ADMIN"), "admin");
+  assert.equal(registry.normalizeSurfaceId("unknown"), "app");
+  assert.equal(registry.resolveSurfacePagesRoot("ADMIN"), "admin");
+  assert.equal(registry.resolveSurfaceRouteBase("ADMIN"), "/admin");
+});