@jskit-ai/kernel 0.1.4

package/shared/support/linkPath.js

@@ -0,0 +1,67 @@
+import { normalizePathname } from "../surface/paths.js";
+
+const EXTERNAL_LINK_PATTERN = /^[A-Za-z][A-Za-z0-9+.-]*:/;
+
+function isExternalLinkTarget(target = "") {
+  const normalizedTarget = String(target || "").trim();
+  if (!normalizedTarget) {
+    return false;
+  }
+  if (normalizedTarget.startsWith("//")) {
+    return true;
+  }
+  return EXTERNAL_LINK_PATTERN.test(normalizedTarget);
+}
+
+function splitPathQueryHash(target = "") {
+  const normalizedTarget = String(target || "").trim();
+  if (!normalizedTarget) {
+    return Object.freeze({
+      pathname: "",
+      search: "",
+      hash: ""
+    });
+  }
+
+  const hashIndex = normalizedTarget.indexOf("#");
+  const beforeHash = hashIndex >= 0 ? normalizedTarget.slice(0, hashIndex) : normalizedTarget;
+  const hash = hashIndex >= 0 ? normalizedTarget.slice(hashIndex) : "";
+  const queryIndex = beforeHash.indexOf("?");
+  const pathname = queryIndex >= 0 ? beforeHash.slice(0, queryIndex) : beforeHash;
+  const search = queryIndex >= 0 ? beforeHash.slice(queryIndex) : "";
+
+  return Object.freeze({
+    pathname,
+    search,
+    hash
+  });
+}
+
+function resolveLinkPath(basePath = "/", relativePath = "/") {
+  const normalizedRelativePath = String(relativePath || "").trim();
+  if (isExternalLinkTarget(normalizedRelativePath)) {
+    return normalizedRelativePath;
+  }
+
+  const normalizedBasePath = normalizePathname(basePath || "/");
+  if (!normalizedRelativePath) {
+    return normalizedBasePath;
+  }
+
+  const { pathname, search, hash } = splitPathQueryHash(normalizedRelativePath);
+  if (!pathname) {
+    return `${normalizedBasePath}${search}${hash}`;
+  }
+
+  const normalizedPathname = normalizePathname(pathname.startsWith("/") ? pathname : `/${pathname}`);
+  const resolvedPathname =
+    normalizedBasePath === "/"
+      ? normalizedPathname
+      : normalizedPathname === "/"
+        ? normalizedBasePath
+        : `${normalizedBasePath}${normalizedPathname}`;
+
+  return `${resolvedPathname}${search}${hash}`;
+}
+
+export { isExternalLinkTarget, splitPathQueryHash, resolveLinkPath };

package/shared/support/linkPath.test.js

@@ -0,0 +1,35 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { isExternalLinkTarget, splitPathQueryHash, resolveLinkPath } from "./linkPath.js";
+
+test("isExternalLinkTarget detects absolute external targets", () => {
+  assert.equal(isExternalLinkTarget("https://example.com"), true);
+  assert.equal(isExternalLinkTarget("mailto:test@example.com"), true);
+  assert.equal(isExternalLinkTarget("//cdn.example.com/lib.js"), true);
+  assert.equal(isExternalLinkTarget("/contacts"), false);
+});
+
+test("splitPathQueryHash separates pathname, search, and hash", () => {
+  assert.deepEqual(splitPathQueryHash("/members?tab=all#list"), {
+    pathname: "/members",
+    search: "?tab=all",
+    hash: "#list"
+  });
+});
+
+test("resolveLinkPath composes basePath and relative path", () => {
+  assert.equal(resolveLinkPath("/admin/w/acme", "/contacts"), "/admin/w/acme/contacts");
+  assert.equal(resolveLinkPath("/admin/w/acme", "contacts/2"), "/admin/w/acme/contacts/2");
+  assert.equal(resolveLinkPath("/admin/w/acme", "/"), "/admin/w/acme");
+  assert.equal(resolveLinkPath("/", "/contacts"), "/contacts");
+});
+
+test("resolveLinkPath preserves query and hash", () => {
+  assert.equal(resolveLinkPath("/admin/w/acme", "/contacts?sort=asc#top"), "/admin/w/acme/contacts?sort=asc#top");
+  assert.equal(resolveLinkPath("/admin/w/acme", "?tab=profile"), "/admin/w/acme?tab=profile");
+  assert.equal(resolveLinkPath("/admin/w/acme", "#details"), "/admin/w/acme#details");
+});
+
+test("resolveLinkPath keeps external targets unchanged", () => {
+  assert.equal(resolveLinkPath("/admin/w/acme", "https://example.com/docs"), "https://example.com/docs");
+});

package/shared/support/normalize.js

@@ -0,0 +1,116 @@
+function normalizeText(value, { fallback = "" } = {}) {
+  const normalized = String(value || "").trim();
+  return normalized || fallback;
+}
+
+function normalizeLowerText(value, { fallback = "" } = {}) {
+  return normalizeText(value, {
+    fallback
+  }).toLowerCase();
+}
+
+function normalizeQueryToken(value, { fallback = "__none__" } = {}) {
+  const normalized = normalizeText(value).toLowerCase();
+  return normalized || fallback;
+}
+
+function normalizeObject(value, { fallback = {} } = {}) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return { ...fallback };
+  }
+  return value;
+}
+
+function isRecord(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function normalizeArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function normalizeInteger(value, { fallback = 0, min = null, max = null } = {}) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) {
+    return fallback;
+  }
+
+  let next = Math.trunc(numeric);
+  if (Number.isFinite(min) && next < min) {
+    next = min;
+  }
+  if (Number.isFinite(max) && next > max) {
+    next = max;
+  }
+  return next;
+}
+
+function normalizePositiveInteger(value, { fallback = 0 } = {}) {
+  const numeric = Number(value);
+  if (!Number.isInteger(numeric) || numeric < 1) {
+    return fallback;
+  }
+
+  return numeric;
+}
+
+function normalizeOpaqueId(value, { fallback = null } = {}) {
+  if (value == null) {
+    return fallback;
+  }
+
+  if (typeof value === "string") {
+    const normalized = value.trim();
+    return normalized || fallback;
+  }
+
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : fallback;
+  }
+
+  if (typeof value === "bigint") {
+    return String(value);
+  }
+
+  return fallback;
+}
+
+function normalizeOneOf(value, allowedValues = [], fallback = "") {
+  const normalized = normalizeText(value).toLowerCase();
+  const supported = Array.isArray(allowedValues)
+    ? allowedValues.map((entry) => normalizeText(entry).toLowerCase()).filter(Boolean)
+    : [];
+
+  if (supported.includes(normalized)) {
+    return normalized;
+  }
+
+  const normalizedFallback = normalizeText(fallback).toLowerCase();
+  if (normalizedFallback) {
+    return normalizedFallback;
+  }
+
+  return supported[0] || "";
+}
+
+function ensureNonEmptyText(value, label = "value") {
+  const normalized = normalizeText(value);
+  if (!normalized) {
+    throw new TypeError(`${label} is required.`);
+  }
+  return normalized;
+}
+
+export {
+  normalizeText,
+  normalizeLowerText,
+  normalizeQueryToken,
+  normalizeObject,
+  isRecord,
+  normalizeArray,
+  normalizeInteger,
+  normalizePositiveInteger,
+  normalizeOpaqueId,
+  normalizeOneOf,
+  ensureNonEmptyText
+};

package/shared/support/normalize.test.js

@@ -0,0 +1,48 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  normalizeOpaqueId,
+  normalizePositiveInteger,
+  normalizeOneOf,
+  normalizeQueryToken
+} from "./normalize.js";
+
+test("normalizeQueryToken trims, lowercases, and falls back when empty", () => {
+  assert.equal(normalizeQueryToken("  Admin  "), "admin");
+  assert.equal(normalizeQueryToken(""), "__none__");
+  assert.equal(normalizeQueryToken(null), "__none__");
+  assert.equal(normalizeQueryToken("   ", { fallback: "surface" }), "surface");
+});
+
+test("normalizeOneOf returns normalized value when supported", () => {
+  assert.equal(normalizeOneOf(" Compact ", ["compact", "comfortable"], "comfortable"), "compact");
+});
+
+test("normalizeOneOf returns fallback when value is unsupported", () => {
+  assert.equal(normalizeOneOf("wide", ["compact", "comfortable"], "comfortable"), "comfortable");
+});
+
+test("normalizeOneOf falls back to first allowed value when fallback is empty", () => {
+  assert.equal(normalizeOneOf("", ["compact", "comfortable"], ""), "compact");
+});
+
+test("normalizePositiveInteger normalizes valid integers and applies fallback", () => {
+  assert.equal(normalizePositiveInteger("12"), 12);
+  assert.equal(normalizePositiveInteger(0), 0);
+  assert.equal(normalizePositiveInteger(-1), 0);
+  assert.equal(
+    normalizePositiveInteger("abc", {
+      fallback: null
+    }),
+    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(10n), "10");
+  assert.equal(normalizeOpaqueId(""), null);
+  assert.equal(normalizeOpaqueId(null), null);
+});

package/shared/support/packageDescriptor.test.js

@@ -0,0 +1,121 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { loadInstalledPackageDescriptor, resolveDescriptorPathForInstalledPackage } from "../../internal/node/installedPackageDescriptor.js";
+
+async function createFixtureRoot(prefix) {
+  return mkdtemp(path.join(tmpdir(), prefix));
+}
+
+async function writeDescriptorFile(filePath, descriptorSource) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, descriptorSource, "utf8");
+}
+
+test("resolveDescriptorPathForInstalledPackage returns empty string when descriptor is missing and required=false", async () => {
+  const appRoot = await createFixtureRoot("kernel-package-descriptor-missing-");
+  try {
+    const descriptorPath = await resolveDescriptorPathForInstalledPackage({
+      appRoot,
+      packageId: "@example/missing",
+      installedPackageState: {},
+      required: false
+    });
+    assert.equal(descriptorPath, "");
+  } finally {
+    await rm(appRoot, { recursive: true, force: true });
+  }
+});
+
+test("resolveDescriptorPathForInstalledPackage throws when descriptor is missing and required=true", async () => {
+  const appRoot = await createFixtureRoot("kernel-package-descriptor-required-");
+  try {
+    await assert.rejects(
+      () =>
+        resolveDescriptorPathForInstalledPackage({
+          appRoot,
+          packageId: "@example/missing",
+          installedPackageState: {},
+          required: true
+        }),
+      /Unable to resolve package descriptor for @example\/missing\./
+    );
+  } finally {
+    await rm(appRoot, { recursive: true, force: true });
+  }
+});
+
+test("resolveDescriptorPathForInstalledPackage resolves descriptor using source.packagePath", async () => {
+  const appRoot = await createFixtureRoot("kernel-package-descriptor-package-path-");
+  try {
+    const descriptorPath = path.join(appRoot, "packages", "local-example", "package.descriptor.mjs");
+    await writeDescriptorFile(descriptorPath, "export default { packageId: \"@local/example\" };\n");
+
+    const resolvedDescriptorPath = await resolveDescriptorPathForInstalledPackage({
+      appRoot,
+      packageId: "@local/example",
+      installedPackageState: {
+        source: {
+          packagePath: "packages/local-example"
+        }
+      },
+      required: true
+    });
+    assert.equal(resolvedDescriptorPath, descriptorPath);
+  } finally {
+    await rm(appRoot, { recursive: true, force: true });
+  }
+});
+
+test("resolveDescriptorPathForInstalledPackage resolves descriptor using jskit-cli descriptorPath fallback", async () => {
+  const appRoot = await createFixtureRoot("kernel-package-descriptor-jskit-root-");
+  try {
+    const descriptorPath = path.join(
+      appRoot,
+      "node_modules",
+      "@jskit-ai",
+      "jskit-cli",
+      "descriptors",
+      "example.descriptor.mjs"
+    );
+    await writeDescriptorFile(descriptorPath, "export default { packageId: \"@example/test\" };\n");
+
+    const resolvedDescriptorPath = await resolveDescriptorPathForInstalledPackage({
+      appRoot,
+      packageId: "@example/test",
+      installedPackageState: {
+        source: {
+          descriptorPath: "descriptors/example.descriptor.mjs"
+        }
+      },
+      required: true
+    });
+    assert.equal(resolvedDescriptorPath, descriptorPath);
+  } finally {
+    await rm(appRoot, { recursive: true, force: true });
+  }
+});
+
+test("loadInstalledPackageDescriptor loads descriptor payload once resolved", async () => {
+  const appRoot = await createFixtureRoot("kernel-package-descriptor-load-");
+  try {
+    const descriptorPath = path.join(appRoot, "node_modules", "@example", "ready", "package.descriptor.mjs");
+    await writeDescriptorFile(descriptorPath, "export default { packageId: \"@example/ready\", version: \"1.0.0\" };\n");
+
+    const descriptorRecord = await loadInstalledPackageDescriptor({
+      appRoot,
+      packageId: "@example/ready",
+      installedPackageState: {},
+      required: true
+    });
+
+    assert.equal(descriptorRecord.descriptorPath, descriptorPath);
+    assert.equal(descriptorRecord.descriptor.packageId, "@example/ready");
+    assert.equal(descriptorRecord.descriptor.version, "1.0.0");
+  } finally {
+    await rm(appRoot, { recursive: true, force: true });
+  }
+});

package/shared/support/permissions.js

@@ -0,0 +1,50 @@
+import { normalizeText } from "./normalize.js";
+
+function normalizePermissionList(value) {
+  const source = Array.isArray(value) ? value : [value];
+  const unique = new Set();
+
+  for (const entry of source) {
+    const normalizedEntry = normalizeText(entry);
+    if (!normalizedEntry) {
+      continue;
+    }
+    unique.add(normalizedEntry);
+  }
+
+  return [...unique];
+}
+
+function hasPermission(permissionSet = [], permission = "") {
+  const requiredPermission = normalizeText(permission);
+  if (!requiredPermission) {
+    return true;
+  }
+
+  const permissions = normalizePermissionList(permissionSet);
+  if (permissions.includes("*") || permissions.includes(requiredPermission)) {
+    return true;
+  }
+
+  for (const grantedPermission of permissions) {
+    if (!grantedPermission.endsWith(".*")) {
+      continue;
+    }
+
+    const wildcardNamespace = grantedPermission.slice(0, -2);
+    if (!wildcardNamespace) {
+      continue;
+    }
+
+    if (requiredPermission.startsWith(`${wildcardNamespace}.`)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export {
+  normalizePermissionList,
+  hasPermission
+};

package/shared/support/pickOwnProperties.js

@@ -0,0 +1,17 @@
+function pickOwnProperties(source, keys) {
+  if (!source || typeof source !== "object" || Array.isArray(source)) {
+    throw new TypeError("pickOwnProperties requires a plain object source.");
+  }
+
+  const patch = {};
+
+  for (const key of keys) {
+    if (Object.hasOwn(source, key)) {
+      patch[key] = source[key];
+    }
+  }
+
+  return patch;
+}
+
+export { pickOwnProperties };

package/shared/support/pickOwnProperties.test.js

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { pickOwnProperties } from "./pickOwnProperties.js";
+
+test("pickOwnProperties preserves only explicitly present keys", () => {
+  const source = {
+    theme: "dark",
+    avatarUrl: "",
+    invitesEnabled: false,
+    ignored: "x"
+  };
+
+  const patch = pickOwnProperties(source, ["theme", "avatarUrl", "invitesEnabled", "missing"]);
+
+  assert.deepEqual(patch, {
+    theme: "dark",
+    avatarUrl: "",
+    invitesEnabled: false
+  });
+});
+
+test("pickOwnProperties requires caller-normalized object input", () => {
+  assert.throws(() => pickOwnProperties(null, ["theme"]), TypeError);
+  assert.throws(() => pickOwnProperties([], ["theme"]), TypeError);
+});

package/shared/support/policies.js

@@ -0,0 +1,11 @@
+const AUTH_POLICY_PUBLIC = "public";
+const AUTH_POLICY_AUTHENTICATED = "authenticated";
+const ROUTE_VISIBILITY_PUBLIC = AUTH_POLICY_PUBLIC;
+const ROUTE_VISIBILITY_USER = "user";
+
+export {
+  AUTH_POLICY_PUBLIC,
+  AUTH_POLICY_AUTHENTICATED,
+  ROUTE_VISIBILITY_PUBLIC,
+  ROUTE_VISIBILITY_USER
+};

package/shared/support/queryPath.js

@@ -0,0 +1,33 @@
+function splitPathAndHash(path = "") {
+  const normalizedPath = String(path || "").trim();
+  const hashIndex = normalizedPath.indexOf("#");
+  if (hashIndex < 0) {
+    return {
+      pathWithoutHash: normalizedPath,
+      hash: ""
+    };
+  }
+
+  return {
+    pathWithoutHash: normalizedPath.slice(0, hashIndex),
+    hash: normalizedPath.slice(hashIndex)
+  };
+}
+
+function appendQueryString(path = "", queryString = "") {
+  const normalizedPath = String(path || "").trim();
+  if (!normalizedPath) {
+    return "";
+  }
+
+  const normalizedQuery = String(queryString || "").trim().replace(/^\?+/, "");
+  if (!normalizedQuery) {
+    return normalizedPath;
+  }
+
+  const { pathWithoutHash, hash } = splitPathAndHash(normalizedPath);
+  const separator = pathWithoutHash.includes("?") ? "&" : "?";
+  return `${pathWithoutHash}${separator}${normalizedQuery}${hash}`;
+}
+
+export { appendQueryString };

package/shared/support/queryPath.test.js

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { appendQueryString } from "./queryPath.js";
+
+test("appendQueryString appends query to a path without existing search", () => {
+  assert.equal(appendQueryString("/api/conversations", "cursor=2"), "/api/conversations?cursor=2");
+});
+
+test("appendQueryString appends query to a path with existing search", () => {
+  assert.equal(appendQueryString("/api/conversations?status=open", "cursor=2"), "/api/conversations?status=open&cursor=2");
+});
+
+test("appendQueryString preserves hash fragments", () => {
+  assert.equal(appendQueryString("/settings/account#profile", "returnTo=%2Fdashboard"), "/settings/account?returnTo=%2Fdashboard#profile");
+});
+
+test("appendQueryString ignores empty query strings", () => {
+  assert.equal(appendQueryString("/api/conversations", ""), "/api/conversations");
+});

package/shared/support/queryResilience.js

@@ -0,0 +1,34 @@
+const TRANSIENT_QUERY_ERROR_STATUSES = Object.freeze(new Set([0, 502, 503, 504]));
+const MAX_TRANSIENT_QUERY_RETRIES = 2;
+const MAX_TRANSIENT_RETRY_DELAY_MS = 3000;
+
+function normalizeQueryErrorStatus(error) {
+  const status = Number(error?.status || error?.statusCode || 0);
+  return Number.isInteger(status) ? status : 0;
+}
+
+function isTransientQueryError(error) {
+  return TRANSIENT_QUERY_ERROR_STATUSES.has(normalizeQueryErrorStatus(error));
+}
+
+function shouldRetryTransientQueryFailure(failureCount, error) {
+  if (!isTransientQueryError(error)) {
+    return false;
+  }
+  return Number(failureCount) < MAX_TRANSIENT_QUERY_RETRIES;
+}
+
+function transientQueryRetryDelay(attemptIndex) {
+  const normalizedAttempt = Number.isInteger(Number(attemptIndex)) ? Number(attemptIndex) : 1;
+  return Math.min(1000 * 2 ** Math.max(0, normalizedAttempt - 1), MAX_TRANSIENT_RETRY_DELAY_MS);
+}
+
+export {
+  TRANSIENT_QUERY_ERROR_STATUSES,
+  MAX_TRANSIENT_QUERY_RETRIES,
+  MAX_TRANSIENT_RETRY_DELAY_MS,
+  normalizeQueryErrorStatus,
+  isTransientQueryError,
+  shouldRetryTransientQueryFailure,
+  transientQueryRetryDelay
+};

package/shared/support/queryResilience.test.js

@@ -0,0 +1,33 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  isTransientQueryError,
+  shouldRetryTransientQueryFailure,
+  transientQueryRetryDelay,
+  normalizeQueryErrorStatus
+} from "./queryResilience.js";
+
+test("normalizeQueryErrorStatus reads status and statusCode", () => {
+  assert.equal(normalizeQueryErrorStatus({ status: 503 }), 503);
+  assert.equal(normalizeQueryErrorStatus({ statusCode: 504 }), 504);
+  assert.equal(normalizeQueryErrorStatus({}), 0);
+});
+
+test("isTransientQueryError checks transient statuses", () => {
+  assert.equal(isTransientQueryError({ status: 503 }), true);
+  assert.equal(isTransientQueryError({ status: 0 }), true);
+  assert.equal(isTransientQueryError({ status: 401 }), false);
+});
+
+test("shouldRetryTransientQueryFailure allows capped transient retries only", () => {
+  assert.equal(shouldRetryTransientQueryFailure(0, { status: 503 }), true);
+  assert.equal(shouldRetryTransientQueryFailure(1, { status: 502 }), true);
+  assert.equal(shouldRetryTransientQueryFailure(2, { status: 503 }), false);
+  assert.equal(shouldRetryTransientQueryFailure(0, { status: 422 }), false);
+});
+
+test("transientQueryRetryDelay is bounded exponential", () => {
+  assert.equal(transientQueryRetryDelay(1), 1000);
+  assert.equal(transientQueryRetryDelay(2), 2000);
+  assert.equal(transientQueryRetryDelay(5), 3000);
+});