docs/wiki/03-developer-guide-and-testing.md

Wiki: 03. Developer Guide & Testing

This guide outlines how to configure, run, test, and verify the Ever-Brain codebase.

---

1. Prerequisites & Required Downloads

Before developing or running Ever-Brain locally, ensure the following tools are installed:

Software	Required Version	Official Download / Install	Version Check
Node.js	>= 20.0.0 (LTS recommended)	nodejs.org	node -v
pnpm	>= 9.0.0	npm install -g pnpm (or corepack enable && corepack prepare pnpm@latest --activate)	pnpm -v
Git	>= 2.30.0	git-scm.com	git --version
GitHub Token (Optional)	Classic / Fine-grained PAT	GitHub Tokens (increases API limit from 60 to 5,000 req/hr)	—

---

2. Monorepo Structure

ever-brain/
├── packages/
│   ├── api/                     # Ever-Brain API Source Layer (@ever-brain/api)
│   │   ├── src/                 # Hono app, Git tree resolver, cache, routes
│   │   ├── test/                # API integration & unit tests
│   │   └── package.json
│   ├── mcp/                     # Ever-Brain MCP Adapter (@ever-brain/mcp)
│   │   ├── src/                 # Streamable HTTP (2025-03-26) & SSE (2024-11-05)
│   │   ├── test/                # MCP protocol integration tests
│   │   └── package.json
│   └── cli/                     # Ever-Brain CLI Control Plane (@ever-brain/cli)
│       ├── src/                 # Meta-skill bootstrap, cache, diff, push/propose
│       ├── test/                # CLI command & cache tests
│       └── package.json
├── docs/
│   └── wiki/                    # Complete 6-Part Project Wiki Documentation
├── .env.example                 # Sample environment configuration template
├── package.json                 # Monorepo root manifest
└── pnpm-workspace.yaml          # pnpm workspace definition

---

3. Setup & Workspace Commands

# 1. Install dependencies across all packages
pnpm install

# 2. Configure environment variables
cp .env.example .env             # Windows: copy .env.example .env

# 3. Build all TypeScript packages
pnpm build

# 4. Start local services (API + MCP Concurrently)
pnpm dev                         # Hosts API on :3000 and MCP on :3002

# Or start services individually:
# pnpm dev:api                   # Start API only
# pnpm dev:mcp                   # Start MCP server only

# 5. Run CLI directly in workspace
pnpm evb --help

# 6. Link CLI globally across your machine (optional)
pnpm cli:link                    # Makes 'evb' available in all terminals

# 7. Run test suite across all 3 packages
pnpm test

# 8. Typecheck all packages
pnpm typecheck

---

4. Automated Test Suites

Automated testing is configured using Vitest across all packages:

Package	Test Suite Files	What is Tested
@ever-brain/api	mime-and-filter.test.ts tree-cache.test.ts resolver-service.test.ts api-routes.test.ts	Resolves extensions, exclusions, in-memory TTL caching, Git tree ingestion, and HTTP endpoints (/health, /repos, /files, /file/*, /search).
@ever-brain/mcp	mcp-server-factory.test.ts repo-context.test.ts mcp-routes.test.ts mcp-integration-e2e.test.ts	Streamable HTTP & SSE transport endpoints, MCP resources (ever-brain://repo/...), and tools (list_files, read_file, search_files).
@ever-brain/cli	project-config.test.ts cache-and-dirty-state.test.ts meta-skill-service.test.ts materialize-service.test.ts auth-service.test.ts github-writer-service.test.ts cli-commands.test.ts	Pure filesystem cache (.evb/), config validation, dirty diff tracking, meta-skill generation for Antigravity/Cursor/Claude, and push/propose commands.

---

5. Live Verification Records

The API has been verified with live HTTP requests against public GitHub repositories:

Live Test 1: abrez-rizvi/trial-markdown

• Target: https://github.com/abrez-rizvi/trial-markdown (branch: main)
• Discovery Response:

  {
    "repository": "abrez-rizvi/trial-markdown",
    "branch": "main",
    "totalFiles": 1,
    "files": [{ "path": "text.md", "type": "file", "sizeBytes": 92, "mimeType": "text/markdown" }]
  }
  

• Raw Content Stream (GET /repos/abrez-rizvi/trial-markdown/file/text.md):
  • HTTP Status: 200 OK
  • Content-Type: text/markdown; charset=utf-8
  • X-Ever-Brain-Path: text.md
  • Body: "sup, say hell yeah gng we in if you could retrieve this information alongisde a few 🤤🤤"
• Case-Insensitive Normalization (GET /repos/abrez-rizvi/trial-markdown/file/TEXT.MD):
  • HTTP Status: 200 OK
  • X-Ever-Brain-Path: text.md
  • Exact raw content returned successfully.

Live Test 2: octocat/Hello-World

• Target: https://github.com/octocat/Hello-World (default branch auto-detected: master)
• Discovery: Discovered README (13 bytes, text/plain).
• Content Stream: Retrieved "Hello World!\n" with 200 OK.
• Search (GET /search?q=Hello): Returned 1 match with line number location.