@jskit-ai/kernel 0.1.22 → 0.1.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/kernel",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "type": "module",
   "dependencies": {
     "typebox": "^1.0.81"

package/server/http/lib/kernel.test.js

@@ -134,7 +134,7 @@ test("registerRoutes attaches request.executeAction and applies action context c
               slug: "main"
             };
             request.membership = {
-              roleId: "owner"
+              roleSid: "owner"
             };
           }
         ],
@@ -191,7 +191,7 @@ test("registerRoutes attaches request.executeAction and applies action context c
   assert.equal(observed[0].context.actor?.id, 7);
   assert.deepEqual(observed[0].context.permissions, ["settings.read"]);
   assert.equal(observed[0].context.workspace?.id, 10);
-  assert.equal(observed[0].context.membership?.roleId, "owner");
+  assert.equal(observed[0].context.membership?.roleSid, "owner");
   assert.equal(observed[0].context.surface, "coffie");
   assert.equal(observed[0].context.channel, "api");
   assert.equal(observed[0].context.requestMeta.commandId, "cmd-1");

package/server/support/shellOutlets.js

@@ -12,6 +12,125 @@ import {
 
 const VUE_DISCOVERY_IGNORED_ERROR_CODES = new Set(["ENOENT", "ENOTDIR", "EACCES", "EPERM"]);
 const LOCK_FILE_RELATIVE_PATH = ".jskit/lock.json";
+const ROUTE_TAG_PATTERN = /<route\b([^>]*)>([\s\S]*?)<\/route>/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 isDefaultEnabled(value) {
+  if (value === true) {
+    return true;
+  }
+  if (value === false || value == null) {
+    return false;
+  }
+
+  const normalized = normalizeText(value).toLowerCase();
+  if (!normalized) {
+    return false;
+  }
+
+  return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}
+
+function normalizeAppRouteOutletTarget({
+  outlet = {},
+  sourcePath = ""
+} = {}) {
+  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);
+  return Object.freeze({
+    id: outletTargetId,
+    host,
+    position,
+    default: isDefaultEnabled(outletRecord.default),
+    sourcePath
+  });
+}
+
+function discoverRouteMetaOutletTargetsFromVueSource(source = "", { context = "shell layout" } = {}) {
+  const sourceText = String(source || "");
+  const resolvedContext = normalizeText(context) || "shell layout";
+  const targetById = new Map();
+  let defaultTargetId = "";
+
+  for (const routeTagMatch of sourceText.matchAll(ROUTE_TAG_PATTERN)) {
+    const routeTagAttributes = parseTagAttributes(routeTagMatch[1]);
+    const routeTagLanguage = normalizeText(routeTagAttributes.lang).toLowerCase();
+    if (routeTagLanguage !== "json") {
+      continue;
+    }
+
+    const routeMetaSource = String(routeTagMatch[2] || "").trim();
+    if (!routeMetaSource) {
+      continue;
+    }
+
+    let routeMetaRecord = null;
+    try {
+      routeMetaRecord = JSON.parse(routeMetaSource);
+    } catch (error) {
+      throw new Error(
+        `${resolvedContext} contains invalid <route lang="json"> block: ${String(error?.message || error || "unknown error")}`
+      );
+    }
+
+    const routeMeta = normalizeObject(normalizeObject(routeMetaRecord).meta);
+    const jskitMeta = normalizeObject(routeMeta.jskit);
+    const placementsMeta = normalizeObject(jskitMeta.placements);
+    const outlets = Array.isArray(placementsMeta.outlets) ? placementsMeta.outlets : [];
+    for (const outlet of outlets) {
+      const normalizedTarget = normalizeAppRouteOutletTarget({
+        outlet,
+        sourcePath: resolvedContext
+      });
+      if (!normalizedTarget) {
+        continue;
+      }
+      if (targetById.has(normalizedTarget.id)) {
+        throw new Error(`${resolvedContext} contains duplicate route meta placement target "${normalizedTarget.id}".`);
+      }
+      if (normalizedTarget.default === true) {
+        if (defaultTargetId && defaultTargetId !== normalizedTarget.id) {
+          throw new Error(
+            `${resolvedContext} defines multiple default route meta placement targets: "${defaultTargetId}" and "${normalizedTarget.id}".`
+          );
+        }
+        defaultTargetId = normalizedTarget.id;
+      }
+      targetById.set(normalizedTarget.id, normalizedTarget);
+    }
+  }
+
+  return Object.freeze({
+    targets: Object.freeze([...targetById.values()]),
+    defaultTargetId
+  });
+}
 
 async function collectVueFilePaths(rootDirectoryPath) {
   const absoluteRoot = path.resolve(String(rootDirectoryPath || ""));
@@ -154,15 +273,27 @@ async function discoverShellOutletTargetsFromApp({ appRoot, sourceRoot = "src" }
   for (const absoluteFilePath of vueFiles) {
     const relativePath = toPosixPath(path.relative(resolvedAppRoot, absoluteFilePath));
     const source = await readFile(absoluteFilePath, "utf8");
-    if (!source.includes("<ShellOutlet")) {
+    if (!source.includes("<ShellOutlet") && !source.includes("<route")) {
       continue;
     }
 
-    const discovered = discoverShellOutletTargetsFromVueSource(source, {
-      context: relativePath
-    });
-    const targets = Array.isArray(discovered.targets) ? discovered.targets : [];
-    for (const target of targets) {
+    const discoveredShellOutlets = source.includes("<ShellOutlet")
+      ? discoverShellOutletTargetsFromVueSource(source, {
+          context: relativePath
+        })
+      : { targets: [], defaultTargetId: "" };
+    const discoveredRouteMetaOutlets = source.includes("<route")
+      ? discoverRouteMetaOutletTargetsFromVueSource(source, {
+          context: relativePath
+        })
+      : { targets: [], defaultTargetId: "" };
+    const discoveredTargets = [
+      ...(Array.isArray(discoveredShellOutlets.targets) ? discoveredShellOutlets.targets : []),
+      ...(Array.isArray(discoveredRouteMetaOutlets.targets)
+        ? discoveredRouteMetaOutlets.targets
+        : [])
+    ];
+    for (const target of discoveredTargets) {
       if (!targetById.has(target.id)) {
         targetById.set(
           target.id,
@@ -174,20 +305,21 @@ async function discoverShellOutletTargetsFromApp({ appRoot, sourceRoot = "src" }
       }
     }
 
-    const discoveredDefaultTargetId = normalizeShellOutletTargetId(discovered.defaultTargetId);
-    if (!discoveredDefaultTargetId) {
-      continue;
-    }
+    const discoveredDefaultTargetIds = [
+      normalizeShellOutletTargetId(discoveredShellOutlets.defaultTargetId),
+      normalizeShellOutletTargetId(discoveredRouteMetaOutlets.defaultTargetId)
+    ].filter(Boolean);
+    for (const discoveredDefaultTargetId of discoveredDefaultTargetIds) {
+      if (defaultTargetId && discoveredDefaultTargetId !== defaultTargetId) {
+        throw new Error(
+          `Multiple default ShellOutlet targets found in app source: "${defaultTargetId}" (${defaultTargetSource}) and ` +
+          `"${discoveredDefaultTargetId}" (${relativePath}).`
+        );
+      }
 
-    if (defaultTargetId && discoveredDefaultTargetId !== defaultTargetId) {
-      throw new Error(
-        `Multiple default ShellOutlet targets found in app source: "${defaultTargetId}" (${defaultTargetSource}) and ` +
-        `"${discoveredDefaultTargetId}" (${relativePath}).`
-      );
+      defaultTargetId = discoveredDefaultTargetId;
+      defaultTargetSource = relativePath;
     }
-
-    defaultTargetId = discoveredDefaultTargetId;
-    defaultTargetSource = relativePath;
   }
 
   const packageTargets = await collectInstalledPackageOutletTargets(resolvedAppRoot);

package/server/support/shellOutlets.test.js

@@ -174,6 +174,52 @@ test("discoverShellOutletTargetsFromApp returns targets with sourcePath and defa
   });
 });
 
+test("discoverShellOutletTargetsFromApp discovers route meta placement outlets", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeFileInApp(
+      appRoot,
+      "src/pages/w/[workspaceSlug]/admin/contacts/[contactId]/contact-tools.vue",
+      `<template><section /></template>
+
+<route lang="json">
+{
+  "meta": {
+    "jskit": {
+      "placements": {
+        "outlets": [
+          {
+            "host": "contact-tools",
+            "position": "sub-pages"
+          }
+        ]
+      }
+    }
+  }
+}
+</route>
+`
+    );
+
+    const discovered = await discoverShellOutletTargetsFromApp({ appRoot });
+    assert.deepEqual(discovered.targets, [
+      {
+        id: "contact-tools:sub-pages",
+        host: "contact-tools",
+        position: "sub-pages",
+        default: false,
+        sourcePath: "src/pages/w/[workspaceSlug]/admin/contacts/[contactId]/contact-tools.vue"
+      }
+    ]);
+
+    const target = await resolveShellOutletPlacementTargetFromApp({
+      appRoot,
+      placement: "contact-tools:sub-pages",
+      context: "ui-generator"
+    });
+    assert.equal(target.id, "contact-tools:sub-pages");
+  });
+});
+
 test("resolveShellOutletPlacementTargetFromApp supports explicit placement override", async () => {
   await withTempApp(async (appRoot) => {
     await writeFileInApp(

package/shared/actions/executionContext.test.js

@@ -42,11 +42,11 @@ test("normalizeExecutionContext keeps actor payload generic", () => {
     actor: {
       id: "user_1",
       email: "UPPER@EXAMPLE.COM",
-      roleId: "OWNER",
+      roleSid: "OWNER",
       customFlag: true
     },
     membership: {
-      roleId: "OWNER",
+      roleSid: "OWNER",
       status: "ACTIVE",
       extra: "x"
     }
@@ -55,11 +55,11 @@ test("normalizeExecutionContext keeps actor payload generic", () => {
   assert.deepEqual(context.actor, {
     id: "user_1",
     email: "UPPER@EXAMPLE.COM",
-    roleId: "OWNER",
+    roleSid: "OWNER",
     customFlag: true
   });
   assert.deepEqual(context.membership, {
-    roleId: "OWNER",
+    roleSid: "OWNER",
     status: "ACTIVE",
     extra: "x"
   });

package/shared/support/normalize.js

@@ -3,6 +3,18 @@ function normalizeText(value, { fallback = "" } = {}) {
   return normalized || fallback;
 }
 
+function hasValue(value) {
+  if (value == null) {
+    return false;
+  }
+
+  if (typeof value === "string") {
+    return normalizeText(value).length > 0;
+  }
+
+  return true;
+}
+
 function normalizeBoolean(value) {
   if (typeof value === "boolean") {
     return value;
@@ -88,7 +100,31 @@ function normalizeIfInSource(source, normalized, fieldName, normalizer = (value)
     return normalized;
   }
 
-  normalized[normalizedFieldName] = normalizer(sourceValue);
+  try {
+    normalized[normalizedFieldName] = normalizer(sourceValue);
+  } catch (error) {
+    const normalizedMessage = normalizeText(error?.message, {
+      fallback: `${normalizedFieldName} is invalid.`
+    });
+    const sourceDetails = isRecord(error?.details) ? error.details : {};
+    const sourceFieldErrors = isRecord(error?.fieldErrors)
+      ? { ...error.fieldErrors }
+      : isRecord(sourceDetails.fieldErrors)
+        ? { ...sourceDetails.fieldErrors }
+        : {};
+
+    if (!normalizeText(sourceFieldErrors[normalizedFieldName])) {
+      sourceFieldErrors[normalizedFieldName] = normalizedMessage;
+    }
+
+    const normalizedError = error instanceof Error ? error : new Error(normalizedMessage);
+    normalizedError.fieldErrors = sourceFieldErrors;
+    normalizedError.details = {
+      ...sourceDetails,
+      fieldErrors: sourceFieldErrors
+    };
+    throw normalizedError;
+  }
   return normalized;
 }
 
@@ -193,6 +229,7 @@ function ensureNonEmptyText(value, label = "value") {
 
 export {
   normalizeText,
+  hasValue,
   normalizeBoolean,
   normalizeFiniteNumber,
   normalizeFiniteInteger,

package/shared/support/normalize.test.js

@@ -1,6 +1,7 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import {
+  hasValue,
   normalizeBoolean,
   normalizeFiniteInteger,
   normalizeFiniteNumber,
@@ -15,6 +16,19 @@ import {
   normalizeUniqueTextList
 } from "./normalize.js";
 
+test("hasValue returns false for nullish and blank text, true otherwise", () => {
+  assert.equal(hasValue(null), false);
+  assert.equal(hasValue(undefined), false);
+  assert.equal(hasValue(""), false);
+  assert.equal(hasValue("   "), false);
+  assert.equal(hasValue("0"), true);
+  assert.equal(hasValue("-"), true);
+  assert.equal(hasValue(0), true);
+  assert.equal(hasValue(false), true);
+  assert.equal(hasValue([]), true);
+  assert.equal(hasValue({}), true);
+});
+
 test("normalizeQueryToken trims, lowercases, and falls back when empty", () => {
   assert.equal(normalizeQueryToken("  Admin  "), "admin");
   assert.equal(normalizeQueryToken(""), "__none__");
@@ -100,6 +114,29 @@ test("normalizeIfInSource passes through nullish values without normalizer", ()
   });
 });
 
+test("normalizeIfInSource annotates thrown normalizer errors with fieldErrors", () => {
+  const source = {
+    temperament: "unknowne"
+  };
+  const normalized = {};
+
+  assert.throws(
+    () =>
+      normalizeIfInSource(source, normalized, "temperament", () => {
+        throw new Error("Invalid pet temperament \"unknowne\".");
+      }),
+    (error) => {
+      assert.deepEqual(error?.fieldErrors, {
+        temperament: "Invalid pet temperament \"unknowne\"."
+      });
+      assert.deepEqual(error?.details?.fieldErrors, {
+        temperament: "Invalid pet temperament \"unknowne\"."
+      });
+      return true;
+    }
+  );
+});
+
 test("normalizeIfInSource validates target and function arguments", () => {
   assert.throws(
     () => normalizeIfInSource({ firstName: "Ada" }, null, "firstName", normalizeText),