Skip to content

Commit dd30207

Browse files
CopilotApollon77
Copilot
and
Apollon77
authored
✨ Add Copilot instructions for create-adapter repository (#1150)
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Apollon77 <11976694+Apollon77@users.noreply.github.com> Co-authored-by: Ingo Fischer <github@fischer-ka.de>
1 parent 34bb4b1 commit dd30207

1 file changed

Lines changed: 147 additions & 0 deletions

File tree

‎.copilot-instructions.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# ioBroker Create-Adapter - Copilot Instructions
2+
3+
## Project Overview
4+
5+
This is a CLI tool for generating customized ioBroker adapter projects. It's a scaffolding utility that uses a template-based system to create complete adapter directories with all necessary files based on user preferences.
6+
7+
**ioBroker Context**: ioBroker is a home automation platform, and adapters are plugins that connect various devices, services, and protocols to the platform. This tool helps developers quickly scaffold new adapters with modern development practices and standardized structure.
8+
9+
## Key Concepts
10+
11+
### Template System
12+
- **Template Functions**: Located in `/templates/`, these are TypeScript files that export a `TemplateFunction`
13+
- **Answers Object**: User input flows through the system as an `Answers` object containing all configuration choices
14+
- **File Generation**: Templates generate file content based on user answers and are written to target directories
15+
16+
### Core Architecture
17+
```typescript
18+
// Template function signature
19+
type TemplateFunction = (answers: Answers) => string | Promise<string> | undefined;
20+
21+
// Templates can have custom properties
22+
templateFunction.customPath = "custom/file/path";
23+
templateFunction.noReformat = true; // Skip automatic formatting
24+
```
25+
26+
### User Interaction Flow
27+
1. CLI prompts collect user preferences into `Answers` object using `enquirer`
28+
2. Validation ensures required fields are provided and constraints are met
29+
3. Templates process answers to generate file content conditionally
30+
4. Files are written to target directory with proper formatting via Prettier
31+
5. Dependencies are optionally installed and initial build performed
32+
6. Git repository is optionally initialized with initial commit
33+
34+
### Error Handling Patterns
35+
- Use descriptive error messages for user-facing CLI errors
36+
- Validate user input early in the process before template generation
37+
- Handle network failures gracefully (package version fetching)
38+
- Provide fallback behavior when optional operations fail
39+
40+
## Development Patterns
41+
42+
### Template Development
43+
- Template files end in `.ts` and export a function as the default export
44+
- Use conditional logic to return `undefined` when template shouldn't be generated
45+
- Access user answers through the `answers` parameter
46+
- Use template literals for multi-line content
47+
48+
```typescript
49+
export = (answers => {
50+
if (!answers.someFeature) return; // Skip if feature not selected
51+
52+
const template = `
53+
// Generated content based on ${answers.someProperty}
54+
`;
55+
return template.trim();
56+
}) as TemplateFunction;
57+
```
58+
59+
### Answer Object Structure
60+
Key properties commonly used in templates:
61+
- `answers.adapterName` - The adapter name
62+
- `answers.authorName` - Author's full name
63+
- `answers.authorGithub` - GitHub username
64+
- `answers.features` - Array of selected features
65+
- `answers.language` - "TypeScript" or "JavaScript"
66+
- `answers.adminUi` - Admin UI type ("html", "react", "json", "none")
67+
- `answers.indentation` - "Tab" or "Space (4)"
68+
- `answers.quotes` - "double" or "single"
69+
- `answers.es6class` - Whether to use ES6 classes
70+
71+
### Testing Patterns
72+
- **Baseline Tests**: Generate complete adapter directories and compare with stored baselines
73+
- **Unit Tests**: Test individual functions and utilities
74+
- **Template Tests**: Verify templates generate expected content for different answer combinations
75+
76+
### File Path Conventions
77+
- Source files: `/src/`
78+
- Templates: `/templates/`
79+
- Build output: `/build/`
80+
- Test baselines: `/test/baselines/`
81+
82+
### Code Style
83+
- TypeScript throughout the codebase
84+
- ESLint + Prettier for formatting
85+
- Prefer explicit types over `any`
86+
- Use `async/await` over Promises
87+
- Follow existing naming conventions
88+
89+
## Common Operations
90+
91+
### Adding a New Template
92+
1. Create `.ts` file in appropriate `/templates/` subdirectory
93+
2. Export a `TemplateFunction` that processes answers
94+
3. Set `customPath` property if output path differs from template path
95+
4. Add conditional logic to return `undefined` when not needed
96+
5. Test with relevant answer combinations
97+
98+
### Modifying Existing Templates
99+
1. Understand what answers control the template
100+
2. Maintain backward compatibility with existing answer structures
101+
3. Test changes against baseline test suite
102+
4. Update baseline files if behavior change is intentional
103+
104+
### Testing Changes
105+
```bash
106+
npm test # Run all tests
107+
npm run test:ts # Unit tests only
108+
npm run test:baselines # Baseline generation tests
109+
npm run build # Rebuild templates
110+
```
111+
112+
### Debugging Template Generation
113+
- Use `console.log` in templates to debug answer processing
114+
- Check baseline test outputs in `/test/baselines/`
115+
- Run single test cases to isolate issues
116+
117+
## File Generation Process
118+
119+
1. **Preprocessing**: Link templates, cache licenses
120+
2. **Question Flow**: Collect user answers via CLI prompts
121+
3. **Template Processing**: Each template function receives answers object
122+
4. **File Writing**: Generated content written to target directory
123+
5. **Post-processing**: Install dependencies, run build steps if requested
124+
125+
## Migration and Compatibility
126+
127+
- The tool supports migrating existing adapters via `--migrate` flag
128+
- Answer format is preserved in `.create-adapter.json` for replay functionality
129+
- Backward compatibility is maintained for existing answer structures
130+
131+
## Important Notes
132+
133+
- Templates are compiled from TypeScript to JavaScript during build
134+
- Raw files (`.raw.*` extensions) are copied without processing
135+
- Formatting is automatically applied unless `noReformat: true` is set
136+
- Git initialization is optional and controlled by user answers
137+
- All file paths should use forward slashes for cross-platform compatibility
138+
139+
## Getting Started with Development
140+
141+
1. Install dependencies: `npm install`
142+
2. Build project: `npm run build`
143+
3. Run tests: `npm test`
144+
4. Watch for changes: `npm run watch`
145+
5. Test CLI locally: `npm link` then `create-adapter`
146+
147+
This tool is actively maintained and used by the ioBroker community to create hundreds of adapters. Changes should be thoroughly tested and maintain backward compatibility.

0 commit comments

Comments
 (0)