@jskit-ai/kernel 0.1.159 → 0.1.161

package/server/platform/providerRuntime.js

@@ -1,146 +0,0 @@
-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 {
-  collectGlobalUiPaths,
-  resolveInstalledJskitPackages,
-  resolvePackageLoadOrder,
-  validatePackageCapabilities
-} from "./providerRuntime/packageCatalog.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("jskit.env", env && typeof env === "object" ? { ...env } : {});
-  app.instance("jskit.logger", logger || console);
-
-  let httpRuntime = null;
-  if (fastify && typeof fastify.route === "function") {
-    httpRuntime = createHttpRuntime({
-      app,
-      fastify
-    });
-  }
-
-  await app.start({ providers });
-
-  if (fastify && typeof fastify.addHook === "function") {
-    let didShutdown = false;
-    fastify.addHook("onClose", async () => {
-      if (didShutdown) {
-        return;
-      }
-
-      didShutdown = true;
-      await app.shutdown();
-    });
-  }
-
-  const routeRegistration = httpRuntime ? httpRuntime.registerRoutes() : { routeCount: 0 };
-  return Object.freeze({
-    app,
-    routeCount: routeRegistration.routeCount,
-    routeRegistration,
-    diagnostics: app.getDiagnostics()
-  });
-}
-
-async function createProviderRuntimeFromApp({
-  appRoot,
-  profile = "",
-  env = {},
-  logger = console,
-  fastify = null
-} = {}) {
-  if (!appRoot || typeof appRoot !== "string") {
-    throw new TypeError("createProviderRuntimeFromApp requires appRoot.");
-  }
-
-  const installedPackages = await resolveInstalledJskitPackages({
-    appRoot
-  });
-  validatePackageCapabilities(installedPackages, {
-    builtinProvidersByCapability: KERNEL_BUILTIN_CAPABILITY_PROVIDERS
-  });
-  const orderedPackages = resolvePackageLoadOrder(installedPackages);
-  const catalog = Object.freeze({
-    packageOrder: Object.freeze(orderedPackages.map((entry) => entry.packageId)),
-    globalUiPaths: collectGlobalUiPaths(orderedPackages),
-    packages: Object.freeze(orderedPackages)
-  });
-
-  const orderedProviderClasses = [];
-  const providerPackageIds = [];
-  const seenProviderIds = new Map();
-
-  for (const packageEntry of catalog.packages) {
-    const packageProviders = await loadPackageProviders({ packageEntry });
-    if (packageProviders.length < 1) {
-      continue;
-    }
-    providerPackageIds.push(packageEntry.packageId);
-
-    for (const providerClass of packageProviders) {
-      registerProviderClass({
-        providerClass,
-        sourceId: packageEntry.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

@@ -1,214 +0,0 @@
-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 writeFile(
-    path.join(appRoot, "package.json"),
-    `${JSON.stringify({ name: "fixture-app", private: true, type: "module" }, null, 2)}\n`,
-    "utf8"
-  );
-  return appRoot;
-}
-
-async function declareLocalPackage(appRoot, packageId, packagePath, jskit = {}) {
-  await writeFile(
-    path.join(appRoot, "package.json"),
-    `${JSON.stringify({
-      name: "fixture-app",
-      private: true,
-      type: "module",
-      dependencies: {
-        [packageId]: `file:${packagePath}`
-      }
-    }, null, 2)}\n`,
-    "utf8"
-  );
-  const packageRoot = path.join(appRoot, packagePath);
-  await mkdir(packageRoot, { recursive: true });
-  await writeFile(
-    path.join(packageRoot, "package.json"),
-    `${JSON.stringify({
-      name: packageId,
-      version: "0.1.0",
-      description: "Local example package",
-      type: "module",
-      jskit
-    }, null, 2)}\n`,
-    "utf8"
-  );
-}
-
-test("createProviderRuntimeFromApp discovers package providers from package metadata", async () => {
-  const appRoot = await createTestAppRoot("kernel-provider-runtime-discover-");
-  try {
-    await mkdir(path.join(appRoot, "packages", "local-example", "src", "server", "providers"), { recursive: true });
-    await declareLocalPackage(appRoot, "@local/example", "packages/local-example", {
-      capabilities: { provides: [], requires: [] },
-      runtime: {
-        server: {
-          providers: [
-            { discover: { dir: "src/server/providers", pattern: "*Provider.js" } }
-          ]
-        }
-      }
-    });
-    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 app-local src/server/providers folder", async () => {
-  const appRoot = await createTestAppRoot("kernel-provider-runtime-app-local-");
-  try {
-    await mkdir(path.join(appRoot, "src", "server", "providers"), { recursive: true });
-    await writeFile(
-      path.join(appRoot, "src", "server", "providers", "IgnoredProvider.js"),
-      [
-        "export default class IgnoredProvider {",
-        "  static id = \"ignored.app.local\";",
-        "  register(app) {",
-        "    app.instance(\"ignored.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("ignored.value"), false);
-  } finally {
-    await rm(appRoot, { recursive: true, force: true });
-  }
-});
-
-test("createProviderRuntimeFromApp resolves package metadata from a file dependency", async () => {
-  const appRoot = await createTestAppRoot("kernel-provider-runtime-local-package-");
-  try {
-    await mkdir(path.join(appRoot, "packages", "local-example"), { recursive: true });
-    await declareLocalPackage(appRoot, "@local/example", "packages/local-example", {
-      capabilities: { provides: [], requires: [] },
-      runtime: { server: { providers: [] } }
-    });
-
-    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 });
-  }
-});
-
-test("createProviderRuntimeFromApp wires fastify onClose to provider shutdown exactly once", async () => {
-  const appRoot = await createTestAppRoot("kernel-provider-runtime-fastify-close-");
-  try {
-    await mkdir(path.join(appRoot, "packages", "local-example", "src", "server", "providers"), { recursive: true });
-    await declareLocalPackage(appRoot, "@local/example", "packages/local-example", {
-      capabilities: { provides: [], requires: [] },
-      runtime: {
-        server: {
-          providers: [
-            { discover: { dir: "src/server/providers", pattern: "*Provider.js" } }
-          ]
-        }
-      }
-    });
-    await writeFile(
-      path.join(appRoot, "packages", "local-example", "src", "server", "providers", "CloseAwareProvider.js"),
-      [
-        "export default class CloseAwareProvider {",
-        "  static id = \"example.close-aware\";",
-        "  register(app) {",
-        "    app.instance(\"example.close.state\", { shutdownCalls: 0 });",
-        "  }",
-        "  async boot() {}",
-        "  async shutdown(app) {",
-        "    app.make(\"example.close.state\").shutdownCalls += 1;",
-        "  }",
-        "}"
-      ].join("\n"),
-      "utf8"
-    );
-
-    const hooks = [];
-    const fastify = {
-      route() {},
-      setErrorHandler() {},
-      addContentTypeParser() {},
-      hasContentTypeParser() {
-        return false;
-      },
-      getDefaultJsonParser() {
-        return (_request, body, done) => done(null, body);
-      },
-      addHook(name, handler) {
-        hooks.push({ name, handler });
-      }
-    };
-
-    const runtime = await createProviderRuntimeFromApp({
-      appRoot,
-      profile: "app",
-      fastify
-    });
-
-    const closeHook = hooks.find((entry) => entry.name === "onClose");
-    assert.ok(closeHook);
-    assert.equal(runtime.app.make("example.close.state").shutdownCalls, 0);
-
-    await closeHook.handler();
-    await closeHook.handler();
-
-    assert.equal(runtime.app.make("example.close.state").shutdownCalls, 1);
-  } finally {
-    await rm(appRoot, { recursive: true, force: true });
-  }
-});

package/server/platform/runtime.js

@@ -1,40 +0,0 @@
-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/registries/actionSurfaceSourceRegistry.js

@@ -1,148 +0,0 @@
-import { assertTaggableApp } from "./primitives.js";
-
-const ACTION_SURFACE_SOURCE_NAME_PATTERN = /^[a-z][a-z0-9_.-]*$/;
-
-function normalizeSurfaceIdValue(value) {
-  return String(value || "").trim().toLowerCase();
-}
-
-function normalizeSurfaceSourceName(sourceName, { context = "action surface source" } = {}) {
-  const normalizedSourceName = normalizeSurfaceIdValue(sourceName);
-  if (!ACTION_SURFACE_SOURCE_NAME_PATTERN.test(normalizedSourceName)) {
-    throw new Error(`${context} must match ${ACTION_SURFACE_SOURCE_NAME_PATTERN.toString()}.`);
-  }
-
-  return normalizedSourceName;
-}
-
-function resolveSurfaceRuntime(scope) {
-  if (!scope || typeof scope.has !== "function" || typeof scope.make !== "function") {
-    throw new Error("Action definition materialization requires scope.has()/make().");
-  }
-
-  if (!scope.has("jskit.surface.runtime")) {
-    throw new Error("Action definition surfacesFrom requires jskit.surface.runtime.");
-  }
-
-  return scope.make("jskit.surface.runtime");
-}
-
-function resolveEnabledSurfaceIds(surfaceRuntime) {
-  return Array.isArray(surfaceRuntime?.listEnabledSurfaceIds?.()) ? surfaceRuntime.listEnabledSurfaceIds() : [];
-}
-
-function normalizeSurfaceIdList(surfaceIds, { context = "action.surfacesFrom", surfaceRuntime = null } = {}) {
-  const sourceSurfaceIds = Array.isArray(surfaceIds) ? surfaceIds : [];
-  const enabledSurfaceIds = new Set(
-    resolveEnabledSurfaceIds(surfaceRuntime).map((entry) => normalizeSurfaceIdValue(entry)).filter(Boolean)
-  );
-  const seen = new Set();
-  const normalized = [];
-
-  for (const sourceSurfaceId of sourceSurfaceIds) {
-    const normalizedSurfaceId = normalizeSurfaceIdValue(sourceSurfaceId);
-    if (!normalizedSurfaceId || seen.has(normalizedSurfaceId)) {
-      continue;
-    }
-
-    if (!enabledSurfaceIds.has(normalizedSurfaceId)) {
-      throw new Error(`${context} resolved non-enabled surface "${normalizedSurfaceId}".`);
-    }
-
-    seen.add(normalizedSurfaceId);
-    normalized.push(normalizedSurfaceId);
-  }
-
-  return Object.freeze(normalized);
-}
-
-function createActionSurfaceSourceRegistry() {
-  const sourceResolvers = new Map();
-
-  const register = (sourceName, resolver, { allowOverride = false } = {}) => {
-    const normalizedSourceName = normalizeSurfaceSourceName(sourceName);
-    if (typeof resolver !== "function") {
-      throw new Error(`action surface source "${normalizedSourceName}" resolver must be a function.`);
-    }
-    if (!allowOverride && sourceResolvers.has(normalizedSourceName)) {
-      throw new Error(`action surface source "${normalizedSourceName}" is already registered.`);
-    }
-    sourceResolvers.set(normalizedSourceName, resolver);
-  };
-
-  register("enabled", ({ surfaceRuntime }) => resolveEnabledSurfaceIds(surfaceRuntime));
-
-  return Object.freeze({
-    register,
-    resolve(scope, sourceName, { context = "action.surfacesFrom" } = {}) {
-      const normalizedSourceName = normalizeSurfaceSourceName(sourceName, { context });
-      const resolver = sourceResolvers.get(normalizedSourceName);
-      if (typeof resolver !== "function") {
-        throw new Error(
-          `${context} references unknown surface source "${normalizedSourceName}". Register it via app.actionSurfaceSource().`
-        );
-      }
-
-      const surfaceRuntime = resolveSurfaceRuntime(scope);
-      const resolvedSurfaceIds = resolver({
-        scope,
-        sourceName: normalizedSourceName,
-        surfaceRuntime
-      });
-
-      return normalizeSurfaceIdList(resolvedSurfaceIds, {
-        context,
-        surfaceRuntime
-      });
-    }
-  });
-}
-
-function resolveActionSurfaceSourceRegistry(scope) {
-  if (!scope || typeof scope.has !== "function" || typeof scope.make !== "function") {
-    throw new Error("Action surface source resolution requires scope.has()/make().");
-  }
-  if (!scope.has("jskit.runtime.actions.surfaceSourceRegistry")) {
-    throw new Error("Action surface source registry is not registered.");
-  }
-  return scope.make("jskit.runtime.actions.surfaceSourceRegistry");
-}
-
-function resolveActionSurfaceSourceIds(scope, sourceName, { context = "action.surfacesFrom" } = {}) {
-  const sourceRegistry = resolveActionSurfaceSourceRegistry(scope);
-  return sourceRegistry.resolve(scope, sourceName, { context });
-}
-
-function installActionSurfaceSourceRegistrationApi(app) {
-  if (typeof app.actionSurfaceSource === "function") {
-    return;
-  }
-
-  const registerActionSurfaceSource = function registerActionSurfaceSource(sourceName, resolver) {
-    const sourceRegistry = resolveActionSurfaceSourceRegistry(this);
-    sourceRegistry.register(sourceName, resolver);
-    return this;
-  };
-
-  Object.defineProperty(app, "actionSurfaceSource", {
-    configurable: true,
-    writable: true,
-    value: registerActionSurfaceSource
-  });
-}
-
-function ensureActionSurfaceSourceRegistry(app) {
-  assertTaggableApp(app, {
-    context: "ensureActionSurfaceSourceRegistry"
-  });
-  if (typeof app.has !== "function") {
-    throw new Error("ensureActionSurfaceSourceRegistry requires app.has().");
-  }
-
-  if (!app.has("jskit.runtime.actions.surfaceSourceRegistry")) {
-    app.singleton("jskit.runtime.actions.surfaceSourceRegistry", () => createActionSurfaceSourceRegistry());
-  }
-  installActionSurfaceSourceRegistrationApi(app);
-}
-
-export { ensureActionSurfaceSourceRegistry, resolveActionSurfaceSourceIds };

package/server/registries/bootstrapPayloadContributorRegistry.js

@@ -1,51 +0,0 @@
-import { normalizeObject } from "../../shared/support/normalize.js";
-import { normalizeContributorEntry, registerTaggedSingleton, resolveTaggedEntries } from "./primitives.js";
-
-function registerBootstrapPayloadContributor(app, token, factory) {
-  registerTaggedSingleton(app, token, factory, "jskit.runtime.bootstrap.payloadContributors", {
-    context: "registerBootstrapPayloadContributor"
-  });
-}
-
-function resolveBootstrapPayloadContributors(scope) {
-  return resolveTaggedEntries(scope, "jskit.runtime.bootstrap.payloadContributors")
-    .map((entry, index) => ({
-      contributor: normalizeContributorEntry(entry),
-      index
-    }))
-    .filter((entry) => Boolean(entry.contributor))
-    .sort((left, right) => {
-      const leftOrder = Number.isFinite(left.contributor?.order) ? Number(left.contributor.order) : 0;
-      const rightOrder = Number.isFinite(right.contributor?.order) ? Number(right.contributor.order) : 0;
-      if (leftOrder !== rightOrder) {
-        return leftOrder - rightOrder;
-      }
-
-      return left.index - right.index;
-    })
-    .map((entry) => entry.contributor);
-}
-
-async function resolveBootstrapPayload(scope, context = {}) {
-  const contributors = resolveBootstrapPayloadContributors(scope);
-  let payload = {};
-
-  for (const contributor of contributors) {
-    const contribution = await contributor.contribute({
-      ...normalizeObject(context),
-      payload: Object.freeze({ ...payload })
-    });
-    payload = {
-      ...payload,
-      ...normalizeObject(contribution)
-    };
-  }
-
-  return payload;
-}
-
-export {
-  registerBootstrapPayloadContributor,
-  resolveBootstrapPayloadContributors,
-  resolveBootstrapPayload
-};

package/server/registries/domainEventListenerRegistry.js

@@ -1,58 +0,0 @@
-import { normalizeObject } from "../../shared/support/normalize.js";
-import { registerTaggedSingleton, resolveTaggedEntries } from "./primitives.js";
-
-function normalizeDomainEventListener(entry) {
-  if (typeof entry === "function") {
-    return {
-      listenerId: String(entry.name || "anonymous"),
-      matches: null,
-      handle: entry
-    };
-  }
-
-  if (entry && typeof entry === "object" && typeof entry.handle === "function") {
-    return {
-      ...entry,
-      listenerId: String(entry.listenerId || "anonymous"),
-      matches: typeof entry.matches === "function" ? entry.matches : null
-    };
-  }
-
-  return null;
-}
-
-function registerDomainEventListener(app, token, factory) {
-  registerTaggedSingleton(app, token, factory, "jskit.runtime.domainEvent.listeners", {
-    context: "registerDomainEventListener"
-  });
-}
-
-function resolveDomainEventListeners(scope) {
-  return resolveTaggedEntries(scope, "jskit.runtime.domainEvent.listeners")
-    .map((entry) => normalizeDomainEventListener(entry))
-    .filter(Boolean);
-}
-
-function createDomainEvents(scope) {
-  return Object.freeze({
-    async publish(event = {}) {
-      const payload = normalizeObject(event);
-      const listeners = resolveDomainEventListeners(scope);
-
-      for (const listener of listeners) {
-        if (listener.matches && listener.matches(payload) !== true) {
-          continue;
-        }
-        await listener.handle(payload);
-      }
-
-      return null;
-    }
-  });
-}
-
-export {
-  registerDomainEventListener,
-  resolveDomainEventListeners,
-  createDomainEvents
-};

package/server/registries/index.js

@@ -1,32 +0,0 @@
-export {
-  registerBootstrapPayloadContributor,
-  resolveBootstrapPayloadContributors,
-  resolveBootstrapPayload
-} from "./bootstrapPayloadContributorRegistry.js";
-export {
-  registerDomainEventListener,
-  resolveDomainEventListeners,
-  createDomainEvents
-} from "./domainEventListenerRegistry.js";
-export {
-  normalizeServiceRegistration,
-  materializeServiceRegistration,
-  registerServiceRegistration,
-  resolveServiceRegistrations,
-  installServiceRegistrationApi
-} from "./serviceRegistrationRegistry.js";
-export {
-  resolveRouteVisibilityResolvers,
-  registerRouteVisibilityResolver,
-  resolveRouteVisibilityContext
-} from "./routeVisibilityResolverRegistry.js";
-export {
-  ensureActionSurfaceSourceRegistry,
-  resolveActionSurfaceSourceIds
-} from "./actionSurfaceSourceRegistry.js";
-export {
-  normalizeNestedEntries,
-  assertTaggableApp,
-  registerTaggedSingleton,
-  resolveTaggedEntries
-} from "./primitives.js";