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.

**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.

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)

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.

---------

Update Workflow

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

.github/workflows/beta-release.yml

@@ -7,22 +7,20 @@ on:
 
 jobs:
   build_and_test:
-    uses: OpenWonderLabs/.github/.github/workflows/nodejs-build-and-test.yml@latest
+    uses: homebridge/.github/.github/workflows/nodejs-build-and-test.yml@latest
     with:
-      enable_coverage: true
+      enable_coverage: false
     secrets:
       token: ${{ secrets.GITHUB_TOKEN }}
-
   lint:
     needs: build_and_test
-    uses: OpenWonderLabs/.github/.github/workflows/eslint.yml@latest
+    uses: homebridge/.github/.github/workflows/eslint.yml@latest
 
   publish:
     needs: lint
-    if: ${{ github.repository == 'OpenWonderLabs/node-switchbot' }}
     permissions:
       id-token: write
-    uses: OpenWonderLabs/.github/.github/workflows/npm-publish-esm.yml@latest
+    uses: homebridge/.github/.github/workflows/npm-publish-esm.yml@latest
     with:
       tag: 'beta'
       dynamically_adjust_version: true
@@ -33,24 +31,22 @@ jobs:
 
   pre-release:
     needs: publish
-    if: ${{ github.repository == 'OpenWonderLabs/node-switchbot' }}
-    uses: OpenWonderLabs/.github/.github/workflows/pre-release.yml@latest
+    uses: homebridge/.github/.github/workflows/pre-release.yml@latest
     with:
       npm_version: ${{ needs.publish.outputs.NPM_VERSION }}
       body: |
         **Beta Release**
         **Version**: v${{ needs.publish.outputs.NPM_VERSION }}
-        [How To Test Beta Releases](https://github.com/OpenWonderLabs/homebridge-switchbot/wiki/Beta-Version)
+        [How To Test Beta Releases](https://github.com/OpenWonderLabs/homebridge-air/wiki/Beta-Version)
 
   github-releases-to-discord:
     name: Discord Webhooks
     needs: [build_and_test,publish]
-    if: ${{ github.repository == 'OpenWonderLabs/node-switchbot' }}
-    uses: OpenWonderLabs/.github/.github/workflows/discord-webhooks.yml@latest
+    uses: homebridge/.github/.github/workflows/discord-webhooks.yml@latest
     with:
-      title: "Node-SwitchBot Beta Release"
+      title: "Node-SwitchBot  Module Beta Release"
       description: |
         Version `v${{ needs.publish.outputs.NPM_VERSION }}`
-      url: "https://github.com/homebridge/camera-utils/releases/tag/v${{ needs.publish.outputs.NPM_VERSION }}"
+      url: "https://github.com/OpenWonderLabs/homebridge-air/releases/tag/v${{ needs.publish.outputs.NPM_VERSION }}"
     secrets:
-      DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK_URL_BETA || secrets.DISCORD_WEBHOOK_URL_LATEST }}
+      DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK_URL_LATEST }}

.github/workflows/build.yml

@@ -1,35 +1,75 @@
-name: Release
+name: Unified Release
 
 on:
-  release:
-    types: [published]
+  push:
+    branches:
+      #- "alpha-*"
+      #- "beta-*"
+      - latest
+  workflow_dispatch:
 
 jobs:
-  build_and_test:
-    uses: OpenWonderLabs/.github/.github/workflows/nodejs-build-and-test.yml@latest
+  # 1️⃣ Determine release type, ESM status, and branch name
+  determine-release-type:
+    uses: homebridge/.github/.github/workflows/determine-release-type.yml@latest
     with:
-      enable_coverage: true
+      ref_name: ${{ github.ref_name }}
+
+  # 2️⃣ Update version and changelog using the scripts
+  update-version:
+    needs: determine-release-type
+    uses: homebridge/.github/.github/workflows/update-version.yml@latest
+    with:
+      release_type: ${{ needs.determine-release-type.outputs.release_type }}
+      is_esm: ${{ needs.determine-release-type.outputs.is_esm == 'true' }}
     secrets:
-      token: ${{ secrets.GITHUB_TOKEN }}
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 
-  publish:
-    needs: build_and_test
-    if: ${{ github.repository == 'OpenWonderLabs/node-switchbot' }}
+  # 3️⃣ Publish to NPM and create GitHub release
+  publish-release:
+    needs: [determine-release-type, update-version]
     permissions:
       id-token: write
-    uses: OpenWonderLabs/.github/.github/workflows/npm-publish-esm.yml@latest
+      contents: write
+    uses: homebridge/.github/.github/workflows/publish-release.yml@latest
+    with:
+      release_type: ${{ needs.determine-release-type.outputs.release_type }}
+      version: ${{ needs.update-version.outputs.version }}
+      is_esm: ${{ needs.determine-release-type.outputs.is_esm == 'true' }}
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  # 4️⃣ Promote branch if this is a prerelease (alpha/beta)
+  promote-branch:
+    needs: [determine-release-type, publish-release]
+    if: ${{ needs.determine-release-type.outputs.release_type != 'latest' && needs.determine-release-type.outputs.release_type != 'skip' }}
+    uses: homebridge/.github/.github/workflows/promote-branch.yml@latest
+    with:
+      branch_name: ${{ needs.determine-release-type.outputs.branch_name }}
+      release_type: ${{ needs.determine-release-type.outputs.release_type }}
+      is_esm: ${{ needs.determine-release-type.outputs.is_esm == 'true' }}
     secrets:
-      npm_auth_token: ${{ secrets.npm_token }}
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  # 5️⃣ Notify if any previous job fails
+  workflow-failure:
+    if: ${{ failure() }}
+    needs: [determine-release-type, update-version, publish-release, promote-branch]
+    uses: homebridge/.github/.github/workflows/report-failure.yml@latest
+    with:
+      workflow_name: ${{ github.workflow }}
+      job_name: ${{ github.job }}
+      run_url: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
 
+  # 6️⃣ Post to Discord
   github-releases-to-discord:
     name: Discord Webhooks
-    needs: [build_and_test,publish]
-    if: ${{ github.repository == 'OpenWonderLabs/node-switchbot' }}
-    uses: OpenWonderLabs/.github/.github/workflows/discord-webhooks.yml@latest
+    needs: [determine-release-type, update-version, publish-release]
+    uses: homebridge/.github/.github/workflows/discord-webhooks.yml@latest
     with:
-      title: "Node-SwitchBot Release"
+      title: "Node-SwitchBot Module Release"
       description: |
-        Version `v${{ needs.publish.outputs.NPM_VERSION }}`
-      url: "https://github.com/homebridge/camera-utils/releases/tag/v${{ needs.publish.outputs.NPM_VERSION }}"
+        Version `v${{ needs.update-version.outputs.version }}`
+      url: "https://github.com/OpenWonderLabs/node-switchbot/releases/tag/v${{ needs.update-version.outputs.version }}"
     secrets:
       DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK_URL_LATEST }}