bahmcloud/bahmcloud_store
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 34 Wiki Activity

Add blueprint support and refresh documentation

Browse Source
This commit is contained in:
René Bachmann
2026-03-23 16:42:52 +01:00
parent 48f8ef6265
commit a55281938c
7 changed files with 415 additions and 227 deletions
Download Patch File Download Diff File Expand all files Collapse all files

222
README_DEVELOPER.md
View File

@@ -1,115 +1,159 @@
# Bahmcloud Store – Developer Documentation
# Bahmcloud Store - Developer Documentation
For contributors and maintainers.
## Architecture
## Project Scope
Repositories:
1) Installer Add-on (HAOS/Supervised) ```https://git.bahmcloud.de/bahmcloud/addons```
2) Core Integration ```https://git.bahmcloud.de/bahmcloud/bahmcloud_store```
3) Store Index (`store.yaml`) ```https://git.bahmcloud.de/bahmcloud/ha_store```
Bahmcloud Store is evolving from an integration-only store into a broader Home Assistant git-based content store.
### Integration Layout
Currently supported install categories:
custom_components/bahmcloud_store/
- __init__.py: setup, panel registration, schedule background after HA started
- core.py: index merge, enrichment, install/update/uninstall, backups, restore, caching
- providers.py: GitHub/GitLab/Gitea repo info + latest version helpers
- metadata.py: read bcs.yaml / hacs.json / hacs.yaml
- storage.py: persistent storage (installed, custom, repo cache, hacs cache)
- views.py: HTTP API endpoints
- update.py: UpdateEntity implementation
- repairs.py: (optional) Repairs flow for restart
- panel/: UI (panel.js, styles.css, etc.)
- manifest.json
- Integrations
- Blueprints
Planned categories:
- Templates
- Lovelace / dashboard designs
- Additional content types with category-specific install logic
## Repository Layout
Repositories related to the project:
1. Installer add-on:
`https://git.bahmcloud.de/bahmcloud/addons`
2. Core integration:
`https://git.bahmcloud.de/bahmcloud/bahmcloud_store`
3. Store index:
`https://git.bahmcloud.de/bahmcloud/ha_store`
## Integration Layout
`custom_components/bahmcloud_store/`
- `__init__.py`: setup, panel registration, delayed startup refresh, periodic refresh
- `core.py`: index merge, repo enrichment, install/update/uninstall, backup/restore, category-aware install groundwork
- `providers.py`: provider detection, latest version lookup, release notes, README fetching
- `metadata.py`: reads `bcs.yaml`, `hacs.json`, and `hacs.yaml`
- `storage.py`: persistent storage for installed repos, settings, caches
- `views.py`: HTTP API
- `update.py`: Home Assistant update entities
- `repairs.py`: restart-required repair flow
- `panel/`: active frontend panel
- `manifest.json`
## Runtime Model
- RepoItem (merged)
- Installed repos (storage)
- Repo cache (persisted enrichment)
- HACS meta cache (mapping owner/repo → name/description)
## Background
- Heavy work only after `homeassistant_started`
- Refresh: if index unchanged → installed-only refresh + schedule enrichment
- Opening a repo triggers `ensure_repo_details()` and persists to cache
## Providers
- GitHub: API/releases/tags/atom + raw readme
- GitLab: API releases/tags + raw readme
- Gitea: API releases/tags + raw readme
- Custom: API or HTTPS Request to your Git Provider
- `RepoItem`: merged repository model used by the UI and backend
- Installed repositories: persisted in Home Assistant storage
- Settings: persistent UI and behavior settings such as HACS enablement and pinned repositories
- Repo cache: provider and metadata enrichment cache
- HACS cache: display metadata cache for HACS integration repositories
## Metadata
- Prefer `bcs.yaml`, fallback `hacs.json` / `hacs.yaml`
- Populate name/description/category/author/maintainer
Metadata priority:
## HTTP API (excerpt)
1. `bcs.yaml`
2. `hacs.yaml`
3. `hacs.json`
Base: /api/bcs
Common fields:
- GET /api/bcs
- POST /api/bcs?action=refresh
- GET /api/bcs/readme?repo_id=...
- GET /api/bcs/versions?repo_id=...
- POST /api/bcs/install?repo_id=...&version=...
- POST /api/bcs/update?repo_id=...&version=...
- POST /api/bcs/uninstall?repo_id=...
- GET /api/bcs/backups?repo_id=...
- POST /api/bcs/restore?repo_id=...&backup_id=...
- (optional) POST/DELETE custom_repo
## Update Entities
- Unique id bcs:<repo_id>
- Compare installed ref vs latest ref
- Dispatcher signal on refresh/install/update
## Storage
- JSON in HA `.storage`
- async read/write helpers
- repo cache applied on startup
## Contributing to **BCS Official**
1) Add pull request to `https://git.bahmcloud.de/bahmcloud/ha_store` (with your integration added to) `store.yaml`)
2) Add entry:
```yaml
- name: Your Integration Name
url: https://your-git-hoster.com/your-org/your-repo
category: Category (actually only "Integrations" are supported)
name: Example Project
description: Short description
category: Integrations
author: Example Author
maintainer: Example Maintainer
```
3) (Recommended) Add `bcs.yaml` to your repo:
Category currently matters operationally:
- `Integrations` -> install from `custom_components/...`
- `Blueprint` / `Blueprints` -> install from `blueprints/...`
## Supported Install Categories
### Integrations
- Expected source layout: `custom_components/<domain>/manifest.json`
- Install target: `/config/custom_components/<domain>`
- Supports backup, restore, update entities, and restart-required flow
### Blueprints
- Expected source layout: `blueprints/...`
- Install target: `/config/blueprints/...`
- Initial support is focused on direct install and uninstall
- Category-aware groundwork is in place so future content types can use their own install strategies
## HTTP API
Base path: `/api/bcs`
- `GET /api/bcs`
- `POST /api/bcs?action=refresh`
- `GET /api/bcs/settings`
- `POST /api/bcs/settings`
- `GET /api/bcs/readme?repo_id=...`
- `GET /api/bcs/release_notes?repo_id=...&ref=...`
- `GET /api/bcs/versions?repo_id=...`
- `GET /api/bcs/repo?repo_id=...`
- `POST /api/bcs/install?repo_id=...&version=...`
- `POST /api/bcs/update?repo_id=...&version=...`
- `POST /api/bcs/uninstall?repo_id=...`
- `GET /api/bcs/backups?repo_id=...`
- `POST /api/bcs/restore?repo_id=...&backup_id=...`
- `POST /api/bcs/restart`
- `DELETE /api/bcs/custom_repo?id=...`
## Current UI Features
- Search, source filter, category filter, state filter, sorting
- HACS integration source toggle
- Pinned repositories
- README rendering
- Release notes rendering
- Version selection
- Backup restore UI for integrations
## Contributing to the Official Store Index
Add a repository to the BCS store index in `ha_store`.
Example index entry:
```yaml
name: Your Integration Name
description: One-liner for the store (optional, store information are also catched from git repository)
category: Integrations (actually only supported)
author: Your Name
maintainer: Your Handle
- name: Example Project
url: https://your-git-hoster.example/org/repo
category: Blueprint
```
4) Open PR; validation checks: reachable, has `custom_components/<domain>/manifest.json`, sensible metadata
5) Merge → appears in **BCS Official** after refresh
## Coding Guidelines
Recommended repository metadata:
- Async I/O, no blocking event loop
- Respect provider rate limits
- Clean logging around refresh/install/update/restore
- Keep UI responsive; throttle updates
```yaml
name: Example Project
description: One-line description
category: Blueprint
author: Example Author
maintainer: Example Maintainer
```
---
Validation should match the category:
## Planed Features
- Integrations: verify `custom_components/<domain>/manifest.json`
- Blueprints: verify `blueprints/...`
- Add Downloads and install for category "Dashboard"
- Add Downloads and install for category "Template"
- Add Downloads and install for category "Theme"
- Add Downloads and install for category "Blueprint"
-
## Design Direction
The long-term architecture should remain category-aware:
- category -> validation strategy
- category -> install target
- category -> backup / restore behavior
- category -> UI affordances
This is especially important before Templates and Lovelace support are added, because those should stay compatible with established HACS expectations where possible.