@jskit-ai/kernel 0.1.119 → 0.1.121

package/client/vite/clientBootstrapPlugin.js

@@ -19,6 +19,7 @@ const CLIENT_RUNTIME_DEDUPE_SPECIFIERS = Object.freeze([
   "vue-router",
   "vuetify"
 ]);
+const LOCAL_PACKAGE_SOURCE_TYPES = new Set(["local-package", "app-local-package"]);
 
 function isLocalScopePackageId(value) {
   return String(value || "").trim().startsWith("@local/");
@@ -38,6 +39,93 @@ function hasClientExport(packageJson) {
   return Boolean(exportsMap["./client"]);
 }
 
+function isPathInsideRoot(rootPath, candidatePath) {
+  const relativePath = path.relative(rootPath, candidatePath);
+  return (
+    relativePath === "" ||
+    (!relativePath.startsWith(`..${path.sep}`) && relativePath !== ".." && !path.isAbsolute(relativePath))
+  );
+}
+
+/**
+ * Generated apps intentionally preserve package symlinks, so a bare import from an editable local
+ * package would otherwise keep its node_modules path. optimizeDeps.exclude only prevents prebundling;
+ * Vite can still append its dependency-wide ?v hash and serve that source as one-year immutable.
+ * That hash does not change when local source changes, which lets a browser reuse stale client code
+ * even after Vite restarts.
+ *
+ * Build this table from every lock-classified local package, not only packages with a ./client export.
+ * Resolving only the bootstrap entry is insufficient: a local client can use bare imports from another
+ * local package's root, shared entry, or exported subpath and accidentally re-enter node_modules caching.
+ */
+async function resolveLocalPackageSources({ appRoot, lockPath }) {
+  const absoluteLockPath = path.resolve(appRoot, lockPath);
+  const lockPayload = await readJsonFile(absoluteLockPath, {});
+  const installedPackages = normalizeObject(lockPayload.installedPackages);
+  const packages = [];
+
+  for (const packageId of sortStrings(Object.keys(installedPackages))) {
+    const installedPackageState = normalizeObject(installedPackages[packageId]);
+    const source = normalizeObject(installedPackageState.source);
+    const sourceType = String(source.type || "").trim().toLowerCase();
+    const packagePath = String(source.packagePath || "").trim();
+    if (!LOCAL_PACKAGE_SOURCE_TYPES.has(sourceType) || !packagePath) {
+      continue;
+    }
+
+    packages.push(
+      Object.freeze({
+        packageId,
+        installedPackageRoot: path.resolve(appRoot, "node_modules", ...packageId.split("/")),
+        sourcePackageRoot: path.resolve(appRoot, packagePath)
+      })
+    );
+  }
+
+  return Object.freeze(packages);
+}
+
+function splitSpecifierSuffix(source) {
+  const normalizedSource = String(source || "");
+  const queryIndex = normalizedSource.indexOf("?");
+  const hashIndex = normalizedSource.indexOf("#");
+  const suffixIndexes = [queryIndex, hashIndex].filter((index) => index >= 0);
+  const suffixIndex = suffixIndexes.length > 0 ? Math.min(...suffixIndexes) : -1;
+  if (suffixIndex < 0) {
+    return [normalizedSource, ""];
+  }
+  return [normalizedSource.slice(0, suffixIndex), normalizedSource.slice(suffixIndex)];
+}
+
+function resolveLocalPackageForSpecifier(source, localPackages = []) {
+  const [specifier] = splitSpecifierSuffix(source);
+  return (
+    (Array.isArray(localPackages) ? localPackages : []).find(
+      (entry) => specifier === entry.packageId || specifier.startsWith(`${entry.packageId}/`)
+    ) || null
+  );
+}
+
+function resolveCanonicalLocalPackageId(resolvedId, localPackage) {
+  const [resolvedPath, suffix] = splitSpecifierSuffix(resolvedId);
+  if (!resolvedPath || resolvedPath.startsWith("\0")) {
+    return "";
+  }
+
+  if (isPathInsideRoot(localPackage.sourcePackageRoot, resolvedPath)) {
+    return `${resolvedPath}${suffix}`;
+  }
+  if (!isPathInsideRoot(localPackage.installedPackageRoot, resolvedPath)) {
+    return "";
+  }
+
+  const packageRelativePath = path.relative(localPackage.installedPackageRoot, resolvedPath);
+  const canonicalPath = path.resolve(localPackage.sourcePackageRoot, packageRelativePath);
+  return isPathInsideRoot(localPackage.sourcePackageRoot, canonicalPath)
+    ? `${canonicalPath}${suffix}`
+    : "";
+}
+
 async function resolveInstalledClientModules({ appRoot, lockPath }) {
   const absoluteLockPath = path.resolve(appRoot, lockPath);
   const lockPayload = await readJsonFile(absoluteLockPath, {});
@@ -160,11 +248,10 @@ export { installedClientModules, bootInstalledClientModules };
 // Vite-only: this Set-based source-type filter exists solely to drive optimizeDeps include/exclude decisions.
 function resolveClientOptimizeExcludeSpecifiers(clientModules = []) {
   const moduleDescriptors = normalizeClientModuleDescriptors(clientModules);
-  const localSourceTypes = new Set(["local-package", "app-local-package"]);
   return sortStrings(
     [
       ...moduleDescriptors
-        .filter((entry) => localSourceTypes.has(entry.sourceType))
+        .filter((entry) => LOCAL_PACKAGE_SOURCE_TYPES.has(entry.sourceType))
         .flatMap((entry) => [entry.packageId, `${entry.packageId}/shared`, `${entry.packageId}/client`]),
       ...moduleDescriptors.flatMap((entry) => entry.descriptorClientOptimizeExcludeSpecifiers || [])
     ]
@@ -173,12 +260,11 @@ function resolveClientOptimizeExcludeSpecifiers(clientModules = []) {
 
 function resolveClientOptimizeIncludeSpecifiers(clientModules = [], excludeSpecifiers = []) {
   const moduleDescriptors = normalizeClientModuleDescriptors(clientModules);
-  const localSourceTypes = new Set(["local-package", "app-local-package"]);
   const excluded = new Set(sortStrings(excludeSpecifiers));
   return sortStrings(
     [
       ...moduleDescriptors
-      .filter((entry) => !localSourceTypes.has(entry.sourceType))
+      .filter((entry) => !LOCAL_PACKAGE_SOURCE_TYPES.has(entry.sourceType))
       .map((entry) => `${entry.packageId}/client`),
       ...moduleDescriptors.flatMap((entry) => entry.descriptorClientOptimizeIncludeSpecifiers || [])
     ].filter((specifier) => !excluded.has(specifier))
@@ -198,10 +284,16 @@ function resolveClientRuntimeDedupeSpecifiers(userResolveConfig = {}) {
 }
 
 function createJskitClientBootstrapPlugin({ lockPath = ".jskit/lock.json" } = {}) {
+  let appRoot = process.cwd();
+  let localPackages = Object.freeze([]);
+  let resolvePackageSpecifier = null;
+
   return {
     name: "jskit-client-bootstrap",
+    // This must run before Vite's normal package resolver turns a local bare import into node_modules.
+    enforce: "pre",
     async config(userConfig = {}) {
-      const appRoot = process.cwd();
+      appRoot = process.cwd();
       const clientModules = await resolveInstalledClientModules({
         appRoot,
         lockPath
@@ -210,6 +302,11 @@ function createJskitClientBootstrapPlugin({ lockPath = ".jskit/lock.json" } = {}
         appRoot,
         lockPath
       });
+      const userResolve = normalizeObject(userConfig.resolve);
+      localPackages = await resolveLocalPackageSources({
+        appRoot,
+        lockPath
+      });
       const clientExcludeSpecifiers = resolveClientOptimizeExcludeSpecifiers(clientModules);
       const localScopeExcludeSpecifiers = resolveLocalScopeOptimizeExcludeSpecifiers(localScopePackageIds);
       const userOptimizeDeps = normalizeObject(userConfig.optimizeDeps);
@@ -218,7 +315,6 @@ function createJskitClientBootstrapPlugin({ lockPath = ".jskit/lock.json" } = {}
       const exclude = sortStrings([...userExclude, ...clientExcludeSpecifiers, ...localScopeExcludeSpecifiers]);
       const clientIncludeSpecifiers = resolveClientOptimizeIncludeSpecifiers(clientModules, exclude);
       const include = sortStrings([...userInclude, ...clientIncludeSpecifiers].filter((specifier) => !exclude.includes(specifier)));
-      const userResolve = normalizeObject(userConfig.resolve);
       const dedupe = resolveClientRuntimeDedupeSpecifiers(userResolve);
 
       return {
@@ -233,11 +329,34 @@ function createJskitClientBootstrapPlugin({ lockPath = ".jskit/lock.json" } = {}
         }
       };
     },
-    resolveId(source) {
+    configResolved(resolvedConfig) {
+      // Do not use `this.resolve()` for this lookup. That re-enters Vite's live plugin chain, where
+      // the dependency optimizer can turn an unlisted local subpath into node_modules/.vite (or add
+      // its dependency ?v hash) before JSKIT sees the selected file. The config resolver applies the
+      // app's aliases, exports conditions, and wildcard rules without registering an optimized dep.
+      resolvePackageSpecifier = resolvedConfig.createResolver({ scan: true });
+    },
+    async resolveId(source, importer) {
       if (source === CLIENT_BOOTSTRAP_VIRTUAL_ID) {
         return CLIENT_BOOTSTRAP_RESOLVED_ID;
       }
-      return null;
+      const localPackage = resolveLocalPackageForSpecifier(source, localPackages);
+      if (!localPackage) {
+        return null;
+      }
+
+      const resolvedId = await resolvePackageSpecifier?.(source, importer);
+      if (!resolvedId) {
+        return null;
+      }
+
+      const canonicalId = resolveCanonicalLocalPackageId(resolvedId, localPackage);
+      if (!canonicalId) {
+        return resolvedId;
+      }
+
+      // The canonical absolute path receives editable-source watching and no-cache headers.
+      return canonicalId;
     },
     async load(id) {
       if (id !== CLIENT_BOOTSTRAP_RESOLVED_ID) {
@@ -245,7 +364,7 @@ function createJskitClientBootstrapPlugin({ lockPath = ".jskit/lock.json" } = {}
       }
 
       const clientModules = await resolveInstalledClientModules({
-        appRoot: process.cwd(),
+        appRoot,
         lockPath
       });
 
@@ -260,6 +379,9 @@ export {
   createVirtualModuleSource,
   resolveClientOptimizeIncludeSpecifiers,
   resolveClientOptimizeExcludeSpecifiers,
+  resolveCanonicalLocalPackageId,
+  resolveLocalPackageForSpecifier,
+  resolveLocalPackageSources,
   resolveLocalScopeOptimizeExcludeSpecifiers,
   resolveInstalledClientPackageIds,
   resolveLocalScopePackageIds,

package/client/vite/clientBootstrapPlugin.test.js

@@ -8,6 +8,9 @@ import {
   CLIENT_BOOTSTRAP_VIRTUAL_ID,
   createJskitClientBootstrapPlugin,
   createVirtualModuleSource,
+  resolveCanonicalLocalPackageId,
+  resolveLocalPackageForSpecifier,
+  resolveLocalPackageSources,
   resolveLocalScopeOptimizeExcludeSpecifiers,
   resolveClientOptimizeIncludeSpecifiers,
   resolveClientOptimizeExcludeSpecifiers,
@@ -24,6 +27,85 @@ async function writeDescriptor(filePath, descriptor) {
   await writeFile(filePath, `export default ${JSON.stringify(descriptor, null, 2)};\n`, "utf8");
 }
 
+test("resolveLocalPackageSources includes every lock-classified local package regardless of scope or exports", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "jskit-client-bootstrap-local-resolution-"));
+  await mkdir(path.join(tempRoot, ".jskit"), { recursive: true });
+  await writeJson(path.join(tempRoot, ".jskit", "lock.json"), {
+    lockVersion: 1,
+    installedPackages: {
+      "@local/main": {
+        source: {
+          type: "local-package",
+          packagePath: "packages/main"
+        }
+      },
+      "@local/feature": {
+        source: {
+          type: "app-local-package",
+          packagePath: "packages/feature"
+        }
+      },
+      "@example/local-utility": {
+        source: {
+          type: "local-package",
+          packagePath: "packages/utility"
+        }
+      },
+      "@example/published": {
+        source: {
+          type: "npm",
+          packagePath: "packages/published"
+        }
+      }
+    }
+  });
+
+  const localPackages = await resolveLocalPackageSources({
+    appRoot: tempRoot,
+    lockPath: ".jskit/lock.json"
+  });
+  assert.deepEqual(localPackages.map((entry) => entry.packageId), [
+    "@example/local-utility",
+    "@local/feature",
+    "@local/main"
+  ]);
+  const mainPackage = localPackages.find((entry) => entry.packageId === "@local/main");
+  assert.equal(
+    mainPackage.installedPackageRoot,
+    path.join(tempRoot, "node_modules", "@local", "main")
+  );
+  assert.equal(
+    mainPackage.sourcePackageRoot,
+    path.join(tempRoot, "packages", "main")
+  );
+  assert.equal(resolveLocalPackageForSpecifier("@local/main/client", localPackages), mainPackage);
+  assert.equal(
+    resolveLocalPackageForSpecifier("@example/local-utility/shared?raw", localPackages)?.packageId,
+    "@example/local-utility"
+  );
+  assert.equal(resolveLocalPackageForSpecifier("@example/published/client", localPackages), null);
+});
+
+test("resolveCanonicalLocalPackageId translates Vite's selected export target to source", () => {
+  const localPackage = {
+    installedPackageRoot: path.join("/app", "node_modules", "@local", "main"),
+    sourcePackageRoot: path.join("/app", "packages", "main")
+  };
+
+  assert.equal(
+    resolveCanonicalLocalPackageId(
+      "/app/node_modules/@local/main/browser/condition-entry.js?vue&type=script",
+      localPackage
+    ),
+    "/app/packages/main/browser/condition-entry.js?vue&type=script"
+  );
+  assert.equal(
+    resolveCanonicalLocalPackageId("/app/packages/main/browser/already-source.js", localPackage),
+    "/app/packages/main/browser/already-source.js"
+  );
+  assert.equal(resolveCanonicalLocalPackageId("/app/node_modules/published/index.js", localPackage), "");
+});
+
 test("createVirtualModuleSource renders deterministic client module imports", () => {
   const source = createVirtualModuleSource([
     {
@@ -401,7 +483,7 @@ test("createJskitClientBootstrapPlugin resolves and loads virtual module", async
     process.chdir(tempRoot);
     const plugin = createJskitClientBootstrapPlugin();
 
-    const resolvedId = plugin.resolveId(CLIENT_BOOTSTRAP_VIRTUAL_ID);
+    const resolvedId = await plugin.resolveId(CLIENT_BOOTSTRAP_VIRTUAL_ID);
     assert.equal(resolvedId, CLIENT_BOOTSTRAP_RESOLVED_ID);
 
     const source = await plugin.load(CLIENT_BOOTSTRAP_RESOLVED_ID);
@@ -412,6 +494,142 @@ test("createJskitClientBootstrapPlugin resolves and loads virtual module", async
   }
 });
 
+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();
+
+  try {
+    await mkdir(path.join(tempRoot, ".jskit"), { recursive: true });
+    await writeJson(path.join(tempRoot, ".jskit", "lock.json"), {
+      lockVersion: 1,
+      installedPackages: {
+        "@local/main": {
+          source: {
+            type: "local-package",
+            packagePath: "packages/main"
+          }
+        },
+        "@local/feature": {
+          source: {
+            type: "app-local-package",
+            packagePath: "packages/feature"
+          }
+        },
+        "@example/local-utility": {
+          source: {
+            type: "local-package",
+            packagePath: "packages/utility"
+          }
+        },
+        "@example/published": {
+          source: {
+            type: "npm"
+          }
+        }
+      }
+    });
+
+    const packageFixtures = [
+      {
+        packageId: "@local/main",
+        packageDirectory: "main",
+        exports: {
+          "./client": "./custom/main-client.js",
+          "./shared": "./custom/main-shared.js"
+        }
+      },
+      {
+        packageId: "@local/feature",
+        packageDirectory: "feature",
+        exports: {
+          "./client": "./browser/feature-client.js",
+          "./shared": "./browser/feature-shared.js"
+        }
+      },
+      {
+        packageId: "@example/local-utility",
+        packageDirectory: "utility",
+        exports: {
+          ".": "./browser/utility.js",
+          "./shared": "./browser/utility-shared.js"
+        }
+      }
+    ];
+    for (const fixture of packageFixtures) {
+      const packageJson = {
+        name: fixture.packageId,
+        exports: fixture.exports
+      };
+      const sourcePackageRoot = path.join(tempRoot, "packages", fixture.packageDirectory);
+      const installedPackageRoot = path.join(tempRoot, "node_modules", ...fixture.packageId.split("/"));
+      await mkdir(sourcePackageRoot, { recursive: true });
+      await mkdir(installedPackageRoot, { recursive: true });
+      await writeJson(path.join(sourcePackageRoot, "package.json"), packageJson);
+      await writeJson(path.join(installedPackageRoot, "package.json"), packageJson);
+    }
+
+    const publishedPackageRoot = path.join(tempRoot, "node_modules", "@example", "published");
+    await mkdir(publishedPackageRoot, { recursive: true });
+    await writeJson(path.join(publishedPackageRoot, "package.json"), {
+      name: "@example/published",
+      exports: {
+        "./client": "./src/client/index.js"
+      }
+    });
+
+    process.chdir(tempRoot);
+    const plugin = createJskitClientBootstrapPlugin();
+    await plugin.config({}, { command: "serve", mode: "development" });
+    const viteResolvedIds = new Map([
+      ["@local/main/client", path.join(tempRoot, "node_modules", "@local", "main", "custom", "main-client.js")],
+      ["@local/main/shared", path.join(tempRoot, "node_modules", "@local", "main", "custom", "main-shared.js")],
+      ["@local/feature/client", path.join(tempRoot, "node_modules", "@local", "feature", "browser", "feature-client.js")],
+      ["@local/feature/shared", path.join(tempRoot, "node_modules", "@local", "feature", "browser", "feature-shared.js")],
+      ["@example/local-utility", path.join(tempRoot, "node_modules", "@example", "local-utility", "browser", "utility.js")],
+      ["@example/local-utility/shared", path.join(tempRoot, "node_modules", "@example", "local-utility", "browser", "utility-shared.js")]
+    ]);
+    plugin.configResolved({
+      createResolver(options) {
+        assert.equal(options.scan, true);
+        return async (source, importer) => {
+          assert.equal(importer, undefined);
+          return viteResolvedIds.get(source);
+        };
+      }
+    });
+    const resolveId = async (source) => plugin.resolveId(source);
+
+    assert.equal(plugin.enforce, "pre");
+    assert.equal(
+      await resolveId("@local/main/client"),
+      path.join(tempRoot, "packages", "main", "custom", "main-client.js")
+    );
+    assert.equal(
+      await resolveId("@local/main/shared"),
+      path.join(tempRoot, "packages", "main", "custom", "main-shared.js")
+    );
+    assert.equal(
+      await resolveId("@local/feature/client"),
+      path.join(tempRoot, "packages", "feature", "browser", "feature-client.js")
+    );
+    assert.equal(
+      await resolveId("@local/feature/shared"),
+      path.join(tempRoot, "packages", "feature", "browser", "feature-shared.js")
+    );
+    assert.equal(
+      await resolveId("@example/local-utility"),
+      path.join(tempRoot, "packages", "utility", "browser", "utility.js")
+    );
+    assert.equal(
+      await resolveId("@example/local-utility/shared"),
+      path.join(tempRoot, "packages", "utility", "browser", "utility-shared.js")
+    );
+    assert.equal(await resolveId("@example/published/client"), null);
+  } finally {
+    process.chdir(previousCwd);
+  }
+});
+
 test("createJskitClientBootstrapPlugin config excludes installed client package specifiers from optimizeDeps", async () => {
   const tempRoot = await mkdtemp(path.join(os.tmpdir(), "jskit-client-bootstrap-config-"));
   const previousCwd = process.cwd();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/kernel",
-  "version": "0.1.119",
+  "version": "0.1.121",
   "type": "module",
   "dependencies": {
     "json-rest-schema": "1.x.x"