Add comprehensive GitHub Copilot instructions for node-switchbot repository (#300)

This PR adds a comprehensive `.github/copilot-instructions.md` file that
provides GitHub Copilot coding agents with detailed instructions on how
to work effectively in the node-switchbot codebase.

## Key Features

**Validated Commands and Timing**: Every command has been tested from a
clean environment with actual timing measurements:
- `npm install`: ~5-25 seconds (varies by cache)
- `npm run build`: ~5 seconds (TypeScript compilation)
- `npm run test`: ~1 second (12 tests)
- `npm run lint`: ~3 seconds (ESLint validation)

**Platform-Specific Requirements**: Clear documentation of constraints:
- BLE functionality requires Linux-based OS only (Raspbian, Ubuntu,
etc.)
- Windows and macOS are NOT supported for BLE operations
- Node.js versions: ^20, ^22, or ^24 required
- ES Modules: Project uses `"type": "module"`

**Development Workflow**: Step-by-step instructions for common tasks:
- Bootstrap and setup procedures
- Build, test, and lint validation cycles
- Adding new device support
- Working with both BLE and OpenAPI interfaces

**Manual Validation Scenarios**: Specific tests to run after making
changes:
```javascript
// Basic functionality validation
const { SwitchBotBLE, SwitchBotOpenAPI } = require('./dist/index.js');
const ble = new SwitchBotBLE(); // Should not throw
const api = new SwitchBotOpenAPI('test', 'test'); // Should not throw
```

**Timeout Warnings**: Explicit "NEVER CANCEL" warnings with timeout
recommendations for all build operations to prevent premature
cancellation of long-running commands.

## Project Structure Documentation

The instructions include comprehensive information about:
- Source code organization (`src/switchbot-ble.ts`,
`src/switchbot-openapi.ts`, device classes)
- Configuration files (TypeScript, ESLint, package.json)
- Build output structure (`dist/` directory)
- Documentation generation (TypeDoc)

## Validation Completed

All instructions have been thoroughly validated by:
- Following step-by-step procedures from a clean environment
- Testing basic functionality scenarios
- Verifying ES module imports work correctly
- Confirming full development workflow chain
- Measuring actual timing for all operations

The instructions follow the required imperative tone ("Run [this
command]", "Do not do [this]") and provide exhaustive guidance for
GitHub Copilot agents to work effectively in this TypeScript Node.js
library for controlling SwitchBot devices via Bluetooth Low Energy and
OpenAPI.

Fixes #299.

<!-- START COPILOT CODING AGENT TIPS -->
---

💡 You can make Copilot smarter by setting up custom instructions,
customizing its development environment and configuring Model Context
Protocol (MCP) servers. Learn more [Copilot coding agent
tips](https://gh.io/copilot-coding-agent-tips) in the docs.

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: donavanbecker <[email protected]>

Author: Copilot

.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