@jskit-ai/agent-docs 0.1.257 → 0.1.259

package/patterns/minimal-foundation/example/bin/develop.js

@@ -1,11 +1,16 @@
 import { spawn } from "node:child_process";
 import { startServer } from "../server.js";
+import { DEFAULT_PORT } from "../server/lib/runtimeEnv.js";
 
 const LOOPBACK_HOST = "127.0.0.1";
 
-function requiredPort(value, fallback = 3000) {
-  const normalized = String(value || "").trim();
-  const parsed = Number.parseInt(normalized || String(fallback), 10);
+/**
+ * The development port a value names; anything that is not a TCP port stops the launcher.
+ * @param {string} value
+ */
+function requiredPort(value) {
+  const normalized = value.trim();
+  const parsed = Number.parseInt(normalized, 10);
   if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65_535) {
     throw new Error(`Invalid development port: ${normalized || "(empty)"}.`);
   }
@@ -20,7 +25,7 @@ function waitForChild(child) {
 }
 
 const previewHost = String(process.env.HOST || "").trim() || "0.0.0.0";
-const previewPort = requiredPort(process.env.PORT);
+const previewPort = requiredPort(process.env.PORT || String(DEFAULT_PORT));
 let apiServer = null;
 let viteProcess = null;
 let requestedSignal = "";
@@ -37,7 +42,7 @@ process.once("SIGTERM", () => requestShutdown("SIGTERM"));
 
 try {
   apiServer = await startServer({ host: LOOPBACK_HOST, port: 0 });
-  const apiPort = requiredPort(apiServer.server.address()?.port);
+  const apiPort = /** @type {import("node:net").AddressInfo} */ (apiServer.server.address()).port;
   const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
   viteProcess = spawn(
     npmCommand,

package/patterns/minimal-foundation/example/eslint.config.mjs

@@ -1,4 +1,19 @@
-import { baseConfig, nodeConfig, vueConfig, webConfig } from "@jskit-ai/config-eslint/server";
+import {
+  baseConfig,
+  clientFeaturesConfig,
+  formatterConfig,
+  nodeConfig,
+  sizeLimitsConfig,
+  typedFeaturesConfig,
+  vueConfig,
+  webConfig
+} from "@jskit-ai/config-eslint/server";
+
+// The checks of https://mobily-enterprises.github.io/jskit-ai/guide/framework/typed-features and
+// https://mobily-enterprises.github.io/jskit-ai/guide/framework/client-features, as errors.
+const SERVER_SOURCES = ["packages/*/src/server/**", "packages/*/src/shared/**", "server/**", "server.js"];
+const CLIENT_SOURCES = ["packages/*/src/client/**", "src/**"];
+const HAND_WRITTEN_SOURCES = ["packages/*/src/**", "src/**", "config/**", "server/**", "server.js", "bin/**"];
 
 export default [
   {
@@ -13,7 +28,11 @@ export default [
     }
   },
   ...baseConfig,
+  ...typedFeaturesConfig(SERVER_SOURCES),
+  ...sizeLimitsConfig(HAND_WRITTEN_SOURCES),
   ...vueConfig,
+  ...clientFeaturesConfig(CLIENT_SOURCES),
   ...webConfig,
-  ...nodeConfig
+  ...nodeConfig,
+  ...formatterConfig([...SERVER_SOURCES, "config/**", "bin/**"])
 ];

package/patterns/minimal-foundation/example/package.json

@@ -34,21 +34,22 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.2.3",
+    "@jskit-ai/kernel": "0.2.4",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.8.5",
+    "pino": "^10.3.1",
     "json-rest-schema": "^1.0.17",
     "pinia": "^4.0.3",
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.2.3",
+    "@jskit-ai/http-runtime": "0.2.4",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.241",
-    "@jskit-ai/jskit-catalog": "0.2.9",
+    "@jskit-ai/config-eslint": "0.1.242",
+    "@jskit-ai/jskit-catalog": "0.2.11",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/minimal-foundation/example/playwright.config.mjs

@@ -4,7 +4,7 @@ const managedBaseUrl = String(process.env.PLAYWRIGHT_BASE_URL || "")
   .trim()
   .replace(/\/+$/u, "");
 const baseURL = managedBaseUrl || "http://127.0.0.1:4173";
-const storageState = String(process.env.VIBE64_PLAYWRIGHT_STORAGE_STATE || "").trim();
+const storageState = String(process.env.PLAYWRIGHT_STORAGE_STATE || "").trim();
 
 export default defineConfig({
   testDir: "./tests/e2e",

package/patterns/minimal-foundation/example/server/lib/envFile.js

@@ -0,0 +1,19 @@
+// .env is loaded into process.env, which every caller shares, at most once per process.
+let loaded = false;
+
+/** Loads .env into process.env once per process; a missing file is not an error. */
+function loadEnvFile() {
+  if (loaded) {
+    return;
+  }
+  try {
+    process.loadEnvFile(".env");
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+  loaded = true;
+}
+
+export { loadEnvFile };

package/patterns/minimal-foundation/example/server/lib/loggerOptions.js

@@ -0,0 +1,15 @@
+import pino from "pino";
+
+/**
+ * The Fastify logger's options. Fastify's logger serializes only the `err` key, so the same serializer under `error`
+ * keeps the message and stack of `logger.error({ error }, "...")`.
+ */
+function buildLoggerOptions() {
+  return {
+    serializers: {
+      error: pino.stdSerializers.err
+    }
+  };
+}
+
+export { buildLoggerOptions };

package/patterns/minimal-foundation/example/server/lib/runtimeEnv.js

@@ -1,7 +1,14 @@
-import { existsSync } from "node:fs";
+import { loadEnvFile } from "./envFile.js";
 import { surfaceRuntime } from "./surfaceRuntime.js";
 
-function toPort(value, fallback = 3000) {
+const DEFAULT_PORT = 3000;
+
+/**
+ * The port a value names, else the fallback.
+ * @param {string | undefined} value
+ * @param {number} fallback
+ */
+function toPort(value, fallback) {
   const parsed = Number.parseInt(String(value || "").trim(), 10);
   if (Number.isInteger(parsed) && parsed > 0) {
     return parsed;
@@ -9,29 +16,22 @@ function toPort(value, fallback = 3000) {
   return fallback;
 }
 
-let envLoaded = false;
-
-function ensureRuntimeEnvLoaded() {
-  if (envLoaded) {
-    return;
-  }
-  if (existsSync(".env")) {
-    process.loadEnvFile(".env");
-  }
-  envLoaded = true;
-}
-
+/**
+ * The process environment, with .env loaded and SERVER_SURFACE, PORT and HOST resolved. Every value stays a string,
+ * as the kernel's RuntimeEnv type says.
+ * @returns {import("@jskit-ai/kernel/server/types").RuntimeEnv}
+ */
 function resolveRuntimeEnv() {
-  ensureRuntimeEnvLoaded();
+  loadEnvFile();
   const serverSurface = surfaceRuntime.normalizeSurfaceMode(
     process.env.JSKIT_SERVER_SURFACE || process.env.SERVER_SURFACE
   );
   return {
     ...process.env,
     SERVER_SURFACE: serverSurface,
-    PORT: toPort(process.env.PORT, 3000),
+    PORT: String(toPort(process.env.PORT, DEFAULT_PORT)),
     HOST: String(process.env.HOST || "").trim() || "0.0.0.0"
   };
 }
 
-export { resolveRuntimeEnv };
+export { DEFAULT_PORT, resolveRuntimeEnv };

package/patterns/minimal-foundation/example/server.js

@@ -2,6 +2,7 @@ import Fastify from "fastify";
 import SerializerSelector from "@fastify/fast-json-stringify-compiler";
 import { createCachedResponseSerializerFactory } from "@jskit-ai/kernel/server/http";
 import fastifyStatic from "@fastify/static";
+import { buildLoggerOptions } from "./server/lib/loggerOptions.js";
 import { resolveRuntimeEnv } from "./server/lib/runtimeEnv.js";
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
@@ -11,11 +12,17 @@ import {
   resolveRuntimeProfileFromSurface
 } from "@jskit-ai/kernel/server/platform";
 import { loadAppConfigFromAppRoot } from "@jskit-ai/kernel/server/support";
-import { matchesPathPrefix, normalizePathname } from "@jskit-ai/kernel/shared/surface/paths";
+import {
+  API_BASE_PATH,
+  matchesPathPrefix,
+  normalizePathname,
+  toRequestPathname
+} from "@jskit-ai/kernel/shared/surface/paths";
 import { surfaceRuntime } from "./server/lib/surfaceRuntime.js";
 
+/** @typedef {import("@jskit-ai/kernel/server/types").RuntimeEnv} RuntimeEnv */
+
 const SPA_INDEX_FILE = "index.html";
-const API_BASE_PATH = "/api";
 const STATIC_GLOBAL_UI_PATHS = Object.freeze([
   "/assets",
   "/favicon.svg",
@@ -24,15 +31,6 @@ const STATIC_GLOBAL_UI_PATHS = Object.freeze([
   "/manifest.webmanifest"
 ]);
 
-function toRequestPathname(urlValue) {
-  const rawUrl = String(urlValue || "").trim() || "/";
-  try {
-    return normalizePathname(new URL(rawUrl, "http://localhost").pathname || "/");
-  } catch {
-    return normalizePathname(rawUrl.split("?")[0] || "/");
-  }
-}
-
 function isApiPath(pathname) {
   return matchesPathPrefix(pathname, API_BASE_PATH);
 }
@@ -41,15 +39,15 @@ function hasFileExtension(pathname) {
   return path.extname(normalizePathname(pathname)) !== "";
 }
 
-function resolveGlobalUiPaths(runtimeGlobalUiPaths = []) {
-  const paths = new Set(Array.isArray(runtimeGlobalUiPaths) ? runtimeGlobalUiPaths : []);
+function buildGlobalUiPaths(runtimeGlobalUiPaths) {
+  const paths = new Set(runtimeGlobalUiPaths);
   for (const staticPath of STATIC_GLOBAL_UI_PATHS) {
     paths.add(staticPath);
   }
   return [...paths];
 }
 
-function resolveStaticFilePath(pathname) {
+function toStaticFilePath(pathname) {
   const normalizedPathname = normalizePathname(pathname);
 
   const relativePath = normalizedPathname.replace(/^\/+/, "");
@@ -85,9 +83,13 @@ function canServeStaticFile(distRoot, relativePath) {
   return existsSync(resolvedPath);
 }
 
-async function createServer({ runtimeEnv = resolveRuntimeEnv() } = {}) {
+/**
+ * The application's Fastify server with its installed JSKIT runtime, for the environment given.
+ * @param {{ runtimeEnv: RuntimeEnv }} settings
+ */
+async function createServer({ runtimeEnv }) {
   const app = Fastify({
-    logger: true,
+    logger: buildLoggerOptions(),
     schemaController: {
       compilersFactory: {
         buildSerializer: createCachedResponseSerializerFactory(SerializerSelector())
@@ -126,7 +128,7 @@ async function createServer({ runtimeEnv = resolveRuntimeEnv() } = {}) {
     fastify: app,
     surfaceRuntime,
     serverSurface: runtimeEnv.SERVER_SURFACE,
-    globalUiPaths: resolveGlobalUiPaths(runtime?.globalUiPaths || [])
+    globalUiPaths: buildGlobalUiPaths(runtime.globalUiPaths)
   });
 
   if (hasWebBuild) {
@@ -140,10 +142,8 @@ async function createServer({ runtimeEnv = resolveRuntimeEnv() } = {}) {
   }
 
   app.setNotFoundHandler(async (request, reply) => {
-    const pathname = toRequestPathname(request?.url);
-    const method = String(request?.method || "GET")
-      .trim()
-      .toUpperCase();
+    const pathname = toRequestPathname(request.url);
+    const method = request.method;
     if (isApiPath(pathname) || (method !== "GET" && method !== "HEAD")) {
       return reply.code(404).send({
         message: `Route ${method}:${pathname} not found`,
@@ -152,7 +152,7 @@ async function createServer({ runtimeEnv = resolveRuntimeEnv() } = {}) {
       });
     }
     if (hasFileExtension(pathname)) {
-      const staticFilePath = resolveStaticFilePath(pathname);
+      const staticFilePath = toStaticFilePath(pathname);
       if (hasWebBuild && staticFilePath && canServeStaticFile(distRoot, staticFilePath)) {
         return reply.sendFile(staticFilePath);
       }
@@ -183,19 +183,22 @@ async function createServer({ runtimeEnv = resolveRuntimeEnv() } = {}) {
   return app;
 }
 
-async function startServer(options = {}) {
+/**
+ * Starts the server on the host and port given, else on the environment's HOST and PORT.
+ * @param {{ host?: string, port?: number }} [options]
+ */
+async function startServer({ host, port } = {}) {
   const runtimeEnv = resolveRuntimeEnv();
-  const configuredPort = options?.port === undefined ? runtimeEnv.PORT : Number(options.port);
-  const port = Number.isInteger(configuredPort) && configuredPort >= 0 ? configuredPort : runtimeEnv.PORT;
-  const host = String(options?.host || "").trim() || runtimeEnv.HOST;
+  const listenHost = host || runtimeEnv.HOST;
+  const listenPort = port ?? Number(runtimeEnv.PORT);
   const app = await createServer({
     runtimeEnv: {
       ...runtimeEnv,
-      HOST: host,
-      PORT: port
+      HOST: listenHost,
+      PORT: String(listenPort)
     }
   });
-  await app.listen({ port, host });
+  await app.listen({ port: listenPort, host: listenHost });
   return app;
 }
 

package/patterns/minimal-foundation/example/tests/server/smoke.test.js

@@ -1,9 +1,10 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import { createServer } from "../../server.js";
+import { resolveRuntimeEnv } from "../../server/lib/runtimeEnv.js";
 
 test("GET /api/health returns built-in health response", async () => {
-  const app = await createServer();
+  const app = await createServer({ runtimeEnv: resolveRuntimeEnv() });
   const response = await app.inject({
     method: "GET",
     url: "/api/health"

package/patterns/shell-foundation/PATTERN.md

@@ -59,6 +59,33 @@ not convert those choices into a generator questionnaire.
   scrims or coordinates.
 - Do not attach generator provenance, receipts, completion state, or replay
   history to copied source.
+- Server code the application adds follows
+  [typed features](https://github.com/mobily-enterprises/jskit-ai/blob/main/packages/agent-docs/site/guide/framework/typed-features.md):
+  a provided capability exports its type from `types.js`; collaborators arrive
+  through declared capabilities, typed in a JSDoc `@param` and required, never
+  probed or defaulted to nothing; slots are `optional` tokens with a named
+  default; one `create<Name>Actions({ <api> })` per feature returns frozen
+  actions whose `execute` is one call; every `create*` returns a frozen object
+  of named functions; one copy of each helper per package; files stay under
+  750 lines and functions under 600. `createServer({ runtimeEnv })` requires
+  the environment it runs with, typed as the kernel's `RuntimeEnv` (the process
+  environment, string values: `resolveRuntimeEnv()` keeps `PORT` a string), and
+  `server.js` takes `API_BASE_PATH` and `toRequestPathname` from the kernel's
+  `shared/surface/paths`. `server/lib/envFile.js` loads `.env` once per process
+  for every entry point. `server/lib/loggerOptions.js` gives Fastify's logger
+  pino's error serializer under `error` as well as `err`, so
+  `logger.error({ error }, "...")` keeps the error's message and stack. `eslint.config.mjs` holds
+  server and shared code to every typed-features rule (`typedFeaturesConfig`),
+  client code (`src/**` and `packages/*/src/client/**`, Vue components
+  included) to the client rules (`clientFeaturesConfig`), all hand-written
+  code to the size limits (`sizeLimitsConfig`), and server, config and script
+  code to the formatter (`formatterConfig`), all as errors, so `npm run lint`
+  reports code that breaks the
+  [typed features guide](https://mobily-enterprises.github.io/jskit-ai/guide/framework/typed-features)
+  or the
+  [client features guide](https://mobily-enterprises.github.io/jskit-ai/guide/framework/client-features).
+  Client code the application adds keeps simple, direct code first, and types
+  each provider hook with `@jskit-ai/kernel/client/types`.
 
 ## Framework APIs
 
@@ -126,3 +153,5 @@ horizontal overflow.
 - Do not push content down with persistent transient-error banners; use the
   standard toast/error presentation.
 - Do not preserve historical template ownership after copying.
+- Do not probe a collaborator, default one to `null`, `{}` or a no-op, fill a
+  slot with a setter after construction, or keep a module-level registry.

package/patterns/shell-foundation/example/AGENTS.md

@@ -8,6 +8,20 @@ Framework references:
 - `https://mobily-enterprises.github.io/jskit-ai/guide/`
 - `https://mobily-enterprises.github.io/jskit-ai/patterns/`
 
+Before writing or reviewing server code (a feature, provider, action, service,
+repository, route, error or test), read the typed features guide at
+`https://mobily-enterprises.github.io/jskit-ai/guide/framework/typed-features`.
+`npm run lint` checks its rules, and each finding links the section that
+explains it; `npm run verify` adds the package graph, tests and build. Fix a
+finding in the code; excuse one only with the guide's `readable-check: allow`
+comment and reason prefix.
+
+Before writing or reviewing client code (a composable, component, client
+factory or client provider), read the client features guide at
+`https://mobily-enterprises.github.io/jskit-ai/guide/framework/client-features`.
+Simple, direct code comes first: never add a layer, wrapper, registry or tiny
+module only to satisfy a rule. `npm run lint` checks its rules too.
+
 Before implementation, read the narrow relevant source pattern completely. If
 its owner package is installed, prefer that version-matched package-owned copy.
 Do not install an unrelated runtime package only to read documentation.

package/patterns/shell-foundation/example/bin/develop.js

@@ -1,11 +1,16 @@
 import { spawn } from "node:child_process";
 import { startServer } from "../server.js";
+import { DEFAULT_PORT } from "../server/lib/runtimeEnv.js";
 
 const LOOPBACK_HOST = "127.0.0.1";
 
-function requiredPort(value, fallback = 3000) {
-  const normalized = String(value || "").trim();
-  const parsed = Number.parseInt(normalized || String(fallback), 10);
+/**
+ * The development port a value names; anything that is not a TCP port stops the launcher.
+ * @param {string} value
+ */
+function requiredPort(value) {
+  const normalized = value.trim();
+  const parsed = Number.parseInt(normalized, 10);
   if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65_535) {
     throw new Error(`Invalid development port: ${normalized || "(empty)"}.`);
   }
@@ -20,7 +25,7 @@ function waitForChild(child) {
 }
 
 const previewHost = String(process.env.HOST || "").trim() || "0.0.0.0";
-const previewPort = requiredPort(process.env.PORT);
+const previewPort = requiredPort(process.env.PORT || String(DEFAULT_PORT));
 let apiServer = null;
 let viteProcess = null;
 let requestedSignal = "";
@@ -37,7 +42,7 @@ process.once("SIGTERM", () => requestShutdown("SIGTERM"));
 
 try {
   apiServer = await startServer({ host: LOOPBACK_HOST, port: 0 });
-  const apiPort = requiredPort(apiServer.server.address()?.port);
+  const apiPort = /** @type {import("node:net").AddressInfo} */ (apiServer.server.address()).port;
   const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
   viteProcess = spawn(
     npmCommand,

package/patterns/shell-foundation/example/eslint.config.mjs

@@ -1,4 +1,19 @@
-import { baseConfig, nodeConfig, vueConfig, webConfig } from "@jskit-ai/config-eslint/server";
+import {
+  baseConfig,
+  clientFeaturesConfig,
+  formatterConfig,
+  nodeConfig,
+  sizeLimitsConfig,
+  typedFeaturesConfig,
+  vueConfig,
+  webConfig
+} from "@jskit-ai/config-eslint/server";
+
+// The checks of https://mobily-enterprises.github.io/jskit-ai/guide/framework/typed-features and
+// https://mobily-enterprises.github.io/jskit-ai/guide/framework/client-features, as errors.
+const SERVER_SOURCES = ["packages/*/src/server/**", "packages/*/src/shared/**", "server/**", "server.js"];
+const CLIENT_SOURCES = ["packages/*/src/client/**", "src/**"];
+const HAND_WRITTEN_SOURCES = ["packages/*/src/**", "src/**", "config/**", "server/**", "server.js", "bin/**"];
 
 export default [
   {
@@ -13,7 +28,11 @@ export default [
     }
   },
   ...baseConfig,
+  ...typedFeaturesConfig(SERVER_SOURCES),
+  ...sizeLimitsConfig(HAND_WRITTEN_SOURCES),
   ...vueConfig,
+  ...clientFeaturesConfig(CLIENT_SOURCES),
   ...webConfig,
-  ...nodeConfig
+  ...nodeConfig,
+  ...formatterConfig([...SERVER_SOURCES, "config/**", "bin/**"])
 ];

package/patterns/shell-foundation/example/package.json

@@ -34,23 +34,24 @@
   "dependencies": {
     "@local/main": "0.1.0",
     "@fastify/static": "^10.1.3",
-    "@jskit-ai/kernel": "0.2.3",
+    "@jskit-ai/kernel": "0.2.4",
     "@tanstack/vue-query": "^5.101.0",
     "fastify": "^5.8.5",
+    "pino": "^10.3.1",
     "json-rest-schema": "^1.0.17",
     "pinia": "^4.0.3",
     "vue": "^3.5.44",
     "vue-router": "^5.3.1",
     "vuetify": "^4.1.2",
-    "@jskit-ai/http-runtime": "0.2.3",
+    "@jskit-ai/http-runtime": "0.2.4",
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/shell-web": "0.2.3",
+    "@jskit-ai/shell-web": "0.2.4",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.241",
-    "@jskit-ai/jskit-catalog": "0.2.9",
+    "@jskit-ai/config-eslint": "0.1.242",
+    "@jskit-ai/jskit-catalog": "0.2.11",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/shell-foundation/example/packages/main/package.json

@@ -9,7 +9,7 @@
   },
   "description": "App-local runtime composition and lightweight glue.",
   "dependencies": {
-    "@jskit-ai/kernel": "0.2.3"
+    "@jskit-ai/kernel": "0.2.4"
   },
   "jskit": {
     "kind": "runtime",

package/patterns/shell-foundation/example/packages/main/src/client/providers/MainClientProvider.js

@@ -8,6 +8,7 @@ const MainClientProvider = defineProvider({
   requires: {
     components: "client.components"
   },
+  /** @param {{ components: import("@jskit-ai/kernel/client/types").ClientComponents }} capabilities */
   setup({ components }) {
     components.register("local.main.ui.menu-link-item", MenuLinkItem);
     components.register("local.main.ui.surface-aware-menu-link-item", SurfaceAwareMenuLinkItem);

package/patterns/shell-foundation/example/playwright.config.mjs

@@ -4,7 +4,7 @@ const managedBaseUrl = String(process.env.PLAYWRIGHT_BASE_URL || "")
   .trim()
   .replace(/\/+$/u, "");
 const baseURL = managedBaseUrl || "http://127.0.0.1:4173";
-const storageState = String(process.env.VIBE64_PLAYWRIGHT_STORAGE_STATE || "").trim();
+const storageState = String(process.env.PLAYWRIGHT_STORAGE_STATE || "").trim();
 
 export default defineConfig({
   testDir: "./tests/e2e",

package/patterns/shell-foundation/example/server/lib/envFile.js

@@ -0,0 +1,19 @@
+// .env is loaded into process.env, which every caller shares, at most once per process.
+let loaded = false;
+
+/** Loads .env into process.env once per process; a missing file is not an error. */
+function loadEnvFile() {
+  if (loaded) {
+    return;
+  }
+  try {
+    process.loadEnvFile(".env");
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+  loaded = true;
+}
+
+export { loadEnvFile };

package/patterns/shell-foundation/example/server/lib/loggerOptions.js

@@ -0,0 +1,15 @@
+import pino from "pino";
+
+/**
+ * The Fastify logger's options. Fastify's logger serializes only the `err` key, so the same serializer under `error`
+ * keeps the message and stack of `logger.error({ error }, "...")`.
+ */
+function buildLoggerOptions() {
+  return {
+    serializers: {
+      error: pino.stdSerializers.err
+    }
+  };
+}
+
+export { buildLoggerOptions };

package/patterns/shell-foundation/example/server/lib/runtimeEnv.js

@@ -1,7 +1,14 @@
-import { existsSync } from "node:fs";
+import { loadEnvFile } from "./envFile.js";
 import { surfaceRuntime } from "./surfaceRuntime.js";
 
-function toPort(value, fallback = 3000) {
+const DEFAULT_PORT = 3000;
+
+/**
+ * The port a value names, else the fallback.
+ * @param {string | undefined} value
+ * @param {number} fallback
+ */
+function toPort(value, fallback) {
   const parsed = Number.parseInt(String(value || "").trim(), 10);
   if (Number.isInteger(parsed) && parsed > 0) {
     return parsed;
@@ -9,29 +16,22 @@ function toPort(value, fallback = 3000) {
   return fallback;
 }
 
-let envLoaded = false;
-
-function ensureRuntimeEnvLoaded() {
-  if (envLoaded) {
-    return;
-  }
-  if (existsSync(".env")) {
-    process.loadEnvFile(".env");
-  }
-  envLoaded = true;
-}
-
+/**
+ * The process environment, with .env loaded and SERVER_SURFACE, PORT and HOST resolved. Every value stays a string,
+ * as the kernel's RuntimeEnv type says.
+ * @returns {import("@jskit-ai/kernel/server/types").RuntimeEnv}
+ */
 function resolveRuntimeEnv() {
-  ensureRuntimeEnvLoaded();
+  loadEnvFile();
   const serverSurface = surfaceRuntime.normalizeSurfaceMode(
     process.env.JSKIT_SERVER_SURFACE || process.env.SERVER_SURFACE
   );
   return {
     ...process.env,
     SERVER_SURFACE: serverSurface,
-    PORT: toPort(process.env.PORT, 3000),
+    PORT: String(toPort(process.env.PORT, DEFAULT_PORT)),
     HOST: String(process.env.HOST || "").trim() || "0.0.0.0"
   };
 }
 
-export { resolveRuntimeEnv };
+export { DEFAULT_PORT, resolveRuntimeEnv };