Skip to content

Commit effb0d1

Browse files
donavanbeckerdonavanbecker
authored
✨ Set up Copilot instructions for homebridge-august repository (#157)
2 parents 764ba70 + a59e37f commit effb0d1

File tree

1 file changed

+223
-0
lines changed

1 file changed

+223
-0
lines changed

‎.copilot/instructions.md‎

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
# Copilot Instructions for Homebridge August Plugin
2+
3+
## Repository Overview
4+
5+
This is a Homebridge plugin that provides HomeKit integration for August and Yale smart locks. The plugin is written in TypeScript with ES modules and follows Homebridge platform patterns.
6+
7+
## Architecture
8+
9+
- **Plugin Type**: Homebridge dynamic platform plugin
10+
- **Language**: TypeScript with ES modules (ES2022)
11+
- **Runtime**: Node.js 20+ or 22+
12+
- **Build System**: TypeScript compiler (tsc) with bundler module resolution
13+
- **Testing**: Vitest with coverage support
14+
- **Linting**: ESLint with Antfu config and custom rules
15+
- **Documentation**: TypeDoc with modern theme
16+
- **External API**: august-yale package for August/Yale API communication
17+
18+
## Key Files and Directories
19+
20+
- `src/` - TypeScript source code
21+
- `index.ts` - Plugin entry point that registers the platform
22+
- `platform.ts` - Main platform class (AugustPlatform)
23+
- `settings.ts` - Configuration interfaces and constants
24+
- `devices/` - Device-specific implementations
25+
- `lock.ts` - Lock mechanism implementation
26+
- `device.ts` - Base device class
27+
- `homebridge-ui/` - Custom UI for Homebridge Config UI X
28+
- `*.test.ts` - Test files (Vitest)
29+
- `dist/` - Compiled JavaScript output (generated, excluded from git)
30+
- `config.schema.json` - Homebridge configuration schema with custom UI
31+
- `package.json` - Dependencies and npm scripts
32+
- `tsconfig.json` - TypeScript configuration (ES2022, bundler resolution)
33+
- `eslint.config.js` - ESLint configuration with Antfu base and custom rules
34+
35+
## Development Workflow
36+
37+
### Building
38+
```bash
39+
npm run build # Full build: clean + compile + copy UI files
40+
npm run clean # Remove dist directory
41+
npm run watch # Build + link + watch with nodemon
42+
```
43+
44+
### Testing
45+
```bash
46+
npm test # Run Vitest tests once
47+
npm run test:watch # Run tests in watch mode
48+
npm run test-coverage # Run tests with coverage report
49+
```
50+
51+
### Linting
52+
```bash
53+
npm run lint # Check for ESLint issues
54+
npm run lint:fix # Auto-fix ESLint issues
55+
```
56+
57+
### Documentation
58+
```bash
59+
npm run docs # Generate TypeDoc documentation
60+
npm run docs:lint # Validate documentation (treat warnings as errors)
61+
npm run docs:theme # Generate docs with default-modern theme
62+
```
63+
64+
### Development Setup
65+
```bash
66+
npm run watch # Start development with hot reload
67+
npm run plugin-ui # Copy UI files to dist
68+
```
69+
70+
## Coding Standards
71+
72+
1. **TypeScript**:
73+
- ES2022 target with bundler module resolution
74+
- Strict mode enabled (except noImplicitAny: false)
75+
- Use ES modules with `.js` file extensions in imports
76+
- Generate declaration files and source maps
77+
78+
2. **ESLint**:
79+
- Antfu ESLint config as base
80+
- Custom rules for import ordering (perfectionist)
81+
- JSDoc alignment enforcement
82+
- Multi-line curly braces only
83+
- Consistent quote props
84+
- Test-specific rules (no-only-tests)
85+
86+
3. **Code Style**:
87+
- Use 1TBS brace style with single line allowed
88+
- Sort imports by type (builtin, external, internal, relative)
89+
- Sort named imports and exports
90+
- Use proper JSDoc formatting and alignment
91+
92+
4. **Homebridge Patterns**:
93+
- Implement DynamicPlatformPlugin interface
94+
- Use proper platform registration in index.ts
95+
- Follow accessory lifecycle management
96+
- Implement proper logging with Homebridge logger
97+
- Use PlatformAccessory for device management
98+
99+
5. **Error Handling**:
100+
- Proper try-catch blocks for async operations
101+
- Meaningful error messages with context
102+
- Graceful degradation for API failures
103+
104+
## Homebridge Specifics
105+
106+
- **Platform Type**: Dynamic platform plugin (not accessory plugin)
107+
- **Platform Name**: "August" (defined in settings.ts)
108+
- **Plugin Name**: "homebridge-august" (must match package.json name)
109+
- **Configuration Schema**: Uses config.schema.json with custom UI
110+
- **Custom UI**: Located in src/homebridge-ui/ with custom configuration interface
111+
- **Platform Class**: AugustPlatform extends DynamicPlatformPlugin
112+
- **Device Management**: Uses PlatformAccessory for caching and state management
113+
- **HAP Services**: Implement LockMechanism service for smart locks
114+
- **Authentication**: Handle August API authentication with validation codes
115+
- **Rate Limiting**: Implement proper refresh/update/push rates for API calls
116+
117+
## August/Yale Integration
118+
119+
- **API Package**: Uses `august-yale` npm package for API communication
120+
- **Authentication Flow**:
121+
1. User provides augustId (email/phone) and password
122+
2. System sends validation code to user
123+
3. User enters validation code to complete authentication
124+
4. API credentials are stored and used for subsequent requests
125+
- **Device Types**: Support multiple lock types (August Smart Lock, Yale Assure Lock variants)
126+
- **State Synchronization**: Keep HomeKit state in sync with August/Yale API
127+
- **Polling**: Implement configurable refresh rates for device state updates
128+
- **Configuration**: Use credentials interface for API authentication settings
129+
130+
## When Making Changes
131+
132+
1. **Dependencies**:
133+
- Only add well-maintained dependencies
134+
- Keep runtime dependencies minimal
135+
- Update package.json and package-lock.json properly
136+
- Consider bundle size impact
137+
138+
2. **Breaking Changes**:
139+
- Follow semantic versioning
140+
- Update CHANGELOG.md appropriately
141+
- Consider migration paths for users
142+
- Test with multiple Homebridge versions
143+
144+
3. **Configuration**:
145+
- Update config.schema.json for new options
146+
- Maintain backward compatibility
147+
- Add proper validation and defaults
148+
- Update TypeScript interfaces in settings.ts
149+
150+
4. **Documentation**:
151+
- Update README.md for user-facing changes
152+
- Add TSDoc comments for new APIs
153+
- Update TypeDoc comments for generated docs
154+
- Consider updating examples
155+
156+
5. **Testing**:
157+
- Add Vitest tests for new features
158+
- Mock external dependencies (August API)
159+
- Test error scenarios and edge cases
160+
- Maintain test coverage
161+
162+
6. **Compatibility**:
163+
- Support Node.js 20+ and 22+
164+
- Support Homebridge 1.9.0+ and 2.0.0+
165+
- Test with Config UI X integration
166+
- Verify ES module compatibility
167+
168+
## Common Patterns
169+
170+
- **RxJS**: Use reactive programming patterns where appropriate
171+
- **Async/Await**: Prefer async/await over Promise chains
172+
- **ES Modules**: Use ES module syntax with `.js` extensions in imports
173+
- **Interface Design**: Define clear TypeScript interfaces in settings.ts
174+
- **Error Handling**: Implement comprehensive error handling with meaningful messages
175+
- **Logging**: Use this.log with appropriate log levels (info, warn, error, debug)
176+
- **Device Lifecycle**: Implement proper setup/cleanup in platform methods
177+
- **Configuration Validation**: Validate user configuration and provide helpful error messages
178+
- **API Rate Limiting**: Respect August API rate limits with configurable intervals
179+
- **State Management**: Maintain device state consistency between API and HomeKit
180+
181+
## Important Constants and Settings
182+
183+
- **PLATFORM_NAME**: "August" (used in Homebridge registration)
184+
- **PLUGIN_NAME**: "homebridge-august" (must match package.json)
185+
- **Plugin Type**: "platform" (not accessory)
186+
- **Custom UI**: Enabled with path "./dist/homebridge-ui"
187+
- **Configuration**: Uses credentials and options interfaces
188+
- **Device Types**: Support for various August and Yale lock models
189+
190+
## Testing Guidelines
191+
192+
- **Framework**: Use Vitest for testing with TypeScript support
193+
- **Test Files**: Name test files with `.test.ts` extension in src/
194+
- **Coverage**: Aim for good test coverage, use `npm run test-coverage`
195+
- **Mocking**: Mock external dependencies, especially:
196+
- August/Yale API calls
197+
- Homebridge API interactions
198+
- File system operations
199+
- **Test Categories**:
200+
- Unit tests for individual functions and classes
201+
- Integration tests for platform initialization
202+
- Configuration validation tests
203+
- Error handling tests
204+
- **Test Data**: Use realistic test data that matches August API responses
205+
- **Async Testing**: Properly test async operations and promises
206+
- **CI/CD**: Ensure tests run in continuous integration pipeline
207+
208+
## Files to Avoid Modifying
209+
210+
- `dist/` directory (generated by TypeScript compilation)
211+
- `node_modules/` directory (managed by npm)
212+
- `docs/` directory (generated by TypeDoc)
213+
- `.git/` directory and git metadata
214+
- Files listed in `.gitignore`
215+
- `package-lock.json` (only modify through npm commands)
216+
217+
## Security Considerations
218+
219+
- **Credentials**: Never log or expose user credentials
220+
- **API Keys**: Handle August API credentials securely
221+
- **Validation**: Validate all user inputs
222+
- **Error Messages**: Don't expose sensitive information in error messages
223+
- **Storage**: Store credentials securely using Homebridge storage mechanisms

0 commit comments

Comments
 (0)