CommunityImagemgithub.com

steipete/vm-lab

Laboratório de VM macOS com Parallels: automação de GUI, Peekaboo, TCC, Ghostty.

O que é vm-lab?

Esta skill configura e gerencia um laboratório de máquina virtual macOS limpo usando Parallels Desktop, projetado especificamente para testar ferramentas de automação de interface gráfica como Peekaboo, fluxos de permissões TCC (Transparência, Consentimento e Controle), captura de tela, cliques e digitação. A ideia central é executar a ferramenta sob teste dentro da VM convidada, mas validar seu comportamento a partir do host usando capturas de tela do Parallels e observações do lado de fora—isto é chamado de validação bidirecional. A skill fornece comandos para descobrir VMs, executar comandos no convidado via `prlctl exec`, abrir painéis de privacidade do sistema, lançar terminais Ghostty e injetar pressionamentos de tecla de forma confiável. Ela também documenta armadilhas comuns, como APIs de área de transferência que falham em contextos headless e comportamentos específicos do Parallels com injeção de teclas. A carga de trabalho principal é escrita como scripts de shell armazenados em `/tmp` e acionados por atalhos curtos digitados no Ghostty, garantindo atuação precisa. A validação bidirecional garante que cada ação da GUI seja verificada por dois sinais independentes: saída da ferramenta e uma captura de tela externa ou estado do aplicativo. Compatível com Parallels Desktop para macOS, foco em macOS convidado, terminal Ghostty e ferramentas de linha de comando swift package manager para builds de Peekaboo.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/steipete/agent-scripts/tree/main/skills/vm-lab

Installed? Explore more Imagem skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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 op for necessário, siga a skill do 1Password e execute-o apenas dentro do tmux.
  • 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 status executado via prlctl exec pode 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 exec pode 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 --key do 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/release explícitos podem repetir ou travar. Return é uma exceção: use press e depois release.
  • Prefira um lote prlctl send-key-event --json em vez de vários processos send-key-event separados; 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.

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

steipete/agent-transcript

GitHub PR/issue agent transcripts: redact, preview, and insert safely.

steipete/beeper

Beeper cache: contact hints, room lookup, WhatsApp/iMessage traces, FTS.

steipete/browser-use

Existing Chrome automation: Chrome plugin first, mcporter fallback.

steipete/clawsweeper-status

ClawSweeper status: URLs, workflow health, active workers, ops snapshot.

steipete/clickclack

ClickClack ops: chat app, Hetzner deploy, DNS/docs/app, Docker rollout.

steipete/cloudflare-registrar

Cloudflare Registrar: domain availability, prices, registration via mcporter.

steipete/codex-debugging

Codex debugging: codex-rs core/tui/exec/cli/app-server/config.

steipete/create-cli

CLI UX/spec: args, flags, help, output, errors, config, dry-run.

steipete/discord-clawd

Discord-backed OpenClaw agent/session relay; not archive search.

steipete/domain-dns-ops

DNS/domain ops: registrars, zones, redirects, DNS/HTTP verify, manager truth.

steipete/frontend-design

Frontend UI: pages, apps, components, polished non-generic design.

steipete/github-author-context

GitHub contributor context: identity, activity, trust, company/team signal.

steipete/github-cache-hygiene

GitHub quota/cache hygiene: gh, ghx, xcache, gitcrawl, mirrors, limits.

steipete/github-deep-review

GitHub deep review: bugs, PRs, best fix, stale-or-real, read code first.

steipete/github-project-triage

GitHub issue/PR triage: queues, CI, blockers, risk, proof, next actions.

steipete/hopper-debugger

Hopper debugging: macOS/iOS binaries, ObjC/Swift symbols, dyld, LLDB.

steipete/instruments-profiling

Instruments/xctrace profiling: macOS/iOS traces, binaries, args, exports.

steipete/mac-maintenance

Mac upkeep: brew update/upgrade, pull clean repos, empty Trash.

steipete/maintainer-orchestrator

Open-source maintainer orchestration: Codex app workers, work recovery, dependencies, vision, releases.

steipete/markdown-converter

Markdown conversion: PDF, Office, HTML, data, OCR, audio, ZIP, YouTube.

Habilidades Relacionadas