Copilot instructions

1# Copilot Instructions for Uptime Kuma
2 
3Warning: Only maintainers of Uptime Kuma can use this instructions, for other contributors, must read AGENTS.md and CLAUDE.md to avoid to get banned because of AI slop.
4 
5## Copilot's Goals/Tasks
6 
7- Check spelling
8- Do not show "Pull Request Overview"
9- You do not have to reply if there are no issues
10 
11## Repository Overview
12 
13**Uptime Kuma** is a self-hosted monitoring tool for HTTP(s), TCP, DNS, Docker, etc. Built with Vue 3 (frontend) and Node.js/Express (backend), using Socket.IO for real-time communication.
14 
15- **Languages**: JavaScript, Vue 3, TypeScript (limited), HTML, CSS/SCSS
16- **Backend**: Node.js >= 20.4, Express.js, Socket.IO, SQLite
17- **Frontend**: Vue 3, Vite, Bootstrap 5, Chart.js
18- **Package Manager**: npm with `legacy-peer-deps=true` (.npmrc)
19 
20## Build & Validation Commands
21 
22### Prerequisites
23 
24- Node.js >= 20.4.0, npm >= 9.3, Git
25 
26### Essential Command Sequence
27 
281. **Install Dependencies**:
29 
30```bash
31   npm ci  # Use npm ci NOT npm install (~60-90 seconds)
32```
33 
342. **Linting** (required before committing):
35 
36```bash
37   npm run lint         # Both linters (~15-30 seconds)
38   npm run lint:prod    # For production (zero warnings)
39```
40 
413. **Build Frontend**:
42 
43```bash
44   npm run build  # Takes ~90-120 seconds, builds to dist/
45```
46 
474. **Run Tests**:
48```bash
49   npm run test-backend  # Backend tests (~50-60 seconds)
50   npm test              # All tests
51```
52 
53### Development Workflow
54 
55```bash
56npm run dev  # Starts frontend (port 3000) and backend (port 3001)
57```
58 
59## Project Architecture
60 
61### Directory Structure
62 
63```
64/
65├── server/              Backend source code
66│   ├── model/          Database models (auto-mapped to tables)
67│   ├── monitor-types/  Monitor type implementations
68│   ├── notification-providers/  Notification integrations
69│   ├── routers/        Express routers
70│   ├── socket-handlers/  Socket.IO event handlers
71│   ├── server.js       Server entry point
72│   └── uptime-kuma-server.js  Main server logic
73├── src/                Frontend source code (Vue 3 SPA)
74│   ├── components/     Vue components
75│   ├── pages/          Page components
76│   ├── lang/          i18n translations
77│   ├── router.js      Vue Router configuration
78│   └── main.js        Frontend entry point
79├── db/                 Database related
80│   ├── knex_migrations/  Knex migration files
81│   └── kuma.db        SQLite database (gitignored)
82├── test/               Test files
83│   ├── backend-test/  Backend unit tests
84│   └── e2e/           Playwright E2E tests
85├── config/             Build configuration
86│   ├── vite.config.js    Vite build config
87│   └── playwright.config.js  Playwright test config
88├── dist/               Frontend build output (gitignored)
89├── data/               App data directory (gitignored)
90├── public/             Static frontend assets (dev only)
91├── docker/             Docker build files
92└── extra/              Utility scripts
93```
94 
95### Key Configuration Files
96 
97- **package.json**: Scripts, dependencies, Node.js version requirement
98- **.eslintrc.js**: ESLint rules (4 spaces, double quotes, unix line endings, JSDoc required)
99- **.stylelintrc**: Stylelint rules (4 spaces indentation)
100- **.editorconfig**: Editor settings (4 spaces, LF, UTF-8)
101- **tsconfig-backend.json**: TypeScript config for backend (only src/util.ts)
102- **.npmrc**: `legacy-peer-deps=true` (required for dependency resolution)
103- **.gitignore**: Excludes node_modules, dist, data, tmp, private
104 
105### Code Style (strictly enforced by linters)
106 
107- 4 spaces indentation, double quotes, Unix line endings (LF), semicolons required
108- **Naming**: JavaScript/TypeScript (camelCase), SQLite (snake_case), CSS/SCSS (kebab-case)
109- JSDoc required for all functions/methods
110 
111## CI/CD Workflows
112 
113**auto-test.yml** (runs on PR/push to master/1.23.X):
114 
115- Linting, building, backend tests on multiple OS/Node versions (15 min timeout)
116- E2E Playwright tests
117 
118**validate.yml**: Validates JSON/YAML files, language files, knex migrations
119 
120**PR Requirements**: All linters pass, tests pass, code follows style guidelines
121 
122## Common Issues
123 
1241. **npm install vs npm ci**: Always use `npm ci` for reproducible builds
1252. **TypeScript errors**: `npm run tsc` shows 1400+ errors - ignore them, they don't affect builds
1263. **Stylelint warnings**: Deprecation warnings are expected, ignore them
1274. **Test failures**: Always run `npm run build` before running tests
1285. **Port conflicts**: Dev server uses ports 3000 and 3001
1296. **First run**: Server shows "db-config.json not found" - this is expected, starts setup wizard
130 
131## Translations
132 
133- Managed via Weblate. Add keys to `src/lang/en.json` only
134- Don't include other languages in PRs
135- Use `$t("key")` in Vue templates
136 
137## Database
138 
139- Primary: SQLite (also supports MariaDB/MySQL)
140- Migrations in `db/knex_migrations/` using Knex.js
141- Filename format validated by CI: `node ./extra/check-knex-filenames.mjs`
142 
143## Testing
144 
145- **Backend**: Node.js test runner, fast unit tests
146- **E2E**: Playwright (requires `npx playwright install` first time)
147- Test data in `data/playwright-test`
148 
149## Adding New Features
150 
151### New Notification Provider
152 
153Files to modify:
154 
1551. `server/notification-providers/PROVIDER_NAME.js` (backend logic)
1562. `server/notification.js` (register provider)
1573. `src/components/notifications/PROVIDER_NAME.vue` (frontend UI)
1584. `src/components/notifications/index.js` (register frontend)
1595. `src/components/NotificationDialog.vue` (add to list)
1606. `src/lang/en.json` (add translation keys)
161 
162### New Monitor Type
163 
164Files to modify:
165 
1661. `server/monitor-types/MONITORING_TYPE.js` (backend logic)
1672. `server/uptime-kuma-server.js` (register monitor type)
1683. `src/pages/EditMonitor.vue` (frontend UI)
1694. `src/lang/en.json` (add translation keys)
170 
171## Important Notes
172 
1731. **Trust these instructions** - based on testing. Search only if incomplete/incorrect
1742. **Dependencies**: 5 known vulnerabilities (3 moderate, 2 high) - acknowledged, don't fix without discussion
1753. **Git Branches**: `master` (v2 development), `1.23.X` (v1 maintenance)
1764. **Node Version**: >= 20.4.0 required
1775. **Socket.IO**: Most backend logic in `server/socket-handlers/`, not REST
1786. **Never commit**: `data/`, `dist/`, `tmp/`, `private/`, `node_modules/`
179