Refactor copilot instructions: add meta-directives and condense content (#992)
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: thomasnordquist <7721625+thomasnordquist@users.noreply.github.com>
This commit is contained in:
Copilot
303
.github/copilot-instructions.md
vendored
303
.github/copilot-instructions.md
vendored
@@ -1,263 +1,80 @@
|
||||
# GitHub Copilot Agent Instructions for MQTT Explorer
|
||||
# copilot-instructions.md - Agent Long-Term Memory
|
||||
|
||||
## Test Suites
|
||||
## META-INSTRUCTIONS (IMMUTABLE)
|
||||
|
||||
MQTT Explorer has several test suites to ensure code quality and reliability:
|
||||
1. **Long-term memory**: If you learn something during a session that would save time in future sessions, add it to `.github/copilot-instructions.md`
|
||||
2. **Paper knowledge must go**: If something is no longer true, update or remove it immediately
|
||||
3. **Evaluate after every session**: Consider whether the instructions need updates based on what you learned
|
||||
4. **Concise and useful**: All information must be actionable, current, and concise
|
||||
|
||||
### Unit Tests
|
||||
## Test Commands
|
||||
|
||||
**App tests** - Frontend component and logic tests:
|
||||
**Unit tests:**
|
||||
- `yarn test` - All unit tests (app + backend)
|
||||
- `yarn test:app` - Frontend tests only
|
||||
- `yarn test:backend` - Backend tests only
|
||||
|
||||
**Integration tests:**
|
||||
- `yarn test:ui` - Browser tests (requires `yarn build` first)
|
||||
- `yarn test:demo-video` - UI recording (requires Xvfb, mosquitto, tmux, ffmpeg)
|
||||
- `yarn test:mcp` - Model Context Protocol tests
|
||||
- `yarn test:all` - All tests (unit + demo-video)
|
||||
|
||||
**CI jobs:** `test`, `ui-tests`, `demo-video`, `test-browser`
|
||||
|
||||
## Browser Mode
|
||||
|
||||
**Prerequisites:** Node.js ≥24, Yarn, Mosquitto broker (for testing)
|
||||
|
||||
**Development (hot reload):**
|
||||
```bash
|
||||
yarn test:app
|
||||
# Or: cd app && yarn test
|
||||
export MQTT_EXPLORER_USERNAME=admin MQTT_EXPLORER_PASSWORD=yourpass
|
||||
yarn dev:server
|
||||
# Backend: http://localhost:3000, Frontend: http://localhost:8080 (use this one)
|
||||
```
|
||||
|
||||
**Backend tests** - Data model and business logic tests:
|
||||
**Production:**
|
||||
```bash
|
||||
yarn test:backend
|
||||
# Or: cd backend && yarn test
|
||||
yarn build:server
|
||||
export MQTT_EXPLORER_USERNAME=admin MQTT_EXPLORER_PASSWORD=yourpass
|
||||
yarn start:server # http://localhost:3000
|
||||
```
|
||||
|
||||
**Run all unit tests**:
|
||||
```bash
|
||||
yarn test
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
|
||||
**UI test suite** - Independent, deterministic browser tests:
|
||||
```bash
|
||||
yarn test:ui
|
||||
# Requires: yarn build
|
||||
```
|
||||
|
||||
**Demo video generation** - UI test recording with video capture:
|
||||
```bash
|
||||
yarn test:demo-video
|
||||
# Requires: Xvfb, mosquitto broker, tmux, ffmpeg
|
||||
# For development: Use ./scripts/uiTests.sh for full video recording setup
|
||||
```
|
||||
|
||||
**MCP introspection tests** - Model Context Protocol tests:
|
||||
```bash
|
||||
yarn test:mcp
|
||||
```
|
||||
|
||||
**Run all tests** (unit + demo-video):
|
||||
```bash
|
||||
yarn test:all
|
||||
```
|
||||
|
||||
### CI/CD Test Execution
|
||||
|
||||
In CI environments, tests run in isolated containers with all dependencies pre-installed:
|
||||
- `test` job: Runs unit tests (app + backend)
|
||||
- `ui-tests` job: Runs UI test suite with screenshots
|
||||
- `demo-video` job: Generates demo video with full recording setup
|
||||
- `test-browser` job: Runs browser mode smoke tests
|
||||
**Build artifacts:** `dist/src/server.js`, `app/build/*.js`, `app/build/index.html`
|
||||
|
||||
## Debugging Browser Mode
|
||||
|
||||
### Prerequisites
|
||||
- Node.js 24 or higher
|
||||
- Yarn package manager
|
||||
- Running Mosquitto MQTT broker (for testing)
|
||||
**DevTools checks:**
|
||||
- Console: JavaScript errors, CSP errors (security headers), WebSocket issues
|
||||
- Network: Static asset loading, WebSocket status, API auth
|
||||
|
||||
### Development Mode (with Hot Reload)
|
||||
**Common issues:**
|
||||
- **Blank page/CSP errors:** Add `'unsafe-eval'` to `scriptSrc` in `src/server.ts` helmet config
|
||||
- **Auth loop:** WebSocket auth failing - check Network → WS → Messages and server logs
|
||||
- **Theme errors:** Verify both ThemeProvider and LegacyThemeProvider in `app/src/index.tsx`
|
||||
|
||||
1. **Set credentials (required):**
|
||||
```bash
|
||||
export MQTT_EXPLORER_USERNAME=admin
|
||||
export MQTT_EXPLORER_PASSWORD=your_password
|
||||
```
|
||||
|
||||
2. **Start development servers:**
|
||||
```bash
|
||||
yarn dev:server
|
||||
```
|
||||
This runs two servers in parallel:
|
||||
- Backend server on http://localhost:3000 (serves API, WebSocket, authentication)
|
||||
- Webpack dev server on http://localhost:8080 (serves frontend with hot reload)
|
||||
|
||||
3. **Access the application:**
|
||||
- Navigate to http://localhost:8080 (NOT :3000)
|
||||
- Webpack dev server proxies API/WebSocket requests to backend on port 3000
|
||||
- Hot reload enabled - changes to React components update automatically
|
||||
|
||||
### Production Mode (Production Build)
|
||||
|
||||
1. **Build the browser version:**
|
||||
```bash
|
||||
yarn build:server
|
||||
```
|
||||
This compiles TypeScript and builds the optimized webpack bundle
|
||||
|
||||
2. **Start the server:**
|
||||
```bash
|
||||
# Set credentials (required) - these are for the browser login page
|
||||
export MQTT_EXPLORER_USERNAME=admin
|
||||
export MQTT_EXPLORER_PASSWORD=your_password
|
||||
|
||||
# Start server
|
||||
yarn start:server
|
||||
# OR: node dist/src/server.js
|
||||
```
|
||||
Server will run on http://localhost:3000 (serves both frontend and backend)
|
||||
|
||||
3. **Login to the application:**
|
||||
- Navigate to http://localhost:3000
|
||||
- Enter the username and password you set in the environment variables
|
||||
- Click "LOGIN" button
|
||||
- After successful login, the main application will load
|
||||
- The MQTT Connection modal will appear where you can configure broker connections
|
||||
|
||||
### Debugging with Browser DevTools
|
||||
|
||||
1. **Open browser DevTools:**
|
||||
- Navigate to http://localhost:3000
|
||||
- Press F12 or right-click → Inspect
|
||||
|
||||
2. **Check Console tab:**
|
||||
- Look for JavaScript errors
|
||||
- CSP (Content Security Policy) errors indicate security header issues
|
||||
- Network errors indicate API/WebSocket connection issues
|
||||
|
||||
3. **Check Network tab:**
|
||||
- Verify static assets load correctly (JS bundles, CSS)
|
||||
- Check WebSocket connection status
|
||||
- Monitor API calls for authentication issues
|
||||
|
||||
4. **Common Issues:**
|
||||
|
||||
**Blank page / CSP errors:**
|
||||
- Symptom: Console shows `EvalError: ... violates Content Security Policy`
|
||||
- Cause: webpack runtime requires `unsafe-eval` for code splitting
|
||||
- Fix: Add `'unsafe-eval'` to `scriptSrc` in `src/server.ts` helmet config
|
||||
|
||||
**Authentication loop:**
|
||||
- Symptom: Login dialog keeps reappearing
|
||||
- Cause: WebSocket authentication failing
|
||||
- Debug: Check browser Network tab → WS → Messages
|
||||
- Check: Server logs for authentication errors
|
||||
|
||||
**Theme errors:**
|
||||
- Symptom: App loads but styling is broken
|
||||
- Cause: Material-UI theme not loading correctly
|
||||
- Check: Console for theme-related errors
|
||||
- Verify: Both ThemeProvider and LegacyThemeProvider in `app/src/index.tsx`
|
||||
|
||||
**Expected console warnings (non-fatal):**
|
||||
- React 18 type warnings with Material-UI v5 components (dozens of "Failed prop type" warnings)
|
||||
- `TypeError: Cannot read properties of undefined (reading 'on')` from IpcRendererEventBus - this is expected in browser mode as there's no Electron IPC
|
||||
- MUI locale warnings for `en-US` - expected, app uses available locales
|
||||
- `componentWillReceiveProps` deprecation warnings - from legacy TreeComponent
|
||||
- ACE editor autocomplete warnings - expected, features not imported
|
||||
- CSP worker violation for ACE editor - known issue, editor still functions
|
||||
|
||||
These warnings don't prevent the application from functioning correctly.
|
||||
|
||||
### Using Playwright for Automated Testing
|
||||
**Expected warnings (non-fatal):**
|
||||
- React 18 + Material-UI v5 type warnings
|
||||
- IpcRendererEventBus errors (no Electron IPC in browser mode)
|
||||
- MUI locale, componentWillReceiveProps, ACE editor warnings
|
||||
|
||||
**WebSocket debugging:**
|
||||
```bash
|
||||
# Start server in background
|
||||
export MQTT_EXPLORER_USERNAME=admin
|
||||
export MQTT_EXPLORER_PASSWORD=test123
|
||||
node dist/src/server.js &
|
||||
|
||||
# Use Playwright browser tool (in Copilot agent context)
|
||||
playwright-browser_navigate http://localhost:3000
|
||||
playwright-browser_take_screenshot --filename debug.png
|
||||
playwright-browser_console_messages # Check for errors
|
||||
node dist/src/server.js 2>&1 | tee server.log
|
||||
# Check DevTools → Network → WS → Messages for handshake
|
||||
# CORS: check ALLOWED_ORIGINS env var
|
||||
```
|
||||
|
||||
### Expected UI Flow
|
||||
**Security notes:**
|
||||
- `unsafe-eval` in CSP required for webpack (security tradeoff)
|
||||
- Never hardcode credentials (use env vars)
|
||||
- Production: use HTTPS with reverse proxy
|
||||
- Rate limit: 5 auth attempts/15min/IP
|
||||
- File upload limit: 16MB
|
||||
|
||||
1. **Login Page** (https://github.com/user-attachments/assets/383305e1-2169-433c-a668-5a05da0c343a)
|
||||
- Enter username and password from environment variables
|
||||
- Click "LOGIN" button
|
||||
|
||||
2. **Main Application After Login** (https://github.com/user-attachments/assets/cc4d665f-2665-4289-b2fc-dc4986f9ab5b)
|
||||
- Application loads with sidebar, topic tree, value panel, and publish panel
|
||||
- MQTT Connection modal appears automatically for first-time setup
|
||||
- Configure broker connection (host, port, credentials, etc.)
|
||||
- Click "CONNECT" to establish MQTT connection
|
||||
|
||||
3. **Application Features:**
|
||||
- Topic tree on the left shows MQTT topic hierarchy
|
||||
- Value panel shows selected topic's message content
|
||||
- Publish panel allows sending MQTT messages
|
||||
- Charts panel for numeric value visualization
|
||||
- Settings drawer for app configuration
|
||||
|
||||
### Debugging WebSocket Connection
|
||||
|
||||
1. **Check server logs:**
|
||||
```bash
|
||||
node dist/src/server.js 2>&1 | tee server.log
|
||||
```
|
||||
|
||||
2. **Check browser WebSocket:**
|
||||
- DevTools → Network → WS tab
|
||||
- Look for socket.io connection
|
||||
- Check Messages tab for authentication handshake
|
||||
|
||||
3. **Common WebSocket issues:**
|
||||
- CORS errors: Check `ALLOWED_ORIGINS` environment variable
|
||||
- Authentication errors: Verify credentials in sessionStorage
|
||||
- Connection refused: Server not running or port blocked
|
||||
|
||||
### Development vs Production
|
||||
|
||||
**Development mode:**
|
||||
```bash
|
||||
yarn dev:server
|
||||
# Runs webpack-dev-server with hot reload
|
||||
# More verbose error messages
|
||||
# Source maps enabled
|
||||
```
|
||||
|
||||
**Production mode:**
|
||||
```bash
|
||||
NODE_ENV=production yarn build:server
|
||||
NODE_ENV=production node dist/src/server.js
|
||||
# Minified bundles
|
||||
# Generic error messages (security)
|
||||
# HSTS enabled
|
||||
```
|
||||
|
||||
### Build Artifacts
|
||||
|
||||
After `yarn build:server`, check:
|
||||
- `dist/src/server.js` - Compiled server code
|
||||
- `app/build/*.js` - Webpack bundles
|
||||
- `app/build/index.html` - Entry point HTML
|
||||
|
||||
### Troubleshooting Checklist
|
||||
|
||||
- [ ] Node.js version >=24
|
||||
- [ ] `yarn install` completed without errors
|
||||
- [ ] TypeScript compilation successful (`npx tsc`)
|
||||
- [ ] Webpack build successful (check `app/build/` directory)
|
||||
- [ ] Server starts without errors
|
||||
- [ ] Can access http://localhost:3000
|
||||
- [ ] Login dialog appears
|
||||
- [ ] No CSP errors in console
|
||||
- [ ] WebSocket connects successfully
|
||||
- [ ] App renders after login
|
||||
|
||||
### Security Considerations
|
||||
|
||||
When debugging, be aware that:
|
||||
- `unsafe-eval` in CSP is required for webpack but reduces security
|
||||
- Credentials should never be hardcoded (use environment variables)
|
||||
- In production, use HTTPS with a reverse proxy (nginx/Apache)
|
||||
- Rate limiting is active (5 auth attempts per 15 min per IP)
|
||||
- File upload size limit is 16MB
|
||||
|
||||
### Related Files
|
||||
|
||||
- `src/server.ts` - Express server with security middleware
|
||||
- `app/webpack.browser.config.mjs` - Browser-specific webpack config
|
||||
- `app/src/browserEventBus.ts` - Socket.io client for browser mode
|
||||
- `app/src/components/BrowserAuthWrapper.tsx` - Authentication dialog
|
||||
- `app/src/index.tsx` - React app entry point with theme providers
|
||||
**Key files:**
|
||||
- `src/server.ts` - Express server, security middleware
|
||||
- `app/webpack.browser.config.mjs` - Browser webpack config
|
||||
- `app/src/browserEventBus.ts` - Socket.io client
|
||||
- `app/src/components/BrowserAuthWrapper.tsx` - Auth dialog
|
||||
- `app/src/index.tsx` - React entry, theme providers
|
||||
|
||||
Reference in New Issue
Block a user