Skip to content

AGENTS.md

Latest commit

 

History

History
65 lines (47 loc) · 3.56 KB

AGENTS.md

File metadata and controls

65 lines (47 loc) · 3.56 KB

Repository Guidelines

Instructions

  • Always refer to home-assistant-js-websocket library for types and functions to interact with the Home Assistant API.
  • When interaction with Home Assistant API is needed, use custom-card-helpers library for helper utilities for the card lifecycle and events.

Project Structure & Module Organization

  • src/: TypeScript source for the custom Lovelace card (entry: src/purifier-card.ts).
  • dist/: Build output (bundled card JS). This is generated by Rollup.
  • rollup.config.mjs: Build pipeline and asset handling.
  • eslint.config.mjs: Lint configuration.
  • package.json: Scripts, dependencies, and release config.

Build, Test, and Development Commands

  • npm install: Install dependencies.
  • npm run start: Watch mode build (Rollup) for local development.
  • npm run build: Production bundle to dist/.
  • npm run lint: Run ESLint on src/.
  • npm run lint:fix: Auto-fix lint issues in src/.
  • npm run format: Format with Prettier (respects .prettier settings in package.json).
  • npm test: Runs lint then build (no separate test suite).

Coding Style & Naming Conventions

  • Language: TypeScript, ES modules ("type": "module").
  • Formatting: Prettier with single quotes ("singleQuote": true).
  • Linting: ESLint (see eslint.config.mjs) using @typescript-eslint and eslint-plugin-import.
  • Match existing patterns in src/ for file naming and exports; prefer descriptive, kebab-case filenames for components.

Technologies Used

  • UI is a Home Assistant Lovelace custom card implemented as a Web Component with Lit (LitElement, decorators, html templates).
  • Home Assistant integrations use custom-card-helpers for card lifecycle/events and home-assistant-js-websocket types for entities/services.
  • Template rendering uses ha-template for dynamic text in the card.
  • Localization is handled via JSON translation files in src/translations/ and the localize helper.
  • Build tooling is Rollup with TypeScript (rollup-plugin-typescript2), Babel transforms, and asset handling for JSON, images, CSS, and SVG.
  • Styling uses PostCSS (postcss-preset-env) and rollup-plugin-postcss-lit to process component CSS.
  • Production optimizations include HTML literal minification and Terser.
  • Utility helpers include Lodash (get).
  • Developer tooling includes ESLint, Prettier, Husky, and lint-staged.

Documentations

  • This card uses the custom-card-helpers library with helper utilities for the card lifecycle and events. Always refer to the documentation for useful functions and utilities.
  • Use the home-assistant-js-websocket library for types and functions to interact with the Home Assistant API.

Testing Guidelines

  • No dedicated test framework is configured.
  • Use npm test to validate linting and the production build.
  • Keep changes buildable; avoid introducing new build-time warnings.

Commit & Pull Request Guidelines

  • Commit messages follow Conventional Commits (Angular preset), e.g. feat: ..., fix: ..., chore(deps): ....
  • Dependency updates should use chore(deps): ... to align with release rules.
  • PRs should include: a concise description, what changed, and how it was validated (commands run). If UI changes are visible, include a screenshot or GIF.

Release & Automation Notes

  • Releases are handled by semantic-release on main with assets from dist/purifier-card.js.
  • Ensure build output remains stable when changing dependencies or build config.