@jskit-ai/kernel 0.1.19 → 0.1.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/kernel",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "type": "module",
   "dependencies": {
     "typebox": "^1.0.81"
@@ -34,6 +34,7 @@
     "./shared/support/tokens": "./shared/support/tokens.js",
     "./shared/support/normalize": "./shared/support/normalize.js",
     "./shared/support/permissions": "./shared/support/permissions.js",
+    "./shared/support/crudLookup": "./shared/support/crudLookup.js",
     "./shared/support/deepFreeze": "./shared/support/deepFreeze.js",
     "./shared/support/listenerSet": "./shared/support/listenerSet.js",
     "./shared/support/providerLogger": "./shared/support/providerLogger.js",

package/server/support/appConfigFiles.js

@@ -0,0 +1,61 @@
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { fileExists } from "../../internal/node/fileSystem.js";
+
+const PUBLIC_CONFIG_RELATIVE_PATH = "config/public.js";
+const SERVER_CONFIG_RELATIVE_PATH = "config/server.js";
+
+function normalizeConfigObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+async function resolveAppRootFromModuleUrl(
+  moduleUrl,
+  { publicConfigRelativePath = PUBLIC_CONFIG_RELATIVE_PATH } = {}
+) {
+  const moduleDirectory = path.dirname(fileURLToPath(moduleUrl));
+  let currentDirectory = path.resolve(moduleDirectory);
+
+  while (true) {
+    const candidateConfigPath = path.join(currentDirectory, publicConfigRelativePath);
+    if (await fileExists(candidateConfigPath)) {
+      return currentDirectory;
+    }
+
+    const parentDirectory = path.dirname(currentDirectory);
+    if (parentDirectory === currentDirectory) {
+      throw new Error(`Unable to locate app root (missing ${publicConfigRelativePath}).`);
+    }
+    currentDirectory = parentDirectory;
+  }
+}
+
+async function loadConfigModuleAtPath(absolutePath) {
+  if (!(await fileExists(absolutePath))) {
+    return {};
+  }
+
+  const loadedModule = await import(pathToFileURL(absolutePath).href);
+  return normalizeConfigObject(loadedModule?.config);
+}
+
+async function loadAppConfigFromModuleUrl({
+  moduleUrl = import.meta.url,
+  publicConfigRelativePath = PUBLIC_CONFIG_RELATIVE_PATH,
+  serverConfigRelativePath = SERVER_CONFIG_RELATIVE_PATH
+} = {}) {
+  const appRoot = await resolveAppRootFromModuleUrl(moduleUrl, {
+    publicConfigRelativePath
+  });
+  const [publicConfig, serverConfig] = await Promise.all([
+    loadConfigModuleAtPath(path.join(appRoot, publicConfigRelativePath)),
+    loadConfigModuleAtPath(path.join(appRoot, serverConfigRelativePath))
+  ]);
+
+  return Object.freeze({
+    ...publicConfig,
+    ...serverConfig
+  });
+}
+
+export { loadAppConfigFromModuleUrl };

package/server/support/appConfigFiles.test.js

@@ -0,0 +1,55 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import test from "node:test";
+import { pathToFileURL } from "node:url";
+import { loadAppConfigFromModuleUrl } from "./appConfigFiles.js";
+
+async function createModuleUrlAt(absolutePath) {
+  await mkdir(path.dirname(absolutePath), { recursive: true });
+  await writeFile(absolutePath, "export {};\n", "utf8");
+  return pathToFileURL(absolutePath).href;
+}
+
+test("loadAppConfigFromModuleUrl merges public and server config", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "kernel-app-config-"));
+  const appRoot = path.join(tempRoot, "app");
+  await mkdir(path.join(appRoot, "config"), { recursive: true });
+  await writeFile(path.join(appRoot, "config", "public.js"), "export const config = { a: 1, shared: 'public' };", "utf8");
+  await writeFile(path.join(appRoot, "config", "server.js"), "export const config = { b: 2, shared: 'server' };", "utf8");
+  const moduleUrl = await createModuleUrlAt(path.join(appRoot, "packages", "main", "src", "server", "providers", "MainServiceProvider.js"));
+
+  const loaded = await loadAppConfigFromModuleUrl({ moduleUrl });
+
+  assert.deepEqual(loaded, {
+    a: 1,
+    b: 2,
+    shared: "server"
+  });
+  assert.equal(Object.isFrozen(loaded), true);
+});
+
+test("loadAppConfigFromModuleUrl tolerates missing server config", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "kernel-app-config-"));
+  const appRoot = path.join(tempRoot, "app");
+  await mkdir(path.join(appRoot, "config"), { recursive: true });
+  await writeFile(path.join(appRoot, "config", "public.js"), "export const config = { a: 1 };", "utf8");
+  const moduleUrl = await createModuleUrlAt(path.join(appRoot, "packages", "main", "src", "server", "providers", "MainServiceProvider.js"));
+
+  const loaded = await loadAppConfigFromModuleUrl({ moduleUrl });
+
+  assert.deepEqual(loaded, {
+    a: 1
+  });
+});
+
+test("loadAppConfigFromModuleUrl throws when app root cannot be resolved", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "kernel-app-config-"));
+  const moduleUrl = await createModuleUrlAt(path.join(tempRoot, "missing", "packages", "main", "src", "server", "providers", "MainServiceProvider.js"));
+
+  await assert.rejects(
+    loadAppConfigFromModuleUrl({ moduleUrl }),
+    /Unable to locate app root/
+  );
+});

package/server/support/index.js

@@ -1,2 +1,8 @@
 export { symlinkSafeRequire } from "./symlinkSafeRequire.js";
 export { resolveAppConfig } from "./appConfig.js";
+export { loadAppConfigFromModuleUrl } from "./appConfigFiles.js";
+export { resolveRequiredAppRoot, toPosixPath } from "./path.js";
+export {
+  discoverShellOutletTargetsFromApp,
+  resolveShellOutletPlacementTargetFromApp
+} from "./shellOutlets.js";

package/server/support/path.js

@@ -0,0 +1,20 @@
+import path from "node:path";
+import { normalizeText } from "../../shared/support/normalize.js";
+
+function toPosixPath(value = "") {
+  return String(value || "").replaceAll(path.sep, "/");
+}
+
+function resolveRequiredAppRoot(appRoot, { context = "operation" } = {}) {
+  const normalizedAppRoot = normalizeText(appRoot);
+  if (!normalizedAppRoot) {
+    throw new Error(`${normalizeText(context) || "operation"} requires appRoot.`);
+  }
+
+  return path.resolve(normalizedAppRoot);
+}
+
+export {
+  resolveRequiredAppRoot,
+  toPosixPath
+};

package/server/support/shellOutlets.js

@@ -0,0 +1,259 @@
+import path from "node:path";
+import { readdir, readFile } from "node:fs/promises";
+import { loadInstalledPackageDescriptor } from "../../internal/node/installedPackageDescriptor.js";
+import { normalizeObject, normalizeText } from "../../shared/support/normalize.js";
+import { resolveRequiredAppRoot, toPosixPath } from "./path.js";
+import {
+  describeShellOutletTargets,
+  discoverShellOutletTargetsFromVueSource,
+  findShellOutletTargetById,
+  normalizeShellOutletTargetId
+} 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";
+
+async function collectVueFilePaths(rootDirectoryPath) {
+  const absoluteRoot = path.resolve(String(rootDirectoryPath || ""));
+  const stack = [absoluteRoot];
+  const files = [];
+
+  while (stack.length > 0) {
+    const currentDirectory = stack.pop();
+    let directoryEntries = [];
+    try {
+      directoryEntries = await readdir(currentDirectory, { withFileTypes: true });
+    } catch (error) {
+      const errorCode = normalizeText(error?.code).toUpperCase();
+      if (!VUE_DISCOVERY_IGNORED_ERROR_CODES.has(errorCode)) {
+        throw error;
+      }
+      continue;
+    }
+
+    for (const entry of directoryEntries) {
+      const entryPath = path.join(currentDirectory, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(entryPath);
+        continue;
+      }
+
+      if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".vue")) {
+        continue;
+      }
+
+      files.push(entryPath);
+    }
+  }
+
+  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 = ""
+} = {}) {
+  const normalizedPackageId = normalizeText(packageId);
+  if (!normalizedPackageId) {
+    return null;
+  }
+
+  const outletRecord = normalizeObject(outlet);
+  const outletTargetId = normalizeShellOutletTargetId(
+    `${normalizeText(outletRecord.host)}:${normalizeText(outletRecord.position)}`
+  );
+  if (!outletTargetId) {
+    return null;
+  }
+
+  const separatorIndex = outletTargetId.indexOf(":");
+  const host = outletTargetId.slice(0, separatorIndex);
+  const position = outletTargetId.slice(separatorIndex + 1);
+  const source = normalizeText(outletRecord.source);
+  const sourcePath = source
+    ? `package:${normalizedPackageId}:${toPosixPath(source)}`
+    : `package:${normalizedPackageId}${descriptorPath ? `:${toPosixPath(descriptorPath)}` : ""}`;
+
+  return Object.freeze({
+    id: outletTargetId,
+    host,
+    position,
+    default: false,
+    sourcePath,
+    sourcePackageId: normalizedPackageId
+  });
+}
+
+async function collectInstalledPackageOutletTargets(appRoot) {
+  const installedPackageStates = await readInstalledPackageStates(appRoot);
+  const packageIds = Object.keys(installedPackageStates).sort((left, right) => left.localeCompare(right));
+  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);
+    const ui = normalizeObject(metadata.ui);
+    const placements = normalizeObject(ui.placements);
+    const outlets = Array.isArray(placements.outlets) ? placements.outlets : [];
+    for (const outlet of outlets) {
+      const normalizedTarget = normalizePackageOutletTarget({
+        packageId,
+        outlet,
+        descriptorPath: descriptorRecord.descriptorPath
+      });
+      if (normalizedTarget) {
+        targets.push(normalizedTarget);
+      }
+    }
+  }
+
+  return targets;
+}
+
+async function discoverShellOutletTargetsFromApp({ appRoot, sourceRoot = "src" } = {}) {
+  const resolvedAppRoot = resolveRequiredAppRoot(appRoot, {
+    context: "discoverShellOutletTargetsFromApp"
+  });
+
+  const sourceDirectory = path.resolve(resolvedAppRoot, String(sourceRoot || "src"));
+  const targetById = new Map();
+  let defaultTargetId = "";
+  let defaultTargetSource = "";
+  const vueFiles = await collectVueFilePaths(sourceDirectory);
+
+  for (const absoluteFilePath of vueFiles) {
+    const relativePath = toPosixPath(path.relative(resolvedAppRoot, absoluteFilePath));
+    const source = await readFile(absoluteFilePath, "utf8");
+    if (!source.includes("<ShellOutlet")) {
+      continue;
+    }
+
+    const discovered = discoverShellOutletTargetsFromVueSource(source, {
+      context: relativePath
+    });
+    const targets = Array.isArray(discovered.targets) ? discovered.targets : [];
+    for (const target of targets) {
+      if (!targetById.has(target.id)) {
+        targetById.set(
+          target.id,
+          Object.freeze({
+            ...target,
+            sourcePath: relativePath
+          })
+        );
+      }
+    }
+
+    const discoveredDefaultTargetId = normalizeShellOutletTargetId(discovered.defaultTargetId);
+    if (!discoveredDefaultTargetId) {
+      continue;
+    }
+
+    if (defaultTargetId && discoveredDefaultTargetId !== defaultTargetId) {
+      throw new Error(
+        `Multiple default ShellOutlet targets found in app source: "${defaultTargetId}" (${defaultTargetSource}) and ` +
+        `"${discoveredDefaultTargetId}" (${relativePath}).`
+      );
+    }
+
+    defaultTargetId = discoveredDefaultTargetId;
+    defaultTargetSource = relativePath;
+  }
+
+  const packageTargets = await collectInstalledPackageOutletTargets(resolvedAppRoot);
+  for (const target of packageTargets) {
+    if (!targetById.has(target.id)) {
+      targetById.set(target.id, target);
+    }
+  }
+
+  const targets = [...targetById.values()].sort((left, right) => left.id.localeCompare(right.id));
+  const normalizedTargets = targets.map((target) =>
+    Object.freeze({
+      ...target,
+      default: target.id === defaultTargetId
+    })
+  );
+
+  return Object.freeze({
+    targets: Object.freeze(normalizedTargets),
+    defaultTargetId
+  });
+}
+
+async function resolveShellOutletPlacementTargetFromApp({ appRoot, placement = "", context = "ui-generator" } = {}) {
+  const resolvedContext = normalizeText(context) || "ui-generator";
+  const requestedPlacementOption = normalizeText(placement);
+  const requestedPlacementTargetId = normalizeShellOutletTargetId(requestedPlacementOption);
+  if (requestedPlacementOption && !requestedPlacementTargetId) {
+    throw new Error(`${resolvedContext} option "placement" must be in "host:position" format.`);
+  }
+
+  const discovered = await discoverShellOutletTargetsFromApp({ appRoot, sourceRoot: "src" });
+  const targets = Array.isArray(discovered.targets) ? discovered.targets : [];
+  if (targets.length < 1) {
+    throw new Error(
+      `${resolvedContext} could not find any placement targets from app Vue outlets or installed package metadata.`
+    );
+  }
+
+  if (requestedPlacementTargetId) {
+    const requestedTarget = findShellOutletTargetById(targets, requestedPlacementTargetId);
+    if (!requestedTarget) {
+      const availableTargets = describeShellOutletTargets(targets);
+      throw new Error(
+        `${resolvedContext} option "placement" target "${requestedPlacementTargetId}" is not declared in app or package placement outlets. ` +
+        `Available targets: ${availableTargets || "<none>"}.`
+      );
+    }
+
+    return requestedTarget;
+  }
+
+  const defaultTarget = findShellOutletTargetById(targets, discovered.defaultTargetId);
+  if (defaultTarget) {
+    return defaultTarget;
+  }
+
+  const availableTargets = describeShellOutletTargets(targets);
+  throw new Error(
+    `${resolvedContext} could not resolve a default ShellOutlet target from app Vue outlets. ` +
+    `Set one outlet as default (e.g. <ShellOutlet host="shell-layout" position="primary-menu" default />) ` +
+    `or pass "--placement host:position". Available targets: ${availableTargets || "<none>"}.`
+  );
+}
+
+export {
+  discoverShellOutletTargetsFromApp,
+  resolveShellOutletPlacementTargetFromApp
+};

package/server/support/shellOutlets.test.js

@@ -0,0 +1,270 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import test from "node:test";
+import {
+  discoverShellOutletTargetsFromApp,
+  resolveShellOutletPlacementTargetFromApp
+} from "./shellOutlets.js";
+
+async function withTempApp(run) {
+  const appRoot = await mkdtemp(path.join(tmpdir(), "kernel-shell-outlets-"));
+  try {
+    return await run(appRoot);
+  } finally {
+    await rm(appRoot, { recursive: true, force: true });
+  }
+}
+
+async function writeFileInApp(appRoot, relativePath, source) {
+  const absoluteFilePath = path.join(appRoot, relativePath);
+  await mkdir(path.dirname(absoluteFilePath), { recursive: true });
+  await writeFile(absoluteFilePath, source, "utf8");
+}
+
+test("resolveShellOutletPlacementTargetFromApp reads outlets across app Vue files", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeFileInApp(
+      appRoot,
+      "src/components/ShellLayout.vue",
+      `<template>
+  <div>
+    <ShellOutlet host="shell-layout" position="primary-menu" />
+    <ShellOutlet host="shell-layout" position="top-right" />
+  </div>
+</template>
+`
+    );
+    await writeFileInApp(
+      appRoot,
+      "src/pages/admin/workspace/settings/index.vue",
+      `<template>
+  <section>
+    <ShellOutlet host="workspace-settings" position="forms" default />
+  </section>
+</template>
+`
+    );
+
+    const target = await resolveShellOutletPlacementTargetFromApp({
+      appRoot,
+      context: "ui-generator"
+    });
+
+    assert.equal(target.host, "workspace-settings");
+    assert.equal(target.position, "forms");
+  });
+});
+
+test("discoverShellOutletTargetsFromApp includes installed package placement outlets", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeFileInApp(
+      appRoot,
+      "src/components/ShellLayout.vue",
+      `<template>
+  <div>
+    <ShellOutlet host="shell-layout" position="primary-menu" default />
+  </div>
+</template>
+`
+    );
+    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: [
+          { host: "workspace-tools", position: "primary-menu", source: "src/client/components/UsersWorkspaceToolsWidget.vue" }
+        ]
+      }
+    }
+  }
+};
+`
+    );
+
+    const discovered = await discoverShellOutletTargetsFromApp({ appRoot });
+    assert.deepEqual(
+      discovered.targets.map((entry) => entry.id),
+      ["shell-layout:primary-menu", "workspace-tools:primary-menu"]
+    );
+    assert.deepEqual(discovered.targets[1], {
+      id: "workspace-tools:primary-menu",
+      host: "workspace-tools",
+      position: "primary-menu",
+      default: false,
+      sourcePath: "package:@example/users-web:src/client/components/UsersWorkspaceToolsWidget.vue",
+      sourcePackageId: "@example/users-web"
+    });
+
+    const target = await resolveShellOutletPlacementTargetFromApp({
+      appRoot,
+      placement: "workspace-tools:primary-menu",
+      context: "ui-generator"
+    });
+    assert.equal(target.id, "workspace-tools:primary-menu");
+  });
+});
+
+test("discoverShellOutletTargetsFromApp returns targets with sourcePath and default marker", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeFileInApp(
+      appRoot,
+      "src/components/ShellLayout.vue",
+      `<template>
+  <div>
+    <ShellOutlet host="shell-layout" position="primary-menu" />
+  </div>
+</template>
+`
+    );
+    await writeFileInApp(
+      appRoot,
+      "src/pages/admin/workspace/settings/index.vue",
+      `<template>
+  <section>
+    <ShellOutlet host="workspace-settings" position="forms" default />
+  </section>
+</template>
+`
+    );
+
+    const discovered = await discoverShellOutletTargetsFromApp({ appRoot });
+    assert.equal(discovered.defaultTargetId, "workspace-settings:forms");
+    assert.deepEqual(discovered.targets, [
+      {
+        id: "shell-layout:primary-menu",
+        host: "shell-layout",
+        position: "primary-menu",
+        default: false,
+        sourcePath: "src/components/ShellLayout.vue"
+      },
+      {
+        id: "workspace-settings:forms",
+        host: "workspace-settings",
+        position: "forms",
+        default: true,
+        sourcePath: "src/pages/admin/workspace/settings/index.vue"
+      }
+    ]);
+  });
+});
+
+test("resolveShellOutletPlacementTargetFromApp supports explicit placement override", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeFileInApp(
+      appRoot,
+      "src/components/ShellLayout.vue",
+      `<template>
+  <div>
+    <ShellOutlet host="shell-layout" position="primary-menu" default />
+    <ShellOutlet host="shell-layout" position="top-right" />
+  </div>
+</template>
+`
+    );
+
+    const target = await resolveShellOutletPlacementTargetFromApp({
+      appRoot,
+      context: "ui-generator",
+      placement: "shell-layout:top-right"
+    });
+
+    assert.equal(target.host, "shell-layout");
+    assert.equal(target.position, "top-right");
+  });
+});
+
+test("resolveShellOutletPlacementTargetFromApp validates placement format", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeFileInApp(
+      appRoot,
+      "src/components/ShellLayout.vue",
+      `<template>
+  <div>
+    <ShellOutlet host="shell-layout" position="primary-menu" default />
+  </div>
+</template>
+`
+    );
+
+    await assert.rejects(
+      () =>
+        resolveShellOutletPlacementTargetFromApp({
+          appRoot,
+          context: "ui-generator",
+          placement: "invalid-placement"
+        }),
+      /option "placement" must be in "host:position" format/
+    );
+  });
+});
+
+test("resolveShellOutletPlacementTargetFromApp throws when multiple default outlets exist", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeFileInApp(
+      appRoot,
+      "src/components/ShellLayout.vue",
+      `<template>
+  <div>
+    <ShellOutlet host="shell-layout" position="primary-menu" default />
+  </div>
+</template>
+`
+    );
+    await writeFileInApp(
+      appRoot,
+      "src/pages/admin/workspace/settings/index.vue",
+      `<template>
+  <section>
+    <ShellOutlet host="workspace-settings" position="forms" default />
+  </section>
+</template>
+`
+    );
+
+    await assert.rejects(
+      () =>
+        resolveShellOutletPlacementTargetFromApp({
+          appRoot,
+          context: "ui-generator"
+        }),
+      /Multiple default ShellOutlet targets found in app source/
+    );
+  });
+});
+
+test("resolveShellOutletPlacementTargetFromApp requires appRoot", async () => {
+  await assert.rejects(
+    () =>
+      resolveShellOutletPlacementTargetFromApp({
+        appRoot: "",
+        context: "ui-generator"
+      }),
+    /requires appRoot/
+  );
+});

package/shared/support/crudLookup.js

@@ -0,0 +1,114 @@
+import { normalizeText } from "./normalize.js";
+import { normalizePathname } from "../surface/paths.js";
+
+const DEFAULT_CRUD_LOOKUP_CONTAINER_KEY = "lookups";
+
+function normalizeCrudLookupApiPath(value = "") {
+  const normalized = normalizePathname(normalizeText(value));
+  if (!normalized || normalized === "/") {
+    return "";
+  }
+
+  return normalized;
+}
+
+function normalizeCrudLookupNamespace(value = "") {
+  const normalizedApiPath = normalizeCrudLookupApiPath(value);
+  if (!normalizedApiPath) {
+    return "";
+  }
+
+  return normalizedApiPath.slice(1);
+}
+
+function resolveCrudLookupApiPathFromNamespace(value = "") {
+  const normalizedNamespace = normalizeCrudLookupNamespace(value);
+  if (!normalizedNamespace) {
+    return "";
+  }
+
+  return `/${normalizedNamespace}`;
+}
+
+function normalizeCrudLookupContainerKey(
+  value,
+  {
+    defaultValue = DEFAULT_CRUD_LOOKUP_CONTAINER_KEY,
+    context = "crud lookup container key"
+  } = {}
+) {
+  if (value === undefined || value === null || value === "") {
+    return normalizeText(defaultValue) || DEFAULT_CRUD_LOOKUP_CONTAINER_KEY;
+  }
+
+  const normalized = normalizeText(value);
+  if (!normalized) {
+    throw new TypeError(`${context} must be a non-empty string.`);
+  }
+
+  return normalized;
+}
+
+function resolveCrudLookupContainerKey(resource = {}, options = {}) {
+  const source = resource && typeof resource === "object" && !Array.isArray(resource) ? resource : {};
+  const contract = source.contract;
+  if (contract !== undefined && contract !== null && (typeof contract !== "object" || Array.isArray(contract))) {
+    throw new TypeError("crud resource contract must be an object when provided.");
+  }
+
+  const lookup = contract?.lookup;
+  if (lookup !== undefined && lookup !== null && (typeof lookup !== "object" || Array.isArray(lookup))) {
+    throw new TypeError("crud resource contract.lookup must be an object when provided.");
+  }
+
+  return normalizeCrudLookupContainerKey(lookup?.containerKey, options);
+}
+
+function resolveCrudLookupFieldKeys(resource = {}, { allowKeys = [] } = {}) {
+  const source = resource && typeof resource === "object" && !Array.isArray(resource) ? resource : {};
+  const entries = Array.isArray(source.fieldMeta) ? source.fieldMeta : [];
+  const allowedKeySet = new Set(
+    (Array.isArray(allowKeys) ? allowKeys : [])
+      .map((entry) => normalizeText(entry))
+      .filter(Boolean)
+  );
+
+  const keys = [];
+  const seenKeys = new Set();
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      continue;
+    }
+
+    const key = normalizeText(entry.key);
+    if (!key || seenKeys.has(key)) {
+      continue;
+    }
+    if (allowedKeySet.size > 0 && !allowedKeySet.has(key)) {
+      continue;
+    }
+
+    const relation = entry.relation;
+    if (!relation || typeof relation !== "object" || Array.isArray(relation)) {
+      continue;
+    }
+    if (normalizeText(relation.kind).toLowerCase() !== "lookup") {
+      continue;
+    }
+
+    seenKeys.add(key);
+    keys.push(key);
+  }
+
+  return Object.freeze(keys);
+}
+
+export {
+  DEFAULT_CRUD_LOOKUP_CONTAINER_KEY,
+  normalizeCrudLookupApiPath,
+  normalizeCrudLookupNamespace,
+  resolveCrudLookupApiPathFromNamespace,
+  normalizeCrudLookupContainerKey,
+  resolveCrudLookupContainerKey,
+  resolveCrudLookupFieldKeys
+};

package/shared/support/crudLookup.test.js

@@ -0,0 +1,83 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  DEFAULT_CRUD_LOOKUP_CONTAINER_KEY,
+  normalizeCrudLookupApiPath,
+  normalizeCrudLookupNamespace,
+  resolveCrudLookupApiPathFromNamespace,
+  normalizeCrudLookupContainerKey,
+  resolveCrudLookupContainerKey,
+  resolveCrudLookupFieldKeys
+} from "./crudLookup.js";
+
+test("normalizeCrudLookupApiPath normalizes and rejects root", () => {
+  assert.equal(normalizeCrudLookupApiPath("vets"), "/vets");
+  assert.equal(normalizeCrudLookupApiPath("/vets//"), "/vets");
+  assert.equal(normalizeCrudLookupApiPath("/"), "");
+});
+
+test("normalizeCrudLookupNamespace normalizes namespace-like values", () => {
+  assert.equal(normalizeCrudLookupNamespace("vets"), "vets");
+  assert.equal(normalizeCrudLookupNamespace("/customer-categories//"), "customer-categories");
+  assert.equal(normalizeCrudLookupNamespace("/"), "");
+});
+
+test("resolveCrudLookupApiPathFromNamespace maps namespace to api path", () => {
+  assert.equal(resolveCrudLookupApiPathFromNamespace("vets"), "/vets");
+  assert.equal(resolveCrudLookupApiPathFromNamespace("/customer-categories"), "/customer-categories");
+  assert.equal(resolveCrudLookupApiPathFromNamespace(""), "");
+});
+
+test("normalizeCrudLookupContainerKey defaults to canonical value", () => {
+  assert.equal(normalizeCrudLookupContainerKey(undefined), DEFAULT_CRUD_LOOKUP_CONTAINER_KEY);
+  assert.equal(normalizeCrudLookupContainerKey(""), DEFAULT_CRUD_LOOKUP_CONTAINER_KEY);
+});
+
+test("resolveCrudLookupContainerKey reads resource contract override", () => {
+  assert.equal(
+    resolveCrudLookupContainerKey({
+      contract: {
+        lookup: {
+          containerKey: "lookupData"
+        }
+      }
+    }),
+    "lookupData"
+  );
+});
+
+test("resolveCrudLookupContainerKey throws for invalid contract shape", () => {
+  assert.throws(
+    () => resolveCrudLookupContainerKey({ contract: { lookup: [] } }),
+    /contract\.lookup must be an object/
+  );
+});
+
+test("resolveCrudLookupFieldKeys returns lookup field keys with optional allow-list", () => {
+  const resource = {
+    fieldMeta: [
+      {
+        key: "contactId",
+        relation: {
+          kind: "lookup",
+          apiPath: "/contacts",
+          valueKey: "id"
+        }
+      },
+      {
+        key: "status"
+      },
+      {
+        key: "vetId",
+        relation: {
+          kind: "lookup",
+          apiPath: "/vets",
+          valueKey: "id"
+        }
+      }
+    ]
+  };
+
+  assert.deepEqual(resolveCrudLookupFieldKeys(resource), ["contactId", "vetId"]);
+  assert.deepEqual(resolveCrudLookupFieldKeys(resource, { allowKeys: ["vetId", "missing"] }), ["vetId"]);
+});

package/shared/support/shellLayoutTargets.js

@@ -0,0 +1,127 @@
+import { normalizeText } from "./normalize.js";
+
+const SHELL_OUTLET_TAG_PATTERN = /<ShellOutlet\b([^>]*)\/?>/g;
+const ATTRIBUTE_PATTERN = /([:@]?[A-Za-z_][A-Za-z0-9_-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'))?/g;
+
+function parseTagAttributes(attributesSource = "") {
+  const attributes = {};
+  const source = String(attributesSource || "");
+  for (const match of source.matchAll(ATTRIBUTE_PATTERN)) {
+    const attributeName = normalizeText(match[1]);
+    if (!attributeName) {
+      continue;
+    }
+
+    const hasValue = match[2] != null || match[3] != null;
+    const attributeValue = hasValue ? String(match[2] ?? match[3] ?? "") : true;
+    attributes[attributeName] = attributeValue;
+  }
+
+  return attributes;
+}
+
+function normalizeShellOutletTargetId(value = "") {
+  const normalizedValue = normalizeText(value);
+  if (!normalizedValue) {
+    return "";
+  }
+
+  const separatorIndex = normalizedValue.indexOf(":");
+  if (separatorIndex <= 0 || separatorIndex >= normalizedValue.length - 1) {
+    return "";
+  }
+
+  const host = normalizeText(normalizedValue.slice(0, separatorIndex));
+  const position = normalizeText(normalizedValue.slice(separatorIndex + 1));
+  if (!host || !position) {
+    return "";
+  }
+
+  return `${host}:${position}`;
+}
+
+function findShellOutletTargetById(targets = [], targetId = "") {
+  const entries = Array.isArray(targets) ? targets : [];
+  const normalizedTargetId = normalizeShellOutletTargetId(targetId);
+  if (!normalizedTargetId) {
+    return null;
+  }
+
+  return entries.find((entry) => normalizeShellOutletTargetId(entry?.id) === normalizedTargetId) || null;
+}
+
+function describeShellOutletTargets(targets = []) {
+  return (Array.isArray(targets) ? targets : [])
+    .map((entry) => normalizeShellOutletTargetId(entry?.id))
+    .filter(Boolean)
+    .join(", ");
+}
+
+function isDefaultAttributeEnabled(value) {
+  if (value === true) {
+    return true;
+  }
+
+  const normalized = normalizeText(value).toLowerCase();
+  if (!normalized) {
+    return true;
+  }
+
+  return normalized !== "false" && normalized !== "0" && normalized !== "no" && normalized !== "off";
+}
+
+function discoverShellOutletTargetsFromVueSource(source = "", { context = "shell layout" } = {}) {
+  const sourceText = String(source || "");
+  const resolvedContext = normalizeText(context) || "shell layout";
+  const targetById = new Map();
+  let defaultTargetId = "";
+
+  for (const tagMatch of sourceText.matchAll(SHELL_OUTLET_TAG_PATTERN)) {
+    const attributes = parseTagAttributes(tagMatch[1]);
+    const host = normalizeText(attributes.host);
+    const position = normalizeText(attributes.position);
+    if (!host || !position) {
+      continue;
+    }
+
+    const id = normalizeShellOutletTargetId(`${host}:${position}`);
+    if (!id) {
+      continue;
+    }
+    if (targetById.has(id)) {
+      throw new Error(`${resolvedContext} contains duplicate ShellOutlet target "${id}".`);
+    }
+
+    const hasDefaultAttribute = Object.hasOwn(attributes, "default") && isDefaultAttributeEnabled(attributes.default);
+    if (hasDefaultAttribute) {
+      if (defaultTargetId) {
+        throw new Error(
+          `${resolvedContext} defines multiple default ShellOutlet targets: "${defaultTargetId}" and "${id}".`
+        );
+      }
+      defaultTargetId = id;
+    }
+
+    targetById.set(
+      id,
+      Object.freeze({
+        id,
+        host,
+        position,
+        default: hasDefaultAttribute
+      })
+    );
+  }
+
+  return Object.freeze({
+    targets: Object.freeze([...targetById.values()]),
+    defaultTargetId
+  });
+}
+
+export {
+  describeShellOutletTargets,
+  discoverShellOutletTargetsFromVueSource,
+  findShellOutletTargetById,
+  normalizeShellOutletTargetId
+};

package/shared/support/shellLayoutTargets.test.js

@@ -0,0 +1,84 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  describeShellOutletTargets,
+  discoverShellOutletTargetsFromVueSource,
+  findShellOutletTargetById,
+  normalizeShellOutletTargetId
+} from "./shellLayoutTargets.js";
+
+test("normalizeShellOutletTargetId validates host:position tokens", () => {
+  assert.equal(normalizeShellOutletTargetId("shell-layout:primary-menu"), "shell-layout:primary-menu");
+  assert.equal(normalizeShellOutletTargetId(" shell-layout : primary-menu "), "shell-layout:primary-menu");
+  assert.equal(normalizeShellOutletTargetId(""), "");
+  assert.equal(normalizeShellOutletTargetId("shell-layout"), "");
+  assert.equal(normalizeShellOutletTargetId("shell-layout:"), "");
+});
+
+test("discoverShellOutletTargetsFromVueSource resolves legal targets and one default", () => {
+  const source = `
+    <template>
+      <ShellOutlet host="shell-layout" position="top-left" />
+      <ShellOutlet host="shell-layout" position="primary-menu" default />
+      <ShellOutlet host="shell-layout" position="secondary-menu" />
+    </template>
+  `;
+
+  const discovered = discoverShellOutletTargetsFromVueSource(source, {
+    context: "ShellLayout.vue"
+  });
+
+  assert.equal(discovered.defaultTargetId, "shell-layout:primary-menu");
+  assert.deepEqual(
+    discovered.targets.map((entry) => entry.id),
+    ["shell-layout:top-left", "shell-layout:primary-menu", "shell-layout:secondary-menu"]
+  );
+  assert.equal(
+    describeShellOutletTargets(discovered.targets),
+    "shell-layout:top-left, shell-layout:primary-menu, shell-layout:secondary-menu"
+  );
+  assert.deepEqual(
+    findShellOutletTargetById(discovered.targets, " shell-layout : primary-menu "),
+    discovered.targets[1]
+  );
+});
+
+test("discoverShellOutletTargetsFromVueSource throws for duplicate targets", () => {
+  const source = `
+    <template>
+      <ShellOutlet host="shell-layout" position="top-right" />
+      <ShellOutlet host="shell-layout" position="top-right" />
+    </template>
+  `;
+
+  assert.throws(
+    () => discoverShellOutletTargetsFromVueSource(source, { context: "ShellLayout.vue" }),
+    /duplicate ShellOutlet target/
+  );
+});
+
+test("discoverShellOutletTargetsFromVueSource throws for multiple defaults", () => {
+  const source = `
+    <template>
+      <ShellOutlet host="shell-layout" position="primary-menu" default />
+      <ShellOutlet host="shell-layout" position="secondary-menu" default />
+    </template>
+  `;
+
+  assert.throws(
+    () => discoverShellOutletTargetsFromVueSource(source, { context: "ShellLayout.vue" }),
+    /multiple default ShellOutlet targets/
+  );
+});
+
+test("discoverShellOutletTargetsFromVueSource ignores disabled default markers", () => {
+  const source = `
+    <template>
+      <ShellOutlet host="shell-layout" position="primary-menu" default="false" />
+      <ShellOutlet host="shell-layout" position="secondary-menu" />
+    </template>
+  `;
+
+  const discovered = discoverShellOutletTargetsFromVueSource(source, { context: "ShellLayout.vue" });
+  assert.equal(discovered.defaultTargetId, "");
+});

package/shared/validators/cursorPaginationQueryValidator.js

@@ -28,4 +28,6 @@ const cursorPaginationQueryValidator = Object.freeze({
   normalize: normalizeCursorPaginationQuery
 });
 
-export { cursorPaginationQueryValidator };
+export {
+  cursorPaginationQueryValidator
+};

package/shared/validators/cursorPaginationQueryValidator.test.js

@@ -19,3 +19,7 @@ test("cursorPaginationQueryValidator normalizes invalid values to 0", () => {
 test("cursorPaginationQueryValidator keeps absent keys absent", () => {
   assert.deepEqual(cursorPaginationQueryValidator.normalize({}), {});
 });
+
+test("cursorPaginationQueryValidator ignores unsupported query fields", () => {
+  assert.deepEqual(cursorPaginationQueryValidator.normalize({ q: "  to  " }), {});
+});