Sections

Guide utilisateur

Guide de la barre de menus

Comment chaque type d'outil s'affiche dans le popover Runyard, et ce que fait chaque action.

Toute l'interface de Runyard vit dans la barre de menus. Cliquez sur l'icône pour ouvrir le popover ; appuyez sur Échap ou cliquez à l'extérieur pour le fermer.

L'icône Runyard

Cliquez-gauche sur l'icône pour basculer le popover. À côté de l'icône, selon vos préférences, vous pouvez voir :

Le texte d'état est figé tant que le popover est ouvert. Il se rafraîchit dès que vous fermez le popover. (Modifier le titre redimensionnerait le bouton de la barre de menus et déconnecterait visuellement le popover ouvert de l'icône, donc le rafraîchissement est différé.)

Disposition du popover

Le popover est une colonne à largeur fixe avec quatre sections :

Les quatre types d'outils

Service

Un service est un processus géré : un backend, un serveur de dev, un stack Docker. Il s'affiche comme une carte avec :

Lorsque la carte est réduite, l'en-tête se compresse en point · nom · port · pastille pour qu'on voie l'essentiel d'un coup d'œil.

Shortcut

Un shortcut est une liste plate de liens ou d'actions sous une étiquette de section en majuscules. Pas de gestion de processus. Chaque action s'affiche comme une tuile pleine largeur dans une pile verticale, peu importe le type d'action (URL, commande, AppleScript, reveal ou vérification d'état). Les cartes shortcut de premier niveau ont leur propre chevron et participent au bouton Tout réduire / Tout déplier. Les shortcuts imbriqués dans un groupe s'affichent à plat sans chevron ; repliez plutôt le groupe parent.

{
  "name": "Quick Links",
  "type": "shortcut",
  "actions": [
    { "label": "Open Grafana", "type": "url", "url": "https://grafana.example.com" },
    { "label": "Open Jira", "type": "url", "url": "https://jira.example.com" }
  ]
}

Group

Un group regroupe des outils liés sous une carte repliable. L'en-tête montre une pastille d'état agrégée qui s'adapte au contenu :

Sous l'en-tête, chaque enfant s'affiche sur une seule rangée compacte pour garder les groupes denses :

●  Nom du service        :8080  [PASTILLE]   ⏹  📄
●  Nom de la vérif.      124 ms [PASTILLE]   ⏸  ↻  📄

Disposition par enfant :

Une seconde rangée de chips apparaît sous la rangée compacte seulement quand le service a des actions visibles (filtrées par showWhen) et/ou est en état .error. Les services en erreur ont un chip rouge Clear Error à la fin de la seconde rangée.

Cliquez-droit sur n'importe quelle rangée compacte pour obtenir un menu textuel complet avec toutes les actions plus des extras : Reveal Directory in Finder, Copy Start Command (services), Copy Endpoint URL (vérifications d'état).

Les actions au niveau du groupe vivent dans un pied de carte sous un titre de section en majuscules ACTIONS. Les boutons s'affichent dans une grille à 2 colonnes (une action seule occupe toute la largeur ; une troisième action impaire occupe sa propre rangée pleine largeur). La première action URL prend l'accent bleu primaire, et les actions healthCheck affichent leur propre état inline. Clear Errors (N) apparaît comme rangée pleine largeur rouge au bas lorsque ≥ 2 services imbriqués sont en erreur ou ont des résultats de health-check en échec.

Astuce : les vérifications d'état imbriquées n'affichent pas le sparkline 20 barres (qui ferait exploser la hauteur du groupe). Si vous voulez le sparkline ainsi que l'UI complète de la carte, promouvez la vérification d'état au niveau racine dans config.json (sortez-la du tableau tools du groupe parent).

{
  "name": "QA Stack",
  "type": "group",
  "actions": [
    { "label": "Open Dashboard", "type": "url", "url": "https://qa.example.com" }
  ],
  "tools": [
    { "name": "API Server", "type": "service", "...": "..." },
    { "name": "Links", "type": "shortcut", "...": "..." },
    { "name": "Health", "type": "healthCheck", "http": { "url": "..." } }
  ]
}

Les groupes ne peuvent pas être imbriqués dans d'autres groupes.

Vérification d'état

Une vérification d'état interroge un endpoint HTTP ou TCP à intervalle fixe et s'affiche sur sa propre carte avec :

Les vérifications d'état imbriquées dans des groupes s'affichent comme des rangées compactes (sans sparkline). Promouvez-la au niveau racine si vous voulez le sparkline + l'UI complète de la carte.

Pause et Resume sont des contrôles d'exécution uniquement : ils ne modifient pas votre config.json. Au prochain lancement, la vérification d'état respecte le réglage Auto-start on launch défini dans Réglages → Tools.

Quand une vérification d'état est en échec, un triangle rouge ⚠︎ apparaît à côté de l'icône Runyard de la barre de menus.

Statistiques de temps de réponse

Survolez n'importe quelle carte de vérification d'état pour voir les statistiques de temps de réponse sur une fenêtre glissante d'une heure des vérifications récentes. Sur une carte saine réduite, survolez le sparkline ; sur une carte en échec, en pause ou dépliée, survolez la pastille d'état. La fenêtre est fixe (non configurable) et se réinitialise quand Runyard se ferme.

Avec moins de 5 vérifications réussies, le popover affiche seulement la dernière latence avec un compteur « N vérifications supplémentaires requises… ». Les estimations de queue lente et de moyenne nécessitent au moins 5 échantillons pour être significatives.

À partir de 5 vérifications réussies, le popover affiche une ventilation à quatre métriques :

Les rangées Queue lente, Moyenne et Taux d'échec affichent chacune une brève explication en italique en dessous.

Quand une vérification est en échec ou en pause, le popover bascule vers l'information la plus pertinente pour cet état (la dernière erreur, le temps écoulé depuis le dernier succès et le nombre d'échecs consécutifs en cas d'échec ; les dernières statistiques connues atténuées en pause).

Actions

Les actions sont des éléments de menu supplémentaires par outil. Chaque action a un label et exactement un type :

Type Champ Effet
Open URL url Ouvre l'URL dans votre navigateur par défaut. Supporte les placeholders {{port}}.
Run command command + args Exécute une commande shell (dans le répertoire de l'outil par défaut). La sortie va dans un log d'action.
Reveal in Finder reveal Ouvre un dossier dans Finder. Les chemins relatifs se résolvent depuis le directory de l'outil.
Inline AppleScript applescript Exécute un snippet AppleScript.
AppleScript file applescriptFile Exécute un fichier .applescript.
Vérification d'état healthCheck Exécute une vérification HTTP ou TCP ponctuelle et affiche le résultat inline (latence en succès, « failed » en échec). Voir Référence config.json → Vérifications d'état.

Placeholders de port dans les URL

Les URL d'action peuvent inclure des placeholders {{port}} et {{port:Label}} :

{ "label": "Open Frontend", "type": "url", "url": "http://localhost:{{port}}/" }
{ "label": "API Docs", "type": "url", "url": "http://localhost:{{port:Backend}}/swagger" }

Si l'outil n'est pas en cours d'exécution (aucun port détecté), le placeholder reste littéral et le lien ne s'ouvre pas.

Contrôler quand les actions apparaissent

Pour les outils service, les actions ont un champ showWhen :

showWhen est ignoré sur les actions de shortcut et group ; celles-ci sont toujours visibles.

Réduction par carte

Chaque carte a un chevron en haut à droite qui réduit son corps. L'état réduit persiste entre les ouvertures du popover et les redémarrages de l'app (stocké dans ~/Library/Preferences/ca.bonevil.runyard.plist sous les clés collapsed.{toolName}). Le bouton Tout réduire / Tout déplier de l'en-tête écrase l'état stocké de chaque carte en un clic.

Détection de port

Runyard utilise lsof pour surveiller l'arbre de PID de chaque processus que vous lancez et capte le premier port TCP qu'il commence à écouter. Le port détecté :

  1. Apparaît à côté du nom de l'outil comme tag bleu :3001 sur la ligne meta.
  2. Est auto-injecté dans les URL startupCheck qui n'incluent pas un port explicite (par exemple http://localhost/api/health devient http://localhost:3001/api/health).
  3. Remplace les placeholders {{port}} dans les URL d'action.

Fallback : si l'auto-détection ne trouve pas de port (rare, mais certains outils fork de manière inhabituelle), définissez startupFallbackPort sur le processus.

Start, Stop et Logs

Start

Le bouton Start exécute :

  1. installCommand si le chemin marqueur (par défaut : node_modules) n'existe pas.
  2. Chaque startCommand dans l'ordre. Les commandes avec waitFor: "OtherLabel" patientent jusqu'à ce que l'autre processus passe son health check.
  3. Le polling du health check (si configuré).

L'outil transite starting → running une fois tous les processus en bonne santé.

Stop

Le bouton Stop soit :

View Logs

Chaque processus lancé écrit dans son propre fichier log sous ~/Library/Logs/Runyard/. View Logs ouvre chaque fichier log dans Console.app (ou retombe sur le dossier si aucun fichier log n'existe encore). Voir Dépannage → Logs pour le schéma complet des chemins.

Effacer les erreurs

Quand un service échoue à démarrer ou crashe, la carte devient rouge et l'icône de la barre de menus affiche un triangle d'avertissement rouge. Le message d'erreur s'affiche inline sous la ligne meta, et la raison complète est écrite dans le fichier log de l'outil.

Pour effacer l'indicateur d'erreur sans redémarrer :

L'effacement ne change que l'affichage ; vos fichiers logs sont conservés sur disque sous ~/Library/Logs/Runyard/.

Garder éveillé

Runyard intègre caffeinate pour empêcher macOS de se mettre en veille pendant qu'un travail important est en cours. Trois voies indépendantes, dont n'importe quelle combinaison peut être active en même temps :

Lorsqu'au moins une source automatique est active sans session manuelle, la rangée bascule sur un fond vert et lit Auto · (ou Auto · <Nom> +N pour plusieurs). Lorsque le manuel et l'automatique sont actifs ensemble, le compte à rebours manuel garde la vedette et la pastille +N indique des sources automatiques supplémentaires ; survolez la rangée pour voir la liste complète.

Le panneau de survol de la barre de menus reprend le même résumé sous forme de ligne ☕ 45 min · Auto · Big Build +2 sous les compteurs de services en cours / en échec.

Limitation capot fermé : macOS ne garde pas votre Mac éveillé lorsque le capot est fermé, quel que soit l'outil anti-veille utilisé. Runyard affiche une alerte unique la première fois que vous activez Garder éveillé pour fixer la bonne attente. C'est une contrainte de sécurité thermique qui s'applique à tout outil basé sur caffeinate.

Actions globales (pied du popover)

Les quatre tuiles au bas du popover :