g-scheduler

¿Qué hace g-scheduler?

Encuentra espacios en los que todos los asistentes estén libres y dentro de su horario laboral, luego (solo si se solicita) crea la invitación. Dos scripts empaquetados hacen las llamadas a Google y los cálculos de tiempo. Nunca hagas cálculos de zona horaria o cambio horario (DST) por tu cuenta: usa su salida.

Ejecuta los scripts con python3 (en Windows, python o py) desde el directorio de esta skill: scripts/gcal.py y scripts/slots.py. Necesitan Python 3.9+.

1. Verificar acceso

Ejecuta python3 scripts/gcal.py check.

• Si falla porque falta gws o no se ha iniciado sesión, o un error de Python solicita tzdata, detente y guía al usuario a través de SETUP.md, paso a paso. No hay forma de continuar sin ello.
• Si tiene éxito, continúa. my_working_hours: "not set" es válido.

2. Recopilar las entradas

• Asistentes: resuelve a todos a direcciones de correo electrónico de Google Workspace. Para nombres sin correo, ejecuta python3 scripts/gcal.py find "Ada Lovelace" "Grace", que busca en el directorio de la organización; otras herramientas que tengas (Slack, el mensaje del usuario) también funcionan. Si find falla (falta ámbito, accessNotConfigured, o el administrador ha desactivado el uso compartido del directorio), la búsqueda de nombres no está disponible: menciona el motivo una vez, señala la sección de Solución de problemas en SETUP.md y usa otras herramientas. Si falta un correo electrónico, es ambiguo o parece fuera de la organización del usuario, pregunta. El usuario se añade automáticamente; pasa --exclude-me solo si dice que no asistirá.
• Rango de fechas: mantenlo simple. "Próximas 2 semanas" significa desde hoy hasta dentro de unos 18 días (los espacios más próximos aparecen primero). Un día concreto significa solo ese día. Las fechas tienen formato YYYY-MM-DD; la fecha de finalización es inclusiva.
• Duración: por defecto 60 minutos. No preguntes; di que lo has asumido.
• Personas opcionales: no preguntes de entrada. Trata a todos como obligatorios.

3. Encontrar espacios

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

Opciones de gather: --duration MIN, --optional EMAIL (repetible), --exclude-me, --time-zone TZ (por defecto se usa la zona horaria del calendario del usuario, que también se usa para ordenar y mostrar).

La salida contiene slots (hasta 5, máximo 2 por día, los más tempranos primero), all_required_free, attendees y warnings. Cada espacio tiene horas local para cada asistente y la zona horaria del usuario, missing, missing_optional y at_day_edge (personas para las que está en los primeros o últimos 30 minutos de su día).

Lee toda la salida. No la filtres (por ejemplo con jq o python -c), porque eso elimina los warnings.

Para verificar una hora específica (el usuario propone una hora, no aparece un espacio en la lista, o se añade un asistente tarde), ejecuta la misma tubería para todos los asistentes con --start y --end ajustados exactamente a esa reunión, como horas RFC3339 con desplazamiento: --start 2026-11-19T11:00:00-08:00 --end 2026-11-19T12:00:00-08:00. El único espacio en la salida indica quién falta. Nunca calcules la disponibilidad a partir de los horarios ocupados por tu cuenta.

4. Presentar los resultados

• Enumera los espacios en la zona horaria del usuario, con la hora local de cada asistente cuando las zonas difieran.
• Repite cada advertencia en lenguaje sencillo. Menciona a las personas cuyas horas laborales se asumieron (09:00-17:00 entre semana en su zona) y a quienes quedaron excluidos porque no se pudo leer su calendario.
• Indica la duración asumida si el usuario no proporcionó ninguna.
• Si all_required_free es falso, di quién falta en cada espacio y pregunta si se debe volver a ejecutar con alguno de ellos como --optional. Solo el usuario decide quién es opcional; nunca marques a alguien como opcional por tu cuenta.
• Si slots está vacío, dímelo y sugiere un rango más amplio o una reunión más corta.

5. Crear la invitación (solo cuando se solicite)

1. Redacta un título a partir del contexto, y una breve descripción que incluya el enlace de origen (por ejemplo, el hilo de Slack) si lo hay.

2. Pregunta si se debe añadir un enlace de videoconferencia. Si se proporciona, ponlo en location y en la descripción. No crees reuniones de Meet o Zoom.

3. Muestra el evento exacto (título, hora local, asistentes, descripción, ubicación) y espera un "sí, envíalo" explícito. Enviar correos electrónicos a todos y no se puede deshacer.

4. Escribe el evento en un archivo JSON temporal como un recurso Events de Calendar, con horarios en la zona del usuario:

   {
     "summary": "Lanzamiento del proyecto",
     "description": "Programado desde 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. Ejecuta python3 scripts/gcal.py invite EVENT.json. Siempre envía invitaciones a todos los asistentes. Usa --dry-run primero si quieres verificar la solicitud.

6. Entrega al usuario el htmlLink de la salida y elimina el archivo temporal.

Reglas

• Todo excepto invite es de solo lectura. Nunca modifiques el calendario ni las horas laborales de nadie.
• Nunca envíes una invitación sin la confirmación explícita del usuario del evento previsualizado.
• Si las horas de una zona parecen estar desfasadas por una hora, probablemente los datos de zona horaria de la máquina están anticuados (las reglas de zona cambian, como sucedió en la Columbia Británica en 2026). Consulta la sección de Solución de problemas en SETUP.md.