Skip to content

copilot-instructions.md

Latest commit

 

History

History
165 lines (137 loc) · 8.11 KB

copilot-instructions.md

File metadata and controls

165 lines (137 loc) · 8.11 KB
Raw

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: 
    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)

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