@jskit-ai/kernel 0.1.156 → 0.1.158

package/client/vite/clientBootstrapPlugin.js

@@ -4,7 +4,7 @@ import {
   collectRootDependencySpecifiers,
   discoverInstalledPackages
 } from "../../internal/node/installedPackages.js";
-import { normalizeObject } from "../../shared/support/normalize.js";
+import { isRecord, normalizeObject } from "../../shared/support/normalize.js";
 import { sortStrings } from "../../shared/support/sorting.js";
 import {
   normalizePackageMetadataClientProviders,
@@ -132,8 +132,7 @@ function resolveCanonicalLocalPackageId(resolvedId, localPackage) {
     : "";
 }
 
-async function resolveInstalledClientModules({ appRoot }) {
-  const installedPackages = await discoverInstalledPackages({ appRoot });
+function resolveClientModulesFromInstalledPackages(installedPackages = []) {
   const modules = [];
   for (const installedPackage of installedPackages) {
     if (!hasClientExport(installedPackage.packageJson)) {
@@ -156,6 +155,85 @@ async function resolveInstalledClientModules({ appRoot }) {
   return Object.freeze(modules);
 }
 
+async function resolveInstalledClientModules({ appRoot }) {
+  return resolveClientModulesFromInstalledPackages(
+    await discoverInstalledPackages({ appRoot })
+  );
+}
+
+function resolveInstalledViteProxyEntries(installedPackages = [], { proxyTarget = "" } = {}) {
+  const fallbackTarget = String(proxyTarget || "").trim();
+  const proxyEntries = {};
+  const ownerByPath = new Map();
+
+  for (const installedPackage of [...installedPackages].sort((left, right) =>
+    String(left?.packageId || "").localeCompare(String(right?.packageId || "")))) {
+    const packageId = String(installedPackage?.packageId || "").trim();
+    const vite = installedPackage?.packageMetadata?.vite;
+    if (vite == null) {
+      continue;
+    }
+    if (!isRecord(vite) || (vite.proxy != null && !isRecord(vite.proxy))) {
+      throw new Error(`${packageId} package.json#jskit.vite.proxy must be an object.`);
+    }
+    const proxy = normalizeObject(vite.proxy);
+
+    for (const routePath of sortStrings(Object.keys(proxy))) {
+      if (!routePath.startsWith("/") || routePath.startsWith("//")) {
+        throw new Error(`Vite proxy path ${JSON.stringify(routePath)} from ${packageId} must start with one "/".`);
+      }
+      if (ownerByPath.has(routePath)) {
+        throw new Error(
+          `Vite proxy path ${JSON.stringify(routePath)} is declared by both ${ownerByPath.get(routePath)} and ${packageId}.`
+        );
+      }
+
+      const config = proxy[routePath];
+      if (!isRecord(config)) {
+        throw new Error(
+          `Vite proxy path ${JSON.stringify(routePath)} from ${packageId} must be an object.`
+        );
+      }
+      const unknownFields = Object.keys(config)
+        .filter((field) => !["changeOrigin", "target", "ws"].includes(field))
+        .sort();
+      if (unknownFields.length > 0) {
+        throw new Error(
+          `Vite proxy path ${JSON.stringify(routePath)} from ${packageId} has unsupported ${unknownFields.length === 1 ? "field" : "fields"}: ${unknownFields.join(", ")}.`
+        );
+      }
+      for (const field of ["changeOrigin", "ws"]) {
+        if (Object.hasOwn(config, field) && typeof config[field] !== "boolean") {
+          throw new Error(
+            `Vite proxy path ${JSON.stringify(routePath)} from ${packageId} requires ${field} to be boolean.`
+          );
+        }
+      }
+      if (Object.hasOwn(config, "target") && typeof config.target !== "string") {
+        throw new Error(
+          `Vite proxy path ${JSON.stringify(routePath)} from ${packageId} requires target to be a string.`
+        );
+      }
+
+      const target = String(config.target || "").trim() || fallbackTarget;
+      if (!target) {
+        throw new Error(
+          `Vite proxy path ${JSON.stringify(routePath)} from ${packageId} requires target or createJskitClientBootstrapPlugin({ proxyTarget }).`
+        );
+      }
+
+      ownerByPath.set(routePath, packageId);
+      proxyEntries[routePath] = {
+        target,
+        ...(Object.hasOwn(config, "changeOrigin") ? { changeOrigin: config.changeOrigin === true } : {}),
+        ...(Object.hasOwn(config, "ws") ? { ws: config.ws === true } : {})
+      };
+    }
+  }
+
+  return proxyEntries;
+}
+
 async function resolveInstalledClientPackageIds(options) {
   const modules = await resolveInstalledClientModules(options);
   return Object.freeze(modules.map((entry) => entry.packageId));
@@ -269,7 +347,7 @@ function resolveClientRuntimeDedupeSpecifiers(userResolveConfig = {}) {
   return sortStrings([...userDedupe, ...CLIENT_RUNTIME_DEDUPE_SPECIFIERS]);
 }
 
-function createJskitClientBootstrapPlugin() {
+function createJskitClientBootstrapPlugin({ proxyTarget = "" } = {}) {
   let appRoot = process.cwd();
   let localPackages = Object.freeze([]);
   let resolvePackageSpecifier = null;
@@ -280,8 +358,10 @@ function createJskitClientBootstrapPlugin() {
     enforce: "pre",
     async config(userConfig = {}) {
       appRoot = process.cwd();
-      const clientModules = await resolveInstalledClientModules({
-        appRoot
+      const installedPackages = await discoverInstalledPackages({ appRoot });
+      const clientModules = resolveClientModulesFromInstalledPackages(installedPackages);
+      const installedProxyEntries = resolveInstalledViteProxyEntries(installedPackages, {
+        proxyTarget
       });
       const localScopePackageIds = await resolveLocalScopePackageIds({
         appRoot
@@ -299,6 +379,8 @@ function createJskitClientBootstrapPlugin() {
       const clientIncludeSpecifiers = resolveClientOptimizeIncludeSpecifiers(clientModules, exclude);
       const include = sortStrings([...userInclude, ...clientIncludeSpecifiers].filter((specifier) => !exclude.includes(specifier)));
       const dedupe = resolveClientRuntimeDedupeSpecifiers(userResolve);
+      const userServer = normalizeObject(userConfig.server);
+      const userProxyEntries = normalizeObject(userServer.proxy);
 
       return {
         optimizeDeps: {
@@ -309,6 +391,12 @@ function createJskitClientBootstrapPlugin() {
         resolve: {
           ...userResolve,
           dedupe
+        },
+        server: {
+          proxy: {
+            ...installedProxyEntries,
+            ...userProxyEntries
+          }
         }
       };
     },
@@ -368,5 +456,6 @@ export {
   resolveInstalledClientPackageIds,
   resolveLocalScopePackageIds,
   resolveInstalledClientModules,
+  resolveInstalledViteProxyEntries,
   createJskitClientBootstrapPlugin
 };

package/client/vite/clientBootstrapPlugin.test.js

@@ -16,7 +16,8 @@ import {
   resolveClientOptimizeExcludeSpecifiers,
   resolveLocalScopePackageIds,
   resolveInstalledClientPackageIds,
-  resolveInstalledClientModules
+  resolveInstalledClientModules,
+  resolveInstalledViteProxyEntries
 } from "./clientBootstrapPlugin.js";
 
 async function writeJson(filePath, value) {
@@ -440,6 +441,69 @@ test("resolveInstalledClientModules resolves a packageMetadata from a file depen
   assert.equal(modules[0].packageMetadataClientProviders[0].export, "LocalClientProvider");
 });
 
+test("resolveInstalledViteProxyEntries derives proxy config directly from package metadata", () => {
+  const proxy = resolveInstalledViteProxyEntries(
+    [
+      {
+        packageId: "@example/realtime",
+        packageMetadata: {
+          vite: {
+            proxy: {
+              "/socket.io": {
+                changeOrigin: true,
+                ws: true
+              }
+            }
+          }
+        }
+      }
+    ],
+    {
+      proxyTarget: "http://localhost:3000"
+    }
+  );
+
+  assert.deepEqual(proxy, {
+    "/socket.io": {
+      target: "http://localhost:3000",
+      changeOrigin: true,
+      ws: true
+    }
+  });
+  proxy["/socket.io"].prependPath = false;
+  assert.equal(proxy["/socket.io"].prependPath, false);
+});
+
+test("resolveInstalledViteProxyEntries rejects ambiguous package proxy paths", () => {
+  assert.throws(
+    () => resolveInstalledViteProxyEntries(
+      ["@example/alpha", "@example/beta"].map((packageId) => ({
+        packageId,
+        packageMetadata: {
+          vite: {
+            proxy: {
+              "/socket.io": { target: "http://localhost:3000" }
+            }
+          }
+        }
+      }))
+    ),
+    /declared by both @example\/alpha and @example\/beta/u
+  );
+});
+
+test("resolveInstalledViteProxyEntries rejects malformed package proxy metadata", () => {
+  assert.throws(
+    () => resolveInstalledViteProxyEntries([
+      {
+        packageId: "@example/realtime",
+        packageMetadata: { vite: { proxy: { "/socket.io": { ws: "yes" } } } }
+      }
+    ], { proxyTarget: "http://localhost:3000" }),
+    /requires ws to be boolean/u
+  );
+});
+
 test("resolveLocalScopePackageIds reads @local packages from package.json", async () => {
   const tempRoot = await mkdtemp(path.join(os.tmpdir(), "jskit-client-bootstrap-local-scope-"));
   await writeJson(path.join(tempRoot, "package.json"), {
@@ -489,6 +553,57 @@ test("createJskitClientBootstrapPlugin resolves and loads virtual module", async
   }
 });
 
+test("createJskitClientBootstrapPlugin contributes installed package proxies without generated state", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "jskit-client-bootstrap-proxy-"));
+  const previousCwd = process.cwd();
+
+  try {
+    await declareInstalledPackages(tempRoot, { "@example/realtime": {} });
+    const packageRoot = path.join(tempRoot, "node_modules", "@example", "realtime");
+    await writePackageMetadata(packageRoot, {
+      packageId: "@example/realtime",
+      version: "1.0.0",
+      vite: {
+        proxy: {
+          "/socket.io": {
+            changeOrigin: true,
+            ws: true
+          }
+        }
+      }
+    });
+
+    process.chdir(tempRoot);
+    const plugin = createJskitClientBootstrapPlugin({
+      proxyTarget: "http://localhost:3000"
+    });
+    const config = await plugin.config({
+      server: {
+        proxy: {
+          "/api": {
+            target: "http://localhost:3000",
+            changeOrigin: true
+          }
+        }
+      }
+    });
+
+    assert.deepEqual(config.server.proxy, {
+      "/api": {
+        target: "http://localhost:3000",
+        changeOrigin: true
+      },
+      "/socket.io": {
+        target: "http://localhost:3000",
+        changeOrigin: true,
+        ws: true
+      }
+    });
+  } finally {
+    process.chdir(previousCwd);
+  }
+});
+
 test("createJskitClientBootstrapPlugin resolves multiple local packages before Vite dependency resolution", async () => {
   const tempRoot = await mkdtemp(path.join(os.tmpdir(), "jskit-client-bootstrap-plugin-local-resolution-"));
   const previousCwd = process.cwd();

package/internal/node/installedPackages.js

@@ -19,7 +19,8 @@ const JSKIT_PACKAGE_CONFIG_KEYS = Object.freeze([
   "mutations",
   "optionPolicies",
   "options",
-  "runtime"
+  "runtime",
+  "vite"
 ]);
 
 async function readJsonFile(filePath, fallback = {}) {

package/internal/node/installedPackages.test.js

@@ -39,7 +39,8 @@ test("createPackageMetadata accepts only the canonical package.json.jskit fields
     "mutations",
     "optionPolicies",
     "options",
-    "runtime"
+    "runtime",
+    "vite"
   ]);
   assert.throws(
     () => createPackageMetadata({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/kernel",
-  "version": "0.1.156",
+  "version": "0.1.158",
   "type": "module",
   "dependencies": {
     "json-rest-schema": "^1.0.17"

package/server/kernel/index.js

@@ -4,7 +4,7 @@ export {
   KernelError,
   ProviderNormalizationError,
   DuplicateProviderError,
-  ProviderDependencyError,
+  ProviderStartOrderError,
   ProviderLifecycleError
 } from "../../shared/runtime/kernelErrors.js";
 export { KernelCoreServiceProvider } from "./KernelCoreServiceProvider.js";

package/shared/runtime/application.js

@@ -1,7 +1,7 @@
 import { createContainer } from "./container.js";
 import {
   DuplicateProviderError,
-  ProviderDependencyError,
+  ProviderStartOrderError,
   ProviderLifecycleError,
   ProviderNormalizationError
 } from "./kernelErrors.js";
@@ -133,7 +133,7 @@ class Application {
 
       return {
         id: providerId,
-        dependsOn: normalizeStringArray(rawProvider.dependsOn || providerInstance.dependsOn),
+        startsAfter: normalizeStringArray(rawProvider.startsAfter ?? providerInstance.startsAfter),
         provider: providerInstance
       };
     }
@@ -147,7 +147,7 @@ class Application {
 
       return {
         id: providerId,
-        dependsOn: normalizeStringArray(provider.dependsOn || provider.constructor?.dependsOn),
+        startsAfter: normalizeStringArray(provider.startsAfter ?? provider.constructor?.startsAfter),
         provider
       };
     }
@@ -155,7 +155,7 @@ class Application {
     throw new ProviderNormalizationError("Provider entry must be a class or object instance.");
   }
 
-  sortProviderGraph(entries = []) {
+  sortProviderStartOrder(entries = []) {
     const byId = new Map(entries.map((entry) => [entry.id, entry]));
     const visited = new Set();
     const visiting = new Set();
@@ -166,17 +166,17 @@ class Application {
         return;
       }
       if (visiting.has(providerId)) {
-        throw new ProviderDependencyError(`Provider dependency cycle detected: ${[...lineage, providerId].join(" -> ")}`);
+        throw new ProviderStartOrderError(`Provider start-order cycle detected: ${[...lineage, providerId].join(" -> ")}`);
       }
 
       const entry = byId.get(providerId);
       if (!entry) {
-        throw new ProviderDependencyError(`Provider \"${lineage[lineage.length - 1] || "<unknown>"}\" depends on missing provider \"${providerId}\".`);
+        throw new ProviderStartOrderError(`Provider \"${lineage[lineage.length - 1] || "<unknown>"}\" starts after missing provider \"${providerId}\".`);
       }
 
       visiting.add(providerId);
-      for (const dependencyId of entry.dependsOn) {
-        visit(dependencyId, [...lineage, providerId]);
+      for (const earlierProviderId of entry.startsAfter) {
+        visit(earlierProviderId, [...lineage, providerId]);
       }
       visiting.delete(providerId);
       visited.add(providerId);
@@ -192,7 +192,7 @@ class Application {
 
   configureProviders(providers = []) {
     const normalized = this.normalizeProviderEntries(providers);
-    const ordered = this.sortProviderGraph(normalized);
+    const ordered = this.sortProviderStartOrder(normalized);
 
     this.providerEntries = ordered;
     this.diagnostics.providerOrder = ordered.map((entry) => entry.id);
@@ -288,7 +288,7 @@ function createApplication(options = {}) {
   return new Application(options);
 }
 
-function createProviderClass({ id, dependsOn = [], register = null, boot = null, shutdown = null } = {}) {
+function createProviderClass({ id, startsAfter = [], register = null, boot = null, shutdown = null } = {}) {
   const providerId = normalizeText(id);
   if (!providerId) {
     throw new ProviderNormalizationError("createProviderClass requires id.");
@@ -297,7 +297,7 @@ function createProviderClass({ id, dependsOn = [], register = null, boot = null,
   class DynamicProvider extends ServiceProvider {
     static id = providerId;
 
-    static dependsOn = normalizeStringArray(dependsOn);
+    static startsAfter = normalizeStringArray(startsAfter);
 
     async register(app) {
       if (typeof register === "function") {

package/shared/runtime/index.js

@@ -13,6 +13,6 @@ export {
   KernelError,
   ProviderNormalizationError,
   DuplicateProviderError,
-  ProviderDependencyError,
+  ProviderStartOrderError,
   ProviderLifecycleError
 } from "./kernelErrors.js";

package/shared/runtime/kernelErrors.js

@@ -13,13 +13,13 @@ class KernelError extends Error {
 
 class ProviderNormalizationError extends KernelError {}
 class DuplicateProviderError extends KernelError {}
-class ProviderDependencyError extends KernelError {}
+class ProviderStartOrderError extends KernelError {}
 class ProviderLifecycleError extends KernelError {}
 
 export {
   KernelError,
   ProviderNormalizationError,
   DuplicateProviderError,
-  ProviderDependencyError,
+  ProviderStartOrderError,
   ProviderLifecycleError
 };

package/shared/runtime/kernelErrors.test.js

@@ -6,7 +6,8 @@ import path from "node:path";
 import process from "node:process";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
-import { KernelError } from "./kernelErrors.js";
+import { Application, createProviderClass } from "./application.js";
+import { KernelError, ProviderStartOrderError } from "./kernelErrors.js";
 
 const APPLICATION_PATH = fileURLToPath(new URL("./application.js", import.meta.url));
 
@@ -22,6 +23,69 @@ test("KernelError preserves structured details while exposing the standard cause
   assert.equal(error.details.providerId, "example.provider");
 });
 
+test("startsAfter orders provider registration, boot, and shutdown", async () => {
+  const calls = [];
+  const EarlierProvider = createProviderClass({
+    id: "example.earlier",
+    register() {
+      calls.push("register:earlier");
+    },
+    boot() {
+      calls.push("boot:earlier");
+    },
+    shutdown() {
+      calls.push("shutdown:earlier");
+    }
+  });
+  const LaterProvider = createProviderClass({
+    id: "example.later",
+    startsAfter: ["example.earlier"],
+    register() {
+      calls.push("register:later");
+    },
+    boot() {
+      calls.push("boot:later");
+    },
+    shutdown() {
+      calls.push("shutdown:later");
+    }
+  });
+
+  const app = new Application();
+  await app.start({ providers: [LaterProvider, EarlierProvider] });
+  await app.shutdown();
+
+  assert.deepEqual(calls, [
+    "register:earlier",
+    "register:later",
+    "boot:earlier",
+    "boot:later",
+    "shutdown:later",
+    "shutdown:earlier"
+  ]);
+});
+
+test("startsAfter rejects missing providers and start-order cycles", () => {
+  const missingApp = new Application();
+  assert.throws(
+    () => missingApp.configureProviders([{ id: "example.later", startsAfter: ["example.missing"] }]),
+    (error) =>
+      error instanceof ProviderStartOrderError &&
+      /starts after missing provider "example\.missing"/u.test(error.message)
+  );
+
+  const cycleApp = new Application();
+  assert.throws(
+    () => cycleApp.configureProviders([
+      { id: "example.alpha", startsAfter: ["example.beta"] },
+      { id: "example.beta", startsAfter: ["example.alpha"] }
+    ]),
+    (error) =>
+      error instanceof ProviderStartOrderError &&
+      /Provider start-order cycle detected/u.test(error.message)
+  );
+});
+
 test("provider lifecycle failures expose their cause in Node test output", async (context) => {
   const fixtureRoot = await mkdtemp(path.join(tmpdir(), "jskit-kernel-error-"));
   context.after(() => rm(fixtureRoot, { recursive: true, force: true }));