@jskit-ai/kernel 0.1.159 → 0.1.161

package/_testable/index.js

@@ -1,4 +1,2 @@
-export { createContainer } from "../server/container/index.js";
-export { createApplication } from "../server/kernel/index.js";
-export { createHttpRuntime, compileRouteValidator } from "../server/http/_testable/index.js";
+export { compileRouteValidator } from "../server/http/_testable/index.js";
 export { deriveResourceRequiredMetadata } from "../shared/validators/index.js";

package/client/componentRegistry.js

@@ -0,0 +1,44 @@
+function normalizeComponentId(value) {
+  const id = String(value || "").trim();
+  if (!id) {
+    throw new TypeError("Client component id is required.");
+  }
+  return id;
+}
+
+function createClientComponentRegistry() {
+  const components = new Map();
+
+  function register(id, component) {
+    const componentId = normalizeComponentId(id);
+    if (component == null) {
+      throw new TypeError(`Client component "${componentId}" is required.`);
+    }
+    if (components.has(componentId)) {
+      throw new Error(`Client component "${componentId}" is duplicated.`);
+    }
+    components.set(componentId, component);
+    return api;
+  }
+
+  function has(id) {
+    return components.has(normalizeComponentId(id));
+  }
+
+  function get(id) {
+    const componentId = normalizeComponentId(id);
+    if (!components.has(componentId)) {
+      throw new Error(`Client component "${componentId}" is not registered.`);
+    }
+    return components.get(componentId);
+  }
+
+  function ids() {
+    return Object.freeze([...components.keys()].sort());
+  }
+
+  const api = Object.freeze({ register, has, get, ids });
+  return api;
+}
+
+export { createClientComponentRegistry };

package/client/componentRegistry.test.js

@@ -0,0 +1,16 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createClientComponentRegistry } from "./componentRegistry.js";
+
+test("client component registry exposes named UI components without a service locator", () => {
+  const registry = createClientComponentRegistry();
+  const component = Object.freeze({ name: "ExampleWidget" });
+
+  registry.register("example.widget", component);
+
+  assert.equal(registry.has("example.widget"), true);
+  assert.equal(registry.get("example.widget"), component);
+  assert.deepEqual(registry.ids(), ["example.widget"]);
+  assert.throws(() => registry.register("example.widget", {}), /duplicated/);
+  assert.throws(() => registry.get("missing.widget"), /not registered/);
+});

package/client/moduleBootstrap.js

@@ -1,6 +1,7 @@
-import { createApplication } from "../shared/runtime/application.js";
+import { createCapabilityRuntime, defineProvider } from "../shared/capabilities/index.js";
 import { filterRoutesBySurface } from "../shared/surface/runtime.js";
 import { isRecord } from "../shared/support/normalize.js";
+import { createClientComponentRegistry } from "./componentRegistry.js";
 import { normalizePackageMetadataClientProviders, normalizePackageMetadataUiRoutes } from "./packageMetadataSections.js";
 import { createStructuredLogger, summarizeRouterRoutes } from "./logging.js";
 
@@ -187,44 +188,7 @@ function registerClientModuleRoutes({
   });
 }
 
-function isProviderClass(candidate) {
-  if (typeof candidate !== "function") {
-    return false;
-  }
-
-  const providerId = String(candidate.id || "").trim();
-  if (!providerId) {
-    return false;
-  }
-
-  const prototype = candidate.prototype;
-  if (!prototype || typeof prototype !== "object") {
-    return false;
-  }
-
-  return (
-    typeof prototype.register === "function" ||
-    typeof prototype.boot === "function" ||
-    typeof prototype.shutdown === "function"
-  );
-}
-
-function normalizeExplicitProviderClasses(value, packageId) {
-  if (!Array.isArray(value)) {
-    return null;
-  }
-
-  const providers = [];
-  for (const candidate of value) {
-    if (!isProviderClass(candidate)) {
-      throw new TypeError(`Client module ${packageId} exports invalid clientProviders entry.`);
-    }
-    providers.push(candidate);
-  }
-  return providers;
-}
-
-function resolvePackageMetadataProviderClasses(moduleNamespace, packageId, packageMetadataClientProviders = []) {
+function resolvePackageMetadataProviders(moduleNamespace, packageId, packageMetadataClientProviders = []) {
   const providers = [];
   const seenProviderIds = new Set();
 
@@ -234,42 +198,34 @@ function resolvePackageMetadataProviderClasses(moduleNamespace, packageId, packa
       continue;
     }
 
-    const providerClass = moduleNamespace?.[exportName];
-    if (!isProviderClass(providerClass)) {
+    const providerValue = moduleNamespace?.[exportName];
+    let provider = null;
+    try {
+      provider = defineProvider(providerValue);
+    } catch (error) {
       throw new TypeError(
-        `Client module ${packageId} packageMetadata provider export "${exportName}" is missing or invalid in "${packageId}/client".`
+        `Client module ${packageId} packageMetadata provider export "${exportName}" must be a capability provider: ${error.message}`,
+        { cause: error }
       );
     }
 
-    const providerId = String(providerClass.id || "").trim();
-    if (!providerId) {
-      throw new TypeError(`Client module ${packageId} packageMetadata provider "${exportName}" requires static id.`);
-    }
+    const providerId = provider.id;
 
     if (seenProviderIds.has(providerId)) {
       continue;
     }
     seenProviderIds.add(providerId);
-    providers.push(providerClass);
+    providers.push(provider);
   }
 
   return providers;
 }
 
-function resolveModuleProviderClasses(moduleNamespace, packageId, packageMetadataClientProviders = []) {
+function resolveModuleProviders(moduleNamespace, packageId, packageMetadataClientProviders = []) {
   if (!isRecord(moduleNamespace)) {
     return [];
   }
-
-  const explicitProviders = normalizeExplicitProviderClasses(moduleNamespace.clientProviders, packageId);
-  if (explicitProviders) {
-    return explicitProviders;
-  }
-
-  if (Array.isArray(packageMetadataClientProviders) && packageMetadataClientProviders.length > 0) {
-    return resolvePackageMetadataProviderClasses(moduleNamespace, packageId, packageMetadataClientProviders);
-  }
-  return [];
+  return resolvePackageMetadataProviders(moduleNamespace, packageId, packageMetadataClientProviders);
 }
 
 function buildPackageMetadataRouteDeclarationIndex({ packageId, packageMetadataUiRoutes = [] } = {}) {
@@ -479,8 +435,9 @@ function normalizeClientModuleEntries(clientModules) {
     .sort((left, right) => left.packageId.localeCompare(right.packageId));
 }
 
-function createClientRuntimeApp({
+function createClientRuntime({
   profile = "client",
+  providers = [],
   app,
   pinia = null,
   queryClient = null,
@@ -490,22 +447,23 @@ function createClientRuntimeApp({
   surfaceRuntime,
   surfaceMode
 } = {}) {
-  const runtimeApp = createApplication({
+  const components = createClientComponentRegistry();
+  const runtime = createCapabilityRuntime({
     profile,
-    strict: true
+    providers,
+    inputs: {
+      "client.vue": app || null,
+      "client.router": router || null,
+      "client.pinia": pinia,
+      "client.query": queryClient,
+      "client.env": Object.freeze({ ...(isRecord(env) ? env : {}) }),
+      "client.surface": surfaceRuntime || null,
+      "client.surface-mode": String(surfaceMode || "").trim(),
+      "client.logger": logger,
+      "client.components": components
+    }
   });
-
-  runtimeApp.instance("jskit.client.runtime.app", runtimeApp);
-  runtimeApp.instance("jskit.client.router", router || null);
-  runtimeApp.instance("jskit.client.vue.app", app || null);
-  runtimeApp.instance("jskit.client.pinia", pinia);
-  runtimeApp.instance("jskit.client.query-client", queryClient);
-  runtimeApp.instance("jskit.client.env", isRecord(env) ? { ...env } : {});
-  runtimeApp.instance("jskit.client.surface.runtime", surfaceRuntime || null);
-  runtimeApp.instance("jskit.client.surface.mode", String(surfaceMode || "").trim());
-  runtimeApp.instance("jskit.client.logger", logger);
-
-  return runtimeApp;
+  return Object.freeze({ runtime, components });
 }
 
 async function bootClientModules({
@@ -528,19 +486,7 @@ async function bootClientModules({
 
   const log = createStructuredLogger(logger);
   const moduleEntries = normalizeClientModuleEntries(clientModules);
-  const runtimeApp = createClientRuntimeApp({
-    profile: String(surfaceRuntime.normalizeSurfaceMode(surfaceMode) || "client"),
-    app,
-    pinia,
-    queryClient,
-    router,
-    env,
-    logger: log,
-    surfaceRuntime,
-    surfaceMode
-  });
-
-  const providerClasses = [];
+  const providers = [];
   const seenProviderIds = new Set();
   log.debug(
     {
@@ -552,28 +498,38 @@ async function bootClientModules({
     "Starting JSKIT client module bootstrap."
   );
   for (const entry of moduleEntries) {
-    const providers = resolveModuleProviderClasses(entry.module, entry.packageId, entry.packageMetadataClientProviders);
+    const moduleProviders = resolveModuleProviders(entry.module, entry.packageId, entry.packageMetadataClientProviders);
     log.debug(
       {
         packageId: entry.packageId,
-        providerExports: providers.map((providerClass) => String(providerClass.id || providerClass.name || "").trim()),
+        providerExports: moduleProviders.map((provider) => provider.id),
         hasClientRoutes: Array.isArray(entry.module.clientRoutes) && entry.module.clientRoutes.length > 0
       },
       "Discovered client module capabilities."
     );
-    for (const providerClass of providers) {
-      const providerId = String(providerClass.id || "").trim();
+    for (const provider of moduleProviders) {
+      const providerId = provider.id;
       if (seenProviderIds.has(providerId)) {
         throw new Error(`Client provider id "${providerId}" is duplicated.`);
       }
       seenProviderIds.add(providerId);
-      providerClasses.push(providerClass);
+      providers.push(provider);
     }
   }
 
-  if (providerClasses.length > 0) {
-    await runtimeApp.start({ providers: providerClasses });
-  }
+  const clientRuntime = createClientRuntime({
+    profile: String(surfaceRuntime.normalizeSurfaceMode(surfaceMode) || "client"),
+    providers,
+    app,
+    pinia,
+    queryClient,
+    router,
+    env,
+    logger: log,
+    surfaceRuntime,
+    surfaceMode
+  });
+  await clientRuntime.runtime.start();
 
   const seenRoutePaths = new Set();
   const seenRouteNames = new Set();
@@ -638,7 +594,7 @@ async function bootClientModules({
     log.debug(
       {
         modules: moduleEntries.map((entry) => entry.packageId),
-        providerCount: providerClasses.length,
+        providerCount: providers.length,
         routeCount: registeredRouteCount
       },
       "Booted JSKIT client modules."
@@ -653,9 +609,10 @@ async function bootClientModules({
   }
 
   return Object.freeze({
-    runtimeApp,
+    runtime: clientRuntime.runtime,
+    components: clientRuntime.components,
     modules: Object.freeze(moduleEntries.map((entry) => entry.packageId)),
-    providerCount: providerClasses.length,
+    providerCount: providers.length,
     routeResults: Object.freeze(routeResults),
     routeCount: registeredRouteCount
   });

package/client/moduleBootstrap.test.js

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import { defineProvider } from "../shared/capabilities/index.js";
 import { createSurfaceRuntime } from "../shared/surface/runtime.js";
 import { bootClientModules } from "./moduleBootstrap.js";
 
@@ -115,25 +116,37 @@ test("bootClientModules registers packageMetadata and clientRoutes with provider
   const pinia = { id: "pinia-instance" };
   const queryClient = { id: "query-client-instance" };
   const implicitPinia = { id: "implicit-vue-global-pinia" };
-  class ExampleClientProvider {
-    static id = "example.client";
-    register(app) {
-      events.push("register");
-      app.instance("example.value", 42);
-      app.instance("example.pinia", app.make("jskit.client.pinia"));
-      app.instance("example.queryClient", app.make("jskit.client.query-client"));
-    }
+  let receivedPinia = null;
+  let receivedQueryClient = null;
+  const ExampleClientProvider = defineProvider({
+    id: "example.client",
+    requires: {
+      components: "client.components",
+      pinia: "client.pinia",
+      queryClient: "client.query"
+    },
+    setup({ components, pinia: runtimePinia, queryClient: runtimeQueryClient }) {
+      events.push("setup");
+      components.register("example.login", loginComponent);
+      receivedPinia = runtimePinia;
+      receivedQueryClient = runtimeQueryClient;
+    },
     boot() {
       events.push("boot");
     }
-  }
+  });
 
   const result = await bootClientModules({
     clientModules: [
       {
         packageId: "@example/alpha",
+        packageMetadataClientProviders: [
+          {
+            entrypoint: "src/client/providers/ExampleClientProvider.js",
+            export: "ExampleClientProvider"
+          }
+        ],
         module: {
-          clientProviders: [ExampleClientProvider],
           ExampleClientProvider
         }
       },
@@ -199,7 +212,7 @@ test("bootClientModules registers packageMetadata and clientRoutes with provider
     logger: { info() {}, warn() {}, error() {} }
   });
 
-  assert.deepEqual(events, ["register", "boot"]);
+  assert.deepEqual(events, ["setup", "boot"]);
   assert.equal(result.providerCount, 1);
   assert.equal(result.routeCount, 2);
   assert.equal(router.routes.length, 2);
@@ -207,10 +220,11 @@ test("bootClientModules registers packageMetadata and clientRoutes with provider
   assert.equal(router.routes[0].component, loginComponent);
   assert.equal(router.routes[1].path, "/auth/login");
   assert.equal(router.routes[1].component, loginComponent);
-  assert.equal(result.runtimeApp.make("example.value"), 42);
-  assert.equal(result.runtimeApp.make("example.pinia"), pinia);
-  assert.equal(result.runtimeApp.make("example.queryClient"), queryClient);
-  assert.notEqual(result.runtimeApp.make("example.pinia"), implicitPinia);
+  assert.equal(result.components.get("example.login"), loginComponent);
+  assert.equal(receivedPinia, pinia);
+  assert.equal(receivedQueryClient, queryClient);
+  assert.notEqual(receivedPinia, implicitPinia);
+  assert.equal(result.runtime.diagnostics().lifecycleState, "started");
 });
 
 test("bootClientModules does not auto-discover providers from module exports", async () => {
@@ -218,15 +232,15 @@ test("bootClientModules does not auto-discover providers from module exports", a
   const surfaceRuntime = createSurfaceRuntimeFixture();
   const events = [];
 
-  class ExampleClientProvider {
-    static id = "example.client";
-    register() {
-      events.push("register");
-    }
+  const ExampleClientProvider = defineProvider({
+    id: "example.client",
+    setup() {
+      events.push("setup");
+    },
     boot() {
       events.push("boot");
     }
-  }
+  });
 
   const result = await bootClientModules({
     clientModules: [
@@ -359,6 +373,15 @@ test("bootClientModules loads client providers declared in packageMetadataClient
   const router = createRouterStub();
   const surfaceRuntime = createSurfaceRuntimeFixture();
   const events = [];
+  const ExampleProvider = defineProvider({
+    id: "example.packageMetadata.provider",
+    setup() {
+      events.push("setup");
+    },
+    boot() {
+      events.push("boot");
+    }
+  });
 
   await bootClientModules({
     clientModules: [
@@ -371,15 +394,7 @@ test("bootClientModules loads client providers declared in packageMetadataClient
           }
         ],
         module: {
-          ExampleProvider: class {
-            static id = "example.packageMetadata.provider";
-            register() {
-              events.push("register");
-            }
-            boot() {
-              events.push("boot");
-            }
-          }
+          ExampleProvider
         }
       }
     ],
@@ -389,7 +404,7 @@ test("bootClientModules loads client providers declared in packageMetadataClient
     logger: { info() {}, warn() {}, error() {} }
   });
 
-  assert.deepEqual(events, ["register", "boot"]);
+  assert.deepEqual(events, ["setup", "boot"]);
 });
 
 test("bootClientModules throws when packageMetadataClientProviders export is missing", async () => {
@@ -415,6 +430,6 @@ test("bootClientModules throws when packageMetadataClientProviders export is mis
       surfaceMode: "all",
       logger: { info() {}, warn() {}, error() {} }
     }),
-    /packageMetadata provider export "MissingProvider" is missing or invalid/
+    /packageMetadata provider export "MissingProvider" must be a capability provider/
   );
 });

package/client/vite/clientBootstrapPlugin.test.js

@@ -504,7 +504,7 @@ test("resolveInstalledViteProxyEntries rejects malformed package proxy metadata"
   );
 });
 
-test("resolveLocalScopePackageIds reads @local packages from package.json", async () => {
+test("resolveLocalScopePackageIds excludes development-only local packages from runtime composition", async () => {
   const tempRoot = await mkdtemp(path.join(os.tmpdir(), "jskit-client-bootstrap-local-scope-"));
   await writeJson(path.join(tempRoot, "package.json"), {
     name: "fixture-app",
@@ -519,7 +519,7 @@ test("resolveLocalScopePackageIds reads @local packages from package.json", asyn
 
   const packageIds = await resolveLocalScopePackageIds({ appRoot: tempRoot });
 
-  assert.deepEqual(packageIds, ["@local/dev-only", "@local/feature"]);
+  assert.deepEqual(packageIds, ["@local/feature"]);
 });
 
 test("createJskitClientBootstrapPlugin resolves and loads virtual module", async () => {

package/internal/node/installedPackages.js

@@ -7,18 +7,13 @@ import { fileExists } from "./fileSystem.js";
 const ROOT_DEPENDENCY_SECTIONS = Object.freeze([
   "dependencies",
   "optionalDependencies",
-  "peerDependencies",
-  "devDependencies"
+  "peerDependencies"
 ]);
 const JSKIT_PACKAGE_CONFIG_KEYS = Object.freeze([
   "capabilities",
-  "ci",
   "kind",
-  "lifecycle",
   "metadata",
-  "mutations",
-  "optionPolicies",
-  "options",
+  "migrations",
   "runtime",
   "vite"
 ]);

package/internal/node/installedPackages.test.js

@@ -32,13 +32,9 @@ test("createPackageMetadata derives package identity from package.json", () => {
 test("createPackageMetadata accepts only the canonical package.json.jskit fields", () => {
   assert.deepEqual(JSKIT_PACKAGE_CONFIG_KEYS, [
     "capabilities",
-    "ci",
     "kind",
-    "lifecycle",
     "metadata",
-    "mutations",
-    "optionPolicies",
-    "options",
+    "migrations",
     "runtime",
     "vite"
   ]);
@@ -94,3 +90,28 @@ test("discoverInstalledPackages resolves file tarballs from node_modules", async
   assert.equal(packages[0].packageRoot, installedPackageRoot);
   assert.equal(packages[0].sourceType, "npm-package");
 });
+
+test("discoverInstalledPackages excludes development-only packages from runtime composition", async (context) => {
+  const appRoot = await mkdtemp(path.join(tmpdir(), "jskit-installed-package-dev-"));
+  context.after(() => rm(appRoot, { recursive: true, force: true }));
+  const runtimeRoot = path.join(appRoot, "node_modules", "@example", "runtime");
+  const docsRoot = path.join(appRoot, "node_modules", "@example", "docs");
+  await mkdir(runtimeRoot, { recursive: true });
+  await mkdir(docsRoot, { recursive: true });
+  await writeFile(
+    path.join(appRoot, "package.json"),
+    JSON.stringify({
+      dependencies: { "@example/runtime": "1.0.0" },
+      devDependencies: { "@example/docs": "1.0.0" }
+    })
+  );
+  for (const [packageRoot, name] of [[runtimeRoot, "@example/runtime"], [docsRoot, "@example/docs"]]) {
+    await writeFile(
+      path.join(packageRoot, "package.json"),
+      JSON.stringify({ name, version: "1.0.0", jskit: { kind: "runtime" } })
+    );
+  }
+
+  const packages = await discoverInstalledPackages({ appRoot });
+  assert.deepEqual(packages.map((entry) => entry.packageId), ["@example/runtime"]);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/kernel",
-  "version": "0.1.159",
+  "version": "0.1.161",
   "type": "module",
   "dependencies": {
     "json-rest-schema": "^1.0.17"
@@ -25,27 +25,25 @@
     "./client/moduleBootstrap": "./client/moduleBootstrap.js",
     "./client/vite": "./client/vite/index.js",
     "./server/actions": "./server/actions/index.js",
+    "./server/features": "./server/features/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/entityChangeEvents": "./server/runtime/entityChangeEvents.js",
     "./server/runtime/errors": "./server/runtime/errors.js",
     "./server/runtime/requestUrl": "./server/runtime/requestUrl.js",
     "./server/support": "./server/support/index.js",
     "./shared": "./shared/index.js",
-    "./shared/actions": "./shared/actions/index.js",
+    "./shared/capabilities": "./shared/capabilities/index.js",
     "./shared/actions/actionContributorHelpers": "./shared/actions/actionContributorHelpers.js",
     "./shared/actions/textNormalization": "./shared/actions/textNormalization.js",
     "./shared/validators": "./shared/validators/index.js",
     "./shared/validators/inputNormalization": "./shared/validators/inputNormalization.js",
     "./shared/support": "./shared/support/index.js",
     "./shared/support/stringCase": "./shared/support/stringCase.js",
-    "./shared/support/tokens": "./shared/support/tokens.js",
     "./shared/support/normalize": "./shared/support/normalize.js",
     "./shared/support/permissions": "./shared/support/permissions.js",
     "./shared/support/jsonApiFieldsets": "./shared/support/jsonApiFieldsets.js",
-    "./shared/support/generatedUiContract": "./shared/support/generatedUiContract.js",
     "./shared/support/deepFreeze": "./shared/support/deepFreeze.js",
     "./shared/support/listenerSet": "./shared/support/listenerSet.js",
     "./shared/support/shellLayoutTargets": "./shared/support/shellLayoutTargets.js",