chore: Add AGENTS.md (#22776)
This commit is contained in:
Michael Geers
GitHub
parent
9e4a63cc6b
commit
b27f2bc769
4 changed files with 247 additions and 124 deletions
1
.cursorrules
Symbolic link
1
.cursorrules
Symbolic link
|
|
@ -0,0 +1 @@
|
|||
AGENTS.md
|
||||
1
.github/copilot-instructions.md
vendored
Symbolic link
1
.github/copilot-instructions.md
vendored
Symbolic link
|
|
@ -0,0 +1 @@
|
|||
../AGENTS.md
|
||||
244
AGENTS.md
Normal file
244
AGENTS.md
Normal file
|
|
@ -0,0 +1,244 @@
|
|||
# Agent Rules for evcc Project
|
||||
|
||||
This file provides guidance to AI coding agents when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
- evcc is an extensible EV Charge Controller and home energy management system written in Go with a Vue.js frontend
|
||||
- The system manages electric vehicle charging, integrates with solar systems, and provides local energy management without cloud dependencies
|
||||
- Architecture follows a plugin-based approach for device integrations
|
||||
|
||||
## Essential Commands
|
||||
|
||||
- `make` - build full application (UI + Go binary)
|
||||
- `make build` - build Go binary only
|
||||
- `make ui` - build UI assets only
|
||||
- `make install` - install Go tools and dependencies
|
||||
- `make install-ui` - install Node.js dependencies (`npm ci`)
|
||||
- `make test` - run Go tests
|
||||
- `make test-ui` - run frontend tests
|
||||
- `make lint` - run Go linting (golangci-lint)
|
||||
- `make lint-ui` - run frontend linting
|
||||
- `npm run dev` - start Vue dev server (http://127.0.0.1:7071)
|
||||
- `npm run playwright` - run integration tests
|
||||
- `evcc --template-type [type] --template [file]` - test device templates
|
||||
- `make docs` - generate template documentation
|
||||
|
||||
## Architecture Guidelines
|
||||
|
||||
### Core Components
|
||||
|
||||
- **main.go** serves as entry point and embeds web assets and i18n files
|
||||
- **cmd/** contains CLI commands, application setup, and various utility commands (configure, detect, migrate, etc.)
|
||||
- **core/** contains core business logic with main files (loadpoint.go, site.go) and subdirectories:
|
||||
- **loadpoint/** - EV charging point management modules
|
||||
- **planner/** - Smart charging planning algorithms
|
||||
- **coordinator/** - Multi-loadpoint coordination logic
|
||||
- **session/** - Charging session management
|
||||
- **vehicle/** - Vehicle-specific core logic
|
||||
- **soc/** - State of charge handling
|
||||
- **api/** contains API definitions and types
|
||||
- **server/** handles HTTP server, WebSocket, MQTT, database operations, and various handlers
|
||||
- **charger/**, **meter/**, **vehicle/** contain device integrations
|
||||
- **tariff/** contains tariff integrations
|
||||
- **plugin/** implements plugin system for device and tariff communication
|
||||
- **assets/** contains Vue.js frontend application
|
||||
|
||||
### Frontend Structure
|
||||
|
||||
- **assets/js/** contains the main TypeScript/Vue.js application with:
|
||||
- **views/** - Vue page components (App.vue, Config.vue, Sessions.vue, etc.)
|
||||
- **components/** - Reusable Vue components
|
||||
- **composables/** - Vue utility functions
|
||||
- **types/** - TypeScript type definitions
|
||||
- **utils/** - Utility functions
|
||||
- **mixins/** - Vue mixins
|
||||
- **assets/css/** contains application stylesheets
|
||||
- **assets/public/** contains static assets and metadata
|
||||
- **i18n/** contains internationalization files
|
||||
- **tests/** contains Playwright integration tests and test configuration files
|
||||
- **dist/** contains built frontend assets (generated)
|
||||
|
||||
## Go Coding Standards
|
||||
|
||||
### Core Principles
|
||||
|
||||
- Follow Go idioms and conventions (Effective Go)
|
||||
- Use `gofmt` for formatting, self-documenting names, early returns
|
||||
- Handle all errors explicitly with meaningful messages
|
||||
- Use interfaces for behavior contracts (small, focused, single responsibility)
|
||||
- Use `context.Context` for I/O, long-running, or cancelable operations
|
||||
- Organize code into logical packages with clear responsibilities
|
||||
- Prefer composition over inheritance, minimize external dependencies
|
||||
|
||||
### File Patterns
|
||||
|
||||
- `_blueprint.go` - templates for new device implementations
|
||||
- `_enumer.go` - generated enum code
|
||||
- `*_decorators.go` - generated decorator pattern implementations
|
||||
- Validate interface implementations: `var _ Interface = (*Type)(nil)`
|
||||
|
||||
### Error Handling
|
||||
|
||||
- Wrap errors with context: `fmt.Errorf("context: %w", err)`
|
||||
- Use `errors.As` and `errors.Is` for type checking
|
||||
- Use `errors.Join` for combining errors (prefer custom `joinErrors` helper)
|
||||
- Create domain-specific error types (ClassError, DeviceError)
|
||||
- Use `backoff.Permanent(err)` for non-retryable errors
|
||||
- Implement panic recovery with `defer` and `recover()` in script contexts
|
||||
|
||||
### Testing & Code Generation
|
||||
|
||||
- Use `testing` package with `testify/assert` and `testify/require`
|
||||
- Table-driven tests with struct definitions for multiple cases
|
||||
- Use `gomock` for interface mocking, `go:generate mockgen` for generation
|
||||
- Test both success and failure scenarios, use `require` for setup, `assert` for tests
|
||||
- Use `go:generate` for code generation, regenerate after interface/enum changes
|
||||
- Never manually edit generated files
|
||||
|
||||
### Context & Concurrency
|
||||
|
||||
- Use `context.Context` as first parameter for I/O operations
|
||||
- Use `context.WithTimeout`, `context.WithCancel` appropriately
|
||||
- Check `ctx.Done()` in long-running loops
|
||||
- Propagate context through goroutines for proper cancellation
|
||||
- Handle concurrent operations safely with Go's concurrency primitives
|
||||
|
||||
### Data Validation
|
||||
|
||||
- Filter `NaN` and `Infinity` values using `math.IsNaN()` and `math.IsInf()`
|
||||
- Validate numeric inputs from external sources
|
||||
- Use helper functions like `parseFloat()` that reject invalid values
|
||||
|
||||
## Vue.js/TypeScript Frontend Standards
|
||||
|
||||
### Core Architecture
|
||||
|
||||
- Use Vue 3 Options API (preferred over Composition API)
|
||||
- Use reactive stores without Vuex/Pinia for cross-component state
|
||||
- Use global app instance (`window.app`) only for: notifications (`raise()`), offline status (`setOffline()`/`setOnline()`), clearing notifications (`clear()`)
|
||||
- Organize components by feature/domain in `assets/js/components/` subdirectories
|
||||
|
||||
### Component Development
|
||||
|
||||
- Use TypeScript for all new frontend code
|
||||
- Use `const` instead of `function` for component methods (e.g., `const updateType = () =>`)
|
||||
- Define TypeScript interfaces for component props, data, and API responses
|
||||
- Implement accessibility features (tabindex, aria-label, keyboard handlers)
|
||||
- Use descriptive names for variables, functions, and event handlers
|
||||
- Use early returns for readability
|
||||
- Use configured Axios instance for HTTP communication
|
||||
|
||||
### State Management
|
||||
|
||||
- Use `reactive()` from Vue for simple global state
|
||||
- Implement property setters for nested object updates using helper functions
|
||||
- Use localStorage with reactive wrappers for persistent settings
|
||||
- Use Vue `watch()` for automatic persistence of settings changes
|
||||
- Separate concerns with dedicated stores (settings, application state)
|
||||
|
||||
### TypeScript Patterns
|
||||
|
||||
- Define comprehensive interfaces for API responses and application state
|
||||
- Use enums for constants (e.g., `THEME`, `CURRENCY`)
|
||||
- Extend global interfaces for window object augmentation
|
||||
- Use union types for flexible but type-safe configurations
|
||||
- Use generic types for reusable utility functions
|
||||
- Handle type assertions carefully with proper error handling
|
||||
- Create focused utility functions with proper TypeScript typing
|
||||
|
||||
### Styling & Internationalization
|
||||
|
||||
- Use CSS Custom Properties for theming (semantic names: `--evcc-green`, `--evcc-battery`)
|
||||
- Use existing custom media queries for responsive breakpoints
|
||||
- Use `$t()` function for all user-facing strings
|
||||
- Update both `i18n/en.json` and `i18n/de.json` for new strings
|
||||
- Use hierarchical namespace: `{section}.{component}.{purpose}`
|
||||
- Examples: `config.vehicle.titleAdd`, `main.vehicleStatus.charging`
|
||||
- Action patterns: `titleAdd`, `titleEdit`, `save`, `cancel`, `delete`, `validateSave`
|
||||
- Use placeholders for dynamic content: `{soc}`, `{duration}`, `{value}`
|
||||
- Prefer context-specific keys over generic ones
|
||||
- Test with German translations (20-40% longer text)
|
||||
|
||||
### Testing
|
||||
|
||||
- Write integration tests using Playwright for user workflows
|
||||
- Use Storybook for component development and visual testing
|
||||
- Use semantic selectors (roles, labels, button text); `data-testid` only when necessary
|
||||
- Test error states and loading states
|
||||
|
||||
## Playwright Integration Testing
|
||||
|
||||
### Test Organization
|
||||
|
||||
- **Location**: `tests/` directory with `.spec.ts` files
|
||||
- **Configuration**: `.evcc.yaml` files for different test scenarios
|
||||
- **Utilities**: `tests/utils.ts` for common helpers, `tests/evcc.ts` for binary management
|
||||
- **Categories**: `config-*.spec.ts` (UI config), `sessions.spec.ts`/`plan.spec.ts` (workflows), `smart-cost.spec.ts`/`limits.spec.ts` (features), `backup-restore.spec.ts`/`auth.spec.ts` (integration)
|
||||
|
||||
### Test Configuration
|
||||
|
||||
- Base URL: `http://127.0.0.1:7070`
|
||||
- Parallel execution with different ports per worker for isolation
|
||||
- Uses `./evcc` binary with test-specific configuration files
|
||||
- Each worker uses isolated temporary database files
|
||||
- Always runs with English UI language
|
||||
|
||||
### Essential Commands
|
||||
|
||||
- Must build before testing: `make ui build`
|
||||
- Run tests: `npm run playwright` or `npx playwright test`
|
||||
- Debug: `npx playwright test --debug`
|
||||
- Specific test: `npx playwright test tests/config-loadpoint.spec.ts`
|
||||
|
||||
### Selector Strategy
|
||||
|
||||
- **Preferred**: Semantic selectors using `getByRole()`, `getByLabel()`, `getByText()`
|
||||
- **Fallback**: `data-testid` only when semantic selectors aren't available
|
||||
- **Examples**:
|
||||
- `page.getByRole("button", { name: "Add charger" })`
|
||||
- `page.getByLabel("Manufacturer").selectOption("Demo charger")`
|
||||
- `page.getByTestId("loadpoint")` (fallback only)
|
||||
|
||||
### Test Patterns
|
||||
|
||||
- Use test-specific `.evcc.yaml` configurations
|
||||
- Import utilities from `tests/utils.ts` for common operations
|
||||
- Focus on complete user journeys rather than isolated interactions
|
||||
- Use `expectModalVisible()` and `expectModalHidden()` helpers
|
||||
- Test configuration persistence across application restarts
|
||||
- Standard structure: import `{ start, stop, baseUrl }` from `./evcc`, use `test.afterEach(stop)`
|
||||
|
||||
## Device Integration & Configuration
|
||||
|
||||
### Plugin System
|
||||
|
||||
- Device types: chargers, meters, vehicles, tariffs
|
||||
- Plugin protocols: Modbus, HTTP, MQTT, JavaScript, Go
|
||||
- Define device capabilities and configuration in templates at `templates/definition/[type]/`
|
||||
- Test templates: `evcc --template-type [type] --template [file]`
|
||||
- Update docs after template changes: `make docs`
|
||||
|
||||
### Configuration
|
||||
|
||||
- Use YAML format for all configuration files (default: `evcc.yaml`, or specify with `--config`)
|
||||
- Provide clear validation and error messages for invalid configurations
|
||||
- Support template-based device configurations with meaningful defaults
|
||||
- Use SQLite as default database (default: `evcc.db`, or specify with `--database`) with proper migrations and data integrity
|
||||
|
||||
## Security & Performance Guidelines
|
||||
|
||||
### Security
|
||||
|
||||
- Validate all user inputs and sanitize data before database storage
|
||||
- Use secure protocols (TLS) for external integrations
|
||||
- Implement proper authentication and authorization
|
||||
- Never log sensitive information (passwords, tokens, personal data)
|
||||
|
||||
### Performance
|
||||
|
||||
- Optimize database queries with appropriate indexes
|
||||
- Handle concurrent operations safely with Go's concurrency primitives
|
||||
- Implement proper caching strategies and connection pooling
|
||||
- Avoid blocking operations in main application loop
|
||||
- Include appropriate comments for complex business logic
|
||||
124
CLAUDE.md
124
CLAUDE.md
|
|
@ -1,124 +0,0 @@
|
|||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
evcc is an extensible EV Charge Controller and home energy management system written in Go with a Vue.js frontend. It manages electric vehicle charging, integrates with solar systems, and provides local energy management without cloud dependencies.
|
||||
|
||||
## Core Development Commands
|
||||
|
||||
### Build & Development
|
||||
|
||||
- `make` - Build the full application (UI + Go binary)
|
||||
- `make build` - Build Go binary only
|
||||
- `make ui` - Build UI assets only
|
||||
- `go run ./...` - Run without building binary
|
||||
- `./evcc` - Run the built binary
|
||||
- `./evcc --demo` - Run with demo configuration
|
||||
|
||||
### Dependencies
|
||||
|
||||
- `make install` - Install Go tools and dependencies
|
||||
- `make install-ui` - Install Node.js dependencies (`npm ci`)
|
||||
|
||||
### Testing & Quality
|
||||
|
||||
- `make test` - Run Go tests
|
||||
- `make test-ui` - Run frontend tests (`npm test`)
|
||||
- `make lint` - Run Go linting (golangci-lint)
|
||||
- `make lint-ui` - Run frontend linting (Prettier, ESLint, TypeScript)
|
||||
|
||||
### Frontend Development
|
||||
|
||||
- `npm run dev` - Start Vue dev server (http://127.0.0.1:7071)
|
||||
- `npm run storybook` - Run Storybook (http://127.0.0.1:6006)
|
||||
- `npm run playwright` - Run integration tests
|
||||
- `npm run simulator` - Run device simulator (http://localhost:7072)
|
||||
|
||||
### Device Templates
|
||||
|
||||
- `evcc --template-type charger --template new-charger-template.yaml` - Test device templates
|
||||
- `make docs` - Generate template documentation
|
||||
|
||||
## Architecture
|
||||
|
||||
### Core Components
|
||||
|
||||
- **main.go** - Entry point, embeds web assets and i18n files
|
||||
- **cmd/** - CLI commands and application setup
|
||||
- **core/** - Core business logic:
|
||||
- **loadpoint.go** - EV charging point management
|
||||
- **site.go** - Site-wide energy management
|
||||
- **planner/** - Smart charging planning
|
||||
- **coordinator/** - Multi-loadpoint coordination
|
||||
- **api/** - API definitions and types
|
||||
- **server/** - HTTP server, WebSocket, MQTT, and database
|
||||
- **charger/**, **meter/**, **vehicle/** - Device integrations
|
||||
- **tariff/** - Tariff integrations
|
||||
- **plugin/** - Plugin system for device and tariff communication
|
||||
- **assets/** - Vue.js frontend application
|
||||
|
||||
### Frontend Structure
|
||||
|
||||
- **assets/js/** - TypeScript/Vue.js application
|
||||
- **assets/views/** - Vue components and pages
|
||||
- **i18n/** - Internationalization files
|
||||
- **dist/** - Built frontend assets (generated)
|
||||
|
||||
### Configuration
|
||||
|
||||
- Uses YAML configuration files
|
||||
- Templates in `templates/definition/` for device and tariff configurations
|
||||
- Database: SQLite (default: `evcc.db`)
|
||||
|
||||
## Key Development Patterns
|
||||
|
||||
### Device Integration
|
||||
|
||||
- Device types: chargers, meters, vehicles (and tariffs)
|
||||
- Plugin system supports: Modbus, HTTP, MQTT, JavaScript, Go
|
||||
- Templates define device capabilities and configuration
|
||||
- Use `_blueprint.go` as starting point for new Go implementations
|
||||
|
||||
### Testing
|
||||
|
||||
- Go tests use standard `testing` package
|
||||
- Frontend tests use Vitest
|
||||
- Integration tests use Playwright
|
||||
- Simulator available for testing without real devices
|
||||
|
||||
### Internationalization
|
||||
|
||||
- Translations managed via Weblate
|
||||
- Update both `i18n/de.json` and `i18n/en.json` for new strings
|
||||
- Use `$t()` function in Vue components
|
||||
|
||||
## Important File Locations
|
||||
|
||||
- Configuration: `evcc.yaml` (or specified with `--config`)
|
||||
- Database: `evcc.db` (or specified with `--database`)
|
||||
- Device templates: `templates/definition/`
|
||||
- Web assets: `assets/` (source), `dist/` (built)
|
||||
- Generated code: Files ending in `_enumer.go`, `*_decorators.go`
|
||||
|
||||
## Common Development Workflows
|
||||
|
||||
### Adding New Device Support
|
||||
|
||||
1. Create template in `templates/definition/[type]/`
|
||||
2. If Go code needed, implement in respective package
|
||||
3. Test with `evcc --template-type [type] --template [file]`
|
||||
4. Run `make docs` to update documentation
|
||||
|
||||
### Frontend Development
|
||||
|
||||
1. Start backend: `make build && ./evcc`
|
||||
2. Start frontend dev server: `npm run dev`
|
||||
3. Access development UI at http://127.0.0.1:7071
|
||||
|
||||
### Integration Testing
|
||||
|
||||
1. Build application: `make ui build`
|
||||
2. Run tests: `npm run playwright`
|
||||
3. Use simulator for device testing: `npm run simulator`
|
||||
1
CLAUDE.md
Symbolic link
1
CLAUDE.md
Symbolic link
|
|
@ -0,0 +1 @@
|
|||
AGENTS.md
|
||||
Loading…
Add table
Add a link
Reference in a new issue