@jskit-ai/kernel 0.1.4

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

@@ -0,0 +1,474 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { createRouter } from "./router.js";
+import { compileRouteValidator, defineRouteValidator, resolveRouteValidatorOptions } from "./routeValidator.js";
+
+test("defineRouteValidator compiles body/query/params and maps query schema to querystring", () => {
+  const bodySchema = {
+    type: "object"
+  };
+  const querySchema = {
+    type: "object"
+  };
+  const paramsSchema = {
+    type: "object"
+  };
+  const responseSchema = {
+    200: {
+      schema: {
+        type: "object"
+      }
+    }
+  };
+  const headersSchema = {
+    type: "object"
+  };
+
+  const normalizeBody = (body) => body;
+  const normalizeQuery = (query) => query;
+  const normalizeParams = (params) => params;
+
+  const validator = defineRouteValidator({
+    meta: {
+      tags: ["contacts", "intake"],
+      summary: "Create contact intake"
+    },
+    bodyValidator: {
+      schema: bodySchema,
+      normalize: normalizeBody
+    },
+    queryValidator: {
+      schema: querySchema,
+      normalize: normalizeQuery
+    },
+    paramsValidator: {
+      schema: paramsSchema
+    },
+    responseValidators: responseSchema,
+    advanced: {
+      fastifySchema: {
+        headers: headersSchema
+      },
+      jskitInput: {
+        params: normalizeParams
+      }
+    }
+  });
+
+  const compiled = validator.toRouteOptions();
+
+  assert.deepEqual(compiled.schema, {
+    tags: ["contacts", "intake"],
+    summary: "Create contact intake",
+    body: bodySchema,
+    querystring: querySchema,
+    params: paramsSchema,
+    response: {
+      200: {
+        type: "object"
+      }
+    },
+    headers: headersSchema
+  });
+  assert.equal(compiled.input.body, normalizeBody);
+  assert.equal(compiled.input.query, normalizeQuery);
+  assert.equal(compiled.input.params, normalizeParams);
+});
+
+test("compileRouteValidator accepts plain validator objects", () => {
+  const querySchema = {
+    type: "object"
+  };
+  const normalizeQuery = (query) => ({
+    dryRun: Boolean(query?.dryRun)
+  });
+
+  const compiled = compileRouteValidator({
+    queryValidator: {
+      schema: querySchema,
+      normalize: normalizeQuery
+    }
+  });
+
+  assert.deepEqual(compiled.schema, {
+    querystring: querySchema
+  });
+  assert.equal(compiled.input.query, normalizeQuery);
+});
+
+test("compileRouteValidator creates pass-through request.input transforms for schema-only params and query", () => {
+  const querySchema = {
+    type: "object"
+  };
+  const paramsSchema = {
+    type: "object"
+  };
+
+  const compiled = compileRouteValidator({
+    queryValidator: {
+      schema: querySchema
+    },
+    paramsValidator: {
+      schema: paramsSchema
+    }
+  });
+
+  assert.deepEqual(compiled.schema, {
+    querystring: querySchema,
+    params: paramsSchema
+  });
+  assert.equal(typeof compiled.input.query, "function");
+  assert.equal(typeof compiled.input.params, "function");
+  assert.deepEqual(compiled.input.query({ workspaceSlug: "acme" }), { workspaceSlug: "acme" });
+  assert.deepEqual(compiled.input.params({ workspaceSlug: "acme" }), { workspaceSlug: "acme" });
+});
+
+test("compileRouteValidator accepts response validator objects and extracts only response schemas", () => {
+  const responseBodySchema = {
+    type: "object"
+  };
+  const normalizeOutput = (payload) => ({
+    ...payload,
+    normalized: true
+  });
+
+  const compiled = compileRouteValidator({
+    responseValidators: {
+      200: {
+        schema: responseBodySchema,
+        normalize: normalizeOutput
+      },
+      400: {
+        schema: {
+          type: "object"
+        }
+      }
+    }
+  });
+
+  assert.deepEqual(compiled.schema, {
+    response: {
+      200: responseBodySchema,
+      400: {
+        type: "object"
+      }
+    }
+  });
+  assert.equal(Object.prototype.hasOwnProperty.call(compiled, "output"), false);
+});
+
+test("compileRouteValidator merges query validator arrays automatically", () => {
+  const paginationQuery = {
+    schema: {
+      type: "object",
+      properties: {
+        cursor: {
+          type: "string"
+        }
+      },
+      additionalProperties: false
+    }
+  };
+  const searchQuery = {
+    schema: {
+      type: "object",
+      properties: {
+        search: {
+          type: "string"
+        }
+      },
+      additionalProperties: false
+    }
+  };
+
+  const compiled = compileRouteValidator({
+    queryValidator: [paginationQuery, searchQuery]
+  });
+
+  assert.deepEqual(compiled.schema, {
+    querystring: {
+      type: "object",
+      properties: {
+        cursor: {
+          type: "string"
+        },
+        search: {
+          type: "string"
+        }
+      },
+      required: ["cursor", "search"],
+      additionalProperties: false
+    }
+  });
+});
+
+test("compileRouteValidator merges params validator arrays automatically", () => {
+  const workspaceSlugParams = {
+    schema: {
+      type: "object",
+      properties: {
+        workspaceSlug: {
+          type: "string"
+        }
+      },
+      required: ["workspaceSlug"],
+      additionalProperties: false
+    }
+  };
+  const inviteIdParams = {
+    schema: {
+      type: "object",
+      properties: {
+        inviteId: {
+          type: "string"
+        }
+      },
+      required: ["inviteId"],
+      additionalProperties: false
+    }
+  };
+
+  const compiled = compileRouteValidator({
+    paramsValidator: [workspaceSlugParams, inviteIdParams]
+  });
+
+  assert.deepEqual(compiled.schema, {
+    params: {
+      type: "object",
+      properties: {
+        workspaceSlug: {
+          type: "string"
+        },
+        inviteId: {
+          type: "string"
+        }
+      },
+      required: ["workspaceSlug", "inviteId"],
+      additionalProperties: false
+    }
+  });
+});
+
+test("compileRouteValidator composes multiple query normalizers in validator arrays", () => {
+  const compiled = compileRouteValidator({
+    queryValidator: [
+      {
+        schema: {
+          type: "object",
+          properties: {
+            cursor: {
+              type: "string"
+            }
+          },
+          additionalProperties: false
+        },
+        normalize(query = {}) {
+          return {
+            cursor: String(query.cursor || "").trim()
+          };
+        }
+      },
+      {
+        schema: {
+          type: "object",
+          properties: {
+            search: {
+              type: "string"
+            }
+          },
+          additionalProperties: false
+        },
+        normalize(query = {}) {
+          return {
+            search: String(query.search || "").trim().toLowerCase()
+          };
+        }
+      }
+    ]
+  });
+
+  assert.deepEqual(compiled.input.query({ cursor: " 100 ", search: " ACME " }), {
+    cursor: "100",
+    search: "acme"
+  });
+});
+
+test("resolveRouteValidatorOptions ignores legacy schema/input definitions", () => {
+  const resolved = resolveRouteValidatorOptions({
+    method: "POST",
+    path: "/contacts",
+    options: {
+      schema: {
+        bodyValidator: {}
+      },
+      input: {
+        body: () => ({})
+      },
+      middleware: ["api"]
+    }
+  });
+
+  assert.equal(Object.prototype.hasOwnProperty.call(resolved, "schema"), false);
+  assert.equal(Object.prototype.hasOwnProperty.call(resolved, "input"), false);
+  assert.deepEqual(resolved.middleware, ["api"]);
+});
+
+test("resolveRouteValidatorOptions supports inline validator shape without wrapper", () => {
+  const bodySchema = {
+    type: "object"
+  };
+  const normalizeBody = (body) => ({
+    name: String(body?.name || "").trim()
+  });
+
+  const resolved = resolveRouteValidatorOptions({
+    method: "POST",
+    path: "/contacts",
+    options: {
+      meta: {
+        tags: ["contacts"],
+        summary: "Create contact"
+      },
+      bodyValidator: {
+        schema: bodySchema,
+        normalize: normalizeBody
+      },
+      middleware: ["api"]
+    }
+  });
+
+  assert.deepEqual(resolved.schema, {
+    tags: ["contacts"],
+    summary: "Create contact",
+    body: bodySchema
+  });
+  assert.equal(resolved.input.body, normalizeBody);
+  assert.deepEqual(resolved.middleware, ["api"]);
+});
+
+test("resolveRouteValidatorOptions ignores validator wrapper", () => {
+  const resolved = resolveRouteValidatorOptions({
+    method: "POST",
+    path: "/contacts",
+    options: {
+      validator: defineRouteValidator({}),
+      middleware: ["api"]
+    }
+  });
+
+  assert.equal(Object.prototype.hasOwnProperty.call(resolved, "validator"), false);
+  assert.deepEqual(resolved.middleware, ["api"]);
+});
+
+test("defineRouteValidator rejects unsupported advanced.jskitInput keys", () => {
+  assert.throws(
+    () =>
+      defineRouteValidator({
+        advanced: {
+          jskitInput: {
+            headers: () => ({})
+          }
+        }
+      }),
+    /advanced\.jskitInput\.headers is not supported/
+  );
+});
+
+test("defineRouteValidator validates meta fields", () => {
+  assert.throws(
+    () =>
+      defineRouteValidator({
+        meta: {
+          tags: ["ok", ""]
+        }
+      }),
+    /meta\.tags\[1\] must be a non-empty string/
+  );
+
+  assert.throws(
+    () =>
+      defineRouteValidator({
+        meta: {
+          summary: ""
+        }
+      }),
+    /meta\.summary must be a non-empty string/
+  );
+});
+
+test("HttpRouter.register ignores validator wrapper options", () => {
+  const router = createRouter();
+  router.register(
+    "POST",
+    "/contacts",
+    {
+      validator: defineRouteValidator({})
+    },
+    async () => {}
+  );
+
+  const [route] = router.list();
+  assert.equal(route.schema, undefined);
+  assert.equal(route.input, null);
+});
+
+test("HttpRouter.register ignores compiled legacy-style route options", () => {
+  const router = createRouter();
+  const querySchema = {
+    type: "object"
+  };
+  const normalizeQuery = (query) => ({
+    dryRun: query?.dryRun === true
+  });
+
+  const validator = defineRouteValidator({
+    queryValidator: {
+      schema: querySchema,
+      normalize: normalizeQuery
+    }
+  });
+
+  router.get(
+    "/contacts",
+    validator.toRouteOptions(),
+    async () => {}
+  );
+
+  const [route] = router.list();
+  assert.equal(route.schema, undefined);
+  assert.equal(route.input, null);
+});
+
+test("HttpRouter.register accepts inline validator shape directly", () => {
+  const router = createRouter();
+  const querySchema = {
+    type: "object"
+  };
+  const normalizeQuery = (query) => ({
+    dryRun: query?.dryRun === true
+  });
+
+  router.get(
+    "/contacts",
+    {
+      meta: {
+        tags: ["contacts"],
+        summary: "List contacts"
+      },
+      queryValidator: {
+        schema: querySchema,
+        normalize: normalizeQuery
+      }
+    },
+    async () => {}
+  );
+
+  const [route] = router.list();
+  assert.deepEqual(route.schema, {
+    tags: ["contacts"],
+    summary: "List contacts",
+    querystring: querySchema
+  });
+  assert.equal(route.input.query, normalizeQuery);
+});

package/server/http/lib/router.js

@@ -0,0 +1,206 @@
+import { ensureNonEmptyText, normalizeArray, normalizeObject, normalizeText } from "../../../shared/support/normalize.js";
+import { RouteDefinitionError } from "./errors.js";
+import { resolveRouteValidatorOptions } from "./routeValidator.js";
+import { normalizeMiddlewareStack as normalizeSharedMiddlewareStack } from "./routeSupport.js";
+
+function normalizeMethod(method) {
+  return ensureNonEmptyText(method, "route method").toUpperCase();
+}
+
+function normalizePath(pathname) {
+  const value = normalizeText(pathname);
+  if (!value.startsWith("/")) {
+    throw new RouteDefinitionError(`Route path must start with '/': ${value || "<empty>"}`);
+  }
+  return value.replace(/\/+/g, "/");
+}
+
+function joinPath(left, right) {
+  const leftPath = normalizeText(left);
+  const rightPath = normalizeText(right);
+
+  const normalizedLeft = leftPath ? `/${leftPath.replace(/^\/+|\/+$/g, "")}` : "";
+  const normalizedRight = rightPath ? `/${rightPath.replace(/^\/+|\/+$/g, "")}` : "";
+  const joined = `${normalizedLeft}${normalizedRight}`.replace(/\/+/g, "/");
+  return joined || "/";
+}
+
+function normalizeRouterMiddlewareStack(value, { context = "middleware" } = {}) {
+  return normalizeSharedMiddlewareStack(value, {
+    context,
+    ErrorType: RouteDefinitionError,
+    entryLabel: "entries",
+    includeIndex: false
+  });
+}
+
+function normalizeRouteInput(method, path, optionsOrHandler, maybeHandler) {
+  const options =
+    typeof optionsOrHandler === "function"
+      ? {}
+      : normalizeObject(optionsOrHandler, {
+          fallback: {}
+        });
+  const handler =
+    typeof optionsOrHandler === "function"
+      ? optionsOrHandler
+      : typeof maybeHandler === "function"
+        ? maybeHandler
+        : null;
+
+  if (typeof handler !== "function") {
+    throw new RouteDefinitionError(`Route ${method} ${path} requires a handler function.`);
+  }
+
+  return {
+    method: normalizeMethod(method),
+    path: normalizePath(path),
+    options,
+    handler
+  };
+}
+
+class HttpRouter {
+  constructor({ routes = null, prefix = "", middleware = [] } = {}) {
+    this._routes = Array.isArray(routes) ? routes : [];
+    this._prefix = normalizeText(prefix);
+    this._middleware = normalizeRouterMiddlewareStack(middleware, {
+      context: "router middleware"
+    });
+  }
+
+  register(method, path, optionsOrHandler, maybeHandler) {
+    const input = normalizeRouteInput(method, path, optionsOrHandler, maybeHandler);
+    const resolvedOptions = resolveRouteValidatorOptions({
+      method: input.method,
+      path: input.path,
+      options: input.options
+    });
+    const routeMiddleware = normalizeRouterMiddlewareStack(resolvedOptions.middleware, {
+      context: `Route ${input.method} ${input.path} middleware`
+    });
+    const routeInput = Object.prototype.hasOwnProperty.call(resolvedOptions, "input") ? resolvedOptions.input : null;
+    const routeOutput = Object.prototype.hasOwnProperty.call(resolvedOptions, "output") ? resolvedOptions.output : null;
+
+    const route = Object.freeze({
+      id: normalizeText(resolvedOptions.id),
+      method: input.method,
+      path: joinPath(this._prefix, input.path),
+      schema: resolvedOptions.schema,
+      input: routeInput,
+      output: routeOutput,
+      config: normalizeObject(resolvedOptions.config),
+      auth: resolvedOptions.auth,
+      contextPolicy: resolvedOptions.contextPolicy,
+      surface: resolvedOptions.surface,
+      visibility: resolvedOptions.visibility,
+      permission: resolvedOptions.permission,
+      ownerParam: resolvedOptions.ownerParam,
+      userField: resolvedOptions.userField,
+      ownerResolver: resolvedOptions.ownerResolver,
+      csrfProtection: resolvedOptions.csrfProtection,
+      bodyLimit: resolvedOptions.bodyLimit,
+      middleware: Object.freeze([...this._middleware, ...routeMiddleware]),
+      handler: input.handler
+    });
+
+    this._routes.push(route);
+    return this;
+  }
+
+  get(path, optionsOrHandler, maybeHandler) {
+    return this.register("GET", path, optionsOrHandler, maybeHandler);
+  }
+
+  post(path, optionsOrHandler, maybeHandler) {
+    return this.register("POST", path, optionsOrHandler, maybeHandler);
+  }
+
+  put(path, optionsOrHandler, maybeHandler) {
+    return this.register("PUT", path, optionsOrHandler, maybeHandler);
+  }
+
+  patch(path, optionsOrHandler, maybeHandler) {
+    return this.register("PATCH", path, optionsOrHandler, maybeHandler);
+  }
+
+  delete(path, optionsOrHandler, maybeHandler) {
+    return this.register("DELETE", path, optionsOrHandler, maybeHandler);
+  }
+
+  group({ prefix = "", middleware = [] } = {}, defineRoutes = null) {
+    if (typeof defineRoutes !== "function") {
+      throw new RouteDefinitionError("group() requires a callback.");
+    }
+
+    const nestedRouter = new HttpRouter({
+      routes: this._routes,
+      prefix: joinPath(this._prefix, prefix || ""),
+      middleware: [
+        ...this._middleware,
+        ...normalizeRouterMiddlewareStack(middleware, {
+          context: "group middleware"
+        })
+      ]
+    });
+
+    defineRoutes(nestedRouter);
+    return this;
+  }
+
+  resource(name, controller, options = {}) {
+    this._resource(name, controller, {
+      ...normalizeObject(options),
+      apiOnly: false
+    });
+    return this;
+  }
+
+  apiResource(name, controller, options = {}) {
+    this._resource(name, controller, {
+      ...normalizeObject(options),
+      apiOnly: true
+    });
+    return this;
+  }
+
+  _resource(name, controller, options = {}) {
+    const resourceName = ensureNonEmptyText(name, "resource name");
+    const idParam = normalizeText(options.idParam, { fallback: "id" });
+    const basePath = `/${resourceName}`;
+    const itemPath = `/${resourceName}/:${idParam}`;
+
+    const methods = normalizeObject(controller);
+    const middleware = normalizeRouterMiddlewareStack(options.middleware, {
+      context: `resource ${resourceName} middleware`
+    });
+
+    const requireMethod = (methodName) => {
+      const handler = methods[methodName];
+      if (typeof handler !== "function") {
+        throw new RouteDefinitionError(`resource controller for ${resourceName} is missing method ${methodName}().`);
+      }
+      return handler;
+    };
+
+    this.get(basePath, { middleware }, requireMethod("index"));
+    if (!options.apiOnly) {
+      this.get(`${basePath}/create`, { middleware }, requireMethod("create"));
+      this.get(`${itemPath}/edit`, { middleware }, requireMethod("edit"));
+    }
+    this.post(basePath, { middleware }, requireMethod("store"));
+    this.get(itemPath, { middleware }, requireMethod("show"));
+    this.put(itemPath, { middleware }, requireMethod("update"));
+    this.delete(itemPath, { middleware }, requireMethod("destroy"));
+  }
+
+  list() {
+    return Object.freeze([...this._routes]);
+  }
+}
+
+function createRouter(options = {}) {
+  return new HttpRouter(options);
+}
+
+export { HttpRouter, createRouter, joinPath };

package/server/kernel/KernelCoreServiceProvider.js

@@ -0,0 +1,27 @@
+import { Application, createApplication, createProviderClass } from "../../shared/runtime/application.js";
+import { ServiceProvider } from "../../shared/runtime/serviceProvider.js";
+import * as errors from "../../shared/runtime/kernelErrors.js";
+
+const KERNEL_CORE_API = Object.freeze({
+  Application,
+  createApplication,
+  createProviderClass,
+  ServiceProvider,
+  errors: Object.freeze({ ...errors })
+});
+
+class KernelCoreServiceProvider {
+  static id = "runtime.kernel";
+
+  register(app) {
+    if (!app || typeof app.singleton !== "function") {
+      throw new Error("KernelCoreServiceProvider requires application singleton().");
+    }
+
+    app.singleton("runtime.kernel", () => KERNEL_CORE_API);
+  }
+
+  boot() {}
+}
+
+export { KernelCoreServiceProvider };

package/server/kernel/index.js

@@ -0,0 +1,10 @@
+export { Application, createApplication, createProviderClass } from "../../shared/runtime/application.js";
+export { ServiceProvider } from "../../shared/runtime/serviceProvider.js";
+export {
+  KernelError,
+  ProviderNormalizationError,
+  DuplicateProviderError,
+  ProviderDependencyError,
+  ProviderLifecycleError
+} from "../../shared/runtime/kernelErrors.js";
+export { KernelCoreServiceProvider } from "./KernelCoreServiceProvider.js";