llm-mock-server 1.0.4 → 1.0.6

package/.desloppify/subagents/runs/20260315_185613/run.log

@@ -0,0 +1,96 @@
+2026-03-15T18:56:13+00:00 run-start runner=codex parallel=True max_parallel=1 timeout=1200s heartbeat=15.0s stall_warning=0s stall_kill=120s retries=2 retry_backoff=2.0s upper_bound=200m selected=[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+2026-03-15T18:56:13+00:00 run-path /Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613
+2026-03-15T18:56:13+00:00 packet /Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/review_packets/holistic_packet_20260315_185613.json
+2026-03-15T18:56:13+00:00 blind-packet /Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/review_packet_blind.json
+2026-03-15T18:56:13+00:00 batch-queued batch=1 position=1/10
+2026-03-15T18:56:13+00:00 batch-start batch=1 position=1/10
+2026-03-15T18:56:13+00:00 batch-queued batch=2 position=2/10
+2026-03-15T18:56:13+00:00 batch-queued batch=3 position=3/10
+2026-03-15T18:56:13+00:00 batch-queued batch=4 position=4/10
+2026-03-15T18:56:13+00:00 batch-queued batch=5 position=5/10
+2026-03-15T18:56:13+00:00 batch-queued batch=6 position=6/10
+2026-03-15T18:56:13+00:00 batch-queued batch=7 position=7/10
+2026-03-15T18:56:13+00:00 batch-queued batch=8 position=8/10
+2026-03-15T18:56:13+00:00 batch-queued batch=9 position=9/10
+2026-03-15T18:56:13+00:00 batch-queued batch=10 position=10/10
+2026-03-15T18:56:28+00:00 heartbeat active=[1] queued=[2, 3, 4, 5, 6, 7, 8, 9, 10] elapsed={1:15}
+2026-03-15T18:56:43+00:00 heartbeat active=[1] queued=[2, 3, 4, 5, 6, 7, 8, 9, 10] elapsed={1:30}
+2026-03-15T18:56:58+00:00 heartbeat active=[1] queued=[2, 3, 4, 5, 6, 7, 8, 9, 10] elapsed={1:45}
+2026-03-15T18:57:02+00:00 batch-start batch=2 position=2/10
+2026-03-15T18:57:02+00:00 batch-done batch=1 position=1/10 code=0 elapsed=49
+2026-03-15T18:57:17+00:00 heartbeat active=[2] queued=[3, 4, 5, 6, 7, 8, 9, 10] elapsed={2:15}
+2026-03-15T18:57:32+00:00 heartbeat active=[2] queued=[3, 4, 5, 6, 7, 8, 9, 10] elapsed={2:30}
+2026-03-15T18:57:47+00:00 heartbeat active=[2] queued=[3, 4, 5, 6, 7, 8, 9, 10] elapsed={2:45}
+2026-03-15T18:58:02+00:00 heartbeat active=[2] queued=[3, 4, 5, 6, 7, 8, 9, 10] elapsed={2:60}
+2026-03-15T18:58:17+00:00 heartbeat active=[2] queued=[3, 4, 5, 6, 7, 8, 9, 10] elapsed={2:75}
+2026-03-15T18:58:32+00:00 heartbeat active=[2] queued=[3, 4, 5, 6, 7, 8, 9, 10] elapsed={2:90}
+2026-03-15T18:58:47+00:00 heartbeat active=[2] queued=[3, 4, 5, 6, 7, 8, 9, 10] elapsed={2:105}
+2026-03-15T18:59:02+00:00 heartbeat active=[2] queued=[3, 4, 5, 6, 7, 8, 9, 10] elapsed={2:120}
+2026-03-15T18:59:03+00:00 batch-done batch=2 position=2/10 code=0 elapsed=121
+2026-03-15T18:59:03+00:00 batch-start batch=3 position=3/10
+2026-03-15T18:59:18+00:00 heartbeat active=[3] queued=[4, 5, 6, 7, 8, 9, 10] elapsed={3:15}
+2026-03-15T18:59:33+00:00 heartbeat active=[3] queued=[4, 5, 6, 7, 8, 9, 10] elapsed={3:30}
+2026-03-15T18:59:48+00:00 heartbeat active=[3] queued=[4, 5, 6, 7, 8, 9, 10] elapsed={3:45}
+2026-03-15T19:00:03+00:00 heartbeat active=[3] queued=[4, 5, 6, 7, 8, 9, 10] elapsed={3:60}
+2026-03-15T19:00:18+00:00 heartbeat active=[3] queued=[4, 5, 6, 7, 8, 9, 10] elapsed={3:75}
+2026-03-15T19:00:33+00:00 heartbeat active=[3] queued=[4, 5, 6, 7, 8, 9, 10] elapsed={3:90}
+2026-03-15T19:00:48+00:00 heartbeat active=[3] queued=[4, 5, 6, 7, 8, 9, 10] elapsed={3:105}
+2026-03-15T19:00:54+00:00 batch-done batch=3 position=3/10 code=0 elapsed=110
+2026-03-15T19:00:54+00:00 batch-start batch=4 position=4/10
+2026-03-15T19:01:09+00:00 heartbeat active=[4] queued=[5, 6, 7, 8, 9, 10] elapsed={4:15}
+2026-03-15T19:01:24+00:00 heartbeat active=[4] queued=[5, 6, 7, 8, 9, 10] elapsed={4:30}
+2026-03-15T19:01:39+00:00 heartbeat active=[4] queued=[5, 6, 7, 8, 9, 10] elapsed={4:45}
+2026-03-15T19:01:48+00:00 batch-done batch=4 position=4/10 code=0 elapsed=54
+2026-03-15T19:01:48+00:00 batch-start batch=5 position=5/10
+2026-03-15T19:02:03+00:00 heartbeat active=[5] queued=[6, 7, 8, 9, 10] elapsed={5:15}
+2026-03-15T19:02:18+00:00 heartbeat active=[5] queued=[6, 7, 8, 9, 10] elapsed={5:30}
+2026-03-15T19:02:28+00:00 batch-start batch=6 position=6/10
+2026-03-15T19:02:28+00:00 batch-done batch=5 position=5/10 code=0 elapsed=40
+2026-03-15T19:02:43+00:00 heartbeat active=[6] queued=[7, 8, 9, 10] elapsed={6:15}
+2026-03-15T19:02:58+00:00 heartbeat active=[6] queued=[7, 8, 9, 10] elapsed={6:30}
+2026-03-15T19:03:13+00:00 heartbeat active=[6] queued=[7, 8, 9, 10] elapsed={6:45}
+2026-03-15T19:03:19+00:00 batch-start batch=7 position=7/10
+2026-03-15T19:03:19+00:00 batch-done batch=6 position=6/10 code=0 elapsed=50
+2026-03-15T19:03:34+00:00 heartbeat active=[7] queued=[8, 9, 10] elapsed={7:15}
+2026-03-15T19:03:49+00:00 heartbeat active=[7] queued=[8, 9, 10] elapsed={7:30}
+2026-03-15T19:04:04+00:00 heartbeat active=[7] queued=[8, 9, 10] elapsed={7:45}
+2026-03-15T19:04:19+00:00 heartbeat active=[7] queued=[8, 9, 10] elapsed={7:60}
+2026-03-15T19:04:34+00:00 heartbeat active=[7] queued=[8, 9, 10] elapsed={7:75}
+2026-03-15T19:04:49+00:00 heartbeat active=[7] queued=[8, 9, 10] elapsed={7:90}
+2026-03-15T19:05:02+00:00 batch-done batch=7 position=7/10 code=0 elapsed=103
+2026-03-15T19:05:02+00:00 batch-start batch=8 position=8/10
+2026-03-15T19:05:17+00:00 heartbeat active=[8] queued=[9, 10] elapsed={8:15}
+2026-03-15T19:05:32+00:00 heartbeat active=[8] queued=[9, 10] elapsed={8:30}
+2026-03-15T19:05:47+00:00 heartbeat active=[8] queued=[9, 10] elapsed={8:45}
+2026-03-15T19:06:02+00:00 heartbeat active=[8] queued=[9, 10] elapsed={8:60}
+2026-03-15T19:06:17+00:00 heartbeat active=[8] queued=[9, 10] elapsed={8:75}
+2026-03-15T19:06:32+00:00 heartbeat active=[8] queued=[9, 10] elapsed={8:90}
+2026-03-15T19:06:47+00:00 heartbeat active=[8] queued=[9, 10] elapsed={8:105}
+2026-03-15T19:06:51+00:00 batch-start batch=9 position=9/10
+2026-03-15T19:06:51+00:00 batch-done batch=8 position=8/10 code=0 elapsed=108
+2026-03-15T19:07:06+00:00 heartbeat active=[9] queued=[10] elapsed={9:15}
+2026-03-15T19:07:21+00:00 heartbeat active=[9] queued=[10] elapsed={9:30}
+2026-03-15T19:07:36+00:00 heartbeat active=[9] queued=[10] elapsed={9:45}
+2026-03-15T19:07:51+00:00 heartbeat active=[9] queued=[10] elapsed={9:60}
+2026-03-15T19:08:06+00:00 heartbeat active=[9] queued=[10] elapsed={9:75}
+2026-03-15T19:08:21+00:00 heartbeat active=[9] queued=[10] elapsed={9:90}
+2026-03-15T19:08:35+00:00 batch-done batch=9 position=9/10 code=0 elapsed=103
+2026-03-15T19:08:35+00:00 batch-start batch=10 position=10/10
+2026-03-15T19:08:50+00:00 heartbeat active=[10] queued=[] elapsed={10:15}
+2026-03-15T19:09:05+00:00 heartbeat active=[10] queued=[] elapsed={10:30}
+2026-03-15T19:09:20+00:00 heartbeat active=[10] queued=[] elapsed={10:45}
+2026-03-15T19:09:35+00:00 heartbeat active=[10] queued=[] elapsed={10:60}
+2026-03-15T19:09:50+00:00 heartbeat active=[10] queued=[] elapsed={10:75}
+2026-03-15T19:10:05+00:00 heartbeat active=[10] queued=[] elapsed={10:90}
+2026-03-15T19:10:20+00:00 heartbeat active=[10] queued=[] elapsed={10:105}
+2026-03-15T19:10:35+00:00 heartbeat active=[10] queued=[] elapsed={10:120}
+2026-03-15T19:10:50+00:00 heartbeat active=[10] queued=[] elapsed={10:135}
+2026-03-15T19:11:05+00:00 heartbeat active=[10] queued=[] elapsed={10:150}
+2026-03-15T19:11:20+00:00 heartbeat active=[10] queued=[] elapsed={10:165}
+2026-03-15T19:11:35+00:00 heartbeat active=[10] queued=[] elapsed={10:180}
+2026-03-15T19:11:50+00:00 heartbeat active=[10] queued=[] elapsed={10:195}
+2026-03-15T19:12:05+00:00 heartbeat active=[10] queued=[] elapsed={10:210}
+2026-03-15T19:12:20+00:00 heartbeat active=[10] queued=[] elapsed={10:225}
+2026-03-15T19:12:25+00:00 batch-done batch=10 position=10/10 code=0 elapsed=230
+2026-03-15T19:12:25+00:00 run-summary /Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/run_summary.json
+2026-03-15T19:12:25+00:00 run-finished successful=[1, 2, 3, 4, 5, 6, 7, 8, 9, 10] failed=[] imported=/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/holistic_findings_merged.json

package/.desloppify/subagents/runs/20260315_185613/run_summary.json

@@ -0,0 +1,156 @@
+{
+  "created_at": "2026-03-15T18:56:13+00:00",
+  "run_stamp": "20260315_185613",
+  "runner": "codex",
+  "parallel": true,
+  "selected_batches": [
+    1,
+    2,
+    3,
+    4,
+    5,
+    6,
+    7,
+    8,
+    9,
+    10
+  ],
+  "successful_batches": [
+    1,
+    2,
+    3,
+    4,
+    5,
+    6,
+    7,
+    8,
+    9,
+    10
+  ],
+  "failed_batches": [],
+  "allow_partial": false,
+  "max_parallel_batches": 1,
+  "batch_timeout_seconds": 1200,
+  "batch_max_retries": 2,
+  "batch_retry_backoff_seconds": 2.0,
+  "batch_heartbeat_seconds": 15.0,
+  "batch_stall_warning_seconds": 0,
+  "batch_stall_kill_seconds": 120,
+  "immutable_packet": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/review_packets/holistic_packet_20260315_185613.json",
+  "blind_packet": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/review_packet_blind.json",
+  "run_dir": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613",
+  "logs_dir": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/logs",
+  "run_log": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/run.log",
+  "batches": {
+    "1": {
+      "position": 1,
+      "status": "succeeded",
+      "prompt_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/prompts/batch-1.md",
+      "result_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/results/batch-1.raw.txt",
+      "log_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/logs/batch-1.log",
+      "started_at": "2026-03-15T18:56:13+00:00",
+      "elapsed_seconds": 49,
+      "exit_code": 0,
+      "completed_at": "2026-03-15T18:57:02+00:00"
+    },
+    "2": {
+      "position": 2,
+      "status": "succeeded",
+      "prompt_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/prompts/batch-2.md",
+      "result_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/results/batch-2.raw.txt",
+      "log_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/logs/batch-2.log",
+      "started_at": "2026-03-15T18:57:02+00:00",
+      "elapsed_seconds": 121,
+      "exit_code": 0,
+      "completed_at": "2026-03-15T18:59:03+00:00"
+    },
+    "3": {
+      "position": 3,
+      "status": "succeeded",
+      "prompt_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/prompts/batch-3.md",
+      "result_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/results/batch-3.raw.txt",
+      "log_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/logs/batch-3.log",
+      "started_at": "2026-03-15T18:59:03+00:00",
+      "elapsed_seconds": 110,
+      "exit_code": 0,
+      "completed_at": "2026-03-15T19:00:54+00:00"
+    },
+    "4": {
+      "position": 4,
+      "status": "succeeded",
+      "prompt_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/prompts/batch-4.md",
+      "result_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/results/batch-4.raw.txt",
+      "log_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/logs/batch-4.log",
+      "started_at": "2026-03-15T19:00:54+00:00",
+      "elapsed_seconds": 54,
+      "exit_code": 0,
+      "completed_at": "2026-03-15T19:01:48+00:00"
+    },
+    "5": {
+      "position": 5,
+      "status": "succeeded",
+      "prompt_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/prompts/batch-5.md",
+      "result_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/results/batch-5.raw.txt",
+      "log_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/logs/batch-5.log",
+      "started_at": "2026-03-15T19:01:48+00:00",
+      "elapsed_seconds": 40,
+      "exit_code": 0,
+      "completed_at": "2026-03-15T19:02:28+00:00"
+    },
+    "6": {
+      "position": 6,
+      "status": "succeeded",
+      "prompt_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/prompts/batch-6.md",
+      "result_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/results/batch-6.raw.txt",
+      "log_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/logs/batch-6.log",
+      "started_at": "2026-03-15T19:02:28+00:00",
+      "elapsed_seconds": 50,
+      "exit_code": 0,
+      "completed_at": "2026-03-15T19:03:19+00:00"
+    },
+    "7": {
+      "position": 7,
+      "status": "succeeded",
+      "prompt_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/prompts/batch-7.md",
+      "result_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/results/batch-7.raw.txt",
+      "log_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/logs/batch-7.log",
+      "started_at": "2026-03-15T19:03:19+00:00",
+      "elapsed_seconds": 103,
+      "exit_code": 0,
+      "completed_at": "2026-03-15T19:05:02+00:00"
+    },
+    "8": {
+      "position": 8,
+      "status": "succeeded",
+      "prompt_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/prompts/batch-8.md",
+      "result_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/results/batch-8.raw.txt",
+      "log_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/logs/batch-8.log",
+      "started_at": "2026-03-15T19:05:02+00:00",
+      "elapsed_seconds": 108,
+      "exit_code": 0,
+      "completed_at": "2026-03-15T19:06:51+00:00"
+    },
+    "9": {
+      "position": 9,
+      "status": "succeeded",
+      "prompt_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/prompts/batch-9.md",
+      "result_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/results/batch-9.raw.txt",
+      "log_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/logs/batch-9.log",
+      "started_at": "2026-03-15T19:06:51+00:00",
+      "elapsed_seconds": 103,
+      "exit_code": 0,
+      "completed_at": "2026-03-15T19:08:35+00:00"
+    },
+    "10": {
+      "position": 10,
+      "status": "succeeded",
+      "prompt_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/prompts/batch-10.md",
+      "result_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/results/batch-10.raw.txt",
+      "log_path": "/Users/suyash.x.srijan/Documents/Personal_Projects/llm-mock-server/.desloppify/subagents/runs/20260315_185613/logs/batch-10.log",
+      "started_at": "2026-03-15T19:08:35+00:00",
+      "elapsed_seconds": 230,
+      "exit_code": 0,
+      "completed_at": "2026-03-15T19:12:25+00:00"
+    }
+  }
+}

package/.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Deploy API docs
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6.0.2
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6.3.0
+        with:
+          node-version-file: 'package.json'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate docs
+        run: npm run docs
+
+      - name: Upload pages artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: docs/api
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/.github/workflows/test.yml

@@ -33,5 +33,8 @@ jobs:
       - name: Lint
         run: npm run lint
 
+      - name: Validate docs
+        run: npm run docs:check
+
       - name: Run tests
         run: npm test

package/README.md

@@ -1,6 +1,6 @@
-# llm-mock-server
+# llm-mock-server [![npm version](https://img.shields.io/npm/v/llm-mock-server)](https://www.npmjs.com/package/llm-mock-server) ![npm downloads](https://img.shields.io/npm/d18m/llm-mock-server)
 
-A mock LLM server for testing. It handles OpenAI `/chat/completions`, Anthropic `/messages`, and OpenAI `/responses` API formats, with both streaming (SSE) and non-streaming responses. Point any client at it and get instant, deterministic replies.
+A mock LLM server for testing. It handles OpenAI `/chat/completions`, Anthropic `/messages`, and OpenAI `/responses` API formats, with both streaming (SSE) and non-streaming responses. Point any client at it and get instant, deterministic replies. Used by [xcode-copilot-server](https://github.com/theblixguy/xcode-copilot-server) and [copilot-sdk-proxy](https://github.com/theblixguy/copilot-sdk-proxy) for their integration tests.
 
 ## Table of contents
 
@@ -25,6 +25,7 @@ A mock LLM server for testing. It handles OpenAI `/chat/completions`, Anthropic
 - [CLI](#cli)
 - [Security](#security)
 - [Architecture](#architecture)
+- [API reference](#api-reference)
 - [Licence](#licence)
 
 ## Quick start
@@ -390,7 +391,6 @@ llm-mock-server [options]
 | `--port` | `-p` | `5555` | Port to listen on |
 | `--host` | `-H` | `127.0.0.1` | Host to bind to |
 | `--rules` | `-r` | | Path to rules file or directory |
-| `--handler` | | | Path to handler file |
 | `--latency` | `-l` | `0` | Ms between SSE chunks |
 | `--chunk-size` | `-c` | `0` | Characters per SSE chunk |
 | `--fallback` | `-f` | | Fallback reply text |
@@ -410,7 +410,7 @@ This is a testing tool, not a production service. It's designed to run locally o
 
 ### Handler files execute code
 
-When you call `server.load()` or pass `--handler` on the CLI, `.ts`/`.js` files are loaded via dynamic `import()`. They run with the same permissions as the rest of your Node.js process. Only load files you trust.
+When you call `server.load()` or pass `--rules` on the CLI, `.ts`/`.js` files are loaded via dynamic `import()`. They run with the same permissions as the rest of your Node.js process. Only load files you trust.
 
 ### JSON5 rule files are data only
 
@@ -428,6 +428,10 @@ Request bodies are capped at 1 MB by Fastify's default. Responses are serialised
 
 See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for how the codebase is structured, the request lifecycle, rule matching, and response serialisation.
 
+## API reference
+
+Full API docs are available [here](https://theblixguy.github.io/llm-mock-server/).
+
 ## Licence
 
 MIT License

package/docs/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # llm-mock-server architecture
 
-A mock LLM server built on Fastify. Clients send requests in OpenAI, Anthropic, or Responses API format. The server normalises them into a common shape, matches against registered rules, and sends back responses in the right format.
+A mock LLM server built on Fastify. Clients send requests in OpenAI Chat Completions, Anthropic Messages, or OpenAI Responses API format. The server normalises them into a common shape, matches against registered rules, and sends back responses in the right format.
 
 ```mermaid
 flowchart LR
@@ -8,7 +8,7 @@ flowchart LR
     Server["llm-mock-server<br/>(Fastify)"]
     Rules["Rule engine"]
 
-    Client <-->|"OpenAI / Anthropic / Responses"| Server
+    Client <-->|"Chat Completions / Messages / Responses"| Server
     Server <--> Rules
 ```
 
@@ -26,9 +26,9 @@ flowchart LR
 
 ## Startup
 
-[`cli.ts`](src/cli.ts) is the CLI entry point. It parses flags with Commander, validates them through [`cli-validators.ts`](src/cli-validators.ts), creates a `MockServer`, loads any rule files, and handles SIGINT/SIGTERM. With `--watch`, it sets up `fs.watch()` on the rules path and reloads on changes.
+[`cli.ts`](src/cli/cli.ts) is the CLI entry point. It parses flags with Commander, validates them through [`validators.ts`](src/cli/validators.ts), creates a `MockServer`, loads any rule files, and handles SIGINT/SIGTERM. With `--watch`, it sets up `fs.watch()` on the rules path and reloads on changes.
 
-[`MockServer`](src/mock-server.ts) is the main class. The constructor creates a Fastify instance and registers a route handler for each format. Consumers interact with it through `when()`, `fallback()`, `load()`, and the lifecycle methods.
+[`MockServer`](src/mock-server.ts) is the main class. The constructor creates a Fastify instance and registers a route handler for each format. Rule authoring (`when()`, `whenTool()`, `whenToolResult()`, `nextError()`) lives in [`RuleBuilder`](src/rule-builder.ts) and is proxied onto `MockServer` via `.bind()`. Consumers interact with it through the rule methods, `fallback()`, `load()`, and the lifecycle methods.
 
 [`createMock()`](src/index.ts) is a convenience that creates a server and starts it in one call.
 
@@ -40,9 +40,9 @@ Three formats are included:
 
 | Format | Route | Directory |
 | ------ | ----- | --------- |
-| OpenAI | `POST /v1/chat/completions` | [`formats/openai/`](src/formats/openai/) |
-| Anthropic | `POST /v1/messages` | [`formats/anthropic/`](src/formats/anthropic/) |
-| OpenAI Responses | `POST /v1/responses` | [`formats/responses/`](src/formats/responses/) |
+| OpenAI Chat Completions | `POST /v1/chat/completions` | [`formats/openai/chat-completions/`](src/formats/openai/chat-completions/) |
+| Anthropic Messages | `POST /v1/messages` | [`formats/anthropic/`](src/formats/anthropic/) |
+| OpenAI Responses | `POST /v1/responses` | [`formats/openai/responses/`](src/formats/openai/responses/) |
 
 Each format directory has three files:
 
@@ -50,7 +50,7 @@ Each format directory has three files:
 - `serialize.ts` takes a [`ReplyObject`](src/types/reply.ts) and produces SSE chunks or a JSON response
 - `index.ts` wires parse and serialize together into a `Format` object
 
-Shared helpers live in [`parse-helpers.ts`](src/formats/parse-helpers.ts). Functions like `buildMockRequest()`, `genId()`, `splitText()`, `shouldEmitText()`, and `finishReason()` are used by all three formats. `isStreaming()` is also shared because every format checks `body.stream !== false` the same way.
+Shared helpers are split into request and response files: [`request-helpers.ts`](src/formats/request-helpers.ts) has `buildMockRequest()` and `isStreaming()` (used by parsers), and [`serialize-helpers.ts`](src/formats/serialize-helpers.ts) has `genId()`, `splitText()`, `shouldEmitText()`, and `finishReason()` (used by serialisers).
 
 To add a new format (say, Gemini), you would create a new directory with those three files and add it to the `formats` array in `mock-server.ts`. Everything else (rule matching, streaming, logging, history) works automatically.
 
@@ -91,7 +91,7 @@ Types are split across three files in [`src/types/`](src/types/):
 - [`reply.ts`](src/types/reply.ts) has `Reply`, `ReplyObject`, `ErrorReply`, `ToolCall`, `Resolver`, and `ReplyOptions`
 - [`rule.ts`](src/types/rule.ts) has `Match`, `MatchObject`, `PendingRule`, `RuleHandle`, `RuleSummary`, `Handler`, and `Rule`
 
-[`src/types.ts`](src/types.ts) re-exports everything from the barrel so internal files can import from a single place.
+[`src/types.ts`](src/types.ts) re-exports everything as a barrel for the public API. Internal modules import directly from the leaf files.
 
 ## Streaming
 
@@ -116,10 +116,10 @@ Directories are read and processed in sorted order.
 
 The threat model is simple: the server runs locally or in CI, loading files written by the developer. There is no multi-tenant isolation or sandboxing.
 
-Handler files (`.ts`, `.js`, `.mjs`) are loaded via `import()` and execute with full process permissions. The trust boundary is the file system path passed to `load()` or `--handler`. If an attacker can write to that path, they already have code execution on the machine. No path restriction is enforced because legitimate setups often load rules from outside the project directory.
+Handler files (`.ts`, `.js`, `.mjs`) are loaded via `import()` and execute with full process permissions. The trust boundary is the file system path passed to `load()` or `--rules`. If an attacker can write to that path, they already have code execution on the machine. No path restriction is enforced because legitimate setups often load rules from outside the project directory.
 
 JSON5 files go through Zod validation and never execute code. The only dynamic construction is `new RegExp()` for regex patterns in rule files, which could hang on pathological backtracking patterns but poses no injection risk.
 
 Fastify caps request bodies at 1 MB by default. The server binds to `127.0.0.1` unless explicitly configured otherwise. Responses are serialised through JSON, so reply text cannot break out of SSE framing.
 
-CLI inputs (port, host, latency, log level) are validated through [`cli-validators.ts`](src/cli-validators.ts) before use.
+CLI inputs (port, host, latency, log level) are validated through [`validators.ts`](src/cli/validators.ts) before use.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-mock-server",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "A standalone mock LLM server for deterministic testing: OpenAI, Anthropic, and Responses API formats",
   "type": "module",
   "engines": {
@@ -15,8 +15,11 @@
     },
     "./package.json": "./package.json"
   },
+  "imports": {
+    "#/*": "./src/*"
+  },
   "bin": {
-    "llm-mock-server": "./dist/cli.js"
+    "llm-mock-server": "./dist/cli/cli.js"
   },
   "scripts": {
     "build": "tsc",
@@ -26,8 +29,10 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "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"
+    "docs": "typedoc",
+    "docs:check": "typedoc --emit none",
+    "dev": "tsx src/cli/cli.ts",
+    "start": "node dist/cli/cli.js"
   },
   "keywords": [
     "llm",
@@ -41,19 +46,21 @@
   "license": "MIT",
   "dependencies": {
     "commander": "14.0.3",
-    "fastify": "5.8.2",
+    "fastify": "5.8.4",
     "json5": "2.2.3",
-    "llm-schemas": "1.0.1",
+    "llm-schemas": "1.0.2",
     "picocolors": "1.1.1",
     "zod": "4.3.6"
   },
   "devDependencies": {
     "@types/node": "25.5.0",
-    "@vitest/coverage-v8": "4.1.0",
-    "oxfmt": "0.40.0",
-    "oxlint": "1.55.0",
+    "@vitest/coverage-v8": "4.1.2",
+    "oxfmt": "0.42.0",
+    "oxlint": "1.57.0",
     "tsx": "4.21.0",
-    "typescript": "5.9.3",
-    "vitest": "4.1.0"
+    "typedoc": "0.28.18",
+    "typedoc-theme-oxide": "0.2.5",
+    "typescript": "6.0.2",
+    "vitest": "4.1.2"
   }
 }

package/src/{cli.ts → cli/cli.ts}

@@ -4,18 +4,18 @@ import { watch } from "node:fs";
 import { createRequire } from "node:module";
 import { Command } from "commander";
 import pc from "picocolors";
-import { MockServer } from "./mock-server.js";
-import { Logger } from "./logger.js";
+import { MockServer } from "#/mock-server.js";
+import { Logger } from "#/logger.js";
 import {
   parsePort,
   parseHost,
   parseLogLevel,
   parseChunkSize,
   parseLatency,
-} from "./cli-validators.js";
+} from "./validators.js";
 
 const require = createRequire(import.meta.url);
-const { version } = require("../package.json") as { version: string };
+const { version } = require("../../package.json") as { version: string };
 
 const WATCH_DEBOUNCE_MS = 100;
 
@@ -23,7 +23,6 @@ interface StartOptions {
   port: string;
   host: string;
   rules?: string;
-  handler?: string;
   latency: string;
   chunkSize: string;
   fallback?: string;
@@ -54,9 +53,6 @@ async function start(options: StartOptions): Promise<void> {
   if (options.rules) {
     await server.load(options.rules);
   }
-  if (options.handler) {
-    await server.load(options.handler);
-  }
 
   const quiet = logLevel === "none";
 
@@ -78,7 +74,7 @@ async function start(options: StartOptions): Promise<void> {
       );
     }
     console.log(
-      `  ${pc.dim("Endpoints")}  ${pc.green("/v1/chat/completions")}, ${pc.green("/v1/messages")}, ${pc.green("/v1/responses")}`,
+      `  ${pc.dim("Endpoints")}  ${server.routes.map((r) => pc.green(r)).join(", ")}`,
     );
     console.log();
   }
@@ -131,8 +127,7 @@ program
   .description("Start the mock server")
   .option("-p, --port <number>", "port to listen on", "5555")
   .option("-H, --host <address>", "host to bind to", "127.0.0.1")
-  .option("-r, --rules <path>", "path to .json5 rules file or directory")
-  .option("--handler <path>", "path to .ts handler file")
+  .option("-r, --rules <path>", "path to rules file or directory")
   .option("-l, --latency <ms>", "latency between SSE chunks (ms)", "0")
   .option("-c, --chunk-size <chars>", "characters per SSE chunk", "0")
   .option("-f, --fallback <text>", "fallback reply text")

package/src/{cli-validators.ts → cli/validators.ts}

@@ -1,17 +1,18 @@
 import { isIP } from "node:net";
 import { lookup } from "node:dns/promises";
-import { LEVEL_PRIORITY, type LogLevel } from "./logger.js";
+import { LEVEL_PRIORITY, type LogLevel } from "#/logger.js";
 
-const VALID_LOG_LEVELS = Object.keys(LEVEL_PRIORITY) as LogLevel[];
+const VALID_LOG_LEVELS: string[] = Object.keys(LEVEL_PRIORITY);
 
-function isLogLevel(value: string): value is LogLevel {
-  return value in LEVEL_PRIORITY;
+function parseStrictInt(value: string): number {
+  if (!/^\d+$/.test(value)) return NaN;
+  return Number(value);
 }
 
 const MAX_PORT = 65535;
 
 export function parsePort(value: string): number {
-  const port = parseInt(value, 10);
+  const port = parseStrictInt(value);
   if (isNaN(port) || port < 1 || port > MAX_PORT) {
     throw new Error(`Invalid port "${value}". Must be 1-${String(MAX_PORT)}.`);
   }
@@ -19,12 +20,12 @@ export function parsePort(value: string): number {
 }
 
 export function parseLogLevel(value: string): LogLevel {
-  if (!isLogLevel(value)) {
+  if (!VALID_LOG_LEVELS.includes(value)) {
     throw new Error(
       `Invalid log level "${value}". Valid: ${VALID_LOG_LEVELS.join(", ")}`,
     );
   }
-  return value;
+  return value as LogLevel;
 }
 
 export async function parseHost(value: string): Promise<string> {
@@ -47,7 +48,7 @@ export async function parseHost(value: string): Promise<string> {
 }
 
 export function parseChunkSize(value: string): number {
-  const size = parseInt(value, 10);
+  const size = parseStrictInt(value);
   if (isNaN(size) || size < 0) {
     throw new Error(
       `Invalid chunk size "${value}". Must be a non-negative integer.`,
@@ -57,7 +58,7 @@ export function parseChunkSize(value: string): number {
 }
 
 export function parseLatency(value: string): number {
-  const ms = parseInt(value, 10);
+  const ms = parseStrictInt(value);
   if (isNaN(ms) || ms < 0) {
     throw new Error(
       `Invalid latency "${value}". Must be a non-negative integer (ms).`,

package/src/formats/anthropic/index.ts

@@ -1,5 +1,5 @@
-import type { Format } from "../types.js";
-import { isStreaming } from "../request-helpers.js";
+import type { Format } from "#/formats/types.js";
+import { isStreaming } from "#/formats/request-helpers.js";
 import { parseRequest } from "./parse.js";
 import { serialize, serializeComplete, serializeError } from "./serialize.js";
 

package/src/formats/anthropic/parse.ts

@@ -1,5 +1,8 @@
-import type { MockRequest, Message, ToolDef } from "../../types.js";
-import { buildMockRequest, type RequestMeta } from "../request-helpers.js";
+import type { MockRequest, Message, ToolDef } from "#/types/request.js";
+import {
+  buildMockRequest,
+  type RequestMeta,
+} from "#/formats/request-helpers.js";
 import { AnthropicRequestSchema, type AnthropicRequest } from "./schema.js";
 
 function extractSystem(system: AnthropicRequest["system"]): Message[] {