llm-mock-server 1.0.2 → 1.0.4

package/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

package/.github/workflows/test.yml

@@ -27,6 +27,9 @@ jobs:
       - name: Type check
         run: tsc --noEmit && tsc --noEmit -p tsconfig.test.json
 
+      - name: Format check
+        run: npm run fmt:check
+
       - name: Lint
         run: npm run lint
 

package/.oxfmtrc.json

@@ -0,0 +1,9 @@
+{
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "all",
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "ignorePatterns": ["dist/", "coverage/"]
+}

package/README.md

@@ -24,6 +24,7 @@ A mock LLM server for testing. It handles OpenAI `/chat/completions`, Anthropic
 - [Logging](#logging)
 - [CLI](#cli)
 - [Security](#security)
+- [Architecture](#architecture)
 - [Licence](#licence)
 
 ## Quick start
@@ -423,6 +424,10 @@ The server binds to `127.0.0.1` by default, so it's only reachable from your mac
 
 Request bodies are capped at 1 MB by Fastify's default. Responses are serialised through JSON, so there's no injection risk in the SSE output.
 
+## Architecture
+
+See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for how the codebase is structured, the request lifecycle, rule matching, and response serialisation.
+
 ## Licence
 
 MIT License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-mock-server",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "A standalone mock LLM server for deterministic testing: OpenAI, Anthropic, and Responses API formats",
   "type": "module",
   "engines": {
@@ -20,10 +20,12 @@
   },
   "scripts": {
     "build": "tsc",
+    "fmt": "oxfmt --write src/ test/",
+    "fmt:check": "oxfmt --check src/ test/",
     "lint": "oxlint --tsconfig tsconfig.json --import-plugin --vitest-plugin src/ test/",
     "test": "vitest run",
     "test:watch": "vitest",
-    "check": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json && npm run lint && npm test",
+    "check": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json && npm run fmt:check && npm run lint && npm test",
     "dev": "tsx src/cli.ts",
     "start": "node dist/cli.js"
   },
@@ -48,6 +50,7 @@
   "devDependencies": {
     "@types/node": "25.5.0",
     "@vitest/coverage-v8": "4.1.0",
+    "oxfmt": "0.40.0",
     "oxlint": "1.55.0",
     "tsx": "4.21.0",
     "typescript": "5.9.3",

package/src/cli-validators.ts

@@ -29,7 +29,9 @@ export function parseLogLevel(value: string): LogLevel {
 
 export async function parseHost(value: string): Promise<string> {
   if (!value) {
-    throw new Error(`Invalid host "${value}". Must be a resolvable hostname or IP address.`);
+    throw new Error(
+      `Invalid host "${value}". Must be a resolvable hostname or IP address.`,
+    );
   }
   if (value === "localhost" || isIP(value) !== 0) {
     return value;
@@ -38,14 +40,18 @@ export async function parseHost(value: string): Promise<string> {
     await lookup(value);
     return value;
   } catch {
-    throw new Error(`Invalid host "${value}". Must be a resolvable hostname or IP address.`);
+    throw new Error(
+      `Invalid host "${value}". Must be a resolvable hostname or IP address.`,
+    );
   }
 }
 
 export function parseChunkSize(value: string): number {
   const size = parseInt(value, 10);
   if (isNaN(size) || size < 0) {
-    throw new Error(`Invalid chunk size "${value}". Must be a non-negative integer.`);
+    throw new Error(
+      `Invalid chunk size "${value}". Must be a non-negative integer.`,
+    );
   }
   return size;
 }
@@ -53,7 +59,9 @@ export function parseChunkSize(value: string): number {
 export function parseLatency(value: string): number {
   const ms = parseInt(value, 10);
   if (isNaN(ms) || ms < 0) {
-    throw new Error(`Invalid latency "${value}". Must be a non-negative integer (ms).`);
+    throw new Error(
+      `Invalid latency "${value}". Must be a non-negative integer (ms).`,
+    );
   }
   return ms;
 }

package/src/cli.ts

@@ -6,7 +6,13 @@ import { Command } from "commander";
 import pc from "picocolors";
 import { MockServer } from "./mock-server.js";
 import { Logger } from "./logger.js";
-import { parsePort, parseHost, parseLogLevel, parseChunkSize, parseLatency } from "./cli-validators.js";
+import {
+  parsePort,
+  parseHost,
+  parseLogLevel,
+  parseChunkSize,
+  parseLatency,
+} from "./cli-validators.js";
 
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json") as { version: string };
@@ -58,12 +64,18 @@ async function start(options: StartOptions): Promise<void> {
 
   if (!quiet) {
     console.log();
-    console.log(`  ${pc.bold(pc.cyan("llm-mock-server"))} ${pc.dim(`v${version}`)}`);
+    console.log(
+      `  ${pc.bold(pc.cyan("llm-mock-server"))} ${pc.dim(`v${version}`)}`,
+    );
     console.log();
     console.log(`  ${pc.dim("Port")}       ${pc.bold(String(port))}`);
-    console.log(`  ${pc.dim("Rules")}      ${pc.bold(String(server.ruleCount))} loaded`);
+    console.log(
+      `  ${pc.dim("Rules")}      ${pc.bold(String(server.ruleCount))} loaded`,
+    );
     if (latency > 0) {
-      console.log(`  ${pc.dim("Latency")}    ${pc.bold(`${String(latency)}ms`)} per chunk`);
+      console.log(
+        `  ${pc.dim("Latency")}    ${pc.bold(`${String(latency)}ms`)} per chunk`,
+      );
     }
     console.log(
       `  ${pc.dim("Endpoints")}  ${pc.green("/v1/chat/completions")}, ${pc.green("/v1/messages")}, ${pc.green("/v1/responses")}`,
@@ -73,11 +85,10 @@ async function start(options: StartOptions): Promise<void> {
 
   if (options.watch && options.rules) {
     const rulesPath = options.rules;
-    let reloading = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
     watch(rulesPath, { recursive: true }, () => {
-      if (reloading) return;
-      reloading = true;
-      setTimeout(async () => {
+      clearTimeout(timer);
+      timer = setTimeout(async () => {
         try {
           server.reset();
           await server.load(rulesPath);
@@ -86,7 +97,6 @@ async function start(options: StartOptions): Promise<void> {
         } catch (err) {
           logger.error("Failed to reload rules", err);
         }
-        reloading = false;
       }, WATCH_DEBOUNCE_MS);
     });
     logger.info(`Watching ${rulesPath} for changes`);
@@ -103,8 +113,12 @@ async function start(options: StartOptions): Promise<void> {
     process.exit(0);
   };
 
-  process.on("SIGINT", () => { shutdown("SIGINT").catch(() => process.exit(1)); });
-  process.on("SIGTERM", () => { shutdown("SIGTERM").catch(() => process.exit(1)); });
+  process.on("SIGINT", () => {
+    shutdown("SIGINT").catch(() => process.exit(1));
+  });
+  process.on("SIGTERM", () => {
+    shutdown("SIGTERM").catch(() => process.exit(1));
+  });
 }
 
 const program = new Command()

package/src/formats/anthropic/parse.ts

@@ -4,18 +4,27 @@ import { AnthropicRequestSchema, type AnthropicRequest } from "./schema.js";
 
 function extractSystem(system: AnthropicRequest["system"]): Message[] {
   if (system == null) return [];
-  if (typeof system === "string") return system ? [{ role: "system", content: system }] : [];
+  if (typeof system === "string")
+    return system ? [{ role: "system", content: system }] : [];
   const text = system.map((b) => b.text).join("\n");
   return text ? [{ role: "system", content: text }] : [];
 }
 
-function extractContent(content: AnthropicRequest["messages"][number]["content"]): { content: string; toolCallId?: string | undefined } {
+function extractContent(
+  content: AnthropicRequest["messages"][number]["content"],
+): {
+  content: string;
+  toolCallId?: string | undefined;
+} {
   if (typeof content === "string") return { content };
   const text = content
     .filter((b): b is { type: "text"; text: string } => b.type === "text")
     .map((b) => b.text)
     .join("\n");
-  const toolResult = content.find((b): b is { type: "tool_result"; tool_use_id: string } => b.type === "tool_result");
+  const toolResult = content.find(
+    (b): b is { type: "tool_result"; tool_use_id: string } =>
+      b.type === "tool_result",
+  );
   const toolCallId = toolResult?.tool_use_id;
   return { content: text, toolCallId };
 }
@@ -27,7 +36,9 @@ function parseMessages(req: AnthropicRequest): readonly Message[] {
     return {
       role: m.role,
       content: extracted.content,
-      ...(extracted.toolCallId !== undefined && { toolCallId: extracted.toolCallId }),
+      ...(extracted.toolCallId !== undefined && {
+        toolCallId: extracted.toolCallId,
+      }),
     };
   });
   return [...system, ...conversation];
@@ -44,5 +55,13 @@ function parseTools(req: AnthropicRequest): readonly ToolDef[] | undefined {
 
 export function parseRequest(body: unknown, meta?: RequestMeta): MockRequest {
   const req = AnthropicRequestSchema.parse(body);
-  return buildMockRequest("anthropic", req, parseMessages(req), parseTools(req), "claude-sonnet-4-6", body, meta);
+  return buildMockRequest(
+    "anthropic",
+    req,
+    parseMessages(req),
+    parseTools(req),
+    "claude-sonnet-4-6",
+    body,
+    meta,
+  );
 }

package/src/formats/anthropic/schema.ts

@@ -1,6 +1,9 @@
 import { z } from "zod";
 
-export { AnthropicRequestSchema, type AnthropicRequest } from "llm-schemas/anthropic";
+export {
+  AnthropicRequestSchema,
+  type AnthropicRequest,
+} from "llm-schemas/anthropic";
 
 const ResponseContentBlockSchema = z.object({
   type: z.string(),
@@ -28,18 +31,23 @@ export type AnthropicMessageStart = z.infer<typeof AnthropicMessageStartSchema>;
 export const AnthropicBlockEventSchema = z.object({
   index: z.number(),
   content_block: ResponseContentBlockSchema.optional(),
-  delta: z.object({
-    type: z.string(),
-    text: z.string().optional(),
-    thinking: z.string().optional(),
-    partial_json: z.string().optional(),
-  }).optional(),
+  delta: z
+    .object({
+      type: z.string(),
+      text: z.string().optional(),
+      thinking: z.string().optional(),
+      partial_json: z.string().optional(),
+    })
+    .optional(),
 });
 
 export type AnthropicBlockEvent = z.infer<typeof AnthropicBlockEventSchema>;
 
 export const AnthropicDeltaSchema = z.object({
-  delta: z.object({ stop_reason: z.string(), stop_sequence: z.string().nullable() }),
+  delta: z.object({
+    stop_reason: z.string(),
+    stop_sequence: z.string().nullable(),
+  }),
   usage: z.object({ output_tokens: z.number() }),
 });
 

package/src/formats/anthropic/serialize.ts

@@ -1,21 +1,49 @@
 import type { ReplyObject, ReplyOptions } from "../../types.js";
 import type { SSEChunk } from "../types.js";
-import { splitText, genId, toolId, shouldEmitText, finishReason, DEFAULT_USAGE } from "../serialize-helpers.js";
+import {
+  splitText,
+  genId,
+  toolId,
+  shouldEmitText,
+  finishReason,
+  DEFAULT_USAGE,
+} from "../serialize-helpers.js";
 
 function buildUsage(usage: { input: number; output: number }) {
   return { input_tokens: usage.input, output_tokens: usage.output };
 }
 
-function contentBlock(index: number, startBlock: unknown, deltas: SSEChunk[]): SSEChunk[] {
+function contentBlock(
+  index: number,
+  startBlock: unknown,
+  deltas: SSEChunk[],
+): SSEChunk[] {
   return [
-    { event: "content_block_start", data: JSON.stringify({ type: "content_block_start", index, content_block: startBlock }) },
+    {
+      event: "content_block_start",
+      data: JSON.stringify({
+        type: "content_block_start",
+        index,
+        content_block: startBlock,
+      }),
+    },
     ...deltas,
-    { event: "content_block_stop", data: JSON.stringify({ type: "content_block_stop", index }) },
+    {
+      event: "content_block_stop",
+      data: JSON.stringify({ type: "content_block_stop", index }),
+    },
   ];
 }
 
 function delta(index: number, payload: Record<string, unknown>): SSEChunk {
-  return { event: "content_block_delta", data: JSON.stringify({ type: "content_block_delta", index, delta: payload }) };
+  return {
+    event: "content_block_delta",
+    data: JSON.stringify({
+      type: "content_block_delta",
+      index,
+      delta: payload,
+    }),
+  };
 }
 
 function reasoningBlock(i: number, reasoning: string): SSEChunk[] {
@@ -28,68 +56,124 @@ function textBlock(i: number, text: string, chunkSize: number): SSEChunk[] {
   return contentBlock(
     i,
     { type: "text", text: "" },
-    splitText(text, chunkSize).map((piece) => delta(i, { type: "text_delta", text: piece })),
+    splitText(text, chunkSize).map((piece) =>
+      delta(i, { type: "text_delta", text: piece }),
+    ),
   );
 }
 
-function toolBlocks(startIndex: number, tools: ReplyObject["tools"]): SSEChunk[] {
+function toolBlocks(
+  startIndex: number,
+  tools: ReplyObject["tools"],
+): SSEChunk[] {
   return (tools ?? []).flatMap((tool, i) => {
     const idx = startIndex + i;
     const id = toolId(tool, "toolu", idx);
     return contentBlock(
       idx,
       { type: "tool_use", id, name: tool.name, input: {} },
-      [delta(idx, { type: "input_json_delta", partial_json: JSON.stringify(tool.args) })],
+      [
+        delta(idx, {
+          type: "input_json_delta",
+          partial_json: JSON.stringify(tool.args),
+        }),
+      ],
     );
   });
 }
 
-export function serialize(reply: ReplyObject, model: string, options: ReplyOptions = {}): readonly SSEChunk[] {
+export function serialize(
+  reply: ReplyObject,
+  model: string,
+  options: ReplyOptions = {},
+): readonly SSEChunk[] {
   const id = genId("msg");
   const usage = reply.usage ?? DEFAULT_USAGE;
   let idx = 0;
 
-  const reasoningChunks = reply.reasoning ? reasoningBlock(idx++, reply.reasoning) : [];
-  const textChunks = shouldEmitText(reply) ? textBlock(idx++, reply.text ?? "", options.chunkSize ?? 0) : [];
+  const reasoningChunks = reply.reasoning
+    ? reasoningBlock(idx++, reply.reasoning)
+    : [];
+  const textChunks = shouldEmitText(reply)
+    ? textBlock(idx++, reply.text ?? "", options.chunkSize ?? 0)
+    : [];
   const toolChunks = toolBlocks(idx, reply.tools);
 
   return [
-    { event: "message_start", data: JSON.stringify({
-      type: "message_start",
-      message: { id, type: "message", role: "assistant", model, content: [], stop_reason: null, usage: { ...buildUsage(usage), output_tokens: 0 } },
-    })},
+    {
+      event: "message_start",
+      data: JSON.stringify({
+        type: "message_start",
+        message: {
+          id,
+          type: "message",
+          role: "assistant",
+          model,
+          content: [],
+          stop_reason: null,
+          usage: { ...buildUsage(usage), output_tokens: 0 },
+        },
+      }),
+    },
     ...reasoningChunks,
     ...textChunks,
     ...toolChunks,
-    { event: "message_delta", data: JSON.stringify({
-      type: "message_delta",
-      delta: { stop_reason: finishReason(reply, "tool_use", "end_turn"), stop_sequence: null },
-      usage: { output_tokens: usage.output },
-    })},
+    {
+      event: "message_delta",
+      data: JSON.stringify({
+        type: "message_delta",
+        delta: {
+          stop_reason: finishReason(reply, "tool_use", "end_turn"),
+          stop_sequence: null,
+        },
+        usage: { output_tokens: usage.output },
+      }),
+    },
     { event: "message_stop", data: JSON.stringify({ type: "message_stop" }) },
   ];
 }
 
-export function serializeComplete(reply: ReplyObject, model: string): Record<string, unknown> {
+export function serializeComplete(
+  reply: ReplyObject,
+  model: string,
+): Record<string, unknown> {
   const id = genId("msg");
   const usage = reply.usage ?? DEFAULT_USAGE;
 
   const content: unknown[] = [
-    ...(reply.reasoning ? [{ type: "thinking", thinking: reply.reasoning }] : []),
-    ...(shouldEmitText(reply) ? [{ type: "text", text: reply.text ?? "" }] : []),
-    ...(reply.tools ?? []).map((tool) => ({
-      type: "tool_use", id: toolId(tool, "toolu", 0), name: tool.name, input: tool.args,
+    ...(reply.reasoning
+      ? [{ type: "thinking", thinking: reply.reasoning }]
+      : []),
+    ...(shouldEmitText(reply)
+      ? [{ type: "text", text: reply.text ?? "" }]
+      : []),
+    ...(reply.tools ?? []).map((tool, i) => ({
+      type: "tool_use",
+      id: toolId(tool, "toolu", i),
+      name: tool.name,
+      input: tool.args,
     })),
   ];
 
   return {
-    id, type: "message", role: "assistant", model, content,
+    id,
+    type: "message",
+    role: "assistant",
+    model,
+    content,
     stop_reason: finishReason(reply, "tool_use", "end_turn"),
     stop_sequence: null,
     usage: buildUsage(usage),
   };
 }
 
-export function serializeError(error: { status: number; message: string; type?: string }): Record<string, unknown> {
-  return { type: "error", error: { type: error.type ?? "api_error", message: error.message } };
+export function serializeError(error: {
+  status: number;
+  message: string;
+  type?: string;
+}): Record<string, unknown> {
+  return {
+    type: "error",
+    error: { type: error.type ?? "api_error", message: error.message },
+  };
 }

package/src/formats/openai/parse.ts

@@ -2,7 +2,9 @@ import type { MockRequest, Message, ToolDef } from "../../types.js";
 import { buildMockRequest, type RequestMeta } from "../request-helpers.js";
 import { OpenAIRequestSchema, type OpenAIRequest } from "./schema.js";
 
-function extractContent(content: OpenAIRequest["messages"][number]["content"]): string {
+function extractContent(
+  content: OpenAIRequest["messages"][number]["content"],
+): string {
   if (content == null) return "";
   if (typeof content === "string") return content;
   return content
@@ -30,5 +32,13 @@ function parseTools(req: OpenAIRequest): readonly ToolDef[] | undefined {
 
 export function parseRequest(body: unknown, meta?: RequestMeta): MockRequest {
   const req = OpenAIRequestSchema.parse(body);
-  return buildMockRequest("openai", req, parseMessages(req), parseTools(req), "gpt-5.4", body, meta);
+  return buildMockRequest(
+    "openai",
+    req,
+    parseMessages(req),
+    parseTools(req),
+    "gpt-5.4",
+    body,
+    meta,
+  );
 }

package/src/formats/openai/schema.ts

@@ -1,6 +1,9 @@
 import { z } from "zod";
 
-export { OpenAIRequestSchema, type OpenAIRequest } from "llm-schemas/openai/chat-completions";
+export {
+  OpenAIRequestSchema,
+  type OpenAIRequest,
+} from "llm-schemas/openai/chat-completions";
 
 const ToolCallResponseSchema = z.object({
   id: z.string(),
@@ -12,16 +15,20 @@ const UsageSchema = z.object({
   prompt_tokens: z.number(),
   completion_tokens: z.number(),
   total_tokens: z.number(),
-  prompt_tokens_details: z.object({
-    cached_tokens: z.number().optional(),
-    audio_tokens: z.number().optional(),
-  }).optional(),
-  completion_tokens_details: z.object({
-    reasoning_tokens: z.number().optional(),
-    audio_tokens: z.number().optional(),
-    accepted_prediction_tokens: z.number().optional(),
-    rejected_prediction_tokens: z.number().optional(),
-  }).optional(),
+  prompt_tokens_details: z
+    .object({
+      cached_tokens: z.number().optional(),
+      audio_tokens: z.number().optional(),
+    })
+    .optional(),
+  completion_tokens_details: z
+    .object({
+      reasoning_tokens: z.number().optional(),
+      audio_tokens: z.number().optional(),
+      accepted_prediction_tokens: z.number().optional(),
+      rejected_prediction_tokens: z.number().optional(),
+    })
+    .optional(),
 });
 
 export const OpenAIChunkSchema = z.object({
@@ -31,16 +38,20 @@ export const OpenAIChunkSchema = z.object({
   model: z.string(),
   system_fingerprint: z.string().nullable().optional(),
   service_tier: z.string().optional(),
-  choices: z.array(z.object({
-    index: z.number(),
-    delta: z.object({
-      role: z.string(),
-      content: z.string(),
-      tool_calls: z.array(ToolCallResponseSchema),
-    }).partial(),
-    logprobs: z.unknown().nullable().optional(),
-    finish_reason: z.string().nullable(),
-  })),
+  choices: z.array(
+    z.object({
+      index: z.number(),
+      delta: z
+        .object({
+          role: z.string(),
+          content: z.string(),
+          tool_calls: z.array(ToolCallResponseSchema),
+        })
+        .partial(),
+      logprobs: z.unknown().nullable().optional(),
+      finish_reason: z.string().nullable(),
+    }),
+  ),
   usage: UsageSchema.nullable().optional(),
 });
 
@@ -53,16 +64,18 @@ export const OpenAICompleteSchema = z.object({
   model: z.string(),
   system_fingerprint: z.string().nullable().optional(),
   service_tier: z.string().optional(),
-  choices: z.array(z.object({
-    index: z.number(),
-    message: z.object({
-      role: z.string(),
-      content: z.string().nullable(),
-      tool_calls: z.array(ToolCallResponseSchema).optional(),
+  choices: z.array(
+    z.object({
+      index: z.number(),
+      message: z.object({
+        role: z.string(),
+        content: z.string().nullable(),
+        tool_calls: z.array(ToolCallResponseSchema).optional(),
+      }),
+      logprobs: z.unknown().nullable().optional(),
+      finish_reason: z.string(),
     }),
-    logprobs: z.unknown().nullable().optional(),
-    finish_reason: z.string(),
-  })),
+  ),
   usage: UsageSchema.optional(),
 });