@jskit-ai/kernel 0.1.148 → 0.1.149

package/server/platform/providerRuntime.test.js

@@ -8,75 +8,56 @@ import { createProviderRuntimeFromApp } from "./providerRuntime.js";
 
 async function createTestAppRoot(prefix) {
   const appRoot = await mkdtemp(path.join(tmpdir(), prefix));
-  await mkdir(path.join(appRoot, ".jskit"), { recursive: true });
   await writeFile(
-    path.join(appRoot, ".jskit", "lock.json"),
-    `${JSON.stringify({ lockVersion: 1, installedPackages: {} }, null, 2)}\n`,
+    path.join(appRoot, "package.json"),
+    `${JSON.stringify({ name: "fixture-app", private: true, type: "module" }, null, 2)}\n`,
     "utf8"
   );
   return appRoot;
 }
 
-test("createProviderRuntimeFromApp discovers package providers from descriptor discover entries", async () => {
+async function declareLocalPackage(appRoot, packageId, packagePath, jskit = {}) {
+  await writeFile(
+    path.join(appRoot, "package.json"),
+    `${JSON.stringify({
+      name: "fixture-app",
+      private: true,
+      type: "module",
+      dependencies: {
+        [packageId]: `file:${packagePath}`
+      }
+    }, null, 2)}\n`,
+    "utf8"
+  );
+  const packageRoot = path.join(appRoot, packagePath);
+  await mkdir(packageRoot, { recursive: true });
+  await writeFile(
+    path.join(packageRoot, "package.json"),
+    `${JSON.stringify({
+      name: packageId,
+      version: "0.1.0",
+      description: "Local example package",
+      type: "module",
+      jskit
+    }, null, 2)}\n`,
+    "utf8"
+  );
+}
+
+test("createProviderRuntimeFromApp discovers package providers from package metadata", async () => {
   const appRoot = await createTestAppRoot("kernel-provider-runtime-discover-");
   try {
     await mkdir(path.join(appRoot, "packages", "local-example", "src", "server", "providers"), { recursive: true });
-    await writeFile(
-      path.join(appRoot, ".jskit", "lock.json"),
-      `${JSON.stringify(
-        {
-          lockVersion: 1,
-          installedPackages: {
-            "@local/example": {
-              packageId: "@local/example",
-              version: "0.1.0",
-              source: {
-                type: "local-package",
-                packagePath: "packages/local-example"
-              },
-              managed: {
-                packageJson: {
-                  dependencies: {},
-                  devDependencies: {},
-                  scripts: {}
-                },
-                text: {},
-                files: []
-              },
-              options: {},
-              installedAt: "2026-01-01T00:00:00.000Z"
-            }
-          }
-        },
-        null,
-        2
-      )}\n`,
-      "utf8"
-    );
-    await writeFile(
-      path.join(appRoot, "packages", "local-example", "package.descriptor.mjs"),
-      [
-        "export default Object.freeze({",
-        "  packageVersion: 1,",
-        "  packageId: \"@local/example\",",
-        "  version: \"0.1.0\",",
-        "  description: \"Local example package\",",
-        "  dependsOn: [],",
-        "  capabilities: {",
-        "    provides: [],",
-        "    requires: []",
-        "  },",
-        "  runtime: {",
-        "    server: {",
-        "      providers: [",
-        "        { discover: { dir: \"src/server/providers\", pattern: \"*Provider.js\" } }",
-        "      ]",
-        "    }",
-        "  }",
-        "});"
-      ].join("\n"),
-      "utf8"
-    );
+    await declareLocalPackage(appRoot, "@local/example", "packages/local-example", {
+      capabilities: { provides: [], requires: [] },
+      runtime: {
+        server: {
+          providers: [
+            { discover: { dir: "src/server/providers", pattern: "*Provider.js" } }
+          ]
+        }
+      }
+    });
     await writeFile(
       path.join(appRoot, "packages", "local-example", "src", "server", "providers", "AlphaProvider.js"),
       [
@@ -145,64 +126,14 @@ test("createProviderRuntimeFromApp ignores app-local src/server/providers folder
   }
 });
 
-test("createProviderRuntimeFromApp resolves descriptor using source.packagePath", async () => {
+test("createProviderRuntimeFromApp resolves package metadata from a file dependency", async () => {
   const appRoot = await createTestAppRoot("kernel-provider-runtime-local-package-");
   try {
     await mkdir(path.join(appRoot, "packages", "local-example"), { recursive: true });
-    await writeFile(
-      path.join(appRoot, ".jskit", "lock.json"),
-      `${JSON.stringify(
-        {
-          lockVersion: 1,
-          installedPackages: {
-            "@local/example": {
-              packageId: "@local/example",
-              version: "0.1.0",
-              source: {
-                type: "local-package",
-                packagePath: "packages/local-example"
-              },
-              managed: {
-                packageJson: {
-                  dependencies: {},
-                  devDependencies: {},
-                  scripts: {}
-                },
-                text: {},
-                files: []
-              },
-              options: {},
-              installedAt: "2026-01-01T00:00:00.000Z"
-            }
-          }
-        },
-        null,
-        2
-      )}\n`,
-      "utf8"
-    );
-    await writeFile(
-      path.join(appRoot, "packages", "local-example", "package.descriptor.mjs"),
-      [
-        "export default Object.freeze({",
-        "  packageVersion: 1,",
-        "  packageId: \"@local/example\",",
-        "  version: \"0.1.0\",",
-        "  description: \"Local example package\",",
-        "  dependsOn: [],",
-        "  capabilities: {",
-        "    provides: [],",
-        "    requires: []",
-        "  },",
-        "  runtime: {",
-        "    server: {",
-        "      providers: []",
-        "    }",
-        "  }",
-        "});"
-      ].join("\n"),
-      "utf8"
-    );
+    await declareLocalPackage(appRoot, "@local/example", "packages/local-example", {
+      capabilities: { provides: [], requires: [] },
+      runtime: { server: { providers: [] } }
+    });
 
     const runtime = await createProviderRuntimeFromApp({
       appRoot,
@@ -220,62 +151,16 @@ test("createProviderRuntimeFromApp wires fastify onClose to provider shutdown ex
   const appRoot = await createTestAppRoot("kernel-provider-runtime-fastify-close-");
   try {
     await mkdir(path.join(appRoot, "packages", "local-example", "src", "server", "providers"), { recursive: true });
-    await writeFile(
-      path.join(appRoot, ".jskit", "lock.json"),
-      `${JSON.stringify(
-        {
-          lockVersion: 1,
-          installedPackages: {
-            "@local/example": {
-              packageId: "@local/example",
-              version: "0.1.0",
-              source: {
-                type: "local-package",
-                packagePath: "packages/local-example"
-              },
-              managed: {
-                packageJson: {
-                  dependencies: {},
-                  devDependencies: {},
-                  scripts: {}
-                },
-                text: {},
-                files: []
-              },
-              options: {},
-              installedAt: "2026-01-01T00:00:00.000Z"
-            }
-          }
-        },
-        null,
-        2
-      )}\n`,
-      "utf8"
-    );
-    await writeFile(
-      path.join(appRoot, "packages", "local-example", "package.descriptor.mjs"),
-      [
-        "export default Object.freeze({",
-        "  packageVersion: 1,",
-        "  packageId: \"@local/example\",",
-        "  version: \"0.1.0\",",
-        "  description: \"Local example package\",",
-        "  dependsOn: [],",
-        "  capabilities: {",
-        "    provides: [],",
-        "    requires: []",
-        "  },",
-        "  runtime: {",
-        "    server: {",
-        "      providers: [",
-        "        { discover: { dir: \"src/server/providers\", pattern: \"*Provider.js\" } }",
-        "      ]",
-        "    }",
-        "  }",
-        "});"
-      ].join("\n"),
-      "utf8"
-    );
+    await declareLocalPackage(appRoot, "@local/example", "packages/local-example", {
+      capabilities: { provides: [], requires: [] },
+      runtime: {
+        server: {
+          providers: [
+            { discover: { dir: "src/server/providers", pattern: "*Provider.js" } }
+          ]
+        }
+      }
+    });
     await writeFile(
       path.join(appRoot, "packages", "local-example", "src", "server", "providers", "CloseAwareProvider.js"),
       [

package/server/platform/surfaceRuntime.test.js

@@ -68,7 +68,7 @@ test("shouldServePathForSurface allows api and matching enabled surfaces", () =>
   );
 });
 
-test("shouldServePathForSurface allows descriptor-declared global ui paths", () => {
+test("shouldServePathForSurface allows packageMetadata-declared global ui paths", () => {
   const surfaceRuntime = createFakeSurfaceRuntime();
   assert.equal(
     shouldServePathForSurface({

package/server/support/index.js

@@ -2,6 +2,12 @@ export { symlinkSafeRequire } from "./symlinkSafeRequire.js";
 export { resolveAppConfig, resolveMobileConfig, resolveClientAssetMode, resolveMobileCallbackUrls } from "./appConfig.js";
 export { loadAppConfigFromAppRoot, loadAppConfigFromModuleUrl } from "./appConfigFiles.js";
 export { importFreshModuleFromAbsolutePath } from "./importFreshModuleFromAbsolutePath.js";
+export {
+  collectPackageDependencyIds,
+  collectRootDependencySpecifiers,
+  createPackageMetadata,
+  discoverInstalledPackages
+} from "../../internal/node/installedPackages.js";
 export { resolveRequiredAppRoot, toPosixPath } from "./path.js";
 export {
   DEFAULT_PAGE_LINK_COMPONENT_TOKEN,

package/server/support/shellOutlets.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { readdir, readFile } from "node:fs/promises";
 import { pathToFileURL } from "node:url";
-import { loadInstalledPackageDescriptor } from "../../internal/node/installedPackageDescriptor.js";
+import { discoverInstalledPackages } from "../../internal/node/installedPackages.js";
 import { normalizeObject, normalizeText } from "../../shared/support/normalize.js";
 import { resolveRequiredAppRoot, toPosixPath } from "./path.js";
 import {
@@ -15,7 +15,6 @@ import {
 } from "../../shared/support/shellLayoutTargets.js";
 
 const VUE_DISCOVERY_IGNORED_ERROR_CODES = new Set(["ENOENT", "ENOTDIR", "EACCES", "EPERM"]);
-const LOCK_FILE_RELATIVE_PATH = ".jskit/lock.json";
 const PLACEMENT_TOPOLOGY_RELATIVE_PATH = "src/placementTopology.js";
 const ROUTE_TAG_PATTERN = /<route\b([^>]*)>([\s\S]*?)<\/route>/g;
 const ATTRIBUTE_PATTERN = /([:@]?[A-Za-z_][A-Za-z0-9_-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'))?/g;
@@ -174,33 +173,10 @@ async function collectVueFilePaths(rootDirectoryPath) {
   return files.sort((left, right) => left.localeCompare(right));
 }
 
-async function readInstalledPackageStates(appRoot) {
-  const lockPath = path.resolve(appRoot, LOCK_FILE_RELATIVE_PATH);
-  let lockSource = "";
-  try {
-    lockSource = await readFile(lockPath, "utf8");
-  } catch (error) {
-    const errorCode = normalizeText(error?.code).toUpperCase();
-    if (errorCode === "ENOENT") {
-      return {};
-    }
-    throw error;
-  }
-
-  let lockPayload = {};
-  try {
-    lockPayload = JSON.parse(lockSource);
-  } catch (error) {
-    throw new Error(`Invalid JSON in ${LOCK_FILE_RELATIVE_PATH}.`);
-  }
-
-  return normalizeObject(lockPayload.installedPackages);
-}
-
 function normalizePackageOutletTarget({
   packageId = "",
   outlet = {},
-  descriptorPath = ""
+  manifestPath = ""
 } = {}) {
   const normalizedPackageId = normalizeText(packageId);
   if (!normalizedPackageId) {
@@ -218,7 +194,7 @@ function normalizePackageOutletTarget({
   const source = normalizeText(outletRecord.source);
   const sourcePath = source
     ? `package:${normalizedPackageId}:${toPosixPath(source)}`
-    : `package:${normalizedPackageId}${descriptorPath ? `:${toPosixPath(descriptorPath)}` : ""}`;
+    : `package:${normalizedPackageId}${manifestPath ? `:${toPosixPath(manifestPath)}` : ""}`;
 
   return Object.freeze({
     ...normalizedTarget,
@@ -229,19 +205,13 @@ function normalizePackageOutletTarget({
 }
 
 async function collectInstalledPackageOutletTargets(appRoot) {
-  const installedPackageStates = await readInstalledPackageStates(appRoot);
-  const packageIds = Object.keys(installedPackageStates).sort((left, right) => left.localeCompare(right));
+  const installedPackages = await discoverInstalledPackages({ appRoot });
   const targets = [];
 
-  for (const packageId of packageIds) {
-    const installedPackageState = normalizeObject(installedPackageStates[packageId]);
-    const descriptorRecord = await loadInstalledPackageDescriptor({
-      appRoot,
-      packageId,
-      installedPackageState
-    });
-    const descriptor = normalizeObject(descriptorRecord.descriptor);
-    const metadata = normalizeObject(descriptor.metadata);
+  for (const installedPackage of installedPackages) {
+    const packageId = installedPackage.packageId;
+    const packageMetadata = normalizeObject(installedPackage.packageMetadata);
+    const metadata = normalizeObject(packageMetadata.metadata);
     const ui = normalizeObject(metadata.ui);
     const placements = normalizeObject(ui.placements);
     const outlets = Array.isArray(placements.outlets) ? placements.outlets : [];
@@ -249,7 +219,7 @@ async function collectInstalledPackageOutletTargets(appRoot) {
       const normalizedTarget = normalizePackageOutletTarget({
         packageId,
         outlet,
-        descriptorPath: descriptorRecord.descriptorPath
+        manifestPath: installedPackage.manifestPath
       });
       if (normalizedTarget) {
         targets.push(normalizedTarget);
@@ -297,19 +267,13 @@ async function loadAppPlacementTopology(appRoot) {
 }
 
 async function collectInstalledPackagePlacementTopology(appRoot) {
-  const installedPackageStates = await readInstalledPackageStates(appRoot);
-  const packageIds = Object.keys(installedPackageStates).sort((left, right) => left.localeCompare(right));
+  const installedPackages = await discoverInstalledPackages({ appRoot });
   const placements = [];
 
-  for (const packageId of packageIds) {
-    const installedPackageState = normalizeObject(installedPackageStates[packageId]);
-    const descriptorRecord = await loadInstalledPackageDescriptor({
-      appRoot,
-      packageId,
-      installedPackageState
-    });
-    const descriptor = normalizeObject(descriptorRecord.descriptor);
-    const metadata = normalizeObject(descriptor.metadata);
+  for (const installedPackage of installedPackages) {
+    const packageId = installedPackage.packageId;
+    const packageMetadata = normalizeObject(installedPackage.packageMetadata);
+    const metadata = normalizeObject(packageMetadata.metadata);
     const ui = normalizeObject(metadata.ui);
     const placementsMeta = normalizeObject(ui.placements);
     const topology = placementsMeta.topology;
@@ -324,7 +288,7 @@ async function collectInstalledPackagePlacementTopology(appRoot) {
       placements.push(
         withTopologySource(
           placement,
-          `package:${packageId}${descriptorRecord.descriptorPath ? `:${toPosixPath(descriptorRecord.descriptorPath)}` : ""}`
+          `package:${packageId}${installedPackage.manifestPath ? `:${toPosixPath(installedPackage.manifestPath)}` : ""}`
         )
       );
     }

package/server/support/shellOutlets.test.js

@@ -71,18 +71,13 @@ test("discoverShellOutletTargetsFromApp includes installed package placement out
     );
     await writeFileInApp(
       appRoot,
-      ".jskit/lock.json",
+      "package.json",
       `${JSON.stringify(
         {
-          lockVersion: 1,
-          installedPackages: {
-            "@example/users-web": {
-              packageId: "@example/users-web",
-              source: {
-                type: "npm-installed-package",
-                descriptorPath: "node_modules/@example/users-web/package.descriptor.mjs"
-              }
-            }
+          name: "fixture-app",
+          private: true,
+          dependencies: {
+            "@example/users-web": "1.0.0"
           }
         },
         null,
@@ -91,23 +86,25 @@ test("discoverShellOutletTargetsFromApp includes installed package placement out
     );
     await writeFileInApp(
       appRoot,
-      "node_modules/@example/users-web/package.descriptor.mjs",
-      `export default {
-  packageId: "@example/users-web",
-  metadata: {
-    ui: {
-      placements: {
-        outlets: [
-          {
-            target: "admin-cog:primary-menu",
-            source: "src/client/components/UsersWorkspaceToolsWidget.vue"
+      "node_modules/@example/users-web/package.json",
+      `${JSON.stringify({
+        name: "@example/users-web",
+        version: "1.0.0",
+        jskit: {
+          metadata: {
+            ui: {
+              placements: {
+                outlets: [
+                  {
+                    target: "admin-cog:primary-menu",
+                    source: "src/client/components/UsersWorkspaceToolsWidget.vue"
+                  }
+                ]
+              }
+            }
           }
-        ]
-      }
-    }
-  }
-};
-`
+        }
+      }, null, 2)}\n`
     );
 
     const discovered = await discoverShellOutletTargetsFromApp({ appRoot });

package/shared/support/generatedUiContract.test.js

@@ -15,7 +15,7 @@ import {
   shouldCreateGeneratedUiNavigationLink
 } from "./generatedUiContract.js";
 
-test("generated UI navigation role metadata is descriptor-ready", () => {
+test("generated UI navigation role metadata is package-ready", () => {
   assert.deepEqual(
     GENERATED_UI_NAVIGATION_ROLE_VALUES,
     ["primary", "secondary", "utility", "detail", "workflow", "none"]

package/internal/node/installedPackageDescriptor.js

@@ -1,125 +0,0 @@
-import path from "node:path";
-import { pathToFileURL } from "node:url";
-import { normalizeObject } from "../../shared/support/normalize.js";
-import { fileExists } from "./fileSystem.js";
-
-function resolveNodeModulesDescriptorCandidatePaths({ appRoot, packageId }) {
-  const packageDescriptorPath = path.join(packageId, "package.descriptor.mjs");
-  const candidatePaths = [];
-  let currentRoot = path.resolve(appRoot);
-
-  while (true) {
-    const nodeModulesRoot =
-      path.basename(currentRoot) === "node_modules" ? currentRoot : path.join(currentRoot, "node_modules");
-    candidatePaths.push(path.join(nodeModulesRoot, packageDescriptorPath));
-
-    const parentRoot = path.dirname(currentRoot);
-    if (parentRoot === currentRoot) {
-      break;
-    }
-    currentRoot = parentRoot;
-  }
-
-  return candidatePaths;
-}
-
-function resolveDescriptorCandidatePaths({ appRoot, packageId, installedPackageState }) {
-  const normalizedAppRoot = String(appRoot || "").trim();
-  if (!normalizedAppRoot) {
-    throw new TypeError("resolveDescriptorCandidatePaths requires appRoot.");
-  }
-
-  const normalizedPackageId = String(packageId || "").trim();
-  if (!normalizedPackageId) {
-    throw new TypeError("resolveDescriptorCandidatePaths requires packageId.");
-  }
-
-  const source = normalizeObject(installedPackageState?.source);
-  const descriptorPathFromSource = String(source.descriptorPath || "").trim();
-  const packagePathFromSource = String(source.packagePath || "").trim();
-  const jskitRoot = path.join(normalizedAppRoot, "node_modules", "@jskit-ai", "jskit-cli");
-
-  const candidatePaths = resolveNodeModulesDescriptorCandidatePaths({
-    appRoot: normalizedAppRoot,
-    packageId: normalizedPackageId
-  });
-  if (packagePathFromSource) {
-    candidatePaths.push(path.resolve(normalizedAppRoot, packagePathFromSource, "package.descriptor.mjs"));
-  }
-  if (descriptorPathFromSource) {
-    candidatePaths.push(path.resolve(normalizedAppRoot, descriptorPathFromSource));
-    candidatePaths.push(path.resolve(jskitRoot, descriptorPathFromSource));
-  }
-
-  const uniqueCandidatePaths = [];
-  const seenPaths = new Set();
-  for (const candidatePath of candidatePaths) {
-    const normalizedCandidatePath = String(candidatePath || "").trim();
-    if (!normalizedCandidatePath || seenPaths.has(normalizedCandidatePath)) {
-      continue;
-    }
-    seenPaths.add(normalizedCandidatePath);
-    uniqueCandidatePaths.push(normalizedCandidatePath);
-  }
-
-  return uniqueCandidatePaths;
-}
-
-async function resolveDescriptorPathForInstalledPackage({ appRoot, packageId, installedPackageState, required = false }) {
-  const candidatePaths = resolveDescriptorCandidatePaths({
-    appRoot,
-    packageId,
-    installedPackageState
-  });
-
-  for (const candidatePath of candidatePaths) {
-    if (await fileExists(candidatePath)) {
-      return candidatePath;
-    }
-  }
-
-  if (required === true) {
-    throw new Error(`Unable to resolve package descriptor for ${String(packageId || "").trim()}.`);
-  }
-
-  return "";
-}
-
-function normalizeDescriptorPayload(descriptorModule) {
-  return normalizeObject(descriptorModule?.default);
-}
-
-async function loadInstalledPackageDescriptor({ appRoot, packageId, installedPackageState, required = false }) {
-  const descriptorPath = await resolveDescriptorPathForInstalledPackage({
-    appRoot,
-    packageId,
-    installedPackageState,
-    required
-  });
-
-  if (!descriptorPath) {
-    return Object.freeze({
-      descriptorPath: "",
-      descriptor: Object.freeze({})
-    });
-  }
-
-  try {
-    const descriptorModule = await import(pathToFileURL(descriptorPath).href);
-    return Object.freeze({
-      descriptorPath,
-      descriptor: normalizeDescriptorPayload(descriptorModule)
-    });
-  } catch (error) {
-    if (required === true) {
-      throw error;
-    }
-
-    return Object.freeze({
-      descriptorPath: "",
-      descriptor: Object.freeze({})
-    });
-  }
-}
-
-export { loadInstalledPackageDescriptor, resolveDescriptorPathForInstalledPackage };

package/server/platform/providerRuntime/lockfile.js

@@ -1,27 +0,0 @@
-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 };