Commandes workspace

Le dépôt expose un package.json à la racine pour piloter l'ensemble des actions (Buildroot OS, domotic local, central de supervision, docserver) depuis un point unique.

Principe

Depuis la racine du projet :

npm run <commande>

Si vous êtes dans un autre dossier, utilisez un préfixe absolu :

npm --prefix /var/workspaces/supervisor/apps/leukOS run <commande>

Aide rapide

npm run help

Commandes OS (Buildroot)

Commande	Rôle
npm run os:deps	Vérifie les dépendances hôte requises pour Buildroot.
npm run os:fetch	Télécharge Buildroot.
npm run os:config	Applique le defconfig par défaut.
npm run os:menuconfig	Ouvre menuconfig Buildroot.
npm run os:boards	Liste les defconfigs disponibles.
npm run os:build	Compile l'image OS (defconfig par défaut).
npm run os:build:rpi02w	Build pour Raspberry Pi Zero 2 W.
npm run os:build:rpi3bplus	Build pour Raspberry Pi 3 B+.
npm run os:build:rpi4	Build pour Raspberry Pi 4.
npm run os:build:rpi5	Build pour Raspberry Pi 5.
npm run os:build:intel-nuc	Build pour Intel NUC.
npm run os:build:amd64	Build pour x86-64.
npm run os:build:arm64	Build pour ARM64 générique.
npm run os:clean	Nettoyage partiel (target/images, conserve la toolchain).
npm run os:clean:all	Nettoyage complet (.build).

Commandes Domotic local (domotic/hub)

Commande	Rôle
npm run hub:run	Lance le hub avec config.yaml.
npm run hub:run:os	Lance le hub avec config.os.yaml.
npm run hub:build	Compile le binaire bin/leukos-hub.
npm run hub:test	Exécute les tests Go.
npm run hub:tidy	Nettoie/maj go.mod et go.sum.

:::info Prérequis Go Les commandes domotic locales nécessitent Go installé sur la machine (sinon go: not found). :::

Vérification Home Assistant MQTT Discovery

Un script de vérification rapide est disponible pour valider que le hub publie bien l'availability et les payloads MQTT Discovery:

cd /var/workspaces/supervisor/apps/leukOS/domotic/hub
./scripts/verify-ha-discovery.sh

Variables optionnelles:

BROKER_HOST=127.0.0.1 \
BROKER_PORT=1883 \
DISCOVERY_PREFIX=homeassistant \
BASE_TOPIC=leukos \
WAIT_SECONDS=8 \
./scripts/verify-ha-discovery.sh

Prérequis système: mosquitto_sub (et mosquitto_pub pour le test optionnel), timeout.

Historique persistent de republication Discovery

Le hub persiste désormais chaque tentative de homeassistant.republish_discovery dans storage_dir/republish_history.json (succès et erreurs).

Lecture via API hub:

curl http://localhost:8123/api/homeassistant/republish-history

Filtrage/pagination:

curl "http://localhost:8123/api/homeassistant/republish-history?status=error&limit=50&offset=0"

curl "http://localhost:8123/api/homeassistant/republish-history?status=success&q=admin&from=2026-08-01&to=2026-08-20&limit=50&offset=0"

Réponse:

• items: entrées triées de la plus récente à la plus ancienne.
• total: nombre total d'entrées correspondant au filtre.
• limit, offset: fenêtre courante.

Chaque entrée contient at, status, message, actor, source, remote_addr.

Intégrité anti-altération:

• prev_hash et hash sont calculés côté hub pour chaîner les entrées.
• L'API vérifie la chaîne avant lecture/export et renvoie 409 si incohérence.
• En complément, un journal append-only immuable est maintenu dans storage_dir/republish_history.audit.jsonl (une ligne JSON par événement, jamais réécrit).

Filtres supportés:

• status: success, error, blocked
• q: recherche texte (message, actor, source, remote_addr)
• from, to: bornes temporelles (RFC3339 ou YYYY-MM-DD)
• limit, offset: pagination

Accès:

• endpoint réservé au rôle admin quand l'auth est activée (403 sinon).

Export serveur signé:

curl -OJ "http://localhost:8123/api/homeassistant/republish-history/export?format=json&limit=100"
curl -OJ "http://localhost:8123/api/homeassistant/republish-history/export.sha256?format=json&limit=100"

Formats: json ou csv.

Le endpoint export inclut aussi l'en-tête X-Content-SHA256.

Contrôle d'intégrité:

curl http://localhost:8123/api/homeassistant/republish-history/integrity

Réponse:

• mutable_ok: cohérence du snapshot JSON principal.
• immutable_ok: cohérence de la chaîne append-only.
• immutable_entries: nombre d'entrées vérifiées.

Console Ops (UI)

Le frontend expose une vue dédiée d'audit: /ops/republish-history.

Fonctions:

• filtres status/date/recherche,
• pagination (Charger plus),
• export JSON/CSV,
• export JSON/CSV signé côté serveur (.sha256) pour audit.

Commandes UI Domotic (domotic/web)

Commande	Rôle
npm run web:install	Installe les dépendances npm du frontend.
npm run web:dev	Lance Vite en mode développement.
npm run web:build	Build de production du frontend.
npm run web:preview	Prévisualise le build web.

Commandes Central (central)

Commande	Rôle
npm run central:up	Démarre la stack centrale (saturn, venus, mercure, kafka, web, CoreDNS) connectée à PostgreSQL/Elasticsearch externes.
npm run central:down	Arrête la stack centrale.
npm run central:logs	Affiche les logs de la stack centrale.
npm run central:ps	Affiche l'état des services centraux.
npm run central:web:install	Installe les dépendances npm du frontend central.
npm run central:web:dev	Lance le frontend central en dev.
npm run central:web:build	Build de production du frontend central.

Commandes Docker projet

Ces commandes pilotent la stack Docker du projet via scripts/docker-project.sh (compose central + override dev). Par défaut elles s'appliquent à tous les services.

Commande	Rôle
npm run docker:up	Démarre tous les conteneurs.
npm run docker:create	Crée les conteneurs sans les démarrer.
npm run docker:recreate	Recrée et démarre les conteneurs (--force-recreate).
npm run docker:stop	Stoppe les conteneurs.
npm run docker:down	Supprime tous les conteneurs de la stack.
npm run docker:dow	Alias de docker:down.

Application à un service précis:

npm run docker:up -- saturn
npm run docker:create -- venus-web
npm run docker:recreate -- saturn
npm run docker:stop -- saturn
npm run docker:down -- saturn

Sans paramètre, l'action s'applique à toute la stack du projet.

Commandes Config centralisée (config/)

Commande	Rôle
npm run config:env:generate	Génère les fichiers .env dev (alias de config:env:generate:dev).
npm run config:env:generate:dev	Génère les .env depuis config/yaml/dev.yml.
npm run config:env:generate:prod	Génère les .env depuis config/yaml/prod.yml.
npm run config:env:generate:all	Génère dev + prod.

Le workflow recommandé est :

1. Modifier les sources YAML dans config/yaml/.
2. Régénérer les .env.
3. Lancer la stack (central:up) qui régénère déjà le profil dev.

Commandes Infra Generator (infra/)

Commande	Rôle
npm run infra:generate:compose -- --tech <tech> --env <env>	Génère un docker-compose depuis infra/definitions/<tech>.<env>.yml.
npm run infra:generate:systemd -- --tech <tech> --env <env>	Génère des units systemd depuis la même définition.
npm run infra:generate:k8s -- --tech <tech> --env <env>	Génère des manifests Kubernetes depuis la même définition.

Exemples :

npm run infra:generate:compose -- --tech elastic --env dev
npm run infra:generate:systemd -- --tech kafka --env dev
npm run infra:generate:k8s -- --tech postgresql --env dev

Commandes Docserver (docserver)

Commande	Rôle
npm run doc:dev	Démarre le docserver en Docker (build + watch).
npm run doc:dev:down	Arrête et supprime les conteneurs docserver dev.
npm run doc:dev:restart	Redémarre le conteneur docserver dev.
npm run doc:logs	Suit les logs Docker du docserver.
npm run doc:build	Lance un build Docusaurus dans le conteneur.

Commande globale

Commande	Rôle
npm run build:all	Chaîne : OS -> hub -> web -> docs.

Exemples usuels

# Lister les cibles OS
npm run os:boards

# Compiler l'OS pour RPi4
npm run os:build:rpi4

# Démarrer le front domotic local
npm run web:install
npm run web:dev

# Démarrer la supervision centrale
npm run central:up

# Régénérer la config d'env depuis YAML
npm run config:env:generate

# Générer un docker-compose infra pour Kafka
npm run infra:generate:compose -- --tech kafka --env dev

# Rebuilder la documentation
npm run doc:build