@jskit-ai/kernel 0.1.4

package/shared/actions/registry.js

@@ -0,0 +1,187 @@
+import {
+  createActionRuntimeError,
+  normalizeActionContributor,
+  createActionVersionKey
+} from "./actionDefinitions.js";
+import { executeActionPipeline } from "./pipeline.js";
+
+function normalizeContributors(contributors) {
+  const source = Array.isArray(contributors) ? contributors : [];
+  return source.map((entry) => normalizeActionContributor(entry));
+}
+
+function buildDefinitionIndex(contributors) {
+  const definitions = [];
+  const byVersionKey = new Map();
+  const byActionId = new Map();
+
+  for (const contributor of contributors) {
+    for (const definition of contributor.actions) {
+      const versionKey = createActionVersionKey(definition.id, definition.version);
+      if (byVersionKey.has(versionKey)) {
+        const existing = byVersionKey.get(versionKey);
+        throw createActionRuntimeError(
+          500,
+          `Action definition \"${versionKey}\" is duplicated between contributors \"${existing.contributorId}\" and \"${contributor.contributorId}\".`,
+          {
+            code: "ACTION_DEFINITION_DUPLICATE"
+          }
+        );
+      }
+
+      byVersionKey.set(versionKey, definition);
+      definitions.push(definition);
+
+      if (!byActionId.has(definition.id)) {
+        byActionId.set(definition.id, []);
+      }
+      byActionId.get(definition.id).push(definition);
+    }
+  }
+
+  for (const list of byActionId.values()) {
+    list.sort((left, right) => right.version - left.version);
+  }
+
+  return {
+    definitions: Object.freeze(definitions),
+    byVersionKey,
+    byActionId
+  };
+}
+
+function normalizeRequestedVersion(version) {
+  const parsed = Number(version);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw createActionRuntimeError(400, "Validation failed.", {
+      code: "ACTION_VERSION_INVALID",
+      details: {
+        fieldErrors: {
+          version: "version must be an integer >= 1."
+        }
+      }
+    });
+  }
+
+  return parsed;
+}
+
+function resolveActionDefinition(index, actionId, version) {
+  const normalizedActionId = String(actionId || "").trim();
+  if (!normalizedActionId) {
+    throw createActionRuntimeError(400, "Validation failed.", {
+      code: "ACTION_ID_REQUIRED",
+      details: {
+        fieldErrors: {
+          actionId: "actionId is required."
+        }
+      }
+    });
+  }
+
+  if (version == null) {
+    const versions = index.byActionId.get(normalizedActionId) || [];
+    if (versions.length < 1) {
+      throw createActionRuntimeError(404, "Not found.", {
+        code: "ACTION_NOT_FOUND",
+        details: {
+          actionId: normalizedActionId
+        }
+      });
+    }
+
+    return versions[0];
+  }
+
+  const normalizedVersion = normalizeRequestedVersion(version);
+  const versionKey = createActionVersionKey(normalizedActionId, normalizedVersion);
+  const definition = index.byVersionKey.get(versionKey);
+  if (!definition) {
+    throw createActionRuntimeError(404, "Not found.", {
+      code: "ACTION_NOT_FOUND",
+      details: {
+        actionId: normalizedActionId,
+        version: normalizedVersion
+      }
+    });
+  }
+
+  return definition;
+}
+
+function createActionRegistry({
+  contributors = [],
+  idempotencyAdapter,
+  auditAdapter,
+  observabilityAdapter,
+  logger = console
+} = {}) {
+  const normalizedContributors = normalizeContributors(contributors);
+  const index = buildDefinitionIndex(normalizedContributors);
+
+  async function execute({ actionId, version = null, input = {}, context = {}, deps = {} } = {}) {
+    const definition = resolveActionDefinition(index, actionId, version);
+    const execution = await executeActionPipeline({
+      definition,
+      input,
+      context,
+      deps,
+      idempotencyAdapter,
+      auditAdapter,
+      observabilityAdapter,
+      logger
+    });
+
+    return execution.result;
+  }
+
+  async function executeStream({ actionId, version = null, input = {}, context = {}, deps = {} } = {}) {
+    const definition = resolveActionDefinition(index, actionId, version);
+    if (definition.kind !== "stream") {
+      throw createActionRuntimeError(400, "Validation failed.", {
+        code: "ACTION_STREAM_KIND_REQUIRED",
+        details: {
+          actionId: definition.id,
+          version: definition.version,
+          kind: definition.kind
+        }
+      });
+    }
+
+    const execution = await executeActionPipeline({
+      definition,
+      input,
+      context,
+      deps,
+      idempotencyAdapter,
+      auditAdapter,
+      observabilityAdapter,
+      logger
+    });
+
+    return execution.result;
+  }
+
+  function listDefinitions() {
+    return index.definitions.slice();
+  }
+
+  function getDefinition(actionId, version = null) {
+    return resolveActionDefinition(index, actionId, version);
+  }
+
+  return Object.freeze({
+    execute,
+    executeStream,
+    listDefinitions,
+    getDefinition
+  });
+}
+
+const __testables = {
+  normalizeContributors,
+  buildDefinitionIndex,
+  resolveActionDefinition
+};
+
+export { createActionRegistry, __testables };

package/shared/actions/registry.test.js

@@ -0,0 +1,381 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Type } from "typebox";
+
+import { createActionRegistry } from "./registry.js";
+
+function createPassThroughSchema() {
+  return {
+    parse(value) {
+      return value;
+    }
+  };
+}
+
+test("action registry executes latest version by default", async () => {
+  const calls = [];
+
+  const registry = createActionRegistry({
+    contributors: [
+      {
+        contributorId: "tests.settings",
+        domain: "settings",
+        actions: [
+          {
+            id: "settings.read",
+            version: 1,
+            domain: "settings",
+            kind: "query",
+            channels: ["api"],
+            surfaces: ["app", "admin", "console"],
+            inputValidator: { schema: createPassThroughSchema() },
+            idempotency: "none",
+            audit: {
+              actionName: "settings.read"
+            },
+            observability: {},
+            async execute() {
+              calls.push("version-one");
+              return {
+                version: 1
+              };
+            }
+          },
+          {
+            id: "settings.read",
+            version: 2,
+            domain: "settings",
+            kind: "query",
+            channels: ["api"],
+            surfaces: ["app", "admin", "console"],
+            inputValidator: { schema: createPassThroughSchema() },
+            idempotency: "none",
+            audit: {
+              actionName: "settings.read"
+            },
+            observability: {},
+            async execute() {
+              calls.push("v2");
+              return {
+                version: 2
+              };
+            }
+          }
+        ]
+      }
+    ]
+  });
+
+  const result = await registry.execute({
+    actionId: "settings.read",
+    input: {},
+    context: {
+      channel: "api",
+      surface: "app",
+      permissions: ["settings.read"]
+    }
+  });
+
+  assert.deepEqual(result, {
+    version: 2
+  });
+  assert.deepEqual(calls, ["v2"]);
+});
+
+test("action registry merges action input validators", async () => {
+  const registry = createActionRegistry({
+    contributors: [
+      {
+        contributorId: "tests.workspace",
+        domain: "workspace",
+        actions: [
+          {
+            id: "workspace.settings.update",
+            version: 1,
+            domain: "workspace",
+            kind: "command",
+            channels: ["api"],
+            surfaces: ["app"],
+            inputValidator: [
+              {
+                schema: Type.Object(
+                  {
+                    workspaceSlug: Type.Optional(Type.String({ minLength: 1 }))
+                  },
+                  { additionalProperties: false }
+                ),
+                normalize(input = {}) {
+                  if (!Object.hasOwn(input, "workspaceSlug")) {
+                    return {};
+                  }
+
+                  return {
+                    workspaceSlug: String(input.workspaceSlug || "").trim().toLowerCase()
+                  };
+                }
+              },
+              {
+                schema: Type.Object(
+                  {
+                    invitesEnabled: Type.Optional(Type.Boolean())
+                  },
+                  { additionalProperties: false }
+                ),
+                normalize(input = {}) {
+                  if (!Object.hasOwn(input, "invitesEnabled")) {
+                    return {};
+                  }
+
+                  return {
+                    invitesEnabled: input.invitesEnabled === true
+                  };
+                }
+              }
+            ],
+            idempotency: "optional",
+            audit: {
+              actionName: "workspace.settings.update"
+            },
+            observability: {},
+            async execute(input) {
+              return input;
+            }
+          }
+        ]
+      }
+    ]
+  });
+
+  const result = await registry.execute({
+    actionId: "workspace.settings.update",
+    input: {
+      workspaceSlug: "  ACME  ",
+      invitesEnabled: true
+    },
+    context: {
+      channel: "api",
+      surface: "app",
+      permissions: []
+    }
+  });
+
+  assert.deepEqual(result, {
+    workspaceSlug: "acme",
+    invitesEnabled: true
+  });
+});
+
+test("action registry fails startup on duplicate action id + version", () => {
+  assert.throws(
+    () =>
+      createActionRegistry({
+        contributors: [
+          {
+            contributorId: "tests.a",
+            domain: "settings",
+            actions: [
+              {
+                id: "settings.profile.update",
+                version: 1,
+                domain: "settings",
+                kind: "command",
+                channels: ["api"],
+                surfaces: ["app"],
+                inputValidator: { schema: createPassThroughSchema() },
+                idempotency: "optional",
+                audit: {
+                  actionName: "settings.profile.update"
+                },
+                observability: {},
+                async execute() {
+                  return {
+                    ok: true
+                  };
+                }
+              }
+            ]
+          },
+          {
+            contributorId: "tests.b",
+            domain: "settings",
+            actions: [
+              {
+                id: "settings.profile.update",
+                version: 1,
+                domain: "settings",
+                kind: "command",
+                channels: ["api"],
+                surfaces: ["app"],
+                inputValidator: { schema: createPassThroughSchema() },
+                idempotency: "optional",
+                audit: {
+                  actionName: "settings.profile.update"
+                },
+                observability: {},
+                async execute() {
+                  return {
+                    ok: true
+                  };
+                }
+              }
+            ]
+          }
+        ]
+      }),
+    /duplicated/
+  );
+});
+
+test("action registry rejects invalid version requests", async () => {
+  const registry = createActionRegistry({
+    contributors: [
+      {
+        contributorId: "tests.settings",
+        domain: "settings",
+        actions: [
+          {
+            id: "settings.read",
+            version: 1,
+            domain: "settings",
+            kind: "query",
+            channels: ["api"],
+            surfaces: ["app"],
+            inputValidator: { schema: createPassThroughSchema() },
+            idempotency: "none",
+            audit: {
+              actionName: "settings.read"
+            },
+            observability: {},
+            async execute() {
+              return {
+                ok: true
+              };
+            }
+          }
+        ]
+      }
+    ]
+  });
+
+  await assert.rejects(
+    () => registry.execute({ actionId: "settings.read", version: "invalid" }),
+    (error) => {
+      assert.equal(error.code, "ACTION_VERSION_INVALID");
+      assert.deepEqual(error.details?.fieldErrors, {
+        version: "version must be an integer >= 1."
+      });
+      return true;
+    }
+  );
+
+  await assert.rejects(
+    () => registry.execute({ actionId: "settings.read", version: 0 }),
+    (error) => {
+      assert.equal(error.code, "ACTION_VERSION_INVALID");
+      return true;
+    }
+  );
+});
+
+test("action registry ignores unknown legacy fields", async () => {
+  const registry = createActionRegistry({
+    contributors: [
+      {
+        contributorId: "tests.internal",
+        domain: "settings",
+        actions: [
+          {
+            id: "settings.internal.ping",
+            version: 1,
+            domain: "settings",
+            kind: "query",
+            channels: ["api", "internal"],
+            surfaces: ["app"],
+            consoleUsersOnly: true,
+            inputValidator: { schema: createPassThroughSchema() },
+            idempotency: "none",
+            audit: {
+              actionName: "settings.internal.ping"
+            },
+            observability: {},
+            async execute() {
+              return { ok: true };
+            }
+          }
+        ]
+      }
+    ]
+  });
+
+  const result = await registry.execute({
+    actionId: "settings.internal.ping",
+    context: {
+      channel: "api",
+      surface: "app"
+    }
+  });
+  assert.deepEqual(result, { ok: true });
+});
+
+test("action registry enforces action-level permissions", async () => {
+  const registry = createActionRegistry({
+    contributors: [
+      {
+        contributorId: "tests.permissions",
+        domain: "workspace",
+        actions: [
+          {
+            id: "workspace.settings.update",
+            version: 1,
+            domain: "workspace",
+            kind: "command",
+            channels: ["api", "internal"],
+            surfaces: ["app"],
+            permission: {
+              require: "all",
+              permissions: ["workspace.settings.update"]
+            },
+            inputValidator: { schema: createPassThroughSchema() },
+            idempotency: "optional",
+            audit: {
+              actionName: "workspace.settings.update"
+            },
+            observability: {},
+            async execute() {
+              return { ok: true };
+            }
+          }
+        ]
+      }
+    ]
+  });
+
+  await assert.rejects(
+    () =>
+      registry.execute({
+        actionId: "workspace.settings.update",
+        context: {
+          channel: "api",
+          surface: "app",
+          actor: { id: 7 },
+          permissions: ["workspace.settings.view"]
+        }
+      }),
+    (error) => {
+      assert.equal(error.code, "ACTION_PERMISSION_DENIED");
+      return true;
+    }
+  );
+
+  const allowed = await registry.execute({
+    actionId: "workspace.settings.update",
+    context: {
+      channel: "api",
+      surface: "app",
+      actor: { id: 7 },
+      permissions: ["workspace.settings.update"]
+    }
+  });
+
+  assert.deepEqual(allowed, { ok: true });
+});

package/shared/actions/requestMeta.js

@@ -0,0 +1,36 @@
+import { normalizeText } from "./textNormalization.js";
+
+const DEFAULT_FIELDS = Object.freeze(["requestId", "commandId", "idempotencyKey", "ip", "userAgent", "request"]);
+
+function normalizeRequestMeta(requestMeta = {}, { fields = DEFAULT_FIELDS, emptyAsNull = false } = {}) {
+  const source = requestMeta && typeof requestMeta === "object" ? requestMeta : {};
+  const fieldList = Array.isArray(fields) && fields.length > 0 ? fields : DEFAULT_FIELDS;
+
+  const normalizeValue = (value) => {
+    const normalized = normalizeText(value);
+    if (emptyAsNull && !normalized) {
+      return null;
+    }
+    return normalized;
+  };
+
+  const normalized = {
+    ...source
+  };
+  for (const field of fieldList) {
+    if (field === "request") {
+      normalized.request = source.request || null;
+      continue;
+    }
+    if (field === "logger") {
+      normalized.logger = source.logger && typeof source.logger.warn === "function" ? source.logger : null;
+      continue;
+    }
+
+    normalized[field] = normalizeValue(source[field]);
+  }
+
+  return normalized;
+}
+
+export { normalizeRequestMeta };

package/shared/actions/textNormalization.js

@@ -0,0 +1,3 @@
+import { normalizeText, normalizeLowerText } from "../support/normalize.js";
+
+export { normalizeText, normalizeLowerText };

package/shared/actions/withActionDefaults.js

@@ -0,0 +1,34 @@
+import { normalizeObject } from "../support/normalize.js";
+
+function withActionDefaults(actions = [], defaults = {}) {
+  const sourceActions = Array.isArray(actions) ? actions : [];
+  const sourceDefaults = normalizeObject(defaults);
+  const defaultDependencies = normalizeObject(sourceDefaults.dependencies);
+  const hasDefaultDependencies = Object.keys(defaultDependencies).length > 0;
+  const hasDefaultDomain = Object.hasOwn(sourceDefaults, "domain");
+
+  return Object.freeze(
+    sourceActions.map((entry) => {
+      const action = normalizeObject(entry);
+      const actionDependencies = normalizeObject(action.dependencies);
+      const next = {
+        ...action
+      };
+
+      if (hasDefaultDomain && !Object.hasOwn(next, "domain")) {
+        next.domain = sourceDefaults.domain;
+      }
+
+      if (hasDefaultDependencies || Object.keys(actionDependencies).length > 0) {
+        next.dependencies = Object.freeze({
+          ...defaultDependencies,
+          ...actionDependencies
+        });
+      }
+
+      return Object.freeze(next);
+    })
+  );
+}
+
+export { withActionDefaults };

package/shared/index.js

@@ -0,0 +1,2 @@
+export { resolveLinkPath } from "./support/linkPath.js";
+export { normalizePathname } from "./surface/apiPaths.js";