@jskit-ai/kernel 0.1.4

package/server/platform/providerRuntime.js

@@ -0,0 +1,142 @@
+import { ActionRuntimeServiceProvider } from "../actions/ActionRuntimeServiceProvider.js";
+import { ServerRuntimeCoreServiceProvider } from "../runtime/ServerRuntimeCoreServiceProvider.js";
+import { createApplication } from "../kernel/index.js";
+import { createHttpRuntime } from "../http/lib/kernel.js";
+import { KERNEL_TOKENS } from "../../shared/support/tokens.js";
+import { readLockFromApp } from "./providerRuntime/lockfile.js";
+import {
+  collectGlobalUiPaths,
+  resolveInstalledPackageDescriptors,
+  resolveDescriptorLoadOrder,
+  validateDescriptorCapabilities
+} from "./providerRuntime/descriptorCatalog.js";
+import { loadPackageProviders, registerProviderClass } from "./providerRuntime/providerLoader.js";
+
+const KERNEL_BUILTIN_CAPABILITY_PROVIDERS = Object.freeze({
+  "runtime.actions": Object.freeze(["@jskit-ai/kernel"])
+});
+
+async function createProviderRuntimeApp({
+  profile = "",
+  providers = [],
+  env = {},
+  logger = console,
+  fastify = null
+} = {}) {
+  const app = createApplication({
+    profile
+  });
+
+  app.instance(KERNEL_TOKENS.Env, env && typeof env === "object" ? { ...env } : {});
+  app.instance(KERNEL_TOKENS.Logger, logger || console);
+
+  let httpRuntime = null;
+  if (fastify && typeof fastify.route === "function") {
+    httpRuntime = createHttpRuntime({
+      app,
+      fastify
+    });
+  }
+
+  await app.start({ providers });
+
+  const routeRegistration = httpRuntime ? httpRuntime.registerRoutes() : { routeCount: 0 };
+  return Object.freeze({
+    app,
+    routeCount: routeRegistration.routeCount,
+    routeRegistration,
+    diagnostics: app.getDiagnostics()
+  });
+}
+
+async function createProviderRuntimeFromApp({
+  appRoot,
+  lockPath = ".jskit/lock.json",
+  profile = "",
+  env = {},
+  logger = console,
+  fastify = null
+} = {}) {
+  if (!appRoot || typeof appRoot !== "string") {
+    throw new TypeError("createProviderRuntimeFromApp requires appRoot.");
+  }
+
+  const { lock } = await readLockFromApp({
+    appRoot,
+    lockPath
+  });
+  const descriptors = await resolveInstalledPackageDescriptors({
+    appRoot,
+    lock
+  });
+  validateDescriptorCapabilities(descriptors, {
+    builtinProvidersByCapability: KERNEL_BUILTIN_CAPABILITY_PROVIDERS
+  });
+  const orderedDescriptors = resolveDescriptorLoadOrder(descriptors);
+  const catalog = Object.freeze({
+    packageOrder: Object.freeze(orderedDescriptors.map((entry) => entry.packageId)),
+    globalUiPaths: collectGlobalUiPaths(orderedDescriptors),
+    descriptors: Object.freeze(orderedDescriptors)
+  });
+
+  const orderedProviderClasses = [];
+  const providerPackageIds = [];
+  const seenProviderIds = new Map();
+
+  for (const descriptorEntry of catalog.descriptors) {
+    const packageProviders = await loadPackageProviders({ descriptorEntry });
+    if (packageProviders.length < 1) {
+      continue;
+    }
+    providerPackageIds.push(descriptorEntry.packageId);
+
+    for (const providerClass of packageProviders) {
+      registerProviderClass({
+        providerClass,
+        sourceId: descriptorEntry.packageId,
+        seenProviderIds,
+        orderedProviderClasses
+      });
+    }
+  }
+
+  if (!seenProviderIds.has(ActionRuntimeServiceProvider.id)) {
+    registerProviderClass({
+      providerClass: ActionRuntimeServiceProvider,
+      sourceId: "@jskit-ai/kernel",
+      seenProviderIds,
+      orderedProviderClasses
+    });
+  }
+
+  if (!seenProviderIds.has(ServerRuntimeCoreServiceProvider.id)) {
+    registerProviderClass({
+      providerClass: ServerRuntimeCoreServiceProvider,
+      sourceId: "@jskit-ai/kernel",
+      seenProviderIds,
+      orderedProviderClasses
+    });
+  }
+
+  const envRecord = env && typeof env === "object" ? { ...env } : {};
+  const loggerInstance = logger || console;
+
+  const providerRuntime = await createProviderRuntimeApp({
+    profile,
+    providers: orderedProviderClasses,
+    env: envRecord,
+    logger: loggerInstance,
+    fastify
+  });
+
+  return Object.freeze({
+    ...providerRuntime,
+    routeCount: providerRuntime.routeCount,
+    packageOrder: catalog.packageOrder,
+    globalUiPaths: catalog.globalUiPaths,
+    providerPackageOrder: Object.freeze(providerPackageIds),
+    appLocalProviderOrder: Object.freeze([])
+  });
+}
+
+export { createProviderRuntimeApp, createProviderRuntimeFromApp };

package/server/platform/providerRuntime.test.js

@@ -0,0 +1,217 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { createProviderRuntimeFromApp } from "./providerRuntime.js";
+
+async function createTestAppRoot(prefix) {
+  const appRoot = await mkdtemp(path.join(tmpdir(), prefix));
+  await mkdir(path.join(appRoot, ".jskit"), { recursive: true });
+  await writeFile(
+    path.join(appRoot, ".jskit", "lock.json"),
+    `${JSON.stringify({ lockVersion: 1, installedPackages: {} }, null, 2)}\n`,
+    "utf8"
+  );
+  return appRoot;
+}
+
+test("createProviderRuntimeFromApp discovers package providers from descriptor discover entries", async () => {
+  const appRoot = await createTestAppRoot("kernel-provider-runtime-discover-");
+  try {
+    await mkdir(path.join(appRoot, "packages", "local-example", "src", "server", "providers"), { recursive: true });
+    await writeFile(
+      path.join(appRoot, ".jskit", "lock.json"),
+      `${JSON.stringify(
+        {
+          lockVersion: 1,
+          installedPackages: {
+            "@local/example": {
+              packageId: "@local/example",
+              version: "0.1.0",
+              source: {
+                type: "local-package",
+                packagePath: "packages/local-example"
+              },
+              managed: {
+                packageJson: {
+                  dependencies: {},
+                  devDependencies: {},
+                  scripts: {}
+                },
+                text: {},
+                files: []
+              },
+              options: {},
+              installedAt: "2026-01-01T00:00:00.000Z"
+            }
+          }
+        },
+        null,
+        2
+      )}\n`,
+      "utf8"
+    );
+    await writeFile(
+      path.join(appRoot, "packages", "local-example", "package.descriptor.mjs"),
+      [
+        "export default Object.freeze({",
+        "  packageVersion: 1,",
+        "  packageId: \"@local/example\",",
+        "  version: \"0.1.0\",",
+        "  description: \"Local example package\",",
+        "  dependsOn: [],",
+        "  capabilities: {",
+        "    provides: [],",
+        "    requires: []",
+        "  },",
+        "  runtime: {",
+        "    server: {",
+        "      providers: [",
+        "        { discover: { dir: \"src/server/providers\", pattern: \"*Provider.js\" } }",
+        "      ]",
+        "    }",
+        "  }",
+        "});"
+      ].join("\n"),
+      "utf8"
+    );
+    await writeFile(
+      path.join(appRoot, "packages", "local-example", "src", "server", "providers", "AlphaProvider.js"),
+      [
+        "export default class AlphaProvider {",
+        "  static id = \"example.alpha\";",
+        "  register(app) {",
+        "    app.instance(\"example.alpha.value\", 42);",
+        "  }",
+        "  boot() {}",
+        "}"
+      ].join("\n"),
+      "utf8"
+    );
+    await writeFile(
+      path.join(appRoot, "packages", "local-example", "src", "server", "providers", "ignored.js"),
+      "export const value = 1;\n",
+      "utf8"
+    );
+
+    const runtime = await createProviderRuntimeFromApp({
+      appRoot,
+      profile: "app"
+    });
+
+    assert.deepEqual(runtime.packageOrder, ["@local/example"]);
+    assert.deepEqual(runtime.providerPackageOrder, ["@local/example"]);
+    assert.equal(runtime.appLocalProviderOrder.length, 0);
+    assert.deepEqual(runtime.diagnostics.providerOrder, ["example.alpha", "runtime.actions", "runtime.server"]);
+    assert.equal(runtime.app.make("example.alpha.value"), 42);
+    assert.equal(typeof runtime.app.make("actionExecutor")?.execute, "function");
+  } finally {
+    await rm(appRoot, { recursive: true, force: true });
+  }
+});
+
+test("createProviderRuntimeFromApp ignores legacy app local src/server/providers folder", async () => {
+  const appRoot = await createTestAppRoot("kernel-provider-runtime-legacy-app-local-");
+  try {
+    await mkdir(path.join(appRoot, "src", "server", "providers"), { recursive: true });
+    await writeFile(
+      path.join(appRoot, "src", "server", "providers", "LegacyProvider.js"),
+      [
+        "export default class LegacyProvider {",
+        "  static id = \"legacy.app.local\";",
+        "  register(app) {",
+        "    app.instance(\"legacy.value\", true);",
+        "  }",
+        "  boot() {}",
+        "}"
+      ].join("\n"),
+      "utf8"
+    );
+
+    const runtime = await createProviderRuntimeFromApp({
+      appRoot,
+      profile: "app"
+    });
+
+    assert.deepEqual(runtime.packageOrder, []);
+    assert.deepEqual(runtime.providerPackageOrder, []);
+    assert.equal(runtime.appLocalProviderOrder.length, 0);
+    assert.deepEqual(runtime.diagnostics.providerOrder, ["runtime.actions", "runtime.server"]);
+    assert.equal(runtime.app.has("legacy.value"), false);
+  } finally {
+    await rm(appRoot, { recursive: true, force: true });
+  }
+});
+
+test("createProviderRuntimeFromApp resolves descriptor using source.packagePath", async () => {
+  const appRoot = await createTestAppRoot("kernel-provider-runtime-local-package-");
+  try {
+    await mkdir(path.join(appRoot, "packages", "local-example"), { recursive: true });
+    await writeFile(
+      path.join(appRoot, ".jskit", "lock.json"),
+      `${JSON.stringify(
+        {
+          lockVersion: 1,
+          installedPackages: {
+            "@local/example": {
+              packageId: "@local/example",
+              version: "0.1.0",
+              source: {
+                type: "local-package",
+                packagePath: "packages/local-example"
+              },
+              managed: {
+                packageJson: {
+                  dependencies: {},
+                  devDependencies: {},
+                  scripts: {}
+                },
+                text: {},
+                files: []
+              },
+              options: {},
+              installedAt: "2026-01-01T00:00:00.000Z"
+            }
+          }
+        },
+        null,
+        2
+      )}\n`,
+      "utf8"
+    );
+    await writeFile(
+      path.join(appRoot, "packages", "local-example", "package.descriptor.mjs"),
+      [
+        "export default Object.freeze({",
+        "  packageVersion: 1,",
+        "  packageId: \"@local/example\",",
+        "  version: \"0.1.0\",",
+        "  description: \"Local example package\",",
+        "  dependsOn: [],",
+        "  capabilities: {",
+        "    provides: [],",
+        "    requires: []",
+        "  },",
+        "  runtime: {",
+        "    server: {",
+        "      providers: []",
+        "    }",
+        "  }",
+        "});"
+      ].join("\n"),
+      "utf8"
+    );
+
+    const runtime = await createProviderRuntimeFromApp({
+      appRoot,
+      profile: "app"
+    });
+
+    assert.deepEqual(runtime.packageOrder, ["@local/example"]);
+    assert.deepEqual(runtime.providerPackageOrder, []);
+  } finally {
+    await rm(appRoot, { recursive: true, force: true });
+  }
+});

package/server/platform/runtime.js

@@ -0,0 +1,40 @@
+import { createRuntimeAssembly } from "../runtime/runtimeAssembly.js";
+
+function createPlatformRuntimeBundle({
+  repositoryDefinitions = [],
+  serviceDefinitions = [],
+  controllerDefinitions = [],
+  runtimeServiceIds = []
+} = {}) {
+  return Object.freeze({
+    repositoryDefinitions,
+    serviceDefinitions,
+    controllerDefinitions,
+    runtimeServiceIds
+  });
+}
+
+function createServerRuntime({ bundles = [], dependencies = {} } = {}) {
+  return createRuntimeAssembly({
+    bundles,
+    dependencies
+  });
+}
+
+function createServerRuntimeWithPlatformBundle({
+  platformBundle,
+  appFeatureBundle,
+  dependencies = {}
+} = {}) {
+  if (!platformBundle || typeof platformBundle !== "object") {
+    throw new Error("platformBundle is required.");
+  }
+
+  const bundles = appFeatureBundle ? [platformBundle, appFeatureBundle] : [platformBundle];
+  return createServerRuntime({
+    bundles,
+    dependencies
+  });
+}
+
+export { createPlatformRuntimeBundle, createServerRuntime, createServerRuntimeWithPlatformBundle };

package/server/platform/surfaceRuntime.js

@@ -0,0 +1,150 @@
+import { createProviderRuntimeFromApp } from "./providerRuntime.js";
+import { matchesPathPrefix, normalizePathname } from "../../shared/surface/paths.js";
+
+function toRequestPathname(urlValue) {
+  const rawUrl = String(urlValue || "").trim() || "/";
+  try {
+    return normalizePathname(new URL(rawUrl, "http://localhost").pathname || "/");
+  } catch {
+    const [pathname] = rawUrl.split("?");
+    return normalizePathname(pathname || "/");
+  }
+}
+
+function matchesGlobalUiPath(pathname, globalUiPaths = []) {
+  const normalizedPathname = normalizePathname(pathname);
+  const normalizedGlobalUiPaths = [...new Set((Array.isArray(globalUiPaths) ? globalUiPaths : []).map(normalizePathname))]
+    .filter(Boolean)
+    .sort((left, right) => right.length - left.length);
+
+  for (const globalUiPath of normalizedGlobalUiPaths) {
+    if (matchesPathPrefix(normalizedPathname, globalUiPath)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function shouldServePathForSurface({
+  surfaceRuntime,
+  pathname,
+  serverSurface,
+  apiPathPrefix = "/api/",
+  globalUiPaths = []
+} = {}) {
+  if (!surfaceRuntime || typeof surfaceRuntime.normalizeSurfaceMode !== "function") {
+    throw new TypeError("shouldServePathForSurface requires surfaceRuntime.normalizeSurfaceMode().");
+  }
+  if (typeof surfaceRuntime.resolveSurfaceFromPathname !== "function") {
+    throw new TypeError("shouldServePathForSurface requires surfaceRuntime.resolveSurfaceFromPathname().");
+  }
+  if (typeof surfaceRuntime.isSurfaceEnabled !== "function") {
+    throw new TypeError("shouldServePathForSurface requires surfaceRuntime.isSurfaceEnabled().");
+  }
+
+  const normalizedSurface = surfaceRuntime.normalizeSurfaceMode(serverSurface);
+  const allMode = String(surfaceRuntime.SURFACE_MODE_ALL || "all").trim().toLowerCase() || "all";
+  const normalizedPathname = String(pathname || "").trim() || "/";
+  const normalizedApiPrefix = String(apiPathPrefix || "/api/").trim() || "/api/";
+
+  if (normalizedPathname.startsWith(normalizedApiPrefix)) {
+    return true;
+  }
+
+  if (matchesGlobalUiPath(normalizedPathname, globalUiPaths)) {
+    return true;
+  }
+
+  const routeSurface = surfaceRuntime.resolveSurfaceFromPathname(normalizedPathname);
+  if (!surfaceRuntime.isSurfaceEnabled(routeSurface)) {
+    return false;
+  }
+
+  if (normalizedSurface === allMode) {
+    return true;
+  }
+
+  return routeSurface === normalizedSurface;
+}
+
+function registerSurfaceRequestConstraint({
+  fastify,
+  surfaceRuntime,
+  serverSurface,
+  apiPathPrefix = "/api/",
+  globalUiPaths = []
+} = {}) {
+  if (!fastify || typeof fastify.addHook !== "function") {
+    throw new TypeError("registerSurfaceRequestConstraint requires fastify.addHook().");
+  }
+
+  const normalizedSurface = surfaceRuntime.normalizeSurfaceMode(serverSurface);
+  fastify.addHook("onRequest", async (request, reply) => {
+    const pathname = toRequestPathname(request?.url);
+    if (
+      shouldServePathForSurface({
+        surfaceRuntime,
+        pathname,
+        serverSurface: normalizedSurface,
+        apiPathPrefix,
+        globalUiPaths
+      })
+    ) {
+      return;
+    }
+
+    reply.code(404).type("application/json").send({
+      ok: false,
+      error: `Path ${pathname} is not served by ${normalizedSurface} surface server.`
+    });
+  });
+}
+
+function resolveRuntimeProfileFromSurface({
+  surfaceRuntime,
+  serverSurface,
+  defaultProfile = ""
+} = {}) {
+  if (!surfaceRuntime || typeof surfaceRuntime.normalizeSurfaceMode !== "function") {
+    throw new TypeError("resolveRuntimeProfileFromSurface requires surfaceRuntime.normalizeSurfaceMode().");
+  }
+
+  const normalizedSurface = surfaceRuntime.normalizeSurfaceMode(serverSurface);
+  const allMode = String(surfaceRuntime.SURFACE_MODE_ALL || "all").trim().toLowerCase() || "all";
+  if (normalizedSurface !== allMode) {
+    return normalizedSurface;
+  }
+
+  const normalizedDefaultProfile = surfaceRuntime.normalizeSurfaceMode(defaultProfile);
+  if (normalizedDefaultProfile && normalizedDefaultProfile !== allMode) {
+    return normalizedDefaultProfile;
+  }
+
+  const normalizedRuntimeDefaultSurface = surfaceRuntime.normalizeSurfaceMode(surfaceRuntime.DEFAULT_SURFACE_ID);
+  if (normalizedRuntimeDefaultSurface && normalizedRuntimeDefaultSurface !== allMode) {
+    return normalizedRuntimeDefaultSurface;
+  }
+
+  return "";
+}
+
+async function tryCreateProviderRuntimeFromApp(options = {}) {
+  try {
+    return await createProviderRuntimeFromApp(options);
+  } catch (error) {
+    const message = String(error?.message || "");
+    if (message.includes("Lock file not found:")) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+export {
+  toRequestPathname,
+  shouldServePathForSurface,
+  registerSurfaceRequestConstraint,
+  resolveRuntimeProfileFromSurface,
+  tryCreateProviderRuntimeFromApp
+};

package/server/platform/surfaceRuntime.test.js

@@ -0,0 +1,136 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  resolveRuntimeProfileFromSurface,
+  shouldServePathForSurface,
+  toRequestPathname
+} from "./surfaceRuntime.js";
+
+function createFakeSurfaceRuntime() {
+  return {
+    SURFACE_MODE_ALL: "all",
+    normalizeSurfaceMode(value) {
+      const normalized = String(value || "")
+        .trim()
+        .toLowerCase();
+      if (!normalized || normalized === "all") {
+        return "all";
+      }
+      return ["app", "admin", "console"].includes(normalized) ? normalized : "all";
+    },
+    resolveSurfaceFromPathname(pathname) {
+      const normalized = String(pathname || "").trim();
+      if (normalized === "/admin" || normalized.startsWith("/admin/")) {
+        return "admin";
+      }
+      if (normalized === "/console" || normalized.startsWith("/console/")) {
+        return "console";
+      }
+      return "app";
+    },
+    isSurfaceEnabled(surfaceId) {
+      return ["app", "admin"].includes(surfaceId);
+    }
+  };
+}
+
+test("toRequestPathname strips query and survives invalid url", () => {
+  assert.equal(toRequestPathname("/admin/users?id=1"), "/admin/users");
+  assert.equal(toRequestPathname("///bad path"), "/bad path");
+});
+
+test("shouldServePathForSurface allows api and matching enabled surfaces", () => {
+  const surfaceRuntime = createFakeSurfaceRuntime();
+  assert.equal(
+    shouldServePathForSurface({
+      surfaceRuntime,
+      pathname: "/api/health",
+      serverSurface: "admin"
+    }),
+    true
+  );
+  assert.equal(
+    shouldServePathForSurface({
+      surfaceRuntime,
+      pathname: "/admin/users",
+      serverSurface: "admin"
+    }),
+    true
+  );
+  assert.equal(
+    shouldServePathForSurface({
+      surfaceRuntime,
+      pathname: "/console",
+      serverSurface: "all"
+    }),
+    false
+  );
+});
+
+test("shouldServePathForSurface allows descriptor-declared global ui paths", () => {
+  const surfaceRuntime = createFakeSurfaceRuntime();
+  assert.equal(
+    shouldServePathForSurface({
+      surfaceRuntime,
+      pathname: "/auth/login",
+      serverSurface: "admin",
+      globalUiPaths: ["/auth/login", "/auth/signout"]
+    }),
+    true
+  );
+  assert.equal(
+    shouldServePathForSurface({
+      surfaceRuntime,
+      pathname: "/auth/signout/complete",
+      serverSurface: "admin",
+      globalUiPaths: ["/auth/login", "/auth/signout"]
+    }),
+    true
+  );
+});
+
+test("resolveRuntimeProfileFromSurface maps all mode to default profile", () => {
+  const surfaceRuntime = createFakeSurfaceRuntime();
+  assert.equal(
+    resolveRuntimeProfileFromSurface({
+      surfaceRuntime,
+      serverSurface: "all",
+      defaultProfile: "app"
+    }),
+    "app"
+  );
+  assert.equal(
+    resolveRuntimeProfileFromSurface({
+      surfaceRuntime,
+      serverSurface: "admin",
+      defaultProfile: "app"
+    }),
+    "admin"
+  );
+});
+
+test("resolveRuntimeProfileFromSurface uses runtime default surface when default profile is not configured", () => {
+  const surfaceRuntime = {
+    SURFACE_MODE_ALL: "all",
+    DEFAULT_SURFACE_ID: "home",
+    normalizeSurfaceMode(value) {
+      const normalized = String(value || "")
+        .trim()
+        .toLowerCase();
+      if (!normalized || normalized === "all") {
+        return "all";
+      }
+      return ["home", "admin"].includes(normalized) ? normalized : "all";
+    }
+  };
+
+  assert.equal(
+    resolveRuntimeProfileFromSurface({
+      surfaceRuntime,
+      serverSurface: "all",
+      defaultProfile: "app"
+    }),
+    "home"
+  );
+});