@jskit-ai/kernel 0.1.4

package/server/platform/PlatformServerRuntimeServiceProvider.js

@@ -0,0 +1,30 @@
+import { createProviderRuntimeApp, createProviderRuntimeFromApp } from "./providerRuntime.js";
+import {
+  createPlatformRuntimeBundle,
+  createServerRuntime,
+  createServerRuntimeWithPlatformBundle
+} from "./runtime.js";
+
+const PLATFORM_SERVER_RUNTIME_API = Object.freeze({
+  createPlatformRuntimeBundle,
+  createServerRuntime,
+  createServerRuntimeWithPlatformBundle,
+  createProviderRuntimeApp,
+  createProviderRuntimeFromApp
+});
+
+class PlatformServerRuntimeServiceProvider {
+  static id = "runtime.platform-server";
+
+  register(app) {
+    if (!app || typeof app.singleton !== "function") {
+      throw new Error("PlatformServerRuntimeServiceProvider requires application singleton().");
+    }
+
+    app.singleton("runtime.platform-server", () => PLATFORM_SERVER_RUNTIME_API);
+  }
+
+  boot() {}
+}
+
+export { PlatformServerRuntimeServiceProvider };

package/server/platform/index.js

@@ -0,0 +1,5 @@
+export {
+  registerSurfaceRequestConstraint,
+  resolveRuntimeProfileFromSurface,
+  tryCreateProviderRuntimeFromApp
+} from "./surfaceRuntime.js";

package/server/platform/providerRuntime/descriptorCatalog.js

@@ -0,0 +1,170 @@
+import path from "node:path";
+import { sortStrings } from "../../../shared/support/sorting.js";
+import { loadInstalledPackageDescriptor } from "../../../internal/node/installedPackageDescriptor.js";
+
+function normalizeUiRoutePath(pathValue) {
+  const rawPath = String(pathValue || "").trim();
+  if (!rawPath || !rawPath.startsWith("/") || rawPath.startsWith("//")) {
+    return "";
+  }
+
+  const normalizedPath = rawPath.replace(/\/{2,}/g, "/");
+  if (normalizedPath === "/") {
+    return "/";
+  }
+
+  return normalizedPath.replace(/\/+$/, "") || "/";
+}
+
+function collectGlobalUiPaths(descriptorEntries) {
+  const globalUiPaths = [];
+  const entries = Array.isArray(descriptorEntries) ? descriptorEntries : [];
+
+  for (const descriptorEntry of entries) {
+    const uiRoutes = Array.isArray(descriptorEntry?.descriptor?.metadata?.ui?.routes)
+      ? descriptorEntry.descriptor.metadata.ui.routes
+      : [];
+
+    for (const routeEntry of uiRoutes) {
+      const routeRecord = routeEntry && typeof routeEntry === "object" && !Array.isArray(routeEntry) ? routeEntry : null;
+      if (!routeRecord) {
+        continue;
+      }
+
+      const scope = String(routeRecord.scope || "")
+        .trim()
+        .toLowerCase();
+      if (scope !== "global") {
+        continue;
+      }
+
+      const routePath = normalizeUiRoutePath(routeRecord.path);
+      if (!routePath) {
+        continue;
+      }
+      globalUiPaths.push(routePath);
+    }
+  }
+
+  return Object.freeze(sortStrings(globalUiPaths));
+}
+
+async function resolveInstalledPackageDescriptors({ appRoot, lock }) {
+  const installedPackages =
+    lock && typeof lock === "object" && lock.installedPackages && typeof lock.installedPackages === "object"
+      ? lock.installedPackages
+      : {};
+
+  const descriptorEntries = [];
+  for (const packageId of sortStrings(Object.keys(installedPackages))) {
+    const installedPackageState = installedPackages[packageId] || {};
+    const descriptorRecord = await loadInstalledPackageDescriptor({
+      appRoot,
+      installedPackageState,
+      packageId,
+      required: true
+    });
+    descriptorEntries.push({
+      packageId,
+      descriptor: descriptorRecord.descriptor,
+      descriptorPath: descriptorRecord.descriptorPath,
+      packageRoot: path.dirname(descriptorRecord.descriptorPath)
+    });
+  }
+
+  return descriptorEntries;
+}
+
+function resolveDescriptorLoadOrder(descriptorEntries) {
+  const byPackageId = new Map(descriptorEntries.map((entry) => [entry.packageId, entry]));
+  const visiting = new Set();
+  const visited = new Set();
+  const ordered = [];
+
+  function visit(packageId, lineage = []) {
+    if (visited.has(packageId)) {
+      return;
+    }
+    if (visiting.has(packageId)) {
+      throw new Error(`Package dependency cycle detected: ${[...lineage, packageId].join(" -> ")}`);
+    }
+
+    const entry = byPackageId.get(packageId);
+    if (!entry) {
+      return;
+    }
+
+    visiting.add(packageId);
+    const dependsOn = Array.isArray(entry.descriptor?.dependsOn) ? entry.descriptor.dependsOn : [];
+    for (const dependencyPackageId of dependsOn) {
+      if (byPackageId.has(dependencyPackageId)) {
+        visit(dependencyPackageId, [...lineage, packageId]);
+      }
+    }
+    visiting.delete(packageId);
+    visited.add(packageId);
+    ordered.push(entry);
+  }
+
+  for (const packageId of sortStrings([...byPackageId.keys()])) {
+    visit(packageId);
+  }
+
+  return ordered;
+}
+
+function registerCapabilityProvider(providersByCapability, capabilityId, providerPackageId) {
+  const normalizedCapabilityId = String(capabilityId || "").trim();
+  const normalizedProviderPackageId = String(providerPackageId || "").trim();
+  if (!normalizedCapabilityId || !normalizedProviderPackageId) {
+    return;
+  }
+
+  if (!providersByCapability.has(normalizedCapabilityId)) {
+    providersByCapability.set(normalizedCapabilityId, new Set());
+  }
+  providersByCapability.get(normalizedCapabilityId).add(normalizedProviderPackageId);
+}
+
+function validateDescriptorCapabilities(descriptorEntries, { builtinProvidersByCapability = {} } = {}) {
+  const providersByCapability = new Map();
+  for (const descriptorEntry of descriptorEntries) {
+    for (const capabilityId of Array.isArray(descriptorEntry.descriptor?.capabilities?.provides)
+      ? descriptorEntry.descriptor.capabilities.provides
+      : []) {
+      registerCapabilityProvider(providersByCapability, capabilityId, descriptorEntry.packageId);
+    }
+  }
+
+  for (const [capabilityId, providerPackageIds] of Object.entries(
+    builtinProvidersByCapability && typeof builtinProvidersByCapability === "object" ? builtinProvidersByCapability : {}
+  )) {
+    for (const providerPackageId of Array.isArray(providerPackageIds) ? providerPackageIds : [providerPackageIds]) {
+      registerCapabilityProvider(providersByCapability, capabilityId, providerPackageId);
+    }
+  }
+
+  for (const descriptorEntry of descriptorEntries) {
+    for (const capabilityId of Array.isArray(descriptorEntry.descriptor?.capabilities?.requires)
+      ? descriptorEntry.descriptor.capabilities.requires
+      : []) {
+      const normalizedCapabilityId = String(capabilityId || "").trim();
+      if (!normalizedCapabilityId) {
+        continue;
+      }
+      const providers = providersByCapability.get(normalizedCapabilityId);
+      if (!providers || providers.size < 1) {
+        throw new Error(
+          `Package ${descriptorEntry.packageId} requires capability ${normalizedCapabilityId}, but no installed package provides it.`
+        );
+      }
+    }
+  }
+}
+
+export {
+  collectGlobalUiPaths,
+  resolveInstalledPackageDescriptors,
+  resolveDescriptorLoadOrder,
+  validateDescriptorCapabilities
+};

package/server/platform/providerRuntime/helpers.js

@@ -0,0 +1,45 @@
+import path from "node:path";
+import { escapeRegExp } from "../../../shared/surface/escapeRegExp.js";
+import { fileExists } from "../../../internal/node/fileSystem.js";
+
+function isIdentifier(value) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(String(value || ""));
+}
+
+function createWildcardMatcher(pattern) {
+  const rawPattern = String(pattern || "").trim();
+  if (!rawPattern) {
+    return null;
+  }
+
+  const escapedPattern = escapeRegExp(rawPattern).replace(/\\\*/g, ".*");
+  return new RegExp(`^${escapedPattern}$`);
+}
+
+function normalizeRelativePath(fromPath, targetPath) {
+  const relative = path.relative(path.resolve(fromPath), path.resolve(targetPath));
+  return relative.split(path.sep).join("/");
+}
+
+function isInsidePackageRoot(packageRoot, candidatePath) {
+  const relative = path.relative(path.resolve(packageRoot), path.resolve(candidatePath));
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function toAbsoluteSortedUniquePaths(values) {
+  const source = Array.isArray(values) ? values : [];
+  return Object.freeze(
+    [...new Set(source.map((entry) => path.resolve(entry)).filter(Boolean))].sort((left, right) =>
+      left.localeCompare(right)
+    )
+  );
+}
+
+export {
+  isIdentifier,
+  createWildcardMatcher,
+  normalizeRelativePath,
+  fileExists,
+  isInsidePackageRoot,
+  toAbsoluteSortedUniquePaths
+};

package/server/platform/providerRuntime/lockfile.js

@@ -0,0 +1,27 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { fileExists } from "../../../internal/node/fileSystem.js";
+
+async function readLockFromApp({ appRoot, lockPath = ".jskit/lock.json" } = {}) {
+  if (!appRoot || typeof appRoot !== "string") {
+    throw new TypeError("readLockFromApp requires appRoot.");
+  }
+
+  const absoluteLockPath = path.resolve(appRoot, String(lockPath || ".jskit/lock.json"));
+  if (!(await fileExists(absoluteLockPath))) {
+    throw new Error(`Lock file not found: ${absoluteLockPath}`);
+  }
+
+  const source = await readFile(absoluteLockPath, "utf8");
+  const lock = JSON.parse(source);
+  if (!lock || typeof lock !== "object") {
+    throw new TypeError(`Invalid lock file payload at ${absoluteLockPath}.`);
+  }
+
+  return {
+    lock,
+    lockPath: absoluteLockPath
+  };
+}
+
+export { readLockFromApp };

package/server/platform/providerRuntime/providerLoader.js

@@ -0,0 +1,283 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  isIdentifier,
+  createWildcardMatcher,
+  normalizeRelativePath,
+  fileExists,
+  isInsidePackageRoot,
+  toAbsoluteSortedUniquePaths
+} from "./helpers.js";
+
+function normalizeServerProviderDefinitions(descriptor, packageId) {
+  const runtime =
+    descriptor && typeof descriptor.runtime === "object" && descriptor.runtime && !Array.isArray(descriptor.runtime)
+      ? descriptor.runtime
+      : {};
+  const server =
+    runtime && typeof runtime.server === "object" && runtime.server && !Array.isArray(runtime.server)
+      ? runtime.server
+      : null;
+  if (!server) {
+    return Object.freeze([]);
+  }
+
+  const providers = Array.isArray(server.providers) ? server.providers : [];
+  const normalizedProviders = [];
+
+  for (const providerDefinition of providers) {
+    const entry = providerDefinition && typeof providerDefinition === "object" ? providerDefinition : {};
+    const providerEntrypoint = String(entry.entrypoint || "").trim();
+    const providerExport = String(entry.export || "").trim();
+    const discoverConfig =
+      entry.discover && typeof entry.discover === "object" && !Array.isArray(entry.discover) ? entry.discover : null;
+
+    if (discoverConfig) {
+      if (providerEntrypoint || providerExport) {
+        throw new Error(
+          `Package ${packageId} runtime.server.providers[] discover entries cannot include entrypoint/export fields.`
+        );
+      }
+
+      const discoverDir = String(discoverConfig.dir || "").trim();
+      if (!discoverDir) {
+        throw new Error(`Package ${packageId} runtime.server.providers[] discover.dir is required.`);
+      }
+      if (discoverDir.startsWith("/") || discoverDir.startsWith("//")) {
+        throw new Error(`Package ${packageId} runtime.server.providers[] discover.dir must be relative.`);
+      }
+      if (discoverDir.includes("*")) {
+        throw new Error(`Package ${packageId} runtime.server.providers[] discover.dir cannot contain wildcard "*".`);
+      }
+
+      const discoverPattern = String(discoverConfig.pattern || "*Provider.js").trim() || "*Provider.js";
+      if (discoverPattern.includes(path.sep) || discoverPattern.includes("/")) {
+        throw new Error(
+          `Package ${packageId} runtime.server.providers[] discover.pattern must match filenames only.`
+        );
+      }
+      if (!createWildcardMatcher(discoverPattern)) {
+        throw new Error(`Package ${packageId} runtime.server.providers[] discover.pattern is invalid.`);
+      }
+
+      const discoverRecursive = discoverConfig.recursive === true;
+      normalizedProviders.push(
+        Object.freeze({
+          type: "discover",
+          discoverDir,
+          discoverPattern,
+          discoverRecursive
+        })
+      );
+      continue;
+    }
+
+    if (!providerEntrypoint) {
+      throw new Error(`Package ${packageId} runtime.server.providers[] entrypoint is required.`);
+    }
+    if (!providerExport) {
+      throw new Error(`Package ${packageId} runtime.server.providers[] export is required for ${providerEntrypoint}.`);
+    }
+    if (!isIdentifier(providerExport)) {
+      throw new Error(`Package ${packageId} runtime.server.providers[] export is invalid: ${providerExport}`);
+    }
+
+    normalizedProviders.push(
+      Object.freeze({
+        type: "explicit",
+        providerEntrypoint,
+        providerExport
+      })
+    );
+  }
+
+  return Object.freeze(normalizedProviders);
+}
+
+function isProviderDefinition(value) {
+  if (typeof value !== "function") {
+    return false;
+  }
+  const prototype = value.prototype && typeof value.prototype === "object" ? value.prototype : null;
+  const hasLifecycleMethods = Boolean(
+    (prototype && typeof prototype.register === "function") ||
+      (prototype && typeof prototype.boot === "function") ||
+      (prototype && typeof prototype.shutdown === "function")
+  );
+  const rawId = value.id;
+  const hasProviderId = rawId !== undefined && rawId !== null && String(rawId).trim().length > 0;
+  return hasLifecycleMethods && hasProviderId;
+}
+
+function normalizeProviderExportValue(value, { packageId, label }) {
+  const output = [];
+  const queue = Array.isArray(value) ? [...value] : [value];
+  while (queue.length > 0) {
+    const candidate = queue.shift();
+    if (!candidate) {
+      continue;
+    }
+    if (Array.isArray(candidate)) {
+      queue.push(...candidate);
+      continue;
+    }
+    if (isProviderDefinition(candidate)) {
+      output.push(candidate);
+      continue;
+    }
+    throw new Error(
+      `Package ${packageId} ${label} must export a provider class/function or an array of provider classes/functions.`
+    );
+  }
+  return output;
+}
+
+function resolveProviderClassesFromModule(moduleNamespace, { packageId, providerExport }) {
+  const namespace = moduleNamespace && typeof moduleNamespace === "object" ? moduleNamespace : {};
+  if (providerExport) {
+    if (!Object.prototype.hasOwnProperty.call(namespace, providerExport)) {
+      throw new Error(`Package ${packageId} provider export "${providerExport}" was not found.`);
+    }
+    return normalizeProviderExportValue(namespace[providerExport], {
+      packageId,
+      label: `provider export "${providerExport}"`
+    });
+  }
+
+  const discovered = [];
+  for (const [exportName, exportValue] of Object.entries(namespace)) {
+    if (!isProviderDefinition(exportValue)) {
+      continue;
+    }
+    discovered.push(...normalizeProviderExportValue(exportValue, { packageId, label: `export "${exportName}"` }));
+  }
+
+  if (discovered.length < 1) {
+    throw new Error(
+      `Package ${packageId} provider entrypoint did not export any provider classes/functions.`
+    );
+  }
+
+  return discovered;
+}
+
+async function collectDiscoveredProviderModulePaths({ descriptorEntry, providerDefinition }) {
+  const discoverRoot = path.resolve(descriptorEntry.packageRoot, providerDefinition.discoverDir);
+  if (!isInsidePackageRoot(descriptorEntry.packageRoot, discoverRoot)) {
+    throw new Error(
+      `Package ${descriptorEntry.packageId} runtime.server.providers[] discover.dir escapes package root: ${providerDefinition.discoverDir}`
+    );
+  }
+  if (!(await fileExists(discoverRoot))) {
+    return Object.freeze([]);
+  }
+
+  const patternMatcher = createWildcardMatcher(providerDefinition.discoverPattern);
+  if (!(patternMatcher instanceof RegExp)) {
+    throw new Error(
+      `Package ${descriptorEntry.packageId} runtime.server.providers[] discover.pattern is invalid: ${providerDefinition.discoverPattern}`
+    );
+  }
+  const collectedPaths = [];
+
+  async function walk(currentPath) {
+    const entries = await readdir(currentPath, { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+
+    for (const entry of entries) {
+      const entryName = String(entry?.name || "");
+      if (!entryName || entryName.startsWith(".")) {
+        continue;
+      }
+
+      const absoluteEntryPath = path.join(currentPath, entryName);
+      if (entry.isDirectory()) {
+        if (entryName === "node_modules") {
+          continue;
+        }
+        if (providerDefinition.discoverRecursive === true) {
+          await walk(absoluteEntryPath);
+        }
+        continue;
+      }
+
+      if (!entry.isFile()) {
+        continue;
+      }
+
+      if (patternMatcher.test(entryName)) {
+        collectedPaths.push(absoluteEntryPath);
+      }
+    }
+  }
+
+  await walk(discoverRoot);
+  return toAbsoluteSortedUniquePaths(collectedPaths);
+}
+
+function registerProviderClass({ providerClass, sourceId, seenProviderIds, orderedProviderClasses }) {
+  const providerId = String(providerClass.id || providerClass.name || "<anonymous-provider>").trim();
+  if (seenProviderIds.has(providerId)) {
+    const existingSourceId = seenProviderIds.get(providerId);
+    throw new Error(`Provider id "${providerId}" is duplicated between ${existingSourceId} and ${sourceId}.`);
+  }
+
+  seenProviderIds.set(providerId, sourceId);
+  orderedProviderClasses.push(providerClass);
+}
+
+async function loadPackageProviders({ descriptorEntry }) {
+  const providerDefinitions = normalizeServerProviderDefinitions(descriptorEntry.descriptor, descriptorEntry.packageId);
+  if (providerDefinitions.length < 1) {
+    return Object.freeze([]);
+  }
+
+  const providerClasses = [];
+  for (const providerDefinition of providerDefinitions) {
+    if (providerDefinition.type === "discover") {
+      const discoveredProviderPaths = await collectDiscoveredProviderModulePaths({
+        descriptorEntry,
+        providerDefinition
+      });
+
+      for (const discoveredProviderPath of discoveredProviderPaths) {
+        const providerModule = await import(pathToFileURL(discoveredProviderPath).href);
+        providerClasses.push(
+          ...resolveProviderClassesFromModule(providerModule, {
+            packageId: `${descriptorEntry.packageId} (${normalizeRelativePath(
+              descriptorEntry.packageRoot,
+              discoveredProviderPath
+            )})`,
+            providerExport: ""
+          })
+        );
+      }
+      continue;
+    }
+
+    const providerModulePath = path.resolve(descriptorEntry.packageRoot, providerDefinition.providerEntrypoint);
+    if (!isInsidePackageRoot(descriptorEntry.packageRoot, providerModulePath)) {
+      throw new Error(
+        `Package ${descriptorEntry.packageId} runtime.server.providers[] entrypoint escapes package root: ${providerDefinition.providerEntrypoint}`
+      );
+    }
+    if (!(await fileExists(providerModulePath))) {
+      throw new Error(
+        `Package ${descriptorEntry.packageId} runtime.server.providers[] entrypoint not found: ${providerDefinition.providerEntrypoint}`
+      );
+    }
+
+    const providerModule = await import(pathToFileURL(providerModulePath).href);
+    providerClasses.push(
+      ...resolveProviderClassesFromModule(providerModule, {
+        packageId: descriptorEntry.packageId,
+        providerExport: providerDefinition.providerExport
+      })
+    );
+  }
+
+  return Object.freeze(providerClasses);
+}
+
+export { loadPackageProviders, registerProviderClass };