Add comprehensive GitHub Copilot instructions for node-switchbot repository

.github/copilot-instructions.md

@@ -0,0 +1,165 @@
+# Node-SwitchBot Development Instructions
+
+Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
+
+## Working Effectively
+
+### Bootstrap and Setup
+- Install Node.js (^20 || ^22 || ^24): Use the existing version if available
+- Install dependencies: `npm install` -- takes ~5-25 seconds (varies by cache). **NEVER CANCEL**
+- Build the project: `npm run build` -- takes ~5 seconds. **NEVER CANCEL**
+- Run tests: `npm run test` -- takes ~1 second with 12 tests. **NEVER CANCEL**
+
+### Development Workflow
+- **ALWAYS run these commands in order when starting work:**
+  1. `npm install` 
+  2. `npm run build`
+  3. `npm run test`
+  4. `npm run lint`
+- **Build and validate EVERY change**: After any code modification, always run `npm run build && npm run test && npm run lint`
+- **NEVER skip linting**: Run `npm run lint` before committing or the CI (.github/workflows/build.yml) will fail
+- **Use lint:fix for automatic fixes**: `npm run lint:fix` to automatically fix ESLint issues
+
+### Platform Requirements and Constraints
+- **BLE functionality requires Linux-based OS only** (Raspbian, Ubuntu, etc.)
+- **Windows and macOS are NOT supported** for BLE operations (use OpenAPI instead)
+- **Node.js versions**: Must use ^20, ^22, or ^24 (currently using v20.19.4)
+- **ES Modules**: This project uses `"type": "module"` - always use ES import/export syntax
+
+### Testing and Validation
+- **Basic functionality test**: After any changes to core classes, run this validation:
+  ```javascript
+  const { SwitchBotBLE, SwitchBotOpenAPI } = require('./dist/index.js');
+  const ble = new SwitchBotBLE(); // Should not throw
+  const api = new SwitchBotOpenAPI('test', 'test'); // Should not throw
+  ```
+- **Complete test suite**: `npm run test` (12 tests) -- should always pass before committing
+- **Test coverage**: `npm run test-coverage` to see coverage report (~15% coverage is normal)
+- **Documentation generation**: `npm run docs` generates TypeDoc documentation in ./docs/
+
+### Build and Timing Expectations
+- **npm install**: ~5-25 seconds (varies by cache) -- **NEVER CANCEL**. Set timeout to 5+ minutes for safety
+- **npm run build**: ~5 seconds -- **NEVER CANCEL**. Set timeout to 2+ minutes for safety  
+- **npm run test**: ~1 second (12 tests) -- **NEVER CANCEL**. Set timeout to 2+ minutes for safety
+- **npm run lint**: ~3 seconds -- **NEVER CANCEL**. Set timeout to 2+ minutes for safety
+- **npm run docs**: ~2 seconds -- **NEVER CANCEL**. Set timeout to 2+ minutes for safety
+
+## Project Structure and Key Files
+
+### Source Code Organization
+- **src/index.ts**: Main export file - exports SwitchBotBLE, SwitchBotOpenAPI, and device classes
+- **src/switchbot-ble.ts**: Bluetooth Low Energy interface for direct device control
+- **src/switchbot-openapi.ts**: HTTP API interface for cloud-based SwitchBot control
+- **src/device.ts**: Individual device classes (WoHand, WoCurtain, WoSmartLock, etc.)
+- **src/types/**: TypeScript type definitions for all device interfaces
+- **src/settings.ts**: Configuration constants and API URLs
+- **dist/**: Compiled JavaScript output (generated by `npm run build`)
+
+### Configuration Files  
+- **package.json**: Main project config - scripts, dependencies, ES module config
+- **tsconfig.json**: TypeScript compilation settings (target: ES2022, module: ES2022)
+- **eslint.config.js**: ESLint configuration using @antfu/eslint-config
+- **jest.config.js**: Test configuration (uses Vitest, not Jest)
+- **.gitignore**: Excludes dist/, node_modules/, coverage/, and build artifacts
+
+### Documentation
+- **README.md**: Main project documentation and installation instructions
+- **BLE.md**: Comprehensive BLE usage documentation and device examples
+- **OpenAPI.md**: OpenAPI usage documentation and authentication setup
+- **CHANGELOG.md**: Version history and release notes
+- **docs/**: Generated TypeDoc API documentation (HTML format)
+
+## Common Development Tasks
+
+### Adding New Device Support
+- **Add device class**: Create new class in src/device.ts extending SwitchbotDevice
+- **Update exports**: Add export to src/index.ts
+- **Add type definitions**: Create types in src/types/ if needed
+- **Test basic instantiation**: Ensure the device class can be imported and instantiated
+- **Always run full build and test cycle**: `npm run build && npm run test && npm run lint`
+
+### API Changes and Extensions
+- **OpenAPI changes**: Modify src/switchbot-openapi.ts
+- **BLE changes**: Modify src/switchbot-ble.ts
+- **Update type definitions**: Modify corresponding files in src/types/
+- **Always verify exports**: Check that new functionality is exported in src/index.ts
+- **Test import functionality**: Verify new exports can be imported correctly
+
+### Working with Dependencies
+- **Noble (BLE)**: @stoprocent/noble for Bluetooth functionality - Linux only
+- **HTTP requests**: Uses undici for HTTP calls (not axios or fetch)
+- **Async operations**: Uses async-mutex for concurrency control
+- **Adding dependencies**: Use `npm install --save` for runtime deps, `--save-dev` for dev deps
+
+## Validation and Quality Assurance
+
+### Pre-commit Checklist
+1. **Build succeeds**: `npm run build` completes without errors
+2. **All tests pass**: `npm run test` shows all 12 tests passing
+3. **Linting passes**: `npm run lint` shows no errors
+4. **Documentation builds**: `npm run docs` generates without warnings
+5. **Basic import works**: Can import and instantiate main classes
+
+### Manual Testing Scenarios
+- **SwitchBotBLE instantiation**: `new SwitchBotBLE()` should not throw errors
+- **SwitchBotOpenAPI instantiation**: `new SwitchBotOpenAPI('token', 'secret')` should not throw
+- **Module exports**: All exported classes should be importable from main package
+- **TypeScript compilation**: No TypeScript errors in dist/ output
+- **Documentation completeness**: Check that new public APIs appear in generated docs
+
+### CI/CD Integration
+- **GitHub Actions**: Build runs on push to 'latest' branch and PRs
+- **External workflows**: Uses OpenWonderLabs/.github/.github/workflows/nodejs-build-and-test.yml
+- **Required checks**: Build, test, and lint must all pass
+- **Coverage reporting**: Test coverage is tracked and reported
+
+## Troubleshooting Common Issues
+
+### BLE Not Working
+- **Check OS**: BLE only works on Linux-based systems
+- **Install noble prerequisites**: May need additional system libraries for @stoprocent/noble
+- **Use OpenAPI instead**: For Windows/macOS development, use SwitchBotOpenAPI class
+
+### Build Failures
+- **Check Node.js version**: Must be ^20, ^22, or ^24
+- **Clean and rebuild**: `npm run clean && npm install && npm run build`
+- **TypeScript errors**: Check tsconfig.json settings and type definitions
+
+### Test Failures
+- **Run individual tests**: Use `npm run test:watch` for interactive testing
+- **Check imports**: Ensure all imports use correct ES module syntax
+- **Verify exports**: Check that src/index.ts exports all necessary components
+
+### Linting Errors
+- **Auto-fix**: Use `npm run lint:fix` to automatically fix many issues
+- **ESLint config**: Review eslint.config.js for current rules
+- **Import sorting**: ESLint enforces specific import order - use lint:fix
+
+## Frequently Referenced Information
+
+### Package Scripts (from package.json)
+```bash
+npm run build       # Clean and compile TypeScript
+npm run test        # Run test suite with Vitest
+npm run lint        # Run ESLint on src/**/*.ts
+npm run lint:fix    # Auto-fix ESLint issues
+npm run docs        # Generate TypeDoc documentation
+npm run clean       # Remove dist/ directory
+npm run watch       # Build and link for development
+```
+
+### Main Exports (from src/index.ts)
+- **SwitchBotBLE**: Bluetooth interface class
+- **SwitchBotOpenAPI**: HTTP API interface class  
+- **SwitchbotDevice**: Base device class
+- **Device classes**: WoHand, WoCurtain, WoSmartLock, etc.
+- **Type definitions**: All device status and response types
+
+### Dependencies Summary
+- **@stoprocent/noble**: BLE functionality (Linux only)
+- **undici**: HTTP client for API requests
+- **async-mutex**: Concurrency control
+- **TypeScript**: Language and compilation
+- **Vitest**: Testing framework
+- **ESLint**: Code linting with @antfu/eslint-config
+- **TypeDoc**: API documentation generation