@jskit-ai/kernel 0.1.62 → 0.1.64

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

@@ -506,6 +506,77 @@ test("registerHttpRuntime passes app context so request scope is available", asy
   assert.equal(fastify.setErrorHandlerCalls, 1);
 });
 
+test("createRouter preserves explicit internal route flags", () => {
+  const router = createRouter();
+
+  router.get(
+    "/internal-only",
+    {
+      internal: true
+    },
+    async (_request, reply) => {
+      reply.code(204).send();
+    }
+  );
+
+  const [route] = router.list();
+  assert.equal(route?.internal, true);
+});
+
+test("registerHttpRuntime skips internal routes from public HTTP registration", () => {
+  const app = createApplication();
+  const fastify = createFastifyStub();
+  const router = createRouter();
+
+  router.get(
+    "/internal-only",
+    {
+      internal: true
+    },
+    async (_request, reply) => {
+      reply.code(200).send({ hidden: true });
+    }
+  );
+  router.get("/public-route", async (_request, reply) => {
+    reply.code(200).send({ ok: true });
+  });
+
+  app.instance("jskit.fastify", fastify);
+  app.instance("jskit.http.router", router);
+
+  const registration = registerHttpRuntime(app);
+  assert.equal(registration.routeCount, 1);
+  assert.equal(fastify.routes.length, 1);
+  assert.equal(fastify.routes[0].url, "/public-route");
+});
+
+test("registerHttpRuntime skips internal routes generated through router apiResource helpers", () => {
+  const app = createApplication();
+  const fastify = createFastifyStub();
+  const router = createRouter();
+
+  router.apiResource(
+    "widgets",
+    {
+      index: async (_request, reply) => reply.code(200).send({ ok: true }),
+      store: async (_request, reply) => reply.code(201).send({ ok: true }),
+      show: async (_request, reply) => reply.code(200).send({ ok: true }),
+      update: async (_request, reply) => reply.code(200).send({ ok: true }),
+      destroy: async (_request, reply) => reply.code(204).send()
+    },
+    {
+      internal: true
+    }
+  );
+
+  app.instance("jskit.fastify", fastify);
+  app.instance("jskit.http.router", router);
+
+  const registration = registerHttpRuntime(app);
+  assert.equal(registration.routeCount, 0);
+  assert.equal(fastify.routes.length, 0);
+});
+
 test("registerHttpRuntime installs API error handling once by default", () => {
   const app = createApplication();
   const fastify = createFastifyStub();

package/server/http/lib/routeRegistration.js

@@ -310,15 +310,16 @@ function registerRoutes(
   }
 
   const normalizedRoutes = normalizeArray(routes);
+  const publicRoutes = normalizedRoutes.filter((route) => route?.internal !== true);
   const policyApplier = typeof applyRoutePolicy === "function" ? applyRoutePolicy : defaultApplyRoutePolicy;
   const fallbackHandler = typeof missingHandler === "function" ? missingHandler : defaultMissingHandler;
   const runtimeMiddlewareConfig = normalizeRuntimeMiddlewareConfig(middleware);
 
-  if (normalizedRoutes.some((route) => routeRequiresJsonApiContentTypeParser(route))) {
+  if (publicRoutes.some((route) => routeRequiresJsonApiContentTypeParser(route))) {
     registerJsonApiContentTypeParser(fastify);
   }
 
-  for (const route of normalizedRoutes) {
+  for (const route of publicRoutes) {
     const routeTransport = normalizeRouteTransport(route?.transport, {
       context: `Route ${String(route?.method || "<unknown>")} ${String(route?.path || "<unknown>")} transport`,
       ErrorType: RouteRegistrationError
@@ -407,7 +408,7 @@ function registerRoutes(
   }
 
   return {
-    routeCount: normalizedRoutes.length
+    routeCount: publicRoutes.length
   };
 }
 

package/server/http/lib/router.js

@@ -35,6 +35,18 @@ function normalizeRouterMiddlewareStack(value, { context = "middleware" } = {})
   });
 }
 
+function normalizeRouteInternal(value, { method = "", path = "" } = {}) {
+  if (value == null) {
+    return false;
+  }
+  if (typeof value !== "boolean") {
+    throw new RouteDefinitionError(
+      `Route ${String(method || "<unknown>")} ${String(path || "<unknown>")} internal must be a boolean.`
+    );
+  }
+  return value;
+}
+
 function normalizeRouteInput(method, path, optionsOrHandler, maybeHandler) {
   const options =
     typeof optionsOrHandler === "function"
@@ -108,6 +120,10 @@ class HttpRouter {
       auth: resolvedOptions.auth,
       contextPolicy: resolvedOptions.contextPolicy,
       surface: resolvedOptions.surface,
+      internal: normalizeRouteInternal(resolvedOptions.internal, {
+        method: input.method,
+        path: input.path
+      }),
       visibility: resolvedOptions.visibility,
       permission: resolvedOptions.permission,
       ownerParam: resolvedOptions.ownerParam,
@@ -186,9 +202,11 @@ class HttpRouter {
     const itemPath = `/${resourceName}/:${idParam}`;
 
     const methods = normalizeObject(controller);
-    const middleware = normalizeRouterMiddlewareStack(options.middleware, {
-      context: `resource ${resourceName} middleware`
-    });
+    const routeOptions = {
+      ...normalizeObject(options)
+    };
+    delete routeOptions.idParam;
+    delete routeOptions.apiOnly;
 
     const requireMethod = (methodName) => {
       const handler = methods[methodName];
@@ -198,15 +216,15 @@ class HttpRouter {
       return handler;
     };
 
-    this.get(basePath, { middleware }, requireMethod("index"));
+    this.get(basePath, routeOptions, requireMethod("index"));
     if (!options.apiOnly) {
-      this.get(`${basePath}/create`, { middleware }, requireMethod("create"));
-      this.get(`${itemPath}/edit`, { middleware }, requireMethod("edit"));
+      this.get(`${basePath}/create`, routeOptions, requireMethod("create"));
+      this.get(`${itemPath}/edit`, routeOptions, 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"));
+    this.post(basePath, routeOptions, requireMethod("store"));
+    this.get(itemPath, routeOptions, requireMethod("show"));
+    this.put(itemPath, routeOptions, requireMethod("update"));
+    this.delete(itemPath, routeOptions, requireMethod("destroy"));
   }
 
   list() {

package/server/support/appConfig.js

@@ -1,4 +1,4 @@
-import { normalizeObject } from "../../shared/support/normalize.js";
+import { normalizeMobileConfig, normalizeObject, normalizeText } from "../../shared/support/normalize.js";
 import { normalizeSurfaceId } from "../../shared/surface/registry.js";
 
 function resolveAppConfig(scope = null) {
@@ -34,4 +34,95 @@ function resolveDefaultSurfaceId(scope = null, { defaultSurfaceId = "" } = {}) {
   });
 }
 
-export { resolveAppConfig, normalizeDefaultSurfaceId, resolveDefaultSurfaceId };
+function resolveMobileConfig(source = null) {
+  const appConfig =
+    source && typeof source === "object" && typeof source.has === "function" && typeof source.make === "function"
+      ? resolveAppConfig(source)
+      : normalizeObject(source);
+
+  return normalizeMobileConfig(appConfig.mobile);
+}
+
+function resolveClientAssetMode(source = null) {
+  return resolveMobileConfig(source).assetMode;
+}
+
+function buildWebCallbackUrl(appPublicUrl = "", callbackPath = "") {
+  const normalizedAppPublicUrl = normalizeText(appPublicUrl);
+  const normalizedCallbackPath = normalizeText(callbackPath);
+  if (!normalizedAppPublicUrl || !normalizedCallbackPath) {
+    return "";
+  }
+
+  try {
+    const baseUrl = new URL(normalizedAppPublicUrl);
+    if (baseUrl.protocol !== "http:" && baseUrl.protocol !== "https:") {
+      return "";
+    }
+
+    if (!baseUrl.pathname.endsWith("/")) {
+      baseUrl.pathname = `${baseUrl.pathname}/`;
+    }
+    baseUrl.search = "";
+    baseUrl.hash = "";
+    const relativeCallbackPath = normalizedCallbackPath.startsWith("/")
+      ? normalizedCallbackPath.slice(1)
+      : normalizedCallbackPath;
+    return new URL(relativeCallbackPath, baseUrl).toString();
+  } catch {
+    return "";
+  }
+}
+
+function buildMobileCallbackUrl(customScheme = "", callbackPath = "") {
+  const normalizedScheme = normalizeText(customScheme).toLowerCase();
+  const normalizedCallbackPath = normalizeText(callbackPath);
+  if (!normalizedScheme || !normalizedCallbackPath) {
+    return "";
+  }
+
+  const suffix = normalizedCallbackPath.startsWith("/") ? normalizedCallbackPath.slice(1) : normalizedCallbackPath;
+  return suffix ? `${normalizedScheme}://${suffix}` : `${normalizedScheme}://`;
+}
+
+function buildAppLinkCallbackUrls(appLinkDomains = [], callbackPath = "") {
+  const normalizedCallbackPath = normalizeText(callbackPath);
+  if (!normalizedCallbackPath) {
+    return Object.freeze([]);
+  }
+
+  const urls = (Array.isArray(appLinkDomains) ? appLinkDomains : [])
+    .map((entry) => normalizeText(entry).toLowerCase())
+    .filter(Boolean)
+    .map((entry) => `https://${entry}${normalizedCallbackPath}`);
+
+  return Object.freeze([...new Set(urls)]);
+}
+
+function resolveMobileCallbackUrls(source = null, { appPublicUrl = "" } = {}) {
+  const mobileConfig = resolveMobileConfig(source);
+  const callbackPath = mobileConfig.auth.callbackPath;
+  const webCallbackUrl = buildWebCallbackUrl(appPublicUrl, callbackPath);
+  const mobileCallbackUrl = buildMobileCallbackUrl(mobileConfig.auth.customScheme, callbackPath);
+  const appLinkCallbackUrls = buildAppLinkCallbackUrls(mobileConfig.auth.appLinkDomains, callbackPath);
+  const callbackUrls = Object.freeze(
+    [...new Set([webCallbackUrl, mobileCallbackUrl, ...appLinkCallbackUrls].filter(Boolean))]
+  );
+
+  return Object.freeze({
+    callbackPath,
+    webCallbackUrl,
+    mobileCallbackUrl,
+    appLinkCallbackUrls,
+    callbackUrls
+  });
+}
+
+export {
+  resolveAppConfig,
+  normalizeDefaultSurfaceId,
+  resolveDefaultSurfaceId,
+  resolveMobileConfig,
+  resolveClientAssetMode,
+  resolveMobileCallbackUrls
+};

package/server/support/appConfig.test.js

@@ -2,8 +2,11 @@ import assert from "node:assert/strict";
 import test from "node:test";
 import {
   resolveAppConfig,
+  resolveClientAssetMode,
   normalizeDefaultSurfaceId,
-  resolveDefaultSurfaceId
+  resolveDefaultSurfaceId,
+  resolveMobileCallbackUrls,
+  resolveMobileConfig
 } from "./appConfig.js";
 
 test("resolveAppConfig returns normalized appConfig when scope exposes appConfig binding", () => {
@@ -92,3 +95,101 @@ test("resolveDefaultSurfaceId falls back to appConfig and then empty default", (
   });
   assert.equal(fromKernelFallback, "");
 });
+
+test("resolveMobileConfig reads the normalized mobile config from raw appConfig or scope", () => {
+  const fromRaw = resolveMobileConfig({
+    mobile: {
+      enabled: true,
+      strategy: "capacitor",
+      assetMode: "dev_server",
+      auth: {
+        customScheme: "convict"
+      }
+    }
+  });
+
+  assert.equal(fromRaw.enabled, true);
+  assert.equal(fromRaw.strategy, "capacitor");
+  assert.equal(fromRaw.assetMode, "dev_server");
+  assert.equal(fromRaw.auth.customScheme, "convict");
+
+  const fromScope = resolveMobileConfig({
+    has(token) {
+      return token === "appConfig";
+    },
+    make() {
+      return {
+        mobile: {
+          enabled: true,
+          strategy: "capacitor"
+        }
+      };
+    }
+  });
+  assert.equal(fromScope.enabled, true);
+  assert.equal(fromScope.strategy, "capacitor");
+});
+
+test("resolveClientAssetMode returns the normalized mobile asset mode", () => {
+  assert.equal(
+    resolveClientAssetMode({
+      mobile: {
+        assetMode: "dev_server"
+      }
+    }),
+    "dev_server"
+  );
+  assert.equal(resolveClientAssetMode({}), "bundled");
+});
+
+test("resolveMobileCallbackUrls resolves web, mobile, and app-link callback URLs", () => {
+  const callbackUrls = resolveMobileCallbackUrls(
+    {
+      mobile: {
+        auth: {
+          callbackPath: "/auth/login",
+          customScheme: "convict",
+          appLinkDomains: ["app.example.com", "APP.EXAMPLE.COM"]
+        }
+      }
+    },
+    {
+      appPublicUrl: "https://example.com/app"
+    }
+  );
+
+  assert.deepEqual(callbackUrls, {
+    callbackPath: "/auth/login",
+    webCallbackUrl: "https://example.com/app/auth/login",
+    mobileCallbackUrl: "convict://auth/login",
+    appLinkCallbackUrls: ["https://app.example.com/auth/login"],
+    callbackUrls: [
+      "https://example.com/app/auth/login",
+      "convict://auth/login",
+      "https://app.example.com/auth/login"
+    ]
+  });
+});
+
+test("resolveMobileCallbackUrls omits invalid or unavailable callback targets", () => {
+  const callbackUrls = resolveMobileCallbackUrls(
+    {
+      mobile: {
+        auth: {
+          callbackPath: "/auth/login"
+        }
+      }
+    },
+    {
+      appPublicUrl: "notaurl"
+    }
+  );
+
+  assert.deepEqual(callbackUrls, {
+    callbackPath: "/auth/login",
+    webCallbackUrl: "",
+    mobileCallbackUrl: "",
+    appLinkCallbackUrls: [],
+    callbackUrls: []
+  });
+});

package/server/support/appConfigFiles.js

@@ -39,17 +39,20 @@ async function loadConfigModuleAtPath(absolutePath) {
   return normalizeConfigObject(loadedModule?.config);
 }
 
-async function loadAppConfigFromModuleUrl({
-  moduleUrl = import.meta.url,
+async function loadAppConfigFromAppRoot({
+  appRoot = "",
   publicConfigRelativePath = PUBLIC_CONFIG_RELATIVE_PATH,
   serverConfigRelativePath = SERVER_CONFIG_RELATIVE_PATH
 } = {}) {
-  const appRoot = await resolveAppRootFromModuleUrl(moduleUrl, {
-    publicConfigRelativePath
-  });
+  const normalizedAppRootInput = String(appRoot || "").trim();
+  if (!normalizedAppRootInput) {
+    throw new Error("loadAppConfigFromAppRoot requires appRoot.");
+  }
+  const normalizedAppRoot = path.resolve(normalizedAppRootInput);
+
   const [publicConfig, serverConfig] = await Promise.all([
-    loadConfigModuleAtPath(path.join(appRoot, publicConfigRelativePath)),
-    loadConfigModuleAtPath(path.join(appRoot, serverConfigRelativePath))
+    loadConfigModuleAtPath(path.join(normalizedAppRoot, publicConfigRelativePath)),
+    loadConfigModuleAtPath(path.join(normalizedAppRoot, serverConfigRelativePath))
   ]);
 
   return Object.freeze({
@@ -58,4 +61,19 @@ async function loadAppConfigFromModuleUrl({
   });
 }
 
-export { loadAppConfigFromModuleUrl };
+async function loadAppConfigFromModuleUrl({
+  moduleUrl = import.meta.url,
+  publicConfigRelativePath = PUBLIC_CONFIG_RELATIVE_PATH,
+  serverConfigRelativePath = SERVER_CONFIG_RELATIVE_PATH
+} = {}) {
+  const appRoot = await resolveAppRootFromModuleUrl(moduleUrl, {
+    publicConfigRelativePath
+  });
+  return loadAppConfigFromAppRoot({
+    appRoot,
+    publicConfigRelativePath,
+    serverConfigRelativePath
+  });
+}
+
+export { loadAppConfigFromAppRoot, loadAppConfigFromModuleUrl };

package/server/support/appConfigFiles.test.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import os from "node:os";
 import test from "node:test";
 import { pathToFileURL } from "node:url";
-import { loadAppConfigFromModuleUrl } from "./appConfigFiles.js";
+import { loadAppConfigFromAppRoot, loadAppConfigFromModuleUrl } from "./appConfigFiles.js";
 
 async function createModuleUrlAt(absolutePath) {
   await mkdir(path.dirname(absolutePath), { recursive: true });
@@ -30,6 +30,30 @@ test("loadAppConfigFromModuleUrl merges public and server config", async () => {
   assert.equal(Object.isFrozen(loaded), true);
 });
 
+test("loadAppConfigFromAppRoot merges public and server config", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "kernel-app-config-"));
+  const appRoot = path.join(tempRoot, "app");
+  await mkdir(path.join(appRoot, "config"), { recursive: true });
+  await writeFile(path.join(appRoot, "config", "public.js"), "export const config = { a: 1, shared: 'public' };", "utf8");
+  await writeFile(path.join(appRoot, "config", "server.js"), "export const config = { b: 2, shared: 'server' };", "utf8");
+
+  const loaded = await loadAppConfigFromAppRoot({ appRoot });
+
+  assert.deepEqual(loaded, {
+    a: 1,
+    b: 2,
+    shared: "server"
+  });
+  assert.equal(Object.isFrozen(loaded), true);
+});
+
+test("loadAppConfigFromAppRoot requires an explicit appRoot", async () => {
+  await assert.rejects(
+    loadAppConfigFromAppRoot({ appRoot: "" }),
+    /requires appRoot/
+  );
+});
+
 test("loadAppConfigFromModuleUrl tolerates missing server config", async () => {
   const tempRoot = await mkdtemp(path.join(os.tmpdir(), "kernel-app-config-"));
   const appRoot = path.join(tempRoot, "app");

package/server/support/index.js

@@ -1,6 +1,6 @@
 export { symlinkSafeRequire } from "./symlinkSafeRequire.js";
-export { resolveAppConfig } from "./appConfig.js";
-export { loadAppConfigFromModuleUrl } from "./appConfigFiles.js";
+export { resolveAppConfig, resolveMobileConfig, resolveClientAssetMode, resolveMobileCallbackUrls } from "./appConfig.js";
+export { loadAppConfigFromAppRoot, loadAppConfigFromModuleUrl } from "./appConfigFiles.js";
 export { importFreshModuleFromAbsolutePath } from "./importFreshModuleFromAbsolutePath.js";
 export { resolveRequiredAppRoot, toPosixPath } from "./path.js";
 export {

package/shared/support/normalize.js

@@ -254,6 +254,94 @@ function normalizeOneOf(value, allowedValues = [], fallback = "") {
   return supported[0] || "";
 }
 
+const MOBILE_ASSET_MODES = Object.freeze(["bundled", "dev_server"]);
+const MOBILE_STRATEGIES = Object.freeze(["capacitor"]);
+const DEFAULT_MOBILE_AUTH_CONFIG = Object.freeze({
+  callbackPath: "/auth/login",
+  customScheme: "",
+  appLinkDomains: Object.freeze([])
+});
+const DEFAULT_MOBILE_ANDROID_CONFIG = Object.freeze({
+  packageName: "",
+  minSdk: 26,
+  targetSdk: 35,
+  versionCode: 1,
+  versionName: "1.0.0"
+});
+
+function normalizeMobileStrategy(value = "", { fallback = "" } = {}) {
+  const normalized = normalizeLowerText(value);
+  return MOBILE_STRATEGIES.includes(normalized) ? normalized : normalizeLowerText(fallback);
+}
+
+function normalizeMobileAssetMode(value = "", { fallback = "bundled" } = {}) {
+  const normalized = normalizeLowerText(value);
+  if (!normalized) {
+    return normalizeLowerText(fallback, {
+      fallback: "bundled"
+    });
+  }
+  if (!MOBILE_ASSET_MODES.includes(normalized)) {
+    throw new TypeError('config.mobile.assetMode must be "bundled" or "dev_server".');
+  }
+  return normalized;
+}
+
+function normalizeMobileCallbackPath(value = "", { fallback = "/auth/login" } = {}) {
+  const normalized = normalizeText(value, {
+    fallback
+  });
+  if (!normalized) {
+    return "";
+  }
+
+  return normalized.startsWith("/") ? normalized : `/${normalized}`;
+}
+
+function normalizeMobileConfig(source = {}) {
+  const mobile = normalizeObject(source);
+  const auth = normalizeObject(mobile.auth);
+  const android = normalizeObject(mobile.android);
+
+  return Object.freeze({
+    enabled: hasValue(mobile.enabled) ? normalizeBoolean(mobile.enabled) : false,
+    strategy: normalizeMobileStrategy(mobile.strategy),
+    appId: normalizeText(mobile.appId),
+    appName: normalizeText(mobile.appName),
+    assetMode: normalizeMobileAssetMode(mobile.assetMode),
+    devServerUrl: normalizeText(mobile.devServerUrl),
+    apiBaseUrl: normalizeText(mobile.apiBaseUrl),
+    auth: Object.freeze({
+      callbackPath: normalizeMobileCallbackPath(auth.callbackPath, {
+        fallback: DEFAULT_MOBILE_AUTH_CONFIG.callbackPath
+      }),
+      customScheme: normalizeLowerText(auth.customScheme),
+      appLinkDomains: Object.freeze([
+        ...new Set(
+          normalizeUniqueTextList(auth.appLinkDomains, {
+            acceptSingle: true
+          }).map((entry) => normalizeLowerText(entry))
+        )
+      ])
+    }),
+    android: Object.freeze({
+      packageName: normalizeText(android.packageName),
+      minSdk: normalizePositiveInteger(android.minSdk, {
+        fallback: DEFAULT_MOBILE_ANDROID_CONFIG.minSdk
+      }),
+      targetSdk: normalizePositiveInteger(android.targetSdk, {
+        fallback: DEFAULT_MOBILE_ANDROID_CONFIG.targetSdk
+      }),
+      versionCode: normalizePositiveInteger(android.versionCode, {
+        fallback: DEFAULT_MOBILE_ANDROID_CONFIG.versionCode
+      }),
+      versionName: normalizeText(android.versionName, {
+        fallback: DEFAULT_MOBILE_ANDROID_CONFIG.versionName
+      })
+    })
+  });
+}
+
 function ensureNonEmptyText(value, label = "value") {
   const normalized = normalizeText(value);
   if (!normalized) {
@@ -283,5 +371,9 @@ export {
   normalizeRecordId,
   normalizeOpaqueId,
   normalizeOneOf,
+  normalizeMobileAssetMode,
+  normalizeMobileCallbackPath,
+  normalizeMobileConfig,
+  normalizeMobileStrategy,
   ensureNonEmptyText
 };