VM Lab
Use isto quando a tarefa precisar de uma VM macOS limpa para testar automação de GUI, prompts de TCC, captura de tela, cliques, digitação, desempenho ou "validação bidirecional" de ferramentas como Peekaboo.
Ideia central: execute a ferramenta sob teste dentro do convidado, mas verifique-a de fora do convidado com capturas de tela do Parallels e observações do lado do host. Não feche aplicativos que você não possui.
Regras de Segurança
- Trate o snapshot da VM como descartável, não o host.
- Nunca imprima segredos. Se
opfor necessário, siga a skill do 1Password e execute-o apenas dentro dotmux. - Prefira janelas de aplicativos novas que você mesmo cria: TextEdit, uma página de teste HTML local ou um pequeno aplicativo de teste.
- Evite modificar o estado do host, exceto capturas de tela temporárias em
/tmp. - Para repositórios git dentro da VM, use remotes HTTPS e disciplina de branch normal.
Descoberta de VM
Listar VMs:
prlctl list --all
Obter status/IP da VM:
prlctl list --info "macOS Tahoe"
Executar comandos no convidado como Peter:
prlctl exec "macOS Tahoe" \
'sudo -u steipete -H /bin/zsh -lc '\''source ~/.zprofile 2>/dev/null || true; uname -a'\'''
Capturar uma captura de tela independente do host:
prlctl capture "macOS Tahoe" --file /tmp/vm-reference.png
sips -g pixelWidth -g pixelHeight /tmp/vm-reference.png
TCC / Atribuição de GUI
Para Gravação de Tela e Acessibilidade no macOS, o processo responsável importa.
prlctl execé headless e pode falhar ao produzir uma atribuição útil de Gravação de Tela.- Inicie o comando de teste a partir de um aplicativo de terminal visível no convidado quando a Gravação de Tela estiver envolvida.
- Ghostty funciona como terminal GUI se instalado.
- Após uma primeira captura falha, verifique
Ajustes do Sistema > Privacidade e Segurança > Gravação de Tela e Áudio do Sistema. permissions statusexecutado viaprlctl execpode ainda relatar Gravação de Tela como falsa mesmo depois do Ghostty estar permitido; valide a Gravação de Tela reexecutando a captura a partir do Ghostty.
Abrir o painel de Gravação de Tela:
prlctl exec "macOS Tahoe" \
'sudo -u steipete -H open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"'
Abrir Ghostty:
prlctl exec "macOS Tahoe" 'sudo -u steipete -H open -a Ghostty'
Executando Comandos Através do Ghostty
Melhor caminho: crie um script convidado com prlctl exec, abra/focalize o Ghostty e digite apenas um caminho curto de launcher no terminal visível.
Padrão de script convidado:
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 "Press return to close..."
read _
exit $rc
EOF
chmod +x /tmp/run-vm-lab.zsh
ln -sf /tmp/run-vm-lab.zsh /tmp/r
open -a Ghostty'\'''
Em seguida, vincule o launcher ao diretório home do Ghostty e digite ./r com scripts/parallels_type.py. Isso evita caracteres de caminho não confiáveis na injeção de teclas do 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'
Evite digitar comandos longos. A injeção de teclas do Parallels usa sua própria tabela de códigos de tecla e pode ser sensível ao layout.
Armadilhas Conhecidas
- As APIs da área de transferência do macOS podem falhar a partir de
prlctl exec;pbcopy, AppleScript clipboard e colagem do Peekaboo podem falhar em contexto headless de convidado. open -na Ghostty.app --args -e ...pode apenas focar uma janela Ghostty existente no macOS; não presuma que ele executa o comando.prlctl execpode reunir argv através de um shell convidado; para payloads complexos, passe uma única string de comando com escape de shell ou crie o arquivo com um pequeno escritor Python.send-key-event --keydo Parallels usa valores de tecla do Parallels, não códigos de tecla virtual do macOS.- Para digitação normal, envie
prlctl send-key-event <vm> --key <key>sem--event;press/releaseexplícitos podem repetir ou travar. Return é uma exceção: use press e depois release. - Prefira um lote
prlctl send-key-event --jsonem vez de vários processossend-key-eventseparados; chamadas separadas podem dessincronizar sob foco/latência. - Use
PRL_KEY_ENTER = 36,PRL_KEY_SLASH = 61,PRL_KEY_R = 27,PRL_KEY_T = 28,PRL_KEY_M = 58,PRL_KEY_P = 33. - Se as teclas digitadas produzirem lixo, envie Return para limpar a linha, crie um launcher mais curto e tente novamente.
- Se as sondagens de permissão do Peekaboo travarem com Gravação de Tela ausente e emitirem
SWIFT TASK CONTINUATION MISUSE, registre como um bug do produto; não confunda com a infraestrutura da VM.
Validação Bidirecional
Para cada ação de GUI, verifique por meio de dois sinais independentes:
- Saída da ferramenta sob teste: JSON, arquivo de captura de tela, resultado AX ou estado do aplicativo.
- Verificador externo:
prlctl capture, inspeção de imagem no lado do host, conteúdo de arquivo no convidado ou estado de processo/janela.
Exemplos:
- Captura de tela: compare as dimensões/conteúdo da imagem do Peekaboo com
prlctl capture. - Clique: use Peekaboo para clicar em um botão de teste; depois verifique tanto o estado do aplicativo convidado quanto a captura de tela do host.
- Digitação: use Peekaboo para digitar em um campo de texto controlado; depois verifique o valor AX e a captura de tela do host.
- Desempenho: envolva comandos com
/usr/bin/time -p; repita execuções frias/quentes; mantenha saídas em/tmp.
Baseline do Peekaboo na VM
Dentro do convidado:
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 referência do lado do host:
prlctl capture "macOS Tahoe" --file /tmp/vm-prlctl-reference.png
Captura do Peekaboo no convidado através do Ghostty:
/tmp/r
Comparar:
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
Relatório
Ao finalizar, inclua apenas:
- Nome da VM e versão do sistema operacional.
- Commit do repositório testado.
- Estado das permissões.
- Comandos que passaram/ falharam.
- Resultado do verificador independente.
- Bugs do produto descobertos.