pilot/gnome-pilot-extension/STRUCTURE.md

Structure de l'extension Pilot Control

Arborescence des fichiers

gnome-pilot-extension/
│
├── metadata.json              # Métadonnées de l'extension (UUID, version, etc.)
├── extension.js              # Point d'entrée principal (bouton panel + menu)
├── prefs.js                  # Fenêtre de préférences (optionnel V1)
├── yamlConfig.js            # Module de lecture/écriture YAML
├── serviceManager.js        # Gestion du service systemd
├── stylesheet.css           # Styles CSS personnalisés
│
├── ui/                       # Composants d'interface utilisateur
│   ├── pilotWindow.js       # Fenêtre principale (3 sections)
│   ├── metricEditDialog.js  # Dialogue d'édition des métriques
│   └── commandEditDialog.js # Dialogue d'édition des commandes
│
├── schemas/                  # GSettings schema (optionnel, vide pour V1)
│
├── install.sh               # Script d'installation automatique
├── README.md                # Documentation complète
├── GUIDE_DEBUTANT.md       # Guide pour débutants
└── STRUCTURE.md            # Ce fichier (vue d'ensemble)

Diagramme de flux

┌─────────────────────────────────────────────────────────────┐
│                     GNOME Shell Panel                        │
│                                                              │
│  [Icon] Pilot Control ▼                                     │
│         ├─ Status: 🟢 Running                               │
│         ├─ Start Service                                    │
│         ├─ Stop Service                                     │
│         ├─ Restart Service                                  │
│         ├─ Open Control Panel ──────────┐                   │
│         └─ Reload Config                │                   │
└──────────────────────────────────────────┼──────────────────┘
                                           │
                                           ▼
┌──────────────────────────────────────────────────────────────┐
│                   Pilot Control Panel                        │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ [Refresh] [Save]                                       │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌─ Service Control ──────────────────────────────────────┐  │
│  │ Service Status        [Switch ON/OFF]                  │  │
│  │ Auto-start Service    [Switch ON/OFF]                  │  │
│  │ Restart Service       [Button: Restart]                │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌─ Telemetry Metrics ────────────────────────────────────┐  │
│  │ Enable Telemetry     [Switch ON/OFF]                   │  │
│  │                                                         │  │
│  │ CPU Usage            [Switch] [Edit...]                │  │
│  │ Memory Usage         [Switch] [Edit...]                │  │
│  │ Battery              [Switch] [Edit...]                │  │
│  │ Temperature          [Switch] [Edit...]                │  │
│  │ IP Address           [Switch] [Edit...]                │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌─ Commands ─────────────────────────────────────────────┐  │
│  │ Enable Commands      [Switch ON/OFF]                   │  │
│  │ Allowed Commands     [Edit...]                         │  │
│  │   → shutdown, reboot, sleep, hibernate, screen         │  │
│  └─────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘

Flux de données

┌──────────────┐
│   User       │
│   Action     │
└──────┬───────┘
       │
       ▼
┌──────────────────────────────────────────┐
│         extension.js                     │
│  (PilotIndicator: Panel Button + Menu)   │
└──────┬───────────────────────────────────┘
       │
       ├─────────────────────┐
       │                     │
       ▼                     ▼
┌──────────────┐      ┌──────────────┐
│ Service      │      │ ui/          │
│ Manager      │      │ pilotWindow  │
└──────┬───────┘      └──────┬───────┘
       │                     │
       │                     ▼
       │              ┌──────────────┐
       │              │ yamlConfig   │
       │              │ (Parser)     │
       │              └──────┬───────┘
       │                     │
       ▼                     ▼
┌──────────────┐      ┌──────────────┐
│ systemctl    │      │ config.yaml  │
│ commands     │      │ (Pilot V2)   │
└──────────────┘      └──────────────┘
       │                     │
       └─────────┬───────────┘
                 │
                 ▼
         ┌──────────────┐
         │ mqtt_pilot   │
         │ .service     │
         │ (Pilot V2)   │
         └──────────────┘

Interactions entre modules

1. extension.js → serviceManager.js

// Contrôle du service systemd
serviceManager.startService()
serviceManager.stopService()
serviceManager.restartService()
serviceManager.isServiceActive()

2. extension.js → ui/pilotWindow.js

// Ouvre la fenêtre principale
new PilotWindow(extension, yamlConfig, serviceManager)
window.show()

3. ui/pilotWindow.js → yamlConfig.js

// Lecture de la config
yamlConfig.load()
yamlConfig.getTelemetryMetrics()
yamlConfig.getCommandsAllowlist()

// Modification de la config
yamlConfig.updateTelemetryMetric(name, updates)
yamlConfig.setTelemetryEnabled(enabled)
yamlConfig.updateCommandsAllowlist(newList)

// Sauvegarde
yamlConfig.save()

4. ui/pilotWindow.js → ui/metricEditDialog.js

// Édition d'une métrique
const dialog = new MetricEditDialog(parent, metricName, config)
dialog.connect('response', (dlg, responseId) => {
    const updates = dialog.getUpdates()
    // Appliquer les modifications
})

5. ui/pilotWindow.js → ui/commandEditDialog.js

// Édition de la allowlist
const dialog = new CommandEditDialog(parent, currentAllowlist)
dialog.connect('response', (dlg, responseId) => {
    const newAllowlist = dialog.getAllowlist()
    // Appliquer les modifications
})

Cycle de vie de l'extension

1. GNOME Shell démarre
   ↓
2. Extension activée (enable())
   ↓
3. PilotIndicator créé
   ↓
4. Icône ajoutée au panel
   ↓
5. Menu construit
   ↓
6. Config chargée (yamlConfig.load())
   ↓
7. Status du service vérifié
   ↓
8. Extension prête

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

User clique sur "Open Control Panel"
   ↓
PilotWindow créée
   ↓
Sections construites (Service, Telemetry, Commands)
   ↓
Données chargées depuis config.yaml
   ↓
Interface affichée

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

User modifie un paramètre
   ↓
Config marquée comme "dirty"
   ↓
User clique "Save"
   ↓
Backup créé (config.yaml.backup_timestamp)
   ↓
Nouveau config.yaml écrit
   ↓
Service redémarré (systemctl restart)
   ↓
Interface mise à jour

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Extension désactivée (disable())
   ↓
Fenêtre détruite
   ↓
Indicateur supprimé du panel
   ↓
Extension arrêtée

Technologies utilisées

Technologie	Version	Usage
GJS	-	JavaScript runtime pour GNOME
GTK4	4.x	Toolkit d'interface graphique
Libadwaita	1.x	Composants UI modernes GNOME
GLib	2.x	Utilitaires système (fichiers, processus)
Gio	2.x	I/O (lecture/écriture fichiers)
GNOME Shell	45+	Environnement de bureau

Dépendances externes

L'extension n'a pas de dépendances externes npm/node. Tout est fourni par :

• GNOME Shell
• GJS (inclus avec GNOME)
• GTK4 et Libadwaita (librairies système)

Permissions requises

L'extension nécessite :

1. Accès fichiers :

   • Lecture : ~/app/pilot/pilot-v2/config.yaml
   • Écriture : ~/app/pilot/pilot-v2/config.yaml
   • Création de backups : ~/app/pilot/pilot-v2/config.yaml.backup_*

2. Commandes systemctl :

   • systemctl --user start mqtt_pilot.service
   • systemctl --user stop mqtt_pilot.service
   • systemctl --user restart mqtt_pilot.service
   • systemctl --user status mqtt_pilot.service
   • systemctl --user is-active mqtt_pilot.service
   • systemctl --user enable mqtt_pilot.service
   • systemctl --user disable mqtt_pilot.service

3. Logs :

   • journalctl --user -u mqtt_pilot.service

Sécurité

Ce que l'extension PEUT faire :

• ✅ Lire et modifier le fichier config.yaml de l'utilisateur
• ✅ Contrôler le service systemd de l'utilisateur (--user)
• ✅ Créer des sauvegardes des fichiers de configuration

Ce que l'extension NE PEUT PAS faire :

• ❌ Accéder aux services système (nécessite sudo)
• ❌ Modifier des fichiers en dehors du home directory
• ❌ Exécuter des commandes arbitraires non validées
• ❌ Accéder au réseau (pas d'API MQTT directe)

Limites de V1

1. Parser YAML simple : Ne gère que la structure de config.yaml de Pilot V2
2. Pas de validation avancée : Entrées utilisateur validées basiquement
3. Rechargement par redémarrage : Nécessite un restart du service (pas de reload à chaud)
4. Une seule instance : Gère uniquement un service Pilot à la fois
5. Pas de logs temps réel : Pas d'affichage des logs dans l'interface

Extensions futures possibles

• Support de plusieurs instances de Pilot
• Visualisation des logs en temps réel
• Notifications pour événements importants
• Graphiques de métriques (historique)
• Export/import de configurations
• Validation avancée des entrées (regex, ranges)
• Thèmes sombres/clairs personnalisés
• Support de configurations complexes (YAML avancé)

Ressources

• Documentation GNOME Extensions
• GTK4 Documentation
• Libadwaita Documentation
• GJS Examples