@jskit-ai/kernel 0.1.38 → 0.1.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/kernel",
-  "version": "0.1.38",
+  "version": "0.1.40",
   "type": "module",
   "dependencies": {
     "typebox": "^1.0.81"
@@ -19,6 +19,7 @@
     "./server/actions": "./server/actions/index.js",
     "./server/http": "./server/http/index.js",
     "./server/platform": "./server/platform/index.js",
+    "./server/registries": "./server/registries/index.js",
     "./server/runtime": "./server/runtime/index.js",
     "./server/runtime/errors": "./server/runtime/errors.js",
     "./server/runtime/requestUrl": "./server/runtime/requestUrl.js",

package/shared/support/visibility.js

@@ -3,6 +3,15 @@ import { ROUTE_VISIBILITY_PUBLIC, ROUTE_VISIBILITY_USER } from "./policies.js";
 
 const ROUTE_VISIBILITY_LEVELS = Object.freeze([ROUTE_VISIBILITY_PUBLIC, ROUTE_VISIBILITY_USER]);
 const ROUTE_VISIBILITY_LEVEL_SET = new Set(ROUTE_VISIBILITY_LEVELS);
+const ROUTE_VISIBILITY_WORKSPACE = "workspace";
+const ROUTE_VISIBILITY_WORKSPACE_USER = "workspace_user";
+const ROUTE_VISIBILITY_TOKENS = Object.freeze([
+  ROUTE_VISIBILITY_PUBLIC,
+  ROUTE_VISIBILITY_USER,
+  ROUTE_VISIBILITY_WORKSPACE,
+  ROUTE_VISIBILITY_WORKSPACE_USER
+]);
+const ROUTE_VISIBILITY_TOKEN_SET = new Set(ROUTE_VISIBILITY_TOKENS);
 
 function normalizeRouteVisibilityToken(value, { fallback = ROUTE_VISIBILITY_PUBLIC } = {}) {
   const normalized = normalizeText(value).toLowerCase();
@@ -34,6 +43,22 @@ function normalizeRouteVisibility(value, { fallback = ROUTE_VISIBILITY_PUBLIC }
   return ROUTE_VISIBILITY_PUBLIC;
 }
 
+function checkRouteVisibility(value, { context = "checkRouteVisibility" } = {}) {
+  const normalized = normalizeRouteVisibilityToken(value);
+  if (ROUTE_VISIBILITY_TOKEN_SET.has(normalized)) {
+    return normalized;
+  }
+
+  throw new TypeError(`${context} must be one of: ${ROUTE_VISIBILITY_TOKENS.join(", ")}.`);
+}
+
+function isWorkspaceRouteVisibility(value = "") {
+  const normalized = checkRouteVisibility(value, {
+    context: "isWorkspaceRouteVisibility visibility"
+  });
+  return normalized === ROUTE_VISIBILITY_WORKSPACE || normalized === ROUTE_VISIBILITY_WORKSPACE_USER;
+}
+
 function normalizeVisibilityScopeKind(value) {
   const normalized = normalizeText(value).toLowerCase();
   return normalized || null;
@@ -53,4 +78,16 @@ function normalizeVisibilityContext(value = {}) {
   });
 }
 
-export { ROUTE_VISIBILITY_LEVELS, normalizeRouteVisibilityToken, normalizeRouteVisibility, normalizeVisibilityContext };
+export {
+  ROUTE_VISIBILITY_LEVELS,
+  ROUTE_VISIBILITY_PUBLIC,
+  ROUTE_VISIBILITY_USER,
+  ROUTE_VISIBILITY_WORKSPACE,
+  ROUTE_VISIBILITY_WORKSPACE_USER,
+  ROUTE_VISIBILITY_TOKENS,
+  normalizeRouteVisibilityToken,
+  normalizeRouteVisibility,
+  checkRouteVisibility,
+  isWorkspaceRouteVisibility,
+  normalizeVisibilityContext
+};

package/shared/support/visibility.test.js

@@ -1,6 +1,12 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { normalizeRouteVisibilityToken, normalizeRouteVisibility, normalizeVisibilityContext } from "./visibility.js";
+import {
+  checkRouteVisibility,
+  isWorkspaceRouteVisibility,
+  normalizeRouteVisibilityToken,
+  normalizeRouteVisibility,
+  normalizeVisibilityContext
+} from "./visibility.js";
 
 test("normalizeRouteVisibility keeps kernel core visibility contract", () => {
   assert.equal(normalizeRouteVisibility("PUBLIC"), "public");
@@ -18,6 +24,18 @@ test("normalizeRouteVisibilityToken normalizes visibility tokens for module-leve
   assert.equal(normalizeRouteVisibilityToken("", { fallback: "workspace" }), "workspace");
 });
 
+test("checkRouteVisibility accepts workspace visibility tokens", () => {
+  assert.equal(checkRouteVisibility("workspace"), "workspace");
+  assert.equal(checkRouteVisibility("workspace_user"), "workspace_user");
+  assert.throws(() => checkRouteVisibility("invalid"), /must be one of/);
+});
+
+test("isWorkspaceRouteVisibility matches only workspace-scoped tokens", () => {
+  assert.equal(isWorkspaceRouteVisibility("workspace"), true);
+  assert.equal(isWorkspaceRouteVisibility("workspace_user"), true);
+  assert.equal(isWorkspaceRouteVisibility("public"), false);
+});
+
 test("normalizeVisibilityContext normalizes mode and owner identifiers", () => {
   assert.deepEqual(normalizeVisibilityContext({ visibility: "user", userId: "7" }), {
     visibility: "user",

package/shared/surface/apiPaths.js

@@ -7,6 +7,76 @@ const API_DOCS_PATH = `${API_PREFIX}/docs`;
 const API_REALTIME_PATH = `${API_PREFIX}/realtime`;
 const VERSIONED_API_PATH_PATTERN = /^\/api\/v[0-9]+(?:$|\/)/;
 
+function normalizeRouteTemplateParams(params = null) {
+  if (!params || typeof params !== "object" || Array.isArray(params)) {
+    return {};
+  }
+  return params;
+}
+
+function materializeRouteTemplate(routeTemplate = "/", { params = {}, strictParams = true, context = "materializeRouteTemplate" } = {}) {
+  const normalizedTemplate = normalizePathname(routeTemplate);
+  const normalizedParams = normalizeRouteTemplateParams(params);
+  const missingParams = new Set();
+  const outputPath = String(normalizedTemplate || "/").replace(/:([A-Za-z0-9_]+)/g, (_full, rawName) => {
+    const paramName = String(rawName || "").trim();
+    const rawValue = normalizedParams[paramName];
+    const paramValue = String(Array.isArray(rawValue) ? rawValue[0] : rawValue ?? "").trim();
+    if (!paramValue) {
+      missingParams.add(paramName);
+      return `:${paramName}`;
+    }
+    return encodeURIComponent(paramValue);
+  });
+
+  if (strictParams && missingParams.size > 0) {
+    throw new Error(`${context} missing required route params: ${[...missingParams].sort().join(", ")}.`);
+  }
+
+  return outputPath;
+}
+
+function resolveScopedRouteBase(routeBase = "/") {
+  const normalizedRouteBase = normalizePathname(routeBase);
+  const segments = normalizedRouteBase.split("/").filter(Boolean);
+  let lastDynamicIndex = -1;
+
+  for (let index = 0; index < segments.length; index += 1) {
+    const segment = segments[index];
+    if (segment.startsWith(":") && segment.length > 1) {
+      lastDynamicIndex = index;
+    }
+  }
+
+  if (lastDynamicIndex < 0) {
+    return "/";
+  }
+
+  return `/${segments.slice(0, lastDynamicIndex + 1).join("/")}`;
+}
+
+function resolveScopedApiBasePath({
+  routeBase = "/",
+  relativePath = "/",
+  params = {},
+  strictParams = true
+} = {}) {
+  const scopedRouteBase = resolveScopedRouteBase(routeBase);
+  const materializedScopeBase = materializeRouteTemplate(scopedRouteBase, {
+    params,
+    strictParams,
+    context: "resolveScopedApiBasePath"
+  });
+  const basePath = materializedScopeBase === "/" ? API_BASE_PATH : `${API_BASE_PATH}${materializedScopeBase}`;
+  const normalizedRelativePath = normalizePathname(relativePath || "/");
+
+  if (normalizedRelativePath === "/") {
+    return basePath;
+  }
+
+  return `${basePath}${normalizedRelativePath}`;
+}
+
 function isApiPath(pathname) {
   return matchesPathPrefix(pathname, API_BASE_PATH);
 }
@@ -74,11 +144,14 @@ export {
   API_PREFIX_SLASH,
   API_DOCS_PATH,
   API_REALTIME_PATH,
+  materializeRouteTemplate,
   normalizePathname,
   isApiPath,
   isVersionedApiPath,
   toVersionedApiPath,
   toVersionedApiPrefix,
   buildVersionedApiPath,
-  isVersionedApiPrefixMatch
+  isVersionedApiPrefixMatch,
+  resolveScopedRouteBase,
+  resolveScopedApiBasePath
 };

package/shared/surface/apiPaths.test.js

@@ -0,0 +1,31 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { resolveScopedApiBasePath, resolveScopedRouteBase } from "./apiPaths.js";
+
+test("resolveScopedRouteBase keeps the route prefix through the last dynamic segment", () => {
+  assert.equal(resolveScopedRouteBase("/"), "/");
+  assert.equal(resolveScopedRouteBase("/home"), "/");
+  assert.equal(resolveScopedRouteBase("/w/:workspaceSlug"), "/w/:workspaceSlug");
+  assert.equal(resolveScopedRouteBase("/w/:workspaceSlug/admin"), "/w/:workspaceSlug");
+  assert.equal(resolveScopedRouteBase("/org/:orgId/team/:teamId/admin"), "/org/:orgId/team/:teamId");
+});
+
+test("resolveScopedApiBasePath materializes scoped API paths from route templates", () => {
+  assert.equal(resolveScopedApiBasePath({ routeBase: "/home", relativePath: "/settings" }), "/api/settings");
+  assert.equal(
+    resolveScopedApiBasePath({
+      routeBase: "/w/:workspaceSlug/admin",
+      relativePath: "/members",
+      params: { workspaceSlug: "acme" }
+    }),
+    "/api/w/acme/members"
+  );
+  assert.throws(
+    () =>
+      resolveScopedApiBasePath({
+        routeBase: "/w/:workspaceSlug/admin",
+        relativePath: "/members"
+      }),
+    /missing required route params/
+  );
+});

package/shared/surface/index.js

@@ -4,3 +4,7 @@ export {
   deriveSurfaceRouteBaseFromPagesRoot
 } from "./registry.js";
 export { createSurfacePathHelpers } from "./paths.js";
+export {
+  resolveScopedRouteBase,
+  resolveScopedApiBasePath
+} from "./apiPaths.js";