paulstraw/g-scheduler

Que fait g-scheduler ?

Trouvez des créneaux de réunion où chaque participant est libre et dans ses propres horaires de travail, puis (uniquement si demandé) créez l’invitation. Deux scripts fournis effectuent les appels Google et le calcul des horaires. Ne faites jamais vous-même des calculs de fuseau horaire ou d’heure d’été : utilisez leur résultat.

Exécutez les scripts avec python3 (sous Windows, python ou py) depuis le répertoire de cette compétence : scripts/gcal.py et scripts/slots.py. Ils nécessitent Python 3.9+.

1. Vérifier l’accès

Exécutez python3 scripts/gcal.py check.

• Si cela échoue car gws est manquant ou non connecté, ou si une erreur Python demande tzdata, arrêtez-vous et guidez l’utilisateur pas à pas dans SETUP.md. Il est impossible de continuer sans cela.
• Si cela réussit, continuez. my_working_hours: "not set" est acceptable.

2. Recueillir les entrées

• Participants : résolvez chaque personne en adresse e-mail Google Workspace. Pour les noms sans e-mail, exécutez python3 scripts/gcal.py find "Ada Lovelace" "Grace", qui recherche dans l’annuaire de l’organisation ; d’autres outils dont vous disposez (Slack, le message de l’utilisateur) fonctionnent aussi. Si find échoue (portée manquante, accessNotConfigured, ou l’administrateur a désactivé le partage d’annuaire), la recherche par nom n’est pas disponible : mentionnez la raison une fois, renvoyez à la section Dépannage de SETUP.md, et utilisez d’autres outils. Si une adresse e-mail est manquante, ambiguë ou semble extérieure à l’organisation de l’utilisateur, demandez. L’utilisateur est ajouté automatiquement ; passez --exclude-me uniquement s’il dit qu’il ne participera pas.
• Plage de dates : restez simple. « Les 2 prochaines semaines » signifie d’aujourd’hui à environ 18 jours (les créneaux les plus proches sont déjà classés en premier). Un jour précis signifie ce jour uniquement. Les dates sont au format YYYY-MM-DD ; la date de fin est inclusive.
• Durée : par défaut 60 minutes. Ne demandez pas ; dites que vous l’avez supposée.
• Personnes facultatives : ne demandez pas à l’avance. Traitez tout le monde comme obligatoire.

3. Trouver des créneaux

python3 scripts/gcal.py gather [email protected] [email protected] --start 2026-11-10 --end 2026-11-27 \
  | python3 scripts/slots.py

Options de gather : --duration MIN, --optional EMAIL (répétable), --exclude-me, --time-zone TZ (par défaut le fuseau horaire du calendrier de l’utilisateur, qui est également utilisé pour classer et afficher).

La sortie contient slots (jusqu’à 5, au maximum 2 par jour, les plus tôt en premier), all_required_free, attendees et warnings. Chaque créneau a des heures local pour chaque participant et le fuseau de l’utilisateur, missing, missing_optional et at_day_edge (personnes pour lesquelles c’est dans les 30 premières ou dernières minutes de leur journée).

Lisez toute la sortie. Ne la filtrez pas (par exemple avec jq ou python -c), car cela supprime les warnings.

Pour vérifier un créneau spécifique (l’utilisateur propose une heure, un créneau n’est pas listé, ou un participant est ajouté tardivement), exécutez le même pipeline pour tous les participants avec --start et --end réglés exactement sur cette réunion, sous forme d’heures RFC3339 avec décalage : --start 2026-11-19T11:00:00-08:00 --end 2026-11-19T12:00:00-08:00. Le créneau unique dans la sortie indique qui manque. Ne déterminez jamais la disponibilité à partir des heures d’occupation brutes vous-même.

4. Présenter les résultats

• Listez les créneaux dans le fuseau horaire de l’utilisateur, avec l’heure locale de chaque participant lorsque les fuseaux diffèrent.
• Répétez chaque avertissement en mots clairs. Nommez les personnes dont les heures de travail ont été supposées (09:00-17:00 en semaine dans leur fuseau) et toute personne exclue car son calendrier n’a pas pu être lu.
• Indiquez la durée supposée si l’utilisateur n’en a pas donné.
• Si all_required_free est faux, dites qui manque pour chaque créneau et demandez s’il faut relancer avec certains d’entre eux en --optional. Seul l’utilisateur décide qui est facultatif ; ne marquez jamais quelqu’un comme facultatif de votre propre chef.
• Si slots est vide, dites-le et suggérez une plage plus large ou une réunion plus courte.

5. Créer l’invitation (uniquement sur demande)

1. Rédigez un titre à partir du contexte, et une courte description incluant le lien source (par exemple, le fil Slack) s’il y en a un.

2. Demandez s’il faut ajouter un lien de visioconférence. Si fourni, mettez-le dans location et dans la description. Ne créez pas de réunions Meet ou Zoom.

3. Affichez l’événement exact (titre, heure locale, participants, description, emplacement) et attendez un « oui, envoie » explicite. L’envoi envoie des e-mails à tout le monde et ne peut pas être annulé.

4. Écrivez l’événement dans un fichier JSON temporaire en tant que ressource Events de Calendar, avec les heures dans le fuseau de l’utilisateur :

   {
     "summary": "Lancement du projet",
     "description": "Planifié depuis https://example.slack.com/archives/...",
     "location": "https://zoom.us/j/123",
     "start": {"dateTime": "2026-11-18T10:00:00", "timeZone": "America/Los_Angeles"},
     "end": {"dateTime": "2026-11-18T11:00:00", "timeZone": "America/Los_Angeles"},
     "attendees": [{"email": "[email protected]"}, {"email": "[email protected]"}]
   }
   

5. Exécutez python3 scripts/gcal.py invite EVENT.json. Il envoie toujours les invitations à tous les participants. Utilisez --dry-run d’abord si vous voulez vérifier la requête.

6. Donnez le htmlLink de la sortie à l’utilisateur, et supprimez le fichier temporaire.

Règles

• Tout sauf invite est en lecture seule. Ne modifiez jamais le calendrier ou les heures de travail de quiconque.
• N’envoyez jamais d’invitation sans la confirmation explicite de l’utilisateur après avoir prévisualisé l’événement.
• Si les heures pour un fuseau semblent décalées d’une heure, les données de fuseau horaire de la machine sont probablement obsolètes (les règles de fuseau changent, comme celles de la Colombie-Britannique en 2026). Voir la section Dépannage dans SETUP.md.