@jskit-ai/kernel 0.1.32 → 0.1.34

package/server/support/shellOutlets.js

@@ -1,5 +1,6 @@
 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 { normalizeObject, normalizeText } from "../../shared/support/normalize.js";
 import { resolveRequiredAppRoot, toPosixPath } from "./path.js";
@@ -7,8 +8,10 @@ import {
   describeShellOutletTargets,
   discoverShellOutletTargetsFromVueSource,
   findShellOutletTargetById,
-  normalizeShellOutletTargetId
+  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";
@@ -52,22 +55,15 @@ function normalizeAppRouteOutletTarget({
   outlet = {},
   sourcePath = ""
 } = {}) {
-  const outletRecord = normalizeObject(outlet);
-  const outletTargetId = normalizeShellOutletTargetId(
-    `${normalizeText(outletRecord.host)}:${normalizeText(outletRecord.position)}`
-  );
-  if (!outletTargetId) {
+  const normalizedTarget = normalizeShellOutletTargetRecord(outlet, {
+    context: sourcePath || "route meta"
+  });
+  if (!normalizedTarget) {
     return null;
   }
-
-  const separatorIndex = outletTargetId.indexOf(":");
-  const host = outletTargetId.slice(0, separatorIndex);
-  const position = outletTargetId.slice(separatorIndex + 1);
   return Object.freeze({
-    id: outletTargetId,
-    host,
-    position,
-    default: isDefaultEnabled(outletRecord.default),
+    ...normalizedTarget,
+    default: isDefaultEnabled(normalizedTarget.default),
     sourcePath
   });
 }
@@ -201,32 +197,67 @@ function normalizePackageOutletTarget({
     return null;
   }
 
-  const outletRecord = normalizeObject(outlet);
-  const outletTargetId = normalizeShellOutletTargetId(
-    `${normalizeText(outletRecord.host)}:${normalizeText(outletRecord.position)}`
-  );
-  if (!outletTargetId) {
+  const normalizedTarget = normalizeShellOutletTargetRecord(outlet, {
+    context: `package:${normalizedPackageId}`
+  });
+  if (!normalizedTarget) {
     return null;
   }
 
-  const separatorIndex = outletTargetId.indexOf(":");
-  const host = outletTargetId.slice(0, separatorIndex);
-  const position = outletTargetId.slice(separatorIndex + 1);
+  const outletRecord = normalizeObject(outlet);
   const source = normalizeText(outletRecord.source);
   const sourcePath = source
     ? `package:${normalizedPackageId}:${toPosixPath(source)}`
     : `package:${normalizedPackageId}${descriptorPath ? `:${toPosixPath(descriptorPath)}` : ""}`;
 
   return Object.freeze({
-    id: outletTargetId,
-    host,
-    position,
+    ...normalizedTarget,
     default: false,
     sourcePath,
     sourcePackageId: normalizedPackageId
   });
 }
 
+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));
@@ -263,6 +294,7 @@ async function discoverShellOutletTargetsFromApp({ appRoot, sourceRoot = "src" }
   const resolvedAppRoot = resolveRequiredAppRoot(appRoot, {
     context: "discoverShellOutletTargetsFromApp"
   });
+  const outletDefaultOverrides = await loadOutletDefaultOverrides(resolvedAppRoot);
 
   const sourceDirectory = path.resolve(resolvedAppRoot, String(sourceRoot || "src"));
   const targetById = new Map();
@@ -331,10 +363,10 @@ async function discoverShellOutletTargetsFromApp({ appRoot, sourceRoot = "src" }
 
   const targets = [...targetById.values()].sort((left, right) => left.id.localeCompare(right.id));
   const normalizedTargets = targets.map((target) =>
-    Object.freeze({
+    applyOutletDefaultOverrides({
       ...target,
       default: target.id === defaultTargetId
-    })
+    }, outletDefaultOverrides)
   );
 
   return Object.freeze({
@@ -348,7 +380,7 @@ async function resolveShellOutletPlacementTargetFromApp({ appRoot, placement = "
   const requestedPlacementOption = normalizeText(placement);
   const requestedPlacementTargetId = normalizeShellOutletTargetId(requestedPlacementOption);
   if (requestedPlacementOption && !requestedPlacementTargetId) {
-    throw new Error(`${resolvedContext} option "placement" must be in "host:position" format.`);
+    throw new Error(`${resolvedContext} option "placement" must be a target in "host:position" format.`);
   }
 
   const discovered = await discoverShellOutletTargetsFromApp({ appRoot, sourceRoot: "src" });
@@ -380,8 +412,8 @@ async function resolveShellOutletPlacementTargetFromApp({ appRoot, placement = "
   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>"}.`
+    `Set one outlet as default (e.g. <ShellOutlet target="shell-layout:primary-menu" default />) ` +
+    `or pass "--placement shell-layout:primary-menu". Available targets: ${availableTargets || "<none>"}.`
   );
 }
 

package/server/support/shellOutlets.test.js

@@ -30,8 +30,8 @@ test("resolveShellOutletPlacementTargetFromApp reads outlets across app Vue file
       "src/components/ShellLayout.vue",
       `<template>
   <div>
-    <ShellOutlet host="shell-layout" position="primary-menu" />
-    <ShellOutlet host="shell-layout" position="top-right" />
+    <ShellOutlet target="shell-layout:primary-menu" />
+    <ShellOutlet target="shell-layout:top-right" />
   </div>
 </template>
 `
@@ -41,7 +41,7 @@ test("resolveShellOutletPlacementTargetFromApp reads outlets across app Vue file
       "src/pages/admin/workspace/settings/index.vue",
       `<template>
   <section>
-    <ShellOutlet host="admin-settings" position="forms" default />
+    <ShellOutlet target="admin-settings:forms" default />
   </section>
 </template>
 `
@@ -52,8 +52,7 @@ test("resolveShellOutletPlacementTargetFromApp reads outlets across app Vue file
       context: "ui-generator"
     });
 
-    assert.equal(target.host, "admin-settings");
-    assert.equal(target.position, "forms");
+    assert.equal(target.id, "admin-settings:forms");
   });
 });
 
@@ -64,7 +63,7 @@ test("discoverShellOutletTargetsFromApp includes installed package placement out
       "src/components/ShellLayout.vue",
       `<template>
   <div>
-    <ShellOutlet host="shell-layout" position="primary-menu" default />
+    <ShellOutlet target="shell-layout:primary-menu" default />
   </div>
 </template>
 `
@@ -98,7 +97,11 @@ test("discoverShellOutletTargetsFromApp includes installed package placement out
     ui: {
       placements: {
         outlets: [
-          { host: "workspace-tools", position: "primary-menu", source: "src/client/components/UsersWorkspaceToolsWidget.vue" }
+          {
+            target: "workspace-tools:primary-menu",
+            defaultLinkComponentToken: "local.main.ui.surface-aware-menu-link-item",
+            source: "src/client/components/UsersWorkspaceToolsWidget.vue"
+          }
         ]
       }
     }
@@ -114,9 +117,8 @@ test("discoverShellOutletTargetsFromApp includes installed package placement out
     );
     assert.deepEqual(discovered.targets[1], {
       id: "workspace-tools:primary-menu",
-      host: "workspace-tools",
-      position: "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"
     });
@@ -130,6 +132,68 @@ 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: {
+      "workspace-tools: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: "workspace-tools: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(
@@ -137,7 +201,7 @@ test("discoverShellOutletTargetsFromApp returns targets with sourcePath and defa
       "src/components/ShellLayout.vue",
       `<template>
   <div>
-    <ShellOutlet host="shell-layout" position="primary-menu" />
+    <ShellOutlet target="shell-layout:primary-menu" />
   </div>
 </template>
 `
@@ -147,7 +211,7 @@ test("discoverShellOutletTargetsFromApp returns targets with sourcePath and defa
       "src/pages/admin/toolbox/index.vue",
       `<template>
   <section>
-    <ShellOutlet host="admin-toolbox" position="widgets" default />
+    <ShellOutlet target="admin-toolbox:widgets" default />
   </section>
 </template>
 `
@@ -158,16 +222,14 @@ test("discoverShellOutletTargetsFromApp returns targets with sourcePath and defa
     assert.deepEqual(discovered.targets, [
       {
         id: "admin-toolbox:widgets",
-        host: "admin-toolbox",
-        position: "widgets",
         default: true,
+        defaultLinkComponentToken: "",
         sourcePath: "src/pages/admin/toolbox/index.vue"
       },
       {
         id: "shell-layout:primary-menu",
-        host: "shell-layout",
-        position: "primary-menu",
         default: false,
+        defaultLinkComponentToken: "",
         sourcePath: "src/components/ShellLayout.vue"
       }
     ]);
@@ -188,8 +250,7 @@ test("discoverShellOutletTargetsFromApp discovers route meta placement outlets",
       "placements": {
         "outlets": [
           {
-            "host": "contact-tools",
-            "position": "sub-pages"
+            "target": "contact-tools:sub-pages"
           }
         ]
       }
@@ -204,9 +265,8 @@ test("discoverShellOutletTargetsFromApp discovers route meta placement outlets",
     assert.deepEqual(discovered.targets, [
       {
         id: "contact-tools:sub-pages",
-        host: "contact-tools",
-        position: "sub-pages",
         default: false,
+        defaultLinkComponentToken: "",
         sourcePath: "src/pages/w/[workspaceSlug]/admin/contacts/[contactId]/contact-tools.vue"
       }
     ]);
@@ -227,8 +287,8 @@ test("resolveShellOutletPlacementTargetFromApp supports explicit placement overr
       "src/components/ShellLayout.vue",
       `<template>
   <div>
-    <ShellOutlet host="shell-layout" position="primary-menu" default />
-    <ShellOutlet host="shell-layout" position="top-right" />
+    <ShellOutlet target="shell-layout:primary-menu" default />
+    <ShellOutlet target="shell-layout:top-right" />
   </div>
 </template>
 `
@@ -240,8 +300,7 @@ test("resolveShellOutletPlacementTargetFromApp supports explicit placement overr
       placement: "shell-layout:top-right"
     });
 
-    assert.equal(target.host, "shell-layout");
-    assert.equal(target.position, "top-right");
+    assert.equal(target.id, "shell-layout:top-right");
   });
 });
 
@@ -252,7 +311,7 @@ test("resolveShellOutletPlacementTargetFromApp validates placement format", asyn
       "src/components/ShellLayout.vue",
       `<template>
   <div>
-    <ShellOutlet host="shell-layout" position="primary-menu" default />
+    <ShellOutlet target="shell-layout:primary-menu" default />
   </div>
 </template>
 `
@@ -265,7 +324,7 @@ test("resolveShellOutletPlacementTargetFromApp validates placement format", asyn
           context: "ui-generator",
           placement: "invalid-placement"
         }),
-      /option "placement" must be in "host:position" format/
+      /option "placement" must be a target in "host:position" format/
     );
   });
 });
@@ -277,7 +336,7 @@ test("resolveShellOutletPlacementTargetFromApp throws when multiple default outl
       "src/components/ShellLayout.vue",
       `<template>
   <div>
-    <ShellOutlet host="shell-layout" position="primary-menu" default />
+    <ShellOutlet target="shell-layout:primary-menu" default />
   </div>
 </template>
 `
@@ -287,7 +346,7 @@ test("resolveShellOutletPlacementTargetFromApp throws when multiple default outl
       "src/pages/admin/workspace/settings/index.vue",
       `<template>
   <section>
-    <ShellOutlet host="admin-settings" position="forms" default />
+    <ShellOutlet target="admin-settings:forms" default />
   </section>
 </template>
 `

package/shared/support/normalize.js

@@ -180,6 +180,34 @@ function normalizePositiveInteger(value, { fallback = 0 } = {}) {
   return numeric;
 }
 
+function normalizeCanonicalRecordIdText(value, { fallback = null } = {}) {
+  if (value == null) {
+    return fallback;
+  }
+
+  const normalized = String(value).trim();
+  return /^[1-9][0-9]*$/.test(normalized) ? normalized : fallback;
+}
+
+function normalizeRecordId(value, { fallback = null } = {}) {
+  if (value == null) {
+    return fallback;
+  }
+
+  if (typeof value === "string") {
+    return normalizeCanonicalRecordIdText(value, { fallback });
+  }
+
+  if (typeof value === "bigint") {
+    if (value < 1n) {
+      return fallback;
+    }
+    return normalizeCanonicalRecordIdText(value, { fallback });
+  }
+
+  return fallback;
+}
+
 function normalizeOpaqueId(value, { fallback = null } = {}) {
   if (value == null) {
     return fallback;
@@ -191,7 +219,7 @@ function normalizeOpaqueId(value, { fallback = null } = {}) {
   }
 
   if (typeof value === "number") {
-    return Number.isFinite(value) ? value : fallback;
+    return Number.isFinite(value) ? String(value) : fallback;
   }
 
   if (typeof value === "bigint") {
@@ -244,6 +272,8 @@ export {
   normalizeUniqueTextList,
   normalizeInteger,
   normalizePositiveInteger,
+  normalizeCanonicalRecordIdText,
+  normalizeRecordId,
   normalizeOpaqueId,
   normalizeOneOf,
   ensureNonEmptyText

package/shared/support/normalize.test.js

@@ -3,11 +3,13 @@ import assert from "node:assert/strict";
 import {
   hasValue,
   normalizeBoolean,
+  normalizeCanonicalRecordIdText,
   normalizeFiniteInteger,
   normalizeFiniteNumber,
   normalizeIfInSource,
   normalizeIfPresent,
   normalizeOrNull,
+  normalizeRecordId,
   normalizeOpaqueId,
   normalizePositiveInteger,
   normalizeOneOf,
@@ -172,10 +174,27 @@ test("normalizeOrNull normalizes non-nullish values and coerces nullish to null"
   );
 });
 
+test("normalizeRecordId accepts canonical string and bigint identifiers only", () => {
+  const unsafeNumericId = Number(9007199254740993n);
+  assert.equal(normalizeRecordId("  7  "), "7");
+  assert.equal(normalizeRecordId(10n), "10");
+  assert.equal(normalizeRecordId(7), null);
+  assert.equal(normalizeRecordId(unsafeNumericId), null);
+  assert.equal(normalizeRecordId(""), null);
+  assert.equal(normalizeRecordId(null), null);
+});
+
+test("normalizeCanonicalRecordIdText validates canonical positive decimal identifiers", () => {
+  assert.equal(normalizeCanonicalRecordIdText("  7  "), "7");
+  assert.equal(normalizeCanonicalRecordIdText("007"), null);
+  assert.equal(normalizeCanonicalRecordIdText("0"), null);
+  assert.equal(normalizeCanonicalRecordIdText("abc"), null);
+});
+
 test("normalizeOpaqueId preserves opaque identifiers", () => {
   assert.equal(normalizeOpaqueId("  user-123  "), "user-123");
-  assert.equal(normalizeOpaqueId(7), 7);
-  assert.equal(normalizeOpaqueId(0), 0);
+  assert.equal(normalizeOpaqueId(7), "7");
+  assert.equal(normalizeOpaqueId(0), "0");
   assert.equal(normalizeOpaqueId(10n), "10");
   assert.equal(normalizeOpaqueId(""), null);
   assert.equal(normalizeOpaqueId(null), null);

package/shared/support/shellLayoutTargets.js

@@ -1,4 +1,7 @@
-import { normalizeText } from "./normalize.js";
+import {
+  normalizeObject,
+  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;
@@ -40,6 +43,21 @@ function normalizeShellOutletTargetId(value = "") {
   return `${host}:${position}`;
 }
 
+function resolveShellOutletTargetParts(
+  {
+    target = ""
+  } = {}
+) {
+  const normalizedTargetId = normalizeShellOutletTargetId(target);
+  if (!normalizedTargetId) {
+    return null;
+  }
+
+  return Object.freeze({
+    id: normalizedTargetId
+  });
+}
+
 function findShellOutletTargetById(targets = [], targetId = "") {
   const entries = Array.isArray(targets) ? targets : [];
   const normalizedTargetId = normalizeShellOutletTargetId(targetId);
@@ -70,6 +88,42 @@ function isDefaultAttributeEnabled(value) {
   return normalized !== "false" && normalized !== "0" && normalized !== "no" && normalized !== "off";
 }
 
+function normalizeShellOutletTargetRecord(
+  value = {},
+  {
+    context = "shell layout"
+  } = {}
+) {
+  const record = normalizeObject(value);
+  const resolvedContext = normalizeText(context) || "shell layout";
+  if (Object.hasOwn(record, "host") || Object.hasOwn(record, "position")) {
+    throw new Error(
+      `${resolvedContext} must declare ShellOutlet targets with "target" only. ` +
+      `Legacy "host" and "position" attributes are not supported.`
+    );
+  }
+
+  const targetParts = resolveShellOutletTargetParts(
+    {
+      target: record.target
+    },
+    { context: resolvedContext }
+  );
+  if (!targetParts) {
+    return null;
+  }
+
+  return Object.freeze({
+    ...targetParts,
+    default:
+      Object.hasOwn(record, "default") &&
+      isDefaultAttributeEnabled(record.default),
+    defaultLinkComponentToken:
+      normalizeText(record.defaultLinkComponentToken) ||
+      normalizeText(record["default-link-component-token"])
+  });
+}
+
 function discoverShellOutletTargetsFromVueSource(source = "", { context = "shell layout" } = {}) {
   const sourceText = String(source || "");
   const resolvedContext = normalizeText(context) || "shell layout";
@@ -78,39 +132,26 @@ function discoverShellOutletTargetsFromVueSource(source = "", { context = "shell
 
   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) {
+    const normalizedTarget = normalizeShellOutletTargetRecord(attributes, {
+      context: resolvedContext
+    });
+    if (!normalizedTarget) {
       continue;
     }
-
-    const id = normalizeShellOutletTargetId(`${host}:${position}`);
-    if (!id) {
-      continue;
-    }
-    if (targetById.has(id)) {
-      throw new Error(`${resolvedContext} contains duplicate ShellOutlet target "${id}".`);
+    if (targetById.has(normalizedTarget.id)) {
+      throw new Error(`${resolvedContext} contains duplicate ShellOutlet target "${normalizedTarget.id}".`);
     }
 
-    const hasDefaultAttribute = Object.hasOwn(attributes, "default") && isDefaultAttributeEnabled(attributes.default);
-    if (hasDefaultAttribute) {
+    if (normalizedTarget.default) {
       if (defaultTargetId) {
         throw new Error(
-          `${resolvedContext} defines multiple default ShellOutlet targets: "${defaultTargetId}" and "${id}".`
+          `${resolvedContext} defines multiple default ShellOutlet targets: "${defaultTargetId}" and "${normalizedTarget.id}".`
         );
       }
-      defaultTargetId = id;
+      defaultTargetId = normalizedTarget.id;
     }
 
-    targetById.set(
-      id,
-      Object.freeze({
-        id,
-        host,
-        position,
-        default: hasDefaultAttribute
-      })
-    );
+    targetById.set(normalizedTarget.id, normalizedTarget);
   }
 
   return Object.freeze({
@@ -123,5 +164,7 @@ export {
   describeShellOutletTargets,
   discoverShellOutletTargetsFromVueSource,
   findShellOutletTargetById,
-  normalizeShellOutletTargetId
+  normalizeShellOutletTargetId,
+  normalizeShellOutletTargetRecord,
+  resolveShellOutletTargetParts
 };