Node Mock Server Development
This skill provides development guidelines and context for working on the node-mock-server project, a TypeScript-based mock API server with filesystem-backed endpoints and scenarios.
What This Skill Does
Guides AI agents working on the node-mock-server codebase by providing:
Active technology stack and version constraintsProject structure and organizationCode style conventionsTesting and linting commandsRecent architectural changes and contextInstructions
When working on the node-mock-server project, follow these guidelines:
1. Technology Stack
**Core Runtime:**
TypeScript 5.3+Node.js 16+ (required, per package.json engines)Express 4.x (backend API server)**Frontend:**
React 18.x (UI components)Tailwind CSS 3.4 (styling)**Key Dependencies:**
fs-extra 11.x (file system operations)Zod 3.x (schema validation)Commander 13.x (CLI interface)YAML 2.x (Swagger/OpenAPI parsing)**Storage Architecture:**
File system based (no database)Mock endpoints: folder structure mirroring API pathsScenarios: JSON files in `mock/scenario/` directoryActive scenario: tracked in `mock/scenario/_active.json`Statistics: calculated in-memory from endpoint data2. Project Structure
```
src/ # TypeScript source code
tests/ # Test files
mock/ # Mock data storage
scenario/ # Scenario JSON files
_active.json
```
3. Development Workflow
**Before committing, always run:**
```bash
npm test && npm run lint
```
**Code Style:**
Follow TypeScript best practicesUse strict type checkingLeverage Zod for runtime validationPrefer functional patterns where appropriateUse async/await for file operations via fs-extra4. Key Architectural Patterns
**Endpoint Management:**
Endpoints mirror API path structure in filesystemEach endpoint can have multiple responsesResponses support HTTP methods independently (GET, POST, PUT, DELETE, etc.)**Scenario System:**
Scenarios are collections of endpoint configurationsOne active scenario at a timeSwitch scenarios via API or CLIScenarios stored as JSON for version control**Statistics:**
No persistence layerCalculate on-demand from endpoint access logsReset on server restart5. Recent Changes Context
**004-scenario-management:**
Added comprehensive scenario management systemIntroduced Tailwind CSS for stylingEnhanced UI with React 18.x components**003-add-endpoint:**
Implemented dynamic endpoint creationAdded Zod validation layerBuilt endpoint management API**002-independent-methods:**
Separated HTTP method handlingImproved statistics calculationEnhanced React frontend components**001-backend-constitution-refactor:**
Refactored core backend architectureAdded CLI support via CommanderIntegrated Swagger/OpenAPI parsing6. Important Constraints
Maintain Node.js 16+ compatibility (minimum engine version)All file operations must use fs-extra for cross-platform supportValidate all inputs with Zod schemasKeep scenarios portable (JSON format only)No external database dependenciesStatistics must be derivable from filesystem stateExamples
**Adding a new endpoint:**
1. Create folder structure matching API path
2. Define response files with HTTP method prefixes
3. Validate schema with Zod
4. Update scenario configurations if needed
**Creating a scenario:**
1. Define scenario in `mock/scenario/<name>.json`
2. Include endpoint configurations
3. Document expected behavior
4. Test activation via API or CLI
**Implementing a feature:**
1. Check technology constraints (Node 16+, TypeScript 5.3+)
2. Write TypeScript with strict types
3. Add Zod validation for external inputs
4. Run `npm test && npm run lint` before committing
5. Update relevant scenario files if feature affects mock behavior
Notes
This is a development tool, not a production API serverFocus on developer experience and ease of configurationFilesystem storage enables version control of mock definitionsScenarios should be shareable across teams