Proposition : Detection outil manquant + Actions d'installation tracees

Date : 03/02/2026 Status : REPORTEE AU BACKLOG Projet : connectors-api + connectors-front Priorite : MOYENNE (amelioration UX, pas bloquant) Prerequis : Fix PowerShell wrapping (commit e9f5f2f) deploye

Concept

Quand une commande SSH echoue parce qu'un outil n'est pas installe :

1. Detection deterministe du nom de l'outil manquant (code, pas IA)
2. Proposition d'une commande d'installation adaptee au package manager de la machine
3. L'utilisateur valide avant execution (jamais automatique)
4. L'installation est sauvegardee comme action avec tag install
5. Historique : on sait exactement ce qui a ete installe/desinstalle, quand, sur quelle machine

Architecture

Phase 1 : Detection deterministe (backend)

Nouveau fichier src/services/packageDetector.ts :

interface MissingToolDetection {
  detected: boolean;
  tool_name: string | null;
  install_commands: InstallCommand[];
}

interface InstallCommand {
  package_manager: string;    // 'apt' | 'yum' | 'dnf' | 'brew' | 'choco' | 'winget' | 'scoop'
  command: string;            // 'apt install -y curl'
  requires_sudo: boolean;
}

Patterns de detection stderr (deterministe, regex) :

Detection package manager (une commande which/where par instance, cachee) :

Le resultat est cache dans token_metadata de l'instance (comme os_type).

Mapping outil → package (table statique, extensible) :

const TOOL_PACKAGES: Record<string, Record<string, string>> = {
  // tool_name → { package_manager: package_name }
  'jq':     { apt: 'jq', yum: 'jq', dnf: 'jq', brew: 'jq', choco: 'jq', winget: 'jqlang.jq', scoop: 'jq' },
  'curl':   { apt: 'curl', yum: 'curl', choco: 'curl', winget: 'cURL.cURL', scoop: 'curl' },
  'htop':   { apt: 'htop', yum: 'htop', dnf: 'htop', brew: 'htop' },
  'tree':   { apt: 'tree', yum: 'tree', choco: 'tree', scoop: 'tree' },
  'git':    { apt: 'git', yum: 'git', choco: 'git', winget: 'Git.Git', scoop: 'git' },
  'wget':   { apt: 'wget', yum: 'wget', choco: 'wget', winget: 'JernejSimoncic.Wget', scoop: 'wget' },
  'nano':   { apt: 'nano', yum: 'nano', choco: 'nano' },
  'vim':    { apt: 'vim', yum: 'vim', brew: 'vim', choco: 'vim' },
  'python3':{ apt: 'python3', yum: 'python3', brew: 'python', choco: 'python', winget: 'Python.Python.3' },
  'node':   { apt: 'nodejs', yum: 'nodejs', brew: 'node', choco: 'nodejs', winget: 'OpenJS.NodeJS' },
  'docker': { apt: 'docker.io', yum: 'docker', brew: 'docker', choco: 'docker-desktop', winget: 'Docker.DockerDesktop' },
  'ffmpeg': { apt: 'ffmpeg', yum: 'ffmpeg', brew: 'ffmpeg', choco: 'ffmpeg', winget: 'Gyan.FFmpeg', scoop: 'ffmpeg' },
  '7z':     { apt: 'p7zip-full', yum: 'p7zip', choco: '7zip', winget: '7zip.7zip', scoop: '7zip' },
  // ... extensible
};

Phase 2 : Integration dans le flow AI suggest (backend)

Dans POST /api/ai/test-command, apres execution :

// Si la commande a echoue, detecter outil manquant
if (!result.success && result.stderr) {
  const detection = packageDetector.detect(result.stderr, instanceId, userId);
  if (detection.detected) {
    return {
      ...result,
      missing_tool: {
        name: detection.tool_name,
        install_commands: detection.install_commands
      }
    };
  }
}

Le frontend recoit missing_tool dans la reponse et peut proposer l'installation.

Phase 3 : Actions d'installation (frontend + backend)

Frontend : Quand missing_tool est present dans la reponse test :

┌──────────────────────────────────────────────────┐
│  ⚠ Outil manquant : jq                          │
│                                                   │
│  Commande d'installation suggeree :               │
│  ┌──────────────────────────────────────────────┐ │
│  │ sudo apt install -y jq                       │ │
│  └──────────────────────────────────────────────┘ │
│                                                   │
│  [Installer]  [Ignorer]  [Sauver comme action]   │
│                                                   │
└──────────────────────────────────────────────────┘

3 choix :

• Installer : Execute la commande immediatement (1 clic) → cree une action install auto
• Ignorer : Ferme le bandeau
• Sauver comme action : Cree l'action sans executer (pour plus tard / validation admin)

Backend : L'action d'installation est une action SSH classique avec :

{
  "name": "Install jq",
  "action_type": "ssh",
  "instance_id": "xxx",
  "config": {
    "type": "command",
    "command": "sudo apt install -y jq",
    "output_parser": "raw"
  },
  "tags": ["install", "package-management"],
  "input_schema": null
}

Phase 4 : Inventaire logiciel par instance

Consultation : Page instance → onglet "Packages" ou section dans la page existante.

Filtre les actions par tags contains 'install' + instance_id → affiche :

On sait exactement ce qui a ete installe via notre systeme, avec l'historique d'execution complet (succes, erreur, stdout, stderr, duree).

Desinstallation : Meme principe — bouton "Desinstaller" genere la commande inverse (apt remove, choco uninstall, etc.), cree une action avec tag uninstall.

Fichiers a creer/modifier

Backend (connectors-api)

Frontend (connectors-front)

Pas de migration BDD necessaire

On reutilise les tables existantes :

• actions avec tags: ['install'] ou tags: ['uninstall']
• action_executions pour l'historique
• user_connectors.token_metadata pour le cache du package manager

Phases de livraison

Points de conception

• Jamais d'execution automatique → l'utilisateur clique toujours
• Le mapping est statique et extensible → pas d'appel IA pour trouver le package
• Retrocompatible → les actions install sont des actions SSH normales, rien de special en BDD
• Pas de nouveau endpoint → on enrichit la reponse existante de test-command
• Cache package manager → 1 detection par instance, stockee dans token_metadata

Limites connues

• Le mapping TOOL_PACKAGES couvre les outils courants, pas tout
• Si l'outil n'est pas dans le mapping, on affiche juste "outil manquant" sans suggestion
• Les noms de packages peuvent varier selon les versions de distro (ex: python3 vs python)
• On ne gere pas les repos custom (PPA, EPEL, etc.) — juste le package manager par defaut