VM Lab
Usa esto cuando la tarea requiera una VM limpia de macOS para probar automatización de GUI, solicitudes de TCC, captura de pantallas, clics, escritura, rendimiento o "validación bidireccional" de herramientas similares a Peekaboo.
Idea central: ejecuta la herramienta bajo prueba dentro del invitado, pero verifícala desde fuera del invitado con capturas de pantalla de Parallels y observaciones del anfitrión. No cierres aplicaciones que no sean tuyas.
Reglas de Seguridad
- Trata la instantánea de la VM como desechable, no el anfitrión.
- Nunca imprimas secretos. Si se necesita
op, sigue el skill de 1Password y ejecútalo solo dentro detmux. - Prefiere ventanas de aplicaciones nuevas que tú mismo crees: TextEdit, una página HTML de prueba local o una pequeña aplicación de prueba.
- Evita modificar el estado del anfitrión excepto capturas de pantalla temporales en
/tmp. - Para repositorios git dentro de la VM, usa remotos HTTPS y disciplina normal de ramas.
Descubrimiento de VM
Lista las VMs:
prlctl list --all
Obtén estado/IP de la VM:
prlctl list --info "macOS Tahoe"
Ejecuta comandos en el invitado como Peter:
prlctl exec "macOS Tahoe" \
'sudo -u steipete -H /bin/zsh -lc '\''source ~/.zprofile 2>/dev/null || true; uname -a'\'''
Captura una captura de pantalla independiente del anfitrión:
prlctl capture "macOS Tahoe" --file /tmp/vm-reference.png
sips -g pixelWidth -g pixelHeight /tmp/vm-reference.png
TCC / Atribución de GUI
Para la grabación de pantalla y accesibilidad de macOS, el proceso responsable es importante.
prlctl execes headless y puede fallar al producir una atribución útil de grabación de pantalla.- Inicia el comando de prueba desde una aplicación de terminal visible en el invitado cuando esté involucrada la grabación de pantalla.
- Ghostty funciona como terminal GUI si está instalado.
- Después de un primer fallo de captura, revisa
Configuración del Sistema > Privacidad y Seguridad > Grabación de Pantalla y Audio del Sistema. permissions statusejecutado a través deprlctl execpuede seguir informando que la grabación de pantalla es falsa después de que Ghostty esté permitido; valida la grabación de pantalla volviendo a ejecutar la captura desde Ghostty.
Abre el panel de Grabación de Pantalla:
prlctl exec "macOS Tahoe" \
'sudo -u steipete -H open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"'
Abre Ghostty:
prlctl exec "macOS Tahoe" 'sudo -u steipete -H open -a Ghostty'
Ejecutando Comandos a Través de Ghostty
Mejor ruta: crea un script invitado con prlctl exec, abre/enfoca Ghostty, luego escribe solo una ruta de lanzador corta en la terminal visible.
Patrón de script invitado:
prlctl exec "macOS Tahoe" 'sudo -u steipete -H /bin/zsh -lc '\''cat > /tmp/run-vm-lab.zsh <<EOF
#!/bin/zsh
source ~/.zprofile 2>/dev/null || true
cd ~/Projects/Peekaboo || exit 1
Apps/CLI/.build/debug/peekaboo image --path /tmp/peekaboo-vm.png --json
rc=$?
echo "EXIT:$rc"
[ -f /tmp/peekaboo-vm.png ] && sips -g pixelWidth -g pixelHeight /tmp/peekaboo-vm.png
echo "Presiona retorno para cerrar..."
read _
exit $rc
EOF
chmod +x /tmp/run-vm-lab.zsh
ln -sf /tmp/run-vm-lab.zsh /tmp/r
open -a Ghostty'\'''
Luego vincula el lanzador al directorio personal de Ghostty y escribe ./r con scripts/parallels_type.py. Esto evita caracteres de ruta poco fiables en la inyección de teclas de Parallels.
prlctl exec "macOS Tahoe" \
"sudo -u steipete -H /bin/zsh -lc 'ln -sf /tmp/run-vm-lab.zsh ~/r'"
python3 skills/vm-lab/scripts/parallels_type.py "macOS Tahoe" $'./r\n'
Evita escribir comandos largos. La inyección de teclas de Parallels usa su propia tabla de códigos de teclas y puede ser sensible a la disposición.
Problemas Conocidos
- Las APIs del portapapeles de macOS pueden fallar desde
prlctl exec;pbcopy, el portapapeles de AppleScript y el pegado de Peekaboo pueden fallar en el contexto headless del invitado. open -na Ghostty.app --args -e ...puede solo enfocar una ventana existente de Ghostty en macOS; no asumas que ejecuta el comando.prlctl execpuede volver a unir argv a través de un shell invitado; para cargas complejas, pasa una cadena de comando completamente escapada por shell o crea el archivo con un pequeño escritor en Python.send-key-event --keyde Parallels usa valores de teclas de Parallels, no códigos de teclas virtuales de macOS.- Para escritura normal, envía
prlctl send-key-event <vm> --key <key>sin--event;press/releaseexplícitos pueden repetirse o pegarse. Return es una excepción: usa press luego release. - Prefiere un lote
prlctl send-key-event --jsonsobre muchos procesossend-key-eventseparados; las llamadas separadas pueden desviarse bajo enfoque/latencia. - Usa
PRL_KEY_ENTER = 36,PRL_KEY_SLASH = 61,PRL_KEY_R = 27,PRL_KEY_T = 28,PRL_KEY_M = 58,PRL_KEY_P = 33. - Si las pulsaciones producen basura, envía Return para limpiar la línea, crea un lanzador más corto, luego reintenta.
- Si las sondas de permisos de Peekaboo se cuelgan con grabación de pantalla faltante y emiten
SWIFT TASK CONTINUATION MISUSE, regístralo como un error del producto; no lo confundas con el entorno de la VM.
Validación Bidireccional
Para cada acción de GUI, verifica a través de dos señales independientes:
- Salida de la herramienta bajo prueba: JSON, archivo de captura de pantalla, resultado AX o estado de la aplicación.
- Verificador externo:
prlctl capture, inspección de imagen del anfitrión, contenido de archivo en el invitado o estado de proceso/ventana.
Ejemplos:
- Captura de pantalla: compara las dimensiones/contenido de la imagen de Peekaboo contra
prlctl capture. - Clic: usa Peekaboo para hacer clic en un botón de prueba, luego verifica tanto el estado de la aplicación invitada como la captura de pantalla del anfitrión.
- Escritura: usa Peekaboo para escribir en un campo de texto controlado, luego verifica el valor AX y la captura de pantalla del anfitrión.
- Rendimiento: envuelve comandos con
/usr/bin/time -p; repite ejecuciones en frío/caliente; mantén las salidas en/tmp.
Línea Base de Peekaboo en VM
Dentro del invitado:
cd ~/Projects/Peekaboo
git pull --recurse-submodules
swift build --package-path Apps/CLI
Apps/CLI/.build/debug/peekaboo --version
Apps/CLI/.build/debug/peekaboo permissions status --json
Captura de referencia del anfitrión:
prlctl capture "macOS Tahoe" --file /tmp/vm-prlctl-reference.png
Captura de Peekaboo desde el invitado a través de Ghostty:
/tmp/r
Compara:
prlctl exec "macOS Tahoe" \
'sudo -u steipete -H /bin/zsh -lc '\''sips -g pixelWidth -g pixelHeight /tmp/peekaboo-vm.png'\'''
sips -g pixelWidth -g pixelHeight /tmp/vm-prlctl-reference.png
Informes
Al entregar, incluye solo:
- Nombre de la VM y versión del sistema operativo.
- commit del repositorio probado.
- estado de permisos.
- comandos que pasaron/fallaron.
- resultado del verificador independiente.
- errores del producto descubiertos.