Copilot instructions

1# Copilot Instructions for Neroli's Lab
2 
3## Project Overview
4 
5Neroli's Lab (SleepAPI) is a full-stack Pokémon Sleep application with a monorepo structure:
6 
7- **backend**: Express API with Bun dev runtime, Node.js production (TypeScript, Knex, MySQL, TSOA)
8- **frontend**: Vue 3 SPA with Vuetify 3 (Pinia state, Vite, Chart.js)
9- **common**: Shared TypeScript library bundled with Rollup (types, utilities, mocks)
10- **docs**: VitePress documentation site
11- **guides**: Vitepress player-facing Pokemon Sleep guides
12 
13## Development Workflow
14 
15### Starting Development
16 
17```bash
18# Backend (Bun with hot reload)
19cd backend && npm run dev
20 
21# Frontend (Vite)
22cd frontend && npm run dev
23 
24# Guides (Vitepress)
25cd guides && npm run dev
26 
27# Common library watch mode (when changing shared types)
28cd common && npm run build-watch
29```
30 
31### Required Pre-Push Checklist
32 
33**Always run these before committing:**
34 
351. **Test**: `npm run test` or `npx vitest --run -- filename.test.ts`
362. **Lint**: `npx eslint .` in the modified package
373. **Type check**:
38   - Frontend: `npm run type-check`
39   - Backend: `npm run _compile`
40   - Guides: `npm run type-check`
414. **Build common** if types changed: `cd common && npm run build`
42 
43### Test-Driven Development
44 
45**Always run tests after creating/modifying test files:**
46 
47```bash
48npx vitest --run -- filename.test.ts
49```
50 
51Use the output to iterate until tests pass. This is non-negotiable for quality assurance.
52 
53## Architecture Patterns
54 
55### Backend Layer Structure
56 
57**Controllers → Services → DAOs → Database**
58 
59- **Controllers** (`backend/src/controllers/`): TSOA-decorated endpoints (minimal, non-sensitive routes only)
60- **Services** (`backend/src/services/`): Business logic and orchestration
61- **DAOs** (`backend/src/database/dao/`): Data access extending `AbstractDAO` with repository pattern
62- **Database**: MySQL with Knex query builder
63 
64Example DAO pattern:
65 
66```typescript
67class UserDAO extends AbstractDAO<typeof DBUserSchema, DBUser> {
68  get tableName() {
69    return 'user';
70  }
71  protected get schema() {
72    return DBUserSchema;
73  }
74}
75```
76 
77### Frontend Component Organization
78 
79**Pages → Components → Stores → Services**
80 
81- **Pages** (`frontend/src/pages/`): Route-level components
82- **Components** (`frontend/src/components/`): Reusable UI following atomic design
83- **Stores** (`frontend/src/stores/`): Pinia state management
84- **Services** (`frontend/src/services/`): API clients matching backend endpoints
85 
86### Shared Code (Common Package)
87 
88All shared types, utilities, and test mocks live in `common/`:
89 
90```typescript
91// common/src/types/ - Types used by both backend and frontend
92// common/src/utils/ - Shared utility functions
93// common/src/vitest/mocks/ - Mock factories for testing
94```
95 
96**After changing common types:** Always run `cd common && npm run build` to update consumers.
97 
98## Testing Conventions
99 
100### Vue Component Testing Pattern
101 
102**Required structure for all Vue component tests:**
103 
104```typescript
105import type { VueWrapper } from '@vue/test-utils';
106import { mount } from '@vue/test-utils';
107import { beforeEach, afterEach, describe, expect, it } from 'vitest';
108import MyComponent from './my-component.vue';
109 
110describe('MyComponent', () => {
111  let wrapper: VueWrapper<InstanceType<typeof MyComponent>>;
112 
113  beforeEach(() => {
114    wrapper = mount(MyComponent, {
115      props: { someProp: 'value' }
116    });
117  });
118 
119  afterEach(() => {
120    wrapper.unmount();
121  });
122 
123  it('renders correctly', () => {
124    expect(wrapper.exists()).toBe(true);
125  });
126});
127```
128 
129### Mocking Strategy (Critical)
130 
131**Only mock external dependencies:**
132 
133✅ **DO Mock:**
134 
135- HTTP requests (axios, fetch)
136- Browser APIs (IntersectionObserver, matchMedia)
137 
138❌ **DON'T Mock:**
139 
140- Internal utility functions (formatters, calculators, validators)
141- Functions from `sleepapi-common` that work in Node.js test environment
142- Internal services without external dependencies
143 
144**Use mock factories from `{package}/src/vitest/mocks/` instead of inline hard-coded mocks.**
145 
146Example:
147 
148```typescript
149// Good - using mock factory
150import { mocks } from '@/vitest';
151const pokemon = mocks.pokemonInstanceExt({ level: 50 });
152 
153// Bad - hard-coded inline mock
154const pokemon = { level: 50, name: 'Test' } as any;
155```
156 
157### Test Setup
158 
159- Frontend tests use `jsdom` environment with Vuetify/Pinia configured in `frontend/src/vitest/setup.ts`
160- All packages use Vitest with coverage reporting
161- Common mocks are exported from `sleepapi-common` and extended by package-specific mocks
162 
163## Code Style Guidelines
164 
165### CSS/Styling
166 
167**Always use utility classes from `frontend/src/assets/common.scss`:**
168 
169```scss
170.flex-center      // display: flex; align-items: center; justify-content: center
171.flex-between     // display: flex; align-items: center; justify-content: space-between
172.flex-column      // display: flex; flex-direction: column
173.flex-wrap        // display: flex; flex-wrap: wrap
174```
175 
176**Rules:**
177 
178- Never use inline styles
179- Prefer utility classes over Vuetify utilities or custom CSS
180- Use scoped styles for component-specific CSS
181 
182### TypeScript
183 
184- Never use `any` unless working with generics
185- Prefer type inference over explicit types when clear
186- Use strict type checking (enabled in all packages)
187 
188### Code Comments
189 
190**Only add comments when necessary:**
191 
192- Explain WHY, not WHAT (code should be self-documenting)
193- Document complex business logic or non-obvious decisions
194- Remove obvious comments like `// Mock the module` or `// Set variable to X`
195 
196## Environment Setup
197 
198### Database
199 
200```bash
201docker-compose up -d  # Starts MySQL
202# Migrations run automatically when backend starts with DATABASE_MIGRATION=UP
203```
204 
205### Environment Files
206 
207Copy `.env.example` to `.env` in both frontend and backend directories. Key variables:
208 
209- Backend: `DATABASE_MIGRATION=UP` for auto-migrations
210- Frontend: API endpoint configuration
211 
212### Package Installation
213 
214```bash
215npm install              # Root (installs git hooks)
216cd backend && bun install
217cd frontend && npm install
218cd common && npm install
219```
220 
221## Commit Conventions
222 
223Follow [Conventional Commits](https://www.conventionalcommits.org/) (enforced by commitlint):
224 
225- `feat:` new features
226- `fix:` bug fixes
227- `style:` design/UI changes
228- `chore:` maintenance tasks
229- `refactor:` code restructuring
230- `test:` test changes
231- `perf:` performance improvements
232 
233**Rules:**
234 
235- Header ≤72 characters
236- No sentence case (lowercase unless proper nouns)
237- No period at end
238- No AI tool references in messages
239 
240## Pokémon Sleep Game Mechanics
241 
242This application simulates Pokémon Sleep mechanics. Key concepts:
243 
244### Core Gameplay
245 
246- Players track sleep (max 100 Sleep Score per session)
247- Helper Pokémon gather berries/ingredients throughout the day
248- Cook meals 3x daily (breakfast 04:00-12:00, lunch 12:00-18:00, dinner 18:00-04:00)
249- Feed Snorlax to increase strength
250- Weekly cycle resets Monday 04:00
251 
252### Helper Pokémon System
253 
254**Energy & Frequency** (`backend/src/services/simulation-service/team-simulator/member-state/`):
255 
256- Energy decreases 1 per 10 minutes linearly
257- Energy affects helping speed (80+ energy = 45% faster, 0 energy = slowest)
258- Helping frequency measured in seconds (e.g., 2400s = 40 minutes between helps)
259 
260**Specialties**:
261 
262- Berry Specialist: 2 berries/drop, lower ingredients (1 at level 1)
263- Ingredient Specialist: 1 berry/drop, more ingredients (2 at level 1)
264- Skill Specialist: Higher skill rate, can store 2 skill triggers
265 
266**Production**: Pokémon collect berries or ingredients. When carry limit reached, they auto-deliver (sneaky snacking).
267 
268### Simulation Engine
269 
270**Location**: `backend/src/services/simulation-service/team-simulator/`
271 
272- Monte Carlo simulations for predictions
273- Handles energy decay, help timing, skill activations, cooking
274- Pre-generated random numbers for performance (`pre-generated-random.ts`)
275 
276### Natures, Subskills, & Instance Properties
277 
278- **Natures** (`common/src/types/nature/`): Affect 5 stats (speed, energy recovery, exp, ingredient rate, skill chance)
279- **Subskills** (`common/src/types/subskill/`): Unlocked at levels 10, 25, 50, 75, 100 (unchangeable after catch)
280- **Instance Properties** (`common/src/types/instance/`): Nature, subskills, ingredient sets rolled at catch time
281 
282## Key File References
283 
284- **Types**: `common/src/types/{pokemon,mainskill,subskill,nature,instance}/`
285- **Simulation**: `backend/src/services/simulation-service/team-simulator/`
286- **API Controllers**: `backend/src/controllers/`
287- **Frontend Pages**: `frontend/src/pages/`
288- **Shared Mocks**: `common/src/vitest/mocks/`
289- **CSS Utilities**: `frontend/src/assets/common.scss`
290 
291## Multi-Workspace Structure
292 
293This VS Code workspace uses a multi-folder setup (`sleepapi.code-workspace`):
294 
295- Root folder for shared configs (ESLint, Prettier, commitlint)
296- Individual folders for each package (backend, frontend, common, docs, guides)
297- Relative imports configured via TypeScript path aliases (`@src/`, `@/`)
298 
299**Import preference**: Use path aliases, not relative imports (configured in workspace settings).
300