@jskit-ai/kernel 0.1.31 → 0.1.33

package/server/support/pageTargets.test.js

@@ -0,0 +1,326 @@
+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 {
+  deriveDefaultSubpagesHost,
+  normalizePagesRelativeTargetRoot,
+  resolvePageLinkTargetDetails,
+  resolvePageTargetDetails
+} from "./pageTargets.js";
+
+async function withTempApp(run) {
+  const appRoot = await mkdtemp(path.join(tmpdir(), "kernel-page-targets-"));
+  try {
+    return await run(appRoot);
+  } finally {
+    await rm(appRoot, { recursive: true, force: true });
+  }
+}
+
+async function writeFileInApp(appRoot, relativePath, source) {
+  const absoluteFile = path.join(appRoot, relativePath);
+  await mkdir(path.dirname(absoluteFile), { recursive: true });
+  await writeFile(absoluteFile, source, "utf8");
+}
+
+async function writeConfig(appRoot, source) {
+  await writeFileInApp(appRoot, "config/public.js", source);
+}
+
+async function writeShellLayout(appRoot, source = "") {
+  await writeFileInApp(
+    appRoot,
+    "src/components/ShellLayout.vue",
+    source ||
+      `<template>
+  <div>
+    <ShellOutlet host="shell-layout" position="top-right" />
+    <ShellOutlet host="shell-layout" position="primary-menu" default />
+  </div>
+</template>
+`
+  );
+}
+
+test("resolvePageTargetDetails derives the surface and route data from an explicit page file", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "w/[workspaceSlug]/admin", enabled: true }
+  }
+};
+`
+    );
+
+    const pageTarget = await resolvePageTargetDetails({
+      appRoot,
+      targetFile: "w/[workspaceSlug]/admin/catalog/index/products/index.vue",
+      context: "page target"
+    });
+
+    assert.equal(pageTarget.surfaceId, "admin");
+    assert.equal(pageTarget.surfacePagesRoot, "w/[workspaceSlug]/admin");
+    assert.equal(pageTarget.routeUrlSuffix, "/catalog/products");
+    assert.equal(pageTarget.placementId, "ui-generator.page.admin.catalog.products.link");
+    assert.deepEqual(pageTarget.visibleRouteSegments, ["catalog", "products"]);
+    assert.equal(deriveDefaultSubpagesHost(pageTarget), "catalog-products");
+  });
+});
+
+test("resolvePageTargetDetails includes surface in placement ids for identical routes on different surfaces", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    app: { id: "app", pagesRoot: "app", enabled: true },
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+
+    const appPageTarget = await resolvePageTargetDetails({
+      appRoot,
+      targetFile: "app/reports/index.vue",
+      context: "page target"
+    });
+    const adminPageTarget = await resolvePageTargetDetails({
+      appRoot,
+      targetFile: "admin/reports/index.vue",
+      context: "page target"
+    });
+
+    assert.equal(appPageTarget.placementId, "ui-generator.page.app.reports.link");
+    assert.equal(adminPageTarget.placementId, "ui-generator.page.admin.reports.link");
+    assert.notEqual(appPageTarget.placementId, adminPageTarget.placementId);
+  });
+});
+
+test("resolvePageTargetDetails chooses the most specific matching surface pagesRoot", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    app: { id: "app", pagesRoot: "w/[workspaceSlug]", enabled: true },
+    admin: { id: "admin", pagesRoot: "w/[workspaceSlug]/admin", enabled: true }
+  }
+};
+`
+    );
+
+    const pageTarget = await resolvePageTargetDetails({
+      appRoot,
+      targetFile: "w/[workspaceSlug]/admin/catalog/index.vue",
+      context: "page target"
+    });
+
+    assert.equal(pageTarget.surfaceId, "admin");
+    assert.equal(pageTarget.surfacePagesRoot, "w/[workspaceSlug]/admin");
+    assert.equal(pageTarget.surfaceRelativeFilePath, "catalog/index.vue");
+    assert.equal(pageTarget.routeUrlSuffix, "/catalog");
+    assert.equal(pageTarget.placementId, "ui-generator.page.admin.catalog.link");
+  });
+});
+
+test("resolvePageTargetDetails rejects duplicate matching surface pagesRoot definitions", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    adminA: { id: "admin-a", pagesRoot: "w/[workspaceSlug]/admin", enabled: true },
+    adminB: { id: "admin-b", pagesRoot: "w/[workspaceSlug]/admin", enabled: true }
+  }
+};
+`
+    );
+
+    await assert.rejects(
+      () =>
+        resolvePageTargetDetails({
+          appRoot,
+          targetFile: "w/[workspaceSlug]/admin/catalog/index.vue",
+          context: "page target"
+        }),
+      /multiple surfaces share pagesRoot "w\/\[workspaceSlug\]\/admin" \(admin-a, admin-b\)/
+    );
+  });
+});
+
+test("resolvePageTargetDetails rejects target files with a src/pages prefix", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+
+    await assert.rejects(
+      () =>
+        resolvePageTargetDetails({
+          appRoot,
+          targetFile: "src/pages/admin/reports/index.vue",
+          context: "page target"
+        }),
+      /must be relative to src\/pages\/, without the src\/pages\/ prefix/
+    );
+  });
+});
+
+test("normalizePagesRelativeTargetRoot rejects route roots with a src/pages prefix", () => {
+  assert.throws(
+    () =>
+      normalizePagesRelativeTargetRoot("src/pages/admin/customers", {
+        context: "crud-ui-generator",
+        label: 'option "target-root"'
+      }),
+    /must be relative to src\/pages\/, without the src\/pages\/ prefix/
+  );
+});
+
+test("resolvePageLinkTargetDetails falls back to the app default placement target", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
+
+    const details = await resolvePageLinkTargetDetails({
+      appRoot,
+      targetFile: "admin/reports/index.vue",
+      context: "page target"
+    });
+
+    assert.equal(details.pageTarget.surfaceId, "admin");
+    assert.equal(details.placementTarget.host, "shell-layout");
+    assert.equal(details.placementTarget.position, "primary-menu");
+    assert.equal(details.componentToken, "users.web.shell.surface-aware-menu-link-item");
+    assert.equal(details.linkTo, "");
+  });
+});
+
+test("resolvePageLinkTargetDetails inherits a file-route parent subpages host", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
+    await writeFileInApp(
+      appRoot,
+      "src/pages/admin/contacts/[contactId].vue",
+      `<template>
+  <SectionContainerShell>
+    <template #tabs>
+      <ShellOutlet host="contact-view" position="sub-pages" />
+    </template>
+    <RouterView />
+  </SectionContainerShell>
+</template>
+`
+    );
+
+    const details = await resolvePageLinkTargetDetails({
+      appRoot,
+      targetFile: "admin/contacts/[contactId]/notes/index.vue",
+      context: "page target"
+    });
+
+    assert.equal(details.parentHost?.id, "contact-view:sub-pages");
+    assert.equal(details.placementTarget.host, "contact-view");
+    assert.equal(details.placementTarget.position, "sub-pages");
+    assert.equal(details.componentToken, "local.main.ui.tab-link-item");
+    assert.equal(details.linkTo, "./notes");
+  });
+});
+
+test("resolvePageLinkTargetDetails honors explicit placement and link overrides", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
+
+    const details = await resolvePageLinkTargetDetails({
+      appRoot,
+      targetFile: "admin/contacts/[contactId]/index/notes/index.vue",
+      placement: "shell-layout:top-right",
+      componentToken: "custom.link-item",
+      linkTo: "./assistant-notes",
+      context: "page target"
+    });
+
+    assert.equal(details.placementTarget.host, "shell-layout");
+    assert.equal(details.placementTarget.position, "top-right");
+    assert.equal(details.componentToken, "custom.link-item");
+    assert.equal(details.linkTo, "./assistant-notes");
+  });
+});
+
+test("resolvePageLinkTargetDetails inherits an index-route parent subpages host for index children", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
+    await writeFileInApp(
+      appRoot,
+      "src/pages/admin/customers/[customerId]/index.vue",
+      `<template>
+  <SectionContainerShell>
+    <template #tabs>
+      <ShellOutlet host="customer-view" position="sub-pages" />
+    </template>
+    <RouterView />
+  </SectionContainerShell>
+</template>
+`
+    );
+
+    const details = await resolvePageLinkTargetDetails({
+      appRoot,
+      targetFile: "admin/customers/[customerId]/index/pets/index.vue",
+      context: "page target"
+    });
+
+    assert.equal(details.parentHost?.id, "customer-view:sub-pages");
+    assert.equal(details.parentHost?.pageFile, "src/pages/admin/customers/[customerId]/index.vue");
+    assert.equal(details.placementTarget.host, "customer-view");
+    assert.equal(details.placementTarget.position, "sub-pages");
+    assert.equal(details.componentToken, "local.main.ui.tab-link-item");
+    assert.equal(details.linkTo, "./pets");
+  });
+});

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/visibility.js

@@ -49,7 +49,7 @@ function normalizeVisibilityContext(value = {}) {
     scopeKind: normalizedScopeKind,
     requiresActorScope: source.requiresActorScope === true,
     scopeOwnerId: normalizeOpaqueId(source.scopeOwnerId),
-    userOwnerId: normalizeOpaqueId(source.userOwnerId)
+    userId: normalizeOpaqueId(source.userId)
   });
 }
 

package/shared/support/visibility.test.js

@@ -19,20 +19,20 @@ test("normalizeRouteVisibilityToken normalizes visibility tokens for module-leve
 });
 
 test("normalizeVisibilityContext normalizes mode and owner identifiers", () => {
-  assert.deepEqual(normalizeVisibilityContext({ visibility: "user", userOwnerId: "7" }), {
+  assert.deepEqual(normalizeVisibilityContext({ visibility: "user", userId: "7" }), {
     visibility: "user",
     scopeKind: null,
     requiresActorScope: false,
     scopeOwnerId: null,
-    userOwnerId: "7"
+    userId: "7"
   });
 
-  assert.deepEqual(normalizeVisibilityContext({ visibility: "workspace_user", scopeOwnerId: "4", userOwnerId: 9 }), {
+  assert.deepEqual(normalizeVisibilityContext({ visibility: "workspace_user", scopeOwnerId: "4", userId: 9 }), {
     visibility: "workspace_user",
     scopeKind: null,
     requiresActorScope: false,
     scopeOwnerId: "4",
-    userOwnerId: 9
+    userId: "9"
   });
 
   assert.deepEqual(normalizeVisibilityContext({ visibility: "workspace", scopeOwnerId: "0" }), {
@@ -40,6 +40,6 @@ test("normalizeVisibilityContext normalizes mode and owner identifiers", () => {
     scopeKind: null,
     requiresActorScope: false,
     scopeOwnerId: "0",
-    userOwnerId: null
+    userId: null
   });
 });

package/shared/validators/cursorPaginationQueryValidator.js

@@ -1,14 +1,13 @@
 import { Type } from "typebox";
-import { normalizeText } from "../support/normalize.js";
 import { normalizeObjectInput } from "./inputNormalization.js";
-import { positiveIntegerValidator } from "./recordIdParamsValidator.js";
+import { positiveIntegerValidator, recordIdInputSchema, recordIdValidator } from "./recordIdParamsValidator.js";
 
 function normalizeCursorPaginationQuery(input = {}) {
   const source = normalizeObjectInput(input);
   const normalized = {};
 
   if (Object.hasOwn(source, "cursor")) {
-    normalized.cursor = normalizeText(source.cursor);
+    normalized.cursor = recordIdValidator.normalize(source.cursor);
   }
 
   if (Object.hasOwn(source, "limit")) {
@@ -21,7 +20,7 @@ function normalizeCursorPaginationQuery(input = {}) {
 const cursorPaginationQueryValidator = Object.freeze({
   schema: Type.Object(
     {
-      cursor: Type.Optional(positiveIntegerValidator.schema),
+      cursor: Type.Optional(recordIdInputSchema),
       limit: Type.Optional(positiveIntegerValidator.schema)
     },
     { additionalProperties: false }

package/shared/validators/cursorPaginationQueryValidator.test.js

@@ -11,9 +11,8 @@ test("cursorPaginationQueryValidator normalizes numeric strings as cursor text",
 
 test("cursorPaginationQueryValidator schema rejects opaque cursor strings", () => {
   assert.equal(
-    cursorPaginationQueryValidator.schema.properties.cursor.anyOf.some(
-      (entry) => entry.type === "string" && entry.pattern === "^[1-9][0-9]*$"
-    ),
+    cursorPaginationQueryValidator.schema.properties.cursor.type === "string" &&
+      cursorPaginationQueryValidator.schema.properties.cursor.pattern === "^[1-9][0-9]*$",
     true
   );
 });

package/shared/validators/index.js

@@ -8,7 +8,17 @@ export {
 export { mergeObjectSchemas } from "./mergeObjectSchemas.js";
 export { mergeValidators } from "./mergeValidators.js";
 export { nestValidator } from "./nestValidator.js";
-export { recordIdParamsValidator, positiveIntegerValidator } from "./recordIdParamsValidator.js";
+export {
+  RECORD_ID_PATTERN,
+  recordIdSchema,
+  recordIdInputSchema,
+  nullableRecordIdSchema,
+  nullableRecordIdInputSchema,
+  recordIdValidator,
+  nullableRecordIdValidator,
+  recordIdParamsValidator,
+  positiveIntegerValidator
+} from "./recordIdParamsValidator.js";
 export { normalizeSettingsFieldInput, normalizeSettingsFieldOutput } from "./settingsFieldNormalization.js";
 export {
   normalizeRequiredFieldList,

package/shared/validators/recordIdParamsValidator.js

@@ -1,23 +1,51 @@
 import { Type } from "typebox";
 import { normalizeObjectInput } from "./inputNormalization.js";
-import { normalizePositiveInteger, normalizeText } from "../support/normalize.js";
+import { normalizePositiveInteger, normalizeRecordId } from "../support/normalize.js";
 
-function normalizeRecordId(value) {
-  return normalizePositiveInteger(normalizeText(value));
-}
+const RECORD_ID_PATTERN = "^[1-9][0-9]*$";
+
+const recordIdSchema = Type.String({
+  minLength: 1,
+  pattern: RECORD_ID_PATTERN
+});
+
+const recordIdInputSchema = recordIdSchema;
+
+const nullableRecordIdSchema = Type.Union([recordIdSchema, Type.Null()]);
+const nullableRecordIdInputSchema = Type.Union([recordIdInputSchema, Type.Null()]);
 
 const positiveIntegerValidator = Object.freeze({
   schema: Type.Union([
     Type.Integer({ minimum: 1 }),
-    Type.String({ minLength: 1, pattern: "^[1-9][0-9]*$" })
+    Type.String({ minLength: 1, pattern: RECORD_ID_PATTERN })
   ]),
-  normalize: normalizeRecordId
+  normalize(value) {
+    return normalizePositiveInteger(value);
+  }
+});
+
+const recordIdValidator = Object.freeze({
+  schema: recordIdInputSchema,
+  normalize(value) {
+    return normalizeRecordId(value, {
+      fallback: ""
+    });
+  }
+});
+
+const nullableRecordIdValidator = Object.freeze({
+  schema: nullableRecordIdInputSchema,
+  normalize(value) {
+    return normalizeRecordId(value, {
+      fallback: null
+    });
+  }
 });
 
 const recordIdParamsValidator = Object.freeze({
   schema: Type.Object(
     {
-      recordId: Type.Optional(positiveIntegerValidator.schema)
+      recordId: Type.Optional(recordIdInputSchema)
     },
     { additionalProperties: false }
   ),
@@ -26,11 +54,21 @@ const recordIdParamsValidator = Object.freeze({
     const normalized = {};
 
     if (Object.hasOwn(source, "recordId")) {
-      normalized.recordId = normalizeRecordId(source.recordId);
+      normalized.recordId = recordIdValidator.normalize(source.recordId);
     }
 
     return normalized;
   }
 });
 
-export { recordIdParamsValidator, positiveIntegerValidator };
+export {
+  RECORD_ID_PATTERN,
+  recordIdSchema,
+  recordIdInputSchema,
+  nullableRecordIdSchema,
+  nullableRecordIdInputSchema,
+  recordIdValidator,
+  nullableRecordIdValidator,
+  recordIdParamsValidator,
+  positiveIntegerValidator
+};

package/shared/validators/recordIdParamsValidator.test.js

@@ -3,15 +3,18 @@ import assert from "node:assert/strict";
 
 import { recordIdParamsValidator } from "./recordIdParamsValidator.js";
 
-test("recordIdParamsValidator normalizes string id to positive integer", () => {
+test("recordIdParamsValidator normalizes canonical string ids", () => {
   assert.deepEqual(recordIdParamsValidator.normalize({ recordId: "42" }), {
-    recordId: 42
+    recordId: "42"
   });
 });
 
-test("recordIdParamsValidator normalizes invalid id to 0", () => {
+test("recordIdParamsValidator rejects invalid ids", () => {
   assert.deepEqual(recordIdParamsValidator.normalize({ recordId: "nope" }), {
-    recordId: 0
+    recordId: ""
+  });
+  assert.deepEqual(recordIdParamsValidator.normalize({ recordId: 42 }), {
+    recordId: ""
   });
 });