@jskit-ai/kernel 0.1.65 → 0.1.67

package/server/support/shellOutlets.js

@@ -8,13 +8,15 @@ import {
   describeShellOutletTargets,
   discoverShellOutletTargetsFromVueSource,
   findShellOutletTargetById,
+  normalizePlacementTopologyDefinition,
+  normalizeSemanticPlacementId,
   normalizeShellOutletTargetId,
   normalizeShellOutletTargetRecord
 } from "../../shared/support/shellLayoutTargets.js";
-import { loadAppConfigFromModuleUrl } from "./appConfigFiles.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;
 
@@ -68,7 +70,13 @@ function normalizeAppRouteOutletTarget({
   });
 }
 
-function discoverRouteMetaOutletTargetsFromVueSource(source = "", { context = "shell layout" } = {}) {
+function discoverRouteMetaOutletTargetsFromVueSource(
+  source = "",
+  {
+    context = "shell layout",
+    enforceSingleDefault = true
+  } = {}
+) {
   const sourceText = String(source || "");
   const resolvedContext = normalizeText(context) || "shell layout";
   const targetById = new Map();
@@ -111,12 +119,14 @@ function discoverRouteMetaOutletTargetsFromVueSource(source = "", { context = "s
         throw new Error(`${resolvedContext} contains duplicate route meta placement target "${normalizedTarget.id}".`);
       }
       if (normalizedTarget.default === true) {
-        if (defaultTargetId && defaultTargetId !== normalizedTarget.id) {
+        if (enforceSingleDefault === true && defaultTargetId && defaultTargetId !== normalizedTarget.id) {
           throw new Error(
             `${resolvedContext} defines multiple default route meta placement targets: "${defaultTargetId}" and "${normalizedTarget.id}".`
           );
         }
-        defaultTargetId = normalizedTarget.id;
+        if (!defaultTargetId) {
+          defaultTargetId = normalizedTarget.id;
+        }
       }
       targetById.set(normalizedTarget.id, normalizedTarget);
     }
@@ -218,46 +228,6 @@ function normalizePackageOutletTarget({
   });
 }
 
-async function loadOutletDefaultOverrides(appRoot = "") {
-  const resolvedAppRoot = resolveRequiredAppRoot(appRoot, {
-    context: "discoverShellOutletTargetsFromApp"
-  });
-  let appConfig = {};
-  try {
-    appConfig = normalizeObject(
-      await loadAppConfigFromModuleUrl({
-        moduleUrl: pathToFileURL(path.join(resolvedAppRoot, "config", "public.js")).href
-      })
-    );
-  } catch {
-    return {};
-  }
-  return normalizeObject(normalizeObject(appConfig.ui).outletDefaults);
-}
-
-function applyOutletDefaultOverrides(target = {}, outletDefaultOverrides = {}) {
-  const targetRecord = normalizeObject(target);
-  const outletTargetId = normalizeShellOutletTargetId(targetRecord.id);
-  if (!outletTargetId) {
-    return targetRecord;
-  }
-
-  const overrideRecord = outletDefaultOverrides?.[outletTargetId];
-  const normalizedOverrideToken =
-    typeof overrideRecord === "string"
-      ? normalizeText(overrideRecord)
-      : normalizeText(normalizeObject(overrideRecord).linkComponentToken) ||
-        normalizeText(normalizeObject(overrideRecord)["link-component-token"]);
-  if (!normalizedOverrideToken) {
-    return targetRecord;
-  }
-
-  return Object.freeze({
-    ...targetRecord,
-    defaultLinkComponentToken: normalizedOverrideToken
-  });
-}
-
 async function collectInstalledPackageOutletTargets(appRoot) {
   const installedPackageStates = await readInstalledPackageStates(appRoot);
   const packageIds = Object.keys(installedPackageStates).sort((left, right) => left.localeCompare(right));
@@ -290,11 +260,185 @@ async function collectInstalledPackageOutletTargets(appRoot) {
   return targets;
 }
 
-async function discoverShellOutletTargetsFromApp({ appRoot, sourceRoot = "src" } = {}) {
+function withTopologySource(placement = {}, sourcePath = "") {
+  return Object.freeze({
+    ...placement,
+    sourcePath
+  });
+}
+
+async function loadAppPlacementTopology(appRoot) {
+  const topologyPath = path.resolve(appRoot, PLACEMENT_TOPOLOGY_RELATIVE_PATH);
+  try {
+    await readFile(topologyPath, "utf8");
+  } catch (error) {
+    const errorCode = normalizeText(error?.code).toUpperCase();
+    if (errorCode === "ENOENT" || errorCode === "ENOTDIR") {
+      return [];
+    }
+    throw error;
+  }
+
+  let moduleNamespace = null;
+  try {
+    moduleNamespace = await import(pathToFileURL(topologyPath).href);
+  } catch (error) {
+    throw new Error(
+      `Could not load ${PLACEMENT_TOPOLOGY_RELATIVE_PATH}: ${String(error?.message || error || "unknown error")}`
+    );
+  }
+
+  const exported = moduleNamespace?.default;
+  const resolved = typeof exported === "function" ? exported() : exported;
+  const normalized = normalizePlacementTopologyDefinition(resolved, {
+    context: PLACEMENT_TOPOLOGY_RELATIVE_PATH
+  });
+  return normalized.placements.map((placement) => withTopologySource(placement, PLACEMENT_TOPOLOGY_RELATIVE_PATH));
+}
+
+async function collectInstalledPackagePlacementTopology(appRoot) {
+  const installedPackageStates = await readInstalledPackageStates(appRoot);
+  const packageIds = Object.keys(installedPackageStates).sort((left, right) => left.localeCompare(right));
+  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);
+    const ui = normalizeObject(metadata.ui);
+    const placementsMeta = normalizeObject(ui.placements);
+    const topology = placementsMeta.topology;
+    if (!topology) {
+      continue;
+    }
+
+    const normalized = normalizePlacementTopologyDefinition(topology, {
+      context: `package:${packageId}:metadata.ui.placements.topology`
+    });
+    for (const placement of normalized.placements) {
+      placements.push(
+        withTopologySource(
+          placement,
+          `package:${packageId}${descriptorRecord.descriptorPath ? `:${toPosixPath(descriptorRecord.descriptorPath)}` : ""}`
+        )
+      );
+    }
+  }
+
+  return placements;
+}
+
+async function discoverPlacementTopologyFromApp({ appRoot } = {}) {
   const resolvedAppRoot = resolveRequiredAppRoot(appRoot, {
-    context: "discoverShellOutletTargetsFromApp"
+    context: "discoverPlacementTopologyFromApp"
+  });
+  const appPlacements = await loadAppPlacementTopology(resolvedAppRoot);
+  const packagePlacements = await collectInstalledPackagePlacementTopology(resolvedAppRoot);
+  const placementByKey = new Map();
+
+  for (const placement of [...packagePlacements, ...appPlacements]) {
+    const key = `${placement.id}::${placement.owner || ""}`;
+    placementByKey.set(key, placement);
+  }
+
+  return Object.freeze({
+    placements: Object.freeze(
+      [...placementByKey.values()].sort((left, right) => {
+        const idCompare = left.id.localeCompare(right.id);
+        if (idCompare !== 0) {
+          return idCompare;
+        }
+        return String(left.owner || "").localeCompare(String(right.owner || ""));
+      })
+    )
+  });
+}
+
+function findSemanticPlacementById(placements = [], { id = "", owner = "", surface = "" } = {}) {
+  const normalizedId = normalizeSemanticPlacementId(id);
+  const normalizedOwner = normalizeText(owner).toLowerCase();
+  const normalizedSurface = normalizeText(surface).toLowerCase();
+  if (!normalizedId) {
+    return null;
+  }
+
+  return (Array.isArray(placements) ? placements : []).find((placement) => {
+    if (placement.id !== normalizedId) {
+      return false;
+    }
+    if (normalizedOwner && placement.owner !== normalizedOwner) {
+      return false;
+    }
+    if (!normalizedOwner && placement.owner) {
+      return false;
+    }
+    const surfaces = Array.isArray(placement.surfaces) ? placement.surfaces : ["*"];
+    return !normalizedSurface || surfaces.includes("*") || surfaces.includes(normalizedSurface);
+  }) || null;
+}
+
+async function resolveSemanticPlacementTargetFromApp({
+  appRoot,
+  placement = "",
+  owner = "",
+  surface = "",
+  context = "ui-generator"
+} = {}) {
+  const resolvedContext = normalizeText(context) || "ui-generator";
+  const topology = await discoverPlacementTopologyFromApp({ appRoot });
+  const placements = Array.isArray(topology.placements) ? topology.placements : [];
+  if (placements.length < 1) {
+    throw new Error(`${resolvedContext} could not find semantic placement topology in ${PLACEMENT_TOPOLOGY_RELATIVE_PATH}.`);
+  }
+
+  const requestedPlacement = normalizeText(placement);
+  if (requestedPlacement) {
+    const requestedId = normalizeSemanticPlacementId(requestedPlacement);
+    if (!requestedId) {
+      throw new Error(`${resolvedContext} option "placement" must be a semantic target in "area.slot" format.`);
+    }
+    const match = findSemanticPlacementById(placements, {
+      id: requestedId,
+      owner,
+      surface
+    }) || (owner
+      ? findSemanticPlacementById(placements, {
+          id: requestedId,
+          owner: "",
+          surface
+        })
+      : null);
+    if (!match) {
+      throw new Error(`${resolvedContext} semantic placement "${requestedId}" is not declared in app placement topology.`);
+    }
+    return match;
+  }
+
+  const defaultPlacement =
+    placements.find((entry) => entry.default === true && (!surface || entry.surfaces.includes("*") || entry.surfaces.includes(surface))) ||
+    placements.find((entry) => !entry.owner && (!surface || entry.surfaces.includes("*") || entry.surfaces.includes(surface))) ||
+    null;
+  if (defaultPlacement) {
+    return defaultPlacement;
+  }
+
+  throw new Error(`${resolvedContext} could not resolve a default semantic placement target.`);
+}
+
+async function collectAppSourceShellOutletTargets({
+  appRoot,
+  sourceRoot = "src",
+  enforceSingleDefault = true,
+  context = "discoverShellOutletTargetsFromApp"
+} = {}) {
+  const resolvedAppRoot = resolveRequiredAppRoot(appRoot, {
+    context
   });
-  const outletDefaultOverrides = await loadOutletDefaultOverrides(resolvedAppRoot);
 
   const sourceDirectory = path.resolve(resolvedAppRoot, String(sourceRoot || "src"));
   const targetById = new Map();
@@ -311,12 +455,14 @@ async function discoverShellOutletTargetsFromApp({ appRoot, sourceRoot = "src" }
 
     const discoveredShellOutlets = source.includes("<ShellOutlet")
       ? discoverShellOutletTargetsFromVueSource(source, {
-          context: relativePath
+          context: relativePath,
+          enforceSingleDefault
         })
       : { targets: [], defaultTargetId: "" };
     const discoveredRouteMetaOutlets = source.includes("<route")
       ? discoverRouteMetaOutletTargetsFromVueSource(source, {
-          context: relativePath
+          context: relativePath,
+          enforceSingleDefault
         })
       : { targets: [], defaultTargetId: "" };
     const discoveredTargets = [
@@ -342,18 +488,37 @@ async function discoverShellOutletTargetsFromApp({ appRoot, sourceRoot = "src" }
       normalizeShellOutletTargetId(discoveredRouteMetaOutlets.defaultTargetId)
     ].filter(Boolean);
     for (const discoveredDefaultTargetId of discoveredDefaultTargetIds) {
-      if (defaultTargetId && discoveredDefaultTargetId !== defaultTargetId) {
+      if (enforceSingleDefault === true && defaultTargetId && discoveredDefaultTargetId !== defaultTargetId) {
         throw new Error(
           `Multiple default ShellOutlet targets found in app source: "${defaultTargetId}" (${defaultTargetSource}) and ` +
           `"${discoveredDefaultTargetId}" (${relativePath}).`
         );
       }
 
-      defaultTargetId = discoveredDefaultTargetId;
-      defaultTargetSource = relativePath;
+      if (!defaultTargetId) {
+        defaultTargetId = discoveredDefaultTargetId;
+        defaultTargetSource = relativePath;
+      }
     }
   }
 
+  return Object.freeze({
+    resolvedAppRoot,
+    targetById,
+    defaultTargetId
+  });
+}
+
+async function discoverShellOutletTargetsFromApp({ appRoot, sourceRoot = "src" } = {}) {
+  const discoveredAppTargets = await collectAppSourceShellOutletTargets({
+    appRoot,
+    sourceRoot,
+    enforceSingleDefault: true,
+    context: "discoverShellOutletTargetsFromApp"
+  });
+  const resolvedAppRoot = discoveredAppTargets.resolvedAppRoot;
+  const targetById = new Map(discoveredAppTargets.targetById);
+
   const packageTargets = await collectInstalledPackageOutletTargets(resolvedAppRoot);
   for (const target of packageTargets) {
     if (!targetById.has(target.id)) {
@@ -363,15 +528,36 @@ async function discoverShellOutletTargetsFromApp({ appRoot, sourceRoot = "src" }
 
   const targets = [...targetById.values()].sort((left, right) => left.id.localeCompare(right.id));
   const normalizedTargets = targets.map((target) =>
-    applyOutletDefaultOverrides({
+    Object.freeze({
       ...target,
-      default: target.id === defaultTargetId
-    }, outletDefaultOverrides)
+      default: target.id === discoveredAppTargets.defaultTargetId
+    })
   );
 
   return Object.freeze({
     targets: Object.freeze(normalizedTargets),
-    defaultTargetId
+    defaultTargetId: discoveredAppTargets.defaultTargetId
+  });
+}
+
+async function discoverShellOutletSourcePathsFromApp({ appRoot, sourceRoot = "src" } = {}) {
+  const discoveredAppTargets = await collectAppSourceShellOutletTargets({
+    appRoot,
+    sourceRoot,
+    enforceSingleDefault: false,
+    context: "discoverShellOutletSourcePathsFromApp"
+  });
+  const targetById = new Map(discoveredAppTargets.targetById);
+
+  const packageTargets = await collectInstalledPackageOutletTargets(discoveredAppTargets.resolvedAppRoot);
+  for (const target of packageTargets) {
+    if (!targetById.has(target.id)) {
+      targetById.set(target.id, target);
+    }
+  }
+
+  return Object.freeze({
+    targets: Object.freeze([...targetById.values()].sort((left, right) => left.id.localeCompare(right.id)))
   });
 }
 
@@ -418,6 +604,9 @@ async function resolveShellOutletPlacementTargetFromApp({ appRoot, placement = "
 }
 
 export {
+  discoverPlacementTopologyFromApp,
+  discoverShellOutletSourcePathsFromApp,
   discoverShellOutletTargetsFromApp,
+  resolveSemanticPlacementTargetFromApp,
   resolveShellOutletPlacementTargetFromApp
 };

package/server/support/shellOutlets.test.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { tmpdir } from "node:os";
 import test from "node:test";
 import {
+  discoverShellOutletSourcePathsFromApp,
   discoverShellOutletTargetsFromApp,
   resolveShellOutletPlacementTargetFromApp
 } from "./shellOutlets.js";
@@ -99,7 +100,6 @@ test("discoverShellOutletTargetsFromApp includes installed package placement out
         outlets: [
           {
             target: "admin-cog:primary-menu",
-            defaultLinkComponentToken: "local.main.ui.surface-aware-menu-link-item",
             source: "src/client/components/UsersWorkspaceToolsWidget.vue"
           }
         ]
@@ -118,7 +118,6 @@ test("discoverShellOutletTargetsFromApp includes installed package placement out
     assert.deepEqual(discovered.targets[0], {
       id: "admin-cog:primary-menu",
       default: false,
-      defaultLinkComponentToken: "local.main.ui.surface-aware-menu-link-item",
       sourcePath: "package:@example/users-web:src/client/components/UsersWorkspaceToolsWidget.vue",
       sourcePackageId: "@example/users-web"
     });
@@ -132,68 +131,6 @@ test("discoverShellOutletTargetsFromApp includes installed package placement out
   });
 });
 
-test("discoverShellOutletTargetsFromApp applies app config default-link overrides by target id", async () => {
-  await withTempApp(async (appRoot) => {
-    await writeFileInApp(
-      appRoot,
-      "config/public.js",
-      `export const config = {
-  ui: {
-    outletDefaults: {
-      "admin-cog:primary-menu": {
-        linkComponentToken: "local.main.ui.surface-aware-menu-link-item"
-      }
-    }
-  }
-};
-`
-    );
-    await writeFileInApp(
-      appRoot,
-      ".jskit/lock.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"
-              }
-            }
-          }
-        },
-        null,
-        2
-      )}\n`
-    );
-    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",
-            defaultLinkComponentToken: "local.main.ui.surface-aware-menu-link-item"
-          }
-        ]
-      }
-    }
-  }
-};
-`
-    );
-
-    const discovered = await discoverShellOutletTargetsFromApp({ appRoot });
-    assert.equal(discovered.targets[0].defaultLinkComponentToken, "local.main.ui.surface-aware-menu-link-item");
-  });
-});
-
 test("discoverShellOutletTargetsFromApp returns targets with sourcePath and default marker", async () => {
   await withTempApp(async (appRoot) => {
     await writeFileInApp(
@@ -223,13 +160,11 @@ test("discoverShellOutletTargetsFromApp returns targets with sourcePath and defa
       {
         id: "admin-toolbox:widgets",
         default: true,
-        defaultLinkComponentToken: "",
         sourcePath: "src/pages/admin/toolbox/index.vue"
       },
       {
         id: "shell-layout:primary-menu",
         default: false,
-        defaultLinkComponentToken: "",
         sourcePath: "src/components/ShellLayout.vue"
       }
     ]);
@@ -266,7 +201,6 @@ test("discoverShellOutletTargetsFromApp discovers route meta placement outlets",
       {
         id: "contact-tools:sub-pages",
         default: false,
-        defaultLinkComponentToken: "",
         sourcePath: "src/pages/w/[workspaceSlug]/admin/contacts/[contactId]/contact-tools.vue"
       }
     ]);
@@ -363,6 +297,36 @@ test("resolveShellOutletPlacementTargetFromApp throws when multiple default outl
   });
 });
 
+test("discoverShellOutletSourcePathsFromApp ignores default conflicts while keeping source paths", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeFileInApp(
+      appRoot,
+      "src/components/ShellLayout.vue",
+      `<template>
+  <div>
+    <ShellOutlet target="shell-layout:primary-menu" default />
+    <ShellOutlet target="shell-layout:primary-bottom-nav" default />
+  </div>
+</template>
+`
+    );
+
+    const discovered = await discoverShellOutletSourcePathsFromApp({ appRoot });
+    assert.deepEqual(discovered.targets, [
+      {
+        id: "shell-layout:primary-bottom-nav",
+        default: true,
+        sourcePath: "src/components/ShellLayout.vue"
+      },
+      {
+        id: "shell-layout:primary-menu",
+        default: true,
+        sourcePath: "src/components/ShellLayout.vue"
+      }
+    ]);
+  });
+});
+
 test("resolveShellOutletPlacementTargetFromApp requires appRoot", async () => {
   await assert.rejects(
     () =>