@jskit-ai/kernel 0.1.4

package/server/support/SupportCoreServiceProvider.js

@@ -0,0 +1,25 @@
+import * as normalize from "../../shared/support/normalize.js";
+import * as sorting from "../../shared/support/sorting.js";
+import * as tokens from "../../shared/support/tokens.js";
+
+const SUPPORT_CORE_API = Object.freeze({
+  normalize: Object.freeze({ ...normalize }),
+  sorting: Object.freeze({ ...sorting }),
+  tokens: Object.freeze({ ...tokens })
+});
+
+class SupportCoreServiceProvider {
+  static id = "runtime.support";
+
+  register(app) {
+    if (!app || typeof app.singleton !== "function") {
+      throw new Error("SupportCoreServiceProvider requires application singleton().");
+    }
+
+    app.singleton("runtime.support", () => SUPPORT_CORE_API);
+  }
+
+  boot() {}
+}
+
+export { SupportCoreServiceProvider };

package/server/support/appConfig.js

@@ -0,0 +1,37 @@
+import { normalizeObject } from "../../shared/support/normalize.js";
+import { normalizeSurfaceId } from "../../shared/surface/registry.js";
+
+function resolveAppConfig(scope = null) {
+  const source = scope && typeof scope === "object" ? scope : null;
+  if (!source || typeof source.has !== "function" || typeof source.make !== "function") {
+    return {};
+  }
+  if (!source.has("appConfig")) {
+    return {};
+  }
+
+  return normalizeObject(source.make("appConfig"));
+}
+
+function normalizeDefaultSurfaceId(value, { fallback = "" } = {}) {
+  const normalizedValue = normalizeSurfaceId(value);
+  if (normalizedValue) {
+    return normalizedValue;
+  }
+
+  const normalizedFallback = normalizeSurfaceId(fallback);
+  if (normalizedFallback) {
+    return normalizedFallback;
+  }
+
+  return "";
+}
+
+function resolveDefaultSurfaceId(scope = null, { defaultSurfaceId = "" } = {}) {
+  const appConfig = resolveAppConfig(scope);
+  return normalizeDefaultSurfaceId(defaultSurfaceId, {
+    fallback: appConfig.surfaceDefaultId
+  });
+}
+
+export { resolveAppConfig, normalizeDefaultSurfaceId, resolveDefaultSurfaceId };

package/server/support/appConfig.test.js

@@ -0,0 +1,94 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  resolveAppConfig,
+  normalizeDefaultSurfaceId,
+  resolveDefaultSurfaceId
+} from "./appConfig.js";
+
+test("resolveAppConfig returns normalized appConfig when scope exposes appConfig binding", () => {
+  const config = resolveAppConfig({
+    has(token) {
+      return token === "appConfig";
+    },
+    make(token) {
+      assert.equal(token, "appConfig");
+      return {
+        surfaceDefaultId: "home"
+      };
+    }
+  });
+
+  assert.deepEqual(config, {
+    surfaceDefaultId: "home"
+  });
+});
+
+test("resolveAppConfig returns empty object when scope has no appConfig binding", () => {
+  const config = resolveAppConfig({
+    has() {
+      return false;
+    },
+    make() {
+      throw new Error("make should not be called");
+    }
+  });
+
+  assert.deepEqual(config, {});
+});
+
+test("resolveAppConfig returns empty object for non-container values", () => {
+  assert.deepEqual(resolveAppConfig(null), {});
+  assert.deepEqual(resolveAppConfig({}), {});
+  assert.deepEqual(resolveAppConfig({ has: () => true }), {});
+});
+
+test("normalizeDefaultSurfaceId normalizes explicit values and fallback values", () => {
+  assert.equal(normalizeDefaultSurfaceId(" HOME "), "home");
+  assert.equal(normalizeDefaultSurfaceId("", { fallback: " Console " }), "console");
+  assert.equal(normalizeDefaultSurfaceId("", { fallback: "" }), "");
+});
+
+test("resolveDefaultSurfaceId prefers explicit default surface", () => {
+  const surfaceId = resolveDefaultSurfaceId(
+    {
+      has(token) {
+        return token === "appConfig";
+      },
+      make() {
+        return {
+          surfaceDefaultId: "admin"
+        };
+      }
+    },
+    {
+      defaultSurfaceId: "home"
+    }
+  );
+
+  assert.equal(surfaceId, "home");
+});
+
+test("resolveDefaultSurfaceId falls back to appConfig and then empty default", () => {
+  const fromAppConfig = resolveDefaultSurfaceId({
+    has(token) {
+      return token === "appConfig";
+    },
+    make() {
+      return {
+        surfaceDefaultId: "console"
+      };
+    }
+  });
+  assert.equal(fromAppConfig, "console");
+
+  const fromKernelFallback = resolveDefaultSurfaceId({
+    has() {
+      return false;
+    },
+    make() {
+      throw new Error("make should not be called");
+    }
+  });
+  assert.equal(fromKernelFallback, "");
+});

package/server/support/defaultMissingHandler.js

@@ -0,0 +1,7 @@
+function defaultMissingHandler(_request, reply) {
+  reply.code(501).send({
+    error: "Route handler is not available in this runtime profile."
+  });
+}
+
+export { defaultMissingHandler };

package/server/support/index.js

@@ -0,0 +1,2 @@
+export { symlinkSafeRequire } from "./symlinkSafeRequire.js";
+export { resolveAppConfig } from "./appConfig.js";

package/server/support/routePolicyConfig.js

@@ -0,0 +1,51 @@
+import { normalizeRouteVisibilityToken } from "../../shared/support/visibility.js";
+import { isRecord } from "../../shared/support/normalize.js";
+
+function normalizeRoutePolicyConfig(routeOptions, route) {
+  const sourceRouteOptions = isRecord(routeOptions) ? routeOptions : {};
+  const sourceConfig = isRecord(sourceRouteOptions.config) ? sourceRouteOptions.config : {};
+  const sourceRoute = isRecord(route) ? route : {};
+
+  const nextConfig = {
+    ...sourceConfig
+  };
+
+  if (Object.prototype.hasOwnProperty.call(sourceRoute, "auth")) {
+    nextConfig.authPolicy = sourceRoute.auth;
+  }
+  if (Object.prototype.hasOwnProperty.call(sourceRoute, "contextPolicy")) {
+    nextConfig.contextPolicy = sourceRoute.contextPolicy;
+  }
+  if (Object.prototype.hasOwnProperty.call(sourceRoute, "surface")) {
+    nextConfig.surface = sourceRoute.surface;
+  }
+  if (Object.prototype.hasOwnProperty.call(sourceRoute, "visibility")) {
+    nextConfig.visibility = normalizeRouteVisibilityToken(sourceRoute.visibility);
+  }
+  if (Object.prototype.hasOwnProperty.call(sourceRoute, "permission")) {
+    nextConfig.permission = sourceRoute.permission;
+  }
+  if (Object.prototype.hasOwnProperty.call(sourceRoute, "ownerParam")) {
+    nextConfig.ownerParam = sourceRoute.ownerParam;
+  }
+  if (Object.prototype.hasOwnProperty.call(sourceRoute, "userField")) {
+    nextConfig.userField = sourceRoute.userField;
+  }
+  if (Object.prototype.hasOwnProperty.call(sourceRoute, "ownerResolver")) {
+    nextConfig.ownerResolver = sourceRoute.ownerResolver;
+  }
+  if (Object.prototype.hasOwnProperty.call(sourceRoute, "csrfProtection")) {
+    nextConfig.csrfProtection = sourceRoute.csrfProtection;
+  }
+
+  return nextConfig;
+}
+
+function defaultApplyRoutePolicy(routeOptions, route) {
+  return {
+    ...routeOptions,
+    config: normalizeRoutePolicyConfig(routeOptions, route)
+  };
+}
+
+export { normalizeRoutePolicyConfig, defaultApplyRoutePolicy };

package/server/support/symlinkSafeRequire.js

@@ -0,0 +1,78 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+
+function createRequireFromTarget(targetPath) {
+  const normalized = String(targetPath || "").trim();
+  if (!normalized) {
+    return null;
+  }
+
+  try {
+    return createRequire(normalized);
+  } catch {
+    return null;
+  }
+}
+
+function createAppRootRequire() {
+  const cwd = String(process.cwd() || "").trim();
+  if (!cwd) {
+    return null;
+  }
+
+  return createRequireFromTarget(path.join(cwd, "package.json"));
+}
+
+function createEntryScriptRequire() {
+  const entryScriptPath = String(process.argv?.[1] || "").trim();
+  if (!entryScriptPath) {
+    return null;
+  }
+
+  return createRequireFromTarget(path.resolve(entryScriptPath));
+}
+
+const localRequire = createRequire(import.meta.url);
+
+function uniqueRequireChain(candidates = []) {
+  const chain = [];
+  for (const candidate of candidates) {
+    if (typeof candidate !== "function") {
+      continue;
+    }
+    if (chain.includes(candidate)) {
+      continue;
+    }
+    chain.push(candidate);
+  }
+  return chain;
+}
+
+function symlinkSafeRequire(moduleId = "") {
+  const normalizedModuleId = String(moduleId || "").trim();
+  if (!normalizedModuleId) {
+    throw new TypeError("symlinkSafeRequire requires a non-empty module id.");
+  }
+
+  const requireChain = uniqueRequireChain([createAppRootRequire(), createEntryScriptRequire(), localRequire]);
+  let lastModuleNotFoundError = null;
+
+  for (const candidateRequire of requireChain) {
+    try {
+      return candidateRequire(normalizedModuleId);
+    } catch (error) {
+      if (String(error?.code || "").trim() === "MODULE_NOT_FOUND") {
+        lastModuleNotFoundError = error;
+        continue;
+      }
+      throw error;
+    }
+  }
+
+  if (lastModuleNotFoundError) {
+    throw lastModuleNotFoundError;
+  }
+  throw new Error(`Failed to resolve module "${normalizedModuleId}".`);
+}
+
+export { symlinkSafeRequire };

package/server/support/symlinkSafeRequire.test.js

@@ -0,0 +1,27 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import test from "node:test";
+import { symlinkSafeRequire } from "./symlinkSafeRequire.js";
+
+test("symlinkSafeRequire requires a non-empty module id", () => {
+  assert.throws(() => symlinkSafeRequire(""), /requires a non-empty module id/);
+});
+
+test("symlinkSafeRequire resolves modules from app cwd node_modules", async () => {
+  const appRoot = await mkdtemp(path.join(tmpdir(), "jskit-symlink-safe-require-"));
+  const knexPackageDir = path.join(appRoot, "node_modules", "knex");
+  await mkdir(knexPackageDir, { recursive: true });
+  await writeFile(path.join(knexPackageDir, "package.json"), JSON.stringify({ name: "knex", main: "index.js" }), "utf8");
+  await writeFile(path.join(knexPackageDir, "index.js"), "module.exports = { source: 'app-cwd' };", "utf8");
+
+  const previousCwd = process.cwd();
+  try {
+    process.chdir(appRoot);
+    const loaded = symlinkSafeRequire("knex");
+    assert.equal(loaded?.source, "app-cwd");
+  } finally {
+    process.chdir(previousCwd);
+  }
+});

package/server/surface/SurfaceRoutingServiceProvider.js

@@ -0,0 +1,27 @@
+import * as apiPaths from "../../shared/surface/apiPaths.js";
+import * as paths from "../../shared/surface/paths.js";
+import * as registry from "../../shared/surface/registry.js";
+import { escapeRegExp } from "../../shared/surface/escapeRegExp.js";
+
+const SURFACE_ROUTING_API = Object.freeze({
+  apiPaths: Object.freeze({ ...apiPaths }),
+  paths: Object.freeze({ ...paths }),
+  registry: Object.freeze({ ...registry }),
+  escapeRegExp
+});
+
+class SurfaceRoutingServiceProvider {
+  static id = "runtime.surface-routing";
+
+  register(app) {
+    if (!app || typeof app.singleton !== "function") {
+      throw new Error("SurfaceRoutingServiceProvider requires application singleton().");
+    }
+
+    app.singleton("runtime.surface-routing", () => SURFACE_ROUTING_API);
+  }
+
+  boot() {}
+}
+
+export { SurfaceRoutingServiceProvider };

package/server/surface/index.js

@@ -0,0 +1,19 @@
+export { createSurfaceRegistry, normalizeSurfaceId } from "../../shared/surface/registry.js";
+export { createSurfacePathHelpers } from "../../shared/surface/paths.js";
+export { createSurfaceRuntime, filterRoutesBySurface } from "../../shared/surface/runtime.js";
+export { escapeRegExp } from "../../shared/surface/escapeRegExp.js";
+export {
+  API_BASE_PATH,
+  API_PREFIX,
+  API_PREFIX_SLASH,
+  API_DOCS_PATH,
+  API_REALTIME_PATH,
+  normalizePathname,
+  isApiPath,
+  isVersionedApiPath,
+  toVersionedApiPath,
+  toVersionedApiPrefix,
+  buildVersionedApiPath,
+  isVersionedApiPrefixMatch
+} from "../../shared/surface/apiPaths.js";
+export { SurfaceRoutingServiceProvider } from "./SurfaceRoutingServiceProvider.js";

package/shared/actions/actionContributorHelpers.js

@@ -0,0 +1,34 @@
+import { Type } from "typebox";
+import { normalizeObject, normalizePositiveInteger as toPositiveInteger } from "../support/normalize.js";
+import { hasPermission } from "../support/permissions.js";
+
+function requireServiceMethod(service, methodName, contributorId, { serviceLabel } = {}) {
+  if (!service || typeof service[methodName] !== "function") {
+    const prefix = serviceLabel ? `${serviceLabel}.` : "";
+    throw new Error(`${contributorId} requires ${prefix}${methodName}().`);
+  }
+}
+
+function resolveRequest(context) {
+  return context?.requestMeta?.request || null;
+}
+
+const OBJECT_INPUT_VALIDATOR = Object.freeze({
+  parse(value) {
+    return normalizeObject(value);
+  }
+});
+
+const EMPTY_INPUT_VALIDATOR = Object.freeze({
+  schema: Type.Object({}, { additionalProperties: false })
+});
+
+export {
+  normalizeObject,
+  toPositiveInteger,
+  requireServiceMethod,
+  resolveRequest,
+  hasPermission,
+  EMPTY_INPUT_VALIDATOR,
+  OBJECT_INPUT_VALIDATOR
+};

package/shared/actions/actionContributorHelpers.test.js

@@ -0,0 +1,16 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { hasPermission } from "./actionContributorHelpers.js";
+
+test("hasPermission allows wildcard and direct matches", () => {
+  assert.equal(hasPermission(["*"], "workspace.billing.manage"), true);
+  assert.equal(hasPermission(["workspace.billing.manage"], "workspace.billing.manage"), true);
+  assert.equal(hasPermission(["workspace.billing.*"], "workspace.billing.manage"), true);
+  assert.equal(hasPermission(["workspace.billing.read"], "workspace.billing.manage"), false);
+});
+
+test("hasPermission allows empty required permissions", () => {
+  assert.equal(hasPermission([], ""), true);
+  assert.equal(hasPermission([], null), true);
+});