Kaysser Kayyali
e2c92e854f
Some checks failed
tests / Unit tests (Node 22) (push) Failing after 2m13s
Expands the unit test suite from 320 to 380 tests (+60) and adds a
Gitea Actions CI workflow. Closes all six follow-up recommendations
from the test-architecture validation report.
New tests (tests/unit/):
- ollamaClient.test.ts — Ollama SDK wrapper, options passthrough
- litellmClient.test.ts — OpenAI SDK wrapper, model fallback
- personaLoader.test.ts — Zod validation + cache invalidation
- foundryReward.test.ts — Tool plugin: lookup, errors, partial grants
- xpAwarder.test.ts — Bulk XP awards + per-player skip reasons
- redisErrorPath.test.ts — Singleton error handler does not crash
- messageRouterRunLLMTurn.test.ts — 18 cases for the runtime heart:
narrative-only path, tool dispatch, filter correction, retry loop
guard, missed-skill-check heuristic, typing indicator interval,
LLM error fallback, archive on resolve.
Coverage (line %):
- harness/litellmClient.ts 0 → 100
- harness/ollamaClient.ts 0 → 100
- harness/tools/foundryReward.ts 0 → 100
- session/xpAwarder.ts 0 → 100
- persona/loader.ts 0 → 100
- db/redis.ts 0 → 100
- bot/handlers/messageRouter.ts 0 → 39.86 (runLLMTurn now covered)
Tooling:
- package.json: + test:coverage, test:watch scripts
- devDep: @vitest/coverage-v8@^3.1.0
- tests/README.md: conventions, anti-patterns, template map
- .gitignore: exclude coverage/
- .gitea/workflows/test.yml: Node 22, npm cache, tsc --noEmit gate
Documentation (from earlier /bmad-document-project run, now committed):
- docs/index.md
- docs/project-overview.md
- docs/architecture.md
- docs/deployment-guide.md
- docs/api-contracts.md
- docs/data-models.md
- docs/source-tree-analysis.md
- docs/component-inventory.md
- docs/development-guide.md
- _bmad-output/test-artifacts/automate-validation-report.md
Co-Authored-By: Claude <noreply@anthropic.com>
2.9 KiB
2.9 KiB
Mardonar Encounter Engine — Documentation Index
Primary entry point for AI-assisted development. Generated 2026-06-19 from a deep scan.
Project Overview
- Type: Monolith — single-part backend
- Primary Language: TypeScript (Node.js 22, ESM)
- Architecture: Layered backend with plugin-style LLM tool registry
- Project name (config): big-red
- Repository name: mardonar-npcs
Quick Reference
- Tech stack: Node.js 22 · TypeScript 5.8 · discord.js v14 · LiteLLM (primary) + Ollama (fallback) · ioredis · GraphMCP JSON-RPC (Neo4j-backed) · Zod · pino · Vitest · Docker
- Entry point:
src/bot/index.ts(compiled todist/bot/index.js) - Architecture pattern: Layered (bot → harness → session/db/graphmcp/vtt) with per-encounter tool plugin filtering
Generated Documentation
- Project Overview
- Architecture
- Source Tree Analysis
- Component Inventory
- Development Guide
- Deployment Guide
- API Contracts
- Data Models
Existing Documentation
These pre-existed in Docs/ and were cross-referenced during generation. Note that some are partially out of date.
- Docs/mardonar-encounter-engine.md — Original system design doc. Out of date — describes a Go bot with embedded MCP; the actual implementation is TypeScript with an external GraphMCP. Use
docs/architecture.mdas the source of truth. - Docs/mardonar-build-plan.md — Phased build plan with packages and test guidance
- Docs/epics.md — Epic list
- Docs/stories/ — Story specs (1.1, 1.2, 2.1, 3.1, 4.1)
- Docs/ux-designs/ux-mardonar-2026-05-30/ — UX session artifacts (EXPERIENCE.md, DESIGN.md, decision-log.md)
- README.md — Player-facing intro, quick start, command list. Project-structure tree is out of date.
- prd.md — Active PRD: Dynamic Goal Registration
Getting Started
- Skim Project Overview (1 minute)
- Read Architecture sections 1–6 for the system design (10 minutes)
- Read Development Guide "First-time setup" to get the bot running locally
- For new feature work, start from Component Inventory to find the right module, then read the linked source
Conventions
- All player-facing bot strings use in-world voice — no utility terms like "session", "user", "ephemeral" (see
feedback-in-world-voicememory). - All env access goes through
import { config }fromsrc/config.ts. - Tool plugins self-register via
registerTool()at module load. - Shared types live only in
src/types/index.ts. - Discord embeds are pure builders — no I/O.