keryx 0.21.5 → 0.21.7

package/classes/API.ts

@@ -92,6 +92,8 @@ export class API {
       }
     }
 
+    this.validateInitializerProperties("initialize");
+
     this.initialized = true;
     this.logger.warn("--- 🔄  Initializing complete ---");
   }
@@ -138,6 +140,8 @@ export class API {
       }
     }
 
+    this.validateInitializerProperties("start");
+
     this.started = true;
     this.logger.warn("--- 🔼  Starting complete ---");
   }
@@ -272,4 +276,37 @@ export class API {
   private sortInitializers(key: InitializerSortKeys) {
     this.initializers.sort((a, b) => a[key] - b[key]);
   }
+
+  /**
+   * Assert that every initializer which claims an API namespace (via
+   * `declaresAPIProperty`) has actually attached `api[initializer.name]`.
+   * Closes the silent-drift gap between TypeScript module augmentation
+   * and runtime property assignment — a missing namespace becomes a fast,
+   * loud startup failure instead of a confusing `Cannot read property of
+   * undefined` deep inside a request handler.
+   *
+   * Initializers excluded from the current `runMode` are skipped during the
+   * `start` phase since their `start()` method never ran.
+   */
+  private validateInitializerProperties(phase: "initialize" | "start") {
+    const missing: string[] = [];
+    for (const initializer of this.initializers) {
+      if (initializer.declaresAPIProperty === false) continue;
+      if (phase === "start" && !initializer.runModes.includes(this.runMode)) {
+        continue;
+      }
+      if (this[initializer.name] == null) {
+        missing.push(initializer.name);
+      }
+    }
+    if (missing.length > 0) {
+      throw new TypedError({
+        type: ErrorType.INITIALIZER_VALIDATION,
+        message:
+          `Initializers did not attach their namespace to api after the ${phase} phase: ` +
+          `${missing.join(", ")}. Each initializer must either return a namespace object ` +
+          `from initialize() (and/or populate it in start()), or set declaresAPIProperty = false.`,
+      });
+    }
+  }
 }

package/classes/Connection.ts

@@ -1,10 +1,10 @@
-import colors from "colors";
 import { randomUUID } from "crypto";
 import { api, logger } from "../api";
 import { config } from "../config";
 import type { PubSubMessage } from "../initializers/pubsub";
 import type { SessionData } from "../initializers/session";
 import type { RateLimitInfo } from "../middleware/rateLimit";
+import { ansi } from "../util/ansi";
 import { isSecret } from "../util/zodMixins";
 import type { Action, ActionParams } from "./Action";
 import { LogFormat } from "./Logger";
@@ -380,20 +380,20 @@ function logAction(opts: {
     logger.info(`action: ${opts.actionName}`, data);
   } else {
     const loggingParams = config.logger.colorize
-      ? colors.gray(JSON.stringify(opts.params))
+      ? ansi.gray(JSON.stringify(opts.params))
       : JSON.stringify(opts.params);
 
     const statusMessage = `[ACTION:${opts.connectionType.toUpperCase()}:${opts.status}]`;
     const messagePrefix = config.logger.colorize
       ? opts.status === "OK"
-        ? colors.bgBlue(statusMessage)
-        : colors.bgMagenta(statusMessage)
+        ? ansi.bgBlue(statusMessage)
+        : ansi.bgMagenta(statusMessage)
       : statusMessage;
 
     const errorStack =
       opts.error && opts.error.stack
         ? config.logger.colorize
-          ? "\r\n" + colors.gray(opts.error.stack)
+          ? "\r\n" + ansi.gray(opts.error.stack)
           : "\r\n" + opts.error.stack
         : "";
 

package/classes/Initializer.ts

@@ -17,6 +17,13 @@ export abstract class Initializer {
   stopPriority: number;
   /** Which run modes this initializer participates in. Defaults to both SERVER and CLI. */
   runModes: RUN_MODE[];
+  /**
+   * Whether this initializer attaches a property named `this.name` on the `api` singleton.
+   * Runtime validation in `API.initialize()` and `API.start()` will fail if the declared
+   * property is missing. Default: `true`. Set to `false` for initializers that intentionally
+   * don't augment the `API` interface.
+   */
+  declaresAPIProperty: boolean;
 
   constructor(name: string) {
     this.name = name;
@@ -24,6 +31,7 @@ export abstract class Initializer {
     this.startPriority = 1000;
     this.stopPriority = 1000;
     this.runModes = [RUN_MODE.SERVER, RUN_MODE.CLI];
+    this.declaresAPIProperty = true;
   }
 
   /**

package/classes/Logger.ts

@@ -1,6 +1,5 @@
-import colors from "colors";
-
 import type { configLogger } from "../config/logger";
+import { ansi } from "../util/ansi";
 
 export enum LogLevel {
   trace = "trace",
@@ -133,7 +132,7 @@ export class Logger {
   private logText(level: LogLevel, message: string, data?: any) {
     let timestamp = this.includeTimestamps ? `${new Date().toISOString()}` : "";
     if (this.colorize && timestamp.length > 0) {
-      timestamp = colors.gray(timestamp);
+      timestamp = ansi.gray(timestamp);
     }
 
     let formattedLevel = `[${level}]`;
@@ -146,7 +145,7 @@ export class Logger {
         ? JSON.stringify(data, null, this.jSONObjectParsePadding)
         : "";
     if (this.colorize && prettyObject.length > 0) {
-      prettyObject = colors.cyan(prettyObject);
+      prettyObject = ansi.cyan(prettyObject);
     }
 
     this.outputStream(
@@ -176,17 +175,17 @@ export class Logger {
   private colorFromLogLevel(level: LogLevel) {
     switch (level) {
       case LogLevel.trace:
-        return colors.gray;
+        return ansi.gray;
       case LogLevel.debug:
-        return colors.blue;
+        return ansi.blue;
       case LogLevel.info:
-        return colors.green;
+        return ansi.green;
       case LogLevel.warn:
-        return colors.yellow;
+        return ansi.yellow;
       case LogLevel.error:
-        return colors.red;
+        return ansi.red;
       case LogLevel.fatal:
-        return colors.magenta;
+        return ansi.magenta;
     }
   }
 }

package/initializers/mcp.ts

@@ -1,11 +1,11 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
-import colors from "colors";
 import { randomUUID } from "crypto";
 import { api, logger } from "../api";
 import { Initializer } from "../classes/Initializer";
 import { ErrorType, TypedError } from "../classes/TypedError";
 import { config } from "../config";
+import { ansi } from "../util/ansi";
 import { buildCorsHeaders, getExternalOrigin } from "../util/http";
 import {
   createMcpServer,
@@ -236,7 +236,7 @@ export class McpInitializer extends Initializer {
 
     const mcpUrl = `${config.server.web.applicationUrl}${mcpRoute}`;
     const startMessage = `started MCP server @ ${mcpUrl}`;
-    logger.info(logger.colorize ? colors.bgBlue(startMessage) : startMessage);
+    logger.info(logger.colorize ? ansi.bgBlue(startMessage) : startMessage);
   }
 
   async stop() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keryx",
-  "version": "0.21.5",
+  "version": "0.21.7",
   "module": "index.ts",
   "type": "module",
   "license": "MIT",
@@ -85,7 +85,6 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/sdk-metrics": "^2.6.1",
-    "colors": "^1.4.0",
     "ioredis": "^5.10.1",
     "mustache": "^4.2.0",
     "node-resque": "^9.5.0",
@@ -103,7 +102,6 @@
   },
   "devDependencies": {
     "@types/bun": "^1.3.11",
-    "@types/formidable": "^3.5.1",
     "drizzle-kit": "^0.31.10",
     "drizzle-zod": "^0.8.3"
   }

package/servers/web.ts

@@ -1,6 +1,5 @@
 import { parse } from "node:url";
 import type { ServerWebSocket } from "bun";
-import colors from "colors";
 import { randomUUID } from "crypto";
 import { api, logger } from "../api";
 import { type HTTP_METHOD } from "../classes/Action";
@@ -10,6 +9,7 @@ import { StreamingResponse } from "../classes/StreamingResponse";
 import { ErrorStatusCodes, ErrorType, TypedError } from "../classes/TypedError";
 import { config } from "../config";
 import type { PubSubMessage } from "../initializers/pubsub";
+import { ansi } from "../util/ansi";
 import { isOriginAllowed } from "../util/http";
 import { compressResponse } from "../util/webCompression";
 import {
@@ -67,7 +67,7 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
       this.port = server.port ?? config.server.web.port;
       this.url = `http://${config.server.web.host}:${this.port}`;
       const startMessage = `started server @ ${this.url}`;
-      logger.info(logger.colorize ? colors.bgBlue(startMessage) : startMessage);
+      logger.info(logger.colorize ? ansi.bgBlue(startMessage) : startMessage);
     } catch (e) {
       await Bun.sleep(1000);
       startupAttempts++;

package/util/ansi.ts

@@ -0,0 +1,14 @@
+const RESET = "\x1b[0m";
+
+/** ANSI terminal color helpers. Each wraps a string in an escape code and reset suffix. */
+export const ansi = {
+  gray: (s: string) => `\x1b[90m${s}${RESET}`,
+  blue: (s: string) => `\x1b[34m${s}${RESET}`,
+  cyan: (s: string) => `\x1b[36m${s}${RESET}`,
+  green: (s: string) => `\x1b[32m${s}${RESET}`,
+  yellow: (s: string) => `\x1b[33m${s}${RESET}`,
+  red: (s: string) => `\x1b[31m${s}${RESET}`,
+  magenta: (s: string) => `\x1b[35m${s}${RESET}`,
+  bgBlue: (s: string) => `\x1b[44m${s}${RESET}`,
+  bgMagenta: (s: string) => `\x1b[45m${s}${RESET}`,
+};