@jskit-ai/kernel 0.1.66 → 0.1.67

package/client/moduleBootstrap.js

@@ -483,6 +483,7 @@ function createClientRuntimeApp({
   profile = "client",
   app,
   pinia = null,
+  queryClient = null,
   router,
   env,
   logger,
@@ -498,6 +499,7 @@ function createClientRuntimeApp({
   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());
@@ -510,6 +512,7 @@ async function bootClientModules({
   clientModules = [],
   app,
   pinia = null,
+  queryClient = null,
   router,
   surfaceRuntime,
   surfaceMode,
@@ -529,6 +532,7 @@ async function bootClientModules({
     profile: String(surfaceRuntime.normalizeSurfaceMode(surfaceMode) || "client"),
     app,
     pinia,
+    queryClient,
     router,
     env,
     logger: log,

package/client/moduleBootstrap.test.js

@@ -113,6 +113,7 @@ test("bootClientModules registers descriptor and clientRoutes with providers onl
   const events = [];
   const loginComponent = {};
   const pinia = { id: "pinia-instance" };
+  const queryClient = { id: "query-client-instance" };
   const implicitPinia = { id: "implicit-vue-global-pinia" };
   class ExampleClientProvider {
     static id = "example.client";
@@ -120,6 +121,7 @@ test("bootClientModules registers descriptor and clientRoutes with providers onl
       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"));
     }
     boot() {
       events.push("boot");
@@ -190,6 +192,7 @@ test("bootClientModules registers descriptor and clientRoutes with providers onl
       }
     },
     pinia,
+    queryClient,
     router,
     surfaceRuntime,
     surfaceMode: "all",
@@ -206,6 +209,7 @@ test("bootClientModules registers descriptor and clientRoutes with providers onl
   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);
 });
 

package/client/shellBootstrap.js

@@ -109,6 +109,7 @@ async function bootstrapClientShellApp({
   appConfig = {},
   appPlugins = [],
   pinia = null,
+  queryClient = null,
   router,
   bootClientModules,
   surfaceRuntime,
@@ -161,6 +162,7 @@ async function bootstrapClientShellApp({
   const clientBootstrap = await bootClientModules({
     app,
     pinia,
+    queryClient,
     router,
     surfaceRuntime,
     surfaceMode,

package/client/shellBootstrap.test.js

@@ -86,6 +86,7 @@ test("bootstrapClientShellApp boots modules, reinstalls fallback route, and moun
   const surfaceRuntime = createSurfaceRuntimeFixture();
   const plugin = { name: "vuetify-like-plugin" };
   const pinia = { id: "pinia-instance" };
+  const queryClient = { id: "query-client-instance" };
   const fallbackRoute = {
     name: "not-found",
     path: "/:pathMatch(.*)*",
@@ -142,11 +143,13 @@ test("bootstrapClientShellApp boots modules, reinstalls fallback route, and moun
     },
     appPlugins: [plugin],
     pinia,
+    queryClient,
     router,
     bootClientModules: async (context) => {
       calls.push("bootClientModules");
       assert.equal(context.app, app);
       assert.equal(context.pinia, pinia);
+      assert.equal(context.queryClient, queryClient);
       assert.equal(context.router, router);
       assert.equal(typeof context.logger.debug, "function");
       return {

package/client/vite/clientBootstrapPlugin.js

@@ -14,6 +14,7 @@ const CLIENT_BOOTSTRAP_VIRTUAL_ID = "virtual:jskit-client-bootstrap";
 const CLIENT_BOOTSTRAP_RESOLVED_ID = `\0${CLIENT_BOOTSTRAP_VIRTUAL_ID}`;
 const CLIENT_RUNTIME_DEDUPE_SPECIFIERS = Object.freeze([
   "@tanstack/vue-query",
+  "pinia",
   "vue",
   "vue-router",
   "vuetify"

package/client/vite/clientBootstrapPlugin.test.js

@@ -404,7 +404,7 @@ test("createJskitClientBootstrapPlugin config excludes installed client package
     assert.equal(Array.isArray(result?.optimizeDeps?.exclude), true);
     assert.deepEqual(result.optimizeDeps.exclude, ["already/excluded"]);
     assert.deepEqual(result.optimizeDeps.include, ["@example/has-client/client", "a"]);
-    assert.deepEqual(result.resolve.dedupe, ["@tanstack/vue-query", "vue", "vue-router", "vuetify"]);
+    assert.deepEqual(result.resolve.dedupe, ["@tanstack/vue-query", "pinia", "vue", "vue-router", "vuetify"]);
   } finally {
     process.chdir(previousCwd);
   }
@@ -469,7 +469,7 @@ test("createJskitClientBootstrapPlugin config excludes local package roots and c
       "@example/local-client/shared"
     ]);
     assert.deepEqual(result.optimizeDeps.include, ["@example/remote-client/client", "mime-match"]);
-    assert.deepEqual(result.resolve.dedupe, ["@tanstack/vue-query", "vue", "vue-router", "vuetify"]);
+    assert.deepEqual(result.resolve.dedupe, ["@tanstack/vue-query", "pinia", "vue", "vue-router", "vuetify"]);
   } finally {
     process.chdir(previousCwd);
   }
@@ -500,7 +500,7 @@ test("createJskitClientBootstrapPlugin config preserves user resolve fields and
     assert.deepEqual(result.resolve.alias, {
       "@": "/tmp/app/src"
     });
-    assert.deepEqual(result.resolve.dedupe, ["@tanstack/vue-query", "custom-lib", "vue", "vue-router", "vuetify"]);
+    assert.deepEqual(result.resolve.dedupe, ["@tanstack/vue-query", "custom-lib", "pinia", "vue", "vue-router", "vuetify"]);
   } finally {
     process.chdir(previousCwd);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/kernel",
-  "version": "0.1.66",
+  "version": "0.1.67",
   "type": "module",
   "dependencies": {
     "json-rest-schema": "1.x.x"
@@ -42,6 +42,7 @@
     "./shared/support/crudListFilters": "./shared/support/crudListFilters.js",
     "./shared/support/crudFieldContract": "./shared/support/crudFieldContract.js",
     "./shared/support/crudLookup": "./shared/support/crudLookup.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",

package/server/http/lib/httpRuntime.js

@@ -1,5 +1,5 @@
 import { normalizeObject } from "../../../shared/support/normalize.js";
-import { ensureApiErrorHandling } from "../../runtime/fastifyBootstrap.js";
+import { ensureApiErrorHandling, registerBodylessContentTypeNormalizer } from "../../runtime/fastifyBootstrap.js";
 import { resolveDefaultSurfaceId } from "../../support/appConfig.js";
 import { RouteRegistrationError } from "./errors.js";
 import { createRouter } from "./router.js";
@@ -25,6 +25,8 @@ function registerHttpRuntime(app, options = {}) {
     defaultSurfaceId: routeRegistrationOptions.requestActionDefaultSurface
   });
 
+  registerBodylessContentTypeNormalizer(fastify);
+
   if (autoRegisterApiErrorHandling !== false) {
     ensureApiErrorHandling(app, {
       fastifyToken,

package/server/http/lib/kernel.test.js

@@ -14,9 +14,13 @@ function createFastifyStub() {
     setErrorHandlerCalls: 0,
     errorHandler: null,
     contentTypeParsers: new Map(),
+    hooks: {},
     route(definition) {
       routes.push(definition);
     },
+    addHook(name, handler) {
+      this.hooks[name] = handler;
+    },
     setErrorHandler(handler) {
       this.errorHandler = handler;
       this.setErrorHandlerCalls += 1;

package/server/runtime/fastifyBootstrap.js

@@ -5,6 +5,7 @@ import { resolveDefaultSurfaceId } from "../support/appConfig.js";
 
 const JSON_API_CONTENT_TYPE = "application/vnd.api+json";
 const JSON_API_CONTENT_TYPE_PARSER_MARKER = Symbol.for("jskit.fastify.jsonApiContentTypeParserRegistered");
+const BODYLESS_CONTENT_TYPE_NORMALIZER_MARKER = Symbol.for("jskit.fastify.bodylessContentTypeNormalizerRegistered");
 
 function resolveLoggerLevel({ configuredLevel = "", nodeEnv = "development", allowedLevels = [] } = {}) {
   const normalizedConfiguredLevel = String(configuredLevel || "")
@@ -83,6 +84,64 @@ function registerJsonApiContentTypeParser(fastify) {
   return true;
 }
 
+function hasHeaderValue(headers = {}, key = "") {
+  return String(headers?.[key] ?? "").trim().length > 0;
+}
+
+function hasRequestBody(headers = {}) {
+  const transferEncoding = String(headers?.["transfer-encoding"] ?? "").trim();
+  if (transferEncoding) {
+    return true;
+  }
+
+  const contentLengthHeader = String(headers?.["content-length"] ?? "").trim();
+  if (!contentLengthHeader) {
+    return false;
+  }
+
+  const contentLength = Number(contentLengthHeader);
+  if (!Number.isFinite(contentLength)) {
+    return true;
+  }
+
+  return contentLength > 0;
+}
+
+function normalizeBodylessContentTypeHeader(request = null) {
+  const headers = request?.headers;
+  if (!headers || typeof headers !== "object" || Array.isArray(headers)) {
+    return false;
+  }
+
+  if (!hasHeaderValue(headers, "content-type") && !hasHeaderValue(headers, "Content-Type")) {
+    return false;
+  }
+
+  if (hasRequestBody(headers)) {
+    return false;
+  }
+
+  delete headers["content-type"];
+  delete headers["Content-Type"];
+  return true;
+}
+
+function registerBodylessContentTypeNormalizer(fastify) {
+  if (!fastify || typeof fastify.addHook !== "function") {
+    throw new TypeError("registerBodylessContentTypeNormalizer requires a Fastify instance.");
+  }
+
+  if (fastify[BODYLESS_CONTENT_TYPE_NORMALIZER_MARKER]) {
+    return false;
+  }
+
+  fastify.addHook("onRequest", async (request) => {
+    normalizeBodylessContentTypeHeader(request);
+  });
+  fastify[BODYLESS_CONTENT_TYPE_NORMALIZER_MARKER] = true;
+  return true;
+}
+
 function registerRequestLoggingHooks(
   app,
   {
@@ -483,6 +542,8 @@ export {
   resolveLoggerLevel,
   createFastifyLoggerOptions,
   registerJsonApiContentTypeParser,
+  normalizeBodylessContentTypeHeader,
+  registerBodylessContentTypeNormalizer,
   registerRequestLoggingHooks,
   registerApiErrorHandler,
   ensureApiErrorHandling,

package/server/runtime/fastifyBootstrap.test.js

@@ -2,7 +2,13 @@ import assert from "node:assert/strict";
 import test from "node:test";
 
 import { AppError, isAppError } from "./errors.js";
-import { registerApiErrorHandler, registerJsonApiContentTypeParser, registerRequestLoggingHooks } from "./fastifyBootstrap.js";
+import {
+  normalizeBodylessContentTypeHeader,
+  registerApiErrorHandler,
+  registerBodylessContentTypeNormalizer,
+  registerJsonApiContentTypeParser,
+  registerRequestLoggingHooks
+} from "./fastifyBootstrap.js";
 
 function createFastifyStub() {
   return {
@@ -275,6 +281,46 @@ test("registerJsonApiContentTypeParser installs the JSON:API media type parser o
   assert.equal(fastify.contentTypeParsers.size, 1);
 });
 
+test("normalizeBodylessContentTypeHeader strips meaningless content type from empty requests", () => {
+  const request = {
+    headers: {
+      "content-type": "text/plain;charset=UTF-8"
+    }
+  };
+
+  assert.equal(normalizeBodylessContentTypeHeader(request), true);
+  assert.deepEqual(request.headers, {});
+});
+
+test("normalizeBodylessContentTypeHeader keeps content type when a body is declared", () => {
+  const request = {
+    headers: {
+      "content-type": "text/plain;charset=UTF-8",
+      "content-length": "12"
+    }
+  };
+
+  assert.equal(normalizeBodylessContentTypeHeader(request), false);
+  assert.equal(request.headers["content-type"], "text/plain;charset=UTF-8");
+});
+
+test("registerBodylessContentTypeNormalizer installs the request hook once", async () => {
+  const fastify = createFastifyStub();
+  assert.equal(registerBodylessContentTypeNormalizer(fastify), true);
+  assert.equal(registerBodylessContentTypeNormalizer(fastify), false);
+
+  const request = {
+    headers: {
+      "content-type": "text/plain;charset=UTF-8",
+      "content-length": "0"
+    }
+  };
+  await fastify.hooks.onRequest(request);
+  assert.deepEqual(request.headers, {
+    "content-length": "0"
+  });
+});
+
 test("registerRequestLoggingHooks uses configured default surface when getSurface is absent", async () => {
   const fastify = createFastifyStub();
   let loggedPayload = null;

package/server/support/appConfigFiles.js

@@ -1,6 +1,7 @@
 import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
 import { fileExists } from "../../internal/node/fileSystem.js";
+import { importFreshModuleFromAbsolutePath } from "./importFreshModuleFromAbsolutePath.js";
 
 const PUBLIC_CONFIG_RELATIVE_PATH = "config/public.js";
 const SERVER_CONFIG_RELATIVE_PATH = "config/server.js";
@@ -35,7 +36,7 @@ async function loadConfigModuleAtPath(absolutePath) {
     return {};
   }
 
-  const loadedModule = await import(pathToFileURL(absolutePath).href);
+  const loadedModule = await importFreshModuleFromAbsolutePath(absolutePath);
   return normalizeConfigObject(loadedModule?.config);
 }
 

package/server/support/appConfigFiles.test.js

@@ -47,6 +47,21 @@ test("loadAppConfigFromAppRoot merges public and server config", async () => {
   assert.equal(Object.isFrozen(loaded), true);
 });
 
+test("loadAppConfigFromAppRoot re-reads config changes within the same process", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "kernel-app-config-"));
+  const appRoot = path.join(tempRoot, "app");
+  const publicConfigPath = path.join(appRoot, "config", "public.js");
+  await mkdir(path.dirname(publicConfigPath), { recursive: true });
+  await writeFile(publicConfigPath, "export const config = { mobile: { enabled: false } };", "utf8");
+
+  const firstLoaded = await loadAppConfigFromAppRoot({ appRoot });
+  await writeFile(publicConfigPath, "export const config = { mobile: { enabled: true } };", "utf8");
+  const secondLoaded = await loadAppConfigFromAppRoot({ appRoot });
+
+  assert.equal(firstLoaded.mobile.enabled, false);
+  assert.equal(secondLoaded.mobile.enabled, true);
+});
+
 test("loadAppConfigFromAppRoot requires an explicit appRoot", async () => {
   await assert.rejects(
     loadAppConfigFromAppRoot({ appRoot: "" }),

package/server/support/index.js

@@ -17,6 +17,7 @@ export {
 } from "./pageTargets.js";
 export {
   discoverPlacementTopologyFromApp,
+  discoverShellOutletSourcePathsFromApp,
   discoverShellOutletTargetsFromApp,
   resolveSemanticPlacementTargetFromApp,
   resolveShellOutletPlacementTargetFromApp

package/server/support/pageTargets.js

@@ -373,8 +373,8 @@ function buildAncestorRouteContexts(pageTarget = {}) {
 
   for (let visiblePrefixLength = visibleRouteSegments.length - 1; visiblePrefixLength >= 1; visiblePrefixLength -= 1) {
     const parentVisibleSegments = visibleRouteSegments.slice(0, visiblePrefixLength);
-      const actualRouteSegments = [];
-      let collectedVisibleSegments = 0;
+    const actualRouteSegments = [];
+    let collectedVisibleSegments = 0;
 
     for (const segment of routeSegments) {
       actualRouteSegments.push(segment);
@@ -585,7 +585,8 @@ function topologyPlacementTargetsConcreteOutlet(placement = {}, target = "") {
 async function resolveSemanticPlacementTargetForConcreteOutlet({
   appRoot,
   concreteTarget = "",
-  surface = ""
+  surface = "",
+  context = "page target"
 } = {}) {
   const normalizedConcreteTarget = normalizeShellOutletTargetId(concreteTarget);
   if (!normalizedConcreteTarget) {
@@ -595,16 +596,31 @@ async function resolveSemanticPlacementTargetForConcreteOutlet({
   const topology = await discoverPlacementTopologyFromApp({ appRoot });
   const owner = resolveConcreteTargetOwner(normalizedConcreteTarget);
   const normalizedSurface = normalizeSurfaceId(surface);
-  return (Array.isArray(topology.placements) ? topology.placements : []).find((placement) => {
+  const candidates = (Array.isArray(topology.placements) ? topology.placements : []).filter((placement) => {
     if (!topologyPlacementTargetsConcreteOutlet(placement, normalizedConcreteTarget)) {
       return false;
     }
-    if (placement.owner && placement.owner !== owner) {
-      return false;
-    }
     const surfaces = Array.isArray(placement.surfaces) ? placement.surfaces : ["*"];
     return !normalizedSurface || surfaces.includes("*") || surfaces.includes(normalizedSurface);
-  }) || null;
+  });
+
+  const exactOwnerMatches = candidates.filter((placement) => placement.owner && placement.owner === owner);
+  const globalMatches = candidates.filter((placement) => !placement.owner);
+  const selectedMatches = exactOwnerMatches.length > 0 ? exactOwnerMatches : globalMatches;
+  if (selectedMatches.length < 1) {
+    return null;
+  }
+  if (selectedMatches.length === 1) {
+    return selectedMatches[0];
+  }
+
+  const targetLabels = selectedMatches.map((placement) =>
+    placement.owner ? `${placement.id} [owner:${placement.owner}]` : placement.id
+  );
+  throw new Error(
+    `${context} found multiple semantic placements mapped to concrete outlet "${normalizedConcreteTarget}": ` +
+    `${targetLabels.join(", ")}. Pass --link-placement or make the topology mapping unambiguous.`
+  );
 }
 
 function resolveRelativeLinkToFromParent(pageTarget = {}, parentHost = null) {

package/server/support/pageTargets.test.js

@@ -388,6 +388,149 @@ test("resolvePageLinkTargetDetails prefers an outlet-declared default link token
   });
 });
 
+test("resolvePageLinkTargetDetails infers owner-scoped placement for sibling file-route children", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    home: { id: "home", pagesRoot: "home", enabled: true }
+  }
+};
+`
+    );
+    await writePlacementTopology(appRoot, [
+      renderTopologyEntry({
+        id: "page.section-nav",
+        owner: "home-settings",
+        surfaces: ["home"],
+        outlet: "home-settings:primary-menu",
+        linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+      })
+    ]);
+    await writeFileInApp(
+      appRoot,
+      "src/pages/home/settings.vue",
+      `<template>
+  <section>
+    <ShellOutlet target="home-settings:primary-menu" />
+    <RouterView />
+  </section>
+</template>
+`
+    );
+
+    const details = await resolvePageLinkTargetDetails({
+      appRoot,
+      targetFile: "home/settings/profile.vue",
+      context: "page target"
+    });
+
+    assert.equal(details.parentHost?.id, "home-settings:primary-menu");
+    assert.equal(details.placementTarget.id, "page.section-nav");
+    assert.equal(details.placementTarget.owner, "home-settings");
+  });
+});
+
+test("resolvePageLinkTargetDetails prefers owner-scoped topology over a global mapping for the same concrete outlet", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    home: { id: "home", pagesRoot: "home", enabled: true }
+  }
+};
+`
+    );
+    await writePlacementTopology(appRoot, [
+      renderTopologyEntry({
+        id: "page.section-nav",
+        surfaces: ["home"],
+        outlet: "home-settings:primary-menu",
+        linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+      }),
+      renderTopologyEntry({
+        id: "page.section-nav",
+        owner: "home-settings",
+        surfaces: ["home"],
+        outlet: "home-settings:primary-menu",
+        linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+      })
+    ]);
+    await writeFileInApp(
+      appRoot,
+      "src/pages/home/settings.vue",
+      `<template>
+  <section>
+    <ShellOutlet target="home-settings:primary-menu" />
+    <RouterView />
+  </section>
+</template>
+`
+    );
+
+    const details = await resolvePageLinkTargetDetails({
+      appRoot,
+      targetFile: "home/settings/profile.vue",
+      context: "page target"
+    });
+
+    assert.equal(details.placementTarget.id, "page.section-nav");
+    assert.equal(details.placementTarget.owner, "home-settings");
+  });
+});
+
+test("resolvePageLinkTargetDetails rejects ambiguous semantic mappings for the same owner outlet", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    home: { id: "home", pagesRoot: "home", enabled: true }
+  }
+};
+`
+    );
+    await writePlacementTopology(appRoot, [
+      renderTopologyEntry({
+        id: "page.section-nav",
+        owner: "home-settings",
+        surfaces: ["home"],
+        outlet: "home-settings:primary-menu",
+        linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+      }),
+      renderTopologyEntry({
+        id: "page.actions",
+        owner: "home-settings",
+        surfaces: ["home"],
+        outlet: "home-settings:primary-menu",
+        linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+      })
+    ]);
+    await writeFileInApp(
+      appRoot,
+      "src/pages/home/settings.vue",
+      `<template>
+  <section>
+    <ShellOutlet target="home-settings:primary-menu" />
+    <RouterView />
+  </section>
+</template>
+`
+    );
+
+    await assert.rejects(
+      resolvePageLinkTargetDetails({
+        appRoot,
+        targetFile: "home/settings/profile.vue",
+        context: "page target"
+      }),
+      /found multiple semantic placements mapped to concrete outlet "home-settings:primary-menu": page\.actions \[owner:home-settings\], page\.section-nav \[owner:home-settings\]/
+    );
+  });
+});
+
 test("resolvePageLinkTargetDetails inherits a file-route parent subpages host", async () => {
   await withTempApp(async (appRoot) => {
     await writeConfig(